Terno

TernoDBI: Capa de Inteligencia de Base de Datos

TernoDBI es una capa de inteligencia de base de datos diseñada para Seguridad y Precisión, que cierra la brecha entre Agentes de IA y Datos Empresariales. Actúa como un potente servidor independiente de Protocolo de Contexto de Modelo (MCP), o puede integrarse directamente en sus proyectos Django existentes. De cualquier manera, proporciona una API unificada y segura para interactuar con bases de datos a escala de almacén, al tiempo que aplica estrictos controles de acceso y optimiza el contexto del esquema de la base de datos para los LLM.

Inicio Rápido: Chatea con tu base de datos en 5 minutos

La forma más fácil de comenzar es ejecutar TernoDBI localmente y conectar tu agente de IA favorito.

1. Instala TernoDBI

   pip install terno-dbi
   

2. Inicia el servidor

   ternodbi start [port]
   

   (Por defecto, esto inicia el servidor en 127.0.0.1:8376. Ejecuta automáticamente migraciones, crea un usuario predeterminado admin/admin y configura una organización predeterminada en el primer arranque.)
3. Configura tu base de datos Abre el panel de administración en http://127.0.0.1:8376/admin y agrega tus conexiones de fuentes de datos.
4. Genera un token de acceso Genera un token desde la interfaz de administración o mediante la CLI. Vincúlalo a tu organización y a un usuario con --org/--user — un token no vinculado no puede usar funciones específicas de la organización como la memoria:

   # Query Token (for AI Agents)
   ternodbi manage issue_token --name "My Agent" --type query --org <subdomain> --user <username>
   
   # Admin Token (for full system access)
   ternodbi manage issue_token --name "System Admin" --type admin --org <subdomain> --user <username>
   

5. Configura MCP (Consulta Integración MCP a continuación)
6. ¡Comienza a chatear con tus datos empresariales!

Características Clave

• Soporte Multi-Base de Datos: Manejo unificado de conexiones listo para usar para Postgres, MySQL, Snowflake, BigQuery, Databricks, Oracle y SQLite.
• Arquitectura MCP Dividida:
  • Servidor de Consultas: Operaciones de solo lectura (listar tablas, información de esquema, ejecutar consultas SELECT) altamente optimizadas para agentes de IA.
  • Servidor de Administración: Operaciones de escritura/gestión (renombrar tablas, actualizar metadatos, gestionar descripciones) diseñadas para flujos de trabajo con intervención humana.
• Seguridad de Nivel Empresarial:
  • Seguridad a Nivel de Fila (RLS): Define filtros estrictos basados en SQL (por ejemplo, department_id = 5) que se inyectan automáticamente en cada consulta ejecutada.
  • Privacidad por Defecto: Oculta tablas o columnas sensibles de la ventana de contexto del LLM a menos que se expongan explícitamente a Roles específicos.
  • SQLShield: Validación automática de SQL basada en AST que previene la inyección de prompts y operaciones destructivas.
• Enriquecimiento de Esquema Listo para LLM:
  • Metadatos Semánticos: Desacopla los nombres físicos de la base de datos (por ejemplo, t_users_v2_fnl) de nombres semánticos limpios orientados al usuario (Customers).
  • Perfilado Estadístico: Inyección automática de estadísticas de cardinalidad y distribución para ayudar a los LLM a generar consistentemente filtros SQL correctos.
• Paginación de Alto Rendimiento:
  • Basada en Cursor (HMAC): Rendimiento $O(1)$. Los benchmarks demuestran una aceleración de ~28x sobre la paginación por desplazamiento.
  • Transmisión del Lado del Servidor: Exporta sin esfuerzo millones de filas mediante cursores del lado del servidor.

Uso y APIs Principales

Ejecutando el Servidor API

# Start on default port (8376)
ternodbi start

# Start on a custom port
ternodbi start 9000

Compartiendo Base de Datos con un Proyecto Django Existente (por ejemplo, Terno-AI)

Si estás ejecutando TernoDBI junto a un proyecto Django existente o incrustándolo dentro de uno que usa el paquete terno_dbi.core, puedes configurar TernoDBI para que use exactamente el mismo archivo de base de datos SQLite. Esto evita mantener bases de datos separadas y permite compartir datos en tiempo real:

DJANGO_PROJECT_PATH=/path/to/your/django/project ternodbi start

Por ejemplo, para compartir la base de datos con Terno-AI:

DJANGO_PROJECT_PATH=/Users/navin/terno/terno-ai/terno ternodbi start

Esto obliga al servidor independiente a leer y escribir directamente en /Users/navin/terno/terno-ai/terno/db.sqlite3.

Comandos de Gestión (CLI)

Automatiza la gestión de credenciales y accesos simplemente mediante la CLI integrada. Siempre pasa --org/--user para vincular el token a una organización y a un usuario — sin ellos el token no tiene identidad y las funciones específicas de la organización (por ejemplo, memoria) no funcionarán:

# General Query Token (For standard AI Assistants)
ternodbi manage issue_token --name "Claude Agent" --type query --expires 30 --org acme --user alice

# Admin Token (Full System Access)
ternodbi manage issue_token --name "System Admin" --type admin --org acme --user alice

# Scoped Token (Restricted to a Specific Datasource)
ternodbi manage issue_token --name "Finance Data Only" --type query --datasource 1 --org acme --user alice

API de Consulta y Paginación

TernoDBI proporciona endpoints REST versátiles.

Modo Offset (Predeterminado) - Mejor para implementaciones de interfaz de usuario estándar.

