📚 Documentacao GIPM

# docs/METHOD_MAPPING.md

# Mapeamento GIPM - [Nome do Projeto]

## Principios Invariantes

| Principio | Implementacao | Arquivo/Classe |
|-----------|---------------|----------------|
| API-first | Toda funcionalidade via REST | `app/api/v1/` |
| Backend orquestra | Pipeline controla fluxo | `app/pipeline/universal.py` |
| Duas fases | AI gera JSON, sistema cria arquivo | `app/services/materializer.py` |
| Persistencia total | Todas interacoes no banco | `app/models/interaction.py` |
| Modular | Interfaces abstratas | `app/clients/base.py` |

## Camadas Arquiteturais

### Camada Humana
- Decisoes: Definidas em `config/business_rules.yaml`
- Limites: `MAX_TOKENS`, `DAILY_COST_LIMIT`
- Criterios: `config/success_criteria.yaml`

### Camada Sistema
- Validacao: `app/services/validator.py`
- Orquestracao: `app/pipeline/universal.py`
- Regras: `app/services/rules_engine.py`

### Camada Cognitiva
- Personas: `app/personas/`
- Invocacao: `app/clients/gemini.py`
- Guardrails: `app/services/cognitive_governance.py`

## Pipeline Universal - 9 Passos

| Passo | Funcao | Arquivo:Linha |
|-------|--------|---------------|
| 1 | Receber | `universal.py:45` |
| 2 | Validar | `universal.py:58` |
| 3 | Contextualizar | `universal.py:72` |
| 4 | Normalizar | `universal.py:89` |
| 5 | Selecionar Persona | `universal.py:105` |
| 6 | Invocar IA | `universal.py:125` |
| 7 | Persistir | `universal.py:148` |
| 8 | Materializar | `universal.py:165` |
| 9 | Retornar | `universal.py:182` |

# docs/COGNITIVE_GOVERNANCE.md

# Governanca Cognitiva - [Nome do Projeto]

## Personas Implementadas

### Summarizer
- **ID**: `summarizer`
- **Proposito**: Criar resumos concisos e estruturados
- **Guardrails**:
  - NUNCA adicionar informacao nao presente no texto
  - SEMPRE manter estrutura de bullet points
  - MAXIMO 3 paragrafos

### Analyst
- **ID**: `analyst`
- **Proposito**: Analisar dados e identificar padroes
- **Guardrails**:
  - NUNCA fazer previsoes sem dados
  - SEMPRE citar fonte dos numeros
  - OBRIGATORIO incluir limitacoes

## Regras de Selecao

```python
PERSONA_RULES = {
    "resumo": "summarizer",
    "analise": "analyst",
    "geracao": "creator",
    "revisao": "reviewer"
}
```

## Validacoes Pre-AI

1. **Tamanho**: Input entre 10 e 10000 caracteres
2. **Injection**: Bloqueio de padroes maliciosos
3. **Conteudo**: Filtro de conteudo proibido

## Validacoes Pos-AI

1. **Formato**: Resposta no schema esperado
2. **Tamanho**: Output dentro dos limites
3. **Qualidade**: Score minimo de coerencia

# app/api/v1/routes.py
from fastapi import APIRouter
from pydantic import BaseModel, Field

router = APIRouter()

class ProcessRequest(BaseModel):
    """
    Requisicao para processamento GIPM.

    Attributes:
        input: Texto a ser processado (10-10000 chars)
        task_type: Tipo de tarefa (resumo, analise, geracao)
        options: Opcoes adicionais de processamento
    """
    input: str = Field(..., min_length=10, max_length=10000,
                       description="Texto para processar")
    task_type: str = Field(..., description="Tipo: resumo|analise|geracao")
    options: dict = Field(default={}, description="Opcoes extras")

class ProcessResponse(BaseModel):
    """
    Resposta do processamento GIPM.

    Attributes:
        request_id: ID unico da requisicao (UUID v4)
        output: Resultado do processamento
        metadata: Informacoes de auditoria
    """
    request_id: str = Field(..., description="UUID da requisicao")
    output: str = Field(..., description="Resultado processado")
    metadata: dict = Field(..., description="Custos, tokens, latencia")

