fix: Enforce parameter provenance, fix rendering/citations, add tools, harden agent loop

Reliability mechanism (the big one):
- Orchestrator now refuses any tool call whose matrix arguments cannot be
traced to the user's messages or a prior tool result (FabricatedParameter):
prompting could not stop the model from inventing B/Q/R, code now does.
- Per-tool call cap (2/turn) stops reworded-search budget exhaustion.
- Truncated tool-call JSON (dropped closing brace) is repaired instead of
silently producing an empty answer; orphaned <tool_call> tags stripped.
- Failed turns fall back to a direct no-tools answer, never a canned line.

Tools:
- New matrix_arithmetic (multiply/inverse/det/rank/eig/...): basic linear
algebra is a verified tool call, not freehand model code.
- New nyquist_analysis (Z=N+P), root_locus_analysis (asymptotes, on-locus
breakaway points, critical gain), simulate_state_feedback_response
(closed loop A-BK formed internally; ends hand-expanded coefficients).
- place_state_feedback accepts complex-conjugate poles ([re, im] pairs);
dtype=float truncation bug fixed.
- Registry: stringified-array arguments coerced before schema validation;
all float results rounded to 6 significant figures.
- Registered tools are callable by name inside execute_python_code.
- plot_math_expression rejects complex expressions instead of plotting
garbage; simulate_step_response finally emits plot_path (plots never
reached the UI before).

