fortune-telling-core 0.1.0__tar.gz

fortune_telling_core-0.1.0/.github/workflows/cd.yml

@@ -0,0 +1,67 @@
+name: CD
+
+# Publish to PyPI on a published GitHub Release using PyPI Trusted Publishing
+# (OIDC). No long-lived API token is stored: the publish job exchanges a
+# short-lived GitHub OIDC token for a PyPI upload credential. Configure the
+# trusted publisher once at https://pypi.org/manage/account/publishing/ with:
+#   owner: moriyoshi   repository: fortune-telling-core
+#   workflow: cd.yml   environment: pypi
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          # hatch-vcs derives the package version from tags, so fetch full
+          # history and tags rather than a shallow checkout.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install release dependencies
+        run: python -m pip install --upgrade ".[release]"
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Check distributions
+        run: |
+          python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fortune-telling-core
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

fortune_telling_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: lint + type-check + test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Format check (ruff)
+        run: python -m ruff format --check .
+
+      - name: Lint (ruff)
+        run: python -m ruff check --output-format=github .
+
+      - name: Type-check (mypy)
+        run: python -m mypy src tests
+
+      - name: Test (pytest)
+        run: python -m pytest

fortune_telling_core-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,70 @@
+name: Docs
+
+# Build the MkDocs site and deploy to GitHub Pages. Deployment uses the GitHub
+# Pages OIDC flow (id-token: write) rather than pushing to a gh-pages branch.
+# Enable once under repository Settings -> Pages -> Build and deployment ->
+# Source: GitHub Actions.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Cancel superseded runs, but let an in-progress deployment finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e ".[docs]"
+
+      - name: Build (strict)
+        run: mkdocs build --strict
+
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to Pages
+    needs: build
+    # Only publish from the default branch, not from manual runs on other refs.
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write # publish to GitHub Pages
+      id-token: write # OIDC verification of the deployment origin
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

fortune_telling_core-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.agents-workspace/
+.cache/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage/
+dist/
+build/
+site/
+.env
+.env.*
+!.env.example
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+__MACOSX

fortune_telling_core-0.1.0/AGENTS.md

