fugacio-copilot

Chemical-engineering design copilot/agent for the Fugacio stack. It sits on top of fugacio.sim and turns natural-language design goals into engineering calculations: flowsheets, equipment sizing, and (eventually) techno-economic / life-cycle analysis.

The bridge between a language model and the differentiable engine is a tool registry, deterministic, JSON-in/JSON-out functions exposed with the same function-calling schemas OpenAI/Anthropic expect:

• Properties & equilibrium: list_components, component_properties, saturation_pressure, bubble_pressure, flash_drum. The flash, the heater, the columns, and the exchanger accept a method (pr, srk, nrtl, unifac, pcsaft, iapws, ...) that selects the property package.
• Molecular PC-SAFT: saft_flash, saft_density, saft_saturation_pressure, saft_bubble_pressure, and saft_residual_enthalpy, the molecular EOS preferred for associating fluids (water, alcohols).
• Unit operations: heat_exchanger (one-sided heater/cooler), two_sided_heat_exchanger (hot and cold streams, rigorous T-Q curves, one closing spec), compressor (and turbine), pump, valve, each closing a rigorous energy balance.
• Distillation: shortcut_distillation (Fenske-Underwood-Gilliland), rigorous_distillation (simultaneous-correction MESH column with stage energy balances, profiles, and duties), and absorber.
• Gradient-based optimization: optimize_flash_temperature differentiates straight through the equilibrium flash; optimize_column_reflux imposes the purity as a specification of the MESH column and reports the reflux it takes.

A model-agnostic agent loop (run_agent) drives plan→act→answer; the planner is injected, so the loop is fully testable with a scripted planner while a real LLM drops in behind the optional llm extra.

from fugacio.copilot import call_tool, run_agent, tool_schemas

# Call an engine-backed tool directly (JSON in / JSON out):
call_tool("saturation_pressure", {"component": "propane", "temperature": 300.0})

# Or drive the agent loop with your own planner (an LLM in production):
def planner(goal, tools, transcript):
    if not transcript:
        return {"tool": "flash_drum", "arguments": {
            "components": ["methane", "propane", "n-pentane"],
            "z": [0.5, 0.3, 0.2], "flow": 100.0,
            "temperature": 320.0, "pressure": 20e5,
        }}
    vf = transcript[-1]["result"]["vapor_fraction"]
    return {"final_answer": f"vapor fraction = {vf:.3f}"}

run_agent("Flash this feed", planner).answer  # 'vapor fraction = 0.747'

tool_schemas() returns the schemas to hand an LLM. LLM-backed planning lives behind the optional llm extra:

pip install "fugacio-copilot[llm]"

run_llm_agent drives a real model through the same registry with a provider from fugacio.copilot.llm: AnthropicProvider (Claude Opus 5, claude-opus-5, by default), OpenAIProvider (gpt-5-mini by default), or the deterministic MockProvider for tests. The providers send a sampling temperature only when you pass one and cap each reply at 16,000 tokens by default. A failed tool call returns to the model as an error it can correct; a refused reply, or one cut off at the token cap, ends the run with that stop_reason rather than an answer. Engine tools raise on a failed or out-of-domain solve, so the model never receives an unconverged number.

from fugacio.copilot import run_llm_agent
from fugacio.copilot.llm import AnthropicProvider

result = run_llm_agent("Flash this feed at 320 K and 20 bar.", AnthropicProvider())
result.answer, result.stop_reason

Part of the fugacio namespace; installs independently: pip install fugacio-copilot.