agent-flow-tdd 0.1.3

Framework para desenvolvimento orientado a testes com agentes de IA

Prompt TDD

Um sistema para desenvolvimento orientado a testes usando prompts de IA.

🚀 Funcionalidades

• Geração de features com critérios de aceite e cenários de teste
• Análise de complexidade e estimativas
• Suporte a múltiplos modelos de IA (GPT-3.5, GPT-4)
• Interface CLI com modo interativo e MCP (Multi-Command Protocol)
• Saída em formatos JSON e Markdown
• Configuração unificada e centralizada

📋 Pré-requisitos

• Python 3.13+
• Chave de API OpenAI (OPENAI_API_KEY)
• Ambiente virtual Python (venv)

🛠️ Instalação

1. Clone o repositório:

git clone https://github.com/seu-usuario/prompt-tdd.git
cd prompt-tdd

2. Configure as variáveis de ambiente necessárias:

# Não use arquivos .env, configure diretamente no ambiente
export OPENAI_API_KEY="sua-chave-aqui"

3. Instale as dependências:

make install

⚙️ Configuração

O projeto usa um arquivo de configuração unificado em src/configs/cli.yaml com três seções principais:

1. CLI (cli)

• Configurações de saída (formatos, indentação)
• Configurações do modelo (nome, temperatura)
• Mensagens do sistema
• Formatação JSON

2. MCP (mcp)

• Configurações de logging do MCP
• Configurações do LLM
• Configurações do handler MCP
• Formatos de metadados

3. Aplicação (app)

• Configurações do modelo
• Configurações do banco de dados
• Configurações de logging
• Configurações de exemplo
• Configurações de resultado

🎮 Comandos Disponíveis

make install

Instala todas as dependências do projeto.

make install

make test

Executa todos os testes do projeto.

make test

make cli

Inicia o CLI para processamento de features.

make cli

# Exemplos de uso:
prompt-tdd feature "Criar sistema de login com autenticação de dois fatores"
prompt-tdd feature "Criar sistema de cadastro de usuários" --model gpt-4-turbo
prompt-tdd feature "Criar API REST" --format markdown
prompt-tdd status

Opções do comando feature:

• --model, -m: Modelo a ser usado (default: gpt-3.5-turbo)
• --elevation-model, -e: Modelo para fallback (default: gpt-4-turbo)
• --force, -f: Força uso do modelo sem fallback
• --api-key, -k: Chave da API (opcional)
• --timeout, -t: Tempo limite em segundos (default: 30)
• --max-retries, -r: Máximo de tentativas (default: 3)
• --temperature, -temp: Temperatura do modelo (default: 0.7)
• --max-tokens, -mt: Limite de tokens (opcional)
• --format, -fmt: Formato de saída (json/markdown)

Protocolo MCP (Model Context Protocol)

O projeto agora suporta o Model Context Protocol oficial, permitindo:

• Integração padronizada com diferentes modelos de IA
• Comunicação bidirecional via protocolo MCP
• Suporte a streaming e eventos assíncronos

Como Funciona

1. Inicie o modo MCP:

prompt-tdd mcp

2. Envie mensagens no formato MCP:

{
  "content": "Criar sistema de login",
  "metadata": {
    "type": "feature",
    "options": {
      "model": "gpt-4-turbo",
      "temperature": 0.7,
      "format": "json"
    }
  }
}

3. Receba respostas no formato MCP:

{
  "content": {
    "feature": "Sistema de Login",
    "acceptance_criteria": [...],
    "test_scenarios": [...],
    "complexity": 3
  },
  "metadata": {
    "status": "success",
    "type": "feature"
  }
}

🤖 Integração de Modelos

O projeto usa o Model Context Protocol para integração com diferentes modelos:

1. Via SDK MCP

from mcp_sdk import MCPHandler
from src.app import AgentOrchestrator

handler = MCPHandler()
handler.initialize(api_key="sua-chave")
handler.run()

2. Via CLI

# OpenAI GPT-4
prompt-tdd feature "Criar API" --model gpt-4-turbo --api-key $OPENAI_API_KEY

# Anthropic Claude
prompt-tdd feature "Criar API" --model claude-3 --api-key $ANTHROPIC_KEY

3. Via MCP

Especifique o modelo nas options:

{
  "content": "Criar API REST",
  "metadata": {
    "type": "feature",
    "options": {
      "model": "gpt-4-turbo",
      "api_key": "sua-chave",
      "temperature": 0.7
    }
  }
}

Modelos Suportados

Atualmente:

