Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/rules/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ inference.
- **The distributed inference path is not implemented.** `runtime.py` never assigns
`self.inference_backend` anything but `EchoBackend`. The working path is the
non-split one that proxies to Ollama. Do not describe split inference as working,
and do not wire `LocalBoundaryEngine` into anything — it is a 155-word vocabulary
and do not wire `LocalBoundaryEngine` into anything — it is a 120-token vocabulary
over seeded random matrices.
- **Hardware figures are measured, never assumed.** Registration once hardcoded
16 GB of VRAM for every node, so matchmaking filtered against fiction. Every probe
Expand Down
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,8 @@ lower its budget so the ratchet holds.

**The distributed inference path is not implemented.** `packages/node/src/node/runtime.py`
never assigns `self.inference_backend` anything but `EchoBackend`. `LocalBoundaryEngine`
uses a 155-word vocabulary and seeded random matrices. The working inference path is
uses a 120-token vocabulary (116 words plus 4 special tokens) and seeded random
matrices. The working inference path is
the non-split one that proxies to Ollama. Don't describe split inference as working.

**`VERIFY.md` step 3's known-issues table is EMPTY, and the greps still return
Expand Down
423 changes: 266 additions & 157 deletions README.md

Large diffs are not rendered by default.

37 changes: 35 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,39 @@
# ROADMAP — v1

> ## CLOSED — 2026-08-21
>
> **The project is archived and this roadmap is no longer a plan.** It is kept as the
> record of what was built and in what order. Nothing below will be worked on.
>
> It ended because two load-bearing premises failed while the engineering was
> succeeding: the economics do not close (~15× against commodity pricing,
> [D2](docs/decisions/D2-economics.md)), and NAT traversal turned out not to be a
> differentiator for the single-machine case that is actually solved — relocating the
> whole claim onto cross-party pooling, for which there was never any evidence
> (`docs/PREMISES.md` P1/P2). 1.5 and D7 below stayed open to the end, and 1.5 was the
> product. See the root [`README.md`](README.md) for the full account.
>
> **Two findings recorded at closure, both from reading the code rather than a failing
> test:**
>
> - **The `v1.0.1` tag names a tree that declares itself `1.0.0`.** All four packages
> agree with each other at `25fe60c`, so `test_every_package_declares_the_same_version`
> passes — it compares the packages to *each other*, never to the tag. V3 below fixed
> "the release shipped two version numbers" by converging them on the *previous* one.
> Deliberately not bumped now: a tree claiming `v1.0.1` that is not the released
> `v1.0.1` is the same confusion in a different hat.
> - **A whole node execution path is dead code.** `Runtime._worker_loop` →
> `InferenceBackend` → `ArtifactStore` is never fed: nothing in `src` enqueues onto
> `task_queue`, `inference_backend` is only ever `EchoBackend`
> (`packages/node/src/node/runtime.py:282`), and `OllamaBackend` is never constructed
> outside a test. The live path is `api/inference.py` → `clients/ollama.py`, a
> different class. `test_end_to_end_pipeline` feeds the queue by hand — an end-to-end
> test of a path production never takes.

Status: **Stages 0–4, C and D are complete. Released as `v1.0.1` on 2026-08-17, with
CI green on all ten jobs (Linux/macOS/Windows × Python 3.11–3.14) at `25fe60c`.
CI green on all ten jobs (Linux/macOS/Windows × Python 3.11, 3.12 and 3.14, plus a
fresh-clone job) at `25fe60c` — 3.13 is not in the matrix, and the range notation used
here previously implied four interpreters where `.github/workflows/ci.yml` names three.
1.5 is half earned — a second machine served a real request over the mesh on
2026-08-11, but not across a real NAT. D7 is open. W1–W10 are done; W7 is done in
code and unexercised on real hardware. V1–V3 closed the Windows CI failure that had
Expand Down Expand Up @@ -152,7 +184,8 @@ cutting it means this isn't v1. I concluded it is not, for four reasons:
expands the catalogue; it is not what makes the exchange work.

2. **What exists today is a simulation, not an implementation.** `LocalBoundaryEngine`
is a 155-word vocabulary and two seeded `random.gauss` matrices; "speculative
is a 120-token vocabulary (116 words plus 4 special tokens, against a declared
`vocab_size` of 32,000) and two seeded `random.gauss` matrices; "speculative
candidates" are `(prev * 7 + 13) % vocab_size`. Real sharding needs real weights,
real tensor ops, and a real runtime. The distance from here to there is a
rewrite, not a fix. Betting v1 on it means v1 does not ship.
Expand Down
32 changes: 22 additions & 10 deletions STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@
<!-- Regenerate with: python3 scripts/generate_status.py -->
<!-- Every value below came from a command run at the timestamp shown. -->

