packaging

17 beliefs (15 IN, 2 OUT)

The packaging topic covers how ftl-reasons is structured, distributed, and installed as a Python package. The central design principle is zero runtime dependencies: the core reasons_lib package runs entirely on Python's standard library, with an empty dependencies list in pyproject.toml (zero-runtime-dependencies, zero-runtime-deps, ftl-reasons-zero-runtime-deps). This constraint is enforced not just at the packaging metadata level but also in the implementation itself — the Network class, which is the engine of the truth maintenance system, imports only stdlib modules like collections.deque and datetime alongside internal dataclasses (network-has-zero-external-dependencies, network-no-external-deps). Together these layers eliminate supply-chain risk and simplify deployment (project-has-zero-external-coupling).

Optional functionality is available through install extras that map one-to-one to specific modules: the pg extra gates reasons_lib/pg.py for PostgreSQL support, cluster gates reasons_lib/cluster.py, and test-pg is a superset combining pg and test dependencies (extras-map-one-to-one-to-modules). This design means users who only need the core TMS backed by SQLite install nothing beyond the standard library, while those needing PostgreSQL or clustering opt in explicitly. The pip-installable name is ftl-reasons while the importable package is reasons_lib, a deliberate decoupling (package-name-split). Only the reasons_lib package ships in built distributions — tests, entries, reviews, and knowledge-base artifacts are excluded (only-reasons-lib-is-distributed, only-reasons-lib-packaged).

The project requires Python 3.10 or higher, which enables use of structural pattern matching and the X | Y union type syntax throughout the codebase (python-310-floor, python-310-minimum, python-version-floor-3-10). Versioning is managed manually with a static declaration in pyproject.toml — there is no dynamic version plugin or SCM-based versioning (version-is-manual). The project was renamed from rms to reasons at version 0.3.0, motivated by a measured 5 percentage-point improvement in LLM accuracy identified through ablation study (rename-from-rms-at-0.3.0).

Two beliefs are currently OUT (retracted): system-efficiency-spans-packaging-and-runtime and system-resource-footprint-is-minimal-at-all-phases. Both attempted to unify packaging-level concerns like zero dependencies with runtime concerns like lazy loading and token estimation into single cross-cutting claims. Their retraction suggests that the knowledge base prefers to keep packaging constraints and runtime optimization as separate, independently justified topics rather than conflating them into broader system-efficiency narratives.

IN extras-map-one-to-one-to-modules
Each optional dependency group maps 1:1 to a specific module: `pg` extra gates `reasons_lib/pg.py`, `cluster` extra gates `reasons_lib/cluster.py`, and `test-pg` is a superset combining `pg` and `test`.
IN ftl-reasons-zero-runtime-deps
The core `reasons_lib` package has no mandatory runtime dependencies — all external packages (psycopg, sentence-transformers, scikit-learn, mcp) are gated behind optional install extras (`[pg]`, `[cluster]`, `[mcp]`).
IN network-has-zero-external-dependencies
The Network class imports only stdlib (`collections.deque`, `datetime`) plus package data types (`Node`, `Justification`, `Nogood`); it has zero external dependencies.
IN network-no-external-deps
`network.py` depends only on stdlib (`deque`, `datetime`) and project dataclasses; it has zero external package dependencies.
IN only-reasons-lib-is-distributed
Only the `reasons_lib` package is included in built distributions — `tests/`, `entries/`, and `reviews/` are excluded by the explicit `packages = ["reasons_lib"]` declaration in pyproject.toml.
IN only-reasons-lib-packaged
Setuptools is configured to include only the `reasons_lib` package in distributions; tests, entries, reviews, and knowledge-base artifacts are excluded from wheels
IN package-name-split
The pip-installable name is `ftl-reasons` but the importable Python package is `reasons_lib`; these are deliberately decoupled.
IN project-has-zero-external-coupling
The project enforces zero external coupling at both the packaging level (empty `dependencies` list in pyproject.toml) and the implementation level (core Network class uses only stdlib imports), eliminating supply-chain risk and simplifying deployment.
IN python-310-floor
The project requires Python 3.10+ (`requires-python = ">=3.10"`), establishing the minimum language features available throughout the codebase.
IN python-310-minimum
The project requires Python >= 3.10 (`requires-python = ">=3.10"`), enabling use of structural pattern matching and `X | Y` union type syntax throughout the codebase.
IN python-version-floor-3-10
The project requires Python >=3.10, allowing use of match statements, union type syntax with `|`, and other 3.10+ features throughout `reasons_lib`.
IN rename-from-rms-at-0.3.0
The project was renamed from `rms` to `reasons` in version 0.3.0, driven by a measured 5 percentage-point LLM accuracy improvement in ablation study
OUT system-efficiency-spans-packaging-and-runtime
Resource efficiency is enforced at every system phase: zero external dependencies with lazy loading minimize the static footprint at packaging and startup, while O(1) per-line budget tracking with chars/4 token estimation minimize computational overhead during runtime belief distillation.
OUT system-resource-footprint-is-minimal-at-all-phases
The system achieves minimal resource footprint across all lifecycle phases: zero external dependencies at both packaging and implementation levels eliminate installation overhead and version conflicts, while lazy module imports in both API and CLI layers defer heavy computation until actually needed — minimizing deployment complexity, startup time, and memory consumption simultaneously.
IN version-is-manual
The version is statically declared in `pyproject.toml` with no dynamic version plugin, `__version__` import, or SCM-based versioning — it must be bumped manually.
IN zero-runtime-dependencies
`ftl-reasons` declares `dependencies = []` in pyproject.toml; the entire `reasons_lib` package runs on Python's standard library alone (sqlite3, json, argparse); PostgreSQL support is opt-in via the `pg` extra
IN zero-runtime-deps
`ftl-reasons` has zero runtime dependencies; the entire library runs on Python's stdlib alone (SQLite via `sqlite3`, dataclasses, etc.).