TALP Compliance Agent

Agente intermediário de análise de regras de negócio e compliance para o projeto acadêmico TALP-CIN — Pipeline Multiagente para Validação de User Stories.

Este repositório implementa o agente:

talp-compliance-agent

Ele faz parte de um pipeline multiagente composto por:

talp-invest-agent — avalia a qualidade da User Story usando critérios INVEST.
talp-compliance-agent — identifica regras de negócio, compliance, dependências, regras bloqueantes e lacunas.
talp-bdd-agent — gera ou avalia cenários BDD a partir da User Story enriquecida.

Objetivo

O talp-compliance-agent recebe uma User Story já analisada pelo talp-invest-agent e executa uma análise de conformidade baseada em catálogo.

O agente identifica:

regras de negócio aplicáveis;
regras obrigatórias;
regras bloqueantes;
dependências entre regras;
lacunas de informação;
requisitos de compliance;
possibilidade de seguir para o agente BDD.

Restrição principal

O agente não pode inventar regras.

Todas as regras utilizadas na análise devem vir exclusivamente do catálogo local:

data/catalog_rules_v1.csv

A saída final deve ser rastreável e validada contra esse catálogo.

Pipeline Multiagente

User Story original
        ↓
[talp-invest-agent]
        ↓
Resultado INVEST estruturado
        ↓
[talp-compliance-agent]
        ↓
Análise de regras, compliance, dependências e lacunas
        ↓
[talp-bdd-agent]
        ↓
Cenários BDD / Validação final

Estado atual do projeto

Nesta etapa, o projeto já possui:

API FastAPI funcionando;
health check;
catálogo de regras carregado via CSV;
sincronização do catálogo com banco SQLite;
persistência de execuções de análise;
endpoints de análise de compliance;
endpoint para análise via arquivo JSON;
Streamlit disponível via Docker;
Docker Compose validado;
banco SQLite inicializado automaticamente no startup da API.

Pré-requisitos

Para execução local:

Python 3.10+ ou 3.11+
pip
Git

Para execução com Docker:

Docker
Docker Compose

Estrutura do Projeto

talp-compliance-agent/
├── app/
│   ├── api/
│   │   └── routes/
│   │       ├── health.py
│   │       ├── compliance.py
│   │       ├── compliance_runs.py
│   │       └── catalog.py
│   ├── config/
│   │   └── settings.py
│   ├── db/
│   │   ├── base.py
│   │   ├── session.py
│   │   ├── models.py
│   │   └── init_db.py
│   ├── nodes/
│   ├── schemas/
│   │   └── models.py
│   ├── services/
│   │   ├── catalog_repository.py
│   │   ├── file_loader.py
│   │   ├── persistence_service.py
│   │   └── rule_matcher.py
│   ├── graph.py
│   ├── graph_state.py
│   └── main.py
├── data/
│   ├── catalog_rules_v1.csv
│   └── samples/
├── features/
├── prompts/
├── storage/
│   ├── audit/
│   ├── db/
│   ├── exports/
│   └── imports/
├── tests/
├── streamlit_app.py
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── .env.example
├── .dockerignore
├── .gitignore
└── README.md

Catálogo de Regras

O catálogo principal está em:

data/catalog_rules_v1.csv

Regras atuais:

ID	Nome	Domínio	Obrigatória	Bloqueante
RULE_001	Sinais Vitais Obrigatórios	Triagem	Sim	Sim
RULE_002	Classificação Manchester	Triagem	Sim	Sim
RULE_003	Registro HDA	Atendimento Médico	Sim	Sim
RULE_004	CID Obrigatório	Diagnóstico	Sim	Sim
RULE_005	Conduta Médica Obrigatória	Diagnóstico	Sim	Sim
RULE_006	Atualização de Status	Fluxo Assistencial	Sim	Não
RULE_007	Prescrição Médica Obrigatória	Prescrição	Sim	Sim
RULE_008	Validação CCIH	Controle de Infecção	Sim	Sim