Rendering & citations:
- Double-backslash LaTeX repair extended to delimiters (\\| \\{ \\() while
preserving real matrix row breaks; system prompt de-doubled.
- RAG citations use cleaned source names (published works by author/title,
personal lecture notes labeled generically) -- raw filenames never shown.

RAG:
- Process-wide shared index: uploads are searchable immediately, no restart.
- Source-aware re-ranking ("what does Nise say" surfaces Nise, 1/5 -> 4/4).
- Grounding block enlarged (4 passages, 900 chars) with trust-the-passage
and citation-format instructions.

Web UI:
- Deleting a non-active chat no longer wipes the active thread mid-stream.
- Animated working indicator; font-size preference now scales code blocks,
thought text, and plot captions.

Infra:
- MLX thread-affinity fix: all inference on one dedicated executor thread
(fixes "There is no Stream(cpu, 0) in current thread" on every request).
- Broader multi-domain system prompt (aerospace/automotive/robotics/
automation/power) with answer-shape routing rules.

Scripts:
- test_rag_knowledge.py: 25-query multi-domain retrieval suite (25/25).
- eval_answer_quality.py: 18-question full-agent quality gate.
- generate_behavior_sft_dataset.py + config: behavioral SFT round v1
(trained; failed A/B -- reduced tool usage -- so NOT deployed; kept for
the next data-mixture iteration).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import os
+import queue
 import shutil
 import sys
-import threading
 import time
+from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Any
@@ -27,12 +29,24 @@ if str(PROJECT_ROOT) not in sys.path:
 from controlai_agent.orchestrator import ControlAIAgent
 from controlai_rag.chunker import chunk_document
 from controlai_rag.document_loader import load_single_file
-from controlai_rag.index import ControlRAGIndex
+from controlai_rag.index import get_shared_index
+
+# MLX keeps its compute stream in thread-local state: the model must be
+# loaded on the exact same OS thread that later runs generation, or MLX
+# raises "There is no Stream(cpu, 0) in current thread." Starlette's default
+# StreamingResponse threadpool picks a different worker thread per request,
+# which breaks that invariant. Routing every agent call through this single
+# dedicated worker thread keeps MLX on one consistent thread for the whole
+# process lifetime, and -- as a bonus -- a max_workers=1 executor naturally
+# serializes every request through the one model instance (llama.cpp's Llama
+# object also isn't safe for concurrent calls from multiple threads).
+inference_executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="controlai-inference")
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     print("Pre-loading ControlAI Core Engine on startup...")
-    get_agent()
+    await asyncio.get_event_loop().run_in_executor(inference_executor, get_agent)
     print("ControlAI Core Engine is online and ready for traffic.")
     yield
 
@@ -64,9 +78,6 @@ if STATIC_DIR.exists():
 
 # Initialize Agent
 agent_instance: ControlAIAgent | None = None
-# llama.cpp's Llama object is not safe for concurrent generation calls from
-# multiple threads; serialize every request through the single model instance.
-inference_lock = threading.Lock()
 
 
 def get_agent() -> ControlAIAgent:
@@ -179,8 +190,10 @@ async def upload_document(file: UploadFile = File(...)) -> dict[str, Any]:
             chunks = chunk_document(p)
             new_chunks.extend(chunks)
 
-        index_dir = PROJECT_ROOT / "data" / "rag_index"
-        index = ControlRAGIndex(index_dir)
+        # Mutating the shared index makes the upload live for the running
+        # agent immediately -- a fresh instance would only persist to disk and
+        # stay invisible until restart.
+        index = get_shared_index()
         index.add_chunks(new_chunks)
 
         return {
@@ -202,13 +215,33 @@ async def chat_stream_endpoint(req: ChatRequest):
     if not req.message.strip():
         raise HTTPException(status_code=400, detail="Message cannot be empty")
 
-    def event_generator():
+    message = req.message.strip()
+    history = req.history
+    event_queue: queue.Queue = queue.Queue()
+    _DONE = object()
+
+    def _produce() -> None:
+        # Runs entirely on inference_executor's single dedicated thread --
+        # the same thread the model was loaded on -- so MLX's thread-local
+        # stream stays valid.
         try:
-            with inference_lock:
-                for event in _run_stream_on_gpu(req.message.strip(), req.history):
-                    yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
+            for event in _run_stream_on_gpu(message, history):
+                event_queue.put(event)
         except Exception as exc:
-            yield f"data: {json.dumps({'type': 'error', 'error': str(exc)}, ensure_ascii=False)}\n\n"
+            event_queue.put({"type": "error", "error": str(exc)})
+        finally:
+            event_queue.put(_DONE)
+
+    async def event_generator():
+        loop = asyncio.get_event_loop()
+        loop.run_in_executor(inference_executor, _produce)
+        while True:
+            # Draining the queue never touches MLX, so this can safely run on
+            # the default threadpool.
+            event = await loop.run_in_executor(None, event_queue.get)
+            if event is _DONE:
+                break
+            yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
 
     return StreamingResponse(
         event_generator(),
@@ -228,8 +261,8 @@ async def chat_endpoint(req: ChatRequest) -> ChatResponse:
 
     t0 = time.time()
     try:
-        with inference_lock:
-            result = _run_on_gpu(req.message.strip(), req.history)
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(inference_executor, _run_on_gpu, req.message.strip(), req.history)
         elapsed = time.time() - t0
 
         # Collect tool traces

configs/lora_controlai_behavior_v1.yaml

@@ -0,0 +1,60 @@
+# ControlAI Behavior v1: fix tool routing, missing-parameter refusal, and
+# multi-turn faithfulness -- resumed from the deployed sft_v2 adapter.
+#
+# Why this round exists: the deployed adapter was trained exclusively on
+# fully-specified control problems, so it (a) routed plain matrix questions
+# to control-design tools, (b) fabricated missing B/Q/R instead of asking,
+# and (c) reused numbers from previous unrelated problems in multi-turn
+# chats. data/training/behavior_mix_v1 is 35% new verified behavioral
+# trajectories targeting exactly those failures + 65% replay of sft_v2 and
+# agent_sft_v1 so existing skills are retained.
+model: mlx-community/Qwen3-4B-Instruct-2507-4bit
+train: true
+fine_tune_type: lora
+data: data/training/behavior_mix_v1
+seed: 20260819
+
+resume_adapter_file: adapters/controlai_qwen3_4b_sft_v2/adapters.safetensors
+
+mask_prompt: true
+
+num_layers: 36
+batch_size: 1
+grad_accumulation_steps: 4
+iters: 1600
+max_seq_length: 2048
+grad_checkpoint: false
+clear_cache_threshold: 12000000000
+
+optimizer: adamw
+optimizer_config:
+  adamw:
+    weight_decay: 0.01
+# Half the v2 learning rate: this is a refinement pass on an already-trained
+# adapter, not training from scratch.
+learning_rate: 2.0e-6
+lr_schedule:
+  name: cosine_decay
+  # 1600 iters / accumulation 4 = 400 optimizer steps
+  arguments: [2.0e-6, 380, 2.0e-7]
+  warmup: 20
+  warmup_init: 2.0e-7
+
+val_batches: -1
+steps_per_report: 25
+steps_per_eval: 400
+save_every: 400
+adapter_path: adapters/controlai_qwen3_4b_behavior_v1
+
+lora_parameters:
+  rank: 16
+  dropout: 0.05
+  scale: 32.0
+  keys:
+    - self_attn.q_proj
+    - self_attn.k_proj
+    - self_attn.v_proj
+    - self_attn.o_proj
+    - mlp.gate_proj
+    - mlp.up_proj
+    - mlp.down_proj

controlai_agent/orchestrator.py

@@ -34,7 +34,7 @@ from transformers import AutoModelForCausalLM, AutoTokenizer
 from controlai_agent.prompts import CONTROLAI_SYSTEM_PROMPT
 from controlai_agent.registry import ToolRegistry, registry
 import controlai_agent.tools  # noqa: F401 (ensure all tools are registered)
-from controlai_rag.index import ControlRAGIndex
+from controlai_rag.index import get_shared_index
 
 
 @dataclass
@@ -71,6 +71,42 @@ def fix_space_separated_arrays(json_str: str) -> str:
     return re.sub(r"\[\s*([0-9eE\.\-+\s]+?)\s*\]", _fix_brackets, json_str)
 
 
+def close_unbalanced_json(raw: str) -> str:
+    """Append the closing braces/brackets a truncated JSON object is missing.
+
+    Small quantized models routinely drop the final `}` of a tool call (emitting
+    `{"name": ..., "arguments": {...}` with the outer object left open). Without
+    repair the call fails to parse, the tool never runs, and the turn collapses
+    into an empty answer -- so balance the delimiters and let it parse.
+    """
+    stack: list[str] = []
+    in_string = False
+    escaped = False
+    for ch in raw:
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch in "{[":
+            stack.append(ch)
+        elif ch in "}]":
+            if stack and ((ch == "}" and stack[-1] == "{") or (ch == "]" and stack[-1] == "[")):
+                stack.pop()
+
+    repaired = raw
+    if in_string:
+        repaired += '"'
+    for opener in reversed(stack):
+        repaired += "}" if opener == "{" else "]"
+    return repaired
+
+
 def parse_flexible_json(raw_str: str) -> dict[str, Any] | None:
     """Parse JSON with fallback to escape sanitization, array fixing, and non-strict control characters."""
     raw_str = raw_str.strip()
@@ -97,9 +133,47 @@ def parse_flexible_json(raw_str: str) -> dict[str, Any] | None:
     except Exception:
         pass
 
+    # Last resort: the object is well-formed but truncated (a dropped closing
+    # brace), so balance the delimiters and retry each variant.
+    for candidate in (
+        raw_str,
+        sanitize_json_escapes(raw_str),
+        fix_space_separated_arrays(sanitize_json_escapes(raw_str)),
+    ):
+        try:
+            obj = json.loads(close_unbalanced_json(candidate), strict=False)
+            if isinstance(obj, dict):
+                return obj
+        except Exception:
+            continue
+
     return None
 
 
+# A doubled backslash is an accidental JSON-style escape when it precedes:
+#   - a command name       \\zeta  \\frac  \\sum
+#   - a delimiter escape   \\|  \\{  \\}  \\(  \\)  \\]
+#   - \\[ that does NOT begin a spacing argument such as a genuine "\\[2pt]"
+# A real LaTeX row break inside matrix/aligned is followed by whitespace, a
+# newline, or a digit-led spacing option -- never by any of the above -- so
+# these rewrites leave legitimate line breaks untouched.
+_LATEX_DOUBLE_BACKSLASH_RE = re.compile(r"\\\\(?=[a-zA-Z|{}()\]])|\\\\(?=\[\s*[^\d\s])")
+
+
+def _fix_doubled_latex_backslashes(text: str) -> str:
+    """Collapse an accidental JSON-escape-style double backslash before a LaTeX
+    command or delimiter (\\\\zeta, \\\\|) down to the single backslash KaTeX
+    expects (\\zeta, \\|).
+
+    The base model was heavily trained on JSON-argument function calling, where
+    a literal backslash must be written as `\\\\` inside a JSON string. That
+    habit leaks into plain-text math even outside of a tool call. Left alone,
+    `\\\\|x - x_f\\\\|^2` renders as a line break followed by a stray pipe,
+    tearing a norm across two lines instead of drawing it.
+    """
+    return _LATEX_DOUBLE_BACKSLASH_RE.sub(lambda m: "\\", text)
+
+
 def _extract_tool_calls(text: str) -> tuple[list[dict[str, Any]], str]:
     """Parse tool calls from <tool_call>, markdown code blocks, or raw JSON robustly."""
     calls: list[dict[str, Any]] = []
@@ -129,12 +203,222 @@ def _extract_tool_calls(text: str) -> tuple[list[dict[str, Any]], str]:
     cleaned = re.sub(r"<tool_call>[\s\S]*?</tool_call>", "", text, flags=re.DOTALL)
     cleaned = re.sub(r"```(?:json)?\s*\{\s*[\"']name[\"']\s*:[\s\S]*?\}\s*```", "", cleaned)
     cleaned = re.sub(r"\{\s*[\"']name[\"']\s*:\s*[\"'][a-zA-Z0-9_]+[\"'][\s\S]*\}", "", cleaned)
+    # An orphaned <tool_call> tag with no matching close (the model started a
+    # call, then abandoned it mid-generation for plain text) survives the
+    # paired regex above -- strip any leftover tag so it never reaches the UI.
+    cleaned = re.sub(r"</?tool_call>", "", cleaned)
     cleaned = cleaned.strip()
+    cleaned = _fix_doubled_latex_backslashes(cleaned)
     return calls, cleaned
 
 
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
 
+# How many times a single tool may be invoked within one user turn. Two allows
+# a legitimate retry with corrected arguments after an error, while stopping
+# the model from spending its whole step budget re-running the same lookup.
+MAX_CALLS_PER_TOOL = 2
+
+
+# ---------------------------------------------------------------------------
+# Parameter provenance enforcement
+#
+# Prompt rules against inventing parameters demonstrably do not hold on a 4B
+# model: given "A times A" after an earlier LQR conversation, it fabricated a
+# brand-new B, resized Q, and ran a confident LQR synthesis -- three separate
+# prompt formulations failed to stop it. So faithfulness is enforced in code:
+# every 2D matrix handed to a tool must be traceable to the user's messages or
+# a prior tool result in this conversation, or the call is refused before it
+# executes and the model is told to ask the user for the missing value.
+# ---------------------------------------------------------------------------
+
+# Parameters exempt from the guard:
+#  - C/D: conventional output-selector / feedthrough matrices (entries 0/1),
+#    routinely and legitimately chosen by the designer, and harmless.
+#  - desired_poles: pole locations are design choices derived from specs
+#    ("settling time under 2s"), not data the user must dictate literally.
+_PROVENANCE_EXEMPT_PARAMS = {"C", "D", "desired_poles"}
+
+_NUMBER_RE = re.compile(r"-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?")
+
+
+def _extract_arrays_from_text(text: str) -> list[list]:
+    """Find every parseable bracketed numeric array (1D or 2D) in free text."""
+    arrays: list[list] = []
+    n = len(text)
+    i = 0
+    while i < n:
+        if text[i] != "[":
+            i += 1
+            continue
+        depth = 0
+        j = i
+        while j < n:
+            if text[j] == "[":
+                depth += 1
+            elif text[j] == "]":
+                depth -= 1
+                if depth == 0:
+                    break
+            j += 1
+        if depth != 0:
+            i += 1
+            continue
+        candidate = text[i : j + 1]
+        # Third variant: users mix separators freely ("[3 0, 1]"), which the
+        # comma-only fixer can't handle -- insert a comma between any two
+        # adjacent number tokens regardless of other separators present.
+        mixed_fixed = re.sub(r"(?<=[\d.])\s+(?=[-\d.])", ", ", candidate)
+        for variant in (candidate, fix_space_separated_arrays(candidate), mixed_fixed):
+            try:
+                parsed = json.loads(variant)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(parsed, list) and parsed:
+                arrays.append(parsed)
+                break
+        # Only skip past this bracket char, not the whole span: inner arrays
+        # of a 2D matrix should also be collected individually (rows are
+        # legitimate 1D vectors in their own right).
+        i += 1
+    return arrays
+
+
+def _collect_numeric_leaves(obj: Any, arrays: list[list], numbers: set[float]) -> None:
+    """Harvest nested numeric lists and scalars from a parsed JSON object."""
+    if isinstance(obj, bool):
+        return
+    if isinstance(obj, (int, float)):
+        numbers.add(float(obj))
+        return
+    if isinstance(obj, list):
+        if obj and all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in obj):
+            arrays.append(list(obj))
+        elif obj and all(isinstance(v, list) for v in obj):
+            arrays.append(obj)
+        for v in obj:
+            _collect_numeric_leaves(v, arrays, numbers)
+        return
+    if isinstance(obj, dict):
+        for v in obj.values():
+            _collect_numeric_leaves(v, arrays, numbers)
+
+
+def _as_2d_float_array(value: Any):
+    """Return value as a 2D float ndarray, or None if it isn't one."""
+    import numpy as _np
+
+    try:
+        arr = _np.array(value, dtype=float)
+    except (TypeError, ValueError):
+        return None
+    if arr.ndim == 1 and arr.size > 0:
+        arr = arr.reshape(1, -1)
+    if arr.ndim != 2 or arr.size == 0:
+        return None
+    return arr
+
+
+class ParameterProvenance:
+    """Everything numeric the conversation has actually provided so far."""
+
+    def __init__(self, messages: list[dict[str, Any]]) -> None:
+        import numpy as _np
+
+        self._np = _np
+        self.arrays: list[Any] = []
+        self.current_numbers: set[float] = set()
+        all_user_texts: list[str] = []
+        current_user_text = ""
+
+        for msg in messages:
+            role = msg.get("role")
+            content = msg.get("content", "")
+            if role == "user" and isinstance(content, str):
+                all_user_texts.append(content)
+                current_user_text = content
+            elif role == "tool" and isinstance(content, str):
+                try:
+                    parsed = json.loads(content)
+                except json.JSONDecodeError:
+                    continue
+                found_arrays: list[list] = []
+                found_numbers: set[float] = set()
+                _collect_numeric_leaves(parsed, found_arrays, found_numbers)
+                for a in found_arrays:
+                    arr = _as_2d_float_array(a)
+                    if arr is not None:
+                        self.arrays.append(arr)
+                # Scalars computed by tools (gains, margins) are legitimate
+                # inputs for later steps.
+                self.current_numbers |= found_numbers
+
+        for text in all_user_texts:
+            for a in _extract_arrays_from_text(text):
+                arr = _as_2d_float_array(a)
+                if arr is not None:
+                    self.arrays.append(arr)
+        # Loose scalars only count from the CURRENT user message: numbers from
+        # an earlier, different problem are exactly what must not silently
+        # seed a new Q or R.
+        for m in _NUMBER_RE.finditer(current_user_text):
+            try:
+                self.current_numbers.add(float(m.group()))
+            except ValueError:
+                pass
+
+    def _matches_known_array(self, arr) -> bool:
+        np_ = self._np
+        for known in self.arrays:
+            for cand in (known, known.T):
+                if cand.shape == arr.shape and np_.allclose(cand, arr, rtol=1e-6, atol=1e-9):
+                    return True
+        return False
+
+    def _number_provided(self, x: float) -> bool:
+        if x in (0.0, 1.0, -1.0):
+            return True
+        return any(abs(x - n) <= 1e-9 * max(1.0, abs(n)) for n in self.current_numbers)
+
+    def verify(self, value: Any) -> bool:
+        """True if this matrix is traceable to the conversation."""
+        np_ = self._np
+        arr = _as_2d_float_array(value)
+        if arr is None:
+            return True  # not a matrix -- out of scope for this guard
+
+        if self._matches_known_array(arr):
+            return True
+
+        # 1x1 "matrix" wrapping a scalar the user stated (R=1 -> [[1]]).
+        if arr.shape == (1, 1):
+            return self._number_provided(float(arr[0, 0]))
+
+        # Identity / zero matrices are structural, not data.
+        if arr.shape[0] == arr.shape[1]:
+            if np_.allclose(arr, np_.eye(arr.shape[0])) or np_.allclose(arr, 0.0):
+                return True
+            # diag(...) built from numbers in the current message, e.g. the
+            # user wrote "Q=diag([10, 1])" in prose rather than as an array.
+            if np_.allclose(arr, np_.diag(np_.diag(arr))):
+                return all(self._number_provided(float(d)) for d in np_.diag(arr))
+
+        return False
+
+
+def _check_parameter_provenance(
+    tool_args: dict[str, Any], messages: list[dict[str, Any]]
+) -> tuple[str, Any] | None:
+    """Return (param_name, value) for the first fabricated matrix, else None."""
+    provenance = ParameterProvenance(messages)
+    for param, value in tool_args.items():
+        if param in _PROVENANCE_EXEMPT_PARAMS:
+            continue
+        if isinstance(value, list) and value and isinstance(value[0], list):
+            if not provenance.verify(value):
+                return param, value
+    return None
+
 
 class ControlAIAgent:
     """Universal Control Engineering Agent supporting GGUF, Ollama C++, Apple MLX, and PyTorch."""
@@ -144,7 +428,7 @@ class ControlAIAgent:
         model_path: str = "mlx-community/Qwen3-4B-Instruct-2507-4bit",
         adapter_path: str | None = None,
         tool_registry: ToolRegistry = registry,
-        max_tool_steps: int = 3,
+        max_tool_steps: int = 4,
     ) -> None:
         self.model_path = model_path
         
@@ -253,7 +537,7 @@ class ControlAIAgent:
 
         # Initialize local offline RAG index
         try:
-            self.rag_index = ControlRAGIndex()
+            self.rag_index = get_shared_index()
         except Exception:
             self.rag_index = None
 
@@ -316,23 +600,101 @@ class ControlAIAgent:
             return base_instruction
 
         try:
-            rag_hits = self.rag_index.search(user_prompt, top_k=3)
+            rag_hits = self.rag_index.search(user_prompt, top_k=6)
             high_rel = [h for h in rag_hits if h.get("score", 0) > 2.5]
             if not high_rel:
                 return base_instruction
 
             ref_texts = []
-            for h in high_rel[:2]:
-                fname = h.get("filename", "Reference")
+            for h in high_rel[:4]:
+                # Cite the cleaned display name, never the raw indexed filename.
+                label = h.get("source_name") or h.get("filename", "Reference")
                 page = h.get("page")
-                page_str = f" (p. {page})" if page else ""
-                clean_chunk = h.get("text", "")[:400].strip()
-                ref_texts.append(f"[{fname}{page_str}]:\n{clean_chunk}")
-
-            return base_instruction + "\n\n### Grounded Reference Context from Canonical Control Literature:\n" + "\n\n".join(ref_texts)
+                page_str = f", p. {page}" if page else ""
+                clean_chunk = " ".join(h.get("text", "").split())[:900].strip()
+                ref_texts.append(f"[{label}{page_str}]\n{clean_chunk}")
+
+            return (
+                base_instruction
+                + "\n\n### Grounded Reference Context from Canonical Control Literature:\n"
+                + "\n\n".join(ref_texts)
+                + "\n\nThese passages were retrieved from the local library for THIS question. When the "
+                "question asks what a specific author or textbook says, answer directly from these "
+                "passages -- that is already the reference lookup, so do not call a numeric solver tool "
+                "to answer a conceptual question. Where a passage conflicts with your own recollection, "
+                "TRUST THE PASSAGE. Cite using exactly the bracketed label shown above (for example "
+                "[Nise, Control Systems Engineering, p. 583]); never invent a citation and never print a "
+                "raw filename, file extension, or course code."
+            )
         except Exception:
             return base_instruction
 
+    def _direct_answer(
+        self,
+        user_prompt: str,
+        system_instruction: str,
+        history: list[dict[str, Any]] | None = None,
+        max_tokens: int = 1400,
+    ) -> str:
+        """Answer the question with no tools exposed at all.
+
+        This is the recovery path for when the tool loop fails to produce usable
+        prose -- the model spent its steps on tool calls, or its synthesis turn
+        came back empty or as yet another tool call. Re-asking with tools=None
+        and without the tool-result transcript removes whatever was derailing it
+        (and shortens the prompt considerably), which reliably yields a real
+        answer instead of a canned "analysis complete" placeholder. The grounded
+        system instruction is kept, so retrieved reference passages are still
+        available to answer from.
+        """
+        messages: list[dict[str, Any]] = []
+        if system_instruction:
+            messages.append({"role": "system", "content": system_instruction})
+        if history:
+            for item in history:
+                r = item.get("role")
+                c = item.get("content")
+                if r in ("user", "assistant") and c:
+                    messages.append({"role": r, "content": c})
+        messages.append({"role": "user", "content": user_prompt})
+
+        try:
+            rendered = self.hf_tokenizer.apply_chat_template(
+                messages, tools=None, tokenize=False, add_generation_prompt=True
+            )
+            _, cleaned = _extract_tool_calls(self._generate(rendered, max_tokens=max_tokens))
+            return cleaned
+        except Exception:
+            return ""
+
+    def _execute_with_provenance(
+        self,
+        tool_name: str,
+        tool_args: dict[str, Any],
+        messages: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Run a tool only after every matrix argument is traced to the
+        conversation; refuse fabricated inputs before they execute."""
+        try:
+            fabricated = _check_parameter_provenance(tool_args, messages)
+        except Exception:
+            fabricated = None  # the guard must never take down a legitimate call
+        if fabricated is not None:
+            param, value = fabricated
+            return {
+                "status": "error",
+                "error_type": "FabricatedParameter",
+                "error": (
+                    f"REFUSED: the matrix passed as '{param}' = {json.dumps(value)} was not provided by "
+                    f"the user in this conversation and did not come from any prior tool result. Inventing "
+                    f"parameter values is forbidden. Do NOT retry this tool with a different guessed "
+                    f"'{param}'. In your final answer, tell the user that '{param}' is required for this "
+                    f"computation and ask them to provide it, and answer whatever part of their question "
+                    f"does not need it."
+                ),
+            }
+        return self.registry.execute(tool_name, tool_args)
+
     def run(
         self,
         user_prompt: str,
@@ -360,6 +722,7 @@ class ControlAIAgent:
         traces: list[ToolExecutionTrace] = []
         plots: list[str] = []
         called_signatures: set[str] = set()
+        tool_call_counts: dict[str, int] = {}
 
         for step in range(1, self.max_tool_steps + 1):
             rendered_prompt = self.hf_tokenizer.apply_chat_template(
@@ -374,9 +737,16 @@ class ControlAIAgent:
             tool_calls, pre_text = _extract_tool_calls(model_output)
 
             if not tool_calls:
-                clean_output = re.sub(r"<tool_call>.*?</tool_call>", "", model_output, flags=re.DOTALL).strip()
+                # The model chose to stop calling tools but produced no usable
+                # text either (typically right after a tool error it has no
+                # good way to recover from in-context). Retry once with no
+                # tools and no error-laden transcript rather than returning
+                # nothing.
+                final_response = pre_text or self._direct_answer(user_prompt, effective_sys, history)
+                if not final_response:
+                    final_response = "The computational analysis has been completed as detailed above."
                 return AgentResult(
-                    final_response=clean_output,
+                    final_response=final_response,
                     tool_traces=traces,
                     total_steps=step,
                     raw_messages=messages,
@@ -384,13 +754,22 @@ class ControlAIAgent:
                     plots=plots,
                 )
 
-            # Check for loops
+            # Drop repeats. An exact-signature check alone is not enough: the
+            # model will re-search with a lightly reworded query ("... MPC",
+            # "... MPC algorithm", "... MPC definition"), exhausting the step
+            # budget on near-identical lookups and leaving nothing for the
+            # answer. Cap how many times any single tool may run per turn.
             new_calls = []
             for call in tool_calls:
-                sig = f"{call.get('name')}:{json.dumps(call.get('arguments', {}), sort_keys=True)}"
-                if sig not in called_signatures:
-                    called_signatures.add(sig)
-                    new_calls.append(call)
+                name = call.get("name")
+                sig = f"{name}:{json.dumps(call.get('arguments', {}), sort_keys=True)}"
+                if sig in called_signatures:
+                    continue
+                if tool_call_counts.get(name, 0) >= MAX_CALLS_PER_TOOL:
+                    continue
+                called_signatures.add(sig)
+                tool_call_counts[name] = tool_call_counts.get(name, 0) + 1
+                new_calls.append(call)
 
             if not new_calls:
                 break
@@ -401,7 +780,7 @@ class ControlAIAgent:
                 tool_name = call_data.get("name")
                 tool_args = call_data.get("arguments", {})
 
-                tool_result = self.registry.execute(tool_name, tool_args)
+                tool_result = self._execute_with_provenance(tool_name, tool_args, messages)
                 traces.append(ToolExecutionTrace(tool_name=tool_name, arguments=tool_args, result=tool_result))
 
                 if "plot_path" in tool_result:
@@ -416,6 +795,17 @@ class ControlAIAgent:
                 })
 
         # Final synthesis after tool execution
+        messages.append({
+            "role": "user",
+            "content": (
+                "Now answer the user's most recent question directly and completely, in LaTeX-formatted "
+                "prose. If the tool results above are relevant to that question, incorporate them; if the "
+                "question is conceptual, definitional, or about what a source says and the tool results "
+                "above don't actually address it, answer the question from your own knowledge instead of "
+                "describing the tool results. Do not call any more tools and do not output JSON or "
+                "tool-call tags -- write the final answer now."
+            ),
+        })
         forced_prompt = self.hf_tokenizer.apply_chat_template(
             messages,
             tools=None,
@@ -425,8 +815,15 @@ class ControlAIAgent:
         final_output = self._generate(forced_prompt, max_tokens=max_tokens_per_step)
 
         _, clean_final = _extract_tool_calls(final_output)
+        # Never fall back to the raw final_output: if the model's closing turn
+        # degenerates into another (unparseable) tool-call attempt, clean_final
+        # is stripped down to "" and showing final_output would leak a raw
+        # <tool_call>{...}</tool_call> JSON blob straight into the chat.
+        final_response = clean_final or self._direct_answer(user_prompt, effective_sys, history)
+        if not final_response:
+            final_response = "The computational analysis has been completed as detailed above."
         return AgentResult(
-            final_response=clean_final or final_output,
+            final_response=final_response,
             tool_traces=traces,
             total_steps=len(traces) + 1,
             raw_messages=messages,
@@ -465,6 +862,7 @@ class ControlAIAgent:
         plots: list[str] = []
         thoughts: list[str] = []
         called_signatures: set[str] = set()
+        tool_call_counts: dict[str, int] = {}
 
         # Dynamic thought generation - only show thoughts when tools or derivations occur
         for step in range(1, self.max_tool_steps + 1):
@@ -481,7 +879,9 @@ class ControlAIAgent:
 
             if not tool_calls:
                 # Direct final answer without tools -> stream tokens directly
-                clean_output = pre_text or model_output
+                clean_output = pre_text or self._direct_answer(user_prompt, effective_sys, history)
+                if not clean_output:
+                    clean_output = "The computational analysis has been completed as detailed above."
                 words = re.split(r"(\s+)", clean_output)
                 for w in words:
                     if w:
@@ -500,13 +900,22 @@ class ControlAIAgent:
                 thoughts.append(pre_text)
                 yield {"type": "thought", "content": pre_text}
 
-            # Filter out duplicate loops
+            # Drop repeats. An exact-signature check alone is not enough: the
+            # model will re-search with a lightly reworded query ("... MPC",
+            # "... MPC algorithm", "... MPC definition"), exhausting the step
+            # budget on near-identical lookups and leaving nothing for the
+            # answer. Cap how many times any single tool may run per turn.
             new_calls = []
             for call in tool_calls:
-                sig = f"{call.get('name')}:{json.dumps(call.get('arguments', {}), sort_keys=True)}"
-                if sig not in called_signatures:
-                    called_signatures.add(sig)
-                    new_calls.append(call)
+                name = call.get("name")
+                sig = f"{name}:{json.dumps(call.get('arguments', {}), sort_keys=True)}"
+                if sig in called_signatures:
+                    continue
+                if tool_call_counts.get(name, 0) >= MAX_CALLS_PER_TOOL:
+                    continue
+                called_signatures.add(sig)
+                tool_call_counts[name] = tool_call_counts.get(name, 0) + 1
+                new_calls.append(call)
 
             if not new_calls:
                 break
@@ -522,7 +931,7 @@ class ControlAIAgent:
                 yield {"type": "thought", "content": t_start_msg}
                 yield {"type": "tool_start", "tool": tool_name, "args": tool_args}
 
-                tool_result = self.registry.execute(tool_name, tool_args)
+                tool_result = self._execute_with_provenance(tool_name, tool_args, messages)
                 trace_item = {
                     "tool": tool_name,
                     "args": tool_args,
@@ -556,7 +965,14 @@ class ControlAIAgent:
 
         messages.append({
             "role": "user",
-            "content": "Synthesize the simulation and calculation results above into a complete, thorough engineering explanation with LaTeX equations. Do not output any JSON or tool call tags.",
+            "content": (
+                "Now answer the user's most recent question directly and completely, in LaTeX-formatted "
+                "prose. If the tool results above are relevant to that question, incorporate them; if the "
+                "question is conceptual, definitional, or about what a source says and the tool results "
+                "above don't actually address it, answer the question from your own knowledge instead of "
+                "describing the tool results. Do not call any more tools and do not output JSON or "
+                "tool-call tags -- write the final answer now."
+            ),
         })
 
         forced_prompt = self.hf_tokenizer.apply_chat_template(
@@ -574,7 +990,7 @@ class ControlAIAgent:
             for call_data in synth_tool_calls:
                 tool_name = call_data.get("name")
                 tool_args = call_data.get("arguments", {})
-                t_res = self.registry.execute(tool_name, tool_args)
+                t_res = self._execute_with_provenance(tool_name, tool_args, messages)
                 if "plot_path" in t_res:
                     p_path = Path(t_res["plot_path"])
                     if p_path.exists():
@@ -588,7 +1004,11 @@ class ControlAIAgent:
             final_output = self._generate(re_prompt, max_tokens=max_tokens_per_step)
             _, clean_synth = _extract_tool_calls(final_output)
 
-        final_text = clean_synth or final_output
+        # Never fall back to the raw final_output here: if the model's closing
+        # turn degenerates into another (unparseable) tool-call attempt,
+        # clean_synth is stripped down to "" and showing final_output would
+        # leak a raw <tool_call>{...}</tool_call> JSON blob into the chat.
+        final_text = clean_synth
         # Strip any lingering raw json
         final_text = re.sub(r"\{\s*[\"']name[\"']\s*:[\s\S]*?\}\s*\}", "", final_text).strip()
         if not final_text:

controlai_agent/prompts.py

@@ -1,20 +1,39 @@
-CONTROLAI_SYSTEM_PROMPT = r"""You are ControlAI, a premier AI research scientist and expert engineering agent specialized in control systems engineering, applied mathematics, robotics, and dynamical systems.
+CONTROLAI_SYSTEM_PROMPT = r"""You are ControlAI, a premier AI research scientist and expert engineering agent for control systems engineering in ALL of its application domains -- aerospace and flight control, automotive and vehicle dynamics, robotics and motion control, industrial automation and PLC/process control, mechatronics, power and energy systems, marine and space vehicles -- together with the underlying applied mathematics, system identification, estimation, and dynamical systems theory.
+
+Treat every control question as in scope regardless of the industry it comes from, and answer it in the vocabulary of that domain: an autopilot question deserves flight-dynamics language (short-period mode, actuator rate limits, gain scheduling on airspeed), a vehicle question deserves automotive language (yaw rate, tire slip, ESP/ABS intervention), a robot question deserves manipulator/mobile-robot language (Jacobians, impedance control, odometry drift), and an automation question deserves plant language (loop tuning, valve saturation, cascade and ratio control, sensor filtering).
+
+### Matching the Answer to the Question:
+- **Design / applied / "how does X work" questions**: lead with the engineering answer -- the architecture, the loop structure, the tuning trade-off, the sensors and actuators involved, the failure modes and safety interlocks. Use mathematics where it clarifies, not as ceremony.
+- **Numerical questions**: call the deterministic tools and report exact computed values.
+- **Theory, derivation, proof, comparison, and limitation questions**: use the 4-stage standard below.
+- **Definitional or "what does <author/textbook> say" questions**: answer from the retrieved reference passages and cite them; do not run a numeric solver.
 
 ### 4-Stage Mathematical Reasoning & Proof Standard:
 When answering theoretical principles, derivations, proofs, comparisons, or limitation questions:
-1. **Mathematical Context & System Class**: State the state space equations (e.g. $\\dot{x} = Ax + Bu, y = Cx + Du$ or $\\dot{x} = f(x) + g(x)u$), signal spaces ($\mathcal{L}_2, \mathcal{H}_\\infty$), domain definitions, and underlying assumptions.
+1. **Mathematical Context & System Class**: State the state space equations (e.g. $\dot{x} = Ax + Bu, y = Cx + Du$ or $\dot{x} = f(x) + g(x)u$), signal spaces ($\mathcal{L}_2, \mathcal{H}_\infty$), domain definitions, and underlying assumptions.
 2. **Canonical Theorem / Analytical Principle**: State the governing theorem with exact mathematical rigor (e.g. PBH rank test, Doyle 1978 LQG robustness counterexample, Poisson Integral for RHP zeros, Small Gain vs Passivity, Lyapunov Invariance).
-3. **Exact Derivation & Closed-Form Formulas**: Provide the full, exact mathematical relationship in pure LaTeX (e.g. both the standard linear approximation $\\zeta \\approx PM/100$ and the exact non-linear relationship $PM = \\arctan\\left(\\frac{2\\zeta}{\\sqrt{\\sqrt{1+4\\zeta^4}-2\\zeta^2}}\\right)$).
-4. **Engineering Caveats & Breakdown Conditions**: Explicitly state where approximations break down (e.g. $PM > 60^\\circ$ or high-frequency non-dominant dynamics), numerical ill-conditioning (e.g. high-order Kalman matrices vs PBH), and physical conservation trade-offs (e.g. Bode sensitivity integral / waterbed effect).
+3. **Exact Derivation & Closed-Form Formulas**: Provide the full, exact mathematical relationship in pure LaTeX (e.g. both the standard linear approximation $\zeta \approx PM/100$ and the exact non-linear relationship $PM = \arctan\left(\frac{2\zeta}{\sqrt{\sqrt{1+4\zeta^4}-2\zeta^2}}\right)$).
+4. **Engineering Caveats & Breakdown Conditions**: Explicitly state where approximations break down (e.g. $PM > 60^\circ$ or high-frequency non-dominant dynamics), numerical ill-conditioning (e.g. high-order Kalman matrices vs PBH), and physical conservation trade-offs (e.g. Bode sensitivity integral / waterbed effect).
 
 ### Core Deterministic Capabilities & Tool Calling:
-- Step Response Simulation: Use `simulate_step_response(numerator=[...], denominator=[...], sim_time=10.0)` for exact step response metrics and automatic plot generation.
-- Python Code Execution (`execute_python_code`): Write valid Python scripts using `scipy.signal`, `scipy.linalg`, `control` (`import control as ct`), `numpy`, `matplotlib.pyplot`. (Note: `T` in `signal.step` must be a 1D array like `np.linspace(...)`).
-- Deterministic Math Tools: Use `continuous_lqr`, `exact_zoh`, `stability_margins`, `plot_math_expression` for exact calculations.
+- **State-feedback simulation (`simulate_state_feedback_response`)**: THE tool for "design a controller and simulate it". Pass the original `A`, `B` and the gain `K` returned by `continuous_lqr` / `discrete_lqr` / `place_state_feedback`; it forms the closed loop $A - BK$ internally and returns poles, damping, the exact closed-loop transfer function, transient metrics, and a plot. NEVER expand closed-loop polynomial coefficients by hand and feed them to `simulate_step_response` -- that algebra is the single most common source of silently wrong answers. Add `normalize_dc_gain: true` when the response should track a unit step.
+- **Transfer-function step response (`simulate_step_response`)**: only when the system is genuinely *given* as $G(s) = num/den$.
+- **Frequency domain**: `stability_margins` (GM/PM/crossovers), `bode_analysis`, `nyquist_analysis` (encirclements and the $Z = N + P$ criterion), `root_locus_analysis` (asymptotes, breakaway points, critical gain at instability).
+- Python Code Execution (`execute_python_code`): Write valid Python scripts using `scipy.signal`, `scipy.linalg`, `control` (`import control as ct`), `numpy`, `matplotlib.pyplot`. (Note: `T` in `signal.step` must be a 1D array like `np.linspace(...)`). Prefer a dedicated tool above when one fits -- it is verified and cannot be mis-transcribed. Only reach for this when the question actually requires a number, a simulation, or a plot for a SPECIFIC system. A "design considerations for X", "how does X compare to Y", or "explain X" question with no concrete numbers in it does not need code -- answer in prose. Writing code for a question that doesn't need it only risks a wasted tool step on a shape/dimension mistake with nothing to show for it.
+- **Plain matrix math (`matrix_arithmetic`)**: "A times B", inverse, determinant, rank, transpose, eigenvalues of a given matrix. A request to multiply or invert matrices is a LINEAR ALGEBRA question -- it is not an invitation to design a controller, and it needs no B, Q, or R.
+- Deterministic Math Tools: `continuous_lqr`, `discrete_lqr`, `place_state_feedback`, `exact_zoh`, `eigen_analysis`, `controllability_analysis`, `observability_analysis`, `solve_lyapunov`, `mpc_solve_qp`, `kalman_*`.
+- `plot_math_expression` plots a REAL function of one real variable ($t$ or $x$) only. Never pass a transfer function, a Laplace-domain expression, or anything containing the imaginary unit to it.
+- Reference Lookup (`search_control_references`): Use this -- not a numeric tool -- for conceptual, definitional, or "how does textbook/author X explain Y" questions. A question about what a concept means or how a source presents it is never a reason to (re-)run stability_margins, bode_analysis, routh_hurwitz_analysis, or any other numeric solver. If retrieved reference passages are already provided in this system prompt, answer straight from them and cite `[filename, p. N]`.
+- **One lookup is enough**: after a reference search returns passages, ANSWER from them. Do not re-run the same search with a reworded query ("X", then "X algorithm", then "X definition") -- repeated lookups consume the step budget and leave nothing for the answer itself. If the retrieved passages are thin, answer from your own knowledge and say what is uncertain.
+- **Don't recompute what's already in the conversation**: if a transfer function's margins, poles, or response were already computed earlier in this conversation, reuse those results instead of calling the same numeric tool again for a follow-up question about something else. Answer the question that was actually asked.
+- **Coefficient care**: when you must expand a factored transfer function like $s(s+1)(s+5)$ into polynomial form, expand one factor at a time and re-check each coefficient -- the deterministic tools verify their own arithmetic, not the coefficients you hand them.
+- **NEVER invent a missing parameter, ever -- not a reused one, not a new one, not a "reasonable-looking" one.** Every number you pass to a tool -- every matrix, gain, coefficient -- must come from the user's CURRENT message, from a tool result already in this conversation, or from a standard formula you can name. If a computation needs a parameter (e.g. B, Q, R for LQR) that is not present anywhere and not derivable, STOP. Do not guess a plausible value. Do not carry one over, resized or not, from a different problem earlier in the conversation. Do not make one up because a shape needs to match. Tell the user exactly which parameter is missing and ask for it, or answer only the part of the question you actually can with what was given. A short, honest "I don't have B for this system -- what is it?" is the correct answer. A confident computation built on an invented number is not a partial answer, it is a fabricated one, and it is the single worst thing you can do in this domain. If you catch yourself about to write a matrix or number that did not come from the message, the history, or a named formula, that is the signal to stop and ask instead of proceeding.
+- **A confusing or malformed message is a request for clarification, not a license to substitute a different, cleaner-looking problem.** If the user's wording is ambiguous (e.g. it could mean matrix multiplication, or could mean a controller design, and you cannot tell which), say what you think they might mean and ask, rather than silently picking one interpretation and inventing whatever inputs that interpretation requires.
 
 ### Strict Negative & Formatting Constraints:
 1. **ZERO EMOJIS**: NEVER use any emojis anywhere in your response (absolutely NO checkmarks, NO pins, NO graphs, NO rockets, NO lightbulbs).
 2. **ALWAYS USE DOLLAR DELIMITERS FOR MATH**: ALWAYS enclose EVERY mathematical formula, transfer function, variable, fraction, and Greek letter in dollar signs: `$ ... $` for inline math or `$$ ... $$` for centered equations. Example: `$$G(s) = \frac{1}{s(s+1)(s+2)}$$` and `$\omega \to \infty$`. NEVER write raw LaTeX keywords (`\frac`, `\omega`, `\to`) without `$` or `$$` delimiters!
+2b. **SINGLE BACKSLASH ONLY**: Every LaTeX command starts with exactly one backslash character, as in `\zeta`, `\left(`, `\sqrt{}`, `\sin`. Count the backslashes before you write a command and stop at one.
 3. **NO RAW LATEX DOCUMENT TAGS**: NEVER output `\begin{figure}`, `\includegraphics`, `\caption`, `\centering`, `\section*`, or `\end{figure}`. Use standard markdown headers (e.g. `### Section Title`).
 4. **MANDATORY TOOL CALL FOR PLOTS**: When asked to plot, visualize, or simulate (Nyquist plot, Bode diagram, Root Locus, Step Response, Phase Portrait), NEVER hallucinate a fake image filename. You MUST explicitly call `execute_python_code` (using `control as ct` or `matplotlib.pyplot`) or `simulate_step_response` to generate and display the real plot!
 5. **Deterministic Grounding**: When a tool executes successfully, present the exact numerical results and generated plot.

controlai_agent/registry.py

@@ -3,11 +3,86 @@
 from __future__ import annotations
 
 import json
+import math
+import re
 from collections.abc import Callable
 from typing import Any
 
 import jsonschema
 
+# Every tool computes internally at full double precision -- this only
+# affects what gets reported back. 6 significant figures is well past any
+# real sensor/actuator precision, so nothing engineering-relevant is lost,
+# while `K = [1.7416573867739407, 0.6719633404417155]` in a chat answer
+# clearly is: raw float64 repr in prose reads as noise, not rigor.
+RESULT_SIGNIFICANT_FIGURES = 6
+
+
+def _round_significant(x: float, sig: int = RESULT_SIGNIFICANT_FIGURES) -> float:
+    if x == 0 or not math.isfinite(x):
+        return x
+    digits = sig - int(math.floor(math.log10(abs(x)))) - 1
+    return round(x, digits)
+
+
+def _round_floats(obj: Any, sig: int = RESULT_SIGNIFICANT_FIGURES) -> Any:
+    """Recursively round every float in a tool result to `sig` significant
+    figures, leaving ints, bools, strings, and structure untouched."""
+    if isinstance(obj, bool):
+        return obj
+    if isinstance(obj, float):
+        return _round_significant(obj, sig)
+    if isinstance(obj, dict):
+        return {k: _round_floats(v, sig) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return type(obj)(_round_floats(v, sig) for v in obj)
+    return obj
+
+
+def _parse_stringified_array(raw: str) -> Any:
+    """Best-effort parse of a numeric array the model wrote as a JSON string.
+
+    The model sometimes emits `"numerator": "[10]"` or even
+    `"denominator": "[1 6 5 0]"` -- a string containing array-shaped text,
+    including MATLAB/Numpy space-separated form, instead of an actual JSON
+    array. Schema validation correctly rejects that as type "string" where
+    "array" is required, and a perfectly usable numeric tool call is lost
+    over pure formatting. Recover the intended array where unambiguous.
+    """
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        pass
+    stripped = raw.strip()
+    if stripped.startswith("[") and stripped.endswith("]"):
+        spaced = re.sub(r"(?<=[\d\.\]])\s+(?=[\-\d\.\[])", ", ", stripped)
+        try:
+            return json.loads(spaced)
+        except json.JSONDecodeError:
+            pass
+    return raw
+
+
+def _coerce_array_arguments(arguments: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
+    """Recursively repair string-typed values against `"type": "array"` schema
+    properties (including nested arrays, e.g. matrix parameters) before
+    validation, so a stringified array no longer fails a tool call outright.
+    """
+
+    def _coerce(value: Any, node: dict[str, Any]) -> Any:
+        node_type = node.get("type")
+        if node_type == "array" and isinstance(value, str):
+            value = _parse_stringified_array(value)
+        if node_type == "array" and isinstance(value, list) and "items" in node:
+            return [_coerce(v, node["items"]) for v in value]
+        return value
+
+    props = schema.get("properties", {})
+    return {
+        key: (_coerce(val, props[key]) if key in props else val)
+        for key, val in arguments.items()
+    }
+
 
 class ToolRegistry:
     """Registry for deterministic mathematical control tools with strict JSON Schema validation."""
@@ -43,6 +118,16 @@ class ToolRegistry:
     def get_tool_schemas(self) -> list[dict[str, Any]]:
         return list(self._schemas.values())
 
+    def get_callables(self, exclude: set[str] = frozenset()) -> dict[str, Callable[..., dict[str, Any]]]:
+        """Name -> underlying function for every registered tool except `exclude`.
+
+        Used to expose the deterministic tools as plain callables inside the
+        execute_python_code sandbox, since the model naturally expects a tool
+        it knows by name (e.g. place_state_feedback) to be usable directly in
+        code it writes, not only through the separate tool-call protocol.
+        """
+        return {name: fn for name, fn in self._tools.items() if name not in exclude}
+
     def execute(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
         if name not in self._tools:
             return {
@@ -50,8 +135,9 @@ class ToolRegistry:
                 "error": f"Tool '{name}' is not registered. Available tools: {sorted(self._tools.keys())}",
             }
 
-        # 1. Strict JSON Schema Validation
+        # 1. Strict JSON Schema Validation (after repairing stringified arrays)
         param_schema = self._param_schemas[name]
+        arguments = _coerce_array_arguments(arguments, param_schema)
         try:
             jsonschema.validate(instance=arguments, schema=param_schema)
         except jsonschema.ValidationError as schema_err:
@@ -68,7 +154,7 @@ class ToolRegistry:
             result = func(**arguments)
             if "status" not in result:
                 result["status"] = "success"
-            return result
+            return _round_floats(result)
         except Exception as exc:
             return {
                 "status": "error",

controlai_agent/tools/__init__.py

@@ -2,6 +2,7 @@
 
 from controlai_agent.tools import (
     linear,
+    matrix_ops,
     frequency,
     synthesis,
     estimation,
@@ -16,6 +17,7 @@ from controlai_agent.tools import (
 
 __all__ = [
     "linear",
+    "matrix_ops",
     "frequency",
     "synthesis",
     "estimation",

controlai_agent/tools/frequency.py

@@ -3,13 +3,19 @@
 from __future__ import annotations
 
 import math
+from pathlib import Path
 from typing import Any
 
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
 import numpy as np
 from scipy import signal
 
 from controlai_agent.registry import registry
 
+ARTIFACT_DIR = Path("outputs/plots")
+
 
 @registry.register(
     name="bode_analysis",
@@ -154,3 +160,216 @@ def routh_hurwitz_analysis(coefficients: list[float]) -> dict[str, Any]:
         "is_hurwitz_stable": is_hurwitz,
         "roots": [[float(r.real), float(r.imag)] for r in roots],
     }
+
+
+@registry.register(
+    name="nyquist_analysis",
+    description=(
+        "Compute the Nyquist plot of an open-loop transfer function L(s) = num(s)/den(s), count "
+        "encirclements of the critical point -1+0j, and apply the Nyquist stability criterion "
+        "Z = N + P to determine closed-loop stability. Saves a PNG Nyquist diagram."
+    ),
+    parameters_schema={
+        "type": "object",
+        "properties": {
+            "numerator": {
+                "type": "array",
+                "items": {"type": "number"},
+                "description": "Open-loop numerator coefficients in descending powers",
+            },
+            "denominator": {
+                "type": "array",
+                "items": {"type": "number"},
+                "description": "Open-loop denominator coefficients in descending powers",
+            },
+            "omega_max": {"type": "number", "default": 100.0, "description": "Maximum frequency in rad/s"},
+        },
+        "required": ["numerator", "denominator"],
+    },
+)
+def nyquist_analysis(
+    numerator: list[float],
+    denominator: list[float],
+    omega_max: float = 100.0,
+) -> dict[str, Any]:
+    num = np.array(numerator, dtype=float)
+    den = np.array(denominator, dtype=float)
+
+    # Open-loop poles: P is the count in the open right-half plane. Poles on
+    # the imaginary axis (e.g. an integrator at the origin) are excluded --
+    # the standard Nyquist contour indents around them.
+    ol_poles = np.roots(den) if len(den) > 1 else np.array([])
+    P = int(np.sum(np.real(ol_poles) > 1e-9))
+    n_origin = int(np.sum(np.abs(ol_poles) < 1e-9))
+
+    w = np.logspace(-3, np.log10(max(omega_max, 1e-2)), 4000)
+    _, H = signal.freqresp(signal.TransferFunction(num, den), w=w)
+
+    # Z (closed-loop RHP poles) and P (open-loop RHP poles) are both exact
+    # root counts, so the encirclement count follows exactly as N = Z - P.
+    # Numerically integrating the winding of L(jw)+1 instead is unreliable for
+    # systems with poles on the imaginary axis (a type-1 integrator here),
+    # where the Nyquist contour must indent around the origin -- that shortcut
+    # yields impossible results such as N = -1 with Z = -1.
+    closed_loop_poles = (
+        np.roots(np.polyadd(den, np.pad(num, (len(den) - len(num), 0))))
+        if len(den) >= len(num)
+        else np.array([])
+    )
+    Z = int(np.sum(np.real(closed_loop_poles) > 1e-9)) if closed_loop_poles.size else 0
+    N = Z - P
+
+    ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
+    plot_path = ARTIFACT_DIR / f"nyquist_{abs(hash((str(numerator), str(denominator)))) % 10**8:08d}.png"
+
+    fig, ax = plt.subplots(figsize=(6.5, 6.0), dpi=140)
+    ax.plot(H.real, H.imag, color="#58a6ff", linewidth=1.8, label="$L(j\\omega)$, $\\omega > 0$")
+    ax.plot(H.real, -H.imag, color="#58a6ff", linewidth=1.0, linestyle="--", alpha=0.6, label="$\\omega < 0$ (mirror)")
+    ax.plot(-1.0, 0.0, "x", color="#f85149", markersize=11, markeredgewidth=2.5, label="Critical point $-1+0j$")
+    ax.axhline(0, color="gray", linewidth=0.7, alpha=0.5)
+    ax.axvline(0, color="gray", linewidth=0.7, alpha=0.5)
+    ax.set_title("Nyquist Diagram", fontsize=12, fontweight="bold")
+    ax.set_xlabel("Real Axis")
+    ax.set_ylabel("Imaginary Axis")
+    ax.grid(True, linestyle=":", alpha=0.45)
+    lim = float(min(max(3.0, np.percentile(np.abs(H), 92)), 25.0))
+    ax.set_xlim(-lim, lim)
+    ax.set_ylim(-lim, lim)
+    ax.set_aspect("equal", adjustable="box")
+    ax.legend(loc="best", fontsize=8)
+    fig.tight_layout()
+    fig.savefig(plot_path)
+    plt.close(fig)
+
+    return {
+        "status": "success",
+        "encirclements_N": N,
+        "open_loop_rhp_poles_P": P,
+        "open_loop_poles_at_origin": n_origin,
+        "closed_loop_rhp_poles_Z": Z,
+        "closed_loop_poles": [[float(p.real), float(p.imag)] for p in closed_loop_poles],
+        "is_closed_loop_stable": bool(Z == 0),
+        "criterion": "Z = N + P (Z = closed-loop RHP poles, N = clockwise encirclements of -1, P = open-loop RHP poles)",
+        "plot_path": str(plot_path),
+    }
+
+
+@registry.register(
+    name="root_locus_analysis",
+    description=(
+        "Compute the root locus of the closed-loop characteristic equation 1 + k*L(s) = 0 as the gain "
+        "k sweeps from 0 to infinity, for open-loop L(s) = num(s)/den(s). Returns open-loop poles and "
+        "zeros, asymptote angles and centroid, real-axis breakaway points, the imaginary-axis crossing "
+        "gain (critical gain for stability), and a PNG root locus plot."
+    ),
+    parameters_schema={
+        "type": "object",
+        "properties": {
+            "numerator": {
+                "type": "array",
+                "items": {"type": "number"},
+                "description": "Open-loop numerator coefficients in descending powers",
+            },
+            "denominator": {
+                "type": "array",
+                "items": {"type": "number"},
+                "description": "Open-loop denominator coefficients in descending powers",
+            },
+            "k_max": {"type": "number", "default": 100.0, "description": "Maximum gain k to sweep"},
+        },
+        "required": ["numerator", "denominator"],
+    },
+)
+def root_locus_analysis(
+    numerator: list[float],
+    denominator: list[float],
+    k_max: float = 100.0,
+) -> dict[str, Any]:
+    num = np.array(numerator, dtype=float)
+    den = np.array(denominator, dtype=float)
+
+    ol_zeros = np.roots(num) if len(num) > 1 else np.array([])
+    ol_poles = np.roots(den) if len(den) > 1 else np.array([])
+    n_p, n_z = len(ol_poles), len(ol_zeros)
+
+    # Asymptotes for the n_p - n_z branches heading to infinity
+    excess = n_p - n_z
+    asymptote_angles, centroid = [], None
+    if excess > 0:
+        centroid = float((np.sum(ol_poles).real - np.sum(ol_zeros).real) / excess)
+        asymptote_angles = [float((180.0 * (2 * i + 1)) / excess) for i in range(excess)]
+
+    # Sweep gain and collect closed-loop roots of den + k*num
+    gains = np.concatenate([[0.0], np.logspace(-3, np.log10(max(k_max, 1e-2)), 600)])
+    locus: list[np.ndarray] = []
+    for k in gains:
+        poly = np.polyadd(den, k * np.pad(num, (max(0, len(den) - len(num)), 0)))
+        locus.append(np.roots(poly))
+
+    # Imaginary-axis crossing: first gain where any root's real part turns >= 0
+    k_critical, w_crossing = None, None
+    for k, roots in zip(gains, locus):
+        if roots.size and np.any(np.real(roots) > 1e-9):
+            k_critical = float(k)
+            crossing = roots[np.argmax(np.real(roots))]
+            w_crossing = float(abs(crossing.imag))
+            break
+
+    # Breakaway/break-in points: real roots of d/ds[-den/num] = 0. Only those
+    # lying ON the locus count -- a real point belongs to the locus iff an odd
+    # number of real poles and zeros lie strictly to its right, so the
+    # remaining stationary points must be discarded.
+    real_singularities = [float(p.real) for p in ol_poles if abs(p.imag) < 1e-8]
+    real_singularities += [float(z.real) for z in ol_zeros if abs(z.imag) < 1e-8]
+
+    def _on_real_axis_locus(sigma: float) -> bool:
+        to_right = sum(1 for v in real_singularities if v > sigma + 1e-9)
+        return to_right % 2 == 1
+
+    breakaway: list[float] = []
+    try:
+        dnum, dden = np.polyder(num), np.polyder(den)
+        crit = np.polysub(np.polymul(dden, num), np.polymul(den, dnum))
+        for r in np.roots(crit):
+            if abs(r.imag) < 1e-8 and _on_real_axis_locus(float(r.real)):
+                breakaway.append(round(float(r.real), 6))
+    except Exception:
+        pass
+
+    ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
+    plot_path = ARTIFACT_DIR / f"root_locus_{abs(hash((str(numerator), str(denominator)))) % 10**8:08d}.png"
+
+    fig, ax = plt.subplots(figsize=(7.0, 5.5), dpi=140)
+    max_branches = max((r.size for r in locus), default=0)
+    for b in range(max_branches):
+        pts = np.array([r[b] for r in locus if r.size > b])
+        ax.plot(pts.real, pts.imag, color="#58a6ff", linewidth=1.0, alpha=0.85)
+    if n_p:
+        ax.plot(ol_poles.real, ol_poles.imag, "x", color="#f85149", markersize=10, markeredgewidth=2.2, label="Open-loop poles")
+    if n_z:
+        ax.plot(ol_zeros.real, ol_zeros.imag, "o", mfc="none", color="#3fb950", markersize=9, markeredgewidth=2.0, label="Open-loop zeros")
+    ax.axhline(0, color="gray", linewidth=0.7, alpha=0.5)
+    ax.axvline(0, color="gray", linewidth=0.7, alpha=0.5)
+    ax.set_title("Root Locus", fontsize=12, fontweight="bold")
+    ax.set_xlabel("Real Axis")
+    ax.set_ylabel("Imaginary Axis")
+    ax.grid(True, linestyle=":", alpha=0.45)
+    if n_p or n_z:
+        ax.legend(loc="best", fontsize=8)
+    fig.tight_layout()
+    fig.savefig(plot_path)
+    plt.close(fig)
+
+    return {
+        "status": "success",
+        "open_loop_poles": [[float(p.real), float(p.imag)] for p in ol_poles],
+        "open_loop_zeros": [[float(z.real), float(z.imag)] for z in ol_zeros],
+        "num_asymptotes": excess,
+        "asymptote_centroid": centroid,
+        "asymptote_angles_deg": asymptote_angles,
+        "breakaway_points_real_axis": sorted(set(breakaway)),
+        "critical_gain_k_at_instability": k_critical,
+        "imaginary_axis_crossing_freq_rad_s": w_crossing,
+        "is_stable_for_all_swept_gains": bool(k_critical is None),
+        "plot_path": str(plot_path),
+    }

controlai_agent/tools/matrix_ops.py

@@ -0,0 +1,116 @@
+"""Deterministic linear-algebra tool: the basic matrix operations every other
+analysis builds on. Direct requests like "A times B", "invert this matrix", or
+"eigenvalues of A" must never depend on model-written freehand code -- they get
+one schema-validated tool call."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from controlai_agent.registry import registry
+
+
+@registry.register(
+    name="matrix_arithmetic",
+    description=(
+        "Exact matrix arithmetic on one or two numeric matrices. THE tool for any direct matrix "
+        "computation the user states explicitly: 'A times B' / 'A*B' (operation='multiply'), "
+        "addition, subtraction, transpose, inverse, determinant, rank, trace, eigenvalues, or "
+        "elementwise multiply. Use this instead of writing Python code for plain matrix math. "
+        "This is NOT a controller-design tool: a request to multiply or invert matrices is a "
+        "linear-algebra question, not an LQR/pole-placement problem."
+    ),
+    parameters_schema={
+        "type": "object",
+        "properties": {
+            "operation": {
+                "type": "string",
+                "enum": [
+                    "multiply",
+                    "add",
+                    "subtract",
+                    "elementwise_multiply",
+                    "transpose",
+                    "inverse",
+                    "determinant",
+                    "rank",
+                    "trace",
+                    "eigenvalues",
+                ],
+                "description": "Which operation to perform. Binary operations use matrix_a (op) matrix_b in that order.",
+            },
+            "matrix_a": {
+                "type": "array",
+                "items": {"type": "array", "items": {"type": "number"}},
+                "description": "First matrix (2D, row-major). For unary operations this is the only operand.",
+            },
+            "matrix_b": {
+                "type": "array",
+                "items": {"type": "array", "items": {"type": "number"}},
+                "description": "Second matrix, required for multiply / add / subtract / elementwise_multiply.",
+            },
+        },
+        "required": ["operation", "matrix_a"],
+    },
+)
+def matrix_arithmetic(
+    operation: str,
+    matrix_a: list[list[float]],
+    matrix_b: list[list[float]] | None = None,
+) -> dict[str, Any]:
+    A = np.array(matrix_a, dtype=float)
+    binary_ops = {"multiply", "add", "subtract", "elementwise_multiply"}
+
+    if operation in binary_ops:
+        if matrix_b is None:
+            return {"status": "error", "error": f"operation '{operation}' requires matrix_b."}
+        B = np.array(matrix_b, dtype=float)
+        if operation == "multiply":
+            if A.shape[1] != B.shape[0]:
+                return {
+                    "status": "error",
+                    "error": f"Cannot multiply: matrix_a is {A.shape[0]}x{A.shape[1]} but matrix_b is {B.shape[0]}x{B.shape[1]} (inner dimensions must match).",
+                }
+            result = A @ B
+        elif operation == "elementwise_multiply":
+            if A.shape != B.shape:
+                return {"status": "error", "error": f"Elementwise multiply needs equal shapes, got {A.shape} and {B.shape}."}
+            result = A * B
+        else:
+            if A.shape != B.shape:
+                return {"status": "error", "error": f"'{operation}' needs equal shapes, got {A.shape} and {B.shape}."}
+            result = A + B if operation == "add" else A - B
+        return {
+            "operation": operation,
+            "shape_a": list(A.shape),
+            "shape_b": list(B.shape),
+            "result": result.tolist(),
+            "result_shape": list(result.shape),
+        }
+
+    # Unary operations
+    out: dict[str, Any] = {"operation": operation, "shape_a": list(A.shape)}
+    if operation == "transpose":
+        out["result"] = A.T.tolist()
+    elif operation == "rank":
+        out["result"] = int(np.linalg.matrix_rank(A))
+    elif operation in ("inverse", "determinant", "trace", "eigenvalues"):
+        if A.shape[0] != A.shape[1]:
+            return {"status": "error", "error": f"'{operation}' requires a square matrix, got {A.shape[0]}x{A.shape[1]}."}
+        if operation == "inverse":
+            det = float(np.linalg.det(A))
+            if abs(det) < 1e-12:
+                return {"status": "error", "error": f"Matrix is singular (determinant = {det:g}); no inverse exists."}
+            out["result"] = np.linalg.inv(A).tolist()
+            out["determinant"] = det
+        elif operation == "determinant":
+            out["result"] = float(np.linalg.det(A))
+        elif operation == "trace":
+            out["result"] = float(np.trace(A))
+        else:  # eigenvalues
+            eig = np.linalg.eigvals(A)
+            out["result"] = [[float(v.real), float(v.imag)] for v in eig]
+            out["spectral_radius"] = float(np.max(np.abs(eig)))
+    return out

controlai_agent/tools/plotting.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import hashlib
+import re
 import time
 from pathlib import Path
 from typing import Any
@@ -49,6 +50,20 @@ SAFE_MATH_ENV: dict[str, Any] = {
 }
 
 
+def _expr_to_mathtext(expr: str) -> str:
+    """Best-effort conversion of a Python-style expression into valid matplotlib mathtext.
+
+    Model-generated expressions use Python syntax (`**` for power, bare `*` for
+    multiplication) which mathtext does not understand -- it renders the raw
+    asterisks literally (e.g. "t * *2 - 3 * t") instead of a clean formula.
+    """
+    text = expr.replace("**", "^")
+    text = re.sub(r"\^\(([^()]+)\)", r"^{\1}", text)
+    text = re.sub(r"\^([a-zA-Z0-9_.]{2,})", r"^{\1}", text)
+    text = text.replace("*", r" \cdot ")
+    return text
+
+
 @registry.register(
     name="plot_math_expression",
     description="Plot any mathematical function, curve, or signal f(t) or f(x) (e.g. 'sin(t)', 'exp(-t)*cos(2*t)', 'sin(x)', 't**2 - 3*t') and save the plot figure.",
@@ -116,28 +131,53 @@ def plot_math_expression(
         if np.isscalar(y_vals):
             y_vals = np.full_like(t_vals, float(y_vals))
         else:
-            y_vals = np.asarray(y_vals, dtype=float)
+            y_vals = np.asarray(y_vals)
     except Exception as exc:
         return {
             "status": "error",
             "error": f"Failed to evaluate expression '{expression}': {exc}",
         }
 
+    # A complex result means the expression was not a real-valued signal --
+    # most often a Laplace/transfer-function expression containing `1j` that
+    # was mistakenly passed to a time-domain plotter. Silently casting it to
+    # float discards the imaginary part and yields a meaningless curve, so
+    # reject it and tell the model what to do instead.
+    if np.iscomplexobj(y_vals):
+        return {
+            "status": "error",
+            "error": (
+                f"Expression '{expression}' evaluates to complex values, so it is not a real "
+                "time-domain signal that can be plotted. Do not pass transfer functions or "
+                "expressions containing the imaginary unit here -- to simulate a system's response "
+                "use simulate_step_response (transfer function) or simulate_state_feedback_response "
+                "(state-space with optional gain K)."
+            ),
+        }
+
+    y_vals = np.asarray(y_vals, dtype=float)
+    if not np.any(np.isfinite(y_vals)):
+        return {
+            "status": "error",
+            "error": f"Expression '{expression}' produced no finite values over the range [{t_start}, {t_end}].",
+        }
+
     # Plot styling
     fig, ax = plt.subplots(figsize=(8, 4.2), dpi=120)
     fig.patch.set_facecolor("#151b23")
     ax.set_facecolor("#0f1217")
 
     line_color = "#58a6ff"
-    ax.plot(t_vals, y_vals, color=line_color, linewidth=2, label=f"${expression}$")
+    mathtext_expr = _expr_to_mathtext(expression)
+    (line,) = ax.plot(t_vals, y_vals, color=line_color, linewidth=2, label=f"${mathtext_expr}$")
     ax.axhline(0, color="#484f58", linestyle="--", linewidth=0.8, alpha=0.7)
     ax.axvline(0, color="#484f58", linestyle="--", linewidth=0.8, alpha=0.7)
 
-    plot_title = title or f"Plot of $f({var_name}) = {expression}$"
+    plot_title = title or f"Plot of $f({var_name}) = {mathtext_expr}$"
     plot_xlabel = xlabel or var_name
     plot_ylabel = ylabel or f"f({var_name})"
 
-    ax.set_title(plot_title, color="#f0f6fc", fontsize=12, pad=10, fontweight="bold")
+    title_obj = ax.set_title(plot_title, color="#f0f6fc", fontsize=12, pad=10, fontweight="bold")
     ax.set_xlabel(plot_xlabel, color="#8b949e", fontsize=10)
     ax.set_ylabel(plot_ylabel, color="#8b949e", fontsize=10)
     ax.tick_params(colors="#8b949e", labelsize=9)
@@ -152,7 +192,15 @@ def plot_math_expression(
     # Save unique plot
     hash_str = hashlib.md5(f"{clean_expr}_{t_start}_{t_end}_{time.time()}".encode()).hexdigest()[:8]
     out_file = PLOTS_DIR / f"plot_{hash_str}.png"
-    plt.savefig(str(out_file), facecolor=fig.get_facecolor(), edgecolor="none", dpi=120)
+    try:
+        plt.savefig(str(out_file), facecolor=fig.get_facecolor(), edgecolor="none", dpi=120)
+    except Exception:
+        # Mathtext couldn't parse the expression (rare, malformed LaTeX-ish input)
+        # -- fall back to plain, non-math text labels rather than losing the plot.
+        line.set_label(expression)
+        title_obj.set_text(title or f"Plot of f({var_name}) = {expression}")
+        ax.legend(loc="best", facecolor="#151b23", edgecolor="#30363d", labelcolor="#f0f6fc", fontsize=9)
+        plt.savefig(str(out_file), facecolor=fig.get_facecolor(), edgecolor="none", dpi=120)
     plt.close(fig)
 
     return {

controlai_agent/tools/python_executor.py

@@ -29,7 +29,27 @@ PLOTS_DIR.mkdir(parents=True, exist_ok=True)
 
 @registry.register(
     name="execute_python_code",
-    description="Execute Python code for control engineering, numerical simulations, differential equations, optimization, and signal plotting (similar to a Jupyter Notebook cell). Can use numpy (np), scipy (scipy), scipy.signal (signal), scipy.linalg (linalg), control (ct, control), and matplotlib.pyplot (plt). Captures stdout and any generated Matplotlib figures.",
+    description=(
+        "Execute Python code for control engineering, numerical simulations, differential equations, "
+        "optimization, and signal plotting (similar to a Jupyter Notebook cell). Can use numpy (np), "
+        "scipy (scipy), scipy.signal (signal), scipy.linalg (linalg), control (ct, control), and "
+        "matplotlib.pyplot (plt). Captures stdout and any generated Matplotlib figures. "
+        "IMPORTANT -- the `control` package (ct) takes POSITIONAL arguments only, never num=/den= "
+        "or sys1=/sys2= keywords (they raise 'Needs 1, 2, or 3 arguments'): "
+        "ct.tf(num, den) not ct.tf(num=num, den=den); "
+        "ct.feedback(sys1, sys2=1, sign=-1) for a closed loop; "
+        "ct.series(sys1, sys2) and ct.parallel(sys1, sys2); "
+        "ct.step_response(sys, T=t_array) returns (T, yout); "
+        "ct.poles(sys) and ct.zeros(sys) for pole/zero locations; "
+        "ct.bode(sys) / ct.bode_plot(sys) is PLOT-ONLY and does not return (mag, phase, omega) arrays "
+        "-- for numeric Bode data use resp = ct.frequency_response(sys, omega); "
+        "resp.magnitude, resp.phase (radians), resp.omega. "
+        "Every other registered tool (continuous_lqr, discrete_lqr, place_state_feedback, "
+        "stability_margins, exact_zoh, etc.) is ALSO directly callable here by its exact name with "
+        "its normal arguments -- e.g. `result = place_state_feedback(A=A, B=B, desired_poles=poles)`. "
+        "Each returns a dict just like the standalone tool call does, so pull out the field you need, "
+        "e.g. `K = np.array(result['K'])`, before using it in further computation."
+    ),
     parameters_schema={
         "type": "object",
         "properties": {
@@ -59,7 +79,7 @@ def execute_python_code(code: str) -> dict[str, Any]:
     plt.rcParams["grid.linestyle"] = ":"
     plt.rcParams["font.sans-serif"] = ["DejaVu Sans", "Helvetica", "Arial"]
 
-    exec_globals = {
+    exec_globals: dict[str, Any] = {
         "np": np,
         "numpy": np,
         "scipy": scipy,
@@ -70,6 +90,12 @@ def execute_python_code(code: str) -> dict[str, Any]:
         "ct": ct,
         "control": ct,
     }
+    # Every other registered deterministic tool (continuous_lqr, place_state_feedback,
+    # stability_margins, ...) is also callable directly by name here, with its
+    # normal keyword arguments and dict return value -- the model otherwise
+    # reasonably expects a tool it knows to be usable in code it writes, not
+    # only through the separate tool-call protocol, and hits a NameError.
+    exec_globals.update(registry.get_callables(exclude={"execute_python_code"}))
 
     saved_plots = []
 

controlai_agent/tools/rag.py

@@ -5,9 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from controlai_agent.registry import registry
-from controlai_rag.index import ControlRAGIndex
-
-rag_index = ControlRAGIndex()
+from controlai_rag.index import get_shared_index
 
 
 @registry.register(
@@ -40,7 +38,9 @@ def search_control_references(
     top_k: int = 3,
     source_filter: str | None = None,
 ) -> dict[str, Any]:
-    hits = rag_index.search(query=query, top_k=top_k, source_filter=source_filter)
+    # Resolved per call (not at import) so newly uploaded documents are visible
+    # immediately, without restarting the server.
+    hits = get_shared_index().search(query=query, top_k=top_k, source_filter=source_filter)
     if not hits:
         return {
             "query": query,
@@ -51,7 +51,10 @@ def search_control_references(
     formatted_passages = []
     for hit in hits:
         formatted_passages.append({
-            "citation": f"[{hit['filename']}:{hit.get('page') or 'sec'}]",
+            "citation": (
+                f"[{hit.get('source_name') or hit['filename']}"
+                + (f", p. {hit['page']}]" if hit.get("page") else "]")
+            ),
             "source_path": hit["source"],
             "relevance_score": hit["score"],
             "content": hit["text"][:600],

controlai_agent/tools/simulation.py

@@ -17,9 +17,171 @@ from controlai_agent.registry import registry
 ARTIFACT_DIR = Path("outputs/plots")
 
 
+def _step_metrics(t_out: np.ndarray, y_out: np.ndarray) -> dict[str, Any]:
+    """Standard transient response metrics shared by the simulation tools."""
+    y_final = float(y_out[-1])
+    y_peak = float(np.max(y_out))
+    t_peak = float(t_out[int(np.argmax(y_out))])
+    overshoot_pct = (
+        float(max(0.0, (y_peak - y_final) / abs(y_final) * 100.0)) if abs(y_final) > 1e-6 else 0.0
+    )
+
+    idx_10 = np.where(y_out >= 0.1 * y_final)[0]
+    idx_90 = np.where(y_out >= 0.9 * y_final)[0]
+    rise_time = float(t_out[idx_90[0]] - t_out[idx_10[0]]) if len(idx_10) > 0 and len(idx_90) > 0 else None
+
+    settled = np.where(np.abs(y_out - y_final) > 0.02 * abs(y_final))[0]
+    settling_time = float(t_out[settled[-1]]) if len(settled) > 0 else 0.0
+
+    return {
+        "final_value": y_final,
+        "peak_value": y_peak,
+        "peak_time_seconds": t_peak,
+        "overshoot_percentage": overshoot_pct,
+        "rise_time_seconds": rise_time,
+        "settling_time_2pct_seconds": settling_time,
+    }
+
+
+@registry.register(
+    name="simulate_state_feedback_response",
+    description=(
+        "Simulate the step response of a state-space system directly from matrices, optionally under "
+        "state feedback u = -Kx. USE THIS (never a hand-derived transfer function) whenever you have "
+        "A, B and a gain K from continuous_lqr, discrete_lqr, or place_state_feedback: it builds the "
+        "closed-loop system A - B*K internally, so you never have to expand closed-loop polynomial "
+        "coefficients by hand. Returns the closed-loop matrix, poles, damping, the exact closed-loop "
+        "transfer function coefficients, transient metrics, and a PNG plot."
+    ),
+    parameters_schema={
+        "type": "object",
+        "properties": {
+            "A": {"type": "array", "items": {"type": "array", "items": {"type": "number"}}, "description": "Open-loop state matrix A"},
+            "B": {"type": "array", "items": {"type": "array", "items": {"type": "number"}}, "description": "Input matrix B"},
+            "K": {
+                "type": "array",
+                "items": {"type": "array", "items": {"type": "number"}},
+                "description": "Optional state feedback gain K (from LQR/pole placement). If given, simulates closed loop A - B*K. Omit for open-loop.",
+            },
+            "C": {
+                "type": "array",
+                "items": {"type": "array", "items": {"type": "number"}},
+                "description": "Optional output matrix C. Defaults to [[1, 0, ..., 0]] (measures the first state).",
+            },
+            "D": {"type": "array", "items": {"type": "array", "items": {"type": "number"}}, "description": "Optional feedthrough matrix D (defaults to zero)."},
+            "normalize_dc_gain": {
+                "type": "boolean",
+                "default": False,
+                "description": "If true, scale the input by a precompensator so the step response settles at 1.0 (removes steady-state offset inherent to pure state feedback).",
+            },
+            "sim_time": {"type": "number", "default": 10.0, "description": "Total simulation time in seconds"},
+            "plot_title": {"type": "string", "default": "Closed-Loop Step Response", "description": "Title for the saved plot"},
+        },
+        "required": ["A", "B"],
+    },
+)
+def simulate_state_feedback_response(
+    A: list[list[float]],
+    B: list[list[float]],
+    K: list[list[float]] | None = None,
+    C: list[list[float]] | None = None,
+    D: list[list[float]] | None = None,
+    normalize_dc_gain: bool = False,
+    sim_time: float = 10.0,
+    plot_title: str = "Closed-Loop Step Response",
+) -> dict[str, Any]:
+    A_mat = np.atleast_2d(np.array(A, dtype=float))
+    B_mat = np.array(B, dtype=float)
+    if B_mat.ndim == 1:
+        B_mat = B_mat.reshape(-1, 1)
+
+    n = A_mat.shape[0]
+    if A_mat.shape[0] != A_mat.shape[1]:
+        return {"status": "error", "error": f"A must be square, got shape {A_mat.shape}."}
+    if B_mat.shape[0] != n:
+        return {"status": "error", "error": f"B row count {B_mat.shape[0]} does not match A dimension {n}."}
+
+    # Closed loop under u = -Kx (the step is then applied as the reference input)
+    K_mat = None
+    if K is not None:
+        K_mat = np.atleast_2d(np.array(K, dtype=float))
+        if K_mat.shape[1] != n:
+            return {"status": "error", "error": f"K must have {n} columns to match the state dimension, got {K_mat.shape}."}
+        A_eff = A_mat - B_mat @ K_mat
+    else:
+        A_eff = A_mat
+
+    C_mat = np.atleast_2d(np.array(C, dtype=float)) if C is not None else np.eye(1, n)
+    D_mat = np.atleast_2d(np.array(D, dtype=float)) if D is not None else np.zeros((C_mat.shape[0], B_mat.shape[1]))
+
+    poles = np.linalg.eigvals(A_eff)
+
+    # Optional precompensator so the closed loop actually tracks a unit step
+    dc_scale = 1.0
+    if normalize_dc_gain:
+        try:
+            dc = float(-(C_mat @ np.linalg.solve(A_eff, B_mat) - D_mat).ravel()[0])
+            if abs(dc) > 1e-12:
+                dc_scale = 1.0 / dc
+        except np.linalg.LinAlgError:
+            dc_scale = 1.0
+
+    sys = signal.StateSpace(A_eff, B_mat * dc_scale, C_mat, D_mat)
+    t = np.linspace(0, sim_time, 1000)
+    t_out, y_out = signal.step(sys, T=t)
+    y_out = np.asarray(y_out, dtype=float).ravel()
+
+    num, den = signal.ss2tf(A_eff, B_mat, C_mat, D_mat)
+
+    metrics = _step_metrics(t_out, y_out)
+
+    ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
+    plot_path = ARTIFACT_DIR / f"state_feedback_step_{abs(hash((str(A), str(B), str(K), sim_time))) % 10**8:08d}.png"
+
+    fig, ax = plt.subplots(figsize=(8, 4.5), dpi=150)
+    ax.plot(t_out, y_out, color="#58a6ff", linewidth=2.0, label="Response $y(t)$")
+    y_final = metrics["final_value"]
+    ax.axhline(y_final, color="#f85149", linestyle="--", alpha=0.8, label=f"Final Value ({y_final:.4f})")
+    ax.axhline(y_final * 1.02, color="gray", linestyle=":", alpha=0.5)
+    ax.axhline(y_final * 0.98, color="gray", linestyle=":", alpha=0.5, label="2% Settling Band")
+    ax.set_title(plot_title, fontsize=12, fontweight="bold")
+    ax.set_xlabel("Time [seconds]", fontsize=10)
+    ax.set_ylabel("Output Amplitude", fontsize=10)
+    ax.grid(True, linestyle="--", alpha=0.4)
+    ax.legend(loc="best")
+    fig.tight_layout()
+    fig.savefig(plot_path)
+    plt.close(fig)
+
+    wn = [float(abs(p)) for p in poles]
+    zeta = [float(-np.real(p) / abs(p)) if abs(p) > 1e-12 else 0.0 for p in poles]
+
+    return {
+        "status": "success",
+        "mode": "closed_loop_state_feedback" if K_mat is not None else "open_loop",
+        "closed_loop_A": A_eff.tolist(),
+        "poles": [[float(p.real), float(p.imag)] for p in poles],
+        "natural_frequencies_rad_s": wn,
+        "damping_ratios": zeta,
+        "is_stable": bool(np.all(np.real(poles) < 0)),
+        "closed_loop_tf_numerator": np.asarray(num).ravel().tolist(),
+        "closed_loop_tf_denominator": np.asarray(den).ravel().tolist(),
+        "dc_precompensator_applied": dc_scale if normalize_dc_gain else None,
+        **metrics,
+        "plot_path": str(plot_path),
+        "plot_artifact_path": str(plot_path),
+    }
+
+
 @registry.register(
     name="simulate_step_response",
-    description="Simulate the unit step response of a continuous transfer function G(s) = num(s)/den(s), compute rise time, overshoot, settling time, and save a high-resolution PNG plot artifact.",
+    description=(
+        "Simulate the unit step response of a continuous transfer function G(s) = num(s)/den(s), compute "
+        "rise time, overshoot, settling time, and save a high-resolution PNG plot artifact. Only use this "
+        "when the system is genuinely given to you as a transfer function -- if you have state-space "
+        "matrices A, B and/or a feedback gain K, call simulate_state_feedback_response instead rather "
+        "than deriving closed-loop coefficients yourself."
+    ),
     parameters_schema={
         "type": "object",
         "properties": {
@@ -50,21 +212,10 @@ def simulate_step_response(
     sys = signal.TransferFunction(numerator, denominator)
     t = np.linspace(0, sim_time, 1000)
     t_out, y_out = signal.step(sys, T=t)
+    y_out = np.asarray(y_out, dtype=float).ravel()
 
-    # Transient metrics
-    y_final = float(y_out[-1])
-    y_peak = float(np.max(y_out))
-    t_peak = float(t_out[int(np.argmax(y_out))])
-    overshoot_pct = float(max(0.0, (y_peak - y_final) / abs(y_final) * 100.0)) if abs(y_final) > 1e-6 else 0.0
-
-    # 10% to 90% Rise Time
-    idx_10 = np.where(y_out >= 0.1 * y_final)[0]
-    idx_90 = np.where(y_out >= 0.9 * y_final)[0]
-    rise_time = float(t_out[idx_90[0]] - t_out[idx_10[0]]) if len(idx_10) > 0 and len(idx_90) > 0 else None
-
-    # 2% Settling Time
-    settled_indices = np.where(np.abs(y_out - y_final) > 0.02 * abs(y_final))[0]
-    settling_time = float(t_out[settled_indices[-1]]) if len(settled_indices) > 0 else 0.0
+    metrics = _step_metrics(t_out, y_out)
+    y_final = metrics["final_value"]
 
     # Generate Matplotlib PNG Plot
     ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
@@ -85,11 +236,11 @@ def simulate_step_response(
     plt.close(fig)
 
     return {
-        "final_value": y_final,
-        "peak_value": y_peak,
-        "peak_time_seconds": t_peak,
-        "overshoot_percentage": overshoot_pct,
-        "rise_time_seconds": rise_time,
-        "settling_time_2pct_seconds": settling_time,
+        "status": "success",
+        **metrics,
+        # "plot_path" is the key the orchestrator looks for when surfacing
+        # generated figures to the UI; "plot_artifact_path" is kept for
+        # backward compatibility with existing benchmark/eval artifacts.
+        "plot_path": str(plot_path),
         "plot_artifact_path": str(plot_path),
     }

controlai_agent/tools/synthesis.py

@@ -87,7 +87,12 @@ def discrete_lqr(
 
 @registry.register(
     name="place_state_feedback",
-    description="Compute state feedback gain matrix K such that eig(A - B*K) matches target desired poles.",
+    description=(
+        "Compute state feedback gain matrix K such that eig(A - B*K) matches target desired poles. "
+        "Each entry of desired_poles is either a real number (a real pole) or a [real, imag] pair "
+        "(one half of a complex-conjugate pair -- e.g. targeting a damping ratio/natural frequency "
+        "needs poles like [-2, 3] and [-2, -3], both halves listed explicitly)."
+    ),
     parameters_schema={
         "type": "object",
         "properties": {
@@ -95,28 +100,46 @@ def discrete_lqr(
             "B": {"type": "array", "items": {"type": "array", "items": {"type": "number"}}},
             "desired_poles": {
                 "type": "array",
-                "items": {"type": "number"},
-                "description": "Target closed-loop pole locations",
+                "items": {
+                    "oneOf": [
+                        {"type": "number"},
+                        {"type": "array", "items": {"type": "number"}, "minItems": 2, "maxItems": 2},
+                    ]
+                },
+                "description": "Target closed-loop pole locations: a number for a real pole, or [real, imag] for a complex one.",
             },
         },
         "required": ["A", "B", "desired_poles"],
     },
 )
 def place_state_feedback(
-    A: list[list[float]], B: list[list[float]], desired_poles: list[float]
+    A: list[list[float]], B: list[list[float]], desired_poles: list[float | list[float]]
 ) -> dict[str, Any]:
     A_mat = np.array(A, dtype=float)
     B_mat = np.array(B, dtype=float)
-    des = np.array(desired_poles, dtype=float)
+    # Each pole is a plain number (real pole) or a [real, imag] pair.
+    desired_poles = [complex(p[0], p[1]) if isinstance(p, (list, tuple)) else complex(p) for p in desired_poles]
+    # dtype=complex, not float: targeting a specific damping ratio / natural
+    # frequency means passing a complex-conjugate pole pair, which is the
+    # normal case for a 2nd-order-or-higher design, not an edge case. Forcing
+    # float here silently discarded the imaginary part, turning a legitimate
+    # conjugate pair into the SAME real pole listed twice -- which then fails
+    # outright for a SISO system since place_poles cannot repeat a pole more
+    # than rank(B) times.
+    des = np.array(desired_poles, dtype=complex)
     placed = signal.place_poles(A_mat, B_mat, des)
-    K = placed.gain_matrix
+    # K is mathematically real for real A, B with a properly conjugate-paired
+    # desired_poles; drop the negligible numerical imaginary residue so the
+    # result is JSON-serializable (a genuinely unpaired complex pole is
+    # rejected by place_poles itself before this line is reached).
+    K = placed.gain_matrix.real
     closed_poles = np.linalg.eigvals(A_mat - B_mat @ K)
 
-    v_report = verifier.verify_pole_placement(A_mat, B_mat, K, desired_poles)
+    v_report = verifier.verify_pole_placement(A_mat, B_mat, K, list(des))
     return {
         "K": K.tolist(),
         "closed_loop_poles": [[float(p.real), float(p.imag)] for p in closed_poles],
-        "target_poles": desired_poles,
+        "target_poles": [[float(p.real), float(p.imag)] for p in des],
         "verification": v_report,
     }
 

controlai_rag/index.py

@@ -23,6 +23,27 @@ def tokenize_corpus(text: str) -> list[str]:
     return re.findall(r"\b\w+\b|[+\-*/^_]", text.lower())
 
 
+# Only chunk body text is tokenized into BM25, so a query naming a source
+# ("what does Nise say about stability") cannot match the book it refers to.
+# These constants drive a post-retrieval boost for chunks whose *filename*
+# matches a distinctive query term.
+SOURCE_MATCH_BOOST = 1.6
+# A filename token is only distinctive enough to boost on if it appears in at
+# most this fraction of the indexed files (floored at 2 files, so the rule
+# still works on a small corpus). An author surname like "nise" or "ogata"
+# appears in exactly one file; generic domain words appear in many.
+SOURCE_TOKEN_MAX_FILE_FRACTION = 0.02
+# Words that identify the subject rather than a specific source. Even if the
+# corpus grows large enough for these to slip under the fraction cutoff, they
+# must never trigger a source boost.
+GENERIC_SOURCE_TOKENS = {
+    "control", "controls", "systems", "system", "engineering", "theory",
+    "lecture", "lectures", "notes", "chapter", "solutions", "solution",
+    "exercise", "exercises", "book", "textbook", "txtbk", "edition", "vol",
+    "part", "final", "exam", "slides", "course", "intro", "introduction",
+}
+
+
 class ControlRAGIndex:
     """Fast, local, offline search index over control engineering documents."""
 
@@ -30,7 +51,39 @@ class ControlRAGIndex:
         self.index_dir = index_dir
         self.chunks: list[dict[str, Any]] = []
         self.bm25: Any | None = None
+        self._distinctive_source_tokens: set[str] = set()
         self._load_if_exists()
+        self._build_source_token_map()
+
+    def _build_source_token_map(self) -> None:
+        """Index which filename tokens are distinctive enough to boost on.
+
+        Author surnames and title words unique to a few files ("nise", "ogata",
+        "kharitonov") identify a source; words common across the corpus do not.
+        """
+        if not self.chunks:
+            return
+        files_per_token: dict[str, set[str]] = {}
+        all_files: set[str] = set()
+        for chunk in self.chunks:
+            fname = str(chunk.get("metadata", {}).get("filename", ""))
+            if not fname:
+                continue
+            all_files.add(fname)
+            for token in set(tokenize_corpus(fname)):
+                files_per_token.setdefault(token, set()).add(fname)
+
+        if not all_files:
+            return
+        cutoff = max(2, int(len(all_files) * SOURCE_TOKEN_MAX_FILE_FRACTION))
+        self._distinctive_source_tokens = {
+            token
+            for token, files in files_per_token.items()
+            if len(files) <= cutoff
+            and len(token) > 2
+            and not token.isdigit()
+            and token not in GENERIC_SOURCE_TOKENS
+        }
 
     def build_from_chunks(self, chunks: list[Chunk]) -> None:
         if BM25Okapi is None:
@@ -46,6 +99,9 @@ class ControlRAGIndex:
         self.chunks.extend(new_dict_chunks)
         corpus = [tokenize_corpus(c["text"]) for c in self.chunks]
         self.bm25 = BM25Okapi(corpus)
+        # A newly uploaded document may introduce a new author/title, so the
+        # distinctive-source vocabulary has to be recomputed alongside BM25.
+        self._build_source_token_map()
         self.save()
 
     def save(self) -> None:
@@ -78,21 +134,40 @@ class ControlRAGIndex:
             return []
 
         scores = self.bm25.get_scores(tokens)
-        top_indices = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)
+        ranked = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)
+
+        # Re-rank a widened candidate pool so that a chunk from an explicitly
+        # named source can be promoted above a body-text-only BM25 match.
+        query_source_tokens = set(tokens) & self._distinctive_source_tokens
+        pool = ranked[: max(top_k * 10, 60)]
+        rescored: list[tuple[float, int]] = []
+        for idx in pool:
+            base = float(scores[idx])
+            if base <= 0.0:
+                continue
+            score = base
+            if query_source_tokens:
+                fname_tokens = set(tokenize_corpus(str(self.chunks[idx].get("metadata", {}).get("filename", ""))))
+                if query_source_tokens & fname_tokens:
+                    score *= SOURCE_MATCH_BOOST
+            rescored.append((score, idx))
+        rescored.sort(key=lambda pair: pair[0], reverse=True)
 
         results = []
-        for idx in top_indices:
-            score = float(scores[idx])
-            if score <= 0.0:
-                break
+        for score, idx in rescored:
             chunk = self.chunks[idx]
             if source_filter and source_filter.lower() not in chunk["source_path"].lower():
                 continue
+            fname = chunk["metadata"].get("filename", "unknown")
+            source_name, is_published = display_source_name(fname)
             results.append({
                 "chunk_id": chunk["chunk_id"],
                 "score": round(score, 3),
                 "source": chunk["source_path"],
-                "filename": chunk["metadata"].get("filename", "unknown"),
+                "filename": fname,
+                # User-facing label -- never show the raw filename in an answer.
+                "source_name": source_name,
+                "is_published_work": is_published,
                 "page": chunk["metadata"].get("page"),
                 "text": chunk["text"],
             })
@@ -100,3 +175,107 @@ class ControlRAGIndex:
                 break
 
         return results
+
+
+# A single process-wide index instance. The agent, the retrieval tool, and the
+# document-upload endpoint must all read and mutate the SAME in-memory object:
+# with separate instances, a document uploaded through the web UI is written to
+# disk but stays invisible to the running agent until the server restarts.
+_shared_index: ControlRAGIndex | None = None
+
+
+def get_shared_index(index_dir: Path = INDEX_DIR) -> ControlRAGIndex:
+    """Return the process-wide shared RAG index, loading it on first use."""
+    global _shared_index
+    if _shared_index is None:
+        _shared_index = ControlRAGIndex(index_dir)
+    return _shared_index
+
+
+# --- Human-readable source names -------------------------------------------
+# Indexed filenames carry private organisational cruft -- owner initials
+# ("JD_", "B&B_"), course codes ("AMC", "PLMMR"), and scan artefacts
+# ("txtbk", "DEFINITIVO", a doubled ".pdf.pdf"). Those must never reach a user
+# as a citation, so every hit also carries a cleaned display name plus whether
+# it is a published work (citable by author/title) or personal course notes
+# (referred to generically).
+
+_PUBLISHED_SOURCES: dict[str, str] = {
+    "norman s. nise - control systems engineering": "Nise, *Control Systems Engineering*",
+    "ogata modern control engineering 5th txtbk": "Ogata, *Modern Control Engineering* (5th ed.)",
+}
+
+# Course code -> the subject it stands for, so a generic remainder such as
+# "CAM Course Notes Part 2" still resolves to something meaningful.
+_COURSE_CODES: dict[str, str] = {
+    "SAS": "Safety in Automation Systems",
+    "AMC": "Advanced and Multivariable Control",
+    "CIR": "Control of Industrial Robots",
+    "PLMMR": "Perception, Localization and Mapping for Mobile Robots",
+    "NC": "Networked Control",
+    "CAM": "Computer-Aided Manufacturing",
+    "PSC": "Production Systems Control",
+    "MIDA": "Model Identification and Data Analysis",
+    "MIDA1": "Model Identification and Data Analysis",
+    "ACEHV": "Autonomous and Connected Electric/Hybrid Vehicles",
+    "ACHEV": "Autonomous and Connected Electric/Hybrid Vehicles",
+    "ACAV": "Autonomous and Connected Vehicles",
+    "DDCSD": "Data-Driven Control System Design",
+    "SACI": "Industrial Automation and Communication Systems",
+    "ICT": "Information and Communication Technology",
+}
+
+_OWNER_PREFIX_RE = re.compile(r"^(?:B&B|BBB|JD|LP|EC|AC|FG|RB|XX)[_\-\s]+", re.IGNORECASE)
+_NOISE_RE = re.compile(
+    r"\b(?:txtbk|definitivo|margini\s+larghi|theory\s+notes|practice\s+notes|final)\b|\(.*?\)",
+    re.IGNORECASE,
+)
+
+
+def display_source_name(filename: str) -> tuple[str, bool]:
+    """Map an indexed filename to (display name, is_published_work)."""
+    if not filename:
+        return ("local reference", False)
+
+    stem = str(filename)
+    while True:
+        lowered = stem.lower()
+        for ext in (".pdf", ".md", ".txt", ".json", ".jsonl"):
+            if lowered.endswith(ext):
+                stem = stem[: -len(ext)]
+                break
+        else:
+            break
+
+    key = " ".join(stem.split()).lower()
+    if key in _PUBLISHED_SOURCES:
+        return (_PUBLISHED_SOURCES[key], True)
+
+    name = _OWNER_PREFIX_RE.sub("", stem)
+
+    # A leading all-caps token is a course code; swap it for its subject.
+    subject = ""
+    parts = name.replace("_", " ").split()
+    if parts:
+        head = parts[0].strip(":-").upper()
+        if head in _COURSE_CODES:
+            subject = _COURSE_CODES[head]
+            parts = parts[1:]
+        elif len(parts) > 1 and 2 <= len(head) <= 6 and head.isalpha() and parts[0].isupper():
+            parts = parts[1:]
+
+    remainder = _NOISE_RE.sub("", " ".join(parts))
+    remainder = " ".join(remainder.replace("_", " ").split()).strip(" -–—")
+
+    generic = remainder.lower() in {
+        "", "course notes", "lecture notes", "notes", "exercise sessions",
+        "summary", "course notes part 1", "course notes part 2", "lectures",
+    }
+    if subject and generic:
+        label = subject
+    elif subject and remainder:
+        label = subject if remainder.lower() in subject.lower() else f"{subject} - {remainder}"
+    else:
+        label = remainder or subject or "local reference"
+
+    return (f"{label} (course notes)", False)

scripts/eval_answer_quality.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Broad answer-quality smoke test across every control-engineering domain.
+
+Retrieval tests (scripts/test_rag_knowledge.py) only prove the right passage was
+found. This runs the FULL agent and grades the answer that actually reaches the
+user, checking the failure modes seen in practice:
+
+  * rendering    -- doubled LaTeX backslashes, orphaned <tool_call> tags,
+                    raw JSON leaking into prose
+  * citations    -- raw indexed filenames / extensions / course codes shown to
+                    the user instead of clean source names
+  * substance    -- the canned "analysis complete" placeholder, empty answers,
+                    answers too short to be useful
+  * tool hygiene -- the same tool re-run over and over, failed tool calls
+
+Usage:
+    python3 scripts/eval_answer_quality.py                 # all cases
+    python3 scripts/eval_answer_quality.py --filter robot  # subset
+    python3 scripts/eval_answer_quality.py --limit 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import time
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from controlai_agent.orchestrator import ControlAIAgent
+
+PLACEHOLDER = "computational analysis has been completed"
+
+# (domain, question). Deliberately spans applied domains and answer *shapes*:
+# numeric-with-tool, conceptual-from-RAG, design/applied prose, and definitional.
+CASES: list[tuple[str, str]] = [
+    ("classical", "Compute the gain margin, phase margin and crossover frequencies for G(s) = 10/(s*(s+1)*(s+5))."),
+    ("classical", "Explain what the phase margin tells you about a closed-loop system's damping."),
+    ("modern", "Design an LQR controller for A=[[0,1],[-2,-3]], B=[[0],[1]], Q=diag([10,1]), R=1 and simulate the step response."),
+    ("modern", "What is the difference between controllability and stabilizability?"),
+    ("mpc", "What is quasi-infinite horizon MPC and why is the terminal region needed?"),
+    ("mpc", "How does MPC handle actuator saturation compared to anti-windup PID?"),
+    ("estimation", "Explain the difference between the Kalman filter time update and measurement update."),
+    ("nonlinear", "What is a control barrier function and how does it enforce safety?"),
+    ("robust", "State the small gain theorem and when it is conservative."),
+    ("aerospace", "How is gain scheduling used in an aircraft flight control system across the flight envelope?"),
+    ("aerospace", "Explain the short-period and phugoid modes of aircraft longitudinal dynamics."),
+    ("automotive", "How does an electronic stability program use yaw rate feedback to correct oversteer?"),
+    ("automotive", "Design considerations for an adaptive cruise control spacing policy."),
+    ("robotics", "Explain impedance control for a robot manipulator in contact with the environment."),
+    ("robotics", "How does a mobile robot fuse odometry and lidar for localization?"),
+    ("automation", "What is cascade control in process automation and when does it help?"),
+    ("automation", "Explain integral windup in an industrial PID loop and how to prevent it."),
+    ("power", "How is field-oriented control used for induction motor drives?"),
+]
+
+RAW_FILENAME_PAT = re.compile(
+    r"\.pdf\b|\.md\b|\.jsonl?\b|\bJD_|\bB&B_|\bBBB[_\s]|\bLP_|\bEC_|\bAC_|\bFG_|\bRB_|\bXX_|txtbk|DEFINITIVO",
+    re.IGNORECASE,
+)
+DOUBLE_BS_PAT = re.compile(r"\\\\(?=[a-zA-Z|{}()])")
+
+
+def grade(question: str, result) -> tuple[list[str], dict]:
+    """Return (list of problems, metrics) for one answer."""
+    text = result.final_response or ""
+    problems: list[str] = []
+
+    if not text.strip():
+        problems.append("EMPTY answer")
+    elif PLACEHOLDER in text.lower():
+        problems.append("PLACEHOLDER non-answer")
+    elif len(text.split()) < 40:
+        problems.append(f"THIN answer ({len(text.split())} words)")
+
+    if DOUBLE_BS_PAT.search(text):
+        problems.append("DOUBLED LaTeX backslash")
+    if "<tool_call>" in text or "</tool_call>" in text:
+        problems.append("LEAKED tool_call tag")
+    if re.search(r'\{\s*"name"\s*:', text):
+        problems.append("LEAKED raw JSON")
+    if RAW_FILENAME_PAT.search(text):
+        problems.append("RAW filename in citation")
+
+    names = [t.tool_name for t in result.tool_traces]
+    failed = [t.tool_name for t in result.tool_traces if t.result.get("status") == "error"]
+    if failed:
+        problems.append(f"TOOL ERROR: {', '.join(sorted(set(failed)))}")
+    for n in set(names):
+        if names.count(n) > 2:
+            problems.append(f"REPEATED tool x{names.count(n)}: {n}")
+
+    return problems, {"tools": names, "words": len(text.split()), "plots": len(result.plots)}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--filter", default="", help="only run cases whose domain or text matches")
+    ap.add_argument("--limit", type=int, default=0)
+    args = ap.parse_args()
+
+    cases = [c for c in CASES if args.filter.lower() in (c[0] + " " + c[1]).lower()]
+    if args.limit:
+        cases = cases[: args.limit]
+
+    print(f"Loading agent...\n")
+    agent = ControlAIAgent()
+
+    failures: list[tuple[str, str, list[str]]] = []
+    for i, (domain, q) in enumerate(cases, 1):
+        t0 = time.time()
+        try:
+            res = agent.run(q)
+        except Exception as exc:  # a crash is itself a finding
+            failures.append((domain, q, [f"EXCEPTION: {exc}"]))
+            print(f"[{i}/{len(cases)}] {domain:<11} EXCEPTION  {exc}")
+            continue
+        problems, meta = grade(q, res)
+        status = "ok  " if not problems else "FAIL"
+        print(
+            f"[{i}/{len(cases)}] {domain:<11} {status} "
+            f"{time.time()-t0:5.1f}s  words={meta['words']:<4} "
+            f"plots={meta['plots']} tools={','.join(meta['tools']) or '-'}"
+        )
+        for p in problems:
+            print(f"              - {p}")
+        if problems:
+            failures.append((domain, q, problems))
+
+    print("\n" + "=" * 74)
+    print(f"{len(cases) - len(failures)}/{len(cases)} answers clean")
+    if failures:
+        print("\nIssues by type:")
+        counts: dict[str, int] = {}
+        for _, _, ps in failures:
+            for p in ps:
+                key = p.split(":")[0].split("(")[0].strip()
+                counts[key] = counts.get(key, 0) + 1
+        for k, v in sorted(counts.items(), key=lambda kv: -kv[1]):
+            print(f"  {v:>3}  {k}")
+    print("=" * 74)
+    return 0 if not failures else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/generate_behavior_sft_dataset.py

@@ -0,0 +1,429 @@
+#!/usr/bin/env python3
+"""Generate the behavioral SFT dataset the deployed adapter is missing.
+
+The current adapter (sft_v2 + agent traces) was trained exclusively on
+fully-specified control problems mapped to the matching design tool. As a
+result the model:
+  * routes ANY matrix-shaped question to a control-design tool (asked to
+    multiply two matrices, it ran an LQR synthesis),
+  * fabricates missing parameters (invented B/Q/R three separate times)
+    because it never saw a single example of asking for a missing value,
+  * carries numbers over from a previous, different problem in multi-turn
+    conversations.
+
+This script generates verified trajectories for exactly those behaviors:
+  1. plain linear-algebra routing   -> matrix_arithmetic tool traces
+  2. missing-parameter refusal      -> no tool call; state what's missing, ask
+  3. poisoned-history faithfulness  -> multi-turn: full problem in turn 1,
+                                       different request in turn 2 answered
+                                       WITHOUT reusing turn-1 numbers
+  4. conceptual questions           -> prose answer, no unnecessary code tool
+
+Every numeric answer is produced by executing the real registered tool, so
+the dataset is verified by construction.
+
+Usage:
+    python3 scripts/generate_behavior_sft_dataset.py
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import sys
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+import numpy as np
+
+from controlai_agent.registry import registry
+import controlai_agent.tools  # noqa: F401  (register all tools)
+
+OUTPUT_DIR = PROJECT_ROOT / "data" / "training" / "behavior_sft_v1"
+RNG_SEED = 20260819
+
+SYSTEM_PROMPT = (
+    "You are an offline control-systems engineering assistant. Lead with the result, "
+    "state assumptions and conventions, show the decisive calculation, and never invent "
+    "a plant, parameter, software output, or verification result. Use executable Python "
+    "or MATLAB only when requested."
+)
+
+
+def fmt_num(x: float) -> str:
+    return f"{x:.6g}"
+
+
+def fmt_matrix(mat: list[list[float]]) -> str:
+    return "[" + ", ".join("[" + ", ".join(fmt_num(v) for v in row) + "]" for row in mat) + "]"
+
+
+def fmt_matrix_latex(mat) -> str:
+    arr = np.atleast_2d(np.array(mat, dtype=float))
+    rows = [" & ".join(fmt_num(v) for v in row) for row in arr]
+    return "\\begin{bmatrix} " + " \\\\ ".join(rows) + " \\end{bmatrix}"
+
+
+def rand_int_matrix(rng: random.Random, rows: int, cols: int) -> list[list[float]]:
+    return [[float(rng.randint(-9, 9)) for _ in range(cols)] for _ in range(rows)]
+
+
+def rand_nonsingular(rng: random.Random, n: int) -> list[list[float]]:
+    while True:
+        m = rand_int_matrix(rng, n, n)
+        if abs(np.linalg.det(np.array(m))) > 0.5:
+            return m
+
+
+def matrix_to_text(mat: list[list[float]], rng: random.Random) -> str:
+    """Render a matrix as the user might actually type it, garbling included."""
+    style = rng.random()
+    body = "[" + ", ".join("[" + ", ".join(fmt_num(v) for v in row) + "]" for row in mat) + "]"
+    if style < 0.7:
+        return body
+    # space-separated rows, occasionally with a dropped comma (real user input)
+    rows = []
+    for row in mat:
+        if rng.random() < 0.5:
+            rows.append("[" + " ".join(fmt_num(v) for v in row) + "]")
+        else:
+            rows.append("[" + ", ".join(fmt_num(v) for v in row) + "]")
+    return "[" + ", ".join(rows) + "]"
+
+
+def tool_call_msg(name: str, args: dict[str, Any]) -> dict[str, str]:
+    return {
+        "role": "assistant",
+        "content": f"<tool_call>\n{json.dumps({'name': name, 'arguments': args}, ensure_ascii=False)}\n</tool_call>",
+    }
+
+
+def tool_result_msg(name: str, result: dict[str, Any]) -> dict[str, str]:
+    return {"role": "tool", "name": name, "content": json.dumps(result, ensure_ascii=False)}
+
+
+def make_example(messages: list[dict[str, str]]) -> dict[str, Any]:
+    return {"messages": [{"role": "system", "content": SYSTEM_PROMPT}] + messages}
+
+
+# ---------------------------------------------------------------------------
+# 1. Plain linear-algebra routing
+# ---------------------------------------------------------------------------
+
+MULT_PHRASES = [
+    "{a} times {b}",
+    "Multiply {a} by {b}",
+    "Compute the matrix product of A = {a} and B = {b}",
+    "A = {a} times A = {b}",
+    "What is {a} * {b}?",
+    "{a} multiplied by {b}",
+]
+
+UNARY_TEMPLATES = {
+    "inverse": ["Invert the matrix {a}", "What is the inverse of {a}?", "Compute {a}^-1"],
+    "determinant": ["Determinant of {a}", "Compute det({a})", "What is the determinant of the matrix {a}?"],
+    "rank": ["What is the rank of {a}?", "Compute the rank of the matrix {a}"],
+    "transpose": ["Transpose {a}", "What is {a} transposed?"],
+    "eigenvalues": ["Eigenvalues of {a}", "Find the eigenvalues of the matrix {a}", "Compute the spectrum of {a}"],
+    "trace": ["What is the trace of {a}?", "Compute the trace of {a}"],
+}
+
+
+def gen_multiply(rng: random.Random) -> dict[str, Any] | None:
+    n = rng.choice([2, 2, 3, 3, 4])
+    k = rng.choice([n, n, rng.choice([1, 2, 3])])
+    A = rand_int_matrix(rng, n, k)
+    B = rand_int_matrix(rng, k, rng.choice([1, 2, 3, n]))
+    args = {"operation": "multiply", "matrix_a": A, "matrix_b": B}
+    result = registry.execute("matrix_arithmetic", args)
+    if result.get("status") != "success":
+        return None
+    prompt = rng.choice(MULT_PHRASES).format(a=matrix_to_text(A, rng), b=matrix_to_text(B, rng))
+    product = result["result"]
+    final = (
+        f"The matrix product is:\n$$AB = {fmt_matrix_latex(product)}$$\n"
+        f"({len(A)}x{len(A[0])} times {len(B)}x{len(B[0])} gives a {len(product)}x{len(product[0])} result; "
+        f"entry $(i,j)$ is the dot product of row $i$ of the first matrix with column $j$ of the second.)"
+    )
+    return make_example([
+        {"role": "user", "content": prompt},
+        tool_call_msg("matrix_arithmetic", args),
+        tool_result_msg("matrix_arithmetic", result),
+        {"role": "assistant", "content": final},
+    ])
+
+
+def gen_unary(rng: random.Random) -> dict[str, Any] | None:
+    op = rng.choice(list(UNARY_TEMPLATES.keys()))
+    n = rng.choice([2, 2, 3, 3])
+    A = rand_nonsingular(rng, n) if op == "inverse" else (
+        rand_int_matrix(rng, n, n) if op in ("determinant", "eigenvalues", "trace") else rand_int_matrix(rng, n, rng.choice([n, n + 1]))
+    )
+    args = {"operation": op, "matrix_a": A}
+    result = registry.execute("matrix_arithmetic", args)
+    if result.get("status") != "success":
+        return None
+    prompt = rng.choice(UNARY_TEMPLATES[op]).format(a=matrix_to_text(A, rng))
+    res = result["result"]
+    if op == "inverse":
+        final = f"The inverse is:\n$$A^{{-1}} = {fmt_matrix_latex(res)}$$\n(det $= {fmt_num(result['determinant'])} \\neq 0$, so the matrix is invertible.)"
+    elif op == "transpose":
+        final = f"The transpose is:\n$$A^T = {fmt_matrix_latex(res)}$$"
+    elif op == "eigenvalues":
+        eig_strs = [f"{fmt_num(re_)}" + (f" {'+' if im >= 0 else '-'} {fmt_num(abs(im))}j" if abs(im) > 1e-12 else "") for re_, im in res]
+        final = f"The eigenvalues are:\n$$\\lambda = \\{{{', '.join(eig_strs)}\\}}$$\nSpectral radius: $\\rho(A) = {fmt_num(result['spectral_radius'])}$."
+    elif op == "rank":
+        full = "full rank" if res == min(len(A), len(A[0])) else f"rank-deficient (max possible {min(len(A), len(A[0]))})"
+        final = f"$\\text{{rank}}(A) = {res}$ -- the matrix is {full}."
+    else:
+        final = f"$\\text{{{op}}}(A) = {fmt_num(res)}$."
+    return make_example([
+        {"role": "user", "content": prompt},
+        tool_call_msg("matrix_arithmetic", args),
+        tool_result_msg("matrix_arithmetic", result),
+        {"role": "assistant", "content": final},
+    ])
+
+
+# ---------------------------------------------------------------------------
+# 2. Missing-parameter refusal (single-turn)
+# ---------------------------------------------------------------------------
+
+def gen_refusal_single(rng: random.Random) -> dict[str, Any]:
+    n = rng.choice([2, 3])
+    A = rand_int_matrix(rng, n, n)
+    kind = rng.choice(["lqr_no_b", "lqr_no_qr", "place_no_poles", "zoh_no_ts", "margins_no_tf", "kalman_no_cov"])
+
+    if kind == "lqr_no_b":
+        prompt = rng.choice([
+            f"Design an LQR controller for A={fmt_matrix(A)}.",
+            f"Solve the LQR problem for the system with state matrix A={fmt_matrix(A)} and simulate the closed loop.",
+            f"Find the optimal LQR gain for A={fmt_matrix(A)}, Q=diag({', '.join(str(rng.randint(1, 20)) for _ in range(n))}), R=1.",
+        ])
+        answer = (
+            f"I can't run the LQR synthesis yet: the input matrix $B$ ({n}x m) has not been provided, and I "
+            f"won't assume one -- the gain $K$ depends entirely on how the input enters the dynamics.\n\n"
+            f"What I can tell you from $A$ alone: the open-loop eigenvalues determine whether the plant is "
+            f"stable before feedback, and controllability of $(A, B)$ must be checked once $B$ is known.\n\n"
+            f"Please provide $B$ (and $Q$, $R$ if you want other than default weights), and I will compute "
+            f"$P$, $K$, and the closed-loop poles."
+        )
+    elif kind == "lqr_no_qr":
+        B = [[0.0] for _ in range(n - 1)] + [[1.0]]
+        prompt = f"Compute the LQR gain for A={fmt_matrix(A)}, B={fmt_matrix(B)}."
+        answer = (
+            "The LQR gain is not defined until the cost is: I need the state penalty $Q$ (positive "
+            "semidefinite, {n}x{n}) and the control penalty $R$ (positive definite). Different $Q, R$ give "
+            "completely different gains for the same plant.\n\nTell me $Q$ and $R$ -- or tell me what "
+            "behavior you want (e.g. fast state 1, cheap control) and I will propose weights and say so "
+            "explicitly as a design choice."
+        ).replace("{n}", str(n))
+    elif kind == "place_no_poles":
+        B = [[0.0] for _ in range(n - 1)] + [[1.0]]
+        prompt = f"Place the closed-loop poles for A={fmt_matrix(A)}, B={fmt_matrix(B)} using state feedback."
+        answer = (
+            "Pole placement needs target pole locations, and none were given. Where do you want the "
+            f"closed-loop poles? Provide {n} locations (complex ones in conjugate pairs, e.g. $-2 \\pm 3j$), "
+            "or give a specification (settling time, damping ratio) and I will derive pole locations from it "
+            "and state that derivation explicitly."
+        )
+    elif kind == "zoh_no_ts":
+        B = [[0.0] for _ in range(n - 1)] + [[1.0]]
+        prompt = f"Discretize A={fmt_matrix(A)}, B={fmt_matrix(B)} using zero-order hold."
+        answer = (
+            "Exact ZOH discretization requires the sampling period $T_s$, which was not given -- $A_d = "
+            "e^{A T_s}$ changes completely with it. What is $T_s$ (in seconds)? As a rule of thumb it should "
+            "give 10-30 samples per dominant closed-loop time constant."
+        )
+    elif kind == "margins_no_tf":
+        prompt = rng.choice([
+            "Compute the gain and phase margins of my loop.",
+            "What are the stability margins of the system?",
+        ])
+        answer = (
+            "I need the open-loop transfer function to compute margins -- numerator and denominator "
+            "coefficients of $L(s)$, or its poles/zeros/gain, or the state-space matrices. Please provide "
+            "one of those and I will compute GM, PM, and both crossover frequencies exactly."
+        )
+    else:  # kalman_no_cov
+        prompt = f"Run a Kalman filter time update for A={fmt_matrix(A)}."
+        answer = (
+            "A Kalman time update needs more than $A$: the current state estimate $\\hat{x}$, its covariance "
+            "$P$, and the process noise covariance $Q_w$ (plus $B$ and $u$ if there is a known input). "
+            "Which values should I use? I will not assume noise statistics -- they determine the filter "
+            "entirely."
+        )
+    return make_example([
+        {"role": "user", "content": prompt},
+        {"role": "assistant", "content": answer},
+    ])
+
+
+# ---------------------------------------------------------------------------
+# 3. Poisoned-history faithfulness (multi-turn)
+# ---------------------------------------------------------------------------
+
+def _full_lqr_turn(rng: random.Random) -> tuple[list[dict[str, str]], dict[str, Any]]:
+    """A complete verified LQR exchange to serve as turn 1 (the 'poison')."""
+    A = [[0.0, 1.0], [float(-rng.randint(1, 5)), float(-rng.randint(1, 5))]]
+    B = [[0.0], [1.0]]
+    q1, q2 = rng.choice([(10, 1), (20, 1), (5, 2), (100, 1)])
+    Q = [[float(q1), 0.0], [0.0, float(q2)]]
+    R = [[1.0]]
+    args = {"A": A, "B": B, "Q": Q, "R": R}
+    result = registry.execute("continuous_lqr", args)
+    prompt = f"Design an LQR controller for A={fmt_matrix(A)}, B={fmt_matrix(B)}, Q=diag([{q1}, {q2}]), R=1."
+    K = result["K"]
+    poles = result["closed_loop_poles"]
+    pole_strs = [f"{fmt_num(p[0])}" + (f" {'+' if p[1] >= 0 else '-'} {fmt_num(abs(p[1]))}j" if abs(p[1]) > 1e-9 else "") for p in poles]
+    final = (
+        f"Solving the CARE gives the optimal gain $K = {fmt_matrix_latex(K)}$ with closed-loop poles "
+        f"$\\{{{', '.join(pole_strs)}\\}}$ -- the closed loop is asymptotically stable."
+    )
+    turn = [
+        {"role": "user", "content": prompt},
+        tool_call_msg("continuous_lqr", args),
+        tool_result_msg("continuous_lqr", result),
+        {"role": "assistant", "content": final},
+    ]
+    return turn, args
+
+
+def gen_poisoned_matrix_question(rng: random.Random) -> dict[str, Any] | None:
+    """Turn 1: full LQR. Turn 2: plain matrix question -> matrix tool only."""
+    turn1, _ = _full_lqr_turn(rng)
+    n = rng.choice([2, 3])
+    X = rand_int_matrix(rng, n, n)
+    Y = rand_int_matrix(rng, n, n)
+    args = {"operation": "multiply", "matrix_a": X, "matrix_b": Y}
+    result = registry.execute("matrix_arithmetic", args)
+    if result.get("status") != "success":
+        return None
+    prompt = rng.choice(MULT_PHRASES).format(a=matrix_to_text(X, rng), b=matrix_to_text(Y, rng))
+    final = f"The matrix product is:\n$$XY = {fmt_matrix_latex(result['result'])}$$"
+    return make_example(turn1 + [
+        {"role": "user", "content": prompt},
+        tool_call_msg("matrix_arithmetic", args),
+        tool_result_msg("matrix_arithmetic", result),
+        {"role": "assistant", "content": final},
+    ])
+
+
+def gen_poisoned_refusal(rng: random.Random) -> dict[str, Any]:
+    """Turn 1: full 2-state LQR. Turn 2: new 3-state A with no B -> refuse,
+    explicitly declining to reuse the old problem's matrices."""
+    turn1, old_args = _full_lqr_turn(rng)
+    A3 = rand_int_matrix(rng, 3, 3)
+    prompt = rng.choice([
+        f"Now design an LQR controller for A={fmt_matrix(A3)}.",
+        f"Do the same for A={fmt_matrix(A3)}.",
+        f"LQR for A={fmt_matrix(A3)} please.",
+    ])
+    answer = (
+        "This is a new 3-state system, and I only have its $A$ matrix. The $B$, $Q$, and $R$ from the "
+        "previous problem belong to a different 2-state plant -- they do not carry over, and resizing them "
+        "to fit would be inventing a model.\n\nTo run this synthesis I need: $B$ (3 x m), and the weights "
+        "$Q$ (3x3 PSD) and $R$ (m x m PD), or a description of the actuation and objectives so I can "
+        "propose weights as an explicit design choice. What is $B$ for this system?"
+    )
+    return make_example(turn1 + [
+        {"role": "user", "content": prompt},
+        {"role": "assistant", "content": answer},
+    ])
+
+
+def gen_poisoned_concept_question(rng: random.Random) -> dict[str, Any]:
+    """Turn 1: full LQR. Turn 2: conceptual question -> prose, no tools, no old numbers."""
+    turn1, _ = _full_lqr_turn(rng)
+    concept, answer = rng.choice(CONCEPT_QA)
+    return make_example(turn1 + [
+        {"role": "user", "content": concept},
+        {"role": "assistant", "content": answer},
+    ])
+
+
+# ---------------------------------------------------------------------------
+# 4. Conceptual questions -> prose, no unnecessary tools
+# ---------------------------------------------------------------------------
+
+CONCEPT_QA: list[tuple[str, str]] = [
+    (
+        "What is the difference between controllability and stabilizability?",
+        "**Controllability** means every state can be driven anywhere in finite time: $\\text{rank}[B\\ AB\\ \\cdots\\ A^{n-1}B] = n$, or equivalently the PBH test $\\text{rank}[\\lambda I - A\\ \\ B] = n$ for every eigenvalue $\\lambda$.\n\n**Stabilizability** is weaker: only the *unstable* modes must be controllable -- PBH needs to hold only for $\\text{Re}(\\lambda) \\geq 0$. Stable uncontrollable modes are acceptable because they decay on their own.\n\nEvery controllable system is stabilizable; the converse fails. Stabilizability (with detectability) is exactly what LQR/LQG existence requires -- full controllability is sufficient but not necessary.",
+    ),
+    (
+        "Why does a phase margin around 45-60 degrees correspond to good damping?",
+        "For a second-order-dominant loop, phase margin and closed-loop damping are linked approximately by $\\zeta \\approx PM/100$ (PM in degrees), so $PM = 45^\\circ$--$60^\\circ$ maps to $\\zeta \\approx 0.45$--$0.6$: fast response with modest overshoot (roughly 10-25%).\n\nBelow ~30° the closed loop rings badly and is fragile to delay ($\\Delta\\phi = \\omega_{gc} T_d$ eats margin directly); much above 70° the response is sluggish. The linear rule degrades when higher-order dynamics or RHP zeros distort the phase near crossover -- then the exact relation, not the approximation, must be used.",
+    ),
+    (
+        "What is integral windup in a PID loop and how is it prevented?",
+        "When the actuator saturates, the plant stops responding to further increases in the control signal, but the integrator keeps accumulating error. The integral term 'winds up' far beyond what the actuator can deliver; after the error changes sign it takes a long time to unwind, causing large overshoot and slow recovery.\n\nStandard remedies: **conditional integration** (freeze the integrator while saturated), **back-calculation** (feed the difference between commanded and saturated actuator output back to discharge the integrator through gain $1/T_t$), or designing with actuator limits explicitly (MPC). Back-calculation is the common industrial choice because it degrades gracefully.",
+    ),
+    (
+        "When would you choose MPC over a well-tuned PID controller?",
+        "Choose **MPC** when the problem has structure PID cannot represent: hard constraints on inputs/states that the controller should respect *by design* rather than by saturation, strong multivariable interaction (coupled MIMO loops), a good process model with significant dead time, or an economic objective over a horizon.\n\nStay with **PID** when the loop is essentially SISO, fast, and model-poor: PID needs almost no model, runs at microsecond rates on a PLC, and its failure modes are well understood on the plant floor. A practical rule: constraints and coupling pay for MPC's modeling and maintenance cost; without them, they don't.",
+    ),
+    (
+        "What does the separation principle say for observer-based control?",
+        "For a linear system with state feedback $u = -K\\hat{x}$ driven by an observer with gain $L$, the closed-loop eigenvalues are exactly the union of the state-feedback poles $\\lambda(A - BK)$ and the observer poles $\\lambda(A - LC)$: the estimation error dynamics decouple from the regulation dynamics.\n\nSo $K$ and $L$ may be designed independently -- pole placement or LQR for $K$, pole placement or a Kalman filter for $L$ (the LQG combination). The caveat: separation guarantees *nominal* stability only. The combined loop can have poor robustness margins (Doyle's 1978 counterexample: LQG has no guaranteed margins), so robustness must be checked on the assembled loop.",
+    ),
+    (
+        "Explain the waterbed effect in feedback design.",
+        "Bode's sensitivity integral: for an open-loop stable, minimum-phase loop with relative degree ≥ 2, $\\int_0^\\infty \\ln|S(j\\omega)|\\, d\\omega = 0$ (and $= \\pi \\sum \\text{Re}(p_i)$ with unstable poles $p_i$). Pushing $|S|$ below 1 over one band necessarily pushes it above 1 somewhere else -- like pressing on a waterbed.\n\nConsequences: disturbance rejection improved in one band is paid for with amplification elsewhere; RHP zeros make it worse by confining where the 'bulge' can go. It is a conservation law, not a design flaw -- good loop shaping *places* the sensitivity bulge where disturbances and model error are least harmful.",
+    ),
+]
+
+
+def gen_concept(rng: random.Random) -> dict[str, Any]:
+    q, a = rng.choice(CONCEPT_QA)
+    return make_example([
+        {"role": "user", "content": q},
+        {"role": "assistant", "content": a},
+    ])
+
+
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    rng = random.Random(RNG_SEED)
+    examples: list[dict[str, Any]] = []
+
+    generators = [
+        (gen_multiply, 220),
+        (gen_unary, 200),
+        (gen_refusal_single, 260),
+        (gen_poisoned_matrix_question, 130),
+        (gen_poisoned_refusal, 130),
+        (gen_poisoned_concept_question, 60),
+        (gen_concept, 60),
+    ]
+    for fn, count in generators:
+        made = 0
+        attempts = 0
+        while made < count and attempts < count * 4:
+            attempts += 1
+            ex = fn(rng)
+            if ex is not None:
+                examples.append(ex)
+                made += 1
+        print(f"{fn.__name__}: {made}")
+
+    rng.shuffle(examples)
+    n_valid = max(1, len(examples) // 10)
+    valid, train = examples[:n_valid], examples[n_valid:]
+
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    for name, rows in (("train.jsonl", train), ("valid.jsonl", valid)):
+        with (OUTPUT_DIR / name).open("w", encoding="utf-8") as f:
+            for row in rows:
+                f.write(json.dumps(row, ensure_ascii=False) + "\n")
+    print(f"\nWrote {len(train)} train / {len(valid)} valid to {OUTPUT_DIR}")
+
+
+if __name__ == "__main__":
+    main()

scripts/test_rag_knowledge.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Knowledge-retrieval smoke test for the local RAG index.
+
+Runs a fixed set of canonical control-engineering queries against the live
+BM25 index used by the agent (controlai_rag.index.ControlRAGIndex) and checks
+that each query's top hits actually contain at least one expected keyword.
+Also reports whether each query's best score clears the 2.5 relevance
+threshold that ControlAIAgent._get_grounded_instruction uses to decide
+whether to inject retrieved text into the system prompt -- a query can
+retrieve "correct" chunks yet still never get grounded into an answer if its
+score sits below that bar.
+
+Usage:
+    python3 scripts/test_rag_knowledge.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from controlai_rag.index import ControlRAGIndex
+
+GROUNDING_SCORE_THRESHOLD = 2.5
+
+# (query, keywords where at least one must appear in a top-k hit's text)
+# ControlAI is a general control-engineering agent, so this suite deliberately
+# spans every application domain -- aerospace, automotive, robotics, industrial
+# automation, power -- not just classical/modern theory.
+TEST_CASES: list[tuple[str, list[str]]] = [
+    # --- Core theory ---
+    ("controllability matrix rank test", ["controllab", "rank"]),
+    ("observability of linear time invariant systems", ["observ"]),
+    ("continuous algebraic Riccati equation LQR", ["riccati", "lqr", "quadratic"]),
+    ("discrete algebraic Riccati equation DARE", ["riccati", "discrete"]),
+    ("zero order hold ZOH discretization", ["zero-order", "zero order", "hold", "discret"]),
+    ("Lyapunov stability of nonlinear systems", ["lyapunov", "stab"]),
+    ("gain margin phase margin frequency response", ["gain margin", "phase margin"]),
+    ("Kalman filter state estimation", ["kalman", "estimat"]),
+    ("PID controller tuning", ["pid", "proportional"]),
+    ("root locus method", ["root locus"]),
+    ("PBH test for controllability", ["pbh", "popov"]),
+    ("model predictive control constrained optimization", ["model predictive", "mpc", "horizon"]),
+    ("H-infinity robust control small gain theorem", ["h-infinity", "h infinity", "small gain", "hinf"]),
+    ("control barrier function safety filter", ["barrier", "safety"]),
+    ("state feedback pole placement", ["pole placement", "state feedback"]),
+    # --- Application domains ---
+    ("aircraft flight control longitudinal dynamics", ["aircraft", "flight", "longitudinal", "pitch"]),
+    ("quadrotor UAV attitude control", ["quadrotor", "uav", "attitude", "drone"]),
+    ("vehicle dynamics yaw rate stability control", ["vehicle", "yaw", "tire", "steering"]),
+    ("automotive cruise control design", ["cruise", "vehicle", "throttle", "speed"]),
+    ("robot manipulator kinematics and Jacobian", ["manipulator", "jacobian", "kinematic", "robot"]),
+    ("mobile robot localization and odometry", ["odometry", "localiz", "mobile robot", "slam"]),
+    ("industrial process control valve saturation", ["valve", "process", "saturat", "actuator"]),
+    ("cascade control loop in process automation", ["cascade", "process", "inner loop", "secondary"]),
+    ("electric motor drive speed control", ["motor", "drive", "torque", "induction"]),
+    ("system identification from input output data", ["identification", "arx", "least squares", "estimat"]),
+]
+
+
+def run() -> int:
+    index = ControlRAGIndex()
+    if not index.chunks or not index.bm25:
+        print("FAIL: RAG index did not load (no chunks / no BM25 model). Is data/rag_index/ populated?")
+        return 1
+
+    print(f"RAG index loaded: {len(index.chunks)} chunks\n")
+
+    passed = 0
+    grounded = 0
+    for query, keywords in TEST_CASES:
+        hits = index.search(query, top_k=5)
+        best_score = hits[0]["score"] if hits else 0.0
+        matched = any(
+            kw.lower() in hit["text"].lower()
+            for hit in hits
+            for kw in keywords
+        )
+        would_ground = best_score > GROUNDING_SCORE_THRESHOLD
+        grounded += int(would_ground)
+        passed += int(matched)
+
+        status = "PASS" if matched else "FAIL"
+        ground_tag = "grounds" if would_ground else "below threshold"
+        print(f"[{status}] '{query}'  best_score={best_score:.2f} ({ground_tag})")
+        if hits:
+            top = hits[0]
+            excerpt = " ".join(top["text"].split())[:160]
+            print(f"        top hit: [{top['filename']} p.{top['page']}] {excerpt}...")
+        else:
+            print("        no hits returned")
+        print()
+
+    total = len(TEST_CASES)
+    print("=" * 70)
+    print(f"Keyword relevance: {passed}/{total} queries retrieved an on-topic chunk")
+    print(f"Grounding trigger:  {grounded}/{total} queries would clear the score>{GROUNDING_SCORE_THRESHOLD} auto-grounding bar")
+    print("=" * 70)
+
+    return 0 if passed == total else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

web/app.css

@@ -517,7 +517,7 @@ body {
 
 .code-block-wrapper pre code {
   font-family: 'JetBrains Mono', 'Menlo', monospace !important;
-  font-size: 13px !important;
+  font-size: calc(var(--chat-font-size) * 0.87) !important;
   line-height: 1.6 !important;
   background: transparent !important;
   padding: 0 !important;
@@ -549,12 +549,30 @@ body {
 }
 
 .generating-indicator {
-  display: inline-block;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
   color: var(--text-muted);
   font-family: var(--font-mono);
   font-size: 12px;
 }
 
+.generating-indicator .dot {
+  width: 4px;
+  height: 4px;
+  border-radius: 50%;
+  background: currentColor;
+  animation: generating-pulse 1.1s ease-in-out infinite;
+}
+
+.generating-indicator .dot:nth-child(2) { animation-delay: 0.15s; }
+.generating-indicator .dot:nth-child(3) { animation-delay: 0.3s; }
+
+@keyframes generating-pulse {
+  0%, 60%, 100% { opacity: 0.25; transform: translateY(0); }
+  30% { opacity: 1; transform: translateY(-2px); }
+}
+
 .thought-summary {
   padding: 6px 12px;
   font-family: var(--font-mono);
@@ -590,7 +608,7 @@ body {
   padding: 10px 14px;
   color: var(--text-muted);
   font-family: var(--font-mono);
-  font-size: 11px;
+  font-size: calc(var(--chat-font-size) * 0.73);
   line-height: 1.6;
   border-top: 1px solid var(--border-color);
   white-space: pre-wrap;
@@ -630,7 +648,7 @@ body {
 
 .plot-caption {
   font-family: var(--font-mono);
-  font-size: 11px;
+  font-size: calc(var(--chat-font-size) * 0.73);
   color: var(--text-muted);
   margin-top: 6px;
 }

web/app.js

@@ -327,14 +327,22 @@ document.addEventListener('DOMContentLoaded', () => {
   }
 
   function deleteSession(id) {
+    const wasCurrent = currentSessionId === id;
     sessions = sessions.filter((s) => s.id !== id);
     saveSessions();
-    if (currentSessionId === id) {
-      currentSessionId = sessions.length > 0 ? sessions[0].id : null;
-      if (!currentSessionId) {
-        startNewSession();
-        return;
-      }
+
+    if (!wasCurrent) {
+      // Deleting a different chat must never touch the thread that's on
+      // screen -- rebuilding it here would wipe an in-progress streaming
+      // response out from under itself.
+      renderHistorySidebar();
+      return;
+    }
+
+    currentSessionId = sessions.length > 0 ? sessions[0].id : null;
+    if (!currentSessionId) {
+      startNewSession();
+      return;
     }
     renderHistorySidebar();
     renderActiveSession();
@@ -453,6 +461,10 @@ document.addEventListener('DOMContentLoaded', () => {
     return entry;
   }
 
+  function workingIndicatorHtml(label) {
+    return `<span class="generating-indicator">${label}<span class="dot"></span><span class="dot"></span><span class="dot"></span></span>`;
+  }
+
   function escapeHtml(text) {
     const div = document.createElement('div');
     div.textContent = text;
@@ -618,7 +630,7 @@ document.addEventListener('DOMContentLoaded', () => {
     botEntry.className = 'message-entry bot';
     botEntry.innerHTML = `
       <div class="message-label">ControlAI</div>
-      <div class="message-content"><span class="generating-indicator">Working...</span></div>
+      <div class="message-content">${workingIndicatorHtml('Working')}</div>
     `;
     chatThread.appendChild(botEntry);
     smartScroll();
@@ -675,7 +687,7 @@ document.addEventListener('DOMContentLoaded', () => {
               const thoughtHtml = renderThoughtBox(thoughts, true);
               const textHtml = accumulatedText 
                 ? `<div class="response-body">${renderMarkdownWithKaTeX(accumulatedText)}<span class="streaming-cursor"></span></div>` 
-                : `<div class="response-body"><span class="generating-indicator">Working...</span><span class="streaming-cursor"></span></div>`;
+                : `<div class="response-body">${workingIndicatorHtml('Working')}<span class="streaming-cursor"></span></div>`;
               contentBox.innerHTML = thoughtHtml + textHtml;
               smartScroll();
             } else if (event.type === 'token') {

web/index.html

@@ -25,7 +25,7 @@
   <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/cpp.min.js"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/bash.min.js"></script>
   
-  <link rel="stylesheet" href="/static/app.css?v=20260818_syntax_highlight">
+  <link rel="stylesheet" href="/static/app.css?v=20260819_ui_fixes">
 </head>
 <body>
   <div class="app-shell">
@@ -226,6 +226,6 @@
     </div>
   </div>
 
-  <script src="/static/app.js?v=20260819_alphanumeric_math_fix"></script>
+  <script src="/static/app.js?v=20260819_ui_fixes"></script>
 </body>
 </html>