README.md

metadata

title: ControlAI Agent
colorFrom: blue
colorTo: indigo
sdk: gradio
app_file: app_space.py
pinned: false

ControlAI: Open-Source Safety-Critical AI Agent for Control Systems Engineering

ControlAI is an open-source, domain-specific AI assistant engineered specifically for Control Systems Engineering, Dynamical Systems, Robotics, and Applied Mathematics.

---

Quickstart

ControlAI runs entirely on your own machine. Requires Apple Silicon (inference is MLX) with at least 16 GB of unified memory; the default model needs about 8 GB on disk and is downloaded on first run.

git clone https://github.com/atakankahya/controlai-agent.git
cd controlai-agent
pip install -r requirements.txt

./run.sh                  # web console, opens http://127.0.0.1:8000
./run.sh --cli            # interactive terminal chat
./run.sh --cli "design an LQR for A=[[0,1],[-2,-3]], B=[[0],[1]], Q=eye(2), R=1"
./run.sh --build-index    # build the dense retrieval index from data/user_docs/ (~45 min)

Variable	Default	Purpose
CONTROLAI_MODEL	mlx-community/Qwen3-14B-4bit	any MLX model id or local path
CONTROLAI_ADAPTER	(none)	optional LoRA adapter
CONTROLAI_THINKING	auto	off, auto (conceptual questions only), or on
CONTROLAI_THINK_BUDGET	512	ceiling on tokens spent reasoning

---

Motivation: Safety-Critical Verification in Control Engineering

Standard large language models (LLMs) operate probabilistically without deterministic verification. When applied to physical systems—such as autonomous aerial vehicles, industrial manipulators, or power grids—general-purpose models present severe reliability challenges:

• Numerical Hallucinations: Estimating eigenvalues without characteristic polynomial evaluation, inverting singular matrices, or generating unstable feedback gains.
• Lack of Formal Proof Structure: Omitting boundary conditions, PBH rank tests, or domain-specific stability limits.
• Physical Safety Violations: A sign error in a state feedback gain leads directly to closed-loop instability in hardware.

ControlAI addresses these limitations through a hybrid architecture:

1. Deterministic Scientific Sandbox: Computes continuous/discrete algebraic Riccati equations (CARE/DARE), matrix exponentials, and Bode diagrams using LAPACK, SciPy, and CVXPY.
2. 4-Stage Mathematical Proof Standard: Formulates system class, analytical theorems, closed-form derivations, and engineering breakdown limits.
3. Dynamic Simulation & Plotting: Solves nonlinear differential equations and renders verified trajectories directly in the interface.
4. Offline Retrieval: 80,000+ chunks of classical and modern control literature, indexed locally. The prebuilt index is not distributed -- it carries the full text of copyrighted textbooks -- so --build-index builds one from whatever you put in data/user_docs/. Lexical and dense rankings are fused and gated on cosine similarity, so an unrelated passage is dropped rather than cited — the retriever returning nothing is a normal outcome.
5. Bounded latency: the fixed system-prompt and tool-schema prefix is prefilled once at startup and reused across turns, so answers begin streaming in well under a second.

---

Architecture Overview

graph TD
    User([Engineering Query]) --> Frontend[Web Console / CLI]
    Frontend --> Agent[ControlAgent streaming tool loop]

    subgraph Local[Runs entirely on-device]
        Engine[LocalEngine - MLX, cached KV prefix]
        Model[Qwen3-14B-4bit]
        Retriever[Hybrid Retriever - BM25 + dense]
        Tools[Deterministic Tool Registry]
    end

    Agent --> Engine --> Model
    Agent --> Retriever
    Agent --> Tools

    Tools --> SciPy[SciPy / LAPACK / BLAS]
    Tools --> PythonControl[python-control]
    Tools --> PyExecutor[Sandboxed Python]
    Tools --> Verifier[Residual Verifier]

    Verifier --> Answer[Verified answer, plots, citations]
    Answer --> Frontend

---

Key Capabilities

1. Modern Interactive Web Console (web/)

• Real-Time Token Streaming (SSE): Token-by-token fluid rendering with smart scroll retention.
• LaTeX Formula Rendering: KaTeX integration with math delimiter protection and syntax-highlighted code blocks.
• Engineering Toolbar: One-click insertion of state matrices, transfer functions, and control parameters ($\zeta, \omega_n$).

2. Deterministic Mathematical Tool Suite (controlai_agent/tools/)

• State-Space Analysis: Exact ZOH discretization, eigenvalue decomposition, controllability and observability Gramians, and Lyapunov equation solvers.
• Frequency Domain: Exact Bode magnitude and phase calculation, gain/phase margins, and Routh-Hurwitz stability criterion.
• Controller Synthesis: Continuous LQR (CARE), Discrete LQR (DARE), pole placement, PID tuning, and constrained Model Predictive Control (CVXPY QP).
• State Estimation: Kalman filter prediction and Joseph-stabilized measurement updates.
• Nonlinear & Safety Filters: Control Barrier Functions (CBF-QP safety filter), Nonlinear Dynamic Inversion (NDI), and Feedback Linearization.
• Robust Control: Kharitonov stability test, Small Gain theorem, and multiplicative uncertainty bounds.

3. Live Python Execution Sandbox (python_executor.py)

• Executes scientific Python routines using numpy, scipy.signal, scipy.linalg, control, and matplotlib.
• Automatically isolates and captures generated simulation plots to outputs/plots/ and renders them in chat.

---

Benchmark Results (ControlBench-v1)

These figures were measured against the previous architecture — the fine-tuned Qwen3-4B LoRA served through the old orchestrator. That serving path has been replaced (base Qwen3-14B, no adapter, rewritten agent loop and retriever), and the suite has not yet been re-run against it, so treat the table as historical rather than as a description of the current build.

Evaluated across 50 multi-pillar benchmark problems:

Benchmark Pillar	Qwen3-4B Base (Text-Only)	ControlAI Agent (Ours)	Verification Mechanism
Numerical Synthesis (CARE, DARE, ZOH, Kalman)	0.0%	100.0%	Deterministic SciPy/LAPACK solver with $10^{-10}$ residual verification.
Theory & Proofs (PBH, Doyle 1978, Waterbed)	83.3%	86.7% - 95.0%	4-Stage CoT Proof Standard with literature grounding.
Code & Simulation (SciPy ODE, Matplotlib)	29.0%	90.0%+	Dynamic execution sandbox with automated plot capture.
Safety & Traps (Uncontrollable / Ill-conditioned modes)	60.0%	80.0%	Pre-computation PBH rank verification.
Real-World Case Studies (Aerospace, Drone, Automotive)	80.0%	80.0%	CBF-QP safety filtering and nonlinear inversion.
Overall Score	47.3%	87.3%	Deterministic tool execution and mathematical grounding.

---

Open-Source and Community Support

ControlAI is an open-source project developed for control engineering researchers, robotics practitioners, and applied mathematicians.

Contributing:

Contributions from the community are welcome across several areas:

• Analytical Derivations: Expanding formal proof templates for multi-input multi-output (MIMO) systems.
• Nonlinear Control: Implementing additional Control Lyapunov Functions (CLFs) and adaptive controllers.
• Simulation Bridges: Connecting agent tool calls with external simulation platforms (ROS 2, MATLAB/Simulink, Gazebo).
• Benchmark Expansion: Adding challenging test problems to benchmarks/controlbench_v1.jsonl.

---

License

This project is licensed under the MIT License.