**Generated:** 2026-08-17 05:19 UTC
**Generated:** 2026-08-21 13:36 UTC
**Test status:** PASSING

## Tests

| Suite | Status | Passed | Failed | Skipped | Time |
| --- | --- | --- | --- | --- | --- |
| Scheduler | PASS | 397 | 0 | 0 | 13.39s |
| Node | PASS | 260 | 0 | 1 | 3.85s |
| Root E2E | PASS | 249 | 0 | 0 | 28.35s |
| Scheduler | PASS | 397 | 0 | 0 | 11.51s |
| Node | PASS | 260 | 0 | 1 | 3.10s |
| Root E2E | PASS | 249 | 0 | 0 | 26.90s |
| **Total** | **PASSING** | **906** | **0** | **1** | |

Reproduce:
Expand All @@ -26,12 +26,24 @@ Reproduce:

## Git

- **Last commit:** `214bcb8` docs: record the real state, including what we cannot see
- **Author / date:** Claude — 2026-08-17 05:18:43 +0000
- **Branch:** claude/v1-wrap-up-checklist-6uadua
- **Total commits:** 52
- **Last commit:** `e5d1e7c` docs: record the real state, including what we cannot see (#2)
- **Author / date:** attu308 — 2026-08-17 11:35:15 +0530
- **Branch:** claude/project-closure-readme-4iwry3
- **Total commits:** 53
- **Remote:** origin https://github.com/Epichlo/Public-Intelligence (fetch)
- **Working tree:** clean
- **Working tree:** 9 uncommitted change(s)

```
M .claude/rules/node.md
M CLAUDE.md
M README.md
M ROADMAP.md
M experimental/README.md
M packages/node/README.md
M packages/scheduler/README.md
M packages/shared/README.md
M packages/website/README.md
```

## CI

Expand All @@ -47,7 +59,7 @@ _Measured, not asserted. Re-run to refresh._

| Repo | Remote | Branch | Tracking |
| --- | --- | --- | --- |
| root | `https://github.com/Epichlo/Public-Intelligence` | claude/v1-wrap-up-checklist-6uadua | origin/claude/v1-wrap-up-checklist-6uadua |
| root | `https://github.com/Epichlo/Public-Intelligence` | claude/project-closure-readme-4iwry3 | **none** |

- **`.gitmodules`:** absent, which is correct — `packages/` are ordinary directories since the 2026-08-04 monorepo migration, and CI's fresh-clone job asserts this file does not come back.
- **root venv interpreter:** Python 3.11.15
Expand Down
7 changes: 4 additions & 3 deletions experimental/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ while an unimportable quarantined test still fails the gate.
| Module | Feature | Lines |
|---|---|---|
| `transport.py` | Shared-memory IPC, backpressured tensor streaming | 541 × 2 |
| `local_boundary.py` | Embedding/unembedding across a split boundary — a 155-word vocabulary and seeded `random.gauss` matrices, **not a model** | 378 × 2 |
| `local_boundary.py` | Embedding/unembedding across a split boundary — a 120-token vocabulary (116 words + 4 special) against a declared `vocab_size` of 32,000, and seeded `random.gauss` matrices, **not a model** | 378 × 2 |
| `boundary_engine.py` | Re-export shim for the above | 5 × 2 |
| `kv_cache.py` | KV-cache checkpointing and restitching | ~98 × 2 |
| `quantization.py` | FP8/FP4 activation compression | 49 × 2 |
Expand Down Expand Up @@ -122,8 +122,9 @@ of that returns.

## If you are reading this because you want to build on it

Don't, yet. `LocalBoundaryEngine` in particular is a simulation: a 155-word
vocabulary and two seeded random matrices. It produces plausible-looking tensors and
Don't, yet. `LocalBoundaryEngine` in particular is a simulation: a 120-token
vocabulary — 116 words plus 4 special tokens, against a declared `vocab_size` of
32,000 — and two seeded random matrices. It produces plausible-looking tensors and
no inference happens. Returning its output to a caller as a completion is precisely
the bug ROADMAP N1 removed, where `token_556` was served as the capital of France
with HTTP 200.
52 changes: 40 additions & 12 deletions packages/node/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Public Intelligence Node

**Archived on 2026-08-21 along with the rest of the project. See the root
[`README.md`](../../README.md) for what worked, what failed, and why it stopped.**

A Public Intelligence Node is a compute worker that registers with the Scheduler,
advertises the models Ollama actually has, executes inference locally, and holds an
authenticated Zenoh mesh session so it is reachable even from behind NAT — it dials
Expand All @@ -9,8 +12,25 @@ Part of the **`public-intelligence` monorepo** (Scheduler, Node, and Website wer
into `packages/` on 2026-08-04). This document describes `packages/node`.

Version 1 establishes the complete lifecycle of a compute node. The distributed
(split) inference path is **not** implemented; the working path proxies to Ollama, and
that is the only backend `runtime.py` assigns.
(split) inference path is **not** implemented.

## Which path actually serves a request

Worth stating precisely, because this file got it wrong until 2026-08-21. It used to say
the Ollama proxy was "the only backend `runtime.py` assigns". It is not a `runtime.py`
backend at all, and there are two separate Ollama integrations:

- **The live path** is the FastAPI route `src/node/api/inference.py`, which calls
`clients/ollama.py` (`OllamaClient`). This is what serves every real request.
- **The `backends/` abstraction is dead code in production.** `runtime.py:282` assigns
`self.inference_backend` an `EchoBackend` and nothing else, ever; `OllamaBackend` is
never constructed outside a test file. `Runtime._worker_loop` consumes a `task_queue`
that **nothing in `src` ever enqueues onto** — only tests do, including the one named
`test_end_to_end_pipeline`, which is an end-to-end test of a path production never
takes.

So `backends/base.py` is an interface with one implementation and zero production
callers. It was written to make a second backend survivable and never got one.

---

Expand Down Expand Up @@ -86,20 +106,28 @@ A local end-to-end text demonstration is also available in [examples/demo.md](ex

## Version

Current Release

```
v1.0.0
```
`pyproject.toml` declares **`1.0.0`**. The last release tag is **`v1.0.1`** — the two do
not match. That discrepancy is recorded rather than papered over in the root
[`README.md`](../../README.md); the version-parity ratchet compares the four packages to
each other, never to the tag that names them.

---

## Future Work
## What was never finished

There is no future work — the project is archived. What did not get done:

- **A proven real-NAT path.** The mesh works on a LAN, and on 2026-08-11 a node on a
second physical machine served a real request over it. Both machines were on adjacent
subnets of one network, so **no NAT boundary was ever crossed** — and NAT traversal was
the differentiator the whole project rested on.
- **Split / distributed inference.** Cut from v1; the node runs whole models, never
shards. The gateway answers `501` rather than fabricating a completion.
- **A second inference backend.** `backends/base.py` exists to make one survivable and
never got one, so the abstraction is untested against reality.

Automatic hardware discovery shipped in v1 — the installer probes CPU, RAM, and GPU,
and registration advertises the measured figures rather than a hardcoded guess. What is
**not** in v1: split/distributed inference (the node runs whole models, not shards), and
a proven real-NAT path (the mesh works on a LAN; crossing a real NAT is unverified).
Automatic hardware discovery *did* ship: the installer probes CPU, RAM and GPU, and
registration advertises the measured figures rather than a hardcoded guess.

---

Expand Down
37 changes: 24 additions & 13 deletions packages/scheduler/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Public Intelligence Scheduler

**Archived on 2026-08-21 along with the rest of the project. See the root
[`README.md`](../../README.md) for what worked, what failed, and why it stopped.**

The Scheduler is the control plane. It maintains a registry of compute nodes, receives
heartbeats over an authenticated Zenoh mesh, matchmakes requests to a node that has the
requested model, dispatches over the mesh (which is how a node behind NAT is reachable),
Expand Down Expand Up @@ -91,25 +94,33 @@ uvicorn scheduler.main:app --reload

## Version

Current Release

```
v1.0.0
```
`pyproject.toml` declares **`1.0.0`**. The last release tag is **`v1.0.1`** — the two do
not match. That discrepancy is recorded rather than papered over in the root
[`README.md`](../../README.md); the version-parity ratchet compares the four packages to
each other, never to the tag that names them.

---

## Roadmap
## What was never finished

Request routing, mesh dispatch, and OpenAI-compatible serving — once listed here as
future work — shipped in v1. What is **deliberately not** in v1, and is not pretended
to be (see the root `README.md` and `docs/PREMISES.md`):
There is no roadmap — the project is archived. Request routing, mesh dispatch and
OpenAI-compatible serving all shipped. What did not, and was never pretended to (see the
root [`README.md`](../../README.md) and [`docs/PREMISES.md`](../../docs/PREMISES.md)):

- **A proven real-NAT path.** The mesh works on a LAN; crossing a real NAT boundary was
never demonstrated (`ROADMAP.md`, 1.5) — and it was the differentiator the project
rested on.
- **Split / distributed inference** (sharding one model across nodes). Cut from v1; the
gateway answers `501`, it does not fabricate a completion.
- **A proven real-NAT path.** The mesh works on a LAN; crossing a real NAT boundary is
unverified (`ROADMAP.md`, 1.5).
- **Any payout / marketplace.** Credits are an accounting unit, not a currency (D2).
gateway answers `501`, it does not fabricate a completion. It used to answer `200` with
text from a toy engine.
- **`/v1/batch`.** Authenticated and tenant-scoped, because those were real fixes to a
real hole — but it answers `501` and dispatches nothing.
- **Any payout / marketplace.** Credits are an accounting unit, not a currency
([D2](../../docs/decisions/D2-economics.md)).
- **Execution integrity beyond admission control.** Canaries catch a host running *no*
model; nothing catches one running the *wrong* one.
- **Revocable tokens, content filtering, real quotas, or backups.** None of these exist.
JWTs are stateless by design; the mitigations are a TTL cap and key rotation.

---

Expand Down
3 changes: 3 additions & 0 deletions packages/shared/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# packages/shared

**Archived on 2026-08-21 along with the rest of the project. See the root
[`README.md`](../../README.md) for what worked, what failed, and why it stopped.**

The stated follow-up to the 2026-08-04 monorepo migration (ROADMAP C8), and the
answer to the question `CLAUDE.md` has been asking contributors to hold in their
heads: *"before adding a module, check whether its twin exists; if you change one of
Expand Down
77 changes: 50 additions & 27 deletions packages/website/README.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,72 @@
# Public Intelligence Website

The official website for **Public Intelligence** — a globally distributed, community-owned AI infrastructure.
**Archived on 2026-08-21 along with the rest of the project. See the root
[`README.md`](../../README.md) for what worked, what failed, and why it stopped.**

The website communicates the project's vision, architecture, research, roadmap, and development progress.
The Next.js front end for **Public Intelligence**: a dashboard over a running Scheduler,
an interactive playground against its OpenAI-compatible gateway, and the public pages
that describe the project.

## Demo
Part of the **`public-intelligence` monorepo** (the Scheduler, Node and Website were
merged into `packages/` on 2026-08-04). This document describes `packages/website`.

A walkthrough of the first working prototype is available on YouTube:
[Public Intelligence v1 Demo](https://www.youtube.com/watch?v=cGDWpOArB5I)
> **This README described the project as "a globally distributed, community-owned AI
> infrastructure" until 2026-08-21.** That was never true and had been explicitly decided
> against: [D6](../../docs/decisions/D6-is-there-a-network.md) records that there is no
> network and one will not be operated, and [D2](../../docs/decisions/D2-economics.md)
> that the marketplace economics do not close. The site's own landing page
> (`src/components/landing/unredacted-truth.tsx`) had been corrected; this file had not.
> It is fixed here because a stale README is how a claim outlives the decision that
> retired it.

This video demonstrates the end-to-end integration of the Website, Scheduler, Node, registration, heartbeats, and local inference.
---

## Tech Stack
## Pages

- Next.js
- TypeScript
- Tailwind CSS
Nine routes under `src/app`:

## Pages
| Route | What it does |
|---|---|
| `/` | Landing page, including the "Unredacted Truth" panel listing what is and is not proven |
| `/dashboard` | Live view of registered nodes, telemetry and credit, proxied to the Scheduler |
| `/playground` | Interactive chat against `/v1/chat/completions`, with a bearer token you supply |
| `/status` | Fleet and request status |
| `/vision`, `/architecture`, `/research`, `/roadmap`, `/contribute` | Static project pages |

`/dashboard`, `/playground` and `/status` are the functional ones — they proxy to a
running Scheduler and do nothing useful without one. The earlier version of this file
listed only the five static pages and omitted all three.

- Home
- Vision
- Architecture
- Research
- Roadmap
- Contribute
## Tech stack

- Next.js 16 / React 19
- TypeScript
- Tailwind CSS

## Development

```bash
npm install
npm run dev
npm run dev # http://localhost:3000
```

Visit:
The dashboard and playground need a Scheduler to talk to; see
[`packages/scheduler`](../scheduler/README.md).

```
http://localhost:3000
```
## Version

`package.json` declares **`1.0.0`**. The last release tag is **`v1.0.1`** — the two do not
match, and that discrepancy is recorded rather than papered over in the root
[`README.md`](../../README.md) ("A ratchet that cannot see the thing it names"). The
version-parity ratchet compares the four packages to each other, never to the tag.

## Related Repositories
## Related components

- Public Intelligence Scheduler
- Public Intelligence Node
Part of the `public-intelligence` monorepo, alongside `packages/scheduler` (control
plane), `packages/node` (host agent) and `packages/shared`. They are directories, not
separate repositories — the pre-monorepo standalone repos are archived and tagged
`pre-monorepo-2026-08-04`.

## License
## Licence

Apache 2.0
Apache 2.0
Loading