MachineFabric Documentation

What is MachineFabric

MachineFabric is a macOS application that orchestrates cartridges to process files and achieve complex workflows. It treats every operation—whether extracting text from a PDF, running a vision model, transcribing audio, or querying an LLM—as a capability provided by a cartridge.

The Problem

AI models are powerful but isolated. A vision model in one app. An LLM in another. A transcription tool somewhere else. They don’t communicate. To use them together, you manually copy outputs between tools.

The Solution

MachineFabric connects them. Every cartridge speaks the same language: CapDAG. Drop a file, and MachineFabric finds the right cartridges to process it. The output of one cartridge becomes the input of the next. Cartridges don’t know about each other—MachineFabric handles the wiring.

Key Principles

• Everything is a cartridge — AI models, file extractors, format converters. Same interface.
• Cartridges compose — Output of one feeds into another. Build complex workflows from simple parts.
• Local first — Runs on your Mac. Your files stay on your machine.
• Open protocol — CapDAG defines how cartridges describe and match capabilities.

How It Works

When you drop a file into MachineFabric, here’s what happens:

1. Identify — MachineFabric reads the file’s media type (PDF, PNG, MP3, etc.)
2. Match — It finds cartridges that can handle that input type
3. Execute — The cartridge runs, producing output with a new media type
4. Chain — If more processing is needed, the output feeds into the next cartridge
5. Store — Results are indexed for search and display

Example: Processing a PDF

input: document.pdf (media:pdf;bytes)
    ↓
pdfcartridge → extract text
    ↓
output: text content (media:txt;textable)
    ↓
candlecartridge → generate embeddings
    ↓
output: vector embeddings (media:json;embedding)
    ↓
stored in search index

Example: Transcribing Audio

input: recording.mp3 (media:mp3;bytes)
    ↓
whispercartridge → transcribe
    ↓
output: transcript (media:txt;textable)
    ↓
mlxcartridge → summarize with LLM
    ↓
output: summary (media:txt;textable)

CapDAG

MachineFabric uses CapDAG (Capability Directed Acyclic Graph) as its naming and routing system. CapDAG defines how capabilities are identified with URNs, how data types are described with media URNs, and how requests are matched to the right cartridge.

See the CapDAG documentation for the full specification — URN syntax, matching, dispatch, specificity and ranking, and the Bifaci runtime protocol.

Capabilities

A capability is an operation a cartridge can perform. It has:

• A URN — What the capability does
• Input types — What media types it accepts
• Output type — What media type it produces
• Arguments — Optional parameters to configure behavior

Capability Categories

Capability Definition

Cartridges declare their capabilities in a JSON manifest:

{
  "capabilities": [
    {
      "cap": "cap:op=extract;format=pdf;target=text",
      "sources": ["media:pdf;bytes"],
      "output": "media:txt;textable",
      "args": {
        "pages": { "type": "string", "optional": true }
      }
    }
  ]
}

Cartridges (Cartridges)

Cartridges are standalone executables that provide capabilities. MachineFabric calls them “cartridges”—self-contained units you slot in to add new powers.

Bundled Cartridges

• pdfcartridge — PDF text and image extraction
• txtcartridge — Text and markdown processing
• candlecartridge — Vector embeddings via Candle
• mlxcartridge — LLM inference via MLX

How Cartridges Work

Cartridges communicate via stdin/stdout using the Bifaci protocol:

1. MachineFabric spawns the cartridge process
2. Sends a request frame with capability URN and input data
3. Cartridge processes and returns a response frame
4. MachineFabric collects the output

Cartridge Discovery

On startup, MachineFabric scans cartridge directories:

• /Library/Application Support/MachineFabric/Cartridges/
• ~/Library/Application Support/MachineFabric/Cartridges/
• Bundled cartridges in the app

Each cartridge is invoked with --manifest to declare its capabilities. MachineFabric builds a capability graph from all available cartridges.

Security

Distributed cartridges must be signed and notarized:

• Developer ID code signature
• Apple notarization
• Runs in sandboxed XPC service

Cartridge development guide →

Orchestration

MachineFabric’s job is to orchestrate cartridges into workflows. Given an objective, it finds a path through available capabilities to achieve it.

Automatic Chaining

When you request an operation, MachineFabric may need multiple cartridges. It builds a directed acyclic graph (DAG) of capabilities:

Request: "Generate searchable embeddings from this PDF"

Graph:
  pdf → [pdfcartridge:extract] → text
  text → [candlecartridge:embed] → embeddings

Manual Workflows

You can also define explicit capability chains:

[
  "cap:op=extract;format=pdf;target=text",
  "cap:op=generate;model=llm;task=summarize",
  "cap:op=embed;model=minilm"
]

Parallel Execution

When capabilities don’t depend on each other, MachineFabric runs them in parallel. Extract text and generate thumbnails simultaneously.

Media Types

Data flowing through MachineFabric is typed by media URNs. This enables automatic matching between cartridge outputs and inputs.

Common Types

System Architecture

MachineFabric runs as two processes that communicate via gRPC:

The Engine (Rust)

• Capability Router — Matches requests to cartridges
• Cartridge Host — Spawns and manages cartridge processes
• Database — SQLite for metadata and results
• Search Index — Tantivy full-text and vector search

The App (Swift)

• Library Browser — View and organize files
• Search Interface — Query across all content
• Cartridge Manager — Install and configure cartridges
• XPC Service — Sandboxed cartridge execution

Cartridge Execution

App (Swift)
    ↓ gRPC
Engine (Rust)
    ↓ spawn
XPC Service
    ↓ Bifaci protocol
Cartridge (any language)

Data Flow

Adding a File

1. User drops file into MachineFabric
2. Engine identifies media type
3. Engine finds extraction capabilities
4. Cartridges extract content in parallel:
   - Text extraction
   - Thumbnail generation
   - Metadata extraction
5. Results stored in database
6. Text indexed for search
7. Embeddings generated for semantic search

Search Query

1. User enters search query
2. Engine runs full-text search (Tantivy)
3. Engine runs semantic search (vector similarity)
4. Results merged and ranked
5. App displays matching content with context

Running a Capability

1. User selects files and capability
2. Engine resolves capability to cartridge
3. Cartridge spawned via XPC
4. Input data streamed via Bifaci
5. Cartridge processes and returns output
6. Output stored and indexed
7. App notified of completion

Privacy

MachineFabric is designed for local operation. Your files and AI processing stay on your Mac.

What Stays Local

• All your files
• All extracted content
• All AI model inference
• All search indexes
• All embeddings

Network Usage

MachineFabric connects to the internet only for:

• Downloading AI models (one-time, from HuggingFace)
• App updates (optional, from App Store)
• Cartridge downloads (optional, user-initiated)

Offline Mode

Once models are downloaded, MachineFabric works entirely offline. All cartridges run locally. No cloud APIs required.