# Start Here

> What this repo actually contains, the single fastest read order, the five entry points to open first, and the core vocabulary (N+1 outcome, sovereign artifact, governed delta, quality floor, anti-capture cap) a new reader must know.

- Repository: The-AI-Alliance/tapestry
- GitHub: https://github.com/The-AI-Alliance/tapestry
- Human wiki: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6
- Complete Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/llms-full.txt

## Source Files

- `README.md`
- `AGENTS.md`
- `src/tapestry/training/consortium/README.md`
- `pyproject.toml`
- `docs/index.markdown`
- `tech-docs/README.md`

---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [README.md](README.md)
- [AGENTS.md](AGENTS.md)
- [pyproject.toml](pyproject.toml)
- [docs/index.markdown](docs/index.markdown)
- [tech-docs/README.md](tech-docs/README.md)
- [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md)
- [src/tapestry/training/consortium/__init__.py](src/tapestry/training/consortium/__init__.py)
- [src/tapestry/training/consortium/policy.py](src/tapestry/training/consortium/policy.py)
- [src/tapestry/training/consortium/messages.py](src/tapestry/training/consortium/messages.py)
- [src/tapestry/training/consortium/coordinator.py](src/tapestry/training/consortium/coordinator.py)
- [src/tapestry/training/consortium/node.py](src/tapestry/training/consortium/node.py)
- [examples/consortium_training_demo.py](examples/consortium_training_demo.py)
- [src/tests/tapestry/training/consortium/test_consortium_training.py](src/tests/tapestry/training/consortium/test_consortium_training.py)
- [Makefile](Makefile)

</details>

# Start Here

This page orients anyone opening the Tapestry repository for the first time. It states exactly what the repo contains today, the single fastest sequence of files to read, the five concrete entry points to open first, and the five core terms that appear in every design document and in the running code. Read this, open the five files, and you will know what the project is building and how the pieces fit.

The repository is the technical home for Project Tapestry. It holds the Python implementation of the consortium-training model, the full set of architectural decision records and requirements analysis, contributor tooling, and the sources for the published technical website.

## What This Repository Actually Contains

- A Python package (`src/tapestry/`) whose only fully implemented slice is the consortium-training proof-of-concept under `training/consortium/`.
- A large body of design documentation under `tech-docs/` that records the TVA phased analysis (stakeholder map through architectural options), numbered ADRs, the anti-capture governance principle, and work-group charters.
- A Jekyll/Just-the-Docs website under `docs/` that is published to GitHub Pages.
- Tests, one runnable end-to-end demo, a Makefile that drives setup/test/format/lint/type-check/view-local, and `pyproject.toml` that pins Python ≥ 3.12 and the tool chain (uv, torch, black, ruff, ty, pytest).
- No production training stack, no full data-governance layer, and no sovereign-alignment pipeline yet; those subsystems exist only as empty package directories.

Sources: [README.md:160-179](), [AGENTS.md:39-53](), [pyproject.toml:1-52](), [src/tapestry/training/consortium/README.md:23-34]()

## Fastest Read Order (First 30 Minutes)

1. `README.md` – top-level purpose, quick paths, licenses, and contributor instructions.
2. `AGENTS.md` – precise repository map, “Where To Look First”, Python layout, and non-negotiable working conventions.
3. `tech-docs/README.md` (then `tech-docs/architecture/README.md`) – how the design artifacts are organized and which document answers which question.
4. `src/tapestry/training/consortium/README.md` – the only code that actually runs; it defines the N+1 outcome and lists the five invariants the PoC demonstrates.
5. `examples/consortium_training_demo.py` – the 100-line script that prints the N+1 outcome and shows the governed-delta loop in action.

After these five, either run the demo or open the three implementation files (`policy.py`, `node.py`, `coordinator.py`) or the first TVA phase documents.

## Five Entry Points to Open First

| File | Why it is first | What you will actually find |
|------|-----------------|-------------------------------|
| [README.md](README.md) | Single source of “what is this repo and how do I start?” | Project banner, quick paths, setup commands, project structure diagram, licenses, and links to the live site. |
| [AGENTS.md](AGENTS.md) | The repo’s own navigation and rule book | Repository map, “Where To Look First” list, tech-docs taxonomy, Python package layout, make targets, formatting/linting rules, and the explicit instruction to treat governance docs as load-bearing. |
| [tech-docs/README.md](tech-docs/README.md) | Design authority index | Table of every major design artifact (TVA phases 0–5, ADRs, governance, work-groups, strategic plan) with one-sentence descriptions of each. |
| [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md) | The only executable slice explained in its own words | Definition of the N+1 model outcome, the five invariants the PoC preserves, and the module-by-module responsibility table. |
| [examples/consortium_training_demo.py](examples/consortium_training_demo.py) | See the concepts run | 100 lines that instantiate three nodes, a policy with quality floor and cap, run three rounds, and literally print “N+1 outcome: 1 shared base … N sovereign model artifacts retained”. |

Sources: [AGENTS.md:16-24](), [README.md:13-35](), [src/tapestry/training/consortium/README.md:1-12](), [examples/consortium_training_demo.py:54-103]()

## Core Vocabulary (Five Terms You Will Meet Everywhere)

These terms are not marketing slogans; they are the precise names used in the code and in the ADRs.

