Foxy Analyzer

info O que faz

228 posts do Marcio analisados. Classifica hook_type, structure, cta_type, theme_slug. Gera relatórios de padrões. Base pro tier matrix.

hub Conexões

description Documentação (CLAUDE.md)

# CLAUDE.md — Contexto Permanente do Projeto
# F5 Têxtil | Foxy Analyzer
# Atualizado em: 2026-04-11

## 1. SOBRE O PROJETO

**Nome:** Foxy Analyzer
**Objetivo:** Analisa o conteúdo de posts do Instagram já coletados, descobre padrões estruturais (gancho, estrutura, CTA) e temáticos (taxonomia dinâmica por perfil) que correlacionam com alta performance, e gera relatórios de insights acionáveis — **agnóstico à fonte do roteiro**.
**Fase atual:** MVP — pré-implementação (scaffold a criar em 2026-04-11)
**Documentação completa:** [PRD.md](PRD.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [SCHEMA.md](SCHEMA.md) · [STATUS.md](STATUS.md)
**Plano de execução em fases:** [.claude/plan.md](.claude/plan.md)

## 2. STACK TECNOLÓGICO

- **Linguagem:** Python 3.12
- **Backend:** FastAPI 0.115 + Uvicorn 0.30 (padrão F5)
- **Scheduler:** APScheduler 3.11 dentro do container FastAPI (via lifespan)
- **LLM:** Anthropic SDK — modelos `claude-haiku-4-5` (default) e `claude-sonnet-4-5` (descoberta de taxonomia)
- **Banco:** PostgreSQL 16 + pgvector (reusa o banco do instagram-collector, schema novo `foxy_analyzer`)
- **Migrations:** Alembic
- **Frontend:** Jinja2 + HTMX + Tailwind CDN (2 telas simples: T1 jobs + T2 relatórios)
- **Auth:** HTTP Basic Auth (operador humano) + `X-API-Key` (Foxy IA futura/leitura) — ver [PRD §4.3 Auth Matrix](PRD.md)
- **HTTP client:** httpx async
- **Whisper:** faster-whisper (modelo `base`, CPU) — para fallback F1b
- **Deploy:** Docker Compose + Traefik (Let's Encrypt) → `https://foxy-analyzer.srv1440237.hstgr.cloud`
- **Envs:** `/root/shared.env` (montado como `env_file`)
- **Porta interna:** **8093** (nova entry no PADROES §2.7 port registry)

## 3. INVARIANTES — NÃO QUEBRAR NUNCA

Estas são as leis do sistema. Mudar qualquer uma delas exige decisão arquitetural explícita do Sandro.

### I1. Análise é agnóstica à fonte do script_raw

- O ClickUp é **atalho de custo** pro perfil do Marcio. **Nada mais** do ClickUp vai pra análise — nem `copywriter_score`, nem `viralizacao_cf`, nem `Abordagem`, nem `hook_type` inferido pelo copywriter.
- Os únicos campos que vêm do ClickUp são: `script_raw` (roteiro puro, sem a seção LEGENDA e sem metadados), `clickup_task_id` (pra auditoria) e `match_score` (pra confiança do matching).
- O pipeline de Fases 2a, 2b, 3 e 4 é **idêntico** pra posts que vieram do ClickUp e pra posts que vieram de Whisper/Vision. Se alguém um dia escrever lógica condicional tipo `if script_source == 'clickup' then X else Y`, é violação desta invariante.
- **Por quê:** o Foxy é produto comercializável pra **qualquer empresa**. Outras empresas não usam ClickUp do jeito que a F5 usa. Se a análise depender de metadados do ClickUp, o produto só serve pro Marcio.

### I2. Taxonomia temática é dinâmica por perfil

- Nenhuma lista fixa global de temas. Cada perfil tem seu próprio dicionário temático, descoberto via clustering do Claude nos próprios posts do perfil.
- A descoberta dispara automaticamente quando o perfil atinge ≥20 posts com `script_raw`.
- Re-descoberta é **manual** — operador aciona via `POST /taxonomy/rediscover/{profile_id}`, bumpa a versão da taxonomia. Posts classificados na versão antiga mantêm a referência.
- **Proibido** hardcodar tema no código ou no prompt. Se o Claude precisa de exemplo, o exemplo é um post do próprio perfil, não uma categoria inventada.

### I3. Features estruturais são taxonomia fechada global

- `hook_type`, `structure`, `cta_type` têm **lista fixa** de valores possíveis. Claude escolhe dentro da lista via tool use.
- Essa lista é **global** — igual pra todos os perfis. O conceito de "gancho polêmico" ou "estrutura head_fake" é universal.
- Valores atuais (ver [PRD §5 F2a](PRD.md)):
  - `hook_type ∈ {numerico, polemico, curiosidade, contraste, historico, autoridade, absurdo, humor}`
  - `structure ∈ {story_arc, numerada, polemica_justificativa, head_fake, caso_estudo, historico_linear, outro}`
  - `cta_type ∈ {follow, save, share, comment, link_bio, none}`
- Adicionar valor novo a essas listas exige decisão explícita do Sandro + migração do banco + re-classificação opcional.

### I4. F3 (backfill) é idempotente por default

- `POST /analyze/profile/{profile_id}` **sem** `?force=true` processa só o delta (posts sem análise completa).
- Chamar 2× seguidas sem posts novos no meio resulta em `progress.total=0` na segunda — zero trabalho duplicado.
- **Força total** via `?force=true` — apaga `post_analysis` do perfil e re-processa tudo. Operação cara, requer decisão humana deliberada.
- Mudança de versão de taxonomia conta como "análise incompleta" — posts classificados em v1 entram no delta quando v2 vira `active`.

### I5. Graceful degradation pra Anthropic API (PADROES §3.6)

- Toda chamada ao Claude passa por `app/services/anthropic_client.py` — ponto único de detecção de erros.
- Erro de crédito esgotado (`HTTP 429` com `insufficient_quota` / `400` com "credit") → job vai pra `paused_no_credit` + alerta Telegram + banner UI + campo no `/health`.
-