Oracle AI Data Platform Workbench (Unofficial)

[!WARNING] Proyecto comunitario e independiente. No es una extensión oficial de Oracle, no está afiliada, patrocinada ni respaldada por Oracle, y no sustituye el soporte oficial de Oracle.

Una extensión de VS Code para explorar, editar y ejecutar notebooks remotos de Oracle AI Data Platform Workbench (AIDP). Usa firma OCI para administrar el workspace y Browser Login de AIDP para conectar el kernel Jupyter.

Qué ofrece

• Barra lateral ordenada como Master Catalog, Workspaces, Clusters y Agents.
• Navegación de workspaces, carpetas, notebooks y archivos desde la barra lateral.
• Acciones nativas New File... y New Folder... para crear notebooks .ipynb, archivos .py, .sql, .txt o carpetas; el menú contextual también permite cargar, renombrar y eliminar contenido con confirmación obligatoria.
• Carga de archivos al workspace desde el menú o arrastrándolos sobre una carpeta de AIDP.
• Edición de notebooks y archivos de texto en los editores nativos de VS Code, con guardado remoto y control de concurrencia por ETag.
• Ejecución de celdas Python, SQL y Scala mediante el canal Jupyter autenticado de AIDP, sin depender del encabezado Location.
• Panel Clusters agrupado por workspace: muestra compute de usuario y AI Compute, y permite iniciar o detener los recursos compatibles.
• Editor SQL ejecutado por el kernel remoto con Browser Login, guardado .sql con ETag, resultados tabulares y plantillas contextuales seguras desde cada tabla.
• Administración nativa de Column Access desde una tabla, visible solo con ADMIN efectivo y respaldada por permisos AIDP con ETag.
• Panel Agents que lista los agentes AIDP desplegados y abre su chat A2A a la derecha, con historial local por agente, cambio, renombrado y eliminación de sesiones.
• Desconexión explícita de AIDP, con confirmación y sin borrar el archivo ni la clave privada de OCI.

Inicio rápido

1. Instala la extensión Jupyter si VS Code lo solicita.
2. Ejecuta Configure.
3. Completa el formulario que se abre dentro de VS Code: endpoint REST, OCID, archivo OCI config, perfil y URL de AIDP Workbench.
4. Selecciona Validate and connect. El asistente valida el acceso OCI, abre el Browser Login oficial y comprueba el endpoint Jupyter en ese orden. La configuración solo se guarda cuando todos los pasos terminan correctamente.
5. Abre un notebook desde Oracle AI Data Platform Workbench (Unofficial), selecciona un cluster y ejecuta la celda.

El Browser Login forma parte del asistente de configuración y es un requisito para ejecutar notebooks. No es necesario repetirlo mientras el token guardado en VS Code SecretStorage continúe vigente y corresponda a la misma URL de AIDP Workbench.

Si el navegador predeterminado no se abre automáticamente, el paso Browser Login muestra Open Browser Login para reintentarlo y Copy Login URL para pegar la dirección manualmente en cualquier navegador.

Ejemplo: región Chicago

El endpoint REST y la URL de navegador son valores distintos. El primero se usa para las APIs; la segunda debe copiarse completa, incluido &domain=Default (o el dominio de identidad correspondiente), porque conserva el alias, tenant y dominio necesarios para iniciar sesión y descubrir el endpoint WebSocket.

Workspaces y clusters

El panel Workspaces muestra carpetas, notebooks y archivos. Usa New File... o New Folder... en la barra del panel o en el menú contextual; allí también encontrarás Upload Files..., Rename y Delete. Los archivos nuevos se abren automáticamente y Ctrl+S guarda sus cambios en AIDP. Puedes arrastrar archivos desde el explorador del sistema o desde VS Code sobre un workspace o carpeta de destino. Las eliminaciones siempre requieren confirmación.

Renombrar y eliminar están disponibles con clic derecho sobre cualquier archivo, notebook o carpeta. La eliminación siempre muestra una confirmación; al eliminar una carpeta, AIDP puede eliminar también su contenido.

El panel Clusters muestra los clusters USER y AI_COMPUTE accesibles del workspace y su estado.

• Start solo aparece para un cluster detenido. La extensión solicita confirmación porque iniciarlo consume recursos OCI.
• Stop solo aparece para un cluster activo. La extensión solicita confirmación porque puede interrumpir ejecuciones.
• El explorador general no crea, redimensiona ni configura clusters. El instalador de gobierno puede crear su workspace técnico, pero nunca crea compute sin un perfil de capacidad explícito.

En el primer Run del notebook, selecciona un cluster. Si seleccionas uno detenido, se inicia y VS Code espera a que esté activo antes de abrir la sesión de kernel. Las siguientes ejecuciones reutilizan la sesión local o una sesión remota activa del mismo notebook; el selector vuelve a aparecer únicamente cuando no existe una sesión reutilizable.

AIDP usa un kernel de sesión de tipo notebook; el lenguaje de cada celda se determina como Python, SQL o Scala a partir de sus metadatos y del lenguaje mostrado por VS Code. La URL del canal se construye con el webSocketEndpoint verificado del alias y con la ruta de gateway de notebooks 20240831/dataLakes usada por AIDP Workbench, por lo que no depende de un encabezado Location en la respuesta de creación de sesión.

