Terno

O Terno é uma camada de inteligência de banco de dados projetada para segurança e precisão, preenchendo a lacuna entre agentes de IA e dados empresariais. Conecte-se instantaneamente ao servidor hospedado com OAuth — sem necessidade de instalação — ou incorpore-o diretamente ao seu próprio projeto Django.

GitHub
8
Experimente este MCPPatrocinado

Documentação

image

TernoDBI: Camada de Inteligência de Banco de Dados

License Python Django

TernoDBI é uma camada de inteligência de banco de dados projetada para Segurança e Precisão, preenchendo a lacuna entre Agentes de IA e Dados Empresariais. Ele atua como um poderoso servidor autônomo de Model Context Protocol (MCP), ou pode ser incorporado diretamente aos seus projetos Django existentes. De qualquer forma, ele fornece uma API unificada e segura para interagir com bancos de dados em escala de warehouse, aplicando controles de acesso rigorosos e otimizando o contexto do esquema do banco de dados para LLMs.

Início Rápido: Converse com seu Banco de Dados em 5 Minutos

A maneira mais fácil de começar é executar o TernoDBI localmente e conectar seu agente de IA favorito.

  1. Instale o TernoDBI 
    pip install terno-dbi
  2. Inicie o Servidor 
    ternodbi start [port]
    (Por padrão, isso inicia o servidor em 127.0.0.1:8376. Ele executa migrações automaticamente, cria um usuário padrão admin/admin e configura uma organização padrão no primeiro boot.)
  3. Configure seu Banco de Dados Abra o painel administrativo em http://127.0.0.1:8376/admin e adicione suas conexões de fonte de dados.
  4. Gere um Token de Acesso Gere um token pela Interface de Administração ou via CLI. Vincule-o à sua organização e a um usuário com --org/--user — um token não vinculado não pode usar recursos específicos da organização como memória: 
    # 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. Configure o MCP (Veja Integração MCP abaixo)
  6. Comece a conversar com seus dados empresariais!

Principais Recursos

  • Suporte a Múltiplos Bancos de Dados: Gerenciamento unificado de conexões pronto para uso para Postgres, MySQL, Snowflake, BigQuery, Databricks, Oracle e SQLite.
  • Arquitetura MCP Dividida:
    • Servidor de Consulta: Operações somente leitura (listar tabelas, informações de esquema, executar consultas SELECT) altamente otimizadas para agentes de IA.
    • Servidor Administrativo: Operações de escrita/gerenciamento (renomear tabelas, atualizar metadados, gerenciar descrições) projetadas para fluxos de trabalho com supervisão humana.
  • Segurança de Nível Empresarial:
    • Segurança em Nível de Linha (RLS): Defina filtros rigorosos baseados em SQL (ex.: department_id = 5) que são automaticamente injetados em cada consulta executada.
    • Privacidade por Padrão: Oculte tabelas ou colunas sensíveis do contexto do LLM, a menos que sejam explicitamente expostas a Funções específicas.
    • SQLShield: Validação automática de SQL baseada em AST, prevenindo injeção de prompt e operações destrutivas.
  • Enriquecimento de Esquema Pronto para LLM:
    • Metadados Semânticos: Desacople nomes físicos de banco de dados (ex.: t_users_v2_fnl) de nomes semânticos limpos e voltados ao usuário (Customers).
    • Perfil Estatístico: Injeção automática de estatísticas de cardinalidade e distribuição para ajudar LLMs a gerar filtros SQL corretos de forma consistente.
  • Paginação de Alto Desempenho:
    • Baseada em Cursor (HMAC): Desempenho $O(1)$. Benchmarks demonstram uma aceleração de ~28x em relação à paginação por deslocamento.
    • Streaming no Lado do Servidor: Exporte milhões de linhas sem esforço via cursores no lado do servidor.

Uso e APIs Principais

Executando o Servidor de API

# Start on default port (8376)
ternodbi start

# Start on a custom port
ternodbi start 9000

Compartilhando Banco de Dados com um Projeto Django Existente (ex.: Terno-AI)

Se você estiver executando o TernoDBI junto ou incorporado a um projeto Django existente que usa o pacote terno_dbi.core, você pode configurar o TernoDBI para usar exatamente o mesmo arquivo de banco de dados SQLite. Isso evita manter bancos de dados separados e permite compartilhamento de dados em tempo real:

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

Por exemplo, para compartilhar o banco de dados com o Terno-AI:

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

Isso força o servidor autônomo a ler e escrever diretamente em /Users/navin/terno/terno-ai/terno/db.sqlite3.

Comandos de Gerenciamento (CLI)

