إنتقل إلى المحتوى الرئيسي

Repair API

The Repair API takes a failing schema and its error codes, then returns an optimal sequence of repair actions. It uses beam search to explore multiple repair paths simultaneously and returns the highest-scoring candidates.

POST /rank-edits/jepa​

Request:

curl -X POST https://api.masar.almadar.io/rank-edits/jepa \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "name": "App",
      "orbitals": [{"entity": "Ticket", "traits": ["Triage"]}]
    },
    "errors": ["missing_transition", "orphan_event", "missing_render_effect"],
    "beam_width": 5,
    "max_steps": 10
  }'

Response:

{
  "suggestions": [
    {
      "rank": 1,
      "score": 0.93,
      "actions": [
        {"step": 1, "action": "add_transition", "params": {"trait": "Triage", "from": "new", "event": "ASSESS", "to": "assessing"}},
        {"step": 2, "action": "remove_event", "params": {"trait": "Triage", "event": "UNUSED_EVENT"}},
        {"step": 3, "action": "add_effect", "params": {"trait": "Triage", "state": "assessing", "effect": "render-ui"}}
      ],
      "predicted_validity": 0.96
    },
    {
      "rank": 2,
      "score": 0.88,
      "actions": [
        {"step": 1, "action": "add_transition", "params": {"trait": "Triage", "from": "new", "event": "ASSESS", "to": "assessing"}},
        {"step": 2, "action": "add_transition", "params": {"trait": "Triage", "from": "new", "event": "UNUSED_EVENT", "to": "assessing"}},
        {"step": 3, "action": "add_effect", "params": {"trait": "Triage", "state": "assessing", "effect": "render-ui"}}
      ],
      "predicted_validity": 0.89
    }
  ],
  "beam_width": 5,
  "steps_explored": 3
}

Parameters​

ParameterTypeDefaultDescription
schemaobjectrequiredThe schema to repair
errorsstring[]requiredError category codes from /error-check
beam_widthint5Number of parallel repair paths to explore
max_stepsint10Maximum repair actions per path

How Beam Search Works​

The repair process explores multiple fix strategies in parallel:

  1. Start: The failing schema is the root state
  2. Expand: For each candidate, generate possible next repair actions
  3. Score: Predict the validity of each resulting schema
  4. Prune: Keep only the top beam_width candidates
  5. Repeat: Continue until all candidates are valid or max_steps is reached

This avoids greedy repair (fixing one error but introducing another) by evaluating the cumulative effect of each action sequence.

Python SDK​

from masar import MasarClient

client = MasarClient()

repairs = client.rank_edits(
    schema=failing_schema,
    errors=["missing_transition", "orphan_event"],
    beam_width=5,
    max_steps=10
)

# Apply the top suggestion
best = repairs.suggestions[0]
for action in best.actions:
    print(f"Step {action.step}: {action.action}({action.params})")

Next Steps​