Metadata-Version: 2.4
Name: flywheel-verify
Version: 0.3.5
Summary: The one platform: routing, verification, the lane layer, memory/context/catalog, and the closed verified-inference loop.
Author: Zain
License-Expression: FSL-1.1-MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: signing
Requires-Dist: cryptography; extra == "signing"
Provides-Extra: monitor
Requires-Dist: psutil; extra == "monitor"
Provides-Extra: local
Requires-Dist: torch; extra == "local"
Requires-Dist: transformers; extra == "local"
Requires-Dist: peft; extra == "local"
Requires-Dist: trl; extra == "local"
Requires-Dist: accelerate; extra == "local"
Requires-Dist: datasets; extra == "local"
Requires-Dist: bitsandbytes; extra == "local"
Requires-Dist: safetensors; extra == "local"
Requires-Dist: sentencepiece; extra == "local"
Dynamic: license-file

# Flywheel

> One platform: routing, verification, the lane layer, the closed loop, and the
> projected world. The native desktop surface for accountable AI infrastructure.

Flywheel is the engine and native client for a verified-inference loop: a model
perceives only through witnessed organs, acts only through a gate it cannot
talk past, journals everything, and verifies its own work by re-perceiving.

The flagship tools (gather, crucible, index, forum, learn, telos) are lanes
inside Flywheel, each a provisioned, health-checked organ reachable through one
surface. Every agent tool call carries a sealed, chain-linked receipt a third
party re-verifies offline.

**Proof before trust.**

## What is in this repo

This is a monorepo containing both halves of the platform:

- **`harness/`** is the Python engine: the gateway (localhost HTTP API), the
  agent loop, the receipt discipline, the lane layer, the verified-inference
  loop, the tool-call receipt system. Zero runtime dependencies (stdlib only).
- **`desktop/`** is the Flutter native client: 24 views, 50 widgets, zero
  webview embedding. Talks to the gateway over localhost. Launches a bundled
  frozen engine by absolute path on a clean machine (no Python, no PATH, no
  network).
- **`site/`** is a dev/CI fallback browser shell (not the primary UI).

## Run it now

Start the gateway (the engine keeps the loop, receipts, lanes, and routing):

```
flywheel app --port 8799
```

The **native surface is Flywheel Desktop**. From a dev checkout:

```
cd desktop
flutter run -d windows --release
```

The gateway also serves a `/site/index.html` shell as a dev/CI fallback.

## The lane model

Flywheel encompasses the tool family. Each flagship is a lane:

| Lane | Repo | Role |
| --- | --- | --- |
| gather | [gather](https://github.com/HarperZ9/gather) | Research intake + provenance receipts |
| crucible | [crucible](https://github.com/HarperZ9/crucible) | Falsifiable verification (MATCH / DRIFT / UNVERIFIABLE) |
| index | [index](https://github.com/HarperZ9/index) | Workspace map + symbol graph + context envelopes |
| forum | [forum](https://github.com/HarperZ9/forum) | Witnessed causal ledger + model-agnostic routing |
| learn | [learn](https://github.com/HarperZ9/learn) | Accountable learning forge |
| telos | [telos](https://github.com/HarperZ9/telos) | The reconciliation lane |

Check their health through one surface:

```
flywheel lanes
flywheel lanes --probe    # live MCP handshake per lane
```

## The receipt discipline

Every agent tool invocation carries a sealed receipt binding:

- **what the tool was** (capability class: read / write / exec / external-mcp)
- **what it was allowed to do** (admission decision from the gate)
- **what it actually did** (witnessed args + output sha256 digests, never raw content)
- **whether a stranger can re-walk it** (offline-verifiable, chain-linked)

Receipts compose into a transitive-witness DAG where a drifted action degrades
exactly its downstream dependents. The five flagships emit organ-bundle entries
on a shared proof-surface spine so cross-tool receipts compose end-to-end.

## The organizational learning loop

The layer above audit. The receipt discipline records what happened at machine
resolution. The learning loop feeds forward: it derives lessons from witnessed
divergences (an allowed action that rolled back, a memory whose source drifted,
a graded failure), stores them in a durable, hash-chained, append-only memory,
and surfaces recurring patterns as improvement candidates for human admission.
A lesson is not a note an operator wrote; it is a claim bound by hash to its
evidence, re-checkable offline, fail-closed when the evidence is gone. See
[docs/LESSON-LOOP.md](docs/LESSON-LOOP.md).

## Offline-first

The Flutter desktop GUI launches a bundled engine by absolute path and serves
its UI menu on localhost only. No external web address is contacted to show the
GUI. The gateway serves `/api/*` and the UI on `http://127.0.0.1:8799`.

## Install

```
pip install flywheel-verify
flywheel up
```

`flywheel-verify` is the PyPI distribution name (the bare `flywheel` name is an
unrelated package); the installed command is `flywheel`. Zero runtime
dependencies, stdlib only.

**No model download required.** The engine is ready for real work the moment
it installs: point it at any hosted provider you hold a key for (the roster
reports credential presence only, never values) and every route carries the
same receipt discipline. Local models get the same support and stay optional: ollama
needs no extras at all (the gateway talks to it over HTTP), the published
[14B](https://huggingface.co/zaindanaharper/flywheel-local-coder-14b) and
[32B](https://huggingface.co/zaindanaharper/flywheel-local-coder-32b) weights
are separate downloads for when you want them, and the local HF
serve/training stack installs with `pip install "flywheel-verify[local]"`.
Receipt signing and egress monitoring have their own extras (`[signing]`,
`[monitor]`); receipt verification stays stdlib-only.

Subscription sign-in is wired in: `flywheel auth login <provider>` runs a
stepwise flow (documented PKCE where the provider sanctions it, the
provider's own official tool where it does not), stores the token in the OS
credential store, and the router picks it up with no further setup. See
[GETTING-STARTED.md](GETTING-STARTED.md).

Or from source:

```
git clone https://github.com/HarperZ9/flywheel.git
cd flywheel
pip install -e .
python scripts/run_harness_cli.py app --port 8799
```

The native desktop app ships as a Windows installer with the engine bundled
(no Python needed): download `Flywheel-Setup-<version>-x64.exe` from the
[releases page](https://github.com/HarperZ9/flywheel/releases) and verify it
against the release's `SHA256SUMS.txt`.

## Documentation

- [QUICKSTART.md](QUICKSTART.md): first ten minutes
- [WALKTHROUGH.md](WALKTHROUGH.md): guided tour
- [docs/LESSON-LOOP.md](docs/LESSON-LOOP.md): the organizational learning loop (architecture)
- [docs/GUIDE-LESSON-LOOP.md](docs/GUIDE-LESSON-LOOP.md): the organizational learning loop (full guide and spec)
- [docs/ASSESSMENT-AGENTIC-SECURITY-2026-08.md](docs/ASSESSMENT-AGENTIC-SECURITY-2026-08.md): Flywheel against the July 2026 agentic security convergence
- [CREDO.md](CREDO.md): the belief

## License

FSL-1.1-MIT (Functional Source License). See [LICENSE](LICENSE).
