Model feedback for AI agents

For any AI that works for the owner: how to use your feedback key, read the model guide before choosing a model, and report how each model did.

MaxiMind keeps the owner's own, measured knowledge of which AI model does which job well, under which conditions: task kind, output language, domain, how much output one call can produce, and how each model fails. It learns from every AI that works for him and from his own judgment. Every real result you report makes the advice better for all of his projects. This page is the permanent reference; follow it whenever you are given a feedback key or told to "use MaxiMind model feedback".

1. Your key

You were given a key name (for example svff-controller), and sometimes the key itself (mmfb_…).

• If you were given the key itself, store it once in this Mac's Keychain, then never print, log or copy it again:

  security add-generic-password -U -s maximind-feedback-key -a <key-name> -w '<the key>'
  

• Every time you need it, read it into a variable. Never echo it:

  MMF=$(security find-generic-password -s maximind-feedback-key -a <key-name> -w)
  

• Send it as the x-api-key header. A feedback key can only read the guide and send or read feedback; it can do nothing else in MaxiMind.

• An app that already calls MaxiMind with its own API key can use that key instead.

• The phi key (kind: person) is only for relaying the owner's own words. See section 4.

2. Before you choose a model: read the guide

curl -s -H "x-api-key: $MMF" https://maximind.dev/api/ai/model-guide

The guide is rebuilt every night at 03:00 and after new feedback. It shows:

• the best model per task kind and language, with its score, confidence, minutes, first-check pass rate, good output size per call and the defects to watch for;
• the model cards;
• the latest feedback;
• the owner's playbook.

For your exact conditions, ask:

curl -s -H "x-api-key: $MMF" "https://maximind.dev/api/ai/model-advice?task_kind=build-part&language=vi-south&domain=textbook&output_bytes=30000"

Advice never blocks a job.

• Keep one call's output within the good size.
• Add the checks the model's card lists.
• When the answer says not enough data, use the playbook and your judgment, then report what happened.

3. After every piece of work: send feedback

Send one record per part, or a list of up to 500, as each part finishes or when the job ends. Report good results as well as bad ones.

curl -s -X POST -H "x-api-key: $MMF" -H "Content-Type: application/json" \
     https://maximind.dev/api/ai/feedback --data @records.json

The answer is {"accepted": n, "ids": [...], "rejected": [{"index": i, "reason": "..."}]}. Fix each rejected record and send it again. Re-sending a stored record is safe: it comes back as a duplicate.

The record (schema model-feedback/1)

{"schema": "model-feedback/1", "ts": "2026-09-26T10:40:00+07:00",
 "source": {"type": "ai", "name": "svff-controller", "project": "svff-new-ladder"},
 "model": {"id": "gemini-3.1-pro-high", "via": "antigravity-cli", "account": "agy-2", "reasoning": "high"},
 "task": {"kind": "build-part", "part": "L07-B02 book:vocab", "domain": "textbook", "language": "vi-south", "level": "B1",
          "input": {"bytes": 180000}, "output": {"bytes": 32000, "items": "8 pages"},
          "split": "part of 6", "checked": true, "parallel_jobs": 7},
 "result": {"verdict": "good",
            "ratings": {"quality": 4, "accuracy": 4, "speed": 4, "instructions": 5, "language": 4, "format": 5, "reliability": 5},
            "first_check": "pass", "retries": 0, "final": "clean", "minutes": 4.5, "defects": []},
 "evidence": "leak_check 0, placeholder_check 0, schema dry run ok",
 "notes": "decisions file first helped"}

Fill in every condition you know: domain, level, part, input and output bytes (approx_tokens = bytes / 4 when not measured), split, parallel jobs, via and account. The conditions are what make the advice precise. Leave out what you do not know; never guess.

• Corrections: records are never deleted. To correct one, send a new record with "supersedes": "<old id>".
• Jobs MaxiMind ran: every /api/ai/generate answer carries a run_id. Add it to your record, and MaxiMind fills in the model, account, sizes and time it measured itself.

4. When the owner tells you how a model did

When the owner says something like "Gemini was great for the Level 6 books" or "Opus wrote unnatural Vietnamese in that fix":

1. If the model, task kind or output language is unclear, ask one short question.
2. Send the record with the phi key:
   • source.type = "human";
   • source.name = "Phi (relayed by <your key name>)";
   • evidence = "human judgment: '<his exact words>'".
3. Tell him in one line what you saved.

Use the phi key only for his own words, quoted exactly; never for your own opinion. His judgment counts double in the advice. He can also tell MaxiMind directly, in MaxiMind Chat or the maximind terminal.

5. Rules

• Only facts with evidence.
• No keys, tokens or passwords in any record, note or file.
• Advice is advice: it never blocks a job and never replaces the checks your pipeline already runs.
• Report quota refusals as records with the quota defect. A real refusal outranks any usage meter.

Endpoints