fugacio-copilot 0.0.1__tar.gz

fugacio_copilot-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled / build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+.jax_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+# Material social-cards plugin cache (downloaded fonts + generated card layers)
+.cache/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

fugacio_copilot-0.0.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: fugacio-copilot
+Version: 0.0.1
+Summary: Chemical-engineering design copilot/agent for the Fugacio stack.
+Author-email: Owen Carey <37121709+owenthcarey@users.noreply.github.com>
+License-Expression: Apache-2.0
+Keywords: agent,chemical-engineering,copilot,llm,process-design
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: fugacio-sim
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.34; extra == 'anthropic'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.34; extra == 'llm'
+Requires-Dist: openai>=1.40; extra == 'llm'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# fugacio-copilot
+
+Chemical-engineering design copilot/agent for the
+[Fugacio](https://github.com/fugacio/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`.
+- **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`, `compressor` (and turbine), `pump`,
+  `valve`, each closing a rigorous energy balance.
+- **Distillation**: `shortcut_distillation` (Fenske-Underwood-Gilliland) and
+  `rigorous_distillation` (multistage column with duties).
+- **Gradient-based optimization**: `optimize_flash_temperature` and
+  `optimize_column_reflux` solve for the operating variable that hits a target by
+  differentiating straight through the equilibrium flash and the column.
+
+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.
+
+```python
+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:
+
+```bash
+pip install "fugacio-copilot[llm]"
+```
+
+Part of the `fugacio` namespace; installs independently:
+`pip install fugacio-copilot`.

fugacio_copilot-0.0.1/README.md

@@ -0,0 +1,58 @@
+# fugacio-copilot
+
+Chemical-engineering design copilot/agent for the
+[Fugacio](https://github.com/fugacio/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`.
+- **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`, `compressor` (and turbine), `pump`,
+  `valve`, each closing a rigorous energy balance.
+- **Distillation**: `shortcut_distillation` (Fenske-Underwood-Gilliland) and
+  `rigorous_distillation` (multistage column with duties).
+- **Gradient-based optimization**: `optimize_flash_temperature` and
+  `optimize_column_reflux` solve for the operating variable that hits a target by
+  differentiating straight through the equilibrium flash and the column.
+
+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.
+
+```python
+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:
+
+```bash
+pip install "fugacio-copilot[llm]"
+```
+
+Part of the `fugacio` namespace; installs independently:
+`pip install fugacio-copilot`.

fugacio_copilot-0.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "fugacio-copilot"
+version = "0.0.1"
+description = "Chemical-engineering design copilot/agent for the Fugacio stack."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+    { name = "Owen Carey", email = "37121709+owenthcarey@users.noreply.github.com" },
+]
+keywords = [
+    "llm",
+    "agent",
+    "chemical-engineering",
+    "process-design",
+    "copilot",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+dependencies = [
+    "fugacio-sim",
+]
+
+[project.optional-dependencies]
+# LLM provider SDKs. The copilot core works without these (e.g. via the mock
+# provider); install the relevant extra to talk to a real model.
+openai = ["openai>=1.40"]
+anthropic = ["anthropic>=0.34"]
+llm = ["openai>=1.40", "anthropic>=0.34"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fugacio"]
+
+[tool.uv.sources]
+fugacio-sim = { workspace = true }

fugacio_copilot-0.0.1/src/fugacio/copilot/__init__.py

@@ -0,0 +1,86 @@
+"""Chemical-engineering design copilot for Fugacio (depends on ``fugacio.sim``).
+
+The copilot exposes the differentiable engine to a language-model design agent
+through:
+
+* a **tool registry** (`default_registry`, `tool_schemas`,
+  `call_tool`) of deterministic, JSON-in/JSON-out engineering calculations
+  spanning properties, unit operations, distillation, reactors, optimization,
+  design specs, and economics;
+* a vendor-neutral **LLM provider layer** (`OpenAIProvider`,
+  `AnthropicProvider`, and the test `MockProvider`) behind the
+  optional ``llm`` extra;
+* a model-agnostic **agent loop** (`run_agent`) plus a real multi-turn
+  function-calling loop (`run_llm_agent`), with planner adapters
+  (`llm_planner`, `heuristic_planner`);
+* human-readable **reports** (`summarize_bubble_point`, and the richer
+  markdown summaries in `fugacio.copilot.report`).
+"""
+
+from fugacio.copilot.agent import (
+    DEFAULT_SYSTEM_PROMPT,
+    AgentResult,
+    Planner,
+    heuristic_planner,
+    llm_planner,
+    run_agent,
+    run_llm_agent,
+)
+from fugacio.copilot.llm import (
+    AnthropicProvider,
+    ChatResponse,
+    LLMProvider,
+    Message,
+    MockProvider,
+    OpenAIProvider,
+    ToolCall,
+)
+from fugacio.copilot.report import (
+    stream_table,
+    summarize_bubble_point,
+    summarize_economics,
+    summarize_heat_integration,
+    summarize_lqr_design,
+    summarize_mpc_simulation,
+    summarize_optimization,
+    summarize_pid_tuning,
+    summarize_transcript,
+)
+from fugacio.copilot.tools import (
+    ToolSpec,
+    call_tool,
+    default_registry,
+    tool_schemas,
+)
+
+__all__ = [
+    "DEFAULT_SYSTEM_PROMPT",
+    "AgentResult",
+    "AnthropicProvider",
+    "ChatResponse",
+    "LLMProvider",
+    "Message",
+    "MockProvider",
+    "OpenAIProvider",
+    "Planner",
+    "ToolCall",
+    "ToolSpec",
+    "call_tool",
+    "default_registry",
+    "heuristic_planner",
+    "llm_planner",
+    "run_agent",
+    "run_llm_agent",
+    "stream_table",
+    "summarize_bubble_point",
+    "summarize_economics",
+    "summarize_heat_integration",
+    "summarize_lqr_design",
+    "summarize_mpc_simulation",
+    "summarize_optimization",
+    "summarize_pid_tuning",
+    "summarize_transcript",
+    "tool_schemas",
+]
+
+__version__ = "0.0.1"

fugacio_copilot-0.0.1/src/fugacio/copilot/agent.py

@@ -0,0 +1,248 @@
+"""Tool-calling agent loops for the Fugacio design copilot.
+
+Two complementary loops share one tool registry:
+
+* `run_agent`: the original *model-agnostic* loop. A **planner** callable
+  ``(goal, tool_schemas, transcript) -> decision`` decides the next tool call or
+  the final answer, where ``decision`` is ``{"tool": name, "arguments": {...}}``
+  or ``{"final_answer": text}``. This keeps the control flow fully testable with
+  a scripted planner and lets any decision policy drop in.
+
+* `run_llm_agent`: a real multi-turn function-calling loop over an
+  `LLMProvider` (OpenAI, Anthropic, or the test
+  `MockProvider`). It maintains the full message
+  history with tool-call ids, executes every requested tool (validating
+  arguments and capturing errors so the model can self-correct), feeds the JSON
+  results back, and returns when the model answers in plain text.
+
+`llm_planner` bridges the two: it turns a provider into a planner for the
+simple loop. A deterministic `heuristic_planner` is provided for tests and
+offline use.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from fugacio.copilot.llm.base import ChatResponse, LLMProvider, Message, ToolCall
+from fugacio.copilot.tools import ToolSpec, call_tool, default_registry, tool_schemas
+
+JsonDict = dict[str, Any]
+Planner = Callable[[str, list[JsonDict], list[JsonDict]], JsonDict]
+
+#: Default system prompt grounding the model as a chemical-engineering copilot.
+DEFAULT_SYSTEM_PROMPT = (
+    "You are Fugacio, an expert chemical-process design copilot. You answer "
+    "engineering questions by calling the provided tools, which run a rigorous, "
+    "differentiable thermodynamics and flowsheet engine. Prefer computing with "
+    "tools over estimating from memory. Use SI units (kelvin, pascal, mol/s, "
+    "watts, dollars). When you have enough information, give a concise, "
+    "quantitative final answer that cites the numbers the tools returned."
+)
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    """Outcome of an agent run.
+
+    Attributes:
+        answer: The final natural-language (or structured) answer.
+        transcript: Ordered tool calls with their arguments and results.
+        stop_reason: Why the loop ended (``"answer"`` or ``"budget"``).
+        steps: Number of planner / model turns taken.
+    """
+
+    answer: str
+    transcript: list[JsonDict] = field(default_factory=list)
+    stop_reason: str = "answer"
+    steps: int = 0
+
+
+def run_agent(
+    goal: str,
+    planner: Planner,
+    *,
+    registry: dict[str, ToolSpec] | None = None,
+    max_steps: int = 6,
+) -> AgentResult:
+    """Run the plan/act loop until the planner returns a final answer.
+
+    Args:
+        goal: The natural-language design goal.
+        planner: Decision function (see module docstring); inject an LLM via
+            `llm_planner`, or pass a scripted/heuristic planner.
+        registry: Tool registry to expose (defaults to `default_registry`).
+        max_steps: Maximum number of tool calls before giving up.
+
+    Returns:
+        An `AgentResult` with the final answer and the full transcript.
+    """
+    registry = default_registry() if registry is None else registry
+    schemas = tool_schemas(registry)
+    transcript: list[JsonDict] = []
+    for step in range(max_steps):
+        decision = planner(goal, schemas, transcript)
+        if "final_answer" in decision:
+            return AgentResult(
+                answer=str(decision["final_answer"]),
+                transcript=transcript,
+                stop_reason="answer",
+                steps=step + 1,
+            )
+        name = decision["tool"]
+        arguments = decision.get("arguments", {})
+        result = call_tool(name, arguments, registry)
+        transcript.append({"tool": name, "arguments": arguments, "result": result})
+    return AgentResult(
+        answer="step budget exhausted before a final answer",
+        transcript=transcript,
+        stop_reason="budget",
+        steps=max_steps,
+    )
+
+
+def run_llm_agent(
+    goal: str,
+    provider: LLMProvider,
+    *,
+    registry: dict[str, ToolSpec] | None = None,
+    system: str = DEFAULT_SYSTEM_PROMPT,
+    max_steps: int = 8,
+    temperature: float = 0.0,
+    max_tokens: int = 1024,
+) -> AgentResult:
+    """Drive a real function-calling LLM through the tool registry to an answer.
+
+    Maintains the full chat history with tool-call ids, executes each requested
+    tool (validating arguments and turning errors into a JSON error result the
+    model can recover from), and loops until the model replies with plain text or
+    the step budget is exhausted.
+
+    Args:
+        goal: The user's natural-language request.
+        provider: Any `LLMProvider`.
+        registry: Tool registry (defaults to `default_registry`).
+        system: System prompt; defaults to `DEFAULT_SYSTEM_PROMPT`.
+        max_steps: Maximum model turns.
+        temperature: Sampling temperature.
+        max_tokens: Per-turn token cap.
+
+    Returns:
+        An `AgentResult`.
+    """
+    registry = default_registry() if registry is None else registry
+    schemas = tool_schemas(registry)
+    messages: list[Message] = [Message.system(system), Message.user(goal)]
+    transcript: list[JsonDict] = []
+
+    for step in range(max_steps):
+        reply: ChatResponse = provider.chat(
+            messages, tools=schemas, temperature=temperature, max_tokens=max_tokens
+        )
+        if not reply.has_tool_calls:
+            return AgentResult(
+                answer=reply.content,
+                transcript=transcript,
+                stop_reason="answer",
+                steps=step + 1,
+            )
+        messages.append(Message.assistant(reply.content, reply.tool_calls))
+        for call in reply.tool_calls:
+            result = _safe_call(call.name, call.arguments, registry)
+            transcript.append({"tool": call.name, "arguments": call.arguments, "result": result})
+            messages.append(Message.tool(json.dumps(result), call.id, call.name))
+
+    return AgentResult(
+        answer="step budget exhausted before a final answer",
+        transcript=transcript,
+        stop_reason="budget",
+        steps=max_steps,
+    )
+
+
+def _safe_call(name: str, arguments: JsonDict, registry: dict[str, ToolSpec]) -> JsonDict:
+    """Execute a tool, returning a structured ``{"error": ...}`` result on failure.
+
+    Surfacing the error to the model (rather than raising) lets the agent recover
+    from a hallucinated tool name or a malformed argument on the next turn.
+    """
+    if name not in registry:
+        return {"error": f"unknown tool {name!r}; available: {sorted(registry)}"}
+    missing = _missing_required(registry[name], arguments)
+    if missing:
+        return {"error": f"missing required arguments for {name!r}: {missing}"}
+    try:
+        return call_tool(name, arguments, registry)
+    except Exception as exc:  # report any tool failure back to the model
+        return {"error": f"{type(exc).__name__}: {exc}"}
+
+
+def _missing_required(spec: ToolSpec, arguments: JsonDict) -> list[str]:
+    """Names of required schema parameters absent from ``arguments``."""
+    required = spec.parameters.get("required", [])
+    return [key for key in required if key not in arguments]
+
+
+def llm_planner(
+    provider: LLMProvider,
+    *,
+    system: str = DEFAULT_SYSTEM_PROMPT,
+    temperature: float = 0.0,
+    max_tokens: int = 1024,
+) -> Planner:
+    """Adapt an `LLMProvider` into a `Planner` for `run_agent`.
+
+    On each call it reconstructs the conversation from the goal and transcript,
+    asks the model for the next step, and maps the first requested tool call to a
+    ``{"tool", "arguments"}`` decision (or the text reply to ``final_answer``).
+    """
+
+    def planner(goal: str, schemas: list[JsonDict], transcript: list[JsonDict]) -> JsonDict:
+        messages = _rebuild_messages(goal, transcript, system)
+        reply = provider.chat(
+            messages, tools=schemas, temperature=temperature, max_tokens=max_tokens
+        )
+        if reply.has_tool_calls:
+            call = reply.tool_calls[0]
+            return {"tool": call.name, "arguments": call.arguments}
+        return {"final_answer": reply.content}
+
+    return planner
+
+
+def _rebuild_messages(goal: str, transcript: list[JsonDict], system: str) -> list[Message]:
+    """Reconstruct a chat history (with synthetic call ids) from a flat transcript."""
+    messages: list[Message] = [Message.system(system), Message.user(goal)]
+    for i, entry in enumerate(transcript):
+        call_id = f"call_{i}"
+        messages.append(
+            Message.assistant(
+                "", [ToolCall(id=call_id, name=entry["tool"], arguments=entry["arguments"])]
+            )
+        )
+        messages.append(Message.tool(json.dumps(entry["result"]), call_id, entry["tool"]))
+    return messages
+
+
+def heuristic_planner(rules: Sequence[tuple[str, JsonDict]], *, default_answer: str) -> Planner:
+    """A deterministic keyword planner: fire the first rule whose keyword is in the goal.
+
+    Each rule is ``(keyword, decision)``; the first ``keyword`` found in the goal
+    (case-insensitive) triggers its ``decision`` once. After its tool runs (or if
+    no rule matches), the planner returns ``default_answer``. Useful for offline
+    demos and tests without an LLM.
+    """
+
+    def planner(goal: str, schemas: list[JsonDict], transcript: list[JsonDict]) -> JsonDict:
+        if transcript:
+            return {"final_answer": default_answer}
+        lowered = goal.lower()
+        for keyword, decision in rules:
+            if keyword.lower() in lowered:
+                return decision
+        return {"final_answer": default_answer}
+
+    return planner