CST_AI

CST_AI v2.0

CST_AI turns a declarative task specification into a planned, budgeted, persisted CST Studio Suite workflow — and returns structured results with the provenance needed to trust them.

It is neither a GUI nor an autonomous scientific agent. It does not decide what to simulate, and it does not guess a number when the data is not there. You describe the task in a TaskSpec, CST_AI plans it, states the solver cost before anything runs, executes inside that authorised budget, and writes a durable run record that a later, completely fresh process can read back.

version = 2.0.0

---

Table of contents

• What CST_AI is
• Status
• Features
• Architecture
• Requirements
• Installation
• Quick start
• Public actions
• TaskSpec example
• Safety and the solve-budget model
• Result capabilities
• Limitations
• Roadmap
• License
• Third-party disclaimer

---

What CST_AI is

CST_AI is a plugin layer around CST Studio Suite. It sits between an agent or a script and the CST Python API, and it provides exactly four things:

1. A declarative front door. A task is a JSON document (TaskSpec) that names the task kind, the stages, the solve policy and the inputs. Unknown fields are rejected, so a typo can never silently change a run.
2. A plan before a side effect. plan is verified to perform zero CST contact, zero builds, zero solves and zero project writes. It reports the stage order, the planned solve count and the authorised budget up front.
3. A budgeted execution. run performs only the side effects the plan lists. Whether a solver may start is decided only by the TaskSpec solve policy. There is no hidden "and while we are in there, solve" behaviour.
4. Durable, structured output. Every run writes an atomic checkpoint, an append-only event log and a ResultBundle (JSON + Markdown) that keeps execution, numerical, scientific and provenance status separate — because a solver that exits successfully is not the same thing as a result you may use for science.

Large arrays never travel through the agent surface as raw samples: they are written to artifacts and referenced by path, size and SHA-256.

Status

Release evidence, capability-by-capability limitations and the acceptance runs are summarised in RELEASE_NOTES.md.

Features

• Five public actions — plan, run, status, inspect, resume — reachable from one launcher and from Python.
• Solve-budget enforcement — solve_policy (FORBID / ALLOW_ONE / ALLOW_UP_TO_N / REUSE_ONLY) plus max_solves; a task that declares a SOLVE stage under FORBID is refused as a contradiction, not executed.
• Durable run store — <store_root>/<run_id>/{state.json, events.jsonl, bundle.json, bundle.md}; status and inspect answer from a fresh process, and resume continues an interrupted run without re-solving anything already solved.
• Parameter sweeps — spec.points[], one isolated project per point, one shared budget, a signature-checked reuse cache, and real resume after interruption.
• Results that stay honest — resonance f0 / FWHM / Q return null with an explicit validity code when a half-level crossing is outside the band instead of inventing a number.
• Structured errors — every failure is {ok: false, error_type, stage, message, detail} with a machine-readable code from a fixed taxonomy (23 codes), and no raw traceback in the message.
• Reuse without re-solving — a reused point must pass both a signature check and an artifact-hash check, otherwise reuse is denied.

Architecture

   agent / script
        │
        ▼
   index.js                            DSH tool adapter (Node, optional)
        │  base64 JSON request
        ▼
   cst_ai_tool_bridge.ps1              PowerShell launcher (resolves interpreter)
        │
        ▼
   cst_ai_tool.py                      request adapter: TaskSpec → envelope
        │
        ▼
   cst_ai_plugin.public                PUBLIC API v1: plan/run/status/inspect/resume
        │
        ├── planner.py       pure: no CST, no solve, no writes
        ├── orchestrator.py  stages: CONNECT → BUILD → VERIFY → SOLVE → EXTRACT → ANALYZE → REPORT
        ├── runstore.py      atomic checkpoints + append-only events
        ├── capabilities.py  capability registry (21 entries)
        ├── validation.py    TaskSpec runtime validation
        ├── preflight.py     preconditions, protected paths
        ├── depsnapshot.py   dependency/config snapshot per run
        └── bundle.py        ResultBundle (JSON + Markdown)
        │
        ▼
   cst.interface  /  cst.results       CST Studio Suite Python API
        │
        ▼
   CST Studio Suite                   (NOT distributed with this project)

cst_cli.py is a small command-line entry point for the same five actions when you do not want the Node adapter. See docs/ARCHITECTURE.md for the layer-by-layer contract and docs/DSH_INTEGRATION.md for the tool-adapter details.