@@ -0,0 +1,83 @@
+# Documents for both humans and coding agents
+
+* [README.md](./README.md)
+
+# Documents for coding agents
+
+* [./.agents/docs/OVERVIEW.md](./.agents/docs/OVERVIEW.md) ... project overview.
+* [./.agents/docs/ARCHITECTURE.md](./.agents/docs/ARCHITECTURE.md) ... library structure and design notes.
+* [./.agents/docs/JOURNAL.md](./.agents/docs/JOURNAL.md) ... chronological findings, decisions, and work history.
+* [./.agents/docs/LTM/INDEX.md](./.agents/docs/LTM/INDEX.md) ... long-term memory index for durable project knowledge under `./.agents/docs/LTM/`.
+* [./.agents/docs/TODO.md](./.agents/docs/TODO.md) ... open to-do items, including the current implementation handoff: extract shared solar-term/time-model code into `astronomy`, then build the Nine Star Ki backend per the `JOURNAL.md` 2026-06-12 Nine Star Ki design entry.
+* [./.agents/skills/](./.agents/skills/) ... local memory-maintenance skills for consolidating `JOURNAL.md`, LTM documents, and canonical project docs.
+
+# Rules and protocols
+
+## General
+
+* This repository is the home for `fortune-telling-core`, a Python library for composable fortune-telling systems.
+* Keep project knowledge in the agent docs as the implementation evolves.
+* Prefer existing project patterns over introducing new frameworks or conventions.
+* Keep the core library deterministic, typed, and testable. Randomness should be injectable so readings can be reproduced.
+* Do not bake spiritual, cultural, or localisation assumptions into shared primitives. Model traditions and interpretation systems as explicit modules.
+* When a design decision is genuinely ambiguous because established schools or conventions diverge (for example the Nine Star Ki day-star escapement, a house system, or a zodiac/ayanamsa choice), expose it as a configurable option (a config enum, engine argument, or request option) with a sensible documented default, rather than hardcoding one choice. Record the selected value in `Provenance.notes` so a reading stays reproducible and auditable. Use judgement: reserve options for genuine divergence, not every default, to avoid option sprawl.
+* When a durable decision, pitfall, or investigation result matters to future work, append it to `.agents/docs/JOURNAL.md`.
+
+## File Management
+
+* Work summaries belong under `./.agents/docs`, not under `/tmp`.
+* Temporary files belong under `./.agents-workspace/tmp`, not under `/tmp`.
+* Never delete user files without permission. Only safe to delete: files you created in the current session under `./.agents-workspace/tmp/`.
+* Keep generated scratch artefacts out of source directories unless they are part of the requested deliverable.
+
+## Building and Testing
+
+* The project stack is Python 3.12+ with a `src/` package layout.
+* When fixing a bug, add a focused regression test whenever the codebase has a practical test harness.
+* Do not report a change as complete until the relevant checks have been run, or until you explicitly state why they could not be run.
+
+## Local Lint Gate
+
+Before reporting a code change as done, run the project's canonical formatter, linter, type-checker, and tests once those commands exist. Record the current commands in this section when the stack is expanded.
+
+Current stack: Python package with `pyproject.toml`, `src/fortune_telling_core`, and `tests`.
+
+Always use the project virtualenv at `./.venv` for Python tooling. The bare `python`/`pip` on `PATH` resolves to the pyenv-global interpreter, **not** the venv, so activate the venv (`source .venv/bin/activate`) or call the venv binaries explicitly (`./.venv/bin/python`, `./.venv/bin/pip`). Never `pip install` into the global/pyenv interpreter — this includes `build`, `twine`, `mkdocs`, and the `.[dev]`/`.[docs]`/`.[release]` extras.
+
+Canonical commands (run after `source .venv/bin/activate`, or prefix each with `./.venv/bin/`):
+
+* Create the virtual environment: `python3 -m venv .venv`
+* Activate it: `source .venv/bin/activate`
+* Install for development: `python -m pip install -e ".[dev]"`
+* Format: `python -m ruff format .`
+* Lint: `python -m ruff check .`
+* Type-check: `python -m mypy src tests`
+* Test: `python -m pytest`
+
+The library supports Python 3.12, 3.13, and 3.14. A Hatch matrix runs the suite (and full gate) against each:
+
+* All versions, tests only: `hatch run test:run`
+* All versions, full gate (ruff + mypy + pytest): `hatch run test:check`
+* A single version: `hatch run +py=3.14 test:run`
+
+Before reporting a change that could affect cross-version behaviour as done, run `hatch run test:check` so all three interpreters are exercised.
+
+## Shell Pitfalls (prezto defaults)
+
+The user's shell uses prezto, which sets aliases and options that can break non-interactive scripts:
+
+* `cp src dst` may prompt interactively when `dst` exists. Prefer explicit overwrite-safe commands.
+* `cat > file <<'EOF'` and `echo > file` can fail with `file exists` when the target exists. Use the repository editing tools rather than shell redirection for tracked files.
+* `rm file` may prompt for confirmation. Never delete user files unless the task explicitly requires it.
+
+## Git Workflow
+
+* Never make discretionary commits. Commit only when the user asks.
+* If commits are requested, sign them with `-S` unless the user gives different instructions.
+* Preserve unrelated work in the tree. Do not revert changes you did not make.
+
+## Documentation
+
+* Append new findings to `JOURNAL.md`; do not edit existing entries in place except through established memory-consolidation workflows.
+* In repo-authored documentation (`AGENTS.md`, `README.md`, `.agents/docs/**`), never use full-width parentheses. Use half-width parentheses.
+* Same for full-width colons. Use a half-width colon followed by a space.

fortune_telling_core-0.1.0/JOURNAL.md

@@ -0,0 +1 @@
+- 2026-06-12: Split interpreter packaging prep: made core packages pkgutil namespaces and promoted coerce/serde_types helper modules for external namespace contributors.

