Metadata-Version: 2.4
Name: agent-flow-tdd
Version: 0.1.3
Summary: Framework para desenvolvimento orientado a testes com agentes de IA
Home-page: https://github.com/seu-usuario/agent-flow-tdd
Author: Seu Nome
Author-email: seu.email@exemplo.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: openai>=1.12.0
Requires-Dist: openrouter>=1.0.0
Requires-Dist: google-generativeai>=0.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: cachetools>=5.3.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: llama-cpp-python>=0.2.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: autoflake>=2.2.0; extra == "dev"
Requires-Dist: build>=1.0.3; extra == "dev"
Requires-Dist: twine>=4.0.2; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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:
```bash
git clone https://github.com/seu-usuario/prompt-tdd.git
cd prompt-tdd
```

2. Configure as variáveis de ambiente necessárias:
```bash
# Não use arquivos .env, configure diretamente no ambiente
export OPENAI_API_KEY="sua-chave-aqui"
```

3. Instale as dependências:
```bash
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.

```bash
make install
```

### `make test`
Executa todos os testes do projeto.

```bash
make test
```

### `make cli`
Inicia o CLI para processamento de features.

```bash
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](https://github.com/modelcontextprotocol/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:
```bash
prompt-tdd mcp
```

2. Envie mensagens no formato MCP:
```json
{
  "content": "Criar sistema de login",
  "metadata": {
    "type": "feature",
    "options": {
      "model": "gpt-4-turbo",
      "temperature": 0.7,
      "format": "json"
    }
  }
}
```

3. Receba respostas no formato MCP:
```json
{
  "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

```python
from mcp_sdk import MCPHandler
from src.app import AgentOrchestrator

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

### 2. Via CLI

```bash
# 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:

```json
{
  "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:
```bash
make download-model
```

2. Use o modelo via CLI:
```bash
prompt-tdd feature "Criar API" --model tinyllama-1.1b
```

3. Ou via MCP:
```json
{
  "content": "Criar API REST",
  "metadata": {
    "type": "feature",
    "options": {
      "model": "tinyllama-1.1b",
      "temperature": 0.7
    }
  }
}
```

## 🧪 Testes

O projeto usa pytest para testes. Execute:

```bash
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](LICENSE) para mais detalhes.

## Uso

O Prompt TDD pode ser usado de duas formas:

### 1. Usando o Makefile (recomendado)

```bash
# 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:

```bash
source .venv/bin/activate
```

Então use o comando `prompt-tdd`:

```bash
# 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

```bash
make test
```

## Limpeza

```bash
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

```bash
# 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

```python
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

```python
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

```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

```bash
# 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

```bash
# 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

```bash
# 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](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:

```bash
# 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:

```bash
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

```bash
# 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:
```bash
cp .docker/.env.example .docker/.env
```

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

### Executando
Para desenvolvimento:
```bash
docker-compose -f .docker/docker-compose.yml run dev
```

Para produção:
```bash
docker-compose -f .docker/docker-compose.yml run app
```

### Comandos Úteis
- Construir as imagens:
```bash
docker-compose -f .docker/docker-compose.yml build
```

- Visualizar logs:
```bash
docker-compose -f .docker/docker-compose.yml logs -f
```

- Limpar volumes:
```bash
docker-compose -f .docker/docker-compose.yml down -v
```
