AI Agent Reference

This page provides a structured, machine-readable summary of the Modellus system for AI agents that generate, interpret, or modify Modellus models.

Schema Files

Canonical references for model structure and expression syntax:

Shape Types

Expression Language Summary

Statement Types

Built-in Functions

Trig:      \sin, \cos, \tan, \cot, \sec, \csc
Inv Trig:  \arcsin, \arccos, \arctan
Hyperbolic: \sinh, \cosh, \tanh
Log:       \ln, \log
Two-arg:   \max(a,b), \min(a,b), \mod(a,b)
Utility:   sign(x), rnd(x), irnd(x), int(x), round(x)
Other:     \det(x), \sqrt{x}

Integral notation: expressions may include LaTeX forms such as \int_{a}^{b} f\left(x\right)\,\mathrm{d}x. For integer-part behavior, use int(x).

Operators

Arithmetic: +  -  \cdot  /  \frac{}{}  ^{}  !  \sqrt{}
Comparison: =  >  <  \ge  \le  \neq
Logical:    \lor (OR)  \land (AND)
Special:    \Delta (finite difference)

Constants

\pi = 3.14159...
e (or \E) = 2.71828...

Editor Shortcuts

Model JSON Structure

{
  "properties": {
    "independent": { "name": "t", "start": 0, "end": 10, "step": 0.1 },
    "initialValuesByCase": { "1": { "x": 0, "v": 5 } }
  },
  "shapes": [
    {
      "type": "expression",
      "id": "uuid",
      "expression": "\\displaylines{g=9.8\\\\\\frac{dx}{dt}=v}",
      "position": { "x": 100, "y": 100 }
    },
    {
      "type": "referential",
      "id": "uuid",
      "children": [
        { "type": "point", "id": "uuid", "xTerm": "x", "yTerm": "y" }
      ]
    }
  ]
}

Notebook Models

Besides board models, Modellus supports document-style notebooks. A notebook definition adds a top-level notebook field to the model JSON:

{
  "properties": { ... },
  "notebook": {
    "title": "string",
    "author": "string",
    "blocks": [
      { "id": 1, "type": "header", "content": "string", "backgroundColor": "transparent", "borderColor": "#e8e8e8" }
    ]
  }
}

Block type values: header, text, expression, chart, table, simulation, gauge, slider, value, media, question, ruler, protractor, slope. Expression blocks store the same LaTeX expression language in content; blocks are rendered top to bottom in array order.

Building Blocks and Component Objects

Visual objects that are not one of the shape classes above are built from building blocks: approved primitives, modifiers, behaviours and components held in a single registry. An agent never writes rendering code — it composes a declarative object definition through structured tools and the deterministic compiler turns it into an editable ComponentShape.

Call list_building_blocks for the live catalogue; it is generated from the same registry the renderer uses, so it never drifts. The published copy of it is Block Reference.

A definition is one JSON document: schemaVersion, type, category: "component", parameters (what the user edits, held in the shape's own properties), locals (derived values evaluated in order, LaTeX formulas over declared names only) and root (the node tree). A node is { id, type, properties, bindings, modifiers, behaviours, children } for a primitive or { id, type, parameters, modifiers, behaviours } for a component; a binding always wins over a constant, and when drops a child before compilation. Reserved parameters $width, $height, $iteration, $playing, $precision, $index and $count are reached through locals. Colours, fonts and axis values are written as design tokens ("token:stroke.accent"), never as literals. See Object Definition for the full specification.

Tools

Over the chat tool bridge these are named modellus_blocks_<tool>, for example modellus_blocks_bind_expression.

Workflow

1. list_model_variables and list_building_blocks to see what exists
2. create_object_draft, then add nodes, parameters, modifiers, behaviours and bindings
3. validate_object — errors come back as { code, path, message, expected, suggestion }
4. Correct the draft with the same tools and validate again
5. render_object_preview to check the result, then insert_object

Example error:

{ "valid": false, "errors": [ { "code": "UNKNOWN_VARIABLE", "path": "root.children[2].bindings.rotation", "message": "The variable 'minutes' does not exist in the current model.", "suggestion": "minute" } ] }

Limits

• Only registered block types may appear in a definition; unknown types are rejected
• Expressions are parsed by the Modellus engine — there is no JavaScript, eval or code tool
• Image sources are limited to https:, data:image/ and relative paths; path data must match the SVG path grammar
• At most 2 000 nodes, 16 levels of nesting, 8 levels of component nesting, 720 repeats and 512 characters per expression
• An invalid draft can be neither inserted nor saved

Key Rules for Agents

• Term names must be globally unique across all Expression shapes in a model
• Differential equations require initial values in properties.initialValuesByCase
• Second-order ODEs must be decomposed into two first-order ODEs
• All function calls use \left( and \right) delimiters
• Explicit multiplication uses \cdot — the × symbol is not in the grammar
• Positional child shapes (Point, Body, Vector, Line, Arc) require a Referential parent
• The expression field stores LaTeX in a \displaylines{} wrapper with \\ line separators
• Data columns in Tables produce terms of type DATA
• Regression results produce terms of type REGRESSION
• Objects that are not a built-in shape are composed from building blocks and inserted as a ComponentShape — never by writing rendering code
• A new object definition must declare every name its formulas read; an undeclared name is refused at registration rather than falling through to a model term
• Anything cartesian uses plot-grid, plot-axes and plot-crosshair rather than hand-drawn lines and text