Chatbot da Base dos Dados

API do chatbot da Base dos Dados, a maior plataforma pública de dados do Brasil.

Tech Stack

• FastAPI como framework web assíncrono.
• Pydantic para validação de dados e gerenciamento de configurações.
• SQLModel para interação com o banco de dados (ORM).
• PostgreSQL como banco de dados relacional.
• Alembic para migrações.
• LangChain para construção de agentes de IA.
• Google BigQuery como fonte dos dados tratados.
• Google VertexAI como provedor de LLMs.
• Docker para conteinerização e desenvolvimento local.
• Helm e Google Kubernetes Engine para deploy em produção.
• GitHub Actions para automação de fluxos de trabalho de CI/CD.
• pre-commit para gerenciamento de hooks de pre-commit.
• ruff para linting e formatação.
• uv para gerenciamento de dependências.

Configuração do Ambiente de Desenvolvimento

1. Pré-requisitos

Instale o Docker e o uv. Em seguida, clone o repositório do chatbot:

git clone https://github.com/basedosdados/chatbot.git
cd chatbot

Crie um ambiente virtual e instale os hooks de pre-commit:

uv sync
pre-commit install

Copie o arquivo .env.example e configure as variáveis de ambiente:

cp .env.example .env

Important

Você precisará de uma conta de serviço com acesso ao BigQuery e à VertexAI, chamada chatbot-sa.json e armazenada em ${HOME}/.basedosdados/credentials.

2. Modo de Autenticação de Desenvolvedor

Por padrão, a API do chatbot depende da API do website para autenticação e autorização de usuários. Para desenvolvimento local sem depender da API do website, habilite o modo de autenticação de desenvolvedor no arquivo .env:

AUTH_DEV_MODE=true
AUTH_DEV_USER_ID=uuid

Note

O modo de autenticação de desenvolvedor só funciona quando ENVIRONMENT=development.

AUTH_DEV_USER_ID é opcional. Configure-o para simular um usuário específico durante o desenvolvimento (deve ser um UUID válido). Caso não seja fornecido, um UUID fixo será utilizado.

Warning

O modo de autenticação de desenvolvedor ignora a validação do token JWT e retorna o ID definido por AUTH_DEV_USER_ID para todas as requisições. Nunca habilite em produção.

3. Executando a API

Os comandos abaixo executam a API do chatbot sem dependências externas. O modo de autenticação de desenvolvedor deve estar ativado para ignorar a autenticação e autorização de usuários.

Com o Make:

make up-dev

Com o Compose Watch:

docker compose -f compose.yaml up --build --watch

Executando a Aplicação Completa (Full Stack)

Para executar a integração completa com o frontend e a API do website, siga as instruções abaixo.

1. Configuração da API do website

Clone o repositório do backend:

git clone https://github.com/basedosdados/backend.git
cd backend

Configure e execute de acordo com as instruções do repositório.

2. Configuração da API do chatbot

Desabilite o modo de autenticação de desenvolvedor:

AUTH_DEV_MODE=false

Configure as variáveis de autenticação e a URL base da API do website no arquivo .env da API do chatbot:

BASEDOSDADOS_BASE_URL='http://api:8000'
JWT_ALGORITHM=jwt-algorithm
JWT_SECRET_KEY=jwt-secret-key

Important

As seguintes variáveis devem ser idênticas entre as APIs:

API Chatbot	API Website
JWT_ALGORITHM	DJANGO_JWT_ALGORITHM
JWT_SECRET_KEY	DJANGO_SECRET_KEY

Execute a API do chatbot com o Make:

make up

Ou com o Compose Watch:

docker compose up --build --watch

3. Configuração do frontend

Clone o repositório chatbot-frontend:

git clone git@github.com:basedosdados/chatbot-frontend.git
cd chatbot-frontend

Configure e execute de acordo com as instruções do repositório.

Tip

Você também pode executar a aplicação full stack com o modo de autenticação de desenvolvedor ativo. Isso pode ser útil caso você deseje apontar a variável BASEDOSDADOS_BASE_URL para a api do website de produção. Porém, a autenticação e autorização de requisições à API do chatbot serão ignoradas nesse caso.