FabricLoom documentation

Build your first cartridge

Scaffold, install, and run a development capability

In this section

This tutorial builds sentiment-tagger, a development cartridge that accepts UTF-8 text and emits positive, neutral, or negative. The generated cartridge delegates the judgment to the installed classify-en capability, so you exercise a real peer call, model progress, and typed output.

Before you begin

Install the capdag CLI and the toolchain for your chosen language. The Python path requires Python 3.11 or newer and the runtime package:

python3 -m pip install capdag

You also need a model cartridge that provides classify-en. Its first run may download a model and therefore require network access.

Create the cartridge

capdag new sentiment-tagger --python
cd sentiment-tagger

The CLI also accepts --rust, --go, and --swift. Compiled-language projects include their build instructions in the generated README.

The scaffold defines:

  • one project-specific capability and alias, sentiment-tagger;
  • unique input and output media URNs;
  • the mandatory identity capability;
  • a handler that calls classify-en with a closed set of three labels; and
  • a development manifest whose registry_url is null.

Inspect the Python manifest:

./cartridge.py manifest | python3 -m json.tool

The custom Cap URN is assembled with CapUrnBuilder. Keep the builder’s canonical string and use it for handler registration; do not hand-build or compare tagged URNs as raw strings.

Install it locally

For Python, install the scaffold directly:

capdag dev-install .

Build Rust, Go, or Swift projects before running dev-install. The command checks that the new alias does not replace an existing fabric alias and stages the cartridge below the per-user dev registry:

~/.capdag/cartridges/dev/v{registry-version}/nightly/sentiment-tagger/0.1.0/

Reinstalling the same version updates that directory. Changing the manifest version installs a separate version.

Run the capability

echo "I love this" | capdag sentiment-tagger

Run the capability through capdag, not by invoking the entry’s operation directly. The host is what routes the peer call. Without it, the generated handler reports Peer invocation not supported in this context.

The result on stdout is one of the three configured labels. Progress from model download or inference is forwarded through the host. If no installed cartridge provides classify-en, the request fails instead of silently switching to a different classifier.

Make a change

Edit the generated label set, capability metadata, or peer capability. Rebuild a compiled cartridge, then reinstall and run it again:

capdag dev-install .
echo "I love this" | capdag sentiment-tagger

This edit–build–install–run loop uses the same host and Bifaci protocol as a published cartridge.

Understand the contract

The scaffold demonstrates the parts every cartridge needs:

  • a manifest describing its identity and capabilities;
  • Cap and Media URNs that define the typed contract;
  • an operation registered under the manifest’s canonical Cap URN;
  • streaming input and output through Bifaci;
  • progress and failure propagation; and
  • peer invocation when another cartridge owns part of the work.

For the complete language-neutral tutorial and troubleshooting table, see Build and run a cartridge. Use the Cartridge SDK reference for the product-specific libraries and Cartridges on macOS for installation, signing, and distribution.