Tool registry

The JSON-schema tool registry that exposes the differentiable engine to a language model: each ToolSpec wraps an engine call with a validated schema, so the model can size, cost, flash, and optimize without touching Python. The tools are plain Python (floats and lists, not JAX arrays), so they serialize cleanly into a function-calling loop.

tools

A tool registry exposing the Fugacio engine to an LLM design agent.

The copilot layer turns natural-language design goals into engineering calculations. The bridge between a language model and the differentiable engine is a set of tools: deterministic, JSON-in/JSON-out functions with machine- readable schemas (the same shape OpenAI / Anthropic function-calling expects).

This module defines that registry over fugacio.sim and fugacio.thermo. The tools are plain Python (floats and lists, not JAX arrays) so they are trivial to serialise; the LLM-planning loop that selects and sequences them lives behind the optional llm extra (fugacio.copilot.agent).

Classes:

Name	Description
ToolSpec	A callable tool with an LLM-facing JSON schema.

Functions:

Name	Description
default_registry	Return the built-in tool registry keyed by tool name.
tool_schemas	Return the function-calling schemas for every tool in the registry.
call_tool	Dispatch a tool call by name with a JSON argument dict.

ToolSpec dataclass

ToolSpec(
    name: str,
    description: str,
    parameters: JsonDict,
    run: Callable[..., JsonDict],
)

A callable tool with an LLM-facing JSON schema.

Attributes:

Name	Type	Description
name	str	Unique tool name.
description	str	One-line description for the planner.
parameters	JsonDict	JSON-schema object describing the arguments.
run	Callable[..., JsonDict]	The implementation, taking keyword arguments and returning a dict.

default_registry

default_registry() -> dict[str, ToolSpec]

Return the built-in tool registry keyed by tool name.

tool_schemas

tool_schemas(
    registry: dict[str, ToolSpec] | None = None,
) -> list[JsonDict]

Return the function-calling schemas for every tool in the registry.

call_tool

call_tool(
    name: str,
    arguments: JsonDict,
    registry: dict[str, ToolSpec] | None = None,
) -> JsonDict

Dispatch a tool call by name with a JSON argument dict.

Raises:

Type	Description
KeyError	if name is not a registered tool.

Domain tool packs

The default registry is assembled from the core tools plus three domain packs. Each factory returns the ToolSpec list for its area.

dynamics_tools

Copilot tools for the time-domain dynamics & control layer.

These expose fugacio.sim.control and fugacio.sim.dynamics to the LLM design agent as deterministic, JSON-in/JSON-out calculations: identify a first- order-plus-dead-time (FOPDT) model from step data, turn it into PID gains by a named tuning rule, simulate the resulting closed loop, and compare tuning rules on their closed-loop performance. They are kept in their own module (rather than the already-large fugacio.copilot.tools) and folded into the registry there.

The closed-loop simulator integrates the FOPDT plant with an explicit fixed step and represents the transport delay as an integer-sample shift buffer carried through a jax.lax.scan, so dead time is handled honestly rather than by a Pade approximation. The controller is the library PID marched with the same step, so the numbers match what the engine would produce.

Functions:

Name	Description
dynamics_tool_specs	ToolSpecs for the dynamics & control layer (folded into default_registry).

dynamics_tool_specs

dynamics_tool_specs() -> list[Any]

ToolSpecs for the dynamics & control layer (folded into default_registry).

integration_tools

Copilot tools for the heat-integration / pinch-analysis layer.

These expose fugacio.sim.integration to the LLM design agent as deterministic, JSON-in/JSON-out calculations: compute the minimum-utility and pinch targets for a set of process streams, return the composite / grand composite curves, find the cost-optimal minimum approach temperature, and synthesise a heat-exchanger network by the pinch design method. They are kept in their own module (rather than the already-large fugacio.copilot.tools) and folded into the registry there.

A stream is supplied as {"t_supply", "t_target"} plus either a heat-capacity flowrate "cp" (W/K) or a "duty" (W), and an optional film coefficient "h"; everything else follows from the differentiable targets.

Functions:

Name	Description
integration_tool_specs	ToolSpecs for the heat-integration layer (folded into default_registry).

integration_tool_specs

integration_tool_specs() -> list[Any]

ToolSpecs for the heat-integration layer (folded into default_registry).

mpc_tools

Copilot tools for advanced process control (MPC + state estimation).

These expose fugacio.sim.mpc to the LLM design agent as deterministic, JSON-in/JSON-out calculations over a linear state-space plant x+ = A x + B u, y = C x:

• lqr_design: the infinite-horizon LQR gain and closed-loop poles for given state/input weights (discrete or continuous);
• kalman_design: the steady-state Kalman filter gain, error covariance and estimator poles for given process/measurement noise;
• simulate_mpc: run a constrained, offset-free linear MPC in closed loop against a setpoint (optionally with a constant output disturbance) and report the response/input trajectories and step metrics;
• tune_mpc_weights: descend the closed-loop tracking cost on the MPC weights themselves, exploiting the differentiability of the controller's own QP.

Matrices are passed as nested lists; weights may be a scalar, a per-channel list (diagonal), or a full matrix. Everything returned is plain Python (floats / lists) so it serialises trivially for function calling.

Functions:

Name	Description
mpc_tool_specs	ToolSpecs for the advanced-control layer (folded into default_registry).

mpc_tool_specs

mpc_tool_specs() -> list[Any]

ToolSpecs for the advanced-control layer (folded into default_registry).