基于 SEC 10-K 文件的混合（BM25 + kNN）智能检索系统，运行于 OpenSearch，配备 Claude 工具使用代理，该代理可自主规划搜索并生成带有逐项引用和硬性数值溯源检查的回答。采用 FastAPI 接口 + TypeScript MCP 工具服务器。作为 Qdrant 管道的 OpenSearch 升级版构建；引用或放弃的溯源逻辑移植自我的 12 域出处包装器。
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层 | 文件 | 说明 | ||
连接器 |
| SEC 股票代码映射 + browse-edgar 回退（处理 successor-shell CIK 问题）、 | ||
解析 |
| 10-K 项目分割器：标题验证的标题、交叉引用过滤器、规范顺序 + 最长跨度选择（解决目录行问题） | ||
分块 |
| 尊重段落、令牌限制（450/60 重叠）、确定性块 ID `sha1(accession | item | idx)` |
嵌入 |
| 默认使用本地 Ollama 上的 | ||
索引 |
| OpenSearch 2.19 映射：英语分析器 BM25 字段 + | ||
检索 |
|
| ||
代理 |
| Claude（ | ||
API |
| FastAPI： | ||
MCP |
| TypeScript stdio MCP 服务器，暴露 | ||
评估 |
|
|
Related MCP server: edgar-mcp
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.pyMCP（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"}}}}通过环境变量配置：FS_OPENSEARCH_URL、FS_INDEX、FS_EMBED_BACKEND=ollama|openai、FS_AGENT_MODEL、FS_JUDGE_MODEL、SEC_USER_AGENT。代理/评判需要 ANTHROPIC_API_KEY（或 ~/.env）。
检索 — 参见 eval/retrieval_results.json：
设置 | 模式 | hit@1 | hit@5 | MRR@10 | 平均毫秒 |
未过滤 | bm25 | 0.571 | 0.857 | 0.686 | 5.7 |
未过滤 | knn | 0.679 | 0.857 | 0.759 | 29.7 |
未过滤 | hybrid | 0.679 | 0.857 | 0.759 | 37.9 |
股票代码过滤 | bm25 | 0.679 | 0.929 | 0.772 | 3.8 |
股票代码过滤 | knn | 0.679 | 0.893 | 0.779 | 26.6 |
股票代码过滤 | hybrid | 0.714 | 0.929 | 0.812 | 34.9 |
代理溯源 — 10 个分析师问题，claude-opus-5 代理 + claude-opus-5 评判（参见 eval/grounding_results.json）：
指标 | 值 |
数值溯源率（每个数字出现在引用的块中） | 10/10 = 1.00 |
LLM 评判结果：已溯源 / 部分溯源 / 未溯源 | 9 / 1 / 0 |
由引用块支持的主张平均比例 | 0.968 |
每个答案平均引用数 | 9.7 |
每个答案平均工具调用次数（代理选择的搜索/扩展） | 7.6 |
平均延迟 | 41 秒（简单 13 秒 → 多项目 59 秒） |
10 个问题运行的令牌数 | 563k 输入 / 23k 输出 |
那一个 partially_grounded（沃尔玛关税，0.87）是因为代理总结了引用块中更狭窄陈述的缓解措施 — 评判发现了这一点；这正是评判的用途。
智能 ≠ 固定 RAG。 模型选择公司、项目、模式和轮数；固定的 top-k 管道没有第二次机会。工具描述带有“何时使用”指南（项目映射、bm25 用于数字、无结果时扩大范围）。
溯源严格是故意的。 衍生四舍五入（“$99,779M” → “~$99.8B”）会被标记为未溯源；分析师希望看到文件中的原始数字。如果不同意，可以放宽容差。
10-K 结构怪癖是真实的，不是解析器错误：JPM 和 XOM 是“包装型”10-K，其 MD&A/财务数据位于书末的财务部分（在最后一个项目下标记）；NVIDIA 在项目 15 下提交报表。这些的评估标签仅为股票代码。后续工作是 F 页面检测（Consolidated Statements of … 标题）以重新标记为项目 8。
RRF 是客户端实现的 — 透明且易于推理；OpenSearch 的 hybrid 查询标准化管道是集群内的替代方案。尚无交叉编码器重排序器。
本次运行每家公司仅一份文件；--filings N 可提取前几年数据（财年过滤器已在映射和工具中）。
无认证、无速率限制、单节点 OpenSearch — 这是一个功能性垂直领域，而非部署方案。
This server cannot be deployed
Access SEC filings efficiently (10-K, 10-Q, etc), save time and tokens, and get cited answers.
Certified SEC EDGAR fact memory for AI agents with zero hallucination and filing provenance.
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
Primary-source SEC filing intelligence for AI agents, with exact evidence and provenance.
