fatebridge 0.1.0__tar.gz

fatebridge-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 thomas-yanxin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fatebridge-0.1.0/NOTICE

@@ -0,0 +1,42 @@
+FateBridge
+Copyright (c) FateBridge contributors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+------------------------------------------------------------------------------
+Third-party components
+------------------------------------------------------------------------------
+
+kintaiyi (太乙神数 / Tai Yi divination engine)
+  Source: https://github.com/kentang2017/kintaiyi
+  Author: kentang2017
+  License: MIT
+
+  fatebridge/core/metaphysics/taiyi.py contains a pure-Python port of the
+  太乙統宗 人道命法 (life-chart) algorithm and its lookup tables, transcribed
+  from kintaiyi's kintaiyi.py and config.py. FateBridge does not depend on
+  kintaiyi at runtime; only the algorithm and constant tables were vendored,
+  and calendar / 节气 inputs are produced by FateBridge's own swisseph-backed
+  engine. The MIT license text below is retained as required.
+
+  MIT License
+
+  Copyright (c) 2023-2026 kentang2017
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.

fatebridge-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: fatebridge
+Version: 0.1.0
+Summary: FateBridge - A Model Context Protocol (MCP) server bridging ancient Chinese fortune telling wisdom with modern technology
+Author-email: thomas-yanxin <yx20001210@163.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/thomas-yanxin/FateBridge
+Project-URL: Repository, https://github.com/thomas-yanxin/FateBridge
+Project-URL: Issues, https://github.com/thomas-yanxin/FateBridge/issues
+Project-URL: Changelog, https://github.com/thomas-yanxin/FateBridge/blob/master/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastapi>=0.110.1
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: kerykeion<6,>=5.5.0
+Requires-Dist: lunardate>=0.2.2
+Requires-Dist: packaging>=23.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyswisseph>=2.10.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pytz>=2024.1
+Requires-Dist: uvicorn>=0.27.0
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.20.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Dynamic: license-file
+
+# FateBridge
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
+[![CI](https://github.com/thomas-yanxin/FateBridge/actions/workflows/ci.yml/badge.svg)](https://github.com/thomas-yanxin/FateBridge/actions/workflows/ci.yml)
+
+FateBridge 是一个可在本地运行的 Python 后端能力库，把八字、紫微、传统占术、西方占星与风水规则组织成可调用、可复算、带来源的计算接口。应用通过 REST 接入，Agent 通过 MCP 调用，脚本通过 CLI 运行；当前版本为 **0.1.0**。
+
+当前提供 **86 个业务 REST 路由**、**87 个 FastMCP 工具**；中央目录含 88 条记录，CLI 可执行其中87条。三端共用领域计算，名称和请求形态见 [三端能力边界](docs/api-reference.md#24-三端能力边界)。完整 **13 family / 87 工具** 清单见 [算法覆盖矩阵](docs/algorithm-coverage.md)。
+
+## 从这里开始
+
+| 你的目标 | 入口 |
+| --- | --- |
+| 在 Codex 中直接咨询 | [Codex 使用指南](docs/codex-guide.md) |
+| 安装并发起第一次调用 | [快速入门](docs/getting-started.md) |
+| 接入应用或 Agent | [接入指南](docs/agent-guide.md) · [API 参考](docs/api-reference.md) |
+| 按问题选择工具或场景技能 | [场景路由](docs/scenario-routing.md) · [9 个 Onda 技能](skills/README.md) |
+| 修改代码、规则或文档 | [开发指南](docs/development-guide.md) · [贡献指南](CONTRIBUTING.md) |
+| 升级旧版调用或排查故障 | [迁移指南](docs/migration.md) · [故障排除](docs/troubleshooting.md) |
+
+完整导航和各文档职责见 [文档中心](docs/README.md)。
+
+## 能力概览
+
+| 领域 | 计算内容 |
+| --- | --- |
+| 八字与双人关系 | 命盘，事业、财运、婚姻等九项专题，双人配合、宿曜相性 |
+| 时运与历法 | 大运、流年、流月、流日、流时、节气与农历 |
+| 中国术数与占卜 | 紫微、奇门、六壬、太乙、金口诀、梅花、六爻及本地技法 |
+| 西方占星 | 本命与流派盘、关系盘、返照、行运、主限及时主等推运 |
+| 风水空间 | 八宅、金锁基础砂水、年星、玄空历史宅盘，以及按事实分层的布局与物件审查 |
+
+风水的输入、来源与适用范围见 [家居风水](docs/fengshui.md)；各工具精度、依赖与未覆盖项目见 [算法覆盖](docs/algorithm-coverage.md)。
+
+## 快速开始
+
+需要 Python 3.10+，当前 CI 覆盖 3.10–3.13。通过 PyPI 安装：
+
+```bash
+python -m pip install fatebridge==0.1.0
+```
+
+源码开发安装需要 Git，以下为 macOS / Linux 示例；Windows 和全部配置见 [快速入门](docs/getting-started.md#安装)。
+
+```bash
+git clone https://github.com/thomas-yanxin/FateBridge.git
+cd FateBridge
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install -e .
+```
+
+### CLI：安装后直接调用
+
+CLI 不需要启动服务。以下命令使用虚构体验资料：
+
+```bash
+fatebridge describe bazi_birth --detail input
+fatebridge bazi_birth --birth-year 1990 --birth-month 5 --birth-day 15   --birth-hour 10 --birth-minute 30 --gender 男 --birth-place 北京   --birth-timezone Asia/Shanghai --fields bazi_birth.day_master --strict-fields
+```
+
+### REST：启动后发起请求
+
+```bash
+API_HOST=127.0.0.1 fatebridge-api
+```
+
+另开一个终端执行：
+
+```bash
+curl http://localhost:8010/health
+curl -X POST http://localhost:8010/api/cn/bazi/birth   -H 'Content-Type: application/json'   -d '{"birth_year":1990,"birth_month":5,"birth_day":15,"birth_hour":10,
+       "birth_minute":30,"gender":"男","birth_place":"北京",
+       "birth_timezone":"Asia/Shanghai","use_true_solar_time":true}'
+```
+
+交互文档位于 `http://localhost:8010/docs`。独立命盘数据位于 `bazi_birth`；配置了 `FATEBRIDGE_API_KEYS` 时，业务请求还需密钥头。监听地址默认 `0.0.0.0`，本机使用以上命令限制到 `127.0.0.1`；配置与部署说明见 [快速入门](docs/getting-started.md#配置环境变量) 和 [安全策略](SECURITY.md)。
+
+### MCP：交给 host 启动
+
+MCP 使用 stdio。先运行 `fatebridge doctor --mcp --scenario onda-shiye`，再按返回的绝对路径命令注册。完整 Codex 配置、虚构对话和连接检查见 [Codex 使用指南](docs/codex-guide.md)。
+
+## 调用与结果
+
+- 用 `fatebridge discover --family bazi` 或 REST `/api/tools?detail=summary&family=bazi` 筛选能力，再读取所选工具契约。已知 Schema 时可直接调用。
+- 成功结果默认带 `run_metadata`，记录工具、时间和计算口径；复现还需保存原输入与运行环境。
+- 用 `fields` 控制响应体积，`strict_fields=true` 拒绝无效路径。MCP 默认预算 8192 字符，超限后通过 `result_delivery` 读取同一次结果。
+- **需要完整 JSON 或全部时间线时，首次调用 `fields=null`**，再按 [完整结果交付](docs/agent-guide.md#完整结果交付与同次导出) 保存与校验；摘要投影无法恢复未选字段。
+
+字段、错误与端口差异见 [API 参考](docs/api-reference.md)，Python / JavaScript 客户端例子见 [接入指南](docs/agent-guide.md)。
+
+## 开发与验证
+
+源码位于 `src/fatebridge/`；中央目录装配领域声明，REST / MCP / CLI 共用服务与算法。[架构说明](docs/architecture.md) 介绍调用链与模块职责。
+
+安装开发依赖后运行：
+
+```bash
+uv pip install -e ".[dev]"
+python scripts/check_docs.py
+python -m pytest -q tests/test_doc_tool_counts.py tests/test_scenario_routing_coverage.py
+```
+
+代码变更还需运行领域测试与 CI 对应检查，命令见 [开发指南](docs/development-guide.md)。提交方式见 [贡献指南](CONTRIBUTING.md)，版本变化见 [CHANGELOG](CHANGELOG.md)。
+
+## 使用范围与许可
+
+计算验证关注历法、规则与数值的一致性；传统解释及分数是文化参考，分数不代表现实成功概率。规则来源、三端一致、黄金快照和真实模型对话分别提供不同证据。
+
+核心星盘支持本地星历与近似路径，应检查实际返回的 `chart_profile.ephemeris_model` 和 `run_metadata.engine_is_approximate`；西占推运、事件与生命周期工具缺少后端依赖时明确报错。项目包含后端、CLI 与技能资料，前端与部署控制由接入方提供。
+
+代码采用 [Apache-2.0](LICENSE)，第三方组件见 [NOTICE](NOTICE)；星历数据单独获取，见 [星历数据与精度](docs/getting-started.md#星历数据与精度)。

fatebridge-0.1.0/README.md

@@ -0,0 +1,113 @@
+# FateBridge
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
+[![CI](https://github.com/thomas-yanxin/FateBridge/actions/workflows/ci.yml/badge.svg)](https://github.com/thomas-yanxin/FateBridge/actions/workflows/ci.yml)
+
+FateBridge 是一个可在本地运行的 Python 后端能力库，把八字、紫微、传统占术、西方占星与风水规则组织成可调用、可复算、带来源的计算接口。应用通过 REST 接入，Agent 通过 MCP 调用，脚本通过 CLI 运行；当前版本为 **0.1.0**。
+
+当前提供 **86 个业务 REST 路由**、**87 个 FastMCP 工具**；中央目录含 88 条记录，CLI 可执行其中87条。三端共用领域计算，名称和请求形态见 [三端能力边界](docs/api-reference.md#24-三端能力边界)。完整 **13 family / 87 工具** 清单见 [算法覆盖矩阵](docs/algorithm-coverage.md)。
+
+## 从这里开始
+
+| 你的目标 | 入口 |
+| --- | --- |
+| 在 Codex 中直接咨询 | [Codex 使用指南](docs/codex-guide.md) |
+| 安装并发起第一次调用 | [快速入门](docs/getting-started.md) |
+| 接入应用或 Agent | [接入指南](docs/agent-guide.md) · [API 参考](docs/api-reference.md) |
+| 按问题选择工具或场景技能 | [场景路由](docs/scenario-routing.md) · [9 个 Onda 技能](skills/README.md) |
+| 修改代码、规则或文档 | [开发指南](docs/development-guide.md) · [贡献指南](CONTRIBUTING.md) |
+| 升级旧版调用或排查故障 | [迁移指南](docs/migration.md) · [故障排除](docs/troubleshooting.md) |
+
+完整导航和各文档职责见 [文档中心](docs/README.md)。
+
+## 能力概览
+
+| 领域 | 计算内容 |
+| --- | --- |
+| 八字与双人关系 | 命盘，事业、财运、婚姻等九项专题，双人配合、宿曜相性 |
+| 时运与历法 | 大运、流年、流月、流日、流时、节气与农历 |
+| 中国术数与占卜 | 紫微、奇门、六壬、太乙、金口诀、梅花、六爻及本地技法 |
+| 西方占星 | 本命与流派盘、关系盘、返照、行运、主限及时主等推运 |
+| 风水空间 | 八宅、金锁基础砂水、年星、玄空历史宅盘，以及按事实分层的布局与物件审查 |
+
+风水的输入、来源与适用范围见 [家居风水](docs/fengshui.md)；各工具精度、依赖与未覆盖项目见 [算法覆盖](docs/algorithm-coverage.md)。
+
+## 快速开始
+
+需要 Python 3.10+，当前 CI 覆盖 3.10–3.13。通过 PyPI 安装：
+
+```bash
+python -m pip install fatebridge==0.1.0
+```
+
+源码开发安装需要 Git，以下为 macOS / Linux 示例；Windows 和全部配置见 [快速入门](docs/getting-started.md#安装)。
+
+```bash
+git clone https://github.com/thomas-yanxin/FateBridge.git
+cd FateBridge
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install -e .
+```
+
+### CLI：安装后直接调用
+
+CLI 不需要启动服务。以下命令使用虚构体验资料：
+
+```bash
+fatebridge describe bazi_birth --detail input
+fatebridge bazi_birth --birth-year 1990 --birth-month 5 --birth-day 15   --birth-hour 10 --birth-minute 30 --gender 男 --birth-place 北京   --birth-timezone Asia/Shanghai --fields bazi_birth.day_master --strict-fields
+```
+
+### REST：启动后发起请求
+
+```bash
+API_HOST=127.0.0.1 fatebridge-api
+```
+
+另开一个终端执行：
+
+```bash
+curl http://localhost:8010/health
+curl -X POST http://localhost:8010/api/cn/bazi/birth   -H 'Content-Type: application/json'   -d '{"birth_year":1990,"birth_month":5,"birth_day":15,"birth_hour":10,
+       "birth_minute":30,"gender":"男","birth_place":"北京",
+       "birth_timezone":"Asia/Shanghai","use_true_solar_time":true}'
+```
+
+交互文档位于 `http://localhost:8010/docs`。独立命盘数据位于 `bazi_birth`；配置了 `FATEBRIDGE_API_KEYS` 时，业务请求还需密钥头。监听地址默认 `0.0.0.0`，本机使用以上命令限制到 `127.0.0.1`；配置与部署说明见 [快速入门](docs/getting-started.md#配置环境变量) 和 [安全策略](SECURITY.md)。
+
+### MCP：交给 host 启动
+
+MCP 使用 stdio。先运行 `fatebridge doctor --mcp --scenario onda-shiye`，再按返回的绝对路径命令注册。完整 Codex 配置、虚构对话和连接检查见 [Codex 使用指南](docs/codex-guide.md)。
+
+## 调用与结果
+
+- 用 `fatebridge discover --family bazi` 或 REST `/api/tools?detail=summary&family=bazi` 筛选能力，再读取所选工具契约。已知 Schema 时可直接调用。
+- 成功结果默认带 `run_metadata`，记录工具、时间和计算口径；复现还需保存原输入与运行环境。
+- 用 `fields` 控制响应体积，`strict_fields=true` 拒绝无效路径。MCP 默认预算 8192 字符，超限后通过 `result_delivery` 读取同一次结果。
+- **需要完整 JSON 或全部时间线时，首次调用 `fields=null`**，再按 [完整结果交付](docs/agent-guide.md#完整结果交付与同次导出) 保存与校验；摘要投影无法恢复未选字段。
+
+字段、错误与端口差异见 [API 参考](docs/api-reference.md)，Python / JavaScript 客户端例子见 [接入指南](docs/agent-guide.md)。
+
+## 开发与验证
+
+源码位于 `src/fatebridge/`；中央目录装配领域声明，REST / MCP / CLI 共用服务与算法。[架构说明](docs/architecture.md) 介绍调用链与模块职责。
+
+安装开发依赖后运行：
+
+```bash
+uv pip install -e ".[dev]"
+python scripts/check_docs.py
+python -m pytest -q tests/test_doc_tool_counts.py tests/test_scenario_routing_coverage.py
+```
+
+代码变更还需运行领域测试与 CI 对应检查，命令见 [开发指南](docs/development-guide.md)。提交方式见 [贡献指南](CONTRIBUTING.md)，版本变化见 [CHANGELOG](CHANGELOG.md)。
+
+## 使用范围与许可
+
+计算验证关注历法、规则与数值的一致性；传统解释及分数是文化参考，分数不代表现实成功概率。规则来源、三端一致、黄金快照和真实模型对话分别提供不同证据。
+
+核心星盘支持本地星历与近似路径，应检查实际返回的 `chart_profile.ephemeris_model` 和 `run_metadata.engine_is_approximate`；西占推运、事件与生命周期工具缺少后端依赖时明确报错。项目包含后端、CLI 与技能资料，前端与部署控制由接入方提供。
+
+代码采用 [Apache-2.0](LICENSE)，第三方组件见 [NOTICE](NOTICE)；星历数据单独获取，见 [星历数据与精度](docs/getting-started.md#星历数据与精度)。

fatebridge-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+# setuptools>=77 is required for the PEP 639 SPDX ``license``/``license-files``
+# expression used below (older setuptools rejects the string form).
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fatebridge"
+# Single source of truth: src/fatebridge/__init__.py::__version__. REST (api.py),
+# MCP (mcp_server.py) and the packaging metadata all read that one value.
+dynamic = ["version"]
+description = "FateBridge - A Model Context Protocol (MCP) server bridging ancient Chinese fortune telling wisdom with modern technology"
+authors = [{name = "thomas-yanxin", email = "yx20001210@163.com"}]
+# PEP 639: SPDX expression + explicit license files (LICENSE + NOTICE, the
+# latter required by Apache-2.0 §4d). The old ``License ::`` classifier is
+# intentionally dropped — setuptools>=77 rejects it alongside an SPDX string.
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "fastapi>=0.110.1",
+    "fastmcp>=3.4.2",
+    # The predictive adapter and numerical fixtures target Kerykeion 5.
+    # Version 6 changes return calculations and bundled ephemeris data layout.
+    "kerykeion>=5.5.0,<6",
+    "lunardate>=0.2.2",
+    "packaging>=23.0",  # doctor checks installed dependency version constraints
+    "pydantic>=2.0.0",
+    "pyswisseph>=2.10.0",
+    "python-dateutil>=2.8.0",
+    "python-multipart>=0.0.9",
+    "pytz>=2024.1",
+    "uvicorn>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "jsonschema>=4.20.0",  # validate published output contracts in transport tests
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.5.0",
+    "pyyaml>=6.0",  # test_skills_interface_contract parses agents/interface.yaml
+]
+
+[project.urls]
+Homepage = "https://github.com/thomas-yanxin/FateBridge"
+Repository = "https://github.com/thomas-yanxin/FateBridge"
+Issues = "https://github.com/thomas-yanxin/FateBridge/issues"
+Changelog = "https://github.com/thomas-yanxin/FateBridge/blob/master/CHANGELOG.md"
+
+[project.scripts]
+fatebridge = "fatebridge.cli:main"
+fatebridge-api = "fatebridge.api:main"
+fatebridge-mcp = "fatebridge.mcp_server:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "fatebridge.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["fatebridge*"]
+
+# packages.find discovers *code* only. The engines load their reference data at
+# runtime via ``Path(__file__).parents[1] / "data" / ...`` (canping, heluo,
+# knowledge_store), so the JSON payloads MUST be declared here or an installed
+# wheel raises FileNotFoundError. ``py.typed`` ships the PEP 561 typed marker.
+[tool.setuptools.package-data]
+fatebridge = ["py.typed", "data/**/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "dateutil",
+    "dateutil.*",
+    "fastmcp",
+    "fastmcp.*",
+    "kerykeion",
+    "lunardate",
+    "lunardate.*",
+    "pytz",
+    "swisseph",
+    "yaml",
+]
+ignore_missing_imports = true

fatebridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fatebridge-0.1.0/src/fatebridge/__init__.py

@@ -0,0 +1,25 @@
+"""
+FateBridge - Fortune Telling System
+
+A backend-only Python toolkit bridging Chinese metaphysics, divination and
+offline Western astrology. The same domain capabilities are exposed through
+three interfaces (FastAPI REST, FastMCP, and the ``fatebridge`` CLI), all
+derived from a single central tool catalog
+(``fatebridge.services.tool_catalog``).
+
+See the docs/ directory for the full algorithm coverage matrix and the
+developer / Agent integration guide.
+
+Public API
+----------
+FateBridge is consumed through its three transports rather than as a library of
+importable functions. The programmatic entry point is the central tool catalog
+``fatebridge.services.tool_catalog`` (every REST route, MCP tool and CLI
+subcommand is derived from it). This top-level module intentionally exposes only
+metadata; deeper capabilities live under ``fatebridge.services`` / ``.core``.
+"""
+
+__version__ = "0.1.0"
+__author__ = "thomas-yanxin"
+
+__all__ = ["__version__", "__author__"]

fatebridge-0.1.0/src/fatebridge/analysis/__init__.py

@@ -0,0 +1 @@
+"""FateBridge analysis modules."""