Metadata-Version: 2.4
Name: fux-engine
Version: 0.9.0
Summary: Fux — a portable agent-aware knowledge engine: rules, memory, narrative, and graph in one frontmatter substrate.
Author-email: arpit arya <arpitarya.me@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/arpitarya/fux
Project-URL: Repository, https://github.com/arpitarya/fux
Project-URL: Documentation, https://github.com/arpitarya/fux/blob/main/docs/guide.md
Project-URL: Bug Tracker, https://github.com/arpitarya/fux/issues
Keywords: knowledge,rules,graph,claude,codex,copilot,frontmatter,llm,memory,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2; extra == "embeddings"
Provides-Extra: ast
Requires-Dist: tree-sitter>=0.23; extra == "ast"
Requires-Dist: tree-sitter-language-pack>=0.7; extra == "ast"
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == "pdf"
Provides-Extra: scrape
Provides-Extra: critic
Requires-Dist: anthropic>=0.40; extra == "critic"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/arpitarya/fux/main/fux/assets/fux-lockup.png" alt="Fux — Alpha Forge Knowledge Index" width="360" />

# Fux

> **Memory tools record what your agent *did*. Fux records *why* your code is the way it is — and checks it's still true.**

[![PyPI](https://img.shields.io/pypi/v/fux-engine.svg)](https://pypi.org/project/fux-engine/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#the-0-guarantee)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

The *why* behind your code — why this formula, why this invariant, why it was done *this* way — usually lives in someone's head and dies when they leave. Fux makes it a first-class, version-controlled thing your agent reads before it touches anything, and tells you the moment the code drifts away from what you wrote. **`$0`, deterministic, zero dependencies, no mandatory LLM calls.**

**Pronounced "fox."** · Python ≥ 3.11 · stdlib only · MIT

<!-- launch: replace the <p> below with the demo GIF — `fux why day-pnl` → rule + why +
     governed code, then the Solar Terminal graph igniting the `governs` links. -->
<p align="center"><em>▶ Demo GIF coming soon.</em></p>

## The story

> *A story? In a README? I know. But here's a fun fact about the human animal: nobody, in the entire history of the species, was ever moved by a bullet point.* We do badges, a wall of CLI flags, and a "Contributing" section nobody's opened since 2019 — and we call it documentation. You will not remember my feature list. You'll remember the pipe. So I wrote the pipe. Ninety seconds, it's about a basement, and — spoiler — you're the idiot in it. Read it. — *Arpit*

You move into an old house. Down in the basement, the previous owner painted one pipe bright red. You have no idea why — so when you renovate, you treat it like any other pipe and reroute it. A week later, the basement floods. That red pipe froze every winter, and the paint was the owner's way of saying *leave this one alone.* They knew. They just never wrote it down, and then they moved out.

That's how almost all important knowledge works. The *reason* behind a choice lives in one person's head, and the day they leave, it's gone — so the next person changes it with complete confidence, and something quietly breaks. (Swap "person" for "AI assistant" and it happens ten times faster.)

**Fux is the note taped to the red pipe.** You write the reason down once, it stays right next to the thing it explains, and whoever comes next — a new owner, a contractor, an AI — reads it *before* they touch anything. And if someone reroutes the pipe anyway, Fux flips the note over: *heads up — this may no longer match what's actually here.* The reason can't vanish, and it can't quietly go out of date.

In code, the red pipe is the one line some genius is always about to "clean up":

```python
def day_pnl(holding):
    # No, this cannot be one tidy line. Normalize each leg to dollars BEFORE
    # summing — percentages double-count during a corporate action.
    # Yes, you have 15 years of experience. So did the last principal who
    # "simplified" this and took prod down on dividend day. (see: day-pnl)
    return sum(to_usd(leg) for leg in holding.legs)
```

Six months later, a Principal Engineer With Opinions skims that comment, concludes whoever wrote it "didn't really understand the domain," deletes it, and ships the one clean line — right before the next corporate action quietly poisons the numbers. The comment was right. It usually is. (We've all been that engineer.) Fux turns it from a comment a confident person can delete into a rule they *can't* — checked, and bound to the exact lines it explains.

## See it

```bash
$ fux why day-pnl
```

```
formula · day-pnl · governs backend/app/aggregator.py#L40-58

  Rule:  Day P&L = current market value − previous close value, per holding,
         summed. Dollar-normalize each leg before summing.
  Why:   Quantity drifts intraday (corporate actions, partial fills); summing
         percentages double-counts. Dollars are the only safe common unit.
  Edge:  New position with no previous close → previous = cost basis, not 0.

  ⚑ unsealed — aggregator.py changed structure since this rule was sealed.
     The logic this rule describes may no longer match. Run `fux why day-pnl --history`.
```

One entry, authored once, answered back with the rule, the reason, the code it governs, and — the part no doc tool does — **a warning that the code moved and the rule might be stale.** That last line is the whole product.

## Quickstart

```bash
pip install fux-engine        # the CLI, zero third-party deps

cd your-project
fux init                      # scaffold .fux/ + agent pointers
fux new formula day-pnl       # scaffold a rule; fill Rule: / Why: / Edge cases:
fux build                     # regenerate INDEX + graph        ($0)
fux why day-pnl               # explain a rule + the code it governs
fux how "which rules govern a file"   # fux explains fux → the exact command ($0)
```

> **Full agent integration** (Claude Code / Codex / Copilot skills + hooks): clone and run `./install.sh` instead — it wires `~/.claude/fux`, the skills, and the SessionStart/PostToolUse/Stop hooks.

Complete, example-driven guide: [docs/guide.md](docs/guide.md) · full command reference: [docs/cli.md](docs/cli.md).

## Explain it like I'm five

Your code is a giant LEGO city. The *reasons* things are built a certain way — why the bridge is red, why the towers go up before the walls — usually live in one builder's head. When they go home, nobody remembers why.

**Fux is a notebook for those reasons.** You write each important one down once, and Fux glues a tiny one-line table of contents to the cover, so your helper can flip straight to the right page instead of searching the whole city. It also draws a map of which notes belong to which buildings — and checks that the notes still match the city, telling you when a building changed but its note didn't. And it does all that for free, without phoning anyone for help.

## Why it's different

It's not another wiki or memory service. The difference is a set of *properties*, not features:

- **Deterministic.** Every maintenance command is shell / AST / parse. Same inputs, same output, every time — your knowledge layer never hallucinates because it never guesses.
- **Verifiable.** `fux seal` binds a rule to an AST fingerprint of its code; `fux check` tells you when the *structure* drifted (not just the mtime). Rules carry `check:` invariants and worked `examples:` that actually run.
- **`$0` and zero-dependency.** Stdlib-only Python, no third-party deps, no API key required to read, write, or serve. Portable as a tarball, auditable line by line.
- **Agent-native.** Typed frontmatter, machine-readable output, an MCP server, and prompt hooks — built so an agent can call it *and verify the result*, not just read prose.

The "so what" chain: deterministic → so your context never hallucinates → so an agent can act on it safely → so you can put the result in front of an auditor. That last clause is the one a memory tool can't say.

## The constitution — rules neither you nor your agent can break by accident

Ordinary rules document and warn. A **constitutional** rule is one a developer *or* an AI agent cannot break without it being caught and named.

- **Debate → ratify.** A principle becomes law through **`/fux debate`** — a skill that spawns two sub-agents to argue it freely (blind first passes, anti-sycophancy gates, no assigned sides) and escalates to **you** as tie-breaker. **`fux ratify`** then makes it tamper-evident: it stamps a `content_seal` + the debate's `debate_hash` and records the rule in a committed **`.fux/constitution.lock`**, so any later in-place edit, add, or delete is an always-blocking `tampered` finding. To change a constitutional rule you must supersede it — the amendment article governs its own amendment, and has already amended *itself*.
- **Critique before it lands.** **`fux critic`** checks a change against the constitution: a deterministic pass first (money / PII / numbers — decided by a `check:` or seal, *never* sent to an LLM, and they hard-block), then the host agent self-critiques the judgment principles (tone, completeness) with its own tokens. The judgment critic is **advisory-first** — a suggestion, not a blocker — so it earns trust before it interrupts.
- **A real wall.** Every merge to `main` requires two checks — `fux gate` (integrity) and `ai-review` (a *separate reviewer identity* that refuses when reviewer == author). New branch → PR → both green → merge is the only path, for everyone including the owner. Branch protection lives outside the repo, so a weekly drift audit fails loudly if it ever changes. ([details](docs/constitution-enforcement-handoff.md))

Crucially, the debates and critiques spend the *host session's* tokens — **Fux's own code never calls an LLM** (a guard test proves it) — and the whole layer is opt-in: `tier` defaults to `standard`, so adopting Fux changes nothing until you ratify your first rule.

> The bet: once verifiable, governed code-context is normal, shipping an AI change against undocumented, unchecked invariants will look as reckless as deploying without tests.

## How it works

You maintain **only** the source frontmatter. Everything else is derived, lazily, for `$0`:

```
Tier 0  agent pointers ........... CLAUDE.md, AGENTS.md, Copilot instructions
Tier 1  .fux/out/INDEX.md ........ ~1 line/rule, read FIRST        ← cheap
Tier 2  .fux/rules/<id>.md ....... opened ONLY when relevant       ← lazy
Tier 3  .fux/out/{rules,graph}.json  machine lookup + browsing
```

Your agent reads the one-line index first and opens a full rule only when it's relevant, so lookups run **~5–10× cheaper and more correct** on every later session — and you don't take that on faith: `fux savings` prices the win in real dollars from your own file sizes. Three hooks keep it live: SessionStart injects the index, PostToolUse warns when an edited file's rule drifted, Stop validates before the turn ends.

The **graph** merges your rules with code symbols and call edges across **Python** (stdlib `ast`) and **JS/TS, Go, Rust** (brace-heuristic, or real tree-sitter ASTs via the optional `[ast]` extra), with community clustering and **PageRank centrality** for architectural chokepoints. The interactive `graph.html` "Solar Terminal" viewer desaturates code to graphite while knowledge nodes ignite amber and `governs` links stream across as glowing threads — so *which rule governs which code* is impossible to miss. It stays smooth at thousands of nodes (a hand-rolled Barnes–Hut layout, viewport culling, pre-rendered glow), collapses each community into one labelled blob when you zoom out, and a **Coverage** lens warms the governed code so the ungoverned grey is the finding. Rules whose **AST seal has drifted pulse red** and constitutional rules wear a crown — straight from `fux check`, never invented. Still one self-contained offline file, zero dependencies.

<details>
<summary><strong>The full command surface</strong> (authoring · verification · governance · runtime)</summary>

```bash
fux check --fix                # validate; repair mechanical drift           ($0)
fux why day-pnl --history      # how a rule's *why* evolved, via git
fux refs src/aggregator.py     # which rules govern this file
fux recall "how is day P&L computed" --hybrid  # BM25F; RRF-fuse lexical+semantic+graph
fux seal --all                 # bind rules to an AST fingerprint of their code
fux debate "<rule>" (skill)    # two-agent free debate → you ratify the result
fux ratify <id> --by Arpit     # ratify a constitutional rule (tamper-evident)
fux constitution               # status: what's law, what it governs, debates, violations
fux critic "<change>"          # critique a change vs principles before it lands ($0)
fux coverage                   # % of important files with a governing rule
fux verify --fuzz              # run invariant `check:`; boundary-fuzz div-by-zero
fux mine                       # surface candidate rules latent in the code (drafts)
fux savings "how is day P&L computed"  # measured token + dollar cost win
fux lint                       # rule quality: missing why / code_refs / edges
fux stats                      # knowledge-health dashboard + score
fux gate --install             # wire a git pre-commit enforcement hook
fux mcp                        # serve the substrate to agents over MCP (stdio)
fux serve                      # local dashboard over the generated views
fux import docs/               # migrate existing markdown → narrative entries
fux query / path / explain     # graph traversal: "how does X relate to Y"
```
</details>

### Layered rules — maintain once, inherit everywhere

```
effective ruleset = ~/.claude/fux/global/   (cross-project best practices)
                  ⊕ ~/.claude/fux/packs/*    (opt-in shareable domain packs)
                  ⊕ ./.fux/rules/            (this project's domain rules)
```

`project` overrides `pack` overrides `global`, and `fux check` flags conflicts instead of silently shadowing. Packs are optional — a single project can keep everything version-controlled in its own `.fux/`, beside the code it governs.

## The `$0` guarantee

Every maintenance command is shell / AST / parse — **no LLM calls, ever.** The only paths that touch a model are the authoring skills (`debate`, `plan`, `adr`, and the judgment critic), and they ride the session you're already in — no background spend. The headless AI critic ships behind an opt-in `[critic]` extra; the default install stays model-free.

**Honest limits.** Fux doesn't write your rules for you — `fux mine` drafts candidates, but the *why* is yours. The constitution governs where trust lives (money, PII, audit), not every line — making everything constitutional would crush your velocity, and the design says so. And branch protection lives in GitHub, so Fux can *watch* it but can't *seal* it; that one link is honest about being outside its reach.

## What's new

- **v0.9.0 — web → draft rules, and fux explains fux.** `/fux scrape <url>` lets the agent fetch a page (HTTP, escalating to **CDP** for client-rendered shells — port configurable by flag/env/config, default `:9299`) and draft governed rules with `source`/`fetched`/`source_hash` provenance — always `status: draft`, never auto-active, regulatory drafts flagged *verify-against-source*. `fux how "<question>"` dogfoods the engine: it runs the same `$0` BM25F recall over fux's **own** command registry and returns the exact command for the task (`fux how "which rules govern a file"` → `fux refs <path>`). And one **command registry** now drives a grouped `fux --help`, `fux help <cmd>`, *and* the generated `docs/cli.md` — so help and docs can't drift. The maintenance path stays model-free **and offline** (a guard test proves it).
- **v0.8.0 — Solar Terminal viewer: fast, legible, governance-aware.** A hand-rolled Barnes–Hut layout keeps `graph.html` smooth at thousands of nodes (~38 ms → ~5 ms/frame on a ~2,400-node graph); zoom out and each community collapses to one labelled blob. A **Coverage** lens warms the governed code so the ungoverned grey is the finding, and rules whose **AST seal drifted pulse red** (constitutional ones wear a crown) — straight from `fux check`, never invented. Still one offline file, zero deps.
- **v0.7.0 — optional cage token-savings receipt.** Per-session savings attribution from the Cage ledger, plus a docs reorg. `$0`, no engine change.
- **v0.6.0 — the wall is real.** Merging to `main` requires `fux gate` + `ai-review` (separate reviewer, refuses when reviewer == author). `fux ratify` opens its own gated PR; a weekly drift audit catches protection changes. ([details](docs/constitution-enforcement-handoff.md))
- **v0.5.0 — advisory-first critic + first amendment.** The judgment critic suggests rather than blocks; `fux constitution` gains debates + violations by severity; the amendment article amended *itself* by supersession.
- **v0.4.0 — the constitutional-app engine.** `tier`, `/fux debate`, `fux ratify`, `.fux/constitution.lock`, `fux critic`, and the deterministic/judgment split. Opt-in and `$0`.

## The name

Named after *Johann Joseph Fux*, author of *Gradus ad Parnassum* (1725) — the counterpoint treatise every composer learned the rules from. A tool that codifies and enforces rules, named after the man who wrote *the* rulebook. The name is deliberate (yes, I kept it). Sits beside `wagner`, `bach`, `orff`.

Fux **unifies and replaces** three things a project usually runs separately — the structural graph, cross-session memory, and the narrative docs — and adds the **business-rules and governance layer** none of them held. See [docs/fux-plan.md](docs/fux-plan.md).

---

If the red-pipe problem is real in your codebase, try Fux on one rule — `pip install fux-engine`.

## License

MIT — see [LICENSE](LICENSE).
