Franco — ODS Racial AI

Agente de inteligência artificial para combate à desigualdade racial no Brasil

Desenvolvido pelo time Greenlet para o AI for Social Impact Hackathon 2026 Google DeepMind × AI Tinkerers

Sobre o Projeto

A plataforma ODS Racial cruza dados oficiais do IBGE, RAIS, DataSUS e INEP para tornar visível o que os números frequentemente escondem: a profundidade da desigualdade racial no Brasil. O Franco analisa mais de 3,6 milhões de registros de indicadores segmentados por cor/raça, região e ano — e transforma esses dados em linguagem natural, relatórios analíticos e sugestões de políticas públicas fundamentadas.

Idealizado como uma integração para a Plataforma ODS Racial, iniciativa brasileira desenvolvida pelo LEMA (Laboratório de Estudos em Modelagem Aplicada da UFPB) em parceria com o Ministério da Igualdade Racial, para o monitoramento da igualdade étnico-racial, o Franco transforma indicadores públicos em análises acionáveis para formulação de políticas baseadas em evidências.

Missão

Combater a desigualdade racial no Brasil através de análise de dados, geração de relatórios e sugestão de políticas públicas baseadas em evidências, alinhadas aos ODS da ONU — com foco especial no ODS 10 (Redução das Desigualdades) e no ODS 18 (Igualdade Racial, proposta brasileira).

Por que importa?

Eixo	Impacto
ODS 10	Dados expõem disparidades sistêmicas de renda, saúde e educação por cor/raça
ODS 18	Igualdade Racial como eixo central da plataforma — proposta brasileira à ONU
Rastreabilidade	Toda sugestão de política cita os dados e estudos de origem
Fontes oficiais	RAIS, DataSUS, INEP, IBGE — dados do Estado brasileiro

Demonstração

Screenshot / GIF da interface aqui

Arquitetura

Fluxo do Agente

Pergunta do usuário
        │
        ▼
 [query_planner]  — Interpreta intenção, extrai filtros (geo, ODS, raça, ano)
        │
        ▼
 [data_fetcher]   — Query MongoDB com filtros dinâmicos (3,6M indicadores)
        │
        ├──► [rag_retriever]  — Busca semântica em artigos e políticas (pgvector)
        ├──► [web_search]     — Notícias e estudos recentes (Tavily / Google Search)
        │
        ▼
 [generate_report] — Gemini 2.0 Flash gera análise estruturada em Markdown
        │
        ▼
   Resposta JSON com análise, citações e sugestões de políticas

Estrutura do Projeto

lema-ods-racial-ai/
├── src/
│   ├── main.py                        # FastAPI entry point
│   ├── core/                          # Config, DB connections, exceções base
│   └── app/
│       ├── server.py                  # FastAPI factory + middlewares
│       ├── container.py               # DI container
│       ├── analysis/                  # Módulo principal (Clean Architecture)
│       │   ├── domain/                # Entidades, comandos, interfaces
│       │   ├── application/           # DTOs, serviços, exceções
│       │   └── adapter/               # Routers FastAPI
│       └── infrastructure/
│           ├── langgraph/             # Grafo de agente (nodes, state, tools)
│           ├── vector_store/          # pgvector: embeddings e busca semântica
│           ├── mongo_store/           # MongoDB: indicadores e metadados
│           ├── gemini/                # Cliente Gemini API
│           └── prompts/               # Templates Jinja2
├── frontend/                          # React 18 + TypeScript + shadcn/ui
├── scripts/
│   ├── seed_db.py                     # Popular MongoDB com dados do CSV
│   └── ingest_articles.py             # Pipeline RAG: PDFs → pgvector
├── data/
│   ├── data.csv                       # ~3,6M registros de indicadores
│   ├── indicators_metadata.csv        # ~179 metadados de indicadores
│   └── referencias/                   # PDFs de políticas para o RAG
├── init-db/                           # Scripts de inicialização dos bancos
├── docker-compose.yml
├── Makefile
└── pyproject.toml

Princípio arquitetural: Clean Architecture com camadas estritas — domain → application → adapter → infrastructure. Nenhuma camada inferior depende de uma superior.

Stack Técnica

Backend

Camada	Tecnologia
Web Framework	FastAPI (async/await)
Orquestração de Agentes	LangGraph (grafos de estado)
LLM	Gemini 2.0 Flash (Google AI)
Embeddings	Google Text Embedding API (text-embedding-004)
Banco de Dados	MongoDB 7.0 (motor async)
Banco Vetorial	PostgreSQL 16 + pgvector
Busca Acadêmica	Tavily API
Busca na Web	Google Search API / SerpAPI
DI Container	dependency-injector
Config	Pydantic BaseSettings + python-dotenv
Linguagem	Python 3.11+

Frontend

Camada	Tecnologia
Framework	React 18 + TypeScript
Build	Vite
UI Components	shadcn/ui + Radix UI
Estilos	Tailwind CSS
Estado de Servidor	TanStack React Query
Roteamento	React Router v6

Infraestrutura

Camada	Tecnologia
Containerização	Docker + Docker Compose
Banco de Dados (dev)	MongoDB 7.0 + Mongo Express
Banco Vetorial (dev)	PostgreSQL 16 + pgAdmin 4

Primeiros Passos

Pré-requisitos

Docker e Docker Compose
Python 3.11+ com uv
Node.js 18+ (para o frontend)

1. Clone e configure o ambiente

git clone https://github.com/greenlet/lema-ods-racial-ai.git
cd lema-ods-racial-ai

# Copie e preencha as variáveis de ambiente
cp .env.example .env

