Welcome to Project Tapestry

Note

Project Tapestry is bringing together talented people, data, and compute from a global consortium of partners to build a new foundation model system trained on a larger and more diverse corpus than ever before.

Tapestry will enable sovereign AI by ensuring ownership of data and compute remains with partners, and that partners can continue to train sovereign derivatives of the consortium-trained base model that they own using the Tapestry open source training platform.

Learn more from our Kickoff Workshop Blog and check out the Project Tapestry website for more information about partnering, events, and how to support Project Tapestry.

This repo contains the code and technical documentation for the project. We invite you to jump in and help!

The rest of this README provides information for contributors and users of this repository.

Contribute to Our First Work Streams

Project Tapestry has big plans, and we're starting with some fundamental building blocks.

• LLM Cultural Alignment and Re-alignment - help us develop techniques for cultural alignment, initially based on the Inglehart–Welzel Cultural Map as a metric. This task will implement a corresponding evaluation and implement tuning experiments to understand how to shift alignment without compromising general model performance. Prior expertise in evaluation and tuning technologies are especially welcome.
• Consortium Training - Tapestry's approach to global model development relies on a balance between centralized and distributed training that preserves use and privacy requirements for data sets. Help us adapt and develop optimal techniques with ideas from both federated learning and the latest LLM pre-training and post-training methods. Prior expertise in large scale LLM training, distributed infrastructure, and federated learning are especially welcome.
• Global Training Data Corpus A core thesis of project Tapestry is that bringing together a much more diverse set of data can provide a path to a better frontier base model for all. What unique datasets exist that could be brought to Tapestry model training? They don't have to be fully open; we will work with you to define and enforce appropriate requirements.
• Tapestry Model Development Roadmap - coming soon - we want your input!

Quick Paths

Note

Make sure to read Getting Involved below for information on contribution guidelines, etc.

We use the develop branch as our default (integration) branch, reserving main for occasional "baked" releases.

Working with the Source Code

Use the Makefile targets to run tests and other tools, executables, etc. However, most commands require MacOS or Linux to work. Try make help for more information. More details are in the Development section below.

The production source code is under the src directory. The unit tests are under the src/tests directory. For example, a consortium training prototype is in src/tapestry/training/consortium/. Try make consortium-demo and make consortium-tests.

There are runnable demos in examples/. Try make consortium-demo.

Contributions are in contrib/, which are PoCs (proofs of concept), experiments, and modules proposed for possible inclusion in the production code. For example, see the contrib. experiment metrics for the consortium prototype in contrib/jneums-consortium-experiment/. Try make consortium-experiment.

Working with the Technical Documentation

The technical documentation lives under docs. This is where you will find our requirements, architecture and design work, etc.

• Architecture
  • The TVA methodology: phased outputs (stakeholder map through design goals), architectural options and core thesis, plus:
    • Architecture Decision Records
    • Diagrams
• Governance
• Strategic Plan
• Reference Materials (e.g. training paradigms)
• Work Groups

For repo layout, conventions, and where to find implementation code, see AGENTS.md.

Setting Up for Development

This project uses uv for Python package management.

Install uv

On macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

The rest of the steps discussed next are automated using make. Try the following:

make one-time-setup  # Requires MacOS or Linux

Create a Virtual Environment

The one-time-setup target starts by running the following command.

On macOS/Linux:

uv venv
source .venv/bin/activate

On Windows, use the following instead:

uv venv
.venv\Scripts\activate

Install Dependencies

The one-time-setup target runs the first of the following two commands. You can also run either command manually.

uv pip install -e ".[dev]"  # full development dependencies
uv pip install -e .         # minimum dependencies

Running Tests

We use pytest for testing. The easiest way to run the test suite is using make:

make unit-tests   # tests is also defined as an alias for unit-tests.

This runs pytest with coverage reporting, using the following commands:

cd src
uv run --active coverage run -m pytest -q -v -s
uv run --active coverage report -m

Note