Automatize seu gerenciamento de credenciais e acesso simplesmente via CLI integrada. Sempre passe --org/--user para vincular o token a uma organização e a um usuário — sem eles o token não tem identidade e recursos específicos da organização (ex.: memória) não funcionarão:

# 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 e Paginação

O TernoDBI fornece endpoints REST versáteis.

Modo de Deslocamento (Padrão) - Melhor para implementações de interface padrão.

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

Modo de Cursor (Alto Desempenho) - Melhor para Agentes sem interface e Grandes Exportações de Dados.

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

TernoDBI como Servidor MCP

O TernoDBI expõe servidores de Model Context Protocol (MCP) para conectar-se facilmente a clientes compatíveis com MCP.

Ferramentas MCP Fornecidas:

  • Serviço de Consulta: list_datasource, list_tables, list_table_columns, execute_query (restringido com segurança via SQLShield).
  • Serviço Administrativo: add_datasource, delete_datasource, validate_connection, sync_metadata, rename_table, rename_column, update_table_description, update_column_description, get_table_info.

Exemplo: Conectando o Claude Desktop

  1. Baixe e instale o Claude Desktop.
  2. Abra o Claude Desktop, navegue até Conta → Configurações → Desenvolvedor.
  3. Clique em Editar Config para abrir seu claude_desktop_config.json.
  4. Gere tokens vinculados à sua organização e usuário (veja Comandos de Gerenciamento acima) e cole a seguinte configuração:
{
  "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: Se você iniciou o TernoDBI em uma porta personalizada, certifique-se de atualizar o TERNODBI_API_URL de acordo.) 5. Reinicie o Claude Desktop. Agora você pode solicitar ao Claude: "Mostre-me as fontes de dados disponíveis."

Integrações Avançadas

Integrando o TernoDBI dentro de um Projeto Django Personalizado

Se você já tem uma infraestrutura Django madura, o TernoDBI pode ser integrado diretamente como um App Django.

Integração Passo a Passo:

  1. Instale o pacote no seu ambiente Django: pip install terno-dbi
  2. Adicione os aplicativos principais ao seu INSTALLED_APPS em settings.py: 
    INSTALLED_APPS = [
    ...
    'terno_dbi.core',
    # Optional: include query or admin apps based on your needs
]
  3. Inclua as configurações de URL do TernoDBI no seu urls.py raiz: 
    path('api/terno/', include('terno_dbi.core.urls')), # Mounts the core API endpoints
  4. Execute python manage.py migrate para aplicar o esquema do TernoDBI junto com suas tabelas existentes.
  5. Agora você pode usar os modelos internos, otimizadores de consulta e serviços do TernoDBI diretamente de forma programática em suas views Django ou tarefas Celery!

(Consulte nosso abrangente Guia de Integração Django para sobrescrita e personalização avançadas).

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

A API REST uniforme do TernoDBI permite que qualquer arquitetura de agente personalizada ingira dados com segurança sem precisar de um host MCP.

Integração Passo a Passo:

  1. Provisione um token query específico para seu script personalizado usando a CLI.
  2. Na implementação do seu Agente, defina uma ferramenta para chamar /api/query/datasources/ para descobrir conexões.
  3. O fluxo do seu Agente deve ditar:
    • Chame /api/query/datasources/{id}/schema/ para buscar as tabelas e colunas otimizadas para contexto.
    • Injete esse contexto de esquema altamente estruturado no prompt do seu LLM.
    • Envie o payload de string sql gerado pelo LLM via POST para /api/query/datasources/{id}/query/.
    • Itere com base na estrutura da resposta ou trate erros de validação do SQLShield de forma graciosa.

(Consulte nossos exemplos de SDK de Agente Personalizado para implementações de referência em Python e TypeScript).

Documentação

Guias detalhados para configurar e dominar o TernoDBI:

Contribuindo

Aceitamos contribuições.

  1. Faça um fork do repositório.
  2. Crie um branch de recurso: git checkout -b feat/your-feature
  3. Adicione testes e documentação.
  4. Abra um PR descrevendo sua mudança.

Siga o estilo de código do repositório (Black/flake8) e inclua testes unitários para lógica crítica de segurança.

Comunidade e Suporte

Se você precisar de ajuda, tiver uma pergunta ou quiser discutir um novo recurso:

  • Abra uma Issue para relatórios de bugs e solicitações de recursos.
  • Inicie uma Discussão para perguntas gerais ou feedback arquitetural.

Licença

O TernoDBI é orgulhosamente open-source e lançado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para mais detalhes.

Construído com precisão para a próxima geração de IA Empresarial.