Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

6.0 KB
Raw Blame

description: "Domains organize concepts and pipes into semantic namespaces within .mthds files. Learn how to structure declarative AI workflows in Pipelex."

Understanding Domains

!!! tip "MTHDS Standard Reference" Domains are part of the MTHDS open standard. For the authoritative language specification, see Domains on mthds.ai. This page documents Pipelex-specific behavior and usage.

A domain in Pipelex is a semantic namespace that organizes related concepts and pipes. It's declared at the top of every .mthds file and serves as an identifier for grouping related functionality.

What is a Domain?

A domain is defined by three properties:

  • code (required) - The unique identifier for the domain (must be snake_case)
  • description (optional) - A human-readable description of the domain's purpose
  • system_prompt (optional) - A default system prompt for all PipeLLM operators in bundles using this domain

Declaring a Domain

Every .mthds file must declare its domain at the beginning:

domain = "invoice_processing"
description = "Tools for extracting, validating, and processing invoice documents"
system_prompt = "You are an expert in financial document analysis and invoice processing."

!!! important "Domain Code Naming Convention" Domain codes MUST be in snake_case (lowercase with underscores). Use descriptive names that clearly indicate the domain's purpose.

**Valid domain codes:**
```toml
✅ domain = "finance"
✅ domain = "invoice_processing"
✅ domain = "medical_records"
✅ domain = "customer_service"
```

**Invalid domain codes:**
```toml
❌ domain = "Finance"           # No uppercase
❌ domain = "invoice-processing" # No hyphens
❌ domain = "INVOICE_PROCESSING" # No all caps
❌ domain = "invoiceProcessing"  # camelCase not allowed
```

Hierarchical Domains

Domains support dotted paths to express a hierarchy:

domain = "legal"
domain = "legal.contracts"
domain = "legal.contracts.shareholder"

Each segment must be snake_case. The hierarchy is organizational — there is no scope inheritance between parent and child domains. legal.contracts and legal are independent namespaces; defining concepts in one does not affect the other.

Valid hierarchical domains:

✅ domain = "legal.contracts"
✅ domain = "legal.contracts.shareholder"
✅ domain = "finance.reporting"

Invalid hierarchical domains:

❌ domain = ".legal"              # Cannot start with a dot
❌ domain = "legal."              # Cannot end with a dot
❌ domain = "legal..contracts"    # No consecutive dots
❌ domain = "Legal.Contracts"     # Segments must be snake_case

Hierarchical domains are used in the [exports] section of METHODS.toml to control pipe visibility across domains. See Packages for details.

How Domains Work

Concept Namespacing

Every concept defined in a bundle belongs to the domain declared in that bundle. The full identifier for a concept is:

domain_code.ConceptName

Example:

domain = "finance"

[concept]
Invoice = "A commercial document for a sale"
Payment = "A financial transaction"

This creates two concepts:

  • finance.Invoice
  • finance.Payment

Domain as Namespace

The domain code prevents naming conflicts. Multiple bundles can define concepts with the same name if they're in different domains:

# finance.mthds
domain = "finance"
[concept]
Report = "A financial report"
# marketing.mthds
domain = "marketing"
[concept]
Report = "A marketing campaign report"

Result: Two different concepts (finance.Report and marketing.Report) with no conflict.

Multiple Bundles, Same Domain

Multiple .mthds files can declare the same domain. They all contribute to that domain's namespace:

# finance_invoices.mthds
domain = "finance"
[concept]
Invoice = "..."
# finance_payments.mthds
domain = "finance"
[concept]
Payment = "..."

Both files contribute to the finance domain, creating:

  • finance.Invoice
  • finance.Payment

Using Domains

In Bundle Files

Same-domain references (no prefix needed):

domain = "finance"

[concept]
Invoice = "A commercial document"

[pipe.process_invoice]
type = "PipeLLM"
inputs = { invoice = "Invoice" }    # Same domain, no prefix
output = "Text"
prompt = "Process this invoice: $invoice"

Cross-domain references (prefix required):

domain = "accounting"

[pipe.reconcile]
type = "PipeLLM"
inputs = { invoice = "finance.Invoice" }    # Different domain, needs prefix
output = "Report"
prompt = "Reconcile this invoice: $invoice"

In Python Code

Always use the full identifier when referencing concepts in code:

from pipelex.core.stuffs.stuff_factory import StuffFactory

invoice_stuff = StuffFactory.make_from_concept_ref(
    concept_ref="finance.Invoice",  # domain_code.ConceptName
    name="invoice_123",
    content=invoice_data,
)

System Prompt Inheritance

When you set a system_prompt at the domain level, it applies to all PipeLLM operators in bundles that declare that domain:

domain = "medical_records"
system_prompt = "You are a medical records specialist with expertise in HIPAA compliance."

[pipe.extract_diagnosis]
type = "PipeLLM"
# Automatically inherits the domain's system_prompt
inputs = { record = "MedicalRecord" }
output = "Diagnosis"
prompt = "Extract the primary diagnosis: $record"

Individual pipes can override the domain system prompt by defining their own system_prompt field.

Related Documentation