fortune_telling_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moriyoshi
+
+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.

fortune_telling_core-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: fortune-telling-core
+Version: 0.1.0
+Summary: Composable, reproducible primitives for fortune-telling systems.
+Author-email: Moriyoshi Koizumi <mozo@mozo.jp>
+License: MIT
+License-File: LICENSE
+Keywords: astrology,divination,fortune-telling,numerology,tarot
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mypy>=2.1; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Requires-Dist: twine>=6.2; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.7; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=1.0; extra == 'docs'
+Requires-Dist: ruff>=0.15; extra == 'docs'
+Provides-Extra: release
+Requires-Dist: build>=1.3; extra == 'release'
+Requires-Dist: twine>=6.2; extra == 'release'
+Description-Content-Type: text/markdown
+
+# fortune-telling-core
+
+`fortune-telling-core` is a composable, reproducible Python library for building
+fortune-telling and divination systems. It provides a small, deterministic, typed core of
+primitives for readings, symbols, spreads, draws, structural summaries, and provenance, with
+tradition-specific engines layered on top.
+
+## Design Principles
+
+- **Deterministic and reproducible.** Randomness enters through one narrow `Rng` protocol,
+  and every reading records the exact `Draw` that produced it. A recorded draw can be
+  replayed without any randomness.
+- **Tradition-agnostic core.** The core knows only symbols, positions, selections,
+  deterministic summaries, and audit metadata. Tradition modules live behind their own
+  packages and are not re-exported from the top-level package.
+- **Interpretation belongs to harnesses.** Discretionary meanings, localisation, and
+  presentation copy are intentionally outside the library. Consumers can map stable
+  symbol ids, position ids, modifiers, summaries, and provenance into their own
+  interpretation layer.
+- **Configurable where schools diverge.** Where established schools or conventions
+  disagree, such as house systems, zodiac/ayanamsa, time models, or the Nine Star Ki
+  day-star escapement, the choice is a documented option recorded in reading provenance.
+
+## Included Systems
+
+- **Core**: Tradition-neutral value types, engine contracts, replay, serialisation, and
+  provenance.
+- **Astronomy**: Shared, dependency-free astronomy including Julian-day helpers, solar
+  terms, time models, the `Ephemeris` protocol, and a pure-Python `BuiltinEphemeris`.
+- **Traditions**: `tarot`, `astrology`, `four_pillars` (BaZi), and `nine_star_ki`.
+  Each tradition exposes its engine and deck/spread data from its own subpackage.
+
+## Quick Start
+
+```python
+from fortune_telling_core import RandomRng, ReadingRequest, reading_to_json
+from fortune_telling_core.traditions.tarot import RWS_DECK, SINGLE_CARD, build_engine
+
+engine = build_engine()
+request = ReadingRequest(
+    deck_id=RWS_DECK.id,
+    spread_id=SINGLE_CARD.id,
+)
+
+reading = engine.read(request, rng=RandomRng(seed=42))
+payload = reading_to_json(reading)
+```
+
+Computed traditions use `cast()` instead of caller-provided randomness:
+
+```python
+from fortune_telling_core import Querent, ReadingRequest
+from fortune_telling_core.traditions.nine_star_ki import (
+    NINE_STAR_KI_DECK,
+    NINE_STAR_KI_SPREAD,
+    build_engine,
+)
+
+engine = build_engine()
+request = ReadingRequest(
+    deck_id=NINE_STAR_KI_DECK.id,
+    spread_id=NINE_STAR_KI_SPREAD.id,
+    querent=Querent(
+        id="example",
+        display_name="Example",
+        attributes={
+            "birth_datetime": "1990-05-17T09:30:00+09:00",
+            "latitude": "35.6895",
+            "longitude": "139.6917",
+        },
+    ),
+)
+
+reading = engine.cast(request)
+```
+
+## Layout
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── pyproject.toml
+├── src/
+│   └── fortune_telling_core/
+├── docs/
+├── tests/
+├── tools/
+└── .agents/
+    └── docs/
+```
+
+## Development
+
+This repository uses a `src/` Python package layout.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Run the deterministic demo CLI:
+
+```bash
+fortune-telling-demo all
+fortune-telling-demo tarot --seed 7
+fortune-telling-demo nine-star-ki --json --target-year 2026
+```
+
+For computed demos, a `--birth-datetime` without a timezone is interpreted in
+the terminal timezone and serialized with an offset.
+
+Build or serve the API documentation:
+
+```bash
+python -m pip install -e ".[docs]"
+mkdocs serve
+mkdocs build --strict
+```
+
+Regenerate the built-in ephemeris series only when changing source tables or
+the truncation threshold. The large public VSOP87D source files are downloaded
+into `.cache/ephemeris/vsop87d/`, an ignored local cache outside `tools/`, and
+verified by checksum:
+
+```bash
+python tools/ephemeris/generate_builtin_series.py --download-missing
+python tools/ephemeris/generate_builtin_series.py --check --download-missing
+```
+
+Canonical agent-facing project notes live in `.agents/docs/`.
+
+## Licence and Dependencies
+
+`fortune-telling-core` is MIT licensed and is intended to remain zero-copyleft. The required runtime dependency set is empty.
+
+Higher-precision astronomy is bring-your-own through the injectable `Ephemeris` Protocol. Consumers own the licensing review for any ephemeris backend they provide.

fortune_telling_core-0.1.0/README.md

@@ -0,0 +1,139 @@
+# fortune-telling-core
+
+`fortune-telling-core` is a composable, reproducible Python library for building
+fortune-telling and divination systems. It provides a small, deterministic, typed core of
+primitives for readings, symbols, spreads, draws, structural summaries, and provenance, with
+tradition-specific engines layered on top.
+
+## Design Principles
+
+- **Deterministic and reproducible.** Randomness enters through one narrow `Rng` protocol,
+  and every reading records the exact `Draw` that produced it. A recorded draw can be
+  replayed without any randomness.
+- **Tradition-agnostic core.** The core knows only symbols, positions, selections,
+  deterministic summaries, and audit metadata. Tradition modules live behind their own
+  packages and are not re-exported from the top-level package.
+- **Interpretation belongs to harnesses.** Discretionary meanings, localisation, and
+  presentation copy are intentionally outside the library. Consumers can map stable
+  symbol ids, position ids, modifiers, summaries, and provenance into their own
+  interpretation layer.
+- **Configurable where schools diverge.** Where established schools or conventions
+  disagree, such as house systems, zodiac/ayanamsa, time models, or the Nine Star Ki
+  day-star escapement, the choice is a documented option recorded in reading provenance.
+
+## Included Systems
+
+- **Core**: Tradition-neutral value types, engine contracts, replay, serialisation, and
+  provenance.
+- **Astronomy**: Shared, dependency-free astronomy including Julian-day helpers, solar
+  terms, time models, the `Ephemeris` protocol, and a pure-Python `BuiltinEphemeris`.
+- **Traditions**: `tarot`, `astrology`, `four_pillars` (BaZi), and `nine_star_ki`.
+  Each tradition exposes its engine and deck/spread data from its own subpackage.
+
+## Quick Start
+
+```python
+from fortune_telling_core import RandomRng, ReadingRequest, reading_to_json
+from fortune_telling_core.traditions.tarot import RWS_DECK, SINGLE_CARD, build_engine
+
+engine = build_engine()
+request = ReadingRequest(
+    deck_id=RWS_DECK.id,
+    spread_id=SINGLE_CARD.id,
+)
+
+reading = engine.read(request, rng=RandomRng(seed=42))
+payload = reading_to_json(reading)
+```
+
+Computed traditions use `cast()` instead of caller-provided randomness:
+
+```python
+from fortune_telling_core import Querent, ReadingRequest
+from fortune_telling_core.traditions.nine_star_ki import (
+    NINE_STAR_KI_DECK,
+    NINE_STAR_KI_SPREAD,
+    build_engine,
+)
+
+engine = build_engine()
+request = ReadingRequest(
+    deck_id=NINE_STAR_KI_DECK.id,
+    spread_id=NINE_STAR_KI_SPREAD.id,
+    querent=Querent(
+        id="example",
+        display_name="Example",
+        attributes={
+            "birth_datetime": "1990-05-17T09:30:00+09:00",
+            "latitude": "35.6895",
+            "longitude": "139.6917",
+        },
+    ),
+)
+
+reading = engine.cast(request)
+```
+
+## Layout
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── pyproject.toml
+├── src/
+│   └── fortune_telling_core/
+├── docs/
+├── tests/
+├── tools/
+└── .agents/
+    └── docs/
+```
+
+## Development
+
+This repository uses a `src/` Python package layout.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Run the deterministic demo CLI:
+
+```bash
+fortune-telling-demo all
+fortune-telling-demo tarot --seed 7
+fortune-telling-demo nine-star-ki --json --target-year 2026
+```
+
+For computed demos, a `--birth-datetime` without a timezone is interpreted in
+the terminal timezone and serialized with an offset.
+
+Build or serve the API documentation:
+
+```bash
+python -m pip install -e ".[docs]"
+mkdocs serve
+mkdocs build --strict
+```
+
+Regenerate the built-in ephemeris series only when changing source tables or
+the truncation threshold. The large public VSOP87D source files are downloaded
+into `.cache/ephemeris/vsop87d/`, an ignored local cache outside `tools/`, and
+verified by checksum:
+
+```bash
+python tools/ephemeris/generate_builtin_series.py --download-missing
+python tools/ephemeris/generate_builtin_series.py --check --download-missing
+```
+
+Canonical agent-facing project notes live in `.agents/docs/`.
+
+## Licence and Dependencies
+
+`fortune-telling-core` is MIT licensed and is intended to remain zero-copyleft. The required runtime dependency set is empty.
+
+Higher-precision astronomy is bring-your-own through the injectable `Ephemeris` Protocol. Consumers own the licensing review for any ephemeris backend they provide.

