Metadata-Version: 2.4
Name: haloa
Version: 0.1.2
Summary: haloa: a grammar in which unverified claims cannot sound verified
Author: James Ray Hawkins
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Jayhawk314/haloa
Project-URL: Repository, https://github.com/Jayhawk314/haloa
Project-URL: Issues, https://github.com/Jayhawk314/haloa/issues
Project-URL: Changelog, https://github.com/Jayhawk314/haloa/commits/master
Keywords: llm,verification,provenance,evidence,receipts,hallucination
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: law
Requires-Dist: eyecite; extra == "law"
Requires-Dist: pypdf; extra == "law"
Provides-Extra: mcp
Requires-Dist: mcp; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# haloa

**A grammar in which unverified claims cannot sound verified.**

```bash
pip install haloa
```

haloa is a free, open, model-agnostic clarity layer any LLM can slip on. It types every
assertion — the model's *and* the user's — into a claim object, judges each claim with a
**deterministic, inspectable gate** (never another LLM), and gives conclusions a confidence
algebra in which unverified premises mechanically poison whatever is built on them. Every
verdict leaves a receipt you can open without trusting the system. Over time, the ledger
makes each model's honesty an empirical, per-domain track record instead of a vibe.

## The origin story

On 2026-07-17, a frontier model reviewing a UI codebase assessed pages **by filename,
without opening them**, and wrapped the assessments in confident prose. A human caught it
by hand. This layer exists so that catch happens by construction: a claim about a file
with no read/run event in the session ledger **must** render as `not_assessed`, and any
conclusion composed from it inherits that status. `tests/test_origin_story.py` encodes
exactly this scenario and is the repo's soul.

## What it is not

**Not a fact-checker.** Fact-checkers ask "is this true in the world?" — usually by asking
another LLM. haloa asks a smaller, harder question: **"what standing does this claim
actually have in this session?"** Did anyone open the file? Run the command? Does the
receipt exist? Truth-in-the-world stays with humans and evidence; standing is what a
deterministic gate can actually guarantee.

## The vocabulary

| Verdict | Plain meaning |
|---|---|
| `agree` | Verified — a receipt from this session backs it. |
| `hollow` | Connected and fluent — and nothing was actually checked. The flagship verdict. |
| `orphan` | No evidence, no connection to anything established. |
| `not_assessed` | Refers to something never opened or run this session. |
| `reject` | Contradicts what's already committed. |

Composition is a quantale with an annihilator: confidence multiplies (only decays), and a
hollow/orphan/not-assessed/rejected premise zeroes whatever is built on it. Vetoes are
never averaged away.

## Try it

```
python -m unittest discover -s tests   # full suite, no network, core is stdlib only
python demo.py                         # watch a hollow premise poison a conclusion

# the law vertical: check every citation in a brief against CourtListener and
# get a Certificate of Citation Verification sealed to a hash-chained ledger
pip install eyecite pypdf
python -m verticals.law path/to/brief.txt
# recommended: set HALOA_COURTLISTENER_TOKEN for exact batched lookup + quote checks

# measured law-product benchmark; downloads stay outside git and are hash-checked
python scripts/benchmark_law.py --download
python scripts/benchmark_law.py --online
```

## Slip it on

The MCP server is the slip-on surface: haloa's session tools (claim, verdict,
compose, receipt, commit, retract…) served standalone — it needs nothing but this
repo and the optional `mcp` package.

```
# run it (core stays stdlib; the server itself needs: pip install mcp)
python -m haloa.mcp_server --ledger sessions/haloa_session.jsonl

# register for Claude Code sessions in this repo:
claude mcp add haloa --env PYTHONPATH=<this repo> -- python -m haloa.mcp_server --ledger <this repo>/sessions/haloa_session.jsonl
```

Optionally, `--wrap <module>` re-exposes any other MCP tools module so that **every
tool call is recorded as an access event by the wrapper itself** — narration about a
tool that was never called then renders `not_assessed` by construction. That is a
feature to reach for when wanted, not default wiring: haloa is not coupled to any
other project.

## Reading order

1. `GRAMMAR.md` — the claim-typing grammar (the design core).
2. `LEDGER_SPEC.md` — the append-only session ledger format.
3. `HANDOFF.md` — design laws, lineage, and build phases.

Core is pure Python stdlib, deliberately small, and stays that way.