La extensión conserva sin transformar las celdas de notebook. AIDP Workbench usa %sql o %scala como primera línea para que el kernel multilenguaje elija el intérprete; el panel SQL añade %sql al ejecutar una consulta que todavía no lo contiene.

Stop Execution envía una interrupción al kernel y cancela de inmediato la espera local, incluso si la extensión todavía estaba seleccionando o iniciando el cluster, conectando el WebSocket o esperando la respuesta de la celda.

Solución de problemas

• Punchout Access Error: vuelve a copiar la URL completa de AIDP Workbench. Si contiene tenant=..., también debe incluir &domain=...; para el dominio predeterminado, usa &domain=Default.
• El navegador no se abre: usa Open Browser Login para reintentar o Copy Login URL para abrir la dirección manualmente. El asistente mantiene ambas acciones visibles mientras espera el callback.
• Vuelve a pedir login o cluster: completa Validate and connect una vez con la misma URL de Workbench. El token queda en SecretStorage y las sesiones activas del notebook se descubren antes de solicitar otro cluster.
• No se encontró oci_medallion: ejecuta Install/Manage Data Governance. Con confirmación explícita, el instalador crea o reutiliza el workspace oci_medallion, su compute oci_medallion_quickstart, el catálogo/esquema, las tablas Delta, el asset y el workflow. La identidad actual debe tener asignado el rol de sistema AI_DATA_PLATFORM_ADMIN; el snapshot inicial debe completarse antes de que la programación quede activa.
• No renderer could be found for mimetype "application/vnd.chart+json": instala esta versión del VSIX y ejecuta Developer: Reload Window. El renderer incluido representa tanto outputs nuevos como los ya guardados. Como alternativa temporal, muestra datos como texto (df.show(...)) o cambia la presentación del output a text/plain.

Seguridad y desconexión

Las operaciones de workspace y compute se firman con la API key definida en aidpNotebooks.ociConfigPath. La extensión nunca copia claves privadas, perfiles ni notebooks a una carpeta de sincronización local.

Para ejecutar notebooks, AIDP abre el login en el navegador y devuelve a VS Code un token SOUP vinculado a una clave RSA efímera. El token y las claves del login se guardan únicamente en SecretStorage; la extensión no lee cookies, no automatiza el navegador y no escribe credenciales en el repositorio ni en la configuración visible.

AIDP: Sign Out Browser cierra las sesiones activas y elimina el token de SecretStorage. AIDP: Disconnect pide confirmación, hace lo mismo y además elimina de la configuración de VS Code el endpoint, URL de navegador y OCID guardados. El archivo de configuración OCI y su clave privada permanecen intactos.

AI Data Governance nativo

AIDP es la única fuente de autorización. La extensión no instala un gateway, no administra OAuth/PKCE adicional y no interpreta descripciones REDACT. Las columnas no permitidas se excluyen mediante la allowlist nativa o la consulta falla; la extensión no genera máscaras ***.

La instalación nativa usa el catálogo y esquema fijos oci_medallion.oci_artifacts, assets versionados bajo /Workspace/data_governance, el workspace técnico oci_medallion, el compute USER oci_medallion_quickstart, el bucket privado oci_artifacts, cuatro tablas Delta y un manifiesto con ETag. Install/Manage Data Governance crea o reutiliza esos recursos de forma idempotente, ejecuta una sincronización inicial y recién entonces activa el workflow cada minuto. El scheduler registra la identidad AIDP actual como Run As; el lector REST de inventario usa el resource principal de solo lectura del compute y el snapshot inicial valida ambas capacidades antes de activar el horario. Una credencial persistente configurada en AIDP evita que la ejecución programada dependa de una sesión organizacional temporal.

Las consultas de usuarios comunes no leen data_governance_access_policy: AIDP aplica directamente sus permisos nativos de tabla y columna (includeColumns, excludeColumns y row filter). La tabla es un espejo de auditoría para el administrador y el job; nunca autoriza consultas ni guarda el SQL del row filter. Una columna nueva queda excluida hasta que un administrador u owner con permiso efectivo la incluya explícitamente.

La preparación del workspace y del compute usa opc-retry-token, espera las operaciones de AIDP y solo acepta un único resultado compatible; los duplicados, perfiles distintos o estados incompletos bloquean el flujo. La creación del catálogo, esquema, tablas, asset y job también es idempotente, y un fallo del snapshot mantiene el workflow pausado para que Repair pueda continuar sin duplicar recursos.

[!IMPORTANT] Un grant heredado de catálogo o esquema que proporcione acceso más amplio bloquea la creación de una restricción de columnas. La extensión muestra el origen y nunca revoca permisos superiores automáticamente.

Alcance del MVP

Incluye gestión de contenido, edición remota, Browser Login para sesiones de notebook, control de compute, SQL nativo, permisos de columnas e instalación idempotente del runtime técnico. Crea o reutiliza el workspace oci_medallion, su compute Quickstart fijo y el workflow de sincronización; no crea identidades, reutiliza cookies ni elimina infraestructura externa heredada.

Contribuir

Los reportes de errores, propuestas y pull requests son bienvenidos. Consulta CONTRIBUTING.md antes de enviar cambios y evita incluir configuraciones OCI, claves, tokens o datos de clientes.

Este proyecto se distribuye bajo la licencia MIT.