FinEventa

# FinEventa 自主托管、自行密钥管理的金融事件API，适用于AI代理和量化交易员。多源数据摄入（KAP、美国证券交易委员会EDGAR、土耳其央行EVDS）、双语AI增强和一级MCP + Python SDK访问。 [](https://github.com/yigitbuyuktunaa/FinEventa/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org) --- ## 首先尝试 - 运行本地API并检查 `GET /v1/filings/latest`。 - 通过 `mcp-server/` 中的MCP服务器连接Claude Desktop或Cursor。 - 使用Python SDK或尝试Telegram/RAG配方流式传输新的申报。 --- ## 功能 FinEventa从多个来源摄取金融披露和宏观数据，并通过单个一致的REST API公开它们。目前的来源：美国证券交易委员会EDGAR的美国8-K申报；土耳其央行EVDS的土耳其宏观指标（CPI、政策利率、USD/TRY、FX储备）；KAP的BIST公司披露（仅限自主托管，默认禁用）。每个申报都使用源感知提示进行双语（TR/EN）摘要、情绪评分和类别的AI增强。构建为自主托管，直接插入交易系统、回测和AI代理。 --- ## 为什么自主托管 - **自行密钥管理。** 您提供Anthropic API密钥；所有AI增强都针对您的账户运行。可选添加TCMB EVDS和SEC用户代理凭证。 - **您的数据属于您。** 除非您指向外部数据库或监控服务，否则不会离开您的机器。 - **无供应商锁定。** 无SaaS账户，无计费，无使用限制，除非您在自己的速率限制设置中配置。 --- ## 架构概览 ```mermaid flowchart TB sec["SEC EDGAR<br/>8-K atom feed"] tcmb["TCMB EVDS<br/>macro indicators"] kap["KAP opt-in<br/>BIST disclosures"] sec --> adapters["Source Adapters<br/>env gated credentials"] tcmb --> adapters kap --> adapters adapters --> registry["Source Registry"] registry --> worker["Celery Worker + Beat<br/>at-least-once ingest"] worker --> db[("PostgreSQL 16<br/>filings, enrichments, companies")] worker --> ai["AI Enricher<br/>Claude Haiku primary<br/>Claude Sonnet failover"] ai --> db db --> api["FastAPI REST API v0.5.0<br/>/v1/filings + legacy KAP routes"] api --> sdk["Python SDK"] api --> mcp["MCP Server"] api --> ws["WebSocket Stream"] sdk --> users["AI agents, quant tools, recipes"] mcp --> users ws --> users ``` 工作线程和API共享相同的 `app/` 包（`infra/Dockerfile.worker` 与 `infra/Dockerfile.api`）。 --- ## 支持的来源 | 来源 | 状态 | 频率 | 备注 | |---|---|---|---| | 美国证券交易委员会EDGAR | 已上线 | 每分钟8-K原子订阅；每周公司刷新（周日04:00 UTC） | 设置 `SEC_EDGAR_ENABLED=true` 和 `SEC_USER_AGENT` | | 土耳其央行EVDS | 已上线 | 每小时宏观订阅 | 设置 `TCMB_EVDS_ENABLED=true` 和 `TCMB_EVDS_API_KEY` | | KAP | 已上线（默认禁用） | 30秒订阅 | 可选自主托管连接器。用户负责KAP、MKK和伊斯坦布尔证券交易所的数据使用、重新分发和许可要求。仅在您的使用被覆盖时启用。 | --- ## 快速入门 先决条件：Docker和Docker Compose。 ```bash git clone https://github.com/yigitbuyuktunaa/FinEventa.git cd FinEventa cp .env.example .env # 编辑.env：设置ANTHROPIC_API_KEY（AI增强所需）。 # 可选设置SEC_USER_AGENT和TCMB_EVDS_API_KEY，如果启用这些来源。 docker compose up -d # 运行数据库迁移 docker compose exec api alembic upgrade head # 创建您的第一个API密钥（打印一次；复制它） docker compose exec api python -m app.cli create-key --tier pro curl http://localhost:8000/v1/health curl -H "Authorization: Bearer <KEY>" http://localhost:8000/v1/filings/latest ``` 来源默认关闭。要开始摄入，请在 `.env` 中启用一个： ```bash # .env -- 美国证券交易委员会EDGAR（美国8-K申报）；根据SEC政策需要用户代理 SEC_EDGAR_ENABLED=true SEC_USER_AGENT="YourApp you@example.com" ``` 重新创建容器，以便加载新的 `.env` （普通的 `restart` 不会重新加载环境变量），然后播种公司列表： ```bash docker compose up -d --force-recreate api worker # 播种完整的公司列表，以便申报解析为股票代码 # （对于股票代码筛选和历史背景必填）： docker compose exec api python -m scripts.seed_sec_companies ``` 交互式API文档在 `http://localhost:8000/docs` 处可用，当 `APP_ENV` 不是 `production` 时。 --- ## API 接口 所有身份验证的端点都需要 `Authorization: Bearer <KEY>`。 | 端点 | 描述 | |---|---| | `GET /v1/filings` | 列出所有来源的申报，带有过滤器（来源、股票代码、申报类型、类别、日期范围、增强状态）。偏移分页，最大200条/页。 | | `GET /v1/filings/latest` | 最新申报，非分页，限制50条。默认情况下仅返回AI增强的行。 | | `GET /v1/filings/{id}` | 单个申报及其增强记录。如果未找到，则返回404。 | | `GET /v1/filings/{id}/summary` | 存储的AI摘要，用于处理后的申报。在增强过程中返回202 +重试-稍后。 | | `GET /v1/filings/{id}/sentiment` | 存储的AI情绪评分。与摘要相同的4状态响应模式。 | | `GET /v1/filings/{id}/classify` | 存储的AI类别分类。与摘要相同的4状态响应模式。 | | `GET /v1/filings/{id}/historical-context` | 类似过去申报的历史反应分布（基准利率，非预测）。仅适用于美国证券交易委员会EDGAR申报。 | | `GET /v1/filings/{id}/extraction` | AI提取的带有出处（证据片段每个字段）的类型化事实。与来源进行验证；不是预测。不可提取和待处理申报返回明确的状态而不是错误。 | | `GET /v1/kap/notifications` | 仅限KAP申报（向后兼容命名空间；仅返回`source="kap"`行）。 | | `GET /v1/kap/notifications/latest` | 最新KAP通知，非分页。 | | `GET /v1/kap/notifications/{id}` | 单个KAP通知，增强。非KAP ID返回404。 | | `WS /v1/stream/filings` | 新申报的实时流，可选`source`和`ticker`过滤器。通过`Authorization: Bearer`标头或`?api_key=`进行身份验证。 | | `GET /v1/health` | Postgres + Redis健康探测。公开，无需API密钥。 | `/v1/kap/notifications`命名空间保留用于向后兼容。它不会返回美国证券交易委员会EDGAR或TCMB数据。请为新集成使用`/v1/filings`。 完整的端点合约、查询参数、错误代码和示例有效载荷：[`docs/api-reference.md`](docs/api-reference.md) --- ## 身份验证 除 `/v1/health` 外，所有端点都需要 `Authorization` 头中的 API 密钥： ``` Authorization: Bearer fev_live_<key> ``` 密钥通过CLI创建（参见快速入门）。明文密钥打印一次，永不存储 - 只有bcrypt哈希被持久化。 ```bash # 创建密钥 docker compose exec api python -m app.cli create-key --tier pro # 可选标志： # --email admin@example.com （默认：admin@localhost） # --name my-agent （人类可读标签） # --env live|test （密钥前缀；默认：live） # --expires-days 90 （省略为非过期密钥） # 列出所有密钥（仅元数据，无哈希） docker compose exec api python -m app.cli list-keys ``` `--tier` 标志选择本地速率限制配置文件。在自主托管的单用户设置中，您可以选择 `pro` 或 `enterprise`；较小的配置文件存在于多租户部署、演示和测试中。有效配置文件是 `free` 、 `hobby` 、 `startup` 、 `pro` 和 `enterprise` 。在 `app/middleware/rate_limit.py` 中配置限制；请参阅 [`docs/configuration.md`](docs/configuration.md) 获取表格。 --- ## 连接 AI 代理（MCP） [`mcp-server/`](mcp-server/) 包提供了一个现成的MCP服务器，通过6种工具和一个分类资源将FinEventa暴露出来。在五分钟内将其连接到Claude Desktop或Cursor： ```bash pip install -e ./mcp-server # 然后将 "fineventa-mcp" 添加到您的 claude_desktop_config.json 或 ~/.cursor/mcp.json。 ``` 完整的设置指南、配置JSON块和工具参考： [`mcp-server/README.md`](mcp-server/README.md)。 --- ## Python SDK [`sdk/`](sdk/) 包提供 `fineventa-sdk`，一个类型化的客户端，包装REST API，提供同步和异步接口。 ```python from fineventa import FineventaClient with FineventaClient(api_url="http://localhost:8000", api_key="fev_live_<key>") as client: page = client.filings.list(ticker="AKBNK", limit=20) detail = client.filings.get(page.items[0].id) ``` `AsyncFineventaClient` 镜像相同的接口，用于 asyncio 代码。安装、异步使用和完整的 API 参考： [`sdk/README.md`](sdk/README.md)。 --- ## 实时流式传输（WebSocket） 连接一次并在新申报被摄入时接收它们，而不是轮询。交易机器人或AI代理订阅 `WS /v1/stream/filings`，带有可选的 `source` 和 `ticker` 过滤器，并获得每个匹配申报的JSON事件。 ```python import json from websockets.sync.client import connect url = "ws://localhost:8000/v1/stream/filings?source=kap&ticker=AKBNK" with connect(url, additional_headers={"Authorization": "Bearer fev_live_<key>"}) as ws: for raw in ws: event = json.loads(raw) if event["type"] == "filing": print(event["data"]["subject"]) ``` 事件类型：`connected`（初始确认和活动过滤器）、`filing`（新申报，负载与 `GET /v1/filings` 行相同）和 `heartbeat`（周期性保持活动）。在 `external_id` 上至少一次交付；如果需要精确一次，请在客户端进行去重。如果浏览器客户端无法设置标头，可以将密钥作为 `?api_key=` 传递（请注意，它可能会出现在反向代理日志中；请优先使用标头）。 在底层，摄入工作线程将每个新申报发布到Redis pub/sub，API进程将分发到所有订阅的连接。 --- ## 我们如何评估我们的AI 大多数项目提供一个“AI情绪”字段，但从未说明它是否具有任何意义。我们进行了测量。 [`fineventa-eval/`](fineventa-eval/) 是一个独立的事件研究管道，提出一个诚实的问题： > 仅根据 **申报文本** 形成的LLM情绪是否能预测股票的短期市场反应？ 它对约500个标普100美国证券交易委员会8-K申报（仅文本，严格无泄漏）进行评分，计算每个申报周围的实现异常回报，并比较两者。头条发现，在纠正一个事件窗口错误后，该错误最初导致了一个虚假的负结果： **没有可靠的短期预测关系** （斯皮尔曼ρ=+0.03，p=0.53）。换句话说，该模型生成一个文本基调分数，但该分数不能可靠地预测下一个交易日的价格变动。这就是为什么API文档将 `sentiment_score` 记录为“文本基调，不是价格预测或投资建议”，而该发现现在用数据支持该措辞。 该管道是可重现的，并且在提交的记录输出上运行，无需任何API调用和网络，因此未来的提示或模型更改不会静默破坏结果。完整的 方法论和局限性： [`docs/eval-methodology.md`](docs/eval-methodology.md) 和 [`fineventa-eval/reports/SONUC_RAPORU.md`](fineventa-eval/reports/SONUC_RAPORU.md)。 相同的基准理念现在在API中生效： `GET /v1/filings/{id}/historical-context` 返回具有相同事件类型的历史反应分布，以便调用者可以查看通常发生的情况 - 而对接下来会发生什么没有任何声明。 --- ## 即将推出 - 历史回填脚本 - 在首次运行时播种数月的美国证券交易委员会EDGAR和TCMB数据。 --- ## 配置 所有设置都是环境变量。复制 `.env.example` 到 `.env` 并编辑。完整的参考资料： [`docs/configuration.md`](docs/configuration.md)。 基本变量： ```bash # 必需 - 实例将无法启动而没有这些 DATABASE_URL=postgresql+asyncpg://fineventa:fineventa@localhost:5432/fineventa DATABASE_URL_SYNC=postgresql+psycopg2://fineventa:fineventa@localhost:5432/fineventa REDIS_URL=redis://localhost:6379/0 APP_SECRET_KEY=<output of: openssl rand -hex 32> # AI增强所需 ANTHROPIC_API_KEY=sk-ant-... # 源适配器（默认为关闭） SEC_EDGAR_ENABLED=false SEC_USER_AGENT= # "AppName contact@email.com" TCMB_EVDS_ENABLED=false TCMB_EVDS_API_KEY= KAP_SCRAPING_ENABLED=false ``` 本地 `docker-compose.yml` 自动连接 `DATABASE_URL` 和 `REDIS_URL` 到捆绑的Postgres和Redis容器，因此您只需要设置 `APP_SECRET_KEY` 和 `ANTHROPIC_API_KEY` 即可获得一个可用的本地实例。 --- ## 开发 ```bash # 运行整个堆栈 docker compose up -d # 测试 cd api export DATABASE_URL=postgresql+asyncpg://finevent:finevent@localhost:5432/finevent export REDIS_URL=redis://localhost:6379/0 export APP_SECRET_KEY=test-secret-key-with-at-least-32-bytes pytest tests/unit/ # fast, external services mocked pytest tests/integration/ # requires Docker stack # lint and type-check ruff check . mypy app/ # 烟雾测试（验证健康状况、身份验证、速率限制标头、多源查询） bash api/scripts/smoke.sh ``` 这是一个独立的Python包和可运行示例的多重仓库。主要可安装的包是 `api/` 、 `mcp-server/` 和 `sdk/` ； `recipes/` 和 `fineventa-eval/` 有自己的依赖文件。CI测试每个表面与匹配的环境。运行包的工具从其自己的目录安装后： ```bash cd mcp-server && pip install -e ".[dev]" && mypy fineventa_mcp && pytest cd sdk && pip install -e ".[dev]" && mypy fineventa && pytest ``` 在没有安装该包的venv中运行 `mypy`/`pytest` 将报告虚假的导入或未类型装饰的错误；请先安装该包。 参见 [`docs/local-development.md`](docs/local-development.md) 了解完整的本地设置指南，包括迁移、种子数据、工作线程行为和故障排除。 --- ## 文档索引 | 文件 | 内容 | |---|---| | [`docs/architecture.md`](docs/architecture.md) | 系统架构、多源摄入模式、Celery beat调度、AI流程、DB模式注释 | | [`docs/api-reference.md`](docs/api-reference.md) | 端点合约、查询参数、错误代码、分页、示例有效载荷 | | [`docs/configuration.md`](docs/configuration.md) | 所有环境变量、每个源的启用标志、生产启动验证器 | | [`docs/local-development.md`](docs/local-development.md) | 本地设置、迁移、种子数据、工作线程、故障排除 | | [`docs/operations-runbook.md`](docs/operations-runbook.md) | 部署、Celery beat任务、源启用/禁用、AI模型交换、事件响应 | | [`docs/eval-methodology.md`](docs/eval-methodology.md) | 我们如何评估AI增强（事件研究方法论） | 有关路线图和项目方向，请参见 [`ROADMAP.md`](ROADMAP.md)。项目历史记录在提交和拉取请求日志中。 --- ## 贡献 欢迎贡献。参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解开发设置、测试/ lint命令和PR约定。安全报告：参见 [`SECURITY.md`](SECURITY.md)。 --- ## 许可证 MIT。参见 [LICENSE](LICENSE)。 **数据免责声明：** 此软件产生的数据和AI生成的内容仅用于信息目的。API生成的任何内容不构成投资建议。 KAP支持作为可选的自主连接器提供，默认禁用。用户负责遵守KAP、MKK和伊斯坦布尔证券交易所的数据使用、重新分发和许可要求。对于生产或商业分发，请使用官方KAP数据分发服务并获得所需的协议。