Tool tree
Reactive visualization for power systems optimization. Drag demand and watch locational marginal prices and their adjoint sensitivities update from KKT columns, with exact DC OPF and SOCWR solves…
Implementation
gradeNot graded
gradeNot graded
list_casesAnswer
List configured and imported cases, including unavailable cases and their reported reasons. Returns stable case IDs, the displayed revision, and a pagination offset for select_case.
View tool JSON
{
"name": "list_cases",
"kind": "answer",
"impl": "imperative",
"description": "List configured and imported cases, including unavailable cases and their reported reasons. Returns stable case IDs, the displayed revision, and a pagination offset for select_case.",
"inputSchema": {
"type": "object",
"properties": {
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 100000,
"description": "Pagination offset. Defaults to 0; use next_offset from the previous result."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Maximum cases. Defaults to 10."
}
},
"additionalProperties": false
},
"page": "/"
}select_caseAction
Show a case from list_cases using the same controls as the case tabs. Leaves saved Studies intact and exits historical inspection. Changes the view only; no proposal approval is required.
View tool JSON
{
"name": "select_case",
"kind": "act",
"impl": "imperative",
"description": "Show a case from list_cases using the same controls as the case tabs. Leaves saved Studies intact and exits historical inspection. Changes the view only; no proposal approval is required.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Case ID from list_cases."
},
"expected_revision": {
"type": "string",
"description": "Optional displayed revision from list_cases or inspect_case, checked before selection."
}
},
"required": [
"case_id"
],
"additionalProperties": false
},
"page": "/"
}solve_multiconductor_pfAction
Calculate terminal voltages, currents, and powers for the displayed multiconductor case. Uses prescribed demand and source voltages. Rejects unsupported equipment physics. Does not optimize dispatch or change electrical inputs. Use query_network for terminal results.
View tool JSON
{
"name": "solve_multiconductor_pf",
"kind": "act",
"impl": "imperative",
"description": "Calculate terminal voltages, currents, and powers for the displayed multiconductor case. Uses prescribed demand and source voltages. Rejects unsupported equipment physics. Does not optimize dispatch or change electrical inputs. Use query_network for terminal results.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Case ID from inspect_case."
},
"expected_revision": {
"type": "string",
"description": "Displayed revision from inspect_case."
},
"max_iterations": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"description": "Iteration limit, default 100."
}
},
"required": [
"case_id",
"expected_revision"
],
"additionalProperties": false
},
"page": "/"
}inspect_caseAction
Inspect the displayed network, including a saved Study state when one is shown. Returns case, state, formulation, units, and revision. Saved states are read-only; select_case returns to the editable case.
View tool JSON
{
"name": "inspect_case",
"kind": "act",
"impl": "imperative",
"description": "Inspect the displayed network, including a saved Study state when one is shown. Returns case, state, formulation, units, and revision. Saved states are read-only; select_case returns to the editable case.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"page": "/"
}query_networkAnswer
Query buses or branches in the displayed network by stable ID or metric. For the highest LMP use element_kind bus, sort_by price, direction desc, limit 1. Returns saved-state values when a Study state is shown.
View tool JSON
{
"name": "query_network",
"kind": "answer",
"impl": "imperative",
"description": "Query buses or branches in the displayed network by stable ID or metric. For the highest LMP use element_kind bus, sort_by price, direction desc, limit 1. Returns saved-state values when a Study state is shown.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"element_kind": {
"type": "string",
"enum": [
"bus",
"branch"
],
"description": "Element type."
},
"element_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Specific stable IDs to return. Omit to rank elements."
},
"sort_by": {
"type": "string",
"enum": [
"id",
"demand_mw",
"generation_mw",
"price",
"voltage_pu",
"voltage_v",
"loading",
"flow_mw",
"rating_mw"
],
"description": "Metric for ranking. Defaults to demand_mw for buses and loading for branches."
},
"direction": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort direction. Defaults to desc."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Maximum rows. Defaults to 5."
}
},
"required": [
"case_id",
"element_kind"
],
"additionalProperties": false
},
"page": "/"
}analyze_sensitivityAction
Compute the displayed formulation's LMP sensitivity for one bus demand or branch rating and return the largest responses. Leaves the visible selection unchanged.
View tool JSON
{
"name": "analyze_sensitivity",
"kind": "act",
"impl": "imperative",
"description": "Compute the displayed formulation's LMP sensitivity for one bus demand or branch rating and return the largest responses. Leaves the visible selection unchanged.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"target": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"bus",
"branch"
],
"description": "Element type."
},
"element_id": {
"type": "string",
"description": "Stable element ID returned by query_network."
}
},
"required": [
"kind",
"element_id"
],
"additionalProperties": false
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Maximum response rows. Defaults to 5."
}
},
"required": [
"case_id",
"target"
],
"additionalProperties": false
},
"page": "/"
}focus_networkAction
Focus a bus or branch in the tellegen interface and load its computed sensitivity view. The returned result reflects the interface after the selection has settled.
View tool JSON
{
"name": "focus_network",
"kind": "act",
"impl": "imperative",
"description": "Focus a bus or branch in the tellegen interface and load its computed sensitivity view. The returned result reflects the interface after the selection has settled.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"target": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"bus",
"branch"
],
"description": "Element type."
},
"element_id": {
"type": "string",
"description": "Stable element ID returned by query_network."
}
},
"required": [
"kind",
"element_id"
],
"additionalProperties": false
}
},
"required": [
"case_id",
"target"
],
"additionalProperties": false
},
"page": "/"
}preview_case_updateAction
Predict objective and locational marginal price (LMP) changes for bounded demand or branch rating edits at the current formulation. Leaves the case and visible interface unchanged and requires the current revision.
View tool JSON
{
"name": "preview_case_update",
"kind": "act",
"impl": "imperative",
"description": "Predict objective and locational marginal price (LMP) changes for bounded demand or branch rating edits at the current formulation. Leaves the case and visible interface unchanged and requires the current revision.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"expected_revision": {
"type": "string",
"description": "Current revision from inspect_case; protects against stale analysis."
},
"mode": {
"type": "string",
"enum": [
"set",
"increment"
],
"description": "Set final deltas or add the supplied MW changes. Defaults to set."
},
"demand": {
"type": "array",
"maxItems": 24,
"description": "Bus demand delta edits in MW from the base case.",
"items": {
"type": "object",
"properties": {
"bus_id": {
"type": "string",
"description": "Stable bus ID from query_network."
},
"delta_mw": {
"type": "number",
"description": "Demand delta in MW."
}
},
"required": [
"bus_id",
"delta_mw"
],
"additionalProperties": false
}
},
"ratings": {
"type": "array",
"maxItems": 24,
"description": "Branch rating delta edits in MW from the base case.",
"items": {
"type": "object",
"properties": {
"branch_id": {
"type": "string",
"description": "Stable branch ID from query_network."
},
"delta_mw": {
"type": "number",
"description": "Branch rating delta in MW."
}
},
"required": [
"branch_id",
"delta_mw"
],
"additionalProperties": false
}
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Maximum predicted locational marginal price (LMP) changes. Defaults to 5."
}
},
"required": [
"case_id",
"expected_revision"
],
"additionalProperties": false
},
"page": "/"
}update_caseAction
Atomically set or increment demand and branch-rating deltas, optionally choose a formulation, then solve and update the visible interface. Requires the current revision.
View tool JSON
{
"name": "update_case",
"kind": "act",
"impl": "imperative",
"description": "Atomically set or increment demand and branch-rating deltas, optionally choose a formulation, then solve and update the visible interface. Requires the current revision.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"expected_revision": {
"type": "string",
"description": "Current revision from inspect_case; protects against stale writes."
},
"mode": {
"type": "string",
"enum": [
"set",
"increment"
],
"description": "Set final deltas or add the supplied MW changes. Defaults to set."
},
"demand": {
"type": "array",
"maxItems": 24,
"description": "Bus demand delta edits in MW from the base case.",
"items": {
"type": "object",
"properties": {
"bus_id": {
"type": "string",
"description": "Stable bus ID from query_network."
},
"delta_mw": {
"type": "number",
"description": "Demand delta in MW."
}
},
"required": [
"bus_id",
"delta_mw"
],
"additionalProperties": false
}
},
"ratings": {
"type": "array",
"maxItems": 24,
"description": "Branch rating delta edits in MW from the base case.",
"items": {
"type": "object",
"properties": {
"branch_id": {
"type": "string",
"description": "Stable branch ID from query_network."
},
"delta_mw": {
"type": "number",
"description": "Branch rating delta in MW."
}
},
"required": [
"branch_id",
"delta_mw"
],
"additionalProperties": false
}
},
"formulation": {
"type": "string",
"description": "Available formulation ID shown by inspect_case."
}
},
"required": [
"case_id",
"expected_revision"
],
"additionalProperties": false
},
"page": "/"
}reset_caseAction
Clear all committed demand and branch-rating edits in the active case, keep its formulation, solve, and update the visible interface. Requires the current revision.
View tool JSON
{
"name": "reset_case",
"kind": "act",
"impl": "imperative",
"description": "Clear all committed demand and branch-rating edits in the active case, keep its formulation, solve, and update the visible interface. Requires the current revision.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"expected_revision": {
"type": "string",
"description": "Current revision from inspect_case; protects against stale writes."
}
},
"required": [
"case_id",
"expected_revision"
],
"additionalProperties": false
},
"page": "/"
}create_studyAction
Save the current case and its results as a Study. A planning goal is optional; add or revise it later. Creating a Study does not change the network or apply a proposal.
View tool JSON
{
"name": "create_study",
"kind": "act",
"impl": "imperative",
"description": "Save the current case and its results as a Study. A planning goal is optional; add or revise it later. Creating a Study does not change the network or apply a proposal.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_case_revision": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"study": {
"additionalProperties": false,
"properties": {
"decisions": {
"anyOf": [
{
"$ref": "#/$defs/DecisionSpace"
},
{
"type": "null"
}
]
},
"display": {
"anyOf": [
{
"$ref": "#/$defs/CreateDisplay"
},
{
"type": "null"
}
]
},
"formulation": {
"enum": [
"dcopf",
"acpf",
"socwr"
],
"type": "string"
},
"interpretation": {
"default": "",
"type": "string"
},
"model_details": {
"anyOf": [
{
"$ref": "#/$defs/ModelDetails"
},
{
"type": "null"
}
]
},
"objective": {
"anyOf": [
{
"$ref": "#/$defs/StudyObjective"
},
{
"type": "null"
}
]
},
"request": {
"default": "",
"type": "string"
},
"solution": {
"description": "A saved solution must belong to the supplied instance.",
"type": [
"string",
"null"
]
},
"success_value": {
"format": "double",
"type": [
"number",
"null"
]
},
"title": {
"type": "string"
},
"view": {
"anyOf": [
{
"$ref": "#/$defs/SolveResponse"
},
{
"type": "null"
}
]
}
},
"required": [
"title",
"formulation"
],
"type": "object"
},
"goal": {
"additionalProperties": false,
"properties": {
"decisions": {
"anyOf": [
{
"$ref": "#/$defs/DecisionSpace"
},
{
"type": "null"
}
]
},
"display": {
"anyOf": [
{
"$ref": "#/$defs/CreateDisplay"
},
{
"type": "null"
}
]
},
"formulation": {
"enum": [
"dcopf",
"acpf",
"socwr"
],
"type": "string"
},
"interpretation": {
"default": "",
"type": "string"
},
"model_details": {
"anyOf": [
{
"$ref": "#/$defs/ModelDetails"
},
{
"type": "null"
}
]
},
"objective": {
"anyOf": [
{
"$ref": "#/$defs/StudyObjective"
},
{
"type": "null"
}
]
},
"request": {
"default": "",
"type": "string"
},
"solution": {
"description": "A saved solution must belong to the supplied instance.",
"type": [
"string",
"null"
]
},
"success_value": {
"format": "double",
"type": [
"number",
"null"
]
},
"title": {
"type": "string"
},
"view": {
"anyOf": [
{
"$ref": "#/$defs/SolveResponse"
},
{
"type": "null"
}
]
}
},
"required": [
"title",
"formulation"
],
"type": "object",
"description": "Legacy alias for study."
}
},
"required": [
"case_id",
"expected_case_revision"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"study"
],
"not": {
"required": [
"goal"
]
}
},
{
"required": [
"goal"
],
"not": {
"required": [
"study"
]
}
}
],
"$defs": {
"DecisionSpace": {
"additionalProperties": false,
"description": "The feasible set, distinct from both the inner problem and the outer goal.",
"properties": {
"demand": {
"anyOf": [
{
"$ref": "#/$defs/DemandConstraint"
},
{
"type": "null"
}
]
},
"max_changed_elements": {
"format": "uint",
"maximum": 65536,
"minimum": 1,
"type": "integer"
},
"total_budget": {
"format": "double",
"minimum": 0,
"type": "number"
},
"variables": {
"items": {
"$ref": "#/$defs/DecisionVariable"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
}
},
"required": [
"variables",
"total_budget",
"max_changed_elements"
],
"type": "object"
},
"DemandConstraint": {
"oneOf": [
{
"additionalProperties": false,
"description": "Allocate this additional MW across the declared demand decisions.",
"properties": {
"increase_mw": {
"format": "double",
"type": "number"
},
"kind": {
"const": "placement",
"type": "string"
}
},
"required": [
"kind",
"increase_mw"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Preserve the existing total MW across the declared demand decisions.",
"properties": {
"kind": {
"const": "redistribution",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
}
]
},
"DecisionVariable": {
"additionalProperties": false,
"description": "Bounds and increments apply to changes from the goal's anchor state in a Study.",
"properties": {
"budget_weight": {
"description": "Budget consumption per absolute unit of intervention.",
"format": "double",
"type": "number"
},
"element": {
"$ref": "#/$defs/ElementKey"
},
"id": {
"maxLength": 128,
"minLength": 1,
"type": "string"
},
"increment": {
"format": "double",
"type": "number"
},
"intervention": {
"$ref": "#/$defs/Intervention"
},
"lower": {
"format": "double",
"type": "number"
},
"upper": {
"format": "double",
"type": "number"
}
},
"required": [
"id",
"element",
"intervention",
"lower",
"upper",
"increment",
"budget_weight"
],
"type": "object"
},
"ElementKey": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"Intervention": {
"description": "A numerical intervention supported by the existing solvers.",
"enum": [
"branch_rating",
"active_demand"
],
"type": "string"
},
"CreateDisplay": {
"additionalProperties": false,
"properties": {
"camera": {
"anyOf": [
{
"$ref": "#/$defs/Camera"
},
{
"type": "null"
}
]
},
"case_id": {
"type": "string"
},
"diagram_camera": {
"anyOf": [
{
"$ref": "#/$defs/DiagramCamera"
},
{
"type": "null"
}
],
"default": null
},
"geo_layer": {
"type": "string"
},
"layers": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"case_id",
"geo_layer"
],
"type": "object"
},
"Camera": {
"additionalProperties": false,
"properties": {
"bearing": {
"format": "double",
"type": "number"
},
"center": {
"items": {
"format": "double",
"type": "number"
},
"maxItems": 2,
"minItems": 2,
"type": "array"
},
"pitch": {
"format": "double",
"type": "number"
},
"zoom": {
"format": "double",
"type": "number"
}
},
"required": [
"center",
"zoom",
"bearing",
"pitch"
],
"type": "object"
},
"DiagramCamera": {
"additionalProperties": false,
"properties": {
"center": {
"items": {
"format": "double",
"type": "number"
},
"maxItems": 2,
"minItems": 2,
"type": "array"
},
"scale": {
"format": "double",
"type": "number"
}
},
"required": [
"center",
"scale"
],
"type": "object"
},
"ModelDetails": {
"properties": {
"approximations": {
"items": {
"$ref": "#/$defs/CostApproximation"
},
"type": "array"
},
"method": {
"$ref": "#/$defs/CostPreparation"
},
"model": {
"type": "string"
},
"quantity": {
"type": "string"
},
"source": {
"type": "string"
},
"units": {
"type": "string"
}
},
"required": [
"method",
"source",
"model",
"quantity",
"units",
"approximations"
],
"type": "object"
},
"CostApproximation": {
"properties": {
"bus": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"generator": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"max_breakpoint_error": {
"format": "double",
"type": "number"
},
"model_cost": {
"$ref": "#/$defs/GenCost"
},
"rms_breakpoint_error": {
"format": "double",
"type": "number"
},
"source_cost": {
"$ref": "#/$defs/GenCost"
}
},
"required": [
"generator",
"bus",
"source_cost",
"model_cost",
"rms_breakpoint_error",
"max_breakpoint_error"
],
"type": "object"
},
"GenCost": {
"description": "A generator cost curve (`mpc.gencost` row).",
"properties": {
"coeffs": {
"description": "Raw coefficients, highest order first for the polynomial model:\n`[c_{k-1}, …, c1, c0]`.",
"items": {
"format": "double",
"type": "number"
},
"type": "array"
},
"model": {
"description": "1 = piecewise linear, 2 = polynomial.",
"format": "uint8",
"maximum": 255,
"minimum": 0,
"type": "integer"
},
"ncost": {
"description": "Number of cost coefficients (polynomial) or breakpoints (piecewise).",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"shutdown": {
"format": "double",
"type": "number"
},
"startup": {
"format": "double",
"type": "number"
}
},
"required": [
"model",
"startup",
"shutdown",
"ncost",
"coeffs"
],
"type": "object"
},
"CostPreparation": {
"enum": [
"exact",
"convex_quadratic_fit"
],
"type": "string"
},
"StudyObjective": {
"description": "A scalar goal over the exact operating point and explicit interventions.",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "weighted_observable",
"type": "string"
},
"operand": {
"$ref": "#/$defs/Operand"
},
"weights": {
"items": {
"$ref": "#/$defs/ObservableWeight"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
}
},
"required": [
"kind",
"operand",
"weights"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "sum",
"type": "string"
},
"terms": {
"items": {
"$ref": "#/$defs/StudyObjective"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
}
},
"required": [
"kind",
"terms"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"expression": {
"$ref": "#/$defs/StudyObjective"
},
"factor": {
"format": "double",
"type": "number"
},
"kind": {
"const": "scale",
"type": "string"
}
},
"required": [
"kind",
"factor",
"expression"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"expression": {
"$ref": "#/$defs/StudyObjective"
},
"kind": {
"const": "squared_target",
"type": "string"
},
"target": {
"format": "double",
"type": "number"
}
},
"required": [
"kind",
"target",
"expression"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"decision": {
"type": "string"
},
"kind": {
"const": "intervention_penalty",
"type": "string"
},
"linear": {
"format": "double",
"type": "number"
},
"quadratic": {
"format": "double",
"type": "number"
}
},
"required": [
"kind",
"decision",
"linear",
"quadratic"
],
"type": "object"
}
]
},
"Operand": {
"description": "What a sensitivity is taken *of*, named for the physical power quantity rather\nthan a formulation's internal variable. The orthogonal sub-axes (active/reactive,\nfrom/to, voltage representation) are visible to the type system; each formulation\nmaps a request to its own KKT rows or returns [`SensError::Unsupported`].\n\nThe dialects fold into one vocabulary: DC `Angle` is `Voltage(Angle)`, the conic\nsquared magnitude `w` is `Voltage(Squared)`, the nodal price is `Price(Active)`.",
"oneOf": [
{
"additionalProperties": false,
"description": "Nodal-balance dual (the LMP for active power, the reactive price for\nreactive), per bus.",
"properties": {
"Price": {
"$ref": "#/$defs/Power"
}
},
"required": [
"Price"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Generator dispatch `pg` / `qg`, per generator.",
"properties": {
"Dispatch": {
"$ref": "#/$defs/Power"
}
},
"required": [
"Dispatch"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Branch active/reactive flow at the from/to end, per branch.",
"properties": {
"Flow": {
"properties": {
"end": {
"$ref": "#/$defs/End"
},
"power": {
"$ref": "#/$defs/Power"
}
},
"required": [
"power",
"end"
],
"type": "object"
}
},
"required": [
"Flow"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Bus voltage in the formulation's representation (`vm` / `va` / `w` / `wr` /\n`wi`), per bus.",
"properties": {
"Voltage": {
"$ref": "#/$defs/VoltageKind"
}
},
"required": [
"Voltage"
],
"type": "object"
}
]
},
"Power": {
"description": "Active or reactive power. The orthogonal P/Q sub-axis shared by prices,\ndispatch, flows, and demand.",
"enum": [
"Active",
"Reactive"
],
"type": "string"
},
"End": {
"description": "Which end of a branch a flow is measured at.",
"enum": [
"From",
"To"
],
"type": "string"
},
"VoltageKind": {
"description": "How a voltage operand is represented: polar (`Magnitude`, `Angle`) for the AC\npower flow, or the W-space lift (`Squared` = `|V|²`, `ProductReal` = `Re(Vi Vj*)`,\n`ProductImag` = `Im(Vi Vj*)`) for the conic relaxation.",
"enum": [
"Magnitude",
"Angle",
"Squared",
"ProductReal",
"ProductImag"
],
"type": "string"
},
"ObservableWeight": {
"additionalProperties": false,
"description": "A weighted observable in the units reported by the selected formulation.",
"properties": {
"element": {
"$ref": "#/$defs/ElementKey"
},
"weight": {
"format": "double",
"type": "number"
}
},
"required": [
"element",
"weight"
],
"type": "object"
},
"SolveResponse": {
"description": "The formulation-agnostic solve result. A superset: every block is optional, and\neach formulation fills what it produces. Powers are MW/MVAr, nodal values are\nin objective units per selected power unit, angles radians, `vm` per unit, and\n`w = |V|^2` per unit squared. Element ids\nare the original bus/branch/generator ids, so the frontend joins straight onto\nits case.",
"properties": {
"dispatch": {
"items": {
"$ref": "#/$defs/GenDispatch"
},
"type": [
"array",
"null"
]
},
"flows": {
"items": {
"$ref": "#/$defs/BranchFlow"
},
"type": [
"array",
"null"
]
},
"formulation": {
"$ref": "#/$defs/Problem",
"description": "The formulation that produced this, echoed for the client."
},
"injections": {
"description": "Nodal injections (acpf), MW/MVAr.",
"items": {
"$ref": "#/$defs/BusInjection"
},
"type": [
"array",
"null"
]
},
"iterations": {
"anyOf": [
{
"$ref": "#/$defs/Iterations"
},
{
"type": "null"
}
]
},
"lmp": {
"description": "Active nodal price when the solved OPF declares a network generator\ncost objective. Feasibility solves leave this absent.",
"items": {
"$ref": "#/$defs/BusScalar"
},
"type": [
"array",
"null"
]
},
"lmp_q": {
"description": "Reactive nodal price. Always `None` in this build; the field is retained for\nwire-format stability.",
"items": {
"$ref": "#/$defs/BusScalar"
},
"type": [
"array",
"null"
]
},
"objective": {
"format": "double",
"type": [
"number",
"null"
]
},
"sensitivities": {
"description": "One self-describing matrix per requested cell, in request order. Each carries\nits own row/column element ids and the served-unit label.",
"items": {
"$ref": "#/$defs/SensitivityMatrix"
},
"type": "array"
},
"status": {
"$ref": "#/$defs/SolveStatus"
},
"va": {
"description": "Voltage angle, radians (every path except socwr, which is W-space).",
"items": {
"$ref": "#/$defs/BusScalar"
},
"type": [
"array",
"null"
]
},
"vm": {
"description": "Voltage magnitude, per unit (ACPF or square root of SOCWR squared magnitude).",
"items": {
"$ref": "#/$defs/BusScalar"
},
"type": [
"array",
"null"
]
},
"w": {
"description": "Squared voltage magnitude `w = |V|^2`, per unit squared (socwr). The conic\nrelaxation does not guarantee a globally consistent set of voltage angles.",
"items": {
"$ref": "#/$defs/BusScalar"
},
"type": [
"array",
"null"
]
},
"wi": {
"items": {
"$ref": "#/$defs/BranchScalar"
},
"type": [
"array",
"null"
]
},
"wr": {
"description": "Real and imaginary oriented branch voltage products (SOCWR).",
"items": {
"$ref": "#/$defs/BranchScalar"
},
"type": [
"array",
"null"
]
}
},
"required": [
"formulation",
"status"
],
"type": "object"
},
"GenDispatch": {
"description": "Generator dispatch, keyed by original generator id. `qg` is `None` on the DC paths.",
"properties": {
"bus": {
"description": "Original bus identity, allowing exact aggregation of co-located dispatch.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"gen": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"pg": {
"format": "double",
"type": "number"
},
"qg": {
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"gen",
"pg"
],
"type": "object"
},
"BranchFlow": {
"description": "Branch flows, keyed by original branch id (plus the row uid when carried, as in\n[`BusScalar`]). `pf` (from-end active, MW) and `loading` (|S|/limit,\ndimensionless) are present on every formulation that has flows; the reactive\nand to-end legs are `None` on the DC paths.",
"properties": {
"branch": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"loading": {
"format": "double",
"type": "number"
},
"pf": {
"format": "double",
"type": "number"
},
"pt": {
"format": "double",
"type": [
"number",
"null"
]
},
"qf": {
"format": "double",
"type": [
"number",
"null"
]
},
"qt": {
"format": "double",
"type": [
"number",
"null"
]
},
"uid": {
"type": [
"string",
"null"
]
}
},
"required": [
"branch",
"pf",
"loading"
],
"type": "object"
},
"Problem": {
"description": "Which problem to solve. The convex/power flow solve paths, as the lowercase JSON\ntags `\"dcpf\"`/`\"dcopf\"`/`\"acpf\"`/`\"socwr\"`. A plain (not internally tagged) enum\nso a request that omits it defaults to [`DcOpf`](Problem::DcOpf), and `{}` is a\nvalid base-case DC OPF request.\n\nThe `\"acopf\"` tag (full nonlinear AC OPF) is retained for wire-format stability\nbut is not solved by this build: [`capabilities_json`] reports it unavailable and\nrequesting it returns a clean `Err`.",
"oneOf": [
{
"const": "dcpf",
"description": "DC power flow: angles and flows at the fixed generator setpoints. No prices,\nno dispatch, no sensitivity.",
"type": "string"
},
{
"const": "dcopf",
"description": "DC OPF: the LMP / dispatch / flow workhorse. Differentiable via the DC KKT.",
"type": "string"
},
{
"const": "acpf",
"description": "AC polar Newton power flow. Voltages and nodal injections. Differentiable\nvia the AC Newton system.",
"type": "string"
},
{
"const": "socwr",
"description": "SOCWR (Jabr) conic relaxation of AC OPF. Differentiable via the conic KKT.",
"type": "string"
},
{
"const": "acopf",
"description": "Full nonlinear AC OPF. Not available in this build (the dispatch errors\ncleanly); the tag is kept so the JSON format stays stable.",
"type": "string"
}
]
},
"BusInjection": {
"description": "A nodal net injection (MW / MVAr), keyed by original bus id (plus the row uid\nwhen carried, as in [`BusScalar`]). Injections describe the net nodal power balance.",
"properties": {
"bus": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"p": {
"format": "double",
"type": "number"
},
"q": {
"format": "double",
"type": "number"
},
"uid": {
"type": [
"string",
"null"
]
}
},
"required": [
"bus",
"p",
"q"
],
"type": "object"
},
"Iterations": {
"anyOf": [
{
"description": "Interior-point iterate trace (dcopf / socwr).",
"items": {
"$ref": "#/$defs/SolveIteration"
},
"type": "array"
},
{
"description": "Newton iteration count and final infinity-norm mismatch (acpf).",
"properties": {
"count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"residual": {
"format": "double",
"type": "number"
}
},
"required": [
"count",
"residual"
],
"type": "object"
}
],
"description": "The convergence record. OPF paths carry the full interior-point trace (for the\nsolve-card sparkline); the AC power flow carries its Newton count and final\nmismatch. Untagged: the OPF arm serializes to the same bare array the DC OPF\nalways returned."
},
"SolveIteration": {
"description": "One interior-point iterate: the iteration index, the primal objective, and\nthe primal and dual residuals. Collected once per Clarabel iteration to draw\nthe convergence plot. Shape matches the frontend `SolveIteration`.",
"properties": {
"inf_du": {
"format": "double",
"type": "number"
},
"inf_pr": {
"format": "double",
"type": "number"
},
"iter": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"objective": {
"format": "double",
"type": "number"
}
},
"required": [
"iter",
"objective",
"inf_pr",
"inf_du"
],
"type": "object"
},
"BusScalar": {
"description": "A scalar keyed by original bus id (LMP, voltage, angle, squared magnitude).\n`uid` is the bus's powerio row uid when the solved network carried one, so an\noverlay can re-key on stable identity instead of the positional id.",
"properties": {
"bus": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"uid": {
"type": [
"string",
"null"
]
},
"value": {
"format": "double",
"type": "number"
}
},
"required": [
"bus",
"value"
],
"type": "object"
},
"SensitivityMatrix": {
"description": "A self-describing sensitivity result: `values[r][c] = d(rows[r])/d(cols[c])`,\nwith row and column metadata naming each quantity and its source element, and the\nserved-unit label.",
"properties": {
"cols": {
"items": {
"$ref": "#/$defs/ColMeta"
},
"type": "array"
},
"rows": {
"items": {
"$ref": "#/$defs/RowMeta"
},
"type": "array"
},
"units": {
"type": "string"
},
"values": {
"description": "`values[r][c] = d(operand_r)/d(parameter_c)`, in the units named by `units`. The\nengine produces per-unit values; the api edge rescales to served units.",
"items": {
"items": {
"format": "double",
"type": "number"
},
"type": "array"
},
"type": "array"
}
},
"required": [
"values",
"rows",
"cols",
"units"
],
"type": "object"
},
"ColMeta": {
"description": "Identity and quantity metadata for one column of a [`SensitivityMatrix`].",
"properties": {
"element": {
"$ref": "#/$defs/ElementId"
},
"index": {
"description": "Dense index of the element this column varies.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"parameter": {
"$ref": "#/$defs/Parameter"
}
},
"required": [
"parameter",
"element",
"index"
],
"type": "object"
},
"ElementId": {
"description": "A source-id reference for a dense row or column, so a [`SensitivityMatrix`]\nself-describes and the api serializes it without re-deriving id maps.",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"Bus": {
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"Bus"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"Branch": {
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"Branch"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"Generator": {
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"Generator"
],
"type": "object"
}
]
},
"Parameter": {
"description": "What a sensitivity is taken *with respect to* — the parameter whose hand-derived\n`dK/dp` column drives the solve.",
"oneOf": [
{
"additionalProperties": false,
"description": "Bus active/reactive demand `pd` / `qd`, per bus.",
"properties": {
"Demand": {
"$ref": "#/$defs/Power"
}
},
"required": [
"Demand"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Generation cost coefficient, per generator.",
"properties": {
"Cost": {
"$ref": "#/$defs/CostTerm"
}
},
"required": [
"Cost"
],
"type": "object"
},
{
"const": "LineLimit",
"description": "DC thermal limit `fmax` / AC-conic apparent-power `|S|` limit, per branch.",
"type": "string"
},
{
"additionalProperties": false,
"description": "Branch series admittance `g` / `b`, per branch.",
"properties": {
"SeriesAdmittance": {
"$ref": "#/$defs/GB"
}
},
"required": [
"SeriesAdmittance"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Bus shunt admittance `gs` / `bs`, per bus.",
"properties": {
"ShuntAdmittance": {
"$ref": "#/$defs/GB"
}
},
"required": [
"ShuntAdmittance"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Voltage-magnitude bound right-hand side (the `w = |V|²` bound), per bus.",
"properties": {
"VoltageBound": {
"$ref": "#/$defs/Bound"
}
},
"required": [
"VoltageBound"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Generator output bound right-hand side (`pmax` / `pmin` / `qmax` / `qmin`),\nper generator.",
"properties": {
"GenBound": {
"properties": {
"bound": {
"$ref": "#/$defs/Bound"
},
"power": {
"$ref": "#/$defs/Power"
}
},
"required": [
"power",
"bound"
],
"type": "object"
}
},
"required": [
"GenBound"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Transformer tap ratio / phase shift, per branch.",
"properties": {
"Transformer": {
"$ref": "#/$defs/TapKind"
}
},
"required": [
"Transformer"
],
"type": "object"
},
{
"const": "Switching",
"description": "Branch switching state `sw` in `[0, 1]`, per branch.",
"type": "string"
}
]
},
"CostTerm": {
"description": "Which generation-cost coefficient: the quadratic `cq` or the linear `cl`.",
"enum": [
"Quadratic",
"Linear"
],
"type": "string"
},
"GB": {
"description": "Conductance `g` or susceptance `b`, the real/imaginary parts of an admittance.",
"enum": [
"Conductance",
"Susceptance"
],
"type": "string"
},
"Bound": {
"description": "A min or max bound, e.g. the lower/upper voltage-magnitude limit.",
"enum": [
"Min",
"Max"
],
"type": "string"
},
"TapKind": {
"description": "A transformer control: the tap ratio or the phase-shift angle.",
"enum": [
"Ratio",
"PhaseShift"
],
"type": "string"
},
"RowMeta": {
"description": "Identity and quantity metadata for one row of a [`SensitivityMatrix`].",
"properties": {
"element": {
"$ref": "#/$defs/ElementId"
},
"index": {
"description": "Dense index of the element this row reports.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"operand": {
"$ref": "#/$defs/Operand"
}
},
"required": [
"operand",
"element",
"index"
],
"type": "object"
},
"SolveStatus": {
"description": "A solve outcome that succeeded. A failed solve is the `Err` arm of a solve entry.",
"oneOf": [
{
"const": "optimal",
"description": "An OPF reached optimality.",
"type": "string"
},
{
"const": "feasible",
"description": "A power flow converged to a feasible point.",
"type": "string"
}
]
},
"BranchScalar": {
"description": "A branch-indexed voltage product, in squared per unit.",
"properties": {
"branch": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"value": {
"format": "double",
"type": "number"
}
},
"required": [
"branch",
"value"
],
"type": "object"
}
}
},
"page": "/"
}inspect_studyAction
Inspect the open Study, read a bounded page of goals, states or evidence, or open a saved Study. Saved candidates remain unapplied.
View tool JSON
{
"name": "inspect_study",
"kind": "act",
"impl": "imperative",
"description": "Inspect the open Study, read a bounded page of goals, states or evidence, or open a saved Study. Saved candidates remain unapplied.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Open this saved Study if it is not currently open."
},
"section": {
"enum": [
"summary",
"goal",
"states",
"experiment",
"evidence"
]
},
"record_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"offset": {
"type": "integer",
"minimum": 0
},
"expected_revision": {
"type": "integer",
"minimum": 0
}
},
"required": [],
"additionalProperties": false
},
"page": "/"
}revise_study_goalAction
Save a new goal revision without changing historical goals. The revision invalidates the current recommendation and approvals.
View tool JSON
{
"name": "revise_study_goal",
"kind": "act",
"impl": "imperative",
"description": "Save a new goal revision without changing historical goals. The revision invalidates the current recommendation and approvals.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"goal": {
"$ref": "#/$defs/GoalRevision"
},
"kind": {
"const": "revise_goal",
"type": "string"
}
},
"required": [
"kind",
"goal"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {
"GoalRevision": {
"additionalProperties": false,
"description": "A goal revision retains its own anchor and interpretation.",
"properties": {
"anchor_state": {
"type": "string"
},
"decisions": {
"$ref": "#/$defs/DecisionSpace"
},
"interpretation": {
"type": "string"
},
"objective": {
"$ref": "#/$defs/StudyObjective"
},
"parent": {
"type": [
"string",
"null"
]
},
"request": {
"type": "string"
},
"success_value": {
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"anchor_state",
"request",
"interpretation",
"objective",
"decisions"
],
"type": "object"
},
"DecisionSpace": {
"additionalProperties": false,
"description": "The feasible set, distinct from both the inner problem and the outer goal.",
"properties": {
"demand": {
"anyOf": [
{
"$ref": "#/$defs/DemandConstraint"
},
{
"type": "null"
}
]
},
"max_changed_elements": {
"format": "uint",
"maximum": 65536,
"minimum": 1,
"type": "integer"
},
"total_budget": {
"format": "double",
"minimum": 0,
"type": "number"
},
"variables": {
"items": {
"$ref": "#/$defs/DecisionVariable"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
}
},
"required": [
"variables",
"total_budget",
"max_changed_elements"
],
"type": "object"
},
"DemandConstraint": {
"oneOf": [
{
"additionalProperties": false,
"description": "Allocate this additional MW across the declared demand decisions.",
"properties": {
"increase_mw": {
"format": "double",
"type": "number"
},
"kind": {
"const": "placement",
"type": "string"
}
},
"required": [
"kind",
"increase_mw"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Preserve the existing total MW across the declared demand decisions.",
"properties": {
"kind": {
"const": "redistribution",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
}
]
},
"DecisionVariable": {
"additionalProperties": false,
"description": "Bounds and increments apply to changes from the goal's anchor state in a Study.",
"properties": {
"budget_weight": {
"description": "Budget consumption per absolute unit of intervention.",
"format": "double",
"type": "number"
},
"element": {
"$ref": "#/$defs/ElementKey"
},
"id": {
"maxLength": 128,
"minLength": 1,
"type": "string"
},
"increment": {
"format": "double",
"type": "number"
},
"intervention": {
"$ref": "#/$defs/Intervention"
},
"lower": {
"format": "double",
"type": "number"
},
"upper": {
"format": "double",
"type": "number"
}
},
"required": [
"id",
"element",
"intervention",
"lower",
"upper",
"increment",
"budget_weight"
],
"type": "object"
},
"ElementKey": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"Intervention": {
"description": "A numerical intervention supported by the existing solvers.",
"enum": [
"branch_rating",
"active_demand"
],
"type": "string"
},
"StudyObjective": {
"description": "A scalar goal over the exact operating point and explicit interventions.",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "weighted_observable",
"type": "string"
},
"operand": {
"$ref": "#/$defs/Operand"
},
"weights": {
"items": {
"$ref": "#/$defs/ObservableWeight"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
}
},
"required": [
"kind",
"operand",
"weights"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "sum",
"type": "string"
},
"terms": {
"items": {
"$ref": "#/$defs/StudyObjective"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
}
},
"required": [
"kind",
"terms"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"expression": {
"$ref": "#/$defs/StudyObjective"
},
"factor": {
"format": "double",
"type": "number"
},
"kind": {
"const": "scale",
"type": "string"
}
},
"required": [
"kind",
"factor",
"expression"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"expression": {
"$ref": "#/$defs/StudyObjective"
},
"kind": {
"const": "squared_target",
"type": "string"
},
"target": {
"format": "double",
"type": "number"
}
},
"required": [
"kind",
"target",
"expression"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"decision": {
"type": "string"
},
"kind": {
"const": "intervention_penalty",
"type": "string"
},
"linear": {
"format": "double",
"type": "number"
},
"quadratic": {
"format": "double",
"type": "number"
}
},
"required": [
"kind",
"decision",
"linear",
"quadratic"
],
"type": "object"
}
]
},
"Operand": {
"description": "What a sensitivity is taken *of*, named for the physical power quantity rather\nthan a formulation's internal variable. The orthogonal sub-axes (active/reactive,\nfrom/to, voltage representation) are visible to the type system; each formulation\nmaps a request to its own KKT rows or returns [`SensError::Unsupported`].\n\nThe dialects fold into one vocabulary: DC `Angle` is `Voltage(Angle)`, the conic\nsquared magnitude `w` is `Voltage(Squared)`, the nodal price is `Price(Active)`.",
"oneOf": [
{
"additionalProperties": false,
"description": "Nodal-balance dual (the LMP for active power, the reactive price for\nreactive), per bus.",
"properties": {
"Price": {
"$ref": "#/$defs/Power"
}
},
"required": [
"Price"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Generator dispatch `pg` / `qg`, per generator.",
"properties": {
"Dispatch": {
"$ref": "#/$defs/Power"
}
},
"required": [
"Dispatch"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Branch active/reactive flow at the from/to end, per branch.",
"properties": {
"Flow": {
"properties": {
"end": {
"$ref": "#/$defs/End"
},
"power": {
"$ref": "#/$defs/Power"
}
},
"required": [
"power",
"end"
],
"type": "object"
}
},
"required": [
"Flow"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Bus voltage in the formulation's representation (`vm` / `va` / `w` / `wr` /\n`wi`), per bus.",
"properties": {
"Voltage": {
"$ref": "#/$defs/VoltageKind"
}
},
"required": [
"Voltage"
],
"type": "object"
}
]
},
"Power": {
"description": "Active or reactive power. The orthogonal P/Q sub-axis shared by prices,\ndispatch, flows, and demand.",
"enum": [
"Active",
"Reactive"
],
"type": "string"
},
"End": {
"description": "Which end of a branch a flow is measured at.",
"enum": [
"From",
"To"
],
"type": "string"
},
"VoltageKind": {
"description": "How a voltage operand is represented: polar (`Magnitude`, `Angle`) for the AC\npower flow, or the W-space lift (`Squared` = `|V|²`, `ProductReal` = `Re(Vi Vj*)`,\n`ProductImag` = `Im(Vi Vj*)`) for the conic relaxation.",
"enum": [
"Magnitude",
"Angle",
"Squared",
"ProductReal",
"ProductImag"
],
"type": "string"
},
"ObservableWeight": {
"additionalProperties": false,
"description": "A weighted observable in the units reported by the selected formulation.",
"properties": {
"element": {
"$ref": "#/$defs/ElementKey"
},
"weight": {
"format": "double",
"type": "number"
}
},
"required": [
"element",
"weight"
],
"type": "object"
}
}
},
"page": "/"
}branch_studyAction
Inspect a saved state and continue exploration from it. This changes the inspected pointer, not the applied state.
View tool JSON
{
"name": "branch_study",
"kind": "act",
"impl": "imperative",
"description": "Inspect a saved state and continue exploration from it. This changes the inspected pointer, not the applied state.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"kind": {
"const": "branch",
"type": "string"
},
"rationale": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"kind",
"state",
"rationale"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {}
},
"page": "/"
}compare_study_statesAction
Compare two saved network states, optionally under a selected goal revision. Results include operating-point changes and goal progress when a goal is selected.
View tool JSON
{
"name": "compare_study_states",
"kind": "act",
"impl": "imperative",
"description": "Compare two saved network states, optionally under a selected goal revision. Results include operating-point changes and goal progress when a goal is selected.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"goal": {
"type": [
"string",
"null"
]
},
"kind": {
"const": "compare",
"type": "string"
},
"left": {
"type": "string"
},
"right": {
"type": "string"
}
},
"required": [
"kind",
"left",
"right"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {}
},
"page": "/"
}propose_studyAction
Explore feasible capacity or demand interventions using implicit gradients and exact solves. Every trial counts against the solve budget. Save the best verified recommendation without applying it. The user applies it in the Study panel.
View tool JSON
{
"name": "propose_study",
"kind": "act",
"impl": "imperative",
"description": "Explore feasible capacity or demand interventions using implicit gradients and exact solves. Every trial counts against the solve budget. Save the best verified recommendation without applying it. The user applies it in the Study panel.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"goal": {
"type": "string"
},
"kind": {
"const": "propose",
"type": "string"
},
"options": {
"$ref": "#/$defs/SearchOptions"
},
"rationale": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"kind",
"state",
"goal",
"options",
"rationale"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {
"SearchOptions": {
"additionalProperties": false,
"properties": {
"beam_width": {
"format": "uint",
"maximum": 32,
"minimum": 1,
"type": "integer"
},
"max_iterations": {
"format": "uint",
"maximum": 256,
"minimum": 0,
"type": "integer"
},
"max_solves": {
"format": "uint",
"maximum": 256,
"minimum": 0,
"type": "integer"
},
"min_improvement": {
"format": "double",
"minimum": 0,
"type": "number"
}
},
"required": [
"max_solves",
"beam_width",
"max_iterations",
"min_improvement"
],
"type": "object"
}
}
},
"page": "/"
}edit_demandAction
Add signed MW increments at permitted buses to the selected saved state. Edits accumulate across calls and persist after reload. Individual bounds and the total change budget apply to every step; incomplete demand totals stay unapplied. Read the resulting state's evidence for the cumulative demand vector.
View tool JSON
{
"name": "edit_demand",
"kind": "act",
"impl": "imperative",
"description": "Add signed MW increments at permitted buses to the selected saved state. Edits accumulate across calls and persist after reload. Individual bounds and the total change budget apply to every step; incomplete demand totals stay unapplied. Read the resulting state's evidence for the cumulative demand vector.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"changes": {
"items": {
"$ref": "#/$defs/DemandAdjustment"
},
"maxItems": 65536,
"minItems": 1,
"type": "array"
},
"constrain_to_goal": {
"default": true,
"type": "boolean"
},
"goal": {
"type": [
"string",
"null"
]
},
"kind": {
"const": "edit_demand",
"type": "string"
},
"rationale": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"kind",
"state",
"changes",
"rationale"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {
"DemandAdjustment": {
"additionalProperties": false,
"properties": {
"bus": {
"$ref": "#/$defs/ElementKey"
},
"delta_mw": {
"description": "Signed increment to the selected state's demand, in MW.",
"format": "double",
"type": "number"
}
},
"required": [
"bus",
"delta_mw"
],
"type": "object"
},
"ElementKey": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
}
}
},
"page": "/"
}restore_base_caseAction
Exactly solve the retained original network data and save a reset candidate without applying it or deleting history. The user can apply the reset in the Study panel. Reports when the original input is unavailable.
View tool JSON
{
"name": "restore_base_case",
"kind": "act",
"impl": "imperative",
"description": "Exactly solve the retained original network data and save a reset candidate without applying it or deleting history. The user can apply the reset in the Study panel. Reports when the original input is unavailable.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"goal": {
"type": [
"string",
"null"
]
},
"kind": {
"const": "restore_base",
"type": "string"
},
"rationale": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"kind",
"state",
"rationale"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {}
},
"page": "/"
}record_study_evidenceAction
Attach a stated rationale and evidence to a saved state without creating an electrical state. Do not record private agent reasoning.
View tool JSON
{
"name": "record_study_evidence",
"kind": "act",
"impl": "imperative",
"description": "Attach a stated rationale and evidence to a saved state without creating an electrical state. Do not record private agent reasoning.",
"inputSchema": {
"type": "object",
"properties": {
"study_id": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"operation": {
"additionalProperties": false,
"properties": {
"assessed_recommendation": {
"type": [
"string",
"null"
]
},
"evidence": true,
"goal": {
"type": [
"string",
"null"
]
},
"kind": {
"const": "record_evidence",
"type": "string"
},
"rationale": {
"type": "string"
},
"sensitivity": {
"type": "boolean"
},
"state": {
"type": "string"
}
},
"required": [
"kind",
"state",
"sensitivity",
"rationale",
"evidence"
],
"type": "object"
}
},
"required": [
"study_id",
"expected_revision",
"operation"
],
"additionalProperties": false,
"$defs": {}
},
"page": "/"
}propose_capacity_planAction
Use implicit derivatives to choose bounded branch capacity increase trials. Exact solves verify the staged proposal. The electrical case stays unchanged.
View tool JSON
{
"name": "propose_capacity_plan",
"kind": "act",
"impl": "imperative",
"description": "Use implicit derivatives to choose bounded branch capacity increase trials. Exact solves verify the staged proposal. The electrical case stays unchanged.",
"inputSchema": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"description": "Active case ID from inspect_case."
},
"expected_revision": {
"type": "string",
"description": "Current revision from inspect_case; a stale revision refuses the run."
},
"objective": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"weighted_lmp"
],
"description": "Implicit objective kind."
},
"weights": {
"type": "array",
"minItems": 1,
"maxItems": 16,
"description": "Weighted LMP terms defining the minimized objective.",
"items": {
"type": "object",
"properties": {
"bus_id": {
"type": "string",
"description": "Stable bus ID from query_network."
},
"weight": {
"type": "number",
"description": "Coefficient applied to this bus LMP."
}
},
"required": [
"bus_id",
"weight"
],
"additionalProperties": false
}
}
},
"required": [
"kind",
"weights"
],
"additionalProperties": false,
"description": "Objective evaluated at each exact OPF solution."
},
"candidates": {
"type": "array",
"minItems": 1,
"maxItems": 12,
"items": {
"type": "string"
},
"description": "Candidate branches whose capacities may increase."
},
"max_increase_per_branch_mw": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Largest proposed increase for one branch, MW."
},
"budget_mw": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Maximum sum of proposed capacity increases, MW."
},
"increment_mw": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Capacity increment used to construct trials, MW."
},
"max_changed_lines": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Maximum branches changed in the final proposal."
},
"exact_solve_budget": {
"type": "integer",
"minimum": 2,
"maximum": 32,
"description": "Solve budget, including the starting point and all trials."
}
},
"required": [
"case_id",
"expected_revision",
"objective",
"candidates",
"max_increase_per_branch_mw",
"budget_mw",
"increment_mw",
"max_changed_lines",
"exact_solve_budget"
],
"additionalProperties": false
},
"page": "/"
}