Welcome to Project Tapestry

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

This repository contains the code and technical documentation for the project. Your help is most welcome!

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

Project Tapestry has big plans. Here are the main areas of current focus. Note that we need help defining requirements, identifying use cases, and writing code for all these areas.

• LLM Cultural Alignment and Re-alignment - Help us develop techniques for cultural alignment, initially based on the Inglehart–Welzel Cultural Map as a metric, with more approaches and metrics to be identified. This effort will continue to explore how to shift cultural alignment without compromising general model performance. Prior expertise in evaluation and tuning technologies are especially welcome, as well as expertise in the ways that current AI models are not well aligned to specific cultures and uses cases in society and business.
• Consortium Training - Tapestry's approach to global model development relies on a balance between centralized and distributed training that ensures permissive use and privacy requirements for datasets. 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 systems and infrastructure, and federated learning are especially welcome. In particular, we are starting to create domain-specific models, and we need expertise in healthcare, finance, industrial technologies, etc.
• Data, Responsibly Used - Help us define the requirements and understand the regulations around permissive use and privacy for datasets, then implement support for them.
  • 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.
• Your good ideas - Our contribution mechanism provides a way for you to suggest new ideas, technologies, and solutions to design challenges we face.

We use GNU make and Makefile targets to run tests and other tools. While this works best on MacOS or Linux, all the Python-based commands can be executed on any platform. We'll show you both ways below. Try make help for more information and see the Development section below.

The production source code is under the src directory. The automated 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/. In fact, the make consortium-demo command uses a script in examples.

Outside contributions are in contrib/, which provides a straightforward way for contributors to provide PoCs (proofs of concept), experiments, examples, and modules proposed for possible inclusion in the production code. For example, see the experiment metrics contributed for the consortium training prototype just mentioned in contrib/jneums-consortium-experiment/. Try make consortium-experiment. See Making Contributions below for more details about our contributions process.

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

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

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

This project uses uv for Python package management and GNU make for running commands. GNU make is included with Linux and MacOS distributions. If you are on Windows, try using Make for Windows.

If you can't use GNU make, you can run the underlying uv commands directly, as discussed below.

If you can run GNU make, run the following command:

make one-time-setup

This command will install uv and fswatch (discussed below), if they aren't already installed and you have HomeBrew installed. Then the target will install the project's Python library dependencies.

If the command worked successfully, you can skip to Development Tasks. Otherwise, install uv, fswatch, and the Python dependencies as follows.

If you don't have uv installed already and you don't have HomeBrew installed, run one of the following commands:

Linux/MacOS:

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

Windows:

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

Install the cross-platform fswatch as described on its website.

After uv is installed, run these commands to complete the setup of your Python environment:

uv venv                     # Create the virtual environment
source .venv/bin/activate   # Activate the environment: MacOS and Linux
# .venv\Scripts\activate    # Activate the environment: Windows
uv pip install -e ".[dev]"  # Install all dependencies

This section discusses the common quality checks automated using make targets, along with the uv commands invoked. An "umbrella" target before-pr invokes all of them as a gate for pull requests (see Before You Submit a PR).

We will show both the GNU make command for a task, followed by the corresponding uv commands that are invoked as part of building the make target. Note that most of the make targets also do some other steps, like checking if required tools and directories exist. We recommend using the make commands if at all possible.

We use pytest for testing. 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 coverage run -m pytest -v -s .
uv run coverage report -m

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

make format # makes the "black" target
make black

This runs black to format your code. Here are the equivalent commands (assuming you start back at the repo root directory, the parent of src):

cd src
uv run black .

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

make lint # makes the "ruff" and "pylint" targets
make ruff pylint

Or use these commands:

cd src
uv run ruff check --fix  .
uv run pylint --recursive=y --ignore=.venv --ignore-pattern='.*cache.*'  .

There is also a --watch CLI option for ruff that keeps it running as you fix mistakes and save the files. We have a custom make target for this purpose. Use one of the following command choices:

make ruff-watch
# Or use the following:
cd src
uv run ruff check --watch .

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

make type-check # makes the "ty" target
make ty

Or use these commands:

cd src
uv run ty .

Like ruff, ty also has a --watch CLI option that keeps ty running as you fix mistakes and save the files. We have a custom make target for this purpose. Use one of the following command choices:

make type-check-watch
# Or use the following:
cd src
uv run ty --watch .

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

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.

For example, the common quality check make targets, like tests, lint, etc. are also run for all the contributions. However, your contribution may not (yet) be production ready, so it might fail some of those checks. While you should try to submit production-ready work, we don't want to discourage idea submissions. So, there is a straightforward mechanism to customize or disable any of these checks for contribution code, as needed. The contrib README has the details.

Before submitting a PR, make sure the make target before-pr passes cleanly:

make before-pr

This target makes all our "quality" targets: format (which uses black), lint (which uses ruff and pylint), type-check (which uses ty), and unit-tests.

Note that black may reformat your code, so be sure to commit any changes. the before-pr target will run these checks in both the production src tree and all the contrib contributions. You can also run these checks 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.

You can run a specific quality target on one or more contributions as follows. Let's suppose there is a contrib/foo contribution and you want to run make format on it:

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

If you want to run make format for all contrib/* contributions:

make contrib-format

The project code structure is still evolving, but currently it is organized into 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/

In addition, docs (discussed above) holds all technical documentation, and website (discussed below) holds the project technical website content.

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/.

If your organization wants to join the Tapestry consortium and it intends to contribute data, compute, people, or funding, please email Kaushik Bhatta for more information.

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).

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.

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, etc. and are found in the website directory. The website is published using GitHub Pages. See GITHUB_PAGES.md for all the details.

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