feat: complete GenIE web app with 3-agent pipeline, encrypted key vault and real-time monitor

.env.example

@@ -6,20 +6,37 @@ LOG_LEVEL=DEBUG
 API_HOST=0.0.0.0
 API_PORT=8000
 
-# LLM Providers (Google é o provider padrão)
-GOOGLE_API_KEY=your-google-ai-key-here
-OPENAI_API_KEY=sk-your-key-here
-ANTHROPIC_API_KEY=sk-ant-your-key-here
+# Security
+# Chave-mestre para cifrar API keys em repouso (AES-256-GCM).
+# Gere com: openssl rand -base64 32
+# Se vazio, o GenIE gera e guarda em ./data/.master_key (modo 0600).
+GENIE_MASTER_KEY=
 
-# Provider ativo e modelo (padrão: google / gemini-1.5-pro)
+# Origens permitidas para CORS (separadas por vírgula)
+CORS_ORIGINS=http://localhost:8000,http://127.0.0.1:8000,http://localhost:5173
+
+# Raízes extras do filesystem que o conector pode ler/gravar
+# (além do home do usuário e do diretório do projeto). Separe com ":".
+# ALLOWED_FS_ROOTS=/srv/dados:/mnt/exames
+
+# Limites de upload
+MAX_UPLOAD_MB=50
+MAX_FILES_PER_UPLOAD=20
+
+# LLM Providers — opcional: prefira cadastrar pela interface web,
+# que armazena as chaves cifradas. Estas variáveis são fallback.
+# GOOGLE_API_KEY=
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# Provider ativo e modelo padrão para o endpoint /extract (legado)
 LLM_PROVIDER=google
-# LLM_MODEL=gemini-1.5-flash   # descomente para sobrescrever o modelo padrão
+# LLM_MODEL=gemini-2.5-flash   # descomente para sobrescrever o modelo padrão
 
 # Storage and Data
 DATA_DIR=./data
 SEARCH_LIBRARY_PATH=./data/search_library/patterns.json
 CONFIG_DIR=./data/configs
 UPLOADS_DIR=./data/uploads
-
-# Optional: Database (Phase 2+)
-# DATABASE_URL=postgresql://user:password@localhost/genie_db
+OUTPUTS_DIR=./data/outputs
+DB_PATH=./data/genie.db

.gitignore

@@ -132,7 +132,7 @@ dmypy.json
 
 # Project-specific
 logs/