Execução com Docker

A forma mais simples de subir o projeto é com Docker Compose.

1. Subir os containers

docker compose up --build

Caso o usuário ainda não tenha permissão para executar Docker sem sudo, use:

sudo docker compose up --build

A API ficará disponível em:

http://localhost:8000

O Streamlit ficará disponível em:

http://localhost:8501

2. Testar health check

Em outro terminal:

curl http://localhost:8000/health

Resultado esperado:

{
  "status": "healthy",
  "service": "talp-compliance-agent",
  "version": "0.1.0"
}

3. Acessar documentação da API

Swagger:

http://localhost:8000/docs

ReDoc:

http://localhost:8000/redoc

4. Acessar Streamlit

http://localhost:8501

5. Parar os containers

docker compose down

Ou, usando sudo:

sudo docker compose down

Execução local sem Docker

1. Clonar o repositório

git clone https://github.com/SEU-USUARIO/talp-compliance-agent.git
cd talp-compliance-agent

Substitua SEU-USUARIO pelo usuário ou organização real do GitHub.

2. Criar ambiente virtual

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

Caso o projeto esteja usando a pasta venv:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\activate

3. Instalar dependências

python -m pip install --upgrade pip
pip install -e ".[dev]"

Se houver erro com as dependências de desenvolvimento, instalar manualmente:

pip install fastapi "uvicorn[standard]" pydantic pydantic-settings sqlalchemy pandas odfpy python-dotenv langchain langchain-core langgraph streamlit pytest pytest-bdd httpx ruff

4. Configurar variáveis de ambiente

cp .env.example .env

O .env local não deve ser enviado para o Git.

5. Inicializar banco local

python -m app.db.init_db

O banco SQLite será criado em:

storage/db/compliance_agent.db

Esse arquivo também não deve ser enviado para o Git.

6. Rodar a API localmente

uvicorn app.main:app --reload

Ou:

python -m uvicorn app.main:app --reload

A API ficará disponível em:

http://localhost:8000

Endpoints principais

Health check

GET /health
GET /api/v1/health

Exemplo:

curl http://localhost:8000/health

Listar regras do catálogo

GET /api/v1/catalog/rules

Exemplo:

curl http://localhost:8000/api/v1/catalog/rules

Sincronizar catálogo com banco

POST /api/v1/catalog/sync

Exemplo:

curl -X POST http://localhost:8000/api/v1/catalog/sync

Resultado esperado:

{
  "status": "ok",
  "synced_rules": 8,
  "message": "8 regra(s) sincronizada(s)."
}

Executar análise de compliance

POST /api/v1/compliance/analyze

Exemplo:

curl -X POST http://localhost:8000/api/v1/compliance/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "investment_id": "US-001",
    "invest_result": {
      "investment_id": "US-001",
      "status": "warning",
      "criteria_results": [
        {
          "criterion_id": "TEST-001",
          "criterion_name": "Testable",
          "result": true,
          "evidence": "A história possui elementos verificáveis."
        }
      ],
      "summary": "Como médico, quero prescrever antibiótico para paciente internado, para iniciar o tratamento adequado.",
      "metadata": {}
    }
  }'

Resultado esperado: a resposta deve conter regras como RULE_007 e RULE_008, caso a lógica de matching encontre evidências relacionadas a prescrição e antibiótico.

Executar análise a partir de arquivo

POST /api/v1/compliance/analyze-file

Exemplo:

curl -X POST http://localhost:8000/api/v1/compliance/analyze-file \
  -H "Content-Type: application/json" \
  -d '{"file_path": "data/samples/compliance_request_sample.json"}'

Listar execuções salvas

GET /api/v1/compliance/runs

Exemplo:

curl http://localhost:8000/api/v1/compliance/runs

Consultar execução específica

GET /api/v1/compliance/runs/{run_id}

Persistência

O projeto usa SQLite local por padrão.

Configuração no .env.example:

DATABASE_URL=sqlite:///./storage/db/compliance_agent.db

A aplicação inicializa as tabelas no startup da API.

Arquivos locais de banco e auditoria não são versionados:

storage/db/*.db
storage/audit/*.jsonl

As pastas são mantidas no Git por meio de arquivos .gitkeep.

Streamlit

A interface Streamlit pode ser executada com Docker Compose:

docker compose up --build

Depois acesse:

http://localhost:8501

Também pode ser executada localmente:

streamlit run streamlit_app.py

Testes

Executar todos os testes:

pytest

Executar com detalhes:

pytest -v

Executar testes BDD, se configurados:

pytest features

Docker validado

O Docker Compose foi validado nesta etapa com:

docker compose up --build
curl http://localhost:8000/health

Resultado obtido:

{
  "status": "healthy",
  "service": "talp-compliance-agent",
  "version": "0.1.0"
}

Serviços disponíveis:

Serviço	URL
API FastAPI	http://localhost:8000
Swagger	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
Streamlit	http://localhost:8501

Como outro desenvolvedor pode revisar

1. Clonar o repositório

git clone https://github.com/SEU-USUARIO/talp-compliance-agent.git
cd talp-compliance-agent

2. Rodar com Docker

docker compose up --build

3. Testar API

curl http://localhost:8000/health
curl http://localhost:8000/api/v1/catalog/rules
curl -X POST http://localhost:8000/api/v1/catalog/sync
curl http://localhost:8000/api/v1/compliance/runs

4. Acessar documentação

http://localhost:8000/docs

5. Acessar Streamlit

http://localhost:8501

Problemas comuns

Erro: porta 8000 em uso

Se aparecer erro de porta ocupada:

lsof -i :8000

Mate o processo:

kill -9 NUMERO_DO_PID

Ou altere a porta externa no docker-compose.yml:

ports:
  - "8001:8000"

Nesse caso, a API ficará em:

http://localhost:8001

Erro: permission denied no Docker

Se aparecer:

permission denied while trying to connect to the docker API

Use temporariamente:

sudo docker compose up --build

Para corrigir definitivamente:

sudo usermod -aG docker $USER

Depois faça logout/login no Ubuntu.

Aviso: version is obsolete

Se o Docker Compose avisar que version é obsoleto, remova a linha:

version: "3.8"

O arquivo deve começar diretamente com:

services:

Próximos passos

Contribuidores

TALP-CIN Team

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.devcontainer		.devcontainer
app		app
data		data
features		features
prompts		prompts
storage		storage
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
RELATORIO_TECNICO_TALP_COMPLIANCE_AGENT.md		RELATORIO_TECNICO_TALP_COMPLIANCE_AGENT.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
streamlit_app.py		streamlit_app.py

Folders and files

Latest commit

History

Repository files navigation

TALP Compliance Agent

Objetivo

Restrição principal

Pipeline Multiagente

Estado atual do projeto

Pré-requisitos

Estrutura do Projeto

Catálogo de Regras

Execução com Docker

1. Subir os containers

2. Testar health check

3. Acessar documentação da API

4. Acessar Streamlit

5. Parar os containers

Execução local sem Docker

1. Clonar o repositório

2. Criar ambiente virtual

3. Instalar dependências

4. Configurar variáveis de ambiente

5. Inicializar banco local

6. Rodar a API localmente

Endpoints principais

Health check

Listar regras do catálogo

Sincronizar catálogo com banco

Executar análise de compliance

Executar análise a partir de arquivo

Listar execuções salvas

Consultar execução específica

Persistência

Streamlit

Testes

Docker validado

Como outro desenvolvedor pode revisar

1. Clonar o repositório

2. Rodar com Docker

3. Testar API

4. Acessar documentação

5. Acessar Streamlit

Problemas comuns

Erro: porta 8000 em uso

Erro: permission denied no Docker

Aviso: version is obsolete

Próximos passos

Contribuidores

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages