# Plano de Implementação: Filtros Inteligentes de Documentos

## Visão Geral

Criar filtros inteligentes para seleção de documentos quando o markdown completo não cabe no contexto do LLM. Inclui view otimizada no Supabase, novos métodos no cliente e nova tool com categorias.

---

## Fase 1: View no Supabase

Criar view que já filtra e prioriza documentos relevantes diretamente no banco.

### Tarefas

- [x] Criar view `vw_documentos_relevantes` via migration MCP

### Detalhes Técnicos

**Migration SQL:**

```sql
CREATE OR REPLACE VIEW vw_documentos_relevantes AS
SELECT
    id,
    numero_processo,
    nome,
    tipo_nome,
    data_juntada,
    tamanho_texto,
    sequencia,
    conteudo,
    CASE
        WHEN LOWER(COALESCE(nome, '')) LIKE '%sentenc%' THEN 1
        WHEN LOWER(COALESCE(nome, '')) LIKE '%acordao%' OR LOWER(COALESCE(nome, '')) LIKE '%acord%' THEN 2
        WHEN LOWER(COALESCE(nome, '')) LIKE '%decisao%' OR LOWER(COALESCE(nome, '')) LIKE '%decis%' THEN 3
        WHEN LOWER(COALESCE(nome, '')) LIKE '%denunc%' OR LOWER(COALESCE(nome, '')) LIKE '%denncia%' THEN 4
        WHEN LOWER(COALESCE(nome, '')) LIKE '%petic%' OR LOWER(COALESCE(nome, '')) LIKE '%petio%' THEN 5
        WHEN LOWER(COALESCE(nome, '')) LIKE '%contest%' THEN 6
        WHEN LOWER(COALESCE(nome, '')) LIKE '%inquer%' OR LOWER(COALESCE(nome, '')) LIKE '%inqurito%' THEN 7
        WHEN LOWER(COALESCE(nome, '')) LIKE '%laudo%' THEN 8
        ELSE 99
    END as prioridade
FROM documents
WHERE tamanho_texto > 500
ORDER BY numero_processo, prioridade, sequencia DESC;
```

---

## Fase 2: Métodos no Supabase Client

Adicionar métodos para filtros por período, tamanho e usando a view.

### Tarefas

- [x] Adicionar método `buscar_documentos_por_periodo()`
- [x] Adicionar método `buscar_documentos_por_tamanho()`
- [x] Adicionar método `buscar_documentos_relevantes()`

### Detalhes Técnicos

**Arquivo:** `services/supabase_client.py`

```python
async def buscar_documentos_por_periodo(
    self,
    numero_processo: str,
    data_inicio: str | None = None,
    data_fim: str | None = None,
    limite: int = 50
) -> list[dict[str, Any]]:
    """Busca documentos juntados em um período específico."""
    query = (
        self._client.table("documents")
        .select("id, sequencia, nome, tipo_nome, data_juntada, tamanho_texto, conteudo")
        .eq("numero_processo", numero_processo)
        .order("data_juntada", desc=True)
        .limit(limite)
    )
    if data_inicio:
        query = query.gte("data_juntada", data_inicio)
    if data_fim:
        query = query.lte("data_juntada", data_fim)

    response = query.execute()
    return response.data or []


async def buscar_documentos_por_tamanho(
    self,
    numero_processo: str,
    min_chars: int = 1000,
    max_chars: int | None = None,
    limite: int = 30
) -> list[dict[str, Any]]:
    """Busca documentos por faixa de tamanho."""
    query = (
        self._client.table("documents")
        .select("id, sequencia, nome, tipo_nome, data_juntada, tamanho_texto, conteudo")
        .eq("numero_processo", numero_processo)
        .gte("tamanho_texto", min_chars)
        .order("tamanho_texto", desc=True)
        .limit(limite)
    )
    if max_chars:
        query = query.lte("tamanho_texto", max_chars)

    response = query.execute()
    return response.data or []


async def buscar_documentos_relevantes(
    self,
    numero_processo: str,
    limite: int = 50
) -> list[dict[str, Any]]:
    """Busca documentos usando view otimizada com prioridade."""
    response = (
        self._client.table("vw_documentos_relevantes")
        .select("*")
        .eq("numero_processo", numero_processo)
        .limit(limite)
        .execute()
    )
    return response.data or []
```

---

## Fase 3: Tool documentos_importantes

Criar tool com filtros inteligentes por categoria, período e tamanho.

### Tarefas

- [x] Adicionar constante `CATEGORIAS_DOCS` em documentos.py
- [x] Criar tool `documentos_importantes()`
- [x] Importar `_normalize_text` do supabase_client

### Detalhes Técnicos

**Arquivo:** `tools/documentos.py`

```python
from services.supabase_client import get_supabase_client, _normalize_text

# Categorias de documentos para filtro
CATEGORIAS_DOCS = {
    "decisorio": ["sentenc", "acordao", "acord", "decisao", "decis", "despacho"],
    "peticoes": ["petic", "petio", "inicial", "contest", "replica", "recurso", "agravo"],
    "provas": ["laudo", "pericia", "certid", "documento", "comprova"],
    "criminal": ["denunc", "denncia", "inquer", "inqurito", "defesa"],
}

@mcp.tool
async def documentos_importantes(
    numero_processo: str,
    categoria: str | None = None,
    periodo_dias: int | None = None,
    min_chars: int = 500,
    ctx: Context = None,
) -> dict[str, Any]:
    """
    Retorna documentos mais importantes do processo com filtros inteligentes.

    Args:
        numero_processo: Numero do processo
        categoria: "decisorio", "peticoes", "provas", "criminal" (opcional)
        periodo_dias: Apenas docs dos ultimos N dias (opcional)
        min_chars: Tamanho minimo do conteudo (default: 500)

    Returns:
        Documentos filtrados e ordenados por relevancia
    """
    from datetime import datetime, timedelta

    client = get_supabase_client()

    # Usa view otimizada
    docs = await client.buscar_documentos_relevantes(numero_processo, limite=100)

    # Filtra por categoria se especificado
    if categoria and categoria in CATEGORIAS_DOCS:
        termos = CATEGORIAS_DOCS[categoria]
        docs = [
            d for d in docs
            if any(t in _normalize_text(d.get("nome") or "") for t in termos)
        ]

    # Filtra por período se especificado
    if periodo_dias:
        data_limite = (datetime.now() - timedelta(days=periodo_dias)).isoformat()
        docs = [d for d in docs if (d.get("data_juntada") or "") >= data_limite]

    # Filtra por tamanho mínimo
    docs = [d for d in docs if (d.get("tamanho_texto") or 0) >= min_chars]

    return {
        "numero_processo": numero_processo,
        "filtros": {
            "categoria": categoria,
            "periodo_dias": periodo_dias,
            "min_chars": min_chars,
        },
        "total": len(docs),
        "documentos": [
            {
                "id": d.get("id"),
                "nome": d.get("nome"),
                "tipo": d.get("tipo_nome"),
                "data": str(d.get("data_juntada"))[:10] if d.get("data_juntada") else None,
                "chars": d.get("tamanho_texto"),
                "prioridade": d.get("prioridade"),
            }
            for d in docs[:30]
        ],
    }
```

---

## Fase 4: Mapeamento de Códigos

Investigar e mapear códigos genéricos de tipo_nome.

### Tarefas

- [x] Rodar query para descobrir padrões de TipoProcessoDocumento#XX
- [x] Criar dicionário MAPA_TIPOS_CODIGO se padrões claros forem encontrados

### Detalhes Técnicos

**Query de investigação:**

```sql
SELECT tipo_nome, tipo_codigo, COUNT(*) as qtd,
       array_agg(DISTINCT LEFT(nome, 50)) as exemplos
FROM documents
WHERE tipo_nome LIKE 'TipoProcessoDocumento#%'
GROUP BY tipo_nome, tipo_codigo
ORDER BY qtd DESC;
```

**Dicionário (se padrões claros):**

```python
# Adicionar em supabase_client.py
MAPA_TIPOS_CODIGO = {
    "TipoProcessoDocumento#13": "Petição Diversa",
    "TipoProcessoDocumento#249": "Documento Anexo",
    # ... etc
}
```

---

## Fase 5: Documentação

Atualizar CLAUDE.md com as novas funcionalidades.

### Tarefas

- [x] Documentar tool `documentos_importantes` com categorias
- [x] Documentar novos métodos do cliente
- [x] Atualizar contagem de tools (32 -> 33)

### Detalhes Técnicos

**Adicionar em CLAUDE.md seção Documentos:**

```markdown
#### `documentos_importantes`
Documentos mais importantes com filtros inteligentes.
```python
documentos_importantes(
    numero_processo: str,
    categoria: str | None = None,  # "decisorio", "peticoes", "provas", "criminal"
    periodo_dias: int | None = None,  # Ultimos N dias
    min_chars: int = 500
) -> {"total": int, "documentos": [...]}
```

**Categorias disponíveis:**
- `decisorio`: Sentenças, acórdãos, decisões, despachos
- `peticoes`: Petições, inicial, contestação, recursos
- `provas`: Laudos, perícias, certidões, documentos
- `criminal`: Denúncias, inquéritos, defesas
```