### N+1 outcome
One governed shared base model plus N participant-owned sovereign model artifacts. The coordinator evolves the single shared base; every node that participates ends the round with its own full model state that it alone owns and can take away.

Sources: [src/tapestry/training/consortium/README.md:4-8](), [src/tapestry/training/consortium/__init__.py:4-6](), [examples/consortium_training_demo.py:99-102]()

### Sovereign artifact (`SovereignModelArtifact`)
The complete model state a node produces after running its local training cycle on its private corpus. The artifact is stored in `coordinator.sovereign_artifacts` and in the node’s own `latest_artifact`; the raw corpus and the full model never leave the node.

Sources: [src/tapestry/training/consortium/messages.py:12-20](), [src/tapestry/training/consortium/node.py:61-68](), [src/tapestry/training/consortium/coordinator.py:44-45]()

### Governed delta (`weight_delta` inside `SovereignContribution`)
The difference between the model the node started the round with and the model it finished with. Only this delta (plus a quality score and token count) is sent to the coordinator. The coordinator never sees raw data or full models—only deltas that survive the policy.

Sources: [src/tapestry/training/consortium/messages.py:24-32](), [src/tapestry/training/consortium/node.py:58](), [src/tapestry/training/consortium/coordinator.py:55-58]()

### Quality floor
The `quality_floor` parameter of `ContributionPolicy`. Any node whose reported `quality_score` is below the floor is rejected for that round and contributes zero weight. The floor is the first anti-degradation control.

Sources: [src/tapestry/training/consortium/policy.py:14-25](), [src/tapestry/training/consortium/coordinator.py:48-52](), [examples/consortium_training_demo.py:68]()

### Anti-capture cap (`max_node_weight`)
The second parameter of `ContributionPolicy`. Even if a node has the highest quality score, its influence on the integrated base is capped at this fraction (commonly 0.5 in the demo). The cap is an explicit governance mechanism, not an optimizer heuristic.

Sources: [src/tapestry/training/consortium/policy.py:17-48](), [src/tapestry/training/consortium/README.md:10](), [examples/consortium_training_demo.py:69]()

## The Consortium Training Proof of Concept

The directory `src/tapestry/training/consortium/` contains the only running code. It uses a 16-line `TinyCausalModel` (embedding + linear projection) so that tests and the demo finish in milliseconds. The important objects are:

- `SovereignTrainingNode` – receives the current base, trains locally, retains a `SovereignModelArtifact`, returns a `SovereignContribution` containing only the delta.
- `ConsortiumCoordinator` – calls every node, asks the `ContributionPolicy` for weights, applies the weighted deltas, and returns a `ConsortiumRoundResult`.
- `ContributionPolicy.weights()` – enforces the quality floor then repeatedly normalizes and caps until no node exceeds `max_node_weight`.

A single round therefore produces the N+1 outcome by construction.

```text
Node (sovereign corpus)          Coordinator
  |                                   |
  v                                   v
local train (never shares corpus)   policy decides
  |                                   |
  +-- keeps full SovereignArtifact    +-- accepts/rejects + caps
  |                                   |
  +-- sends only weight_delta ----------> weighted sum applied to base
                                          |
                                          v
                                    new shared base (1)
                                          ^
                                    N sovereign artifacts retained
```

Sources: [src/tapestry/training/consortium/coordinator.py:38-66](), [src/tapestry/training/consortium/node.py:51-78](), [src/tapestry/training/consortium/policy.py:22-59]()

## Development Workflow (What the Makefile Actually Does)

All day-to-day work is driven by the Makefile:

- `make one-time-setup` – installs uv and creates the environment.
- `make tests` (or `make unit-tests`) – runs discovery from `src/` using the pytest configuration in `pyproject.toml`.
- `make format`, `make lint`, `make type-check` – the three tools (black, ruff+pylint, ty) that must pass before any PR.
- `make before-pr` – runs the whole gate in one command.

Python sources live under `src/`, tests mirror them under `src/tests/`, and every new module must be accompanied by matching tests. AGENTS.md is the authoritative statement of these rules.

Sources: [Makefile:43-60](), [AGENTS.md:57-73](), [pyproject.toml:28-53]()

## Design and Governance Context

All architecture work follows the TVA methodology documented in `tech-docs/architecture/`. The six phases (0–5) move from stakeholder map through pain points, value propositions, design goals, and finally an explicit options analysis. Design Goal 3 (anti-capture) is treated as a load-bearing constraint, not a nice-to-have; the `max_node_weight` cap in the PoC is the first executable expression of that goal. Governance documents under `tech-docs/governance/` are therefore required reading before any new architectural proposal.

Sources: [tech-docs/README.md:1-36](), [tech-docs/architecture/README.md:1-15](), [src/tapestry/training/consortium/policy.py:10-11]()

## Next Concrete Steps

1. `python examples/consortium_training_demo.py` – watch the N+1 outcome print.
2. `make one-time-setup && make tests` – verify the environment.
3. Open `src/tapestry/training/consortium/policy.py` and change `max_node_weight` or `quality_floor`; re-run the demo.
4. Read `tech-docs/architecture/0-tva-methodology.md` and `4-design-goals.md` when you need the “why” behind the code.

The N+1 consortium loop and its governed policy are the executable heart of the current implementation. Everything else in the repository exists to specify, justify, or eventually replace it.

Sources: [examples/consortium_training_demo.py:99-103](), [src/tapestry/training/consortium/coordinator.py:38-66]()