russell@unturf.com
0a2e347f9c
`make query Q="0.1 + 0.2"` used to return `no_sources` because
arithmetic-shaped input has no FTS5 hits in any text shard. Two
surfaces close that gap.
**`arborist canon <key> "<input>"`** — direct π* call, no shards,
no LLM, no audit chain. Pure projection:
$ arborist canon arithmetic@v1 "0.1 + 0.2" → 3/10
$ arborist canon logic-kernel@v1 "A IMPL B" → (NOT A OR B)
$ arborist canon --list → registry contents
$ arborist canon --json arithmetic@v1 "0.1+0.2" → SHA-256 envelope
**Math/logic preflight in `arborist query`** — pure-arithmetic and
pure-propositional questions short-circuit RAG and answer through
arithmetic@v1 / logic-kernel@v1 directly. Synthetic
`audit_mode=CANONICAL_PROJECTION`, renders as
`CANONICAL · via <pi_star_ref>`:
$ arborist query "0.1 + 0.2"
0.1 + 0.2
CANONICAL · via arithmetic@v1 0.0s (projected)
3/10
$ arborist query "(NOT B) IMPL (NOT A)"
(NOT B) IMPL (NOT A)
CANONICAL · via logic-kernel@v1 0.0s (projected)
(NOT A OR B)
Sniff is conservative: pure-arithmetic shape (digits + ops, no
letters) or pure-propositional shape (uppercase atoms + reserved
keywords only). Natural-language wrapping ("what is 0.1+0.2?")
falls through to RAG. PiStarError on a shape match also falls
through — preflight is best-effort, never blocking.
Disable per-call: `--no-canonical-preflight` flag,
`policy["canonical_projection_preflight"]=False`.
No schema changes: CANONICAL_PROJECTION is a render-layer audit_mode
token. No providence_cache writes, no audit_events, no
governance_policy_hash bump. The canonical bytes ARE the answer;
SHA-256 of the bytes is the equivalence-class identity (already
committed via the π* registry).
Side housekeeping: arborist/pi_star/__init__.py docstring caught up
with reality — six concrete π*'s ship today, only tabular-pinned@v1
remains as a stub.
31 new tests (preflight sniff + dispatch, query short-circuit,
contrapositive equivalence-class collapse, CLI subcommand exit codes
and JSON envelope, --no-canonical-preflight policy gate). Full
suite: 1300 passed, 36 skipped.
|
||
|---|---|---|
| .. | ||
| _ext | ||
| _static | ||
| api | ||
| bench.rst | ||
| concepts.rst | ||
| conf.py | ||
| cookbook.rst | ||
| diagrams | ||
| index.rst | ||
| license.rst | ||
| Makefile | ||
| pi-star.rst | ||
| quickstart.rst | ||
| README.md | ||
| requirements.txt | ||
| v8-fork-score.rst | ||
Arborist API Reference (Sphinx)
This directory contains Sphinx configuration to generate API documentation from docstrings.
Build
cd docs/_source
make html # Generate HTML (output: _build/html/)
make text # Generate text (output: _build/text/)
make clean # Remove build artifacts
Or directly:
sphinx-build -b html . _build/html
View
After building, open _build/html/index.html in a browser.
Structure
conf.py— Sphinx configurationindex.rst— Main table of contentsapi/— Module documentation (one .rst per module category)substrate.rst— Core data structures (merkle, document, wikitext)storage.rst— SQLite schema (store, ingest, evict)retrieval.rst— FTS5 search (search, sources, concepts)qa.rst— Q&A pipeline (runner, query, verify, evidence, etc.)distill.rst— Distillation (surface→core)mesh.rst— Federation (gossip-based sync)cli.rst— Command-line interface
What it replaces
This generated documentation replaces docs/modules.md (1200+ lines of static API reference). The docstrings in code are the source of truth; Sphinx extracts them automatically.
Adding new modules
- Add a docstring to the module (module-level docstring at the top of
module.py) - Add an
.rstfile inapi/that includes the module withautomoduledirective - Reference it in
index.rst - Rebuild with
make html
Theme
Uses furo theme (modern, responsive, search-enabled).
Autodoc directives
The .rst files use Sphinx automodule to extract:
- Module docstrings
- Class docstrings + members
- Function signatures + docstrings
- Source code links (
:viewcode:extension)
See Sphinx autodoc docs.