https://github.com/smoothemerson/brdata
Conversational AI agent that answers analytical questions about Brazil using real IBGE public data.
https://github.com/smoothemerson/brdata
ai-agent brazil conversational-ai docker fastapi fastmcp ibge langchain llm local-llm mcp ollama python
Last synced: 3 months ago
JSON representation
Conversational AI agent that answers analytical questions about Brazil using real IBGE public data.
- Host: GitHub
- URL: https://github.com/smoothemerson/brdata
- Owner: smoothemerson
- Created: 2026-03-04T19:15:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T21:05:46.000Z (3 months ago)
- Last Synced: 2026-03-26T02:30:04.974Z (3 months ago)
- Topics: ai-agent, brazil, conversational-ai, docker, fastapi, fastmcp, ibge, langchain, llm, local-llm, mcp, ollama, python
- Language: Shell
- Homepage:
- Size: 75.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ibge-agent
Conversational agent that answers analytical questions about Brazil using real data from the [IBGE public API](https://servicodados.ibge.gov.br). Runs entirely locally via Docker Compose.
## Architecture
```
Client → FastAPI :8000 → LangChain Agent → MCP Server :8001 → IBGE API
↓
Ollama :11434
```
## Requirements
- Docker + Docker Compose
- Ollama with `llama3.2` pulled
## Setup
```bash
cp .env.example .env
# Edit .env: set COMPOSE_PROFILES to cpu, gpu-amd, or gpu-nvidia
docker compose up
```
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `COMPOSE_PROFILES` | `cpu` | Ollama profile: `cpu`, `gpu-amd`, `gpu-nvidia` |
| `OLLAMA_MODEL` | `llama3.2` | Model name to use |
| `OLLAMA_BASE_URL` | `http://ollama:11434` | Ollama service URL |
| `MCP_BASE_URL` | `http://mcp:8001/mcp` | MCP server URL |
| `IBGE_BASE_URL` | `https://servicodados.ibge.gov.br/api` | IBGE API base URL |
## API
### POST /chat
```json
// Request
{ "question": "Quais são os estados do Brasil?" }
// Response
{ "answer": "..." }
```
### GET /health
```json
{ "healthy": true }
```
## MCP Tools
| Tool | Description |
|---|---|
| `ibge_get_states` | All 27 Brazilian states with region info |
| `ibge_get_municipalities` | Municipalities for a given state (2-letter UF code) |
## Local Development
```bash
# Terminal 1 — MCP server
uv run python -m mcp_server.server
# Terminal 2 — API
uv run python -m src.main
```
Set `MCP_BASE_URL=http://localhost:8001/mcp` and `OLLAMA_BASE_URL=http://localhost:11434` in `.env` for local runs.