Reference
What MAG needs to run a Picture
A Picture is a complete, self-contained description of a situation. Give MAG these six blocks and it can compute a decision — nothing else is required, and nothing here is optional except where marked.
The Picture
What situation is MAG deciding about? One name, one sentence.
Required fields
- nametext— a short label for this picture
- statementtext— the situation in one plain sentence
Example
name: Factory Line
statement: The line is unsafe and defective;
fix it without blowing the energy budget.No domain is selected. The engine is domain-agnostic — the name is a label only, it changes nothing in the math.
Factors
What is measured in this picture — where it stands now, and where success is.
Required fields
- nametext— the measured quantity
- nownumber— its current value
- targetnumber | unknown— the value that counts as success (may be left unknown)
Example
LineSafety now 6 → target 9 DefectRate now 11 → target 3 QueueSize now 38 → target 8 EnergyCost now 380 → target unknown SlowLine now 0 → target unknown
Two kinds of factor live in one list. Outcome factors (LineSafety, DefectRate) are what MAG is judged on. Control factors (SlowLine, Overtime) are the levers — their target is normally unknown, because MAG is the one that sets them in step 05.
Effects
How do factors move each other? One line per cause-effect link.
Required fields
- fromfactor— the cause — usually a control factor
- tofactor— the factor that moves
- directionincreases | decreases— which way it moves
- per_unitnumber— how much `to` moves for +1 of `from`
Example
SlowLine → LineSafety increases +1 → +0.35 SlowLine → DefectRate decreases +1 → -0.8 SlowLine → EnergyCost decreases +1 → -15 ExtraInspect → DefectRate decreases +1 → -1.1 ExtraInspect → EnergyCost increases +1 → +18 Overtime → QueueSize decreases +1 → -5
This is the whole physics of the picture. Every effect must be a real number per unit — no verbal strength like 'strong' or 'weak'. Missing links mean MAG simply cannot see that consequence.
Limits
What lines must not be crossed, and what lines are only preferred?
Required fields
- kindhard | preferred— hard vetoes a plan, preferred only penalises it
- factorfactor— the factor being bounded
- boundat_least | at_most— direction of the bound
- valuenumber— the threshold
Example
[HARD] LineSafety at_least 8 [HARD] DefectRate at_most 12 [HARD] EnergyCost at_most 520 [PREFERRED] QueueSize at_most 15
Hard limits define feasibility: any plan that breaks one is rejected outright, however good its score. Preferred limits are soft — MAG will pay a penalty to cross them if the gain is worth it.
Options
Which controls may MAG use, and how far can each be pushed?
Required fields
- factorfactor— the control factor MAG is allowed to set
- minnumber— lowest allowed setting
- maxnumber— highest allowed setting
Example
SlowLine range 0 — 6 ExtraInspect range 0 — 5 StopForMaint range 0 — 4 Overtime range 0 — 6
These ranges are the entire action space. MAG will not invent a lever that is not listed here, and will never step outside a range.
Goal Posture
How ambitious, and how cautious, should MAG be?
Required fields
- target0 — 100— the score MAG must reach to call the picture solved
- caution1 — 10— how heavily uncertainty and risk are penalised
Example
target: 70 caution: 5
This is the only place with a matter of taste. Everything else is a fact about the picture; these two say what 'good enough' and 'too risky' mean for you.
The one rule
Everything MAG needs is a number or a named relationship — never an opinion, a story, or a domain. If a piece of information cannot be written as a value, a range, a bound, or a per-unit effect, MAG does not need it. That is why the same engine runs a factory line, a treatment plan, or a portfolio without changing a single equation.