• OpenAI GPT-3.5 Turbo
• OpenAI GPT-4 Turbo
• Anthropic Claude (via MCP)
• TinyLLaMA 1.1B (local, via llama.cpp)
• Outros modelos compatíveis com MCP

Configuração do TinyLLaMA

Para usar o TinyLLaMA:

1. O modelo será baixado automaticamente durante a instalação (make install). Alternativamente, você pode baixá-lo manualmente:

make download-model

2. Use o modelo via CLI:

prompt-tdd feature "Criar API" --model tinyllama-1.1b

3. Ou via MCP:

{
  "content": "Criar API REST",
  "metadata": {
    "type": "feature",
    "options": {
      "model": "tinyllama-1.1b",
      "temperature": 0.7
    }
  }
}

🧪 Testes

O projeto usa pytest para testes. Execute:

make test

📝 Logs

Os logs são gerados automaticamente com:

• Nível INFO para entrada/saída de funções
• Nível DEBUG para estados intermediários
• Nível ERROR para exceções (com stacktrace)
• Configuração centralizada em cli.yaml

🔒 Variáveis de Ambiente

Variáveis obrigatórias:

• OPENAI_API_KEY: Chave da API OpenAI

Variáveis opcionais:

• OPENROUTER_KEY: Chave da API OpenRouter
• GEMINI_KEY: Chave da API Gemini
• ANTHROPIC_KEY: Chave da API Anthropic
• LOG_LEVEL: Nível de log (default: INFO)
• CACHE_DIR: Diretório de cache
• CACHE_TTL: Tempo de vida do cache
• FALLBACK_ENABLED: Habilita fallback de modelos
• DEFAULT_MODEL: Modelo padrão
• ELEVATION_MODEL: Modelo para fallback
• MODEL_TIMEOUT: Timeout para chamadas de modelo
• MAX_RETRIES: Máximo de tentativas

IMPORTANTE: Não use arquivos .env. Configure as variáveis diretamente no ambiente ou via argumentos.

🤝 Contribuindo

1. Fork o projeto
2. Crie sua branch de feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Uso

O Prompt TDD pode ser usado de duas formas:

1. Usando o Makefile (recomendado)

# Criar uma nova feature
make run prompt-tdd="Criar um sistema de login com autenticação JWT"

# Verificar status do ambiente
make run prompt-tdd="" mode=status

# Iniciar servidor MCP em background (sem saída no terminal)
make run prompt-tdd="" mode=mcp
# O servidor MCP será iniciado em background e você verá apenas o PID do processo

2. Usando o comando diretamente

Primeiro, ative o ambiente virtual:

source .venv/bin/activate

Então use o comando prompt-tdd:

# Criar uma nova feature
prompt-tdd "Criar um sistema de login com autenticação JWT"

# Verificar status do ambiente
prompt-tdd --mode status ""

# Iniciar servidor MCP (irá bloquear o terminal e mostrar logs)
prompt-tdd --mode mcp ""

# Ou inicie em background sem logs
nohup prompt-tdd --mode mcp "" > /dev/null 2>&1 &

Opções

• --format: Formato de saída (json ou markdown). Padrão: json
• --mode: Modo de operação (feature, status ou mcp). Padrão: feature

Testes

make test

Limpeza

make clean

Agent Flow TDD

Framework para desenvolvimento orientado a testes com agentes de IA.

Recursos

• Desenvolvimento orientado a testes para agentes de IA
• Integração com OpenAI Agent SDK
• Logging estruturado em SQLite
• Suporte a múltiplos provedores de LLM
• Sistema de tracing e monitoramento
• Interface MCP (Model Context Protocol)

Instalação

# Instalação básica
pip install agent-flow-tdd

# Instalação com dependências de desenvolvimento
pip install agent-flow-tdd[dev]

Uso Básico

from src.app import AgentOrchestrator

# Inicializa o orquestrador
orchestrator = AgentOrchestrator(api_key="sua-chave-api")

# Processa uma entrada
result = orchestrator.handle_input("Criar sistema de login")
print(result)

Logging Estruturado

O framework inclui um sistema de logging estruturado que armazena todas as interações em SQLite:

Dados Armazenados

• Execuções de Agentes

  • Session ID
  • Input/Output
  • Último agente executado
  • Tipo de saída
  • Timestamp

• Itens Gerados

  • MessageOutput
  • HandoffCall/HandoffOutput
  • ToolCall/ToolCallOutput
  • ReasoningItem

• Guardrails

  • Resultados de input/output
  • Mensagens de validação

• Respostas Brutas

  • Respostas do LLM
  • Metadados de execução

Consulta de Logs