@router.post("/process", response_model=ProcessResponse)
async def process(request: ProcessRequest):
    """
    Processa texto usando o Pipeline Universal GIPM.

    - Valida entrada conforme regras de governanca
    - Seleciona persona apropriada
    - Invoca AI com guardrails
    - Persiste interacao completa
    - Retorna resultado estruturado
    """
    pass  # Implementacao

# OpenAPI automatico: GET /docs

# docs/RUNBOOK.md

# Runbook Operacional - [Nome do Projeto]

## Startup

```bash
# 1. Configurar ambiente
cp .env.example .env
# Editar .env com GEMINI_API_KEY

# 2. Instalar dependencias
pip install -r requirements.txt

# 3. Inicializar banco
alembic upgrade head

# 4. Iniciar servidor
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## Health Checks

```bash
# API Health
curl http://localhost:8000/health

# Database Health
curl http://localhost:8000/health/db

# AI Provider Health
curl http://localhost:8000/health/ai
```

## Troubleshooting

### Erro: "Rate limit exceeded"
1. Verificar `DAILY_COST_LIMIT` em .env
2. Consultar custos: `GET /api/v1/dashboard`
3. Aguardar reset (meia-noite UTC)

### Erro: "Persona not found"
1. Verificar task_type enviado
2. Consultar personas: `GET /api/v1/personas`
3. Verificar `app/personas/*.yaml`

### Erro: "Validation failed"
1. Verificar tamanho do input
2. Consultar logs: `docker logs app`
3. Testar com input minimo

# docs/adr/001-pipeline-universal.md

# ADR 001: Adocao do Pipeline Universal GIPM

## Status
Aceito

## Contexto
Precisamos de uma forma padronizada de processar
requisicoes que envolvem IA, garantindo governanca,
auditoria e controle de fluxo.

## Decisao
Implementar o Pipeline Universal de 9 passos conforme
especificado no metodo GIPM v1.2.

## Consequencias

### Positivas
- Todas as interacoes seguem mesmo fluxo
- Auditoria completa garantida por design
- Facil adicionar novos tipos de processamento

### Negativas
- Overhead em requisicoes simples
- Curva de aprendizado para novos devs

## Alternativas Consideradas
1. **Sem pipeline**: Rejeitado - sem garantias de governanca
2. **Pipeline simplificado (5 passos)**: Rejeitado - perderia
   rastreabilidade do metodo

---

# docs/adr/002-gemini-como-provider.md
# ADR 002: Gemini como Provider de AI

## Status
Aceito

## Decisao
Usar Gemini via API oficial, com interface abstrata
permitindo troca futura de provider.

# docs/DOCUMENTATION_CHECKLIST.md

# Checklist de Documentacao GIPM

## Documentos Obrigatorios

- [ ] **README.md**
  - [ ] Descricao do projeto
  - [ ] Quick start (< 5 comandos)
  - [ ] Link para documentacao completa

- [ ] **METHOD_MAPPING.md**
  - [ ] Mapeamento dos 5 principios
  - [ ] Mapeamento das 3 camadas
  - [ ] Mapeamento dos 9 passos do pipeline

- [ ] **COGNITIVE_GOVERNANCE.md**
  - [ ] Lista de personas
  - [ ] Guardrails de cada persona
  - [ ] Regras de selecao

- [ ] **API Documentation** (OpenAPI/Swagger)
  - [ ] Todos os endpoints documentados
  - [ ] Schemas com descricoes
  - [ ] Exemplos de request/response

- [ ] **RUNBOOK.md**
  - [ ] Instrucoes de deploy
  - [ ] Health checks
  - [ ] Troubleshooting comum

- [ ] **ADRs** (Architecture Decision Records)
  - [ ] ADR para Pipeline
  - [ ] ADR para AI Provider
  - [ ] ADR para Database

## Verificacao Final
```bash
# Script para verificar documentacao
python scripts/check_docs.py

# Output esperado:
# README.md ✓
# METHOD_MAPPING.md ✓
# COGNITIVE_GOVERNANCE.md ✓
# API Docs ✓
# RUNBOOK.md ✓
# ADRs ✓
# DOCUMENTATION COMPLETE
```