POST /api/query/datasources/1/query/
{
    "sql": "SELECT * FROM users",
    "pagination_mode": "offset",
    "page": 2,
    "per_page": 50
}

Modo Cursor (Alto Rendimiento) - Mejor para agentes sin interfaz y exportaciones de datos grandes.

POST /api/query/datasources/1/query/
{
    "sql": "SELECT * FROM users",
    "pagination_mode": "cursor",
    "per_page": 50,
    "cursor": "eyJ2IjoxLCJ2YWx..." 
}

TernoDBI como Servidor MCP

TernoDBI expone servidores de Protocolo de Contexto de Modelo (MCP) para conectarse sin esfuerzo a clientes compatibles con MCP.

Herramientas MCP Proporcionadas:

• Servicio de Consulta: list_datasource, list_tables, list_table_columns, execute_query (restringido de forma segura mediante SQLShield).
• Servicio de Administración: add_datasource, delete_datasource, validate_connection, sync_metadata, rename_table, rename_column, update_table_description, update_column_description, get_table_info.

Ejemplo: Conectando Claude Desktop

1. Descarga e instala Claude Desktop.
2. Abre Claude Desktop, navega a Cuenta → Configuración → Desarrollador.
3. Haz clic en Editar Config para abrir tu claude_desktop_config.json.
4. Acuña tokens vinculados a tu organización y usuario (consulta Comandos de Gestión arriba), luego pega la siguiente configuración:

{
  "mcpServers": {
    "ternodbi-query": {
      "command": "uvx",
      "args": [
        "--from",
        "terno-dbi",
        "dbi-mcp",
        "query"
      ],
      "env": {
        "TERNODBI_API_URL": "http://127.0.0.1:8376", 
        "TERNODBI_API_KEY": "dbi_query_YOUR_TOKEN_HERE"
      }
    },
    "ternodbi-admin": {
      "command": "uvx",
      "args": [
        "--from",
        "terno-dbi",
        "dbi-mcp",
        "admin"
      ],
      "env": {
        "TERNODBI_API_URL": "http://127.0.0.1:8376",
        "TERNODBI_API_KEY": "dbi_admin_YOUR_TOKEN_HERE"
      }
    }
  }
}

(Nota: Si iniciaste TernoDBI en un puerto personalizado, asegúrate de actualizar el TERNODBI_API_URL en consecuencia.) 5. Reinicia Claude Desktop. Ahora puedes pedirle a Claude: "Muéstrame las fuentes de datos disponibles."

Integraciones Avanzadas

Integrando TernoDBI dentro de un Proyecto Django Personalizado

Si ya tienes una infraestructura Django madura, TernoDBI puede integrarse directamente como una aplicación Django.

Integración Paso a Paso:

1. Instala el paquete en tu entorno Django: pip install terno-dbi
2. Agrega las aplicaciones principales a tu INSTALLED_APPS en settings.py:

   INSTALLED_APPS = [
       ...
       'terno_dbi.core',
       # Optional: include query or admin apps based on your needs
   ]
   

3. Incluye las configuraciones de URL de TernoDBI en tu urls.py raíz:

   path('api/terno/', include('terno_dbi.core.urls')), # Mounts the core API endpoints
   

4. Ejecuta python manage.py migrate para aplicar el esquema de TernoDBI junto con tus tablas existentes.
5. Ahora puedes usar los modelos internos, optimizadores de consultas y servicios de TernoDBI directamente de forma programática dentro de tus vistas de Django o tareas de Celery.

(Consulta nuestra completa Guía de Integración Django para personalización y anulación avanzada).

Integrando con Agentes de IA Personalizados (LangChain, LlamaIndex, Python)

La API REST uniforme de TernoDBI permite que cualquier arquitectura de agente personalizada ingiera datos de forma segura sin necesidad de un host MCP.

Integración Paso a Paso:

1. Aprovisiona un token query específico para tu script personalizado usando la CLI.
2. En la implementación de tu agente, define una herramienta para llamar a /api/query/datasources/ y descubrir conexiones.
3. El flujo de tu agente debe dictar:
   • Llama a /api/query/datasources/{id}/schema/ para obtener las tablas y columnas optimizadas para el contexto.
   • Inyecta este contexto de esquema altamente estructurado en el prompt de tu LLM.
   • Envía el payload de cadena sql generado por el LLM mediante POST a /api/query/datasources/{id}/query/.
   • Itera basándote en la estructura de la respuesta o maneja con elegancia los errores de validación de SQLShield.

(Consulta nuestros ejemplos de SDK de Agente Personalizado para implementaciones de referencia en Python y TypeScript).

Documentación

Guías detalladas para configurar y dominar TernoDBI:

• Guía de Configuración
• Arquitectura del Sistema
• Integración MCP
• Seguridad y SQLShield
• Integración Django

Contribuciones

Damos la bienvenida a las contribuciones.

1. Haz un fork del repositorio.
2. Crea una rama de características: git checkout -b feat/your-feature
3. Agrega pruebas y documentación.
4. Abre un PR describiendo tu cambio.

Por favor, sigue el estilo de código del repositorio (Black/flake8) e incluye pruebas unitarias para la lógica crítica de seguridad.

Comunidad y Soporte

Si necesitas ayuda, tienes una pregunta o quieres discutir una nueva característica:

• Abre un Issue para informes de errores y solicitudes de características.
• Inicia una Discusión para preguntas generales o comentarios arquitectónicos.

Licencia

TernoDBI es orgullosamente de código abierto y se publica bajo la Licencia Apache 2.0. Consulta el archivo LICENCIA para más detalles.

Construido con precisión para la próxima generación de IA Empresarial.