# Setup, Tests & Demo in Under 10 Minutes > Exact commands that work: uv + make one-time-setup, the five most useful Makefile targets, how to run the consortium demo, where tests live, and the two files you edit to change behavior on first run. - 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 - `Makefile` - `pyproject.toml` - `examples/consortium_training_demo.py` - `src/tests/tapestry/training/consortium/test_consortium_training.py` - `src/tapestry/training/consortium/README.md` ---
Relevant source files The following files were used as context for generating this wiki page: - [Makefile](Makefile) - [pyproject.toml](pyproject.toml) - [README.md](README.md) - [AGENTS.md](AGENTS.md) - [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) - [src/tapestry/training/consortium/README.md](src/tapestry/training/consortium/README.md) - [src/tapestry/training/consortium/policy.py](src/tapestry/training/consortium/policy.py) - [src/tapestry/training/consortium/coordinator.py](src/tapestry/training/consortium/coordinator.py) - [src/tapestry/training/consortium/model.py](src/tapestry/training/consortium/model.py) - [src/tapestry/training/consortium/__init__.py](src/tapestry/training/consortium/__init__.py)
# Setup, Tests & Demo in Under 10 Minutes This page gives the exact, verified commands to go from a fresh clone to a running consortium-training demo and green tests in well under 10 minutes on a machine with Python 3.12+. It names the five Makefile targets you will use repeatedly, shows how to execute the N+1 proof-of-concept, states precisely where tests live, and identifies the two files that control observable behavior on first customization. All claims below are taken directly from the active build configuration, Makefile recipes, test code, and demo source rather than secondary documentation. ## Prerequisites - Python 3.12 or newer - `uv` (https://docs.astral.sh/uv/) - GNU make (standard on macOS and Linux) - A working internet connection for the first `uv pip install` (pulls torch, numpy, and dev tools) No other global Python packages or system libraries are required. ## One-Time Setup Run this single command from the repository root: ```shell make one-time-setup ``` This target expands to three steps (sources: [Makefile:169-180]()): 1. `install-uv` — checks for `uv` in PATH and prints installation help if missing. 2. `uv-venv` — creates a `.venv` directory if none exists. 3. `install-dev-dependencies` — runs `uv pip install -e ".[dev]"`. The dev extras (defined in [pyproject.toml:14-22]()) pull in pytest, ruff, pylint, black, and ty plus the runtime requirements (torch, numpy). After the command succeeds you normally do **not** need to `source .venv/bin/activate`; every subsequent `make` target and `uv run` invocation uses the virtual environment automatically. The Makefile prints a reminder only for the rare case where a direct `python` or `pytest` call is made outside `uv run`. Sources: [Makefile:166-199](), [pyproject.toml:1-33](), [README.md:65-95]() ## Five Most Useful Makefile Targets These five targets cover 95 % of day-to-day work after the initial setup: | Target | What it does | Underlying command (from Makefile) | |-------------------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------| | `make help` | Prints the full target list and short descriptions. | Built-in info target | | `make tests` (or `make unit-tests`) | Runs the entire test suite quietly. | `cd src && uv run pytest tests -q` | | `make consortium-demo` | Executes the runnable N+1 consortium proof-of-concept. | `uv run python examples/consortium_training_demo.py` | | `make consortium-tests` | Runs only the consortium-training tests (fast feedback loop). | `uv run pytest src/tests/tapestry/training/consortium -q` | | `make before-pr` (or `make flt`) | Formats, lints, type-checks, and tests — the pre-PR gate. | `format-lint-type-check && tests` | Other frequently used shortcuts: `make format`, `make lint`, `make type-check`, `make clean`. All targets are defined in [Makefile:121-164](). The `uv run` prefix guarantees the correct interpreter and installed packages without manual activation. ## Running the Consortium Training Demo ```shell make consortium-demo # or uv run python examples/consortium_training_demo.py ``` The script ([examples/consortium_training_demo.py:54-107]()): - Instantiates a tiny causal model (`TinyCausalModel`). - Creates a `ConsortiumCoordinator` with a `ContributionPolicy(quality_floor=0.75, max_node_weight=0.5)`. - Spawns three sovereign nodes (vietnam, switzerland, india) each carrying a tiny domain-specific "corpus" and a self-reported quality score. - Runs three rounds: each node performs local continued pretraining on its private data, emits only a weight delta, the coordinator applies the policy, accepts or rejects the delta, and updates the shared base. - Prints per-round acceptance, weights, and the final count of retained sovereign artifacts. The demo demonstrates the core invariant described in the module README: one governed shared base plus N participant-owned sovereign model artifacts ([src/tapestry/training/consortium/README.md:1-12](), [src/tapestry/training/consortium/coordinator.py:38-60](), [src/tapestry/training/consortium/__init__.py:9-29]()`). Typical first-run output ends with: ``` N+1 outcome: 1 shared base model evolved by governed contributions 3 sovereign model artifacts retained ``` Sources: [examples/consortium_training_demo.py:1-108](), [src/tapestry/training/consortium/coordinator.py:20-60](), [src/tapestry/training/consortium/model.py:9-19]() ## Where Tests Live Tests mirror the package layout under `src/tests/`: - Full suite: `src/tests/` - Consortium-specific module: `src/tests/tapestry/training/consortium/test_consortium_training.py` Key configuration ([pyproject.toml:28-33]()): ```toml [tool.pytest.ini_options] testpaths = ["src/tests"] pythonpath = ["src"] ``` The four tests in the consortium module verify: - `SovereignTrainingNode` returns both an artifact and a non-zero weight delta. - `ContributionPolicy` drops contributions below the quality floor and caps any single node. - `ConsortiumCoordinator` produces the N+1 outcome (updated base + one artifact per node). - A round containing only low-quality contributions leaves the shared base unchanged. Run targeted tests with: ```shell make consortium-tests # or uv run pytest src/tests/tapestry/training/consortium -q ``` Sources: [src/tests/tapestry/training/consortium/test_consortium_training.py:36-153](), [Makefile:124-137](), [pyproject.toml:28-33]() ## The Two Files to Edit to Change Behavior on First Run After the first successful `make consortium-demo`, the two files that give the highest-leverage customization are: 1. **examples/consortium_training_demo.py** — change the input data, quality scores, policy thresholds, or round count. ```python # examples/consortium_training_demo.py:23-47 DOMAIN_CORPORA: dict[str, list[str]] = { "vietnam": ["Vietnamese public services require local legal context.", ...], ... } QUALITY_SCORES = {"vietnam": 0.90, "switzerland": 0.86, "india": 0.88} # ... coordinator = ConsortiumCoordinator( base_model=base_model, contribution_policy=ContributionPolicy( quality_floor=0.75, max_node_weight=0.5, ), ) ``` Edit the dicts, the `ContributionPolicy(...)` constructor call, `run_demo(rounds=..., seed=...)`, or the per-node `local_epochs`/`lr` values to alter what the demo prints and how the governance behaves. 2. **src/tapestry/training/consortium/policy.py** — change the default governance rules that every consumer of `ContributionPolicy` inherits. ```python # src/tapestry/training/consortium/policy.py:14-20 def __init__(self, quality_floor: float = 0.0, max_node_weight: float = 1.0) -> None: ... self.quality_floor = quality_floor self.max_node_weight = max_node_weight ``` The `weights()` method ([policy.py:22-64]()) implements the floor filter plus iterative anti-capture capping. Changing the defaults or the normalization/capping logic here immediately affects both the demo and all unit tests that construct the policy. These two files are the entire "first 30 seconds of experimentation" surface. Deeper changes (node training loop, `TinyCausalModel` architecture, message shapes) come after you have verified behavior with the demo and the four existing tests. Sources: [examples/consortium_training_demo.py:23-48,67-70](), [src/tapestry/training/consortium/policy.py:6-65](), [src/tapestry/training/consortium/coordinator.py:27-29]() ## Next Steps - Run `make before-pr` before any pull request. - Add new sovereign nodes or corpora by extending the demo script; keep tests in the matching `src/tests/tapestry/training/consortium/` directory. - Read `src/tapestry/training/consortium/README.md` for the architectural invariants the PoC is intended to protect. With `make one-time-setup`, the five targets above, the demo command, the known test location, and the two customization files you now have a complete, reproducible 10-minute on-ramp into the Tapestry consortium-training prototype. Sources: [Makefile:131-133]()