filings-search

Híbrido (BM25 + kNN) recuperación basada en agentes sobre presentaciones 10-K de la SEC, en OpenSearch, con un agente de uso de herramientas de Claude que planifica sus propias búsquedas y responde con citas por afirmación y una verificación estricta de fundamentación numérica. Interfaz FastAPI + servidor de herramientas MCP en TypeScript. Construido como el sucesor de OpenSearch de mi pipeline Qdrant; la fundamentación de citar o abstenerse está adaptada de mi envoltorio de procedencia de 12 dominios.

EDGAR ──► connector ──► section splitter ──► chunker ──► embeddings ──► OpenSearch (BM25 + HNSW kNN)
(SEC API)  (ticker→CIK,   (Item 1/1A/1C/7/8…)  (450 tok,    (nomic-embed-text            │
            10-K list,     order-constrained,    60 overlap)  local via Ollama, or        │
            iXBRL strip)   x-ref filtered)                     OpenAI)                     ▼
                                                                          hybrid search (RRF) + filters
                                                                                       │
                                                       ┌───────────────────────────────┼─────────────────────┐
                                                       ▼                               ▼                     ▼
                                              FastAPI /search /ask           TS MCP server            eval harness
                                              /chunk /companies         (search_filings, ask_filings)  (P@k/MRR, LLM-judge)
                                                       ▲
                                              Claude agent (tool loop):
                                              resolve_company → search_filings (item/ticker/FY filters, hybrid|bm25|knn)
                                              → expand_chunk → answer with [c:chunk_id] cites → numeric grounding check

Qué incluye

Ejecútalo

docker compose up -d                       # OpenSearch 2.19 (knn + neural plugins), :9200
ollama pull nomic-embed-text               # local embeddings
python3.12 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
./.venv/bin/python ingest.py --recreate AAPL MSFT NVDA JPM XOM WMT TSLA JNJ   # ~2 min, 8 filings, ~2.1k chunks
./run_api.sh                               # FastAPI on :8801
./.venv/bin/python -m filings_search.agent "What does NVIDIA disclose about export controls to China?"
./.venv/bin/python eval/run_retrieval_eval.py
./.venv/bin/python eval/run_grounding_eval.py

MCP (Claude Desktop / Claude Code / Cursor):

{"mcpServers": {"filings-search": {"command": "node", "args": ["/ABS/PATH/filings-search/mcp/dist/server.js"],
                                    "env": {"FILINGS_API_URL": "http://127.0.0.1:8801"}}}}

Configuración mediante variables de entorno: FS_OPENSEARCH_URL, FS_INDEX, FS_EMBED_BACKEND=ollama|openai, FS_AGENT_MODEL, FS_JUDGE_MODEL, SEC_USER_AGENT. ANTHROPIC_API_KEY (o ~/.env) para el agente/juez.

Resultados (2026-08-18, 8 presentaciones / 2.101 fragmentos, 28 consultas etiquetadas)

Recuperación — ver eval/retrieval_results.json:

Fundamentación del agente — 10 preguntas de analistas, agente claude-opus-5 + juez claude-opus-5 (ver eval/grounding_results.json):

El único partially_grounded (aranceles de Walmart, 0,87) fue el agente resumiendo una mitigación que el fragmento citado establece de manera más restrictiva — el juez lo detectó; para eso está el juez.

Notas de diseño / limitaciones honestas

• Agéntico ≠ RAG fijo. El modelo elige empresa, Ítem, modo y cuántas rondas; un pipeline fijo de top-k no tiene segunda oportunidad. Las descripciones de las herramientas contienen la guía de 'cuándo usar' (mapa de ítems, bm25 para cifras, ampliar si está vacío).

• La fundamentación es estricta a propósito. Un redondeo derivado ("$99.779M" → "~$99.8B") se marca como no fundamentado; los analistas quieren la cifra tal como se presentó. Afloje con una tolerancia si no está de acuerdo.

• Las peculiaridades de la estructura 10-K son reales, no errores del analizador: JPM y XOM son 10-K 'envoltorio' cuyos MD&A/estados financieros se encuentran en una Sección Financiera al final del libro (etiquetada bajo el último Ítem); NVIDIA presenta estados bajo el Ítem 15. Las etiquetas de evaluación para esos son solo ticker. Un seguimiento es la detección de páginas F (encabezados Consolidated Statements of …) para reetiquetar como Ítem 8.

• RRF es del lado del cliente — transparente y fácil de razonar; el pipeline de normalización de consultas hybrid de OpenSearch es la alternativa dentro del clúster. Aún no hay re-ranker de codificador cruzado.

• Una sola presentación por empresa en esta ejecución; --filings N obtiene años anteriores (el filtro fiscal_year ya está en el mapeo y las herramientas).

• Sin autenticación, sin límites de tasa, OpenSearch de un solo nodo — esto es un vertical funcional, no un despliegue.