-data/uploads/*
-data/search_library/patterns.json
-data/search_library/patterns.db
+# Runtime data: NEVER commit (contains master key and encrypted secrets)
+data/
+
 *.db

README.md

@@ -1,160 +1,148 @@
-# GENIE - Generic Extractor of Information Engine
+# GenIE — Generic Extractor of Information Engine
 
-A Python framework for intelligent data extraction using LLMs.
+Framework Python para extração inteligente de dados com LLMs, orquestrado por
+três agentes cooperativos e operável por uma interface web completa.
 
-## Quick Start
+```
+Conector (I/O)  →  Localizador (extração via LLM)  →  Organizador (formato)  →  Conector (entrega)
+```
 
-### Prerequisites
-- Python 3.11+
-- Poetry (or pip)
+## Interface Web
 
-### Installation
+A SPA embutida (servida pelo próprio FastAPI em `http://localhost:8000`) permite:
 
-**Using Poetry (recommended):**
-```bash
-poetry install
-poetry shell
-```
+1. **Modelo de IA** — escolher Gemini / GPT / Claude e cadastrar a API Key
+   (cifrada com AES-256-GCM no servidor; nunca volta ao navegador).
+2. **Entrada** — URL, pasta local, banco de dados, API REST ou upload de arquivos
+   (PDF, CSV, XLSX, JSON, TXT, HTML…).
+3. **O que extrair** — instrução em linguagem natural para o Localizador.
+4. **Saída** — webhook, pasta local, banco SQLite, API REST (ex.: TabEx) ou download.
+5. **Formato da saída** — instrução em linguagem natural para o Organizador.
 
-**Using pip:**
-```bash
-pip install -r requirements.txt
-```
+O monitor à direita mostra os 3 agentes com progresso, log em tempo real (SSE)
+e a prévia tabular/JSON do resultado, com links de download assinados.
 
-### Configuration
+## Quick Start
 
-1. Copy `.env.example` to `.env`:
 ```bash
-cp .env.example .env
-```
-
-2. Add your API keys to `.env`:
-```
-ANTHROPIC_API_KEY=sk-ant-your-key-here
-OPENAI_API_KEY=sk-your-key-here
-```
+# 1. Instalar dependências (Python 3.11+)
+pip install -r requirements.txt
 
-### Running the Server
+# 2. (Opcional) Configurar ambiente
+cp .env.example .env
+# Gere a chave-mestre para produção: openssl rand -base64 32 → GENIE_MASTER_KEY
+# Em desenvolvimento o GenIE gera uma automaticamente em ./data/.master_key
 
-```bash
-uvicorn spec.main:app --reload --port 8000
+# 3. Rodar
+uvicorn spec.main:app --port 8000
 ```
 
-The API will be available at `http://localhost:8000`
+Abra **http://localhost:8000** — cadastre a API Key do provedor (ex.: Google
+Gemini), envie um arquivo, descreva o que extrair e clique em *Enviar requisição*.
 
-- Docs: http://localhost:8000/docs
-- ReDoc: http://localhost:8000/redoc
+- Web app: http://localhost:8000
+- Docs da API: http://localhost:8000/docs
 - Health: http://localhost:8000/api/v1/health
 
-## Project Structure
+## Segurança
+
+- **API Keys nunca atravessam o navegador**: são enviadas uma única vez,
+  cifradas com **AES-256-GCM** (chave-mestre via `GENIE_MASTER_KEY` ou arquivo
+  `./data/.master_key`, modo 0600) e armazenadas em SQLite. Nenhum endpoint
+  devolve a chave — apenas `has_key` e um preview mascarado.
+- **Credenciais transitórias** (senha de banco, token de API por execução)
+  ficam apenas em memória e nunca aparecem em logs, eventos SSE ou resultados.
+- **Filesystem com allowlist**: o conector só lê/grava sob o home do usuário,
+  o diretório do projeto e raízes extras de `ALLOWED_FS_ROOTS` (anti path traversal).
+- **Uploads**: nomes sanitizados, allowlist de extensões, limites de tamanho
+  (`MAX_UPLOAD_MB`) e quantidade (`MAX_FILES_PER_UPLOAD`).
+- **Downloads assinados**: links HMAC-SHA256 com validade de 15 minutos.
+- **CORS** restrito a uma allowlist explícita (`CORS_ORIGINS`).
+
+## API da aplicação web
+
+| Método | Rota | Descrição |
+|---|---|---|
+| `GET` | `/api/v1/models` | Catálogo de modelos + `has_key` por provedor |
+| `GET` | `/api/v1/keys` | Provedores com chave (apenas preview mascarado) |
+| `POST` | `/api/v1/keys` | `{provider, key, validate_key}` → valida e cifra |
+| `DELETE` | `/api/v1/keys/{provider}` | Remove a chave |
+| `POST` | `/api/v1/uploads` | multipart → `{upload_id, files}` |
+| `POST` | `/api/v1/runs` | Cria execução → `{job_id}` |
+| `GET` | `/api/v1/runs/{id}` | Estado atual + resultado |
+| `GET` | `/api/v1/runs/{id}/events` | SSE com eventos dos agentes (suporta `Last-Event-ID`) |
+| `POST` | `/api/v1/runs/{id}/cancel` | Interrompe a execução |
+| `GET` | `/api/v1/downloads/{id}/{arquivo}` | Artefatos com link assinado |
+
+Endpoints do framework (extração programática): `POST /api/v1/extract`,
+`GET/POST /api/v1/providers*` — ver `/docs`.
+
+### Exemplo de execução via API
 
-```
-spec/
-├── api/                    # REST API endpoints
-│   └── v1/
-│       ├── endpoints/      # Endpoint implementations
-│       ├── router.py       # Route aggregator
-│       └── dependencies.py # Dependency injection
-├── core/                   # Core infrastructure
-│   ├── config.py          # Settings management
-│   ├── exceptions.py      # Custom exceptions
-│   ├── logging_config.py  # Logging setup
-│   └── security.py        # Security utilities
-├── models/                 # Pydantic data models
-├── extraction/             # Extraction engine
-│   ├── engine.py          # Main orchestrator
-│   ├── llm/               # LLM providers
-│   ├── parsers/           # Content parsers
-│   └── layout/            # Layout fingerprinting
-├── search_library/        # Pattern storage
-├── output/                # Output management
-└── main.py                # FastAPI entry point
+```bash
+# Upload
+UP=$(curl -s -F "files=@exames.pdf" localhost:8000/api/v1/uploads | jq -r .upload_id)
+
+# Run
+curl -s -X POST localhost:8000/api/v1/runs -H 'Content-Type: application/json' -d "{
+  \"model_id\": \"gemini-2.5-flash\",
+  \"input\":  {\"type\": \"upload\", \"upload_id\": \"$UP\"},
+  \"prompt\": \"Extraia Data, Nome do Exame, Resultado e Valor de Referência\",
+  \"output\": {\"type\": \"download\"},
+  \"format\": \"Um registro por exame com data ISO-8601\"
+}"
 ```
 
-## API Endpoints
+## Conectores
 
-### Health Check
-```http
-GET /api/v1/health
-```
+| Tipo | Entrada | Saída |
+|---|---|---|
+| URL | HTML/PDF/JSON públicos; links de arquivo do Google Drive | POST webhook |
+| Pasta local | varredura recursiva (allowlist de raízes) | `output.json` + `output.csv` |
+| Banco de dados | SQLite nativo; Postgres/MySQL via SQLAlchemy opcional | SQLite (cria/evolui tabela) |
+| API REST | GET com Bearer token | POST com Bearer (lote ou por registro) |
+| Upload / Download | multipart seguro | links assinados (15 min) |
+| Texto inline (`text`) | conteúdo enviado no próprio POST — ideal para integração plugin | — |
 
-### Extract Data
-```http
-POST /api/v1/extract
-Content-Type: application/json
-
-{
-    "config_id": "config_001",
-    "source": {
-        "type": "text",
-        "content": "Document content here..."
-    },
-    "force_llm": false,
-    "options": {
-        "auto_create_patterns": true
-    }
-}
-```
+## Integração TabEx
 
-## Testing
+O GenIE opera de forma independente e como serviço para outros apps.
+Para entregar dados ao TabEx, use saída **API REST** apontando para o endpoint
+do TabEx com o token de acesso, e descreva o body esperado no campo
+*Formato da saída* — o Organizador monta os payloads e o Conector entrega.
 
-Run all tests:
-```bash
-pytest
-```
+## Estrutura
 
-Run specific test file:
-```bash
-pytest tests/unit/test_models.py -v
 ```
-
-Run with coverage:
-```bash
-pytest --cov=spec --cov-report=html
+spec/
+├── api/v1/endpoints/   # extract, providers, models, keys, uploads, runs, downloads
+├── core/               # config, exceptions, security (AES-256-GCM), logging
+├── extraction/
+│   ├── agents/         # connector, locator, organizer, orchestrator
+│   ├── llm/            # factory + providers (Google, OpenAI, Anthropic)
+│   ├── parsers/        # pdf, text, content (csv/xlsx/html/json)
+│   └── layout/         # fingerprint
+├── models/             # Pydantic v2 (extraction, webapp, …)
+├── search_library/     # padrões reutilizáveis (JSON)
+├── webapp/             # catálogo de modelos + gestor de jobs/SSE
+└── web/                # SPA (index.html, styles.css, app.js)
 ```
 
-## Development
-
-### Code Style
-- **Formatter:** Black (88 chars line length)
-- **Linter:** Ruff
-- **Type Checker:** Mypy
-
-Format code:
-```bash
-black spec/ tests/
-ruff check . --fix
-```
+## Testes
 
-Type checking:
 ```bash
-mypy spec/
+pytest                      # suíte completa
+pytest tests/unit -v        # unidade
+pytest --cov=spec           # cobertura
 ```
 
-## Documentation
+## Documentação
 
-- [Architecture Guide](./docs/guides/GENIE-ARCHITECTURE.md)
-- [Phase 1 Plan](./docs/guides/PHASE-1-PLAN.md)
-- [Specification v2](./docs/guides/GENIE-SPEC-v2.md)
+- **[Manual de uso](./docs/MANUAL.md)** — interface web, API REST (plugin) e integração TabEx
+- [Arquitetura](./docs/guides/GENIE-ARCHITECTURE.md)
+- [Especificação v2](./docs/guides/GENIE-SPEC-v2.md)
+- [Exemplos](./docs/examples/GENIE-EXAMPLES.md)
 
-## License
+## Licença
 
 MIT
-
-## Project Status
-
-**Phase 1: MVP Core** - In Development
-
-- ✓ Project setup and tooling
-- ✓ Core infrastructure
-- ✓ Pydantic models
-- ✓ LLM provider interface (Anthropic)
-- ✓ Text and PDF parsers
-- ✓ Layout fingerprinting
-- ✓ Search library (JSON storage)
-- ✓ Extraction engine
-- ✓ REST API endpoints
-- ⏳ Comprehensive testing
-- ⏳ End-to-end validation
-
-See [PHASE-1-PLAN.md](./docs/guides/PHASE-1-PLAN.md) for detailed roadmap.