Improve your model

Two things can be off. Your model may not match your instructions and rules somewhere: a targeted retrain sharpens it there. Or a rule itself may be wrong: change the rule: it retrains straight away, and the build says what it changed. A retrain brings your model closer to your instructions and rules; it can't make a wrong rule right, so the advice below points out rules your outcomes contradict.

Every retrain is your call. Nothing retrains, promotes or changes a rule on its own.

This page is about models made with POST /v1/build. Advice and marking a decision wrong work for every model. For outcomes, the unsure queue, new options and replacing cases, see Improving.

Advice

What would improve your model most right now, in plain words, most useful first. It's also in GET /v1/domains/{domain}/progress as advice, and on the console's Progress tab as cards. Read-only.

{ "domain": "cards", "statement": "3 things would improve your model most right now.",
  "items": [
    { "kind": "retrain_to_sharpen", "title": "Retrain to sharpen 'topic'", "action": "retrain", "question": "topic",
      "agreement": 0.91,
      "text": "'topic' matches your instructions and rules in 91% of situations when the right answer is 'lost_card' (97.8% overall). A retrain adds situations where your model disagrees and shows the before and after for them." },
    { "kind": "rule_may_be_wrong", "title": "This rule may be wrong", "action": "change_rules",
      "rule": "Never approve when amount is over 500", "contradicted": 7, "applied": 20,
      "text": "…in 7 of the 20 outcomes where it applied, the right answer went against it ('approve'). If it should allow that, change the rule: the build shows what it changes." },
    { "kind": "answer_these", "title": "Answer a few of these", "action": "answer",
      "decisions": [{ "decision_id": "dec_…", "summary": "…", "answer": "refund", "confidence": 0.41 }],
      "text": "These 5 decisions in your unsure queue are the ones your model was least sure about. …" } ] }

CLI: canonopy advice refunds. MCP: get_advice (model). Python: client.advice("refunds").

Targeted retrain

The same call as any retrain. On a model made with POST /v1/build, it runs as a build of kind retrain, from the same instructions and rules, and adds:

• situations where the current version disagrees with your instructions and rules;
• more around the answers it confuses, and around the answers your hard rules depend on and their look-alikes (for "block the card when the topic is lost_card": a compromised card, a stolen phone);
• your new cases since the last version (uploads, outcomes, unsure-queue answers);
• the decisions you marked wrong, and the examples you corrected. Your instructions are made to give those right answers first. Nothing waits for you.

curl -X POST https://api.canonopylabs.com/v1/domains/cards/train \
  -H "Authorization: Bearer $CANONOPY_API_KEY" -H "Content-Type: application/json" -d '{"wait": false}'
# → a Job with build_id; follow it:
curl https://api.canonopylabs.com/v1/build/bld_… -H "Authorization: Bearer $CANONOPY_API_KEY"

The Job has build_id; with wait: true it waits for the build and answers with its training job (the version and its report). The build's retrain says what it added and, once checked, the before and after on the same fresh situations:

"retrain": { "since_version": 3,
  "added": { "disagreements": 312, "around_confusions": 900, "look_alikes": 600, "example_messages": 40, "corrections": 2 },
  "areas": [{ "question": "topic", "answer": "lost_card", "area": "when the right answer to 'topic' is 'lost_card'",
              "before": 0.91, "after": 0.99, "cases": 240 }],
  "statement": "Added 312 situations where version 3 disagreed with your instructions and rules and 1,500 more around 'lost_card', 'card_fault' and their look-alikes. Before and after: when the right answer to 'topic' is 'lost_card': 91% → 99%." }

The version's report has it too (build.retrain), and the Progress tab compares the versions. The new version serves when every question passes the 95% bar; with your history, it's also measured on the same held-back cases of yours as before. questions in the body retrains only those questions, the usual way. A retrain counts as a build (20 per workspace per UTC day).

Change a rule with a preview

Say the change in plain words. Your model is retrained with the new rules straight away, and the new version serves only if it passes the quality check; until then, @latest keeps the version before.

{ "rules": "Always escalate when amount is over 300.", "mode": "add" }

mode: add (to your current rules, the default) or replace (these are all your rules now). It answers with a Build of kind rule_change. Its rule_preview says what changes:

"rule_preview": {
  "rules": "Never approve when amount is over 500.\nAlways escalate when amount is over 300.",
  "previous_rules": "Never approve when amount is over 500.",
  "situations": 1240, "of": 3000,
  "changes": [{ "question": "action", "from": "approve", "to": "escalate", "situations": 1100 }, "…"],
  "examples": [{ "state": { "…": "…" }, "before": { "action": "approve" }, "after": { "action": "escalate" } }, "…"],
  "statement": "Changes 1,240 of 3,000 situations: approve → escalate (1,100), decline → escalate (140)." }

About 10 changed situations come with it. The build's examples (GET /v1/domains/{domain}/examples) are situations whose answer changes: reviewing them is optional. If one is wrong, correct it with POST /v1/domains/{domain}/signoff and "retrain": true, and the next version gives that answer.

curl https://api.canonopylabs.com/v1/domains/refunds/rules \
  -H "Authorization: Bearer $CANONOPY_API_KEY" -H "Content-Type: application/json" \
  -d '{"rules": "Always escalate when amount is over 300."}'

A message to the set-up agent (POST /v1/domains/{domain}/agent) on a built model does the same with mode: add; its reply has the build_id. MCP: change_rules (model, rules, mode). In the console, change the rules on the model: it retrains, and the build shows what changed. Errors: 400 (not a model made with POST /v1/build: change its rules with the set-up agent; or no rules), 402, 409 (a build is in progress), 429 (a rule change counts as a build).

Mark a decision wrong

The second works with the decision id alone, as POST /v1/decide returned it.

{ "answers": { "action": "escalate" } }
{ "action": "escalate", "note": "over the limit" }

answers (per question) or action (the decision question's answer), and an optional note for your own records. → {"recorded": true, "decision_id", "domain", "answers", "message"}.

• It's recorded as the decision's outcome, with via: "marked_wrong"; the decision log shows it (marked_wrong: true), and Progress counts it under "Decisions you marked wrong".
• The next retrain learns it. On a built model, the retrain first makes your instructions give that answer there.
• When your corrections go against a rule, advice says so (rule_may_be_wrong).

CLI: canonopy decisions wrong dec_… --answer escalate (or --answer action=escalate, and --note "…"). MCP: mark_decision_wrong (decision_id, answers or action, note). Python: client.mark_wrong("dec_…", action="escalate"). Console: Mark wrong on a decision in the decision log. 400: an unknown question or answer; 404: no such decision.

A loop that works

1. Read the advice on Progress (or canonopy advice).
2. Weak spot? Retrain, and read the before and after.
3. A rule your outcomes contradict? Change it, and read what it changed (the changed examples are optional to review).
4. Mark the wrong decisions you find in the log, and answer the unsure queue: the next retrain learns them.
5. Promote or roll back as usual: see Versions.