MachineFabric Documentation

What is MachineFabric

MachineFabric is a macOS application that orchestrates plugins 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 plugin.

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 plugin speaks the same language: CAPDAG. Drop a file, and MachineFabric finds the right plugins to process it. The output of one plugin becomes the input of the next. Plugins don't know about each other—MachineFabric handles the wiring.

Key Principles

• Everything is a plugin — AI models, file extractors, format converters. Same interface.
• Plugins 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 plugins 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 plugins that can handle that input type
3. Execute — The plugin runs, producing output with a new media type
4. Chain — If more processing is needed, the output feeds into the next plugin
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

CAPDAG (Capability Directed Acyclic Graph) is the naming system that makes MachineFabric work. It defines how capabilities are described, how requests are matched to implementations, and how plugins communicate.

Capability URNs

Every capability has a URN (Uniform Resource Name) that describes what it does:

cap:op=extract;format=pdf;target=text
cap:op=transcribe;format=audio
cap:op=embed;model=minilm
cap:op=generate;model=llm;task=summarize

Media URNs

Data flowing between plugins is typed by media URNs:

media:pdf;bytes      # PDF document as raw bytes
media:txt;textable   # Plain text content
media:png;bytes      # PNG image
media:json;embedding # Vector embedding as JSON

Matching

When MachineFabric needs a capability, it matches your request against available plugins. More specific capabilities take precedence. A plugin that handles cap:op=extract;format=pdf;target=text beats a generic cap:op=extract.

Read the CAPDAG matching spec →

Capabilities

A capability is an operation a plugin 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

Plugins 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 }
      }
    }
  ]
}

Plugins (Cartridges)

Plugins 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 Plugins Work

Plugins communicate via stdin/stdout using the Bifaci protocol:

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

Plugin Discovery

On startup, MachineFabric scans plugin directories:

• /Library/Application Support/MachineFabric/Plugins/
• ~/Library/Application Support/MachineFabric/Plugins/
• Bundled plugins in the app

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

Security

Distributed plugins must be signed and notarized:

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

Plugin development guide →

Orchestration

MachineFabric's job is to orchestrate plugins 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 plugins. 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 plugin outputs and inputs.

Common Types

Type Matching

Media types use tagged URN matching. A plugin accepting media:png;bytes can also handle media:png;bytes;dimensions=1024x768 (more specific types are subtypes of less specific ones).

System Architecture

MachineFabric runs as two processes that communicate via gRPC:

The Engine (Rust)

• Capability Router — Matches requests to plugins
• Plugin Host — Spawns and manages plugin 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
• Plugin Manager — Install and configure plugins
• XPC Service — Sandboxed plugin execution

Plugin Execution

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

Data Flow

Adding a File

1. User drops file into MachineFabric
2. Engine identifies media type
3. Engine finds extraction capabilities
4. Plugins 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 plugin
3. Plugin spawned via XPC
4. Input data streamed via Bifaci
5. Plugin 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)
• Plugin downloads (optional, user-initiated)

Offline Mode

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