The --active flag is needed for recursive invocation in contrib/*, where some of the contributions define their own local uv/venv environments.

Code Refinement

We use tools for formatting, linting, and type-checking the code.

Code Formatting

Use either of the following commands to format the Python code with black:

make format
# or
uv run black src

Linting

Use either of the following commands to lint the Python code with ruff and pylint:

make lint
# or
uv run ruff check src
uv pylint src

Type Checking

Use either of the following commands to type check the Python code with ty:

make type-check
# or
uv run ty src

There is also a "watch" option that keeps ty running as you fix mistakes and save the files:

make type-check-watch
# or
uv run ty --watch src

Making Contributions

Note

Make sure to read the general guidance in Getting Involved below before submitting a PR.

Where to Create Your Contribution

If you are enhancing existing code, make the changes under src, and when appropriate, the top-level Makefile and .common.mk.

However, for everything else, including proofs of concept (PoCs), experiments, proposed additions, etc., create them under contrib, the staging area for new contributions. The contrib README describes the requirements you must follow for new contributions, including how the master make process works and the customizations you might need to "global" quality check targets, like tests, lint, etc. For example, there is an easy way to disable some of these checks for PoC code that isn't considered production ready.

Before You Submit a PR...

Before submitting a PR, please make these "quality" targets: format, lint (which makes ruff and pylint), type-check, and unit-tests. This needs to be done in both the production src tree and all the contrib contributions. Use the convenient make target before-pr, which handles all of them for you:

make before-pr

Make sure everything passes cleanly! This ensures that the production code under src and the contrib contributions are properly formatted, linted, type checked, and the tests pass (and continue to work, even when you aren't working on one of these "sections" with your PR...). You can also run these tasks separately for the "top-level" code and for the contributions:

make before-pr-top       # The top-level code only.
make before-pr-contrib   # The contrib/* code only.

However, note that there is a mechanism each contrib contribution may use to skip certain of these targets when the contribution is not yet production ready. This mechanism is discussed in the contrib README.

You can run a specific quality target on one or more contributions as follows. Let's use contrib/foo and target format as an example:

# Make "format" just for "contrib/foo"
make SRC_DIR=contrib/foo --include-dir=contrib/foo format  
# Make "format" for ALL "contrib/*"
make contrib-format

Project Code Structure

In addition to the top-level directories docs, discussed above, website, discussed below, and contrib, the staging area for contributed ideas and techniques, the code structure is as follows. At this time, there are three major subsystems:

• data for all data governance and management capabilities.
• training for all distributed training and tuning capabilities.
• infrastructure for all underlying infrastructure.

tapestry/
├── contrib/        # Contributed ideas & techniques, proposed via PR
├── src/
│   └── tapestry/
│       └── data/
│       └── infrastructure/
│       └── training/
│   └── tests
│       └── tapestry/
│           └── data/
│           └── infrastructure/
│           └── training/

Final Notes on Getting Involved

We welcome contributions as pull requests, issues, and discussions.

See CONTRIBUTING.md for guidelines. In particular, read this section on using DCO with any commits.

Have an idea, technique, or experiment you'd like the project to consider? The contrib/ directory is a lightweight staging area where contributors can propose work via a PR into their own subdirectory. See contrib/README.md for the simple workflow and contribution policy.

You can also join one or more work groups that are being organized to identify requirements in several areas and to start the engineering work to prototype and test ideas, followed by the initial implementation iterations. Details are being documented in docs/work-groups/.

Licenses

All code contributions are licensed under the Apache 2.0 LICENSE (which is also in this repo, LICENSES/LICENSE.Apache-2.0).

All documentation contributions are licensed under the Creative Commons Attribution 4.0 International (which is also in this repo, LICENSES/LICENSE.CC-BY-4.0).

All data contributions are licensed under the Community Data License Agreement - Permissive - Version 2.0 (which is also in this repo, LICENSES/LICENSE.CDLA-2.0).

We use the "Developer Certificate of Origin" (DCO).

Warning

Before you make any git commits with changes, understand what's required for DCO.

See the contributing guide section on DCO for details. In practical terms, supporting this requirement means you must use the -s flag with your git commit commands.

About the Technical Website (GitHub Pages)

The website for this repository provides another way to discover and navigate the technical documentation content in docs. However, at this time, the site mostly just points to the content in docs. Eventually, it will publish "refined" versions of the docs content.

The website sources are written in Markdown, HTML, JavaScript, etc. and are found in the website directory. The website is published using GitHub Pages, which uses the Jekyll engine. See GITHUB_PAGES.md for all the details.

---

Project Tapestry is an initiative of the AI Alliance Innovation Association, 501(c)(6) non-profit.