Appendix D: R-THYM AI Co-pilot Architecture & Steering

The R-THYM AI Co-pilot is a premium, context-aware virtual engineering assistant designed to help users build, troubleshoot, and optimize complex integrated hydraulic and electrical networks. By leveraging advanced language models paired with live simulation context, the Co-pilot lowers the barrier to entry for professional-grade hydraulic modeling.

This reference guide provides a deep dive into the information sources that feed the AI Co-pilot and the explicit behavioral rules and constraints programmed into its steering engine.

1. Information Feeds (Context Sources)

To provide accurate and contextually relevant assistance, the AI Co-pilot receives a structured data package representing the current state of the active project during every query. This context is divided into three primary layers:

A. Topological Schematic Data (systemData)

The Co-pilot has a full view of the interactive canvas topology. It reads the raw JSON representing all components currently placed on the schematic, including all their configured physical and operational parameters: - Hydraulic Components: Junctions (elevation, base demand, etc.), Tanks (elevation, diameter, max depth, initial level, initial quality, etc.), Pressure Boundaries (total head, patterns), Inflow/Outflow Nodes (demands, patterns, random flow parameters, etc.), Pipes (length, diameter, roughness, quadrants, etc.), Pumps (type, speed, curve configuration, efficiency, design flow/head, etc.), and Valves (PRV, PSV, TCV, GPV settings, initial status, etc.). - Electrical & Energy Components: Utility Grids (limits, carbon intensity, export permissions, voltage, etc.), Batteries (capacity, state-of-charge limits, efficiencies, charge/discharge rates, etc.), Power Generators (solar efficiency/area, wind turbine count/rotor diameter, hydro TDH, fuel efficiency, etc.), and Power Switches/Links (capacity, status). - Logical & Telemetry Connectors: Control Links (sensor type, actuator target, PID coefficients, deadband limits, PCV sequencing, etc.) and custom Chart Nodes.

B. Simulation Execution Results

When a simulation is executed, the results are summarized and passed to the Co-pilot. This includes: - Solver State: Current mode (Steady-State, Extended Period Simulation, or Transient MOC), simulation status (Running/Paused), and simulated time (Day/Hour/Minute). - Aggregated Performance Metrics: Total water volume delivered, total energy imported/exported, total electricity costs, total fuel consumed, and fuel costs. - Hydraulic Status and Constraints: Peak pressure envelopes across all network nodes, including the absolute minimum and maximum pressures recorded, along with their location and any active cavitation alerts. - System Warnings: Real-time error messages, connectivity warnings, or numerical divergence logs. To prevent token bloat, warning arrays are automatically truncated before sending.

C. Static Domain Knowledge (agent_knowledge.md)

The server injects a static engineering knowledgebase directly into the prompt context. This file contains mathematical relationships and rules that the Co-pilot references during conversations: - Transient Fluid Dynamics: The 1-D Method of Characteristics (MOC), Courant condition calculations, and wave speed calculations using the Korteweg-Joukowsky formula. - Surge Protection Mechanics: Polytropic gas laws ($P \cdot V^n = C$) governing hydropneumatic vessels and orifice equations for air valves. - Power Generation Formulas: Thermodynamic wind turbine power equations ($0.5 \cdot \rho \cdot A \cdot V^3 \cdot \eta$) and solar panel attenuation rules.

2. Programmed Steering & Safety Guidance

To ensure the Co-pilot remains a safe, educational, and predictable assistant, its system prompt enforces strict rules governing how it interacts with the schematic.

A. Topology Modification Restrictions (Version 1.0 Limits)

[!IMPORTANT] The AI Co-pilot is restricted from directly modifying the canvas network topology in Version 1.0. It cannot add new components or links, nor delete existing elements from the canvas at this time.

If a user requests the Co-pilot to add or delete components (e.g., "Add an air valve at Junction 3" or "Delete this pipe"): 1. The Co-pilot must inform the user that direct topology modification is planned for the Version 2.0 release. 2. It must provide step-by-step guidance on how the user can manually add or delete the components using the toolbar or canvas context menus. 3. It should offer to configure the parameters (such as diameters or coefficients) once the user has manually placed the components and provided their IDs.

B. Property Configuration (Allowed Actions)

While topology editing is blocked, property modification of existing components is supported. If a component already exists on the canvas: - The Co-pilot is allowed to propose changes directly via the UPDATE_PROPERTY action. - It will automatically package these updates into a structured JSON action containing the component ID and a properties dictionary (e.g., updating a pipe's roughness or a valve's setpoint).

C. Engineering Advice vs. Automated Action

To prevent unexpected or unwanted changes to a user's model, the Co-pilot operates under two distinct interaction modes: - Explicit Requests: If a user explicitly asks to change a property (e.g., "Change the diameter of Pipe 1 to 12 inches"), the Co-pilot will immediately generate an action card. - Open-Ended Consultations: If a user asks an investigatory question (e.g., "How can I prevent water hammer here?"), the Co-pilot is instructed not to propose property modifications immediately. Instead, it must outline the engineering alternatives (such as enlarging pipes, adding surge tanks, or adjusting valve closing times) and ask the user which approach they prefer before generating any actions.

D. Resolving Implicit References

Users frequently refer to components in general terms (e.g., "the pump" or "the air valve"). The steering engine mandates that the Co-pilot cross-reference these terms with systemData: - It searches the canvas for a component matching the described type. - If a match is found, it maps the general description to the specific ID (e.g., Pump_A or AirValve_1) and targets that ID for any proposed properties updates, avoiding confusion and ensuring correct alignment.

3. Co-pilot Operations & Subscription Tiers

• AI Co-pilot Version: The AI Co-pilot is currently on Version 1.0, focusing on property configuration, diagnostics, and simulation controls. Support for direct topological drawing and canvas node additions/deletions is planned for Version 2.0. All engineering designs, warning interpretations, and component adjustments proposed by the assistant must be verified by a licensed professional engineer (PE) before field application.
• Access Tiers:
• Standard Users: Free accounts have a preview limit of 5 total Co-pilot queries. After reaching this limit, users are prompted to upgrade or join the waiting list.
• Premium Users: Subscribers on the Premium Tier (along with system staff/superusers) have unlimited access to the AI Co-pilot.