Requirements

• Windows (the launcher is PowerShell; the CST Python API is used as installed).
• CST Studio Suite 2026 with its bundled Python 3.12.x interpreter. CST_AI imports cst.interface / cst.results, which exist only in that interpreter — a stock CPython installation does not have them.
• PowerShell 5.1 or newer for cst_ai_tool_bridge.ps1.
• Node.js 18+ only if you want the DSH tool adapter (the dsh-cst-tools bundle).
• No Python packages. CST_AI uses the standard library only. There is nothing to pip install, and no virtual environment to create.

Installation

1. Clone or copy this repository somewhere writable:

   git clone <your-fork-url> CST_AI_public
   

2. Point the bridge at your CST interpreter. Either set the environment variable (recommended):

   $env:CST_AI_PYTHON = "C:\Program Files\CST Studio Suite 2026\Python\python.exe"
   

   or edit the default inside cst_ai_tool_bridge.ps1.

3. Create your local configuration (optional but recommended). Copy cst_ai_config.json and set:

   • run_store_path — where run records are written (default runs),
   • default_output_root — where task output directories resolve (default runs),
   • cst_runtime_pid_policy — AUTO or EXPLICIT (see below),
   • expected_project — optional guard: the project path a run is expected to touch,
   • parameter_rules — optional min/max rules for parameter validation.

4. (Optional) Install the DSH bundle instead of wiring a checkout by hand:

   dsh plugin --profile web add github:aomk20201110-commits/CST_AI#<40-char-commit>
   

   The repository root is the bundle: package.json declares dsh.bundle.patch: ./cordis.patch.yml, so one dsh plugin add installs the Node adapter, the PowerShell bridge and the Python package together. There is no build step and no install-time code execution, so pnpm never has to be allowlisted. Pin a commit — a GitHub install fetches source, so a branch would be free to change under you.

   A manual checkout keeps working: CST_AI_BRIDGE points the adapter at another installation's bridge.

   $env:CST_AI_BRIDGE = "C:\path\to\CST_AI_public\cst_ai_tool_bridge.ps1"
   

   The DSH marketplace listing is not published yet; until it is, install from GitHub as above.

5. Run the tests to confirm the checkout is healthy (see tests/):

   & $env:CST_AI_PYTHON -m unittest discover -s tests -v
   

CST_AI never starts, stops, kills or elevates CST. A Design Environment must already be running (or be startable by you, the user).

Quick start

1. Plan — no CST contact, no solve, no writes:

.\cst_ai_tool_bridge.ps1 plan (base64 of the request)

or from Python:

from cst_ai_plugin import public

plan = public.plan({
    "task_id": "read_my_result",
    "task_kind": "LOAD_EXISTING_RESULT",
    "stages": ["CONNECT", "EXTRACT", "ANALYZE", "REPORT"],
    "solve_policy": "FORBID",
    "spec": {"existing_project": "C:/work/solved_model.cst",
             "incident_mode": "Zmin(1)"},
    "inputs": {},
    "expected_outputs": ["resonance_table"],
    "output_dir": "runs/read_my_result",
})

print(plan["PLANNED_SOLVE_COUNT"], plan["MAX_AUTHORIZED_SOLVES"])

2. Run — only the side effects the plan lists:

result = public.run(task, store_root="runs")
print(result["run_id"], result["execution_status"])

3. Read it back later, from any process:

public.status(run_id)                  # offline: execution status + solver_usage
public.inspect(run_id)["observables"]  # the numbers, and their status
public.resume(run_id)                  # continue an interrupted run

QUICKSTART.md walks through the same flow with the example task specs in examples/.

Public actions

Both status and inspect are offline by contract. Requesting a runtime refresh from status is deliberately not authorised in V2.0: it answers REFRESH_RUNTIME_NOT_AUTHORIZED instead of quietly touching CST.

TaskSpec example

