Custom Domains Guide

Masar ships with built-in support for .orb schemas, but the underlying models work with any structured data that follows a state machine pattern. This guide shows how to use Masar with your own domain.

What Counts as a Domain

Any system with these properties is a good fit:

• Entities with defined fields (users, orders, devices, documents)
• States that entities move through (draft, active, archived)
• Transitions triggered by events (SUBMIT, APPROVE, CANCEL)
• Rules that constrain valid structures (every state needs an exit, every event needs a handler)

Examples: workflow engines, CI/CD pipelines, form builders, game rule systems, protocol definitions, infrastructure-as-code.

Define Your Domain Schema

Register your domain's structural vocabulary with Masar:

from masar import MasarClient

client = MasarClient()

client.domains.register(
    name="ci-pipeline",
    entity_types=["Pipeline", "Stage", "Job"],
    state_labels=["pending", "running", "passed", "failed", "skipped"],
    event_labels=["TRIGGER", "APPROVE", "RETRY", "CANCEL"],
    validation_rules=[
        {"rule": "every_stage_has_jobs", "description": "Each stage must contain at least one job"},
        {"rule": "no_orphan_jobs", "description": "Every job must belong to a stage"},
        {"rule": "terminal_states_exist", "description": "Pipeline must have at least one terminal state"}
    ]
)

Create Golden Behaviors

Golden behaviors are reference examples of correct structures. They teach Masar what "good" looks like in your domain:

client.behaviors.create(
    domain="ci-pipeline",
    name="basic-ci",
    schema={
        "entities": [{"name": "Pipeline", "fields": ["name", "status", "trigger"]}],
        "states": {"Pipeline": ["pending", "running", "passed", "failed"]},
        "transitions": [
            {"from": "pending", "event": "TRIGGER", "to": "running"},
            {"from": "running", "event": "PASS", "to": "passed"},
            {"from": "running", "event": "FAIL", "to": "failed"}
        ]
    },
    description="Basic CI pipeline with pass/fail outcomes"
)

After registering 5-10 golden behaviors, planning and verification quality improves significantly for your domain.

Use Planning With Your Domain

plan = client.plan_instructions(
    current={"entities": [{"name": "Pipeline"}]},
    goal="basic-ci",
    domain="ci-pipeline"
)

for step in plan.instructions:
    print(f"Level {step.level}: {step.action} - {step.params}")

Use Verification With Your Domain

Masar adapts its verification models to your registered rules:

check = client.verify(schema=my_pipeline, domain="ci-pipeline")
errors = client.error_check(schema=my_pipeline, domain="ci-pipeline")

How Accuracy Scales

Golden Behaviors	Planning Accuracy	Verification Accuracy
1-3	Basic structural guidance	Low
5-10	Good coverage of common patterns	Medium
20+	High accuracy, edge cases covered	High
50+	Near-expert level	Near-expert level

The more examples Masar sees of your domain, the better it gets at planning and verifying new instances.

Next Steps

• Embedding API - Search for similar behaviors across domains
• Memory Lifecycle - Build domain-specific memory