Reference implementations of the Factlet Protocol v0.1. Other implementations validate against these.
| Implementation | Status | Tests | Path |
|---|---|---|---|
| Python | ✅ Working v0.1.0 | 13 passing | python/ |
| TypeScript | — | typescript/ |
Python ships first to lock the contract via tests; TypeScript ports byte-identical behavior next. We chose this over simultaneous development to avoid diverging implementations during the protocol's pre-v1.0 phase.
cd python/
pip install -e .
python -c "from factlet import load_factbook, factsignal; \
fb = load_factbook('../../registry/examples/payments/factbook.yaml'); \
print(factsignal('how do refunds work?', fb))"The five protocol primitives, exposed as callable functions:
load_factbook(path)→Factbook— parses YAML/JSON Factbook from diskretrieve(query, factbook)→list[Factlet]— relevance-ordered factlets (§4)factsignal(query, factbook)→int— coverage bars 0-5 (§6)on_low_factsignal(query, factbook, threshold, callback)→(score, retrieved)— runtime warning hook (§7)render_for_claude(factlets)/render_for_gpt(factlets)→str— vendor-flavored rendering (§8)
See python/README.md for full usage and python/tests/test_basic.py for behavior under each scenario.
Per SPEC.md §4 and §6, implementations choose their own retrieval and scoring algorithms. The reference SDK uses:
- Retrieval: token-overlap weighted by confidence. Simple, fast, deterministic.
- FactSignal: maps (retrieved factlet count) × (top-result confidence) to bars 0-5.
Production implementations (e.g. Kernora's Nora) layer embedding-based retrieval and LLM-based scoring on top of the same protocol contract.
See CONTRIBUTING.md. Behavioral changes require corresponding test additions; spec divergence is a bug.
MIT — see LICENSE.