BravoCore — ambientes Coolify¶

API de RAG multi-tenant e agentes LGPD, usada pelo Adapter como backend de IA.

O suporte ao BravoCore cobre somente os ambientes gerenciados pelo Coolify: DEV, TEST, HOMOLOG e PROD. Cada ambiente tem backend, worker, agendador, banco e Redis próprios.

Ambientes e acesso¶

Ambiente	API base	Documentação da API
DEV	`https://api.dev.adapter.bravonix.ia.br`	Swagger UI
TEST	`https://api.test.adapter.bravonix.ia.br`	Swagger UI
HOMOLOG	`https://api.homolog.adapter.bravonix.ia.br`	Swagger UI
PROD	`https://api.prod.adapter.bravonix.ia.br`	Swagger UI

Consulte a página do Adapter para o papel de cada ambiente, branches, publicação e cuidados com os dados. O nome PROD não confirma que a virada do atendimento aos clientes tenha ocorrido.

BravoCore e Adapter são aplicações separadas

No domínio de API de cada ambiente, os caminhos /api, /admin e /static são encaminhados ao BravoCore. POST /v1/auth/login é o login do Adapter; POST /api/v1/auth/login/ é o do BravoCore.

Endpoints¶

Acrescente os caminhos abaixo à API base do ambiente escolhido. Os recursos disponíveis dependem da versão publicada; consulte o schema do próprio ambiente.

Recurso	Caminho
Documentação interativa (Swagger UI)	`/api/docs/`
ReDoc	`/api/redoc/`
Schema OpenAPI	`/api/schema/`
Health check	`/api/health/`
Painel administrativo	`/administrator/`

O admin não fica em /admin/

O prefixo /admin encaminha ao Django, mas a rota do painel é /administrator/.

Autenticação¶

JWT. Faça login para receber o par de tokens e envie o access no header Authorization das demais chamadas.

# Exemplo em DEV — use a API base do ambiente desejado
# 1. Login
curl -X POST https://api.dev.adapter.bravonix.ia.br/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"username": "<usuario>", "password": "<senha>"}'

# 2. Usar o token
curl https://api.dev.adapter.bravonix.ia.br/api/v1/auth/me/ \
  -H "Authorization: Bearer <access_token>"

POST /api/v1/auth/refresh/ renova o token expirado; POST /api/v1/auth/logout/ invalida o refresh.

Onde estão as credenciais?

Usuários e senhas ficam com a equipe de desenvolvimento. Solicite acesso ao responsável pelo serviço.

O que a API oferece¶

Chat e conversas¶

Método	Rota	Para quê
`POST`	`/api/v1/chat/`	Pergunta ao agente orquestrador (decide sozinho entre RAG, busca web ou resposta direta)
`POST`	`/api/v1/chat/stream/`	Mesma coisa, com resposta em streaming
`POST`	`/api/v1/chat/temporary/`	Conversa que não fica no histórico
`GET`	`/api/v1/conversations/`	Lista conversas; `/{id}/messages/` traz as mensagens
`GET`	`/api/v1/chat/orchestration/{message_id}/`	Rastro de decisão do orquestrador para uma resposta (agentes acionados, documentos usados, tempo)

Base de conhecimento¶

Método	Rota	Para quê
`GET` `POST`	`/api/v1/knowledge-bases/`	Lista e cria bases
`POST`	`/api/v1/knowledge-bases/{id}/upload_documents/`	Envia PDFs para indexação
`GET`	`/api/v1/documents/`	Documentos e status de processamento
`POST`	`/api/v1/documents/{id}/reprocess/`	Reprocessa um documento

A ingestão é assíncrona: o upload responde na hora e o documento passa por extração, chunking e geração de embeddings em um worker dedicado. Acompanhe por processing_status no documento.

Agentes LGPD¶

Todos em POST /api/v1/agents/..., com resposta estruturada segundo um schema configurável por agente.

