Skip to main content

Process API Guide

The Process API provides a unified /process/next endpoint that manages an entire construction session. Instead of calling plan, verify, and memory endpoints separately, you advance through a guided episode one step at a time.

How It Works​

An episode has three phases: start (get the plan), advance (execute steps and get the next one), and complete (store the result).

Start an Episode​

from masar import MasarClient

client = MasarClient()

episode = client.process.start(
    goal="std-helpdesk",
    domain="helpdesk",
    context="Customer wants a ticket routing system"
)

print(f"Episode: {episode.episode_id}")
print(f"Total steps: {episode.total_steps}")
print(f"First instruction: {episode.current_step}")

Response:

{
  "episode_id": "ep_abc123",
  "phase": "executing",
  "total_steps": 14,
  "current_step": {
    "level": 1,
    "action": "add_trait",
    "params": {"name": "TicketTriage", "linkedEntity": "Ticket"},
    "hint": "Create the triage trait first. All other structures depend on it."
  },
  "memory_match": {
    "pattern": "timeout-resolution",
    "similarity": 0.89
  }
}

The start phase automatically runs recall. If a matching pattern exists, it's included so your agent can decide whether to follow it or plan fresh.

Advance Through Steps​

After your LLM executes a step, advance to get the next one:

next_step = client.process.next(
    episode_id=episode.episode_id,
    result=updated_schema,  # schema after executing current step
)

print(f"Step {next_step.step_number}/{next_step.total_steps}")
print(f"Next: {next_step.current_step}")
print(f"Verification: valid={next_step.check.valid}, probability={next_step.check.probability}")

Each advance call automatically verifies the intermediate result. If verification detects issues, the response includes repair suggestions:

{
  "current_step": {"action": "add_transition", "params": {...}},
  "check": {"valid": false, "probability": 0.42},
  "repairs": [
    {"action": "fix_missing_initial_state", "params": {"trait": "TicketTriage", "state": "new"}}
  ]
}

Complete the Episode​

When all steps are done, complete the episode to store it in memory:

summary = client.process.complete(
    episode_id=episode.episode_id,
    final_schema=completed_schema,
    outcome="success"
)

print(f"Stored as episode {summary.episode_id}")
print(f"Final validity: {summary.validity}")

Domain-Language Translation​

The Process API translates between your domain language and Masar's internal operations. When you specify domain="helpdesk", step hints and action descriptions use helpdesk terminology ("ticket", "routing", "SLA") instead of generic terms ("entity", "trait", "transition").

This makes the API output more useful as direct context for your LLM.

Next Steps​