# After 30 Minutes: Your Map Forward > What you now know and the three concrete next actions: pick one ADR or work-group charter to read deeply, run and modify the demo with your own corpus, and the exact contribution workflow (PR templates, license stack, AGENTS.md conventions) for this repository. - 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 - `AGENTS.md` - `.github/PULL_REQUEST_TEMPLATE/general_code_pr.md` - `tech-docs/architecture/decisions/adr-007-architecture-comparison.md` - `tech-docs/strategic-plan/README.md` - `Makefile` ---
Relevant source files The following files were used as context for generating this wiki page: - [AGENTS.md](AGENTS.md) - [.github/PULL_REQUEST_TEMPLATE/general_code_pr.md](.github/PULL_REQUEST_TEMPLATE/general_code_pr.md) - [.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md](.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md) - [Makefile](Makefile) - [README.md](README.md) - [docs/contributing.markdown](docs/contributing.markdown) - [examples/consortium_training_demo.py](examples/consortium_training_demo.py) - [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md) - [tech-docs/README.md](tech-docs/README.md) - [tech-docs/architecture/decisions/README.md](tech-docs/architecture/decisions/README.md) - [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md) - [tech-docs/architecture/decisions/adr-007-architecture-comparison.md](tech-docs/architecture/decisions/adr-007-architecture-comparison.md) - [tech-docs/work-groups/README.md](tech-docs/work-groups/README.md) - [tech-docs/work-groups/data-governance/README.md](tech-docs/work-groups/data-governance/README.md)
# After 30 Minutes: Your Map Forward After 30 minutes in the Tapestry repository you have a working mental model of the project and a clear path to productive contribution. You understand the core thesis (a governed consortium training loop that produces one shared frontier base plus N participant-owned sovereign models), the current concrete artifact (a runnable Python proof-of-concept), the design rationale captured in ADRs, the work-group structure that owns the lifecycle, and the exact local development and PR conventions enforced by this repo. This page turns that orientation into three high-signal next actions so your time moves from "figuring out the repo" to "doing useful work." ## What You Now Know **Project intent and invariants.** Tapestry is building a frontier foundation model through "consortium training": a shared base (initially adopted, later evolved by the consortium) is distributed to sovereign nodes; each node performs continued pre-training and alignment on its own data; only governed weight deltas return to improve the base. Raw sovereign data never leaves the node. The outcome at every round is the N+1 model pattern—one evolving global base plus N persistent, deployable sovereign artifacts owned by participants. Anti-capture, data sovereignty, and incremental value are architectural requirements, not aspirations. **Current implementation surface.** The only live code is the small but faithful `src/tapestry/training/consortium/` package (coordinator, sovereign node, contribution policy, tiny causal model, messages). The runnable demo in `examples/consortium_training_demo.py` exercises the exact loop described in the ADRs: quality floor, anti-capture weight cap, accepted/rejected contributions, and sovereign artifact retention. Everything else (data governance, full sovereign pipeline, evaluation, infrastructure) is still in `tech-docs/`. **Design documentation as load-bearing context.** `tech-docs/architecture/` contains the TVA requirements phases, the option-space analysis, and the numbered ADRs. `tech-docs/work-groups/` contains the lifecycle charters. `AGENTS.md` explicitly tells contributors to treat these documents as first stops and constraints before writing code. **Local development contract.** Python 3.12 + `uv`, all work driven by `make` targets (`one-time-setup`, `tests`, `format`, `lint`, `type-check`, `before-pr`, `consortium-demo`), strict layout mirroring between `src/tapestry/...` and `src/tests/tapestry/...`, small focused changes, and the requirement to run the full verification suite before any PR. Sources: [AGENTS.md:1-140](AGENTS.md), [README.md:180-250](README.md), [src/tapestry/training/consortium/README.md:1-60](src/tapestry/training/consortium/README.md), [tech-docs/README.md:1-50](tech-docs/README.md) ## Three Concrete Next Actions ### 1. Pick one ADR or work-group charter and read it deeply (30–60 minutes) The ADRs and charters are the primary sources of truth for why choices were made and what is in or out of scope. Skimming is not enough; pick one and map its reasoning, the alternatives it rejected, and the open questions it flags. **Recommended starting ADRs** (all under `tech-docs/architecture/decisions/`): | ADR | One-sentence reason to read it | Core claim | |-----|--------------------------------|------------| | [TAP-001](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md) | The foundational layering decision that everything else assumes. | Core-plus-sovereign (shared base + sovereign layers) beats both monolithic and fully distributed alternatives for the primary goals. | | [TAP-007](tech-docs/architecture/decisions/adr-007-architecture-comparison.md) | The cross-cutting evaluation of eight training architectures against the design goals. | Weight-delta consortium training is the current bet because it has the strongest (still small-scale) empirical and theoretical support; the contribution mechanism itself is designed to be swappable. | | [TAP-002](tech-docs/architecture/decisions/adr-002-consortium-training.md) or [TAP-004](tech-docs/architecture/decisions/adr-004-training-loop.md) | The operational loop and the N+1 outcome. | Governance of deltas, not just the existence of the loop, is what makes the system anti-capture and strategically rational for participants. | **Recommended starting work-group charter**: - [Data Governance](tech-docs/work-groups/data-governance/README.md) — defines the data-tier taxonomy, provenance requirements, and the hard "raw data never leaves" boundary that the rest of the system must respect. After you finish, you will be able to explain the concrete trade-off that justified the current architecture and name at least two alternatives that were deliberately ruled out or deferred. Sources: [tech-docs/architecture/decisions/README.md:20-70](tech-docs/architecture/decisions/README.md), [tech-docs/architecture/decisions/adr-007-architecture-comparison.md:80-160](tech-docs/architecture/decisions/adr-007-architecture-comparison.md), [tech-docs/work-groups/README.md:20-80](tech-docs/work-groups/README.md), [tech-docs/work-groups/data-governance/README.md:1-60](tech-docs/work-groups/data-governance/README.md) ### 2. Run the demo and modify it with your own corpus (15 minutes) This is the fastest way to develop intuition for the invariants the architecture actually enforces. ```bash make consortium-demo # or directly: uv run python examples/consortium_training_demo.py ``` The script instantiates three fictional sovereign nodes (Vietnam, Switzerland, India), each with a tiny corpus, runs three rounds of the governed loop, and prints accepted contributions, weights, rejections, and retained sovereign artifacts. **To make it yours:** 1. Open `examples/consortium_training_demo.py`. 2. Replace or extend the `DOMAIN_CORPORA` dictionary with 4–8 short, culturally specific sentences in your target language or domain. 3. Adjust the corresponding entry in `QUALITY_SCORES` (must be ≥ the policy's quality floor of 0.75 to be accepted). 4. Re-run. Observe which nodes are accepted or rejected and how the contribution weights are capped. Then open the three core modules (`node.py`, `coordinator.py`, `policy.py`) and trace exactly where the quality floor and `max_node_weight` are applied. You now have a live, modifiable model of "data stays local, only deltas move, governance is executable." Sources: [Makefile:115-130](Makefile), [examples/consortium_training_demo.py:20-95](examples/consortium_training_demo.py), [src/tapestry/training/consortium/README.md:20-55](src/tapestry/training/consortium/README.md) ### 3. Execute the exact contribution workflow (the checklist you will follow on every PR) **Before you write code or docs:** - Read `AGENTS.md` (the single source of repo conventions). - Read the relevant slice of `tech-docs/` first; do not start a broad refactor. - Keep changes small and contained to one subsystem; mirror any new `src/tapestry/X/` code with `src/tests/tapestry/X/` tests. **When you open the PR, GitHub will ask you to choose a template.** Pick the right one: - `general_code_pr.md` — any change that touches `src/`, `examples/`, tests, or build files. - `docs_website_pr.md` — pure documentation or `docs/` site changes. Both templates require the same high-level structure (description, related issues, testing/impact, checklist). The code template additionally demands: - Unit or integration tests added/updated. - `make before-pr` (or the individual format + lint + type-check + tests) has passed locally. - No secrets committed. - Documentation updated where behavior changed. **License and DCO stack (non-negotiable):** - Code → Apache 2.0 (`LICENSE.Apache-2.0`) - Documentation → CC-BY-4.0 (`LICENSE.CC-BY-4.0`) - Data → CDLA-2.0 (`LICENSE.CDLA-2.0`) - Every commit must include the `-s` / `--signoff` flag (Developer Certificate of Origin). The Alliance CONTRIBUTING guide (linked from the templates and README) explains the exact requirement. **Docs-specific extra steps** (when using the docs template): - `make view-local` must succeed (Jekyll build). - `./check-external-links.sh` must pass for any new external links (and you must add the `target="..."` attributes the script cannot insert). **Practical pre-PR command sequence** (from AGENTS.md and Makefile): ```bash make one-time-setup # first time only make before-pr # format + lint + type-check + tests make consortium-tests # if you touched the PoC ``` Only after the above is green do you push and open the PR with the correct template filled in. Sources: [.github/PULL_REQUEST_TEMPLATE/general_code_pr.md:30-70](.github/PULL_REQUEST_TEMPLATE/general_code_pr.md), [.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md:1-40](.github/PULL_REQUEST_TEMPLATE/docs_website_pr.md), [README.md:200-240](README.md), [AGENTS.md:70-110](AGENTS.md), [docs/contributing.markdown:1-60](docs/contributing.markdown) ## Your 30-Minute Outcome You now possess: - A precise architectural mental model (N+1, governed deltas, core-plus-sovereign). - A living, editable artifact that demonstrates the invariants. - The exact documents that encode the "why" and the governance boundaries. - The mechanical checklist that every accepted contribution must satisfy. Pick one of the three actions above and do it today. When you return, you will be ready to open a meaningful issue, improve a charter, add a test case to the PoC, or propose a small, well-scoped change that respects the architecture the repo has already decided. Sources: [AGENTS.md:1-20](AGENTS.md), [tech-docs/architecture/decisions/adr-007-architecture-comparison.md:300-340](tech-docs/architecture/decisions/adr-007-architecture-comparison.md)