sim-cli-core 0.3.7__tar.gz → 0.3.9__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/CLAUDE.md +61 -9
- sim_cli_core-0.3.9/PKG-INFO +235 -0
- sim_cli_core-0.3.9/README.md +193 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/agent-readability.md +4 -0
- sim_cli_core-0.3.9/docs/remote-solvers.md +49 -0
- sim_cli_core-0.3.9/docs/why-cli-first.md +18 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/pyproject.toml +3 -2
- sim_cli_core-0.3.9/src/sim/_skills/sim-cli/SKILL.md +146 -0
- sim_cli_core-0.3.9/src/sim/assets.py +309 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/cli.py +39 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/describe.py +55 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/server.py +85 -7
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_cli.py +1 -1
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_describe.py +8 -1
- sim_cli_core-0.3.9/tests/base/test_scan.py +194 -0
- sim_cli_core-0.3.9/tests/base/test_session_versions.py +158 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/gui/test_connect_tools_field.py +5 -1
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/uv.lock +14 -1
- sim_cli_core-0.3.7/PKG-INFO +0 -367
- sim_cli_core-0.3.7/README.md +0 -326
- sim_cli_core-0.3.7/src/sim/_skills/sim-cli/SKILL.md +0 -94
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/.github/workflows/publish.yml +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/.gitignore +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/CONTRIBUTING.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/LICENSE +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/NOTICE +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/assets/architecture.svg +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/assets/banner.svg +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/assets/logo.svg +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/DEVELOPMENT.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/architecture/multi-session-and-config.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/architecture/skills-layering-plan.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/architecture/version-compat.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/plugin-install.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/__main__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_plugin_install.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_skills/sim-cli/gui/SKILL.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_skills/sim-cli/gui/snippets/dismiss_named_dialog.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_timeout.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/compat.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/config.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/driver.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/drivers/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/LICENSES/ATTRIBUTION.md +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/_pywinauto_tools.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/_win32_dialog.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/history.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/inspect.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/plugins.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/runner.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/session.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/testing/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/testing/protocol_conformance.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_compat.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_config.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_connect.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_driver_discovery.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_history.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_init_setup.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_lint.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_lint_public_corpus.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_logs.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_multi_session.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_plugin_install.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_plugins.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_protocol_conformance.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_python_floor_audit.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_run.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/conftest.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/drivers/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/calculix_e2e_cantilever_run.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/coolprop/water_props.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/elmer_e2e_heat_square.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/gmsh_e2e_sphere_mesh.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/lammps_e2e_lj_nvt.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/meshio_e2e_gmsh_to_vtk.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/pymfem_e2e_poisson.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/pyvista_e2e_sphere_stats.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/scikit_fem_e2e_poisson.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/scikitrf/short_load.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/su2_e2e_inviscid_bump.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/comsol/comsol_good.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/comsol/comsol_no_client.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/comsol/comsol_no_import.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_good.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_gui.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_no_import.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_no_usage.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_syntax_error.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/bad_import_order.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/bad_no_close.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/bad_no_simapp.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/hello_world.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/import_franka.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/not_isaac.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/official_hello_world.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/replicator_cubes.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/syntax_error.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/warehouse_sdg.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/matlab/empty_model.mdl +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/matlab/empty_model.slx +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/matlab/matlab_ok.m +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_good.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_no_import.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_no_mesh.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_syntax_error.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mock_fail.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mock_solver.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/newton/basic_pendulum.json +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/newton/cable_twist.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/newton/robot_g1.json +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/not_simulation.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_bad_import.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_crate_sweep.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_no_solve.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_spm_good.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_good.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_no_import.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_no_solve.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_syntax_error.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/gui/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/gui/test_gui_facade.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/__init__.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/_extract_comsol_Tmax.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_channel_3_4_5_9.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_gui_probes.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_inspect_types.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_probes.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_snippet_timeout.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tools/audit_python_floor.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tools/extract_driver.py +0 -0
- {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tools/lint-public-corpus.py +0 -0
|
@@ -4,12 +4,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|
|
4
4
|
|
|
5
5
|
## Project Overview
|
|
6
6
|
|
|
7
|
-
**sim**
|
|
7
|
+
**sim** reads existing CAE files and turns them into structured text an agent can use, detects local solver installs, validates scripts, and can hold a live solver session open across steps. The `pyproject.toml` description — "Agent-native simulation asset parsing and CAD/CAE runtime" — states the priority correctly: parsing first, runtime second.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
**Know which tier you are working in, because their dependencies differ:**
|
|
10
10
|
|
|
11
|
-
- **
|
|
12
|
-
- **
|
|
11
|
+
- **Asset parsing** (`sim scan`) — pure core, no plugin, no solver, no license. Backed by the `simparse` native extension, a hard dependency of `sim-cli-core`. This is the most-used capability in practice: agents can already drive solver GUIs directly, so the highest-value thing `sim` does today is recover engineering context from historical case files (a preprocessing step, closer to a document-to-structured-text converter than to a solver driver).
|
|
12
|
+
- **Solver discovery and script validation** (`sim check`, `sim lint`) — require the solver's plugin. With no plugins installed, `check --all` reports "scanned 0 drivers" and `lint` errors with `No registered driver claims ...`.
|
|
13
|
+
- **Execution** — requires a plugin, and comes in two modes:
|
|
14
|
+
- **One-shot** (`sim run script --solver=X`): subprocess execution, result stored as a numbered run, `sim logs` to browse.
|
|
15
|
+
- **Persistent session** (`sim connect/exec/inspect/disconnect`): a long-lived HTTP server holds a live solver session; agents send code snippets and inspect state without restarting the solver. `sim connect` auto-starts a local server when none is reachable (`session.py:_auto_start_server`), so `sim serve` is only needed explicitly for remote hosts — and `sim stop` is the counterpart that reaps that background process.
|
|
16
|
+
|
|
17
|
+
This tiering is load-bearing for docs and error messages: never imply `sim scan` needs a plugin, and never imply `sim check` works without one.
|
|
13
18
|
|
|
14
19
|
The shared runtime skill is bundled at `src/sim/_skills/sim-cli/` and synced into agent skill directories by `sim plugin sync-skills`. Per-solver agent skills ship inside their own `sim-plugin-<solver>` packages.
|
|
15
20
|
|
|
@@ -21,14 +26,19 @@ uv pip install -e ".[dev]" # core + pytest + ruff
|
|
|
21
26
|
|
|
22
27
|
# Tests
|
|
23
28
|
pytest -q # unit tests (no solver needed)
|
|
24
|
-
pytest tests/
|
|
29
|
+
pytest tests/base/test_scan.py # single test file
|
|
25
30
|
pytest -q -m integration # integration tests (need solvers + sim serve)
|
|
26
31
|
|
|
27
32
|
# Lint
|
|
28
33
|
ruff check src/sim tests
|
|
29
34
|
ruff check --fix src/sim tests
|
|
30
35
|
|
|
31
|
-
# CLI
|
|
36
|
+
# CLI — asset parsing (core only, no plugin/solver needed)
|
|
37
|
+
sim --json scan ./historical-cases # bounded summary, paths redacted
|
|
38
|
+
sim --json scan model.mph --full --include-paths
|
|
39
|
+
sim --json scan case.inp --format abaqus-inp # force format for a named file
|
|
40
|
+
|
|
41
|
+
# CLI — sessions
|
|
32
42
|
sim serve --host 0.0.0.0 # start HTTP server (default port 7600)
|
|
33
43
|
sim --host <ip> connect --solver <name> --mode solver --ui-mode gui
|
|
34
44
|
sim --host <ip> exec "solver.settings.mesh.check()"
|
|
@@ -36,13 +46,19 @@ sim --host <ip> inspect session.summary
|
|
|
36
46
|
sim --host <ip> screenshot -o shot.png
|
|
37
47
|
sim --host <ip> disconnect
|
|
38
48
|
|
|
49
|
+
sim disconnect # tear down the session
|
|
50
|
+
sim stop # reap the auto-started local server
|
|
51
|
+
|
|
39
52
|
sim run script.py --solver pybamm # one-shot mode
|
|
40
53
|
sim logs # list runs
|
|
41
54
|
sim logs last --field voltage_V # extract a parsed field
|
|
42
|
-
sim check <name> # solver availability
|
|
43
|
-
sim lint script.py # validate before running
|
|
55
|
+
sim check <name> # solver availability (needs the plugin)
|
|
56
|
+
sim lint script.py # validate before running (needs the plugin)
|
|
57
|
+
sim --json describe # machine-readable command manifest
|
|
44
58
|
```
|
|
45
59
|
|
|
60
|
+
**`--json` is a group-level flag and must precede the subcommand.** `sim --json describe` works; `sim describe --json` fails with `Error: No such option: --json`. The same applies to `--host`, `--port`, and `--session`. Note `docs/agent-readability.md` still shows the broken postfix form in two places.
|
|
61
|
+
|
|
46
62
|
Environment variables: `SIM_HOST`, `SIM_PORT` (CLI client, also `[server]` in config), `SIM_HOME` (global config + history dir, default `~/.sim/`), `SIM_DIR` (project dir, default `./.sim/`).
|
|
47
63
|
|
|
48
64
|
Config files (issue #5): `~/.sim/config.toml` (global) + `.sim/config.toml` (project). Resolution order `env > project > global > default`. With no config files present, behavior is unchanged from pre-config sim. Run `sim config path | show | init` to manage. See `docs/architecture/multi-session-and-config.md` for the full schema.
|
|
@@ -50,7 +66,18 @@ Config files (issue #5): `~/.sim/config.toml` (global) + `.sim/config.toml` (pro
|
|
|
50
66
|
## Architecture
|
|
51
67
|
|
|
52
68
|
### CLI (`src/sim/cli.py`)
|
|
53
|
-
Click app with subcommands: `serve`, `check`, `lint`, `run`, `connect`, `exec`, `inspect`, `ps`, `disconnect`, `screenshot`, `logs`. The session-related commands (`connect`/`exec`/`inspect`/`ps`/`disconnect`/`screenshot`) all delegate to `sim.session.SessionClient`, an HTTP client that talks to a running `sim serve`. The non-session commands (`run`, `lint`, `check`, `logs`) work locally without a server.
|
|
69
|
+
Click app with subcommands: `serve`, `scan`, `check`, `lint`, `run`, `connect`, `exec`, `inspect`, `ps`, `disconnect`, `stop`, `screenshot`, `logs`, `config`, `init`, `setup`, `plugin`, `describe`. The session-related commands (`connect`/`exec`/`inspect`/`ps`/`disconnect`/`screenshot`) all delegate to `sim.session.SessionClient`, an HTTP client that talks to a running `sim serve`. The non-session commands (`scan`, `run`, `lint`, `check`, `logs`, `config`, `init`, `setup`, `plugin`, `describe`) work locally without a server.
|
|
70
|
+
|
|
71
|
+
### Asset parsing (`src/sim/assets.py`)
|
|
72
|
+
`sim scan` → `assets.scan_assets(paths, ...)`, which lazily imports the `simparse` native extension (`_load_simparse`) and calls `simparse.scan` / `simparse.inspect`. There is no Python-level parser here: `assets.py` handles path walking, redaction, bounding, and envelope shaping; all format knowledge lives in the compiled `simparse` wheel.
|
|
73
|
+
|
|
74
|
+
Formats and their `--format` ids come from the `simparse` package metadata — check `simparse-<ver>.dist-info/METADATA` for the authoritative table rather than guessing, and re-check when the pinned range in `pyproject.toml` (`simparse>=0.3.2,<0.4`) moves. As of 0.3.2: COMSOL `.mph` (`comsol-mph`), Abaqus `.inp`/`.inc` (`abaqus-inp`), Fluent `.cas.h5`/`.msh.h5` (`fluent-hdf5`), Ansys Electronics Desktop `.aedt`/`.aedtz` (`hfss-aedt`), Ansys Mechanical `.mechdb`/`.mechdat` (`ansys-mechanical`), Icepak Classic `.tzr` (`icepak-tzr`), Simcenter FloTHERM `.pack`/`.xml`/`.floxml` (`flotherm-pack`, `flotherm-floxml`).
|
|
75
|
+
|
|
76
|
+
Output contract (`schema_version: "sim.scan/v1"`), which agents depend on:
|
|
77
|
+
- **Default (summary) view is bounded** — every list is wrapped as `{total, sample, truncated}` so a large directory scan cannot blow up an agent's context. `--full` returns plain lists and is documented for small input sets only.
|
|
78
|
+
- **Absolute paths are redacted** unless `--include-paths` is passed. Preserve this default in any new output path.
|
|
79
|
+
- `--format` is honored only for explicitly named files; directory scans always auto-detect.
|
|
80
|
+
- Unparseable input yields `error_code: ASSET_FORMAT_UNSUPPORTED` inside the standard failure envelope, not an exception.
|
|
54
81
|
|
|
55
82
|
### HTTP server (`src/sim/server.py`)
|
|
56
83
|
FastAPI app exposing:
|
|
@@ -110,6 +137,16 @@ Create or update solver drivers in the owning `sim-plugin-<solver>` repository.
|
|
|
110
137
|
|
|
111
138
|
The core CLI should only change when the shared runtime contract or plugin discovery machinery changes. Before editing driver-facing docs or behavior, inspect the installed environment with `sim plugin list` and `sim plugin info <solver>`, then work in the plugin repo that owns that solver.
|
|
112
139
|
|
|
140
|
+
**Prefer generic primitives over task-specific ones.** Before adding a new
|
|
141
|
+
driver method purpose-built for one workflow (a resumable-sweep runner, an
|
|
142
|
+
auto-coupling helper, etc.), check whether bounded `run(timeout_s=...)` +
|
|
143
|
+
`health()`/progress inspection + the solver's own retained state already let
|
|
144
|
+
the agent script that workflow step-by-step. Add a new dedicated primitive
|
|
145
|
+
only for a genuine generic gap proven by a real session (missing timeout
|
|
146
|
+
guard, no orphan-process cleanup, no liveness check) — not for workflow
|
|
147
|
+
convenience alone. See `sim-studio-desktop` issues #62/#80 for the HFSS case
|
|
148
|
+
this pattern was drawn from.
|
|
149
|
+
|
|
113
150
|
## Test Layout
|
|
114
151
|
|
|
115
152
|
```
|
|
@@ -117,19 +154,34 @@ tests/
|
|
|
117
154
|
__init__.py
|
|
118
155
|
conftest.py shared fixtures / execution paths
|
|
119
156
|
base/ core framework tests (no solver needed)
|
|
157
|
+
test_scan.py asset scanning contract (envelope, bounding, redaction)
|
|
120
158
|
test_cli.py smoke tests for click commands
|
|
159
|
+
test_describe.py CLI manifest / self-describing surface
|
|
121
160
|
test_compat.py skills layering / profile resolution
|
|
122
161
|
test_config.py two-tier config resolution
|
|
162
|
+
test_init_setup.py sim.toml init + setup, exit codes
|
|
123
163
|
test_connect.py driver.connect() availability checks
|
|
124
164
|
test_driver_discovery.py entry-point plugin discovery
|
|
165
|
+
test_plugins.py plugin listing / info
|
|
166
|
+
test_plugin_install.py retired-installer migration shim
|
|
167
|
+
test_protocol_conformance.py DriverProtocol conformance
|
|
125
168
|
test_history.py global run history persistence
|
|
126
169
|
test_lint.py lint protocol coverage
|
|
170
|
+
test_lint_public_corpus.py lint against a public script corpus
|
|
127
171
|
test_logs.py sim logs CLI
|
|
128
172
|
test_multi_session.py session routing + concurrency
|
|
173
|
+
test_session_versions.py session.versions inspect target
|
|
129
174
|
test_run.py one-shot subprocess execution
|
|
175
|
+
test_python_floor_audit.py minimum-Python-version audit
|
|
176
|
+
drivers/ per-solver driver checks (skipped without the solver)
|
|
177
|
+
execution/ end-to-end solver runs (integration marker)
|
|
178
|
+
gui/ GUI facade + connect tool fields
|
|
179
|
+
inspect/ inspect targets, probes, snippet timeouts
|
|
130
180
|
fixtures/ mock scripts and shared test assets
|
|
131
181
|
```
|
|
132
182
|
|
|
183
|
+
Only `-m integration` tests need solvers; `pytest -q` runs green with no plugins installed.
|
|
184
|
+
|
|
133
185
|
Solver plugin tests live in their own plugin repos. Tests in this repo cover the shared CLI/runtime contract and plugin discovery behavior.
|
|
134
186
|
|
|
135
187
|
## Notes
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: sim-cli-core
|
|
3
|
+
Version: 0.3.9
|
|
4
|
+
Summary: Agent-native simulation asset parsing and CAD/CAE runtime
|
|
5
|
+
Project-URL: Homepage, https://github.com/svd-ai-lab/sim-cli
|
|
6
|
+
Project-URL: Repository, https://github.com/svd-ai-lab/sim-cli
|
|
7
|
+
Project-URL: Issues, https://github.com/svd-ai-lab/sim-cli/issues
|
|
8
|
+
Project-URL: Documentation, https://github.com/svd-ai-lab/sim-cli#readme
|
|
9
|
+
Project-URL: Changelog, https://github.com/svd-ai-lab/sim-cli/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Weiqi Ji <jiweiqi10@gmail.com>
|
|
11
|
+
License-Expression: Apache-2.0
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
License-File: NOTICE
|
|
14
|
+
Keywords: agent,agentic,cad,cae,cfd,fea,llm,out-of-tree,plugins,simulation
|
|
15
|
+
Classifier: Development Status :: 3 - Alpha
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Intended Audience :: Science/Research
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Requires-Dist: click>=8.0
|
|
28
|
+
Requires-Dist: fastapi>=0.115
|
|
29
|
+
Requires-Dist: httpx>=0.28
|
|
30
|
+
Requires-Dist: lxml>=5.0
|
|
31
|
+
Requires-Dist: pillow>=10
|
|
32
|
+
Requires-Dist: psutil>=5.9; sys_platform == 'win32'
|
|
33
|
+
Requires-Dist: pywinauto>=0.6.8; sys_platform == 'win32'
|
|
34
|
+
Requires-Dist: pyyaml>=6.0
|
|
35
|
+
Requires-Dist: simparse<0.4,>=0.3.2
|
|
36
|
+
Requires-Dist: tomli>=2.0; python_version < '3.11'
|
|
37
|
+
Requires-Dist: uvicorn>=0.34
|
|
38
|
+
Provides-Extra: dev
|
|
39
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
40
|
+
Requires-Dist: ruff>=0.4; extra == 'dev'
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
# sim
|
|
44
|
+
|
|
45
|
+
**`sim` reads existing CAE files and turns them into structured text an agent
|
|
46
|
+
can use — without launching the solver.** It also detects local solver installs,
|
|
47
|
+
validates scripts before you run them, and can hold a live solver session open
|
|
48
|
+
when an agent needs to work one verified step at a time.
|
|
49
|
+
|
|
50
|
+
Python 3.10+ · Apache-2.0 · alpha
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Scan existing simulation assets
|
|
55
|
+
|
|
56
|
+
Point `sim scan` at a folder of `.mph` / `.inp` / `.cas.h5` / `.aedt` files and
|
|
57
|
+
get back structured JSON an agent can reason over — model inventory, materials,
|
|
58
|
+
boundary conditions, mesh counts, solve settings. No solver, no license, and no
|
|
59
|
+
plugin needed:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
uv init # only if this is not already a uv project
|
|
63
|
+
uv add sim-cli-core
|
|
64
|
+
uv run sim --json scan ./historical-cases
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```console
|
|
68
|
+
$ uv run sim --json scan ./cases/beam.inp --full
|
|
69
|
+
{
|
|
70
|
+
"schema_version": "sim.scan/v1",
|
|
71
|
+
"assets": [{
|
|
72
|
+
"file_name": "beam.inp",
|
|
73
|
+
"format": "abaqus-inp",
|
|
74
|
+
"summary": {"data": {
|
|
75
|
+
"title": "Cantilever beam thermal-stress",
|
|
76
|
+
"node_count": 3,
|
|
77
|
+
"element_count": 1,
|
|
78
|
+
"materials": ["STEEL"],
|
|
79
|
+
"sections": ["SOLID SECTION:STEEL"],
|
|
80
|
+
"steps": ["STATIC"],
|
|
81
|
+
"boundary_keywords": ["BOUNDARY"],
|
|
82
|
+
"load_keywords": ["CLOAD"],
|
|
83
|
+
"output_keywords": ["NODE PRINT"]
|
|
84
|
+
}}
|
|
85
|
+
}]
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
(abridged — the real envelope also carries `ok`, `engine`, `request`, and a
|
|
90
|
+
roll-up `summary` block.)
|
|
91
|
+
|
|
92
|
+
| Solver | Files | `--format` id |
|
|
93
|
+
| --- | --- | --- |
|
|
94
|
+
| COMSOL | `.mph` | `comsol-mph` |
|
|
95
|
+
| Abaqus | `.inp`, `.inc` | `abaqus-inp` |
|
|
96
|
+
| Fluent | `.cas.h5`, `.msh.h5` | `fluent-hdf5` |
|
|
97
|
+
| Ansys Electronics Desktop (HFSS / Icepak) | `.aedt`, `.aedtz` | `hfss-aedt` |
|
|
98
|
+
| Ansys Mechanical | `.mechdb`, `.mechdat` | `ansys-mechanical` |
|
|
99
|
+
| Icepak Classic | `.tzr` | `icepak-tzr` |
|
|
100
|
+
| Simcenter FloTHERM | `.pack`, `.xml`, `.floxml` | `flotherm-pack`, `flotherm-floxml` |
|
|
101
|
+
|
|
102
|
+
The default view is bounded — lists come back as `{total, sample, truncated}`
|
|
103
|
+
so a large scan cannot blow up an agent's context — and absolute paths are
|
|
104
|
+
redacted unless `--include-paths` is set. Use `--full` for the complete parser
|
|
105
|
+
result on a small input set, `--limit` and `--no-recursive` to bound a directory
|
|
106
|
+
walk, and `--format` to force a format for an explicitly named file.
|
|
107
|
+
|
|
108
|
+
## Example: what's in this folder?
|
|
109
|
+
|
|
110
|
+
```text
|
|
111
|
+
Scan ./legacy-cases and tell me which models are package-level thermal
|
|
112
|
+
studies, which already have solved results, and what total power each one
|
|
113
|
+
assumes. Use `uv run sim --json scan`.
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Find solvers and validate scripts
|
|
117
|
+
|
|
118
|
+
These need the solver's plugin installed — `sim-cli-core` ships with no drivers:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
uv add sim-plugin-comsol
|
|
122
|
+
uv run sim plugin sync-skills --target .agents/skills --copy
|
|
123
|
+
uv run sim check comsol # detect local installs and versions
|
|
124
|
+
uv run sim plugin doctor comsol --deep # plugin wiring + solver detection
|
|
125
|
+
uv run sim lint <script> # validate before running
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Use `.agents/skills` for Codex and GitHub Copilot, `.claude/skills` for Claude
|
|
129
|
+
Code. Two things are worth telling the agent explicitly: run through the project
|
|
130
|
+
with `uv run sim ...` so it sees the project's installed plugins, and never
|
|
131
|
+
guess solver API names — inspect the live model or the solver's local docs
|
|
132
|
+
first.
|
|
133
|
+
|
|
134
|
+
No uv, or installing from a wheel, git, or a local checkout — and the `sim.toml`
|
|
135
|
+
project manifest schema — are covered in
|
|
136
|
+
[docs/plugin-install.md](docs/plugin-install.md).
|
|
137
|
+
|
|
138
|
+
## Drive a live solver session
|
|
139
|
+
|
|
140
|
+
When an agent needs the solver held open across steps, `sim connect` starts a
|
|
141
|
+
local runtime and keeps the session alive. A bounded step is one modeling,
|
|
142
|
+
meshing, solving, or postprocessing action that can be inspected and verified
|
|
143
|
+
before continuing: create a geometry feature, assign a material, generate a
|
|
144
|
+
mesh, run one study, extract a probe value, export a result table.
|
|
145
|
+
|
|
146
|
+
Prefer this loop over one large generated script:
|
|
147
|
+
|
|
148
|
+
1. `uv run sim check <solver>`, then `uv run sim connect --solver <solver>`
|
|
149
|
+
2. `uv run sim inspect session.versions` before changing state — including after
|
|
150
|
+
any human GUI edit, since an engineer can cut in through the solver GUI at
|
|
151
|
+
any time and a previous script may no longer match the real session
|
|
152
|
+
3. `uv run sim exec --file step.py --label <step>` — one bounded step
|
|
153
|
+
4. `uv run sim inspect last.result`, verify with numeric evidence (mesh
|
|
154
|
+
statistics, convergence, probes, conservation checks, tolerances), checkpoint
|
|
155
|
+
5. `uv run sim disconnect`, then `uv run sim stop` to free the local runtime
|
|
156
|
+
|
|
157
|
+
The bundled solver skill enforces the details, so give the agent the engineering
|
|
158
|
+
goal in plain language rather than a list of `sim` sub-steps:
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
Simulate the natural-convection cooling of the attached `pcb.mph` and report the
|
|
162
|
+
maximum junction temperature. Use the installed COMSOL skill. If you need a
|
|
163
|
+
visible COMSOL Desktop session, connect with `--ui-mode gui`.
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Running the solver on a different host — and the security constraints that come
|
|
167
|
+
with it — is covered in [docs/remote-solvers.md](docs/remote-solvers.md).
|
|
168
|
+
|
|
169
|
+
## Solver plugins
|
|
170
|
+
|
|
171
|
+
Solver knowledge is not in the core CLI. It comes from plugins, each of which
|
|
172
|
+
provides a **driver**, so `sim` can launch or talk to the solver, and a
|
|
173
|
+
**skill**, so the agent knows that solver's workflow, pitfalls, and inspection
|
|
174
|
+
rules.
|
|
175
|
+
|
|
176
|
+
| Solver | Package spec | Plugin repo |
|
|
177
|
+
| --- | --- | --- |
|
|
178
|
+
| COMSOL | `sim-plugin-comsol` | [sim-plugin-comsol](https://github.com/svd-ai-lab/sim-plugin-comsol) |
|
|
179
|
+
| Abaqus | `sim-plugin-abaqus` | [sim-plugin-abaqus](https://github.com/svd-ai-lab/sim-plugin-abaqus) |
|
|
180
|
+
| LTspice | `sim-plugin-ltspice` | [sim-plugin-ltspice](https://github.com/svd-ai-lab/sim-plugin-ltspice) |
|
|
181
|
+
|
|
182
|
+
For the curated full list, see
|
|
183
|
+
[sim-plugin-index](https://github.com/svd-ai-lab/sim-plugin-index).
|
|
184
|
+
|
|
185
|
+
## Commands
|
|
186
|
+
|
|
187
|
+
Every command takes `--json` and returns a stable envelope with a closed
|
|
188
|
+
error-code enum — see [docs/agent-readability.md](docs/agent-readability.md).
|
|
189
|
+
|
|
190
|
+
| Command | Use it for |
|
|
191
|
+
|---|---|
|
|
192
|
+
| `uv run sim --json scan <path>...` | Parse historical simulation assets without launching a solver. |
|
|
193
|
+
| `uv run sim plugin list` | Show plugins visible in this project environment. |
|
|
194
|
+
| `uv run sim plugin info <solver>` | Show plugin metadata and compatibility summary. |
|
|
195
|
+
| `uv run sim plugin doctor <solver> --deep` | Check plugin wiring plus local solver detection. |
|
|
196
|
+
| `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for your agent. |
|
|
197
|
+
| `uv run sim check <solver>` | Detect local or remote solver installs. |
|
|
198
|
+
| `uv run sim connect --solver <solver>` | Open a persistent solver session. |
|
|
199
|
+
| `uv run sim exec --file step.py` | Run one bounded step in the live session. |
|
|
200
|
+
| `uv run sim inspect <target>` | Query session, result, or solver-specific state. |
|
|
201
|
+
| `uv run sim run script.py --solver <solver>` | Run a deterministic one-shot script. |
|
|
202
|
+
| `uv run sim logs last --field <name>` | Read back a one-shot run's parsed result. |
|
|
203
|
+
| `uv run sim disconnect` | Tear down the active session. |
|
|
204
|
+
| `uv run sim stop` | Stop the local runtime that `sim connect` auto-started. |
|
|
205
|
+
| `uv run sim setup` | Validate `sim.toml` and report declared plugin package specs. |
|
|
206
|
+
|
|
207
|
+
Run `uv run sim --json describe` for a machine-readable command manifest, or
|
|
208
|
+
`uv run sim <command> --help` for exact options.
|
|
209
|
+
|
|
210
|
+
## Solver ownership
|
|
211
|
+
|
|
212
|
+
`sim-cli` does not bundle or redistribute simulation solvers or vendor SDKs.
|
|
213
|
+
Install and operate each underlying solver according to its vendor terms. See
|
|
214
|
+
[NOTICE](NOTICE) for optional SDK dependency notes.
|
|
215
|
+
|
|
216
|
+
`sim-cli` is an independent open-source project and is not affiliated with,
|
|
217
|
+
endorsed by, or sponsored by any solver vendor. Product, solver, and company
|
|
218
|
+
names remain the property of their respective owners.
|
|
219
|
+
|
|
220
|
+
## Docs
|
|
221
|
+
|
|
222
|
+
- [docs/agent-readability.md](docs/agent-readability.md) — `--json` envelope,
|
|
223
|
+
error-code enum, exit codes. Read this first if you are an agent.
|
|
224
|
+
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — project setup, layout, driver
|
|
225
|
+
protocol, and architecture notes
|
|
226
|
+
- [docs/plugin-install.md](docs/plugin-install.md) — plugin installation and
|
|
227
|
+
`sim.toml` reference
|
|
228
|
+
- [docs/remote-solvers.md](docs/remote-solvers.md) — running the solver on
|
|
229
|
+
another host, and the security constraints that apply
|
|
230
|
+
- [docs/why-cli-first.md](docs/why-cli-first.md) — why a CLI rather than MCP
|
|
231
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md) — branch, test, and PR workflow
|
|
232
|
+
|
|
233
|
+
## License
|
|
234
|
+
|
|
235
|
+
Apache-2.0 — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# sim
|
|
2
|
+
|
|
3
|
+
**`sim` reads existing CAE files and turns them into structured text an agent
|
|
4
|
+
can use — without launching the solver.** It also detects local solver installs,
|
|
5
|
+
validates scripts before you run them, and can hold a live solver session open
|
|
6
|
+
when an agent needs to work one verified step at a time.
|
|
7
|
+
|
|
8
|
+
Python 3.10+ · Apache-2.0 · alpha
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Scan existing simulation assets
|
|
13
|
+
|
|
14
|
+
Point `sim scan` at a folder of `.mph` / `.inp` / `.cas.h5` / `.aedt` files and
|
|
15
|
+
get back structured JSON an agent can reason over — model inventory, materials,
|
|
16
|
+
boundary conditions, mesh counts, solve settings. No solver, no license, and no
|
|
17
|
+
plugin needed:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
uv init # only if this is not already a uv project
|
|
21
|
+
uv add sim-cli-core
|
|
22
|
+
uv run sim --json scan ./historical-cases
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```console
|
|
26
|
+
$ uv run sim --json scan ./cases/beam.inp --full
|
|
27
|
+
{
|
|
28
|
+
"schema_version": "sim.scan/v1",
|
|
29
|
+
"assets": [{
|
|
30
|
+
"file_name": "beam.inp",
|
|
31
|
+
"format": "abaqus-inp",
|
|
32
|
+
"summary": {"data": {
|
|
33
|
+
"title": "Cantilever beam thermal-stress",
|
|
34
|
+
"node_count": 3,
|
|
35
|
+
"element_count": 1,
|
|
36
|
+
"materials": ["STEEL"],
|
|
37
|
+
"sections": ["SOLID SECTION:STEEL"],
|
|
38
|
+
"steps": ["STATIC"],
|
|
39
|
+
"boundary_keywords": ["BOUNDARY"],
|
|
40
|
+
"load_keywords": ["CLOAD"],
|
|
41
|
+
"output_keywords": ["NODE PRINT"]
|
|
42
|
+
}}
|
|
43
|
+
}]
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
(abridged — the real envelope also carries `ok`, `engine`, `request`, and a
|
|
48
|
+
roll-up `summary` block.)
|
|
49
|
+
|
|
50
|
+
| Solver | Files | `--format` id |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| COMSOL | `.mph` | `comsol-mph` |
|
|
53
|
+
| Abaqus | `.inp`, `.inc` | `abaqus-inp` |
|
|
54
|
+
| Fluent | `.cas.h5`, `.msh.h5` | `fluent-hdf5` |
|
|
55
|
+
| Ansys Electronics Desktop (HFSS / Icepak) | `.aedt`, `.aedtz` | `hfss-aedt` |
|
|
56
|
+
| Ansys Mechanical | `.mechdb`, `.mechdat` | `ansys-mechanical` |
|
|
57
|
+
| Icepak Classic | `.tzr` | `icepak-tzr` |
|
|
58
|
+
| Simcenter FloTHERM | `.pack`, `.xml`, `.floxml` | `flotherm-pack`, `flotherm-floxml` |
|
|
59
|
+
|
|
60
|
+
The default view is bounded — lists come back as `{total, sample, truncated}`
|
|
61
|
+
so a large scan cannot blow up an agent's context — and absolute paths are
|
|
62
|
+
redacted unless `--include-paths` is set. Use `--full` for the complete parser
|
|
63
|
+
result on a small input set, `--limit` and `--no-recursive` to bound a directory
|
|
64
|
+
walk, and `--format` to force a format for an explicitly named file.
|
|
65
|
+
|
|
66
|
+
## Example: what's in this folder?
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
Scan ./legacy-cases and tell me which models are package-level thermal
|
|
70
|
+
studies, which already have solved results, and what total power each one
|
|
71
|
+
assumes. Use `uv run sim --json scan`.
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Find solvers and validate scripts
|
|
75
|
+
|
|
76
|
+
These need the solver's plugin installed — `sim-cli-core` ships with no drivers:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
uv add sim-plugin-comsol
|
|
80
|
+
uv run sim plugin sync-skills --target .agents/skills --copy
|
|
81
|
+
uv run sim check comsol # detect local installs and versions
|
|
82
|
+
uv run sim plugin doctor comsol --deep # plugin wiring + solver detection
|
|
83
|
+
uv run sim lint <script> # validate before running
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Use `.agents/skills` for Codex and GitHub Copilot, `.claude/skills` for Claude
|
|
87
|
+
Code. Two things are worth telling the agent explicitly: run through the project
|
|
88
|
+
with `uv run sim ...` so it sees the project's installed plugins, and never
|
|
89
|
+
guess solver API names — inspect the live model or the solver's local docs
|
|
90
|
+
first.
|
|
91
|
+
|
|
92
|
+
No uv, or installing from a wheel, git, or a local checkout — and the `sim.toml`
|
|
93
|
+
project manifest schema — are covered in
|
|
94
|
+
[docs/plugin-install.md](docs/plugin-install.md).
|
|
95
|
+
|
|
96
|
+
## Drive a live solver session
|
|
97
|
+
|
|
98
|
+
When an agent needs the solver held open across steps, `sim connect` starts a
|
|
99
|
+
local runtime and keeps the session alive. A bounded step is one modeling,
|
|
100
|
+
meshing, solving, or postprocessing action that can be inspected and verified
|
|
101
|
+
before continuing: create a geometry feature, assign a material, generate a
|
|
102
|
+
mesh, run one study, extract a probe value, export a result table.
|
|
103
|
+
|
|
104
|
+
Prefer this loop over one large generated script:
|
|
105
|
+
|
|
106
|
+
1. `uv run sim check <solver>`, then `uv run sim connect --solver <solver>`
|
|
107
|
+
2. `uv run sim inspect session.versions` before changing state — including after
|
|
108
|
+
any human GUI edit, since an engineer can cut in through the solver GUI at
|
|
109
|
+
any time and a previous script may no longer match the real session
|
|
110
|
+
3. `uv run sim exec --file step.py --label <step>` — one bounded step
|
|
111
|
+
4. `uv run sim inspect last.result`, verify with numeric evidence (mesh
|
|
112
|
+
statistics, convergence, probes, conservation checks, tolerances), checkpoint
|
|
113
|
+
5. `uv run sim disconnect`, then `uv run sim stop` to free the local runtime
|
|
114
|
+
|
|
115
|
+
The bundled solver skill enforces the details, so give the agent the engineering
|
|
116
|
+
goal in plain language rather than a list of `sim` sub-steps:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
Simulate the natural-convection cooling of the attached `pcb.mph` and report the
|
|
120
|
+
maximum junction temperature. Use the installed COMSOL skill. If you need a
|
|
121
|
+
visible COMSOL Desktop session, connect with `--ui-mode gui`.
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Running the solver on a different host — and the security constraints that come
|
|
125
|
+
with it — is covered in [docs/remote-solvers.md](docs/remote-solvers.md).
|
|
126
|
+
|
|
127
|
+
## Solver plugins
|
|
128
|
+
|
|
129
|
+
Solver knowledge is not in the core CLI. It comes from plugins, each of which
|
|
130
|
+
provides a **driver**, so `sim` can launch or talk to the solver, and a
|
|
131
|
+
**skill**, so the agent knows that solver's workflow, pitfalls, and inspection
|
|
132
|
+
rules.
|
|
133
|
+
|
|
134
|
+
| Solver | Package spec | Plugin repo |
|
|
135
|
+
| --- | --- | --- |
|
|
136
|
+
| COMSOL | `sim-plugin-comsol` | [sim-plugin-comsol](https://github.com/svd-ai-lab/sim-plugin-comsol) |
|
|
137
|
+
| Abaqus | `sim-plugin-abaqus` | [sim-plugin-abaqus](https://github.com/svd-ai-lab/sim-plugin-abaqus) |
|
|
138
|
+
| LTspice | `sim-plugin-ltspice` | [sim-plugin-ltspice](https://github.com/svd-ai-lab/sim-plugin-ltspice) |
|
|
139
|
+
|
|
140
|
+
For the curated full list, see
|
|
141
|
+
[sim-plugin-index](https://github.com/svd-ai-lab/sim-plugin-index).
|
|
142
|
+
|
|
143
|
+
## Commands
|
|
144
|
+
|
|
145
|
+
Every command takes `--json` and returns a stable envelope with a closed
|
|
146
|
+
error-code enum — see [docs/agent-readability.md](docs/agent-readability.md).
|
|
147
|
+
|
|
148
|
+
| Command | Use it for |
|
|
149
|
+
|---|---|
|
|
150
|
+
| `uv run sim --json scan <path>...` | Parse historical simulation assets without launching a solver. |
|
|
151
|
+
| `uv run sim plugin list` | Show plugins visible in this project environment. |
|
|
152
|
+
| `uv run sim plugin info <solver>` | Show plugin metadata and compatibility summary. |
|
|
153
|
+
| `uv run sim plugin doctor <solver> --deep` | Check plugin wiring plus local solver detection. |
|
|
154
|
+
| `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for your agent. |
|
|
155
|
+
| `uv run sim check <solver>` | Detect local or remote solver installs. |
|
|
156
|
+
| `uv run sim connect --solver <solver>` | Open a persistent solver session. |
|
|
157
|
+
| `uv run sim exec --file step.py` | Run one bounded step in the live session. |
|
|
158
|
+
| `uv run sim inspect <target>` | Query session, result, or solver-specific state. |
|
|
159
|
+
| `uv run sim run script.py --solver <solver>` | Run a deterministic one-shot script. |
|
|
160
|
+
| `uv run sim logs last --field <name>` | Read back a one-shot run's parsed result. |
|
|
161
|
+
| `uv run sim disconnect` | Tear down the active session. |
|
|
162
|
+
| `uv run sim stop` | Stop the local runtime that `sim connect` auto-started. |
|
|
163
|
+
| `uv run sim setup` | Validate `sim.toml` and report declared plugin package specs. |
|
|
164
|
+
|
|
165
|
+
Run `uv run sim --json describe` for a machine-readable command manifest, or
|
|
166
|
+
`uv run sim <command> --help` for exact options.
|
|
167
|
+
|
|
168
|
+
## Solver ownership
|
|
169
|
+
|
|
170
|
+
`sim-cli` does not bundle or redistribute simulation solvers or vendor SDKs.
|
|
171
|
+
Install and operate each underlying solver according to its vendor terms. See
|
|
172
|
+
[NOTICE](NOTICE) for optional SDK dependency notes.
|
|
173
|
+
|
|
174
|
+
`sim-cli` is an independent open-source project and is not affiliated with,
|
|
175
|
+
endorsed by, or sponsored by any solver vendor. Product, solver, and company
|
|
176
|
+
names remain the property of their respective owners.
|
|
177
|
+
|
|
178
|
+
## Docs
|
|
179
|
+
|
|
180
|
+
- [docs/agent-readability.md](docs/agent-readability.md) — `--json` envelope,
|
|
181
|
+
error-code enum, exit codes. Read this first if you are an agent.
|
|
182
|
+
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — project setup, layout, driver
|
|
183
|
+
protocol, and architecture notes
|
|
184
|
+
- [docs/plugin-install.md](docs/plugin-install.md) — plugin installation and
|
|
185
|
+
`sim.toml` reference
|
|
186
|
+
- [docs/remote-solvers.md](docs/remote-solvers.md) — running the solver on
|
|
187
|
+
another host, and the security constraints that apply
|
|
188
|
+
- [docs/why-cli-first.md](docs/why-cli-first.md) — why a CLI rather than MCP
|
|
189
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md) — branch, test, and PR workflow
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
Apache-2.0 — see [LICENSE](LICENSE).
|
|
@@ -62,6 +62,10 @@ top-level keys (`stdout`, `stderr`); never inside `message`.
|
|
|
62
62
|
| `PLUGIN_INSTALL_RETIRED` | A retired plugin package mutation command was invoked; use `uv add` / `uv remove` instead. |
|
|
63
63
|
| `PROTOCOL_VIOLATION` | A driver returned a value that doesn't match `DriverProtocol`. |
|
|
64
64
|
| `NONINTERACTIVE_INPUT_REQUIRED` | `--no-interactive` is set and the command would otherwise prompt. |
|
|
65
|
+
| `ASSET_SCAN_FAILED` | A simulation asset or directory could not be read or parsed. |
|
|
66
|
+
| `ASSET_FORMAT_UNSUPPORTED` | An explicitly requested file is not a supported simulation asset format. |
|
|
67
|
+
| `ASSET_PATH_NOT_FOUND` | A requested simulation asset path does not exist. |
|
|
68
|
+
| `SIMPARSE_UNAVAILABLE` | The required native `simparse` dependency could not be loaded on this platform. |
|
|
65
69
|
|
|
66
70
|
This list is closed: adding a new code requires updating this doc, the CLI,
|
|
67
71
|
and the JSON schema emitted by `sim describe --error-codes`.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Remote solvers
|
|
2
|
+
|
|
3
|
+
Most work happens on one machine, where `sim connect` starts a local runtime for
|
|
4
|
+
you and no `--host` is needed. This document covers the other case: the solver
|
|
5
|
+
lives on a workstation, lab box, or HPC login node, and the agent runs somewhere
|
|
6
|
+
else.
|
|
7
|
+
|
|
8
|
+
## Setup
|
|
9
|
+
|
|
10
|
+
Install `sim-cli-core` and the solver plugin **on the solver host**, then start
|
|
11
|
+
the server there:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# On the solver host.
|
|
15
|
+
uv run sim serve --host 0.0.0.0 --port 7600
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Point the agent machine at it. `--host`, `--port`, and `--session` are
|
|
19
|
+
group-level flags, so they precede the subcommand:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
# On the agent machine.
|
|
23
|
+
uv run sim --host <solver-host-ip> check <solver>
|
|
24
|
+
uv run sim --host <solver-host-ip> connect --solver <solver>
|
|
25
|
+
uv run sim --host <solver-host-ip> inspect session.summary
|
|
26
|
+
uv run sim --host <solver-host-ip> disconnect
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`SIM_HOST` and `SIM_PORT` set the same values through the environment.
|
|
30
|
+
|
|
31
|
+
## Security
|
|
32
|
+
|
|
33
|
+
**Only bind `sim serve` to a trusted network** such as a VPN, Tailscale, or a
|
|
34
|
+
protected LAN. Never expose it to the public internet.
|
|
35
|
+
|
|
36
|
+
The runtime has no authentication layer. `POST /connect` and `POST /exec` run
|
|
37
|
+
code on the solver host, so anyone who can reach the port can execute arbitrary
|
|
38
|
+
code as the user running `sim serve`.
|
|
39
|
+
|
|
40
|
+
Note the asymmetry in what is currently gated: `POST /shutdown` is
|
|
41
|
+
localhost-only (`server.py`), so a network peer cannot stop the server — but the
|
|
42
|
+
endpoints that execute code are not restricted the same way. Treat network
|
|
43
|
+
reachability itself as the security boundary.
|
|
44
|
+
|
|
45
|
+
## Caveats
|
|
46
|
+
|
|
47
|
+
`sim serve --reload` drops all sessions on any source change under the watched
|
|
48
|
+
tree, which matters more on a shared solver host than locally. Launch without
|
|
49
|
+
`--reload` for long-running work.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Why CLI-first?
|
|
2
|
+
|
|
3
|
+
Engineering simulation is file-based, scriptable, local, artifact-heavy, and
|
|
4
|
+
long-running. CAE agents work with solver executables, model files,
|
|
5
|
+
Python/Java/journal scripts, shell commands, logs, checkpoints, and plots — a
|
|
6
|
+
CLI command surface composes with all of that and matches how Codex CLI, Claude
|
|
7
|
+
Code, and other coding agents already operate.
|
|
8
|
+
|
|
9
|
+
MCP is useful for API-style integrations and remote tool discovery, but a broad
|
|
10
|
+
MCP surface adds context overhead and wrapper maintenance. For COMSOL, Abaqus,
|
|
11
|
+
Ansys Workbench, OpenFOAM, LTspice, and similar solvers, sim-cli keeps the
|
|
12
|
+
source of truth as a small, auditable command loop.
|
|
13
|
+
|
|
14
|
+
The practical consequence: an agent learns the whole surface from one
|
|
15
|
+
`sim --json describe` call, and every command it runs is a line a human can
|
|
16
|
+
re-run, paste into a bug report, or drop into a shell script. See
|
|
17
|
+
[agent-readability.md](agent-readability.md) for the I/O contract that makes
|
|
18
|
+
this work.
|