feat(media-routing): implement 007 media article routing, runtime architecture diagram and update graphify knowledge graph

2026-08-25 01:20:49 -03:00
parent d2d1aad001
commit 47b5215541
45 changed files with 290741 additions and 68310 deletions
@@ -0,0 +1,68 @@
+# Quickstart & Validation Guide: Classificação e Roteamento de Mídia
+
+**Feature**: `007-media-article-routing`  
+**Date**: 2026-08-24  
+**Status**: Completed  
+
+---
+
+## 1. Configuração de Variáveis de Ambiente (Configuração Externa)
+
+As credenciais e endpoints dos provedores devem ser configurados no ambiente de execução:
+
+```bash
+# Provedor Primário (Ollama Local)
+OLLAMA_ENDPOINT="http://localhost:11434"
+OLLAMA_MODEL="qwen3.5:2b"
+OLLAMA_TIMEOUT="10"
+
+# 1º Fallback (Groq)
+GROQ_ENDPOINT="https://api.groq.com/openai/v1/chat/completions"
+GROQ_API_KEY="gsk_..."
+GROQ_MODEL="openai/gpt-oss-20b"
+GROQ_TIMEOUT="15"
+
+# 2º Fallback (OmniRoute)
+OMNIROUTE_ENDPOINT="https://<seu-endpoint-omniroute>/v1/chat/completions"
+OMNIROUTE_API_KEY="omni_..."
+OMNIROUTE_MODEL="cgpt-web/gpt-5.5"
+OMNIROUTE_TIMEOUT="20"
+```
+
+---
+
+## 2. Execução dos Testes Automatizados (CI)
+
+A suíte de testes executa 100% offline em ambiente de CI via simulações controladas:
+
+```bash
+# Executar testes unitários e de integração da feature
+pytest tests/unit/test_media_classifier.py tests/integration/test_media_routing.py -v
+
+# Validar conformidade com a política Zero-Regex
+python tests/scripts/check_zero_regex.py
+```
+
+---
+
+## 3. Cenários de Validação Manual / E2E
+
+### Cenário 1: Execução Padrão com Arquivo de Notícias
+```bash
+python scripts/extract_article_contents.py -i out/river_plate.json
+```
+**Resultados esperados**:
+- `out/river_plate_extracted.json` gerado contendo artigos textuais e contadores atualizados;
+- `out/river_plate_media.json` gerado contendo o envelope `{ "articles": [ ... ] }` com as mídias identificadas (ou `{"articles": []}` caso nenhuma mídia seja classificada no lote);
+- Logs no stderr exibindo as 11 métricas operacionais obrigatórias.
+
+### Cenário 2: Execução com Caminho de Saída Customizado (`-o/--output`)
+```bash
+python scripts/extract_article_contents.py \
+  -i out/river_plate.json \
+  -o out/processados/resultado_custom.json \
+  -l 5
+```
+**Resultados esperados**:
+- Saída textual em `out/processados/resultado_custom.json`;
+- Saída de mídia em `out/processados/resultado_custom_media.json` (gerado obrigatoriamente, contendo as mídias ou `{"articles": []}`).