Metadata-Version: 2.4
Name: fux-engine
Version: 0.30.0
Summary: Fux — rank organizational knowledge from a small index committed to git; fetch content from the systems that own it; verify freshness at answer time.
Project-URL: Homepage, https://github.com/arpitarya/fux
Project-URL: Repository, https://github.com/arpitarya/fux
Project-URL: Bug Tracker, https://github.com/arpitarya/fux/issues
Author-email: arpit arya <arpitarya.me@gmail.com>
License: MIT
License-File: LICENSE
Keywords: adr,agent,claude,codebase,frontmatter,index,knowledge,llm,search
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Fux

**Deterministic knowledge retrieval for AI-assisted codebases — rank from a
small git-carried index, fetch content from the systems that own it, verify
at answer time.**

> **Status (2026-08-10): T0 slice — `ingest` + `ask` work on this repo.**
> `src/fux/` exists. From a configured directory:
> ```bash
> fux ingest              # builds the committed .fux/index/*.jsonl
> fux ask "your question" # scans it, ranks with BM25F, cites the source file
> ```
> No accelerator yet (scan-only, ~100–200 ms class queries — correct M1
> behavior, not a bug) and no dense/graph query lanes (M2/M3). The v0.26
> engine and its docs are archived under
> [`archive/v0.26/`](archive/v0.26/), reference-only. The new architecture
> is specified in
> [`docs/paper/the-fux-index-paper.md`](docs/paper/the-fux-index-paper.md)
> (§4–§6 knowingly stale until M6) and built against
> [`docs/PLAN.md`](docs/PLAN.md).
>
> **The pruning gate closed (2026-08-09): FAIL.** Keeping only each
> document's top-*k* terms was measured, twice, against a corpus that could
> actually test it — no selector came within 35.9 points of preserving
> candidate recall at a 6 % budget. The committed index carries **full
> postings**, permanently — [ADR-0003](docs/adr/0003-pruning-criterion-rerun.md).

## The idea

- **Sources own content.** Repo docs stay in git; Confluence pages stay in
  Confluence. Fux never keeps a durable copy (except explicit per-source
  `snapshot` policy).
- **Git carries the index** — doc-major, sharded, human-readable JSONL;
  full per-document postings, dense binary codes, an extracted link graph,
  and a source ledger, one line per document, sorted and content-sharded so
  git itself diffs and merges it —
  [`docs/compare/index-format.compare.md`](docs/compare/index-format.compare.md).
- **Answers verify themselves.** Rank in the index, fetch the cited
  documents live (through a version-keyed cache), re-score passages on the
  fetched bytes, cite the fresh sha. (The refer plane is M4; M1's `ask`
  cites straight from the committed index.)
- **Laws:** $0 default · stdlib-only · byte-deterministic · offline by
  default · one ADR per feature, every rule referenced.

## Reading order

1. [`docs/paper/the-fux-index-paper.md`](docs/paper/the-fux-index-paper.md) — architecture + falsifiable predictions
2. [`docs/compare/index-format.compare.md`](docs/compare/index-format.compare.md) — the committed format, measured
3. [`docs/PLAN.md`](docs/PLAN.md) — milestones M0–M8
4. [`docs/adr/0004-index-format.md`](docs/adr/0004-index-format.md) — the frozen M1 schema
5. [`examples/playground/PLAYGROUND.md`](examples/playground/PLAYGROUND.md) — a 20-doc fixture corpus to try it on
6. [`docs/WORKLOG.md`](docs/WORKLOG.md) — the running build log

License: MIT.