{
  "task_id": "cross_fss_point_7p0",
  "task_kind": "PARAMETER_SWEEP",
  "stages": ["CONNECT", "BUILD", "VERIFY", "SOLVE", "EXTRACT", "ANALYZE", "REPORT"],
  "solve_policy": "ALLOW_UP_TO_N",
  "max_solves": 2,
  "spec": {
    "fixture_definition": "fixtures/my_unit_cell.json",
    "points": [
      {"parameter": "cross_span_mm", "value": 6.5, "project_path": "work/point_6p5.cst"},
      {"parameter": "cross_span_mm", "value": 7.0, "project_path": "work/point_7p0.cst"}
    ],
    "incident_mode": "Zmin(1)"
  },
  "inputs": {},
  "expected_outputs": ["s_parameters", "resonance_table"],
  "output_dir": "runs/cross_fss_point_7p0",
  "notes": "TEST_ONLY: not valid for science"
}

Required fields: task_id, task_kind, stages, solve_policy, output_dir. Everything else is optional and validated. The complete schema, stage rules, solve policies and per-kind requirements are in docs/TASKSPEC.md.

Safety and the solve-budget model

• Nothing solves by accident. A real solver run requires a SOLVE stage and a solve policy that authorises it (ALLOW_ONE or ALLOW_UP_TO_N). REUSE_ONLY keeps the stage in the plan and turns it into a reuse decision; FORBID refuses a task that declares a SOLVE stage at all.
• One place authorises a solve count. The plan reports PLANNED_SOLVE_COUNT and MAX_AUTHORIZED_SOLVES before execution; the run record reports what was performed. Exceeding the budget raises SOLVE_BUDGET_EXCEEDED.
• Never re-solve solved work. A reused point must match a signature and an artifact hash. A mismatch denies reuse (SIGNATURE_MISMATCH / CACHE_INVALID) instead of silently re-simulating.
• No implicit output location. output_dir is mandatory; preflight refuses an output directory that is empty, is the repository root, or overlaps a protected input.
• CST is treated as somebody else's live process. CST_AI discovers an existing Design Environment and attaches to it; it never starts, stops, kills or elevates CST. cst_runtime_pid_policy is AUTO (follow the recorded runtime PID, then fall back to discovery) or EXPLICIT (only the PID you name); both require the PID to be verified, and ambiguity is reported rather than guessed.
• Statuses are not interchangeable. execution_status, numerical_status, scientific_status and provenance_status are reported separately. A completed solver run with an unresolvable observable is COMPLETED and UNRESOLVED — both true.

Result capabilities

21 capabilities are registered; each carries its verification status, its inputs and outputs, and whether it needs a solve. Highlights:

Everything except REFERENCE_COMPARATOR is reachable through the five public actions. The full table — verification stage, evidence, availability and limitations — is in CAPABILITY_MATRIX_V2.0.md.

Limitations

• Windows only. The launcher and the CST Python API integration are Windows-based.
• You must own CST. CST Studio Suite is not part of this project; CST_AI is a client of an installation you license separately.
• One live Design Environment at a time. CST_AI attaches to a single live DE and reports ambiguity instead of picking one arbitrarily.
• Existing results are required for the read-only capabilities. FARFIELD_*, DIRECTIVITY, GAIN, REALIZED_GAIN, BEAM_DIRECTION and HPBW activate a stored farfield result; they never re-solve to obtain one.
• Farfield readback depends on result activation. The angular data is read through the documented farfield evaluation-list chain after selecting the stored tree item. The CST-native GetMainLobeDirection / GetAngularWidthXdB getters are documented for .Plottype "Polar" only and raise on the results this plugin reads, so beam direction is taken from the read grid and HPBW is computed from it.
• No optimisation. PARAMETER_SWEEP evaluates the points you list; it does not adapt parameters, search a space or claim a "best" point.
• No natural-language input. You write the TaskSpec. (See the roadmap.)
• Fixtures are yours. CST project geometry is not redistributable, so this repository ships the shape of a fixture definition, not ready-made CST models.
• Repeatability is bounded by physics and by the solver. A numerically identical re-read of a stored result is exact; a new solve is as reproducible as CST itself.

Roadmap

Roadmap items are intentions, not commitments, and none of them weakens the solve-budget or provenance rules above.

License

MIT — see LICENSE. Third-party notices, including the CST Studio Suite relationship, are in THIRD_PARTY_NOTICES.md.

Third-party disclaimer

CST Studio Suite and its Python API are products of Dassault Systèmes. They are not distributed with this project, and this project is not affiliated with, endorsed by, or sponsored by Dassault Systèmes. You must have your own valid CST Studio Suite installation and licence to use CST_AI. See THIRD_PARTY_NOTICES.md.