fortune_telling_core-0.1.0/docs/api/astronomy.md

@@ -0,0 +1,7 @@
+# Astronomy
+
+Shared, tradition-neutral astronomy used by the computed traditions: Julian-day and delta-T
+conversion, nutation, solar terms, the time-model helpers, and the injectable `Ephemeris` protocol
+with its pure-Python `BuiltinEphemeris` (and `FixedEphemeris` test stub).
+
+::: fortune_telling_core.astronomy

fortune_telling_core-0.1.0/docs/api/core.md

@@ -0,0 +1,6 @@
+# Core API
+
+The tradition-agnostic core: value types, the engine contract, randomness, serialisation, and
+errors. These symbols are re-exported from the top-level `fortune_telling_core` package.
+
+::: fortune_telling_core

fortune_telling_core-0.1.0/docs/api/traditions/astrology.md

@@ -0,0 +1,29 @@
+# Astrology
+
+A natal-chart engine: tropical or sidereal zodiac, ten planets plus the lunar nodes and the
+Ascendant/Midheaven, Whole Sign / Equal / Placidus houses, and aspects rendered into the summary.
+
+```python
+from fortune_telling_core import Querent, ReadingRequest
+from fortune_telling_core.traditions.astrology import NATAL_CHART, TROPICAL_ZODIAC, build_engine
+
+engine = build_engine()
+request = ReadingRequest(
+    deck_id=TROPICAL_ZODIAC.id,
+    spread_id=NATAL_CHART.id,
+    querent=Querent(
+        id="sample",
+        display_name="Sample",
+        attributes={
+            "birth_datetime": "1990-01-01T12:00:00+00:00",
+            "latitude": "51.5074",
+            "longitude": "-0.1278",
+            "house_system": "whole_sign",
+        },
+    ),
+)
+
+reading = engine.cast(request)
+```
+
+::: fortune_telling_core.traditions.astrology