2. Suba os bancos de dados

# Apenas os serviços de banco (produção)
make up

# Com interfaces gráficas (Mongo Express + pgAdmin) — desenvolvimento
make dev

Serviço	URL	Credenciais (dev)
MongoDB	`localhost:27017`	`lema / lema_secret`
PostgreSQL	`localhost:5432`	ver `.env`
Mongo Express	`http://localhost:8081`	`admin / admin_secret`
pgAdmin	`http://localhost:8080`	ver `.env`

3. Popule os bancos com os dados

# Instala dependências Python
uv sync

# Seed MongoDB com ~3,6M indicadores
uv run python scripts/seed_db.py

# Indexa artigos e PDFs de referência no pgvector
uv run python scripts/ingest_articles.py

4. Inicie a API

uvicorn src.main:app --reload --port 8000

A documentação interativa estará disponível em http://localhost:8000/docs.

5. Inicie o Frontend

cd frontend
npm install
npm run dev

O frontend estará em http://localhost:5173.

Variáveis de Ambiente

Copie .env.example para .env e preencha:

# Google AI
GEMINI_API_KEY=your_key_here
GOOGLE_EMBEDDING_MODEL=text-embedding-004

# MongoDB
MONGODB_URL=mongodb://lema:lema_secret@localhost:27017/ods_racial?authSource=admin
MONGO_DB=ods_racial

# PostgreSQL + pgvector
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/ods_racial_vectors

# Busca
TAVILY_API_KEY=your_key_here
GOOGLE_SEARCH_API_KEY=your_key_here
GOOGLE_SEARCH_ENGINE_ID=your_id_here

# App
APP_ENV=development
LOG_LEVEL=INFO
CORS_ORIGINS=*

API

Endpoints

Método	Rota	Descrição
`POST`	`/api/v1/analysis/analyze`	Analisa indicadores via linguagem natural
`GET`	`/api/v1/analysis/health`	Health check do serviço

Exemplo de Uso

Requisição:

curl -X POST http://localhost:8000/api/v1/analysis/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual é a disparidade salarial entre brancos e negros em São Paulo?",
    "session_id": "session-001",
    "user_id": "user-001"
  }'

Resposta:

{
  "response": "# Disparidade Salarial em São Paulo\n\nSegundo dados da RAIS 2022...",
  "session_id": "session-001"
}

Schema de Dados

Indicadores (MongoDB)

{
  "name": "Renda média do trabalho principal",
  "asian":  4823.50,
  "white":  3912.30,
  "black":  2104.80,
  "native": 1876.40,
  "format": "money",
  "region_id": "35",
  "region_name": "São Paulo",
  "region_group": "Estado, SP",
  "year": 2022
}

Campo `format`	Interpretação
`percent`	Participação relativa do grupo
`money`	Rendimento médio em R$
`float`	Médias ou totais diretos
`paridade`	100% = proporcional; >100% = super-representação; <100% = sub-representação

direction: "positiva" — valor maior é melhor (ex: salário). direction: "negativa" — valor maior é pior (ex: taxa de mortalidade).

Comandos Make

make up      # Sobe PostgreSQL + MongoDB
make dev     # Sobe tudo + Mongo Express + pgAdmin
make down    # Para todos os containers
make logs    # Acompanha logs em tempo real
make ps      # Status dos containers
make clean   # Para e apaga todos os volumes (DESTRUTIVO)
make reset   # clean + up

Desenvolvimento

# Testes
uv run pytest src/tests/ -v

# Type check
uv run mypy src/ --strict

# Linting
uv run ruff check src/

Autores

_{Nome Autor 1}
_{Cargo / Role}
LinkedIn • GitHub

_{Nome Autor 2}
_{Cargo / Role}
LinkedIn • GitHub

_{Nome Autor 3}
_{Cargo / Role}
LinkedIn • GitHub

Licença

Este projeto está licenciado sob a MIT License.

Desenvolvido com propósito pelo time Greenlet AI for Social Impact Hackathon 2026 — Google DeepMind × AI Tinkerers

"A luta de Marielle continua nos dados."

Name		Name	Last commit message	Last commit date
docker/postgres		docker/postgres
docs		docs
frontend		frontend
init-db		init-db
notebooks		notebooks
scripts		scripts
skills		skills
src		src
.DS_Store		.DS_Store
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

Franco — ODS Racial AI

Sobre o Projeto

Missão

Por que importa?

Demonstração

Arquitetura

Fluxo do Agente

Estrutura do Projeto

Stack Técnica

Backend

Frontend

Infraestrutura

Primeiros Passos

Pré-requisitos

1. Clone e configure o ambiente

2. Suba os bancos de dados

3. Popule os bancos com os dados

4. Inicie a API

5. Inicie o Frontend

Variáveis de Ambiente

API

Endpoints

Exemplo de Uso

Schema de Dados

Indicadores (MongoDB)

Comandos Make

Desenvolvimento

Autores

Licença

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Franco — ODS Racial AI

Sobre o Projeto

Missão

Por que importa?

Demonstração

Arquitetura

Fluxo do Agente

Estrutura do Projeto

Stack Técnica

Backend

Frontend

Infraestrutura

Primeiros Passos

Pré-requisitos

1. Clone e configure o ambiente

2. Suba os bancos de dados

3. Popule os bancos com os dados

4. Inicie a API

5. Inicie o Frontend

Variáveis de Ambiente

API

Endpoints

Exemplo de Uso

Schema de Dados

Indicadores (MongoDB)

Comandos Make

Desenvolvimento

Autores

Licença

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages