Entity

The verified scaffold between you and any LLM. Entity is a CLI/TUI that sits between you and a model you choose (via /model), applying structured edits and verification before writing — with a dark-cyan interface and an animated ASCII octopus mascot. It ships with Entity-Bench, the proof-of-concept benchmark.

Read THESIS.md (history + algebra), ARCHITECTURE.md (design), and BLUEPRINT.md (the full build spec that generated this repo).

Install

pip install -e ".[full]"          # from source, with TUI + live LLM calls
# system-wide (Ubuntu/Debian/WSL):
bash packaging/build_deb.sh && sudo dpkg -i dist/entity_0.1.0_all.deb
# Fedora/RHEL or any distro:
sudo bash packaging/install.sh

Core installs dependency-free; [full] adds rich, prompt_toolkit, httpx.

Use

entity                 # launch the TUI (octopus banner, entity› prompt)
entity --plain         # no-TUI line mode (for pipes / dumb terminals)
entity --version

Inside the TUI: /model to connect an LLM, then just chat.

entity› /model
entity› /learner none        # parametric learner is OPTIONAL (none|bitnet|lora|custom)
entity› /edit entity-ast
entity› /verifier z3

Full command list: docs/cli.md. The /model page: docs/model-config.md.

Benchmark

entity bench run --dataset mock --n 128 --out runs/a   # -> PASS

Metrics & algebra: docs/metrics.md and THESIS.md.

Documentation, paper & empirical study

• MANUAL.md — the complete user manual (install, every slash command, the /model wizard, the verification gate, the benchmark, packaging, FAQ).
• paper/entity.pdf — the pre-print "Entity: A Verified Scaffold Between Language Models and Source Code" (compile from paper/entity.tex with tectonic).
• experiments/ — the reproducible empirical study. Real Z3 proofs, real tree-sitter token accounting, real dense-vs-lexical retrieval, a multi-seed composite sweep, full statistics, and CodeCarbon energy/carbon accounting.

pip install -e ".[study]"
python -m experiments.run_all --out results --seed 0     # writes results/*.json
python -m experiments.figures --results results --out figures   # layered SVG + PDF

Every figure is an editable, layered SVG (Inkscape layers) with a vector PDF twin. Every published number regenerates from the command above; the run manifest records platform and library versions.

Headline measured results

Result	Value
Verification gate (10 contracts ×2): verified-correctness / invalid-patch reduction	1.00 / 1.00, mean proof latency 2.95 ms
Edit-emission token economy (tree-sitter, 120 files)	−85.2% vs unified diff, −98.8% vs full rewrite
Verified-memory retrieval (disjoint paraphrases)	dense p@1=0.50 vs lexical 0.43 vs chance 0.125
Composite sweep (40 seeds, paired n=1024)	tokens −30% (Cliff's δ −0.64, p<10⁻¹⁶⁰); solve-lift p=7e-4 on issue data
Full study energy / carbon (CodeCarbon)	4.19e-5 kWh / 6.93e-6 kg CO₂eq in 13.5 s

License

Apache-2.0.