Agente	Rota	O que faz
Process Suggester	`process-suggester/`	Sugere processos de tratamento de dados para uma área
Questionnaire Suggestions	`questionnaire-suggestions/`	Gera questionários de conformidade
Juridical Analysis	`juridical-analysis/`	Análise jurídica de um processo
DPO Insights	`dpo-insights/`	Análise consolidada para o DPO
Risks Analysis	`risks-analysis/`	Avaliação de riscos de privacidade
Checklist Effectiveness	`checklist-effectiveness/`	Efetividade de checklists
LIA Analysis	`lia-analysis/`	Análise de Legítimo Interesse
Hypothesis Justificator	`hypothesis-justificator/`	Justifica a hipótese legal escolhida
Document Matcher	`document-matcher/`	Relaciona documentos a processos
Process Import	`process-import/`	Extrai processos de um PDF (ROPA, inventário, relatório)
Questionnaire Import	`questionnaire-import/`	Extrai processos e preenche as 4 etapas do questionário LGPD

Os dois agentes de importação recebem multipart/form-data com o PDF em file e um JSON em payload com a estrutura organizacional. POST /api/v1/agents/feedback/ registra avaliações — respostas com nota ≥ 4 voltam como exemplo para execuções futuras do mesmo agente.

Multi-tenancy¶

Toda chamada de agente e de chat acontece no contexto de uma Company, e o usuário precisa estar vinculado a uma. Sem esse vínculo, os endpoints de agente respondem 404 com "Usuário não está associado a nenhuma empresa".

Cada Company tem sua base de conhecimento padrão, limites de chamadas de API e de armazenamento, e contagem de consumo. GET /api/v1/auth/my-companies/ lista as empresas do usuário autenticado; GET /api/v1/auth/companies/{id}/stats/ mostra o consumo.

Modelos e provedores¶

Os modelos de chat, embeddings e reranking dependem da configuração de cada ambiente. Confira os provedores e modelos ativos antes de executar uma análise. Não presuma que o processamento fique na infraestrutura Bravonix quando houver um provedor externo configurado.

Arquitetura¶

flowchart LR
    A["Adapter ou cliente da API"]
    subgraph AMB["Ambiente Coolify — DEV, HOMOLOG ou PROD"]
        B["Backend BravoCore<br>Django + Gunicorn"]
        C["Worker Celery<br>agentes e ingestão"]
        E["Agendador Celery beat"]
        F[("PostgreSQL + pgvector")]
        G[("Redis")]
    end
    H["Langfuse compartilhado<br>projeto por ambiente"]
    I["Provedor de modelo<br>configurado no ambiente"]
    A -->|HTTPS| B
    B --> F
    B -->|enfileira| G
    E --> G
    G --> C
    C --> F
    B --> I
    C --> I
    B -.->|traces| H
    C -.->|traces| H

O worker processa as tarefas em segundo plano; o agendador dispara tarefas periódicas. A configuração de um recurso no Coolify não é herdada pelos outros.

Observabilidade¶

Os quatro ambientes usam langfuse-2608.bravonix.ia.br, com projetos DEV, HOMOLOG e PROD. TEST herda a configuração de DEV, sem projeto exclusivo. O Langfuse é um serviço compartilhado de apoio aos ambientes; ele roda fora do Coolify.

Backend e worker precisam das configurações de envio próprias. Em PROD, mantenha o mascaramento de dados pessoais ligado nos dois. Veja configuração e validação do Langfuse.

Troubleshooting¶

Sintoma	Causa provável	Ação
`401 Unauthorized`	Token ausente, expirado, inválido ou login na aplicação errada	Conferir a API base e refazer o login do BravoCore
`404` em `/admin/`	Rota errada	Usar `/administrator/`
Documento fica em processamento	Worker indisponível, tarefa pendente ou falha de ingestão	Conferir o status do documento e o worker do ambiente
`404` "Usuário não está associado a nenhuma empresa"	Usuário sem vínculo com uma Company	Vincular o usuário à empresa correta
Resposta sem contexto da empresa	Base vazia ou documento não indexado	Conferir indexação e base selecionada
Análise termina, mas não aparece no Langfuse	Worker sem configuração de envio	Conferir as variáveis no worker e o projeto de destino
`502` logo após uma atualização	Backend iniciando	Conferir os logs e a conclusão do deploy no Coolify