from src.core.db import DatabaseManager

# Inicializa o gerenciador
db = DatabaseManager()

# Busca histórico de execuções
history = db.get_run_history(limit=10)

# Exemplo de processamento
for run in history:
    print(f"Execução {run['id']}:")
    print(f"- Input: {run['input']}")
    print(f"- Agente: {run['last_agent']}")
    print(f"- Items gerados: {len(run['items'])}")
    print(f"- Guardrails: {len(run['guardrails'])}")
    print(f"- Respostas: {len(run['raw_responses'])}")

Schema SQL

-- Tabela principal de execuções
CREATE TABLE agent_runs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    session_id TEXT NOT NULL,
    input TEXT NOT NULL,
    last_agent TEXT,
    output_type TEXT,
    final_output TEXT
);

-- Tabela de itens gerados
CREATE TABLE run_items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    run_id INTEGER NOT NULL,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    item_type TEXT NOT NULL,
    raw_item TEXT NOT NULL,
    source_agent TEXT,
    target_agent TEXT,
    FOREIGN KEY(run_id) REFERENCES agent_runs(id)
);

-- Tabela de resultados de guardrails
CREATE TABLE guardrail_results (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    run_id INTEGER NOT NULL,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    guardrail_type TEXT CHECK(guardrail_type IN ('input', 'output')),
    results TEXT NOT NULL,
    FOREIGN KEY(run_id) REFERENCES agent_runs(id)
);

-- Tabela de respostas brutas do LLM
CREATE TABLE raw_responses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    run_id INTEGER NOT NULL,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    response TEXT NOT NULL,
    FOREIGN KEY(run_id) REFERENCES agent_runs(id)
);

Desenvolvimento

Configuração do Ambiente

# Clone o repositório
git clone https://github.com/seu-usuario/agent-flow-tdd.git
cd agent-flow-tdd

# Crie um ambiente virtual
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Instale em modo desenvolvimento
pip install -e ".[dev]"

Executando Testes

# Executa todos os testes
make test

# Executa testes com cobertura
pytest --cov=src tests/

# Executa testes específicos
pytest tests/test_db.py -v

Linting e Formatação

# Formata o código
make format

# Executa linters
make lint

# Limpa imports não utilizados
make autoflake

Contribuindo

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Crie um Pull Request

Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.

Visualização de Logs

O framework inclui um visualizador de logs que permite consultar o histórico de execuções dos agentes. Para usar:

# Lista as últimas 10 execuções
make logs

# Lista as últimas N execuções
make logs ARGS="--limit 20"

# Filtra por session ID
make logs ARGS="--session abc123"

# Filtra por agente
make logs ARGS="--agent CodeReviewer"

# Mostra detalhes de uma execução específica
make logs ARGS="--id 42"

O visualizador mostra:

• Lista resumida de execuções com timestamp, session, agente e contadores
• Detalhes completos de uma execução específica incluindo:
  • Input/output
  • Itens gerados entre agentes
  • Resultados de guardrails
  • Respostas brutas do LLM

Comandos Disponíveis

Para ver todos os comandos disponíveis:

make help

Ambiente

• make install - Instala dependências do projeto
• make clean - Remove arquivos temporários
• make dev - Executa em modo desenvolvimento

Qualidade

• make test - Executa testes
• make coverage - Gera relatório de cobertura
• make lint - Executa linters
• make format - Formata código

Banco de Dados

• make db-init - Inicializa banco de dados
• make db-clean - Remove banco de dados
• make db-backup - Faz backup do banco
• make logs - Visualiza logs do banco

Exemplos

# Executa o agente com um prompt
make dev prompt-tdd="Cadastro de pessoas" mode=mcp format=markdown

# Visualiza os últimos 20 logs de uma sessão
make logs ARGS="--limit 20 --session abc123"

# Visualiza detalhes de uma execução específica
make logs ARGS="--id 42"

🐳 Usando com Docker

Pré-requisitos

• Docker
• Docker Compose

Configuração

1. Copie o arquivo de exemplo de variáveis de ambiente:

cp .docker/.env.example .docker/.env

2. Configure suas chaves de API no arquivo .docker/.env

Executando

Para desenvolvimento:

docker-compose -f .docker/docker-compose.yml run dev

Para produção:

docker-compose -f .docker/docker-compose.yml run app

Comandos Úteis

• Construir as imagens:

docker-compose -f .docker/docker-compose.yml build

• Visualizar logs:

docker-compose -f .docker/docker-compose.yml logs -f

• Limpar volumes:

docker-compose -f .docker/docker-compose.yml down -v