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.
Files changed (136) hide show
  1. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/CLAUDE.md +61 -9
  2. sim_cli_core-0.3.9/PKG-INFO +235 -0
  3. sim_cli_core-0.3.9/README.md +193 -0
  4. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/agent-readability.md +4 -0
  5. sim_cli_core-0.3.9/docs/remote-solvers.md +49 -0
  6. sim_cli_core-0.3.9/docs/why-cli-first.md +18 -0
  7. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/pyproject.toml +3 -2
  8. sim_cli_core-0.3.9/src/sim/_skills/sim-cli/SKILL.md +146 -0
  9. sim_cli_core-0.3.9/src/sim/assets.py +309 -0
  10. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/cli.py +39 -0
  11. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/describe.py +55 -0
  12. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/server.py +85 -7
  13. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_cli.py +1 -1
  14. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_describe.py +8 -1
  15. sim_cli_core-0.3.9/tests/base/test_scan.py +194 -0
  16. sim_cli_core-0.3.9/tests/base/test_session_versions.py +158 -0
  17. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/gui/test_connect_tools_field.py +5 -1
  18. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/uv.lock +14 -1
  19. sim_cli_core-0.3.7/PKG-INFO +0 -367
  20. sim_cli_core-0.3.7/README.md +0 -326
  21. sim_cli_core-0.3.7/src/sim/_skills/sim-cli/SKILL.md +0 -94
  22. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/.github/workflows/publish.yml +0 -0
  23. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/.gitignore +0 -0
  24. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/CONTRIBUTING.md +0 -0
  25. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/LICENSE +0 -0
  26. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/NOTICE +0 -0
  27. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/assets/architecture.svg +0 -0
  28. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/assets/banner.svg +0 -0
  29. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/assets/logo.svg +0 -0
  30. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/DEVELOPMENT.md +0 -0
  31. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/architecture/multi-session-and-config.md +0 -0
  32. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/architecture/skills-layering-plan.md +0 -0
  33. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/architecture/version-compat.md +0 -0
  34. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/docs/plugin-install.md +0 -0
  35. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/__init__.py +0 -0
  36. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/__main__.py +0 -0
  37. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_plugin_install.py +0 -0
  38. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_skills/sim-cli/gui/SKILL.md +0 -0
  39. {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
  40. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/_timeout.py +0 -0
  41. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/compat.py +0 -0
  42. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/config.py +0 -0
  43. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/driver.py +0 -0
  44. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/drivers/__init__.py +0 -0
  45. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/LICENSES/ATTRIBUTION.md +0 -0
  46. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/__init__.py +0 -0
  47. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/_pywinauto_tools.py +0 -0
  48. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/gui/_win32_dialog.py +0 -0
  49. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/history.py +0 -0
  50. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/inspect.py +0 -0
  51. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/plugins.py +0 -0
  52. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/runner.py +0 -0
  53. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/session.py +0 -0
  54. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/testing/__init__.py +0 -0
  55. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/src/sim/testing/protocol_conformance.py +0 -0
  56. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/__init__.py +0 -0
  57. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/__init__.py +0 -0
  58. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_compat.py +0 -0
  59. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_config.py +0 -0
  60. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_connect.py +0 -0
  61. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_driver_discovery.py +0 -0
  62. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_history.py +0 -0
  63. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_init_setup.py +0 -0
  64. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_lint.py +0 -0
  65. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_lint_public_corpus.py +0 -0
  66. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_logs.py +0 -0
  67. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_multi_session.py +0 -0
  68. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_plugin_install.py +0 -0
  69. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_plugins.py +0 -0
  70. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_protocol_conformance.py +0 -0
  71. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_python_floor_audit.py +0 -0
  72. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/base/test_run.py +0 -0
  73. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/conftest.py +0 -0
  74. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/drivers/__init__.py +0 -0
  75. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/calculix_e2e_cantilever_run.py +0 -0
  76. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/coolprop/water_props.py +0 -0
  77. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/elmer_e2e_heat_square.py +0 -0
  78. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/gmsh_e2e_sphere_mesh.py +0 -0
  79. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/lammps_e2e_lj_nvt.py +0 -0
  80. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/meshio_e2e_gmsh_to_vtk.py +0 -0
  81. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/pymfem_e2e_poisson.py +0 -0
  82. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/pyvista_e2e_sphere_stats.py +0 -0
  83. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/scikit_fem_e2e_poisson.py +0 -0
  84. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/scikitrf/short_load.py +0 -0
  85. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/execution/su2_e2e_inviscid_bump.py +0 -0
  86. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/comsol/comsol_good.py +0 -0
  87. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/comsol/comsol_no_client.py +0 -0
  88. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/comsol/comsol_no_import.py +0 -0
  89. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_good.py +0 -0
  90. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_gui.py +0 -0
  91. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_no_import.py +0 -0
  92. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_no_usage.py +0 -0
  93. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/hypermesh_syntax_error.py +0 -0
  94. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/bad_import_order.py +0 -0
  95. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/bad_no_close.py +0 -0
  96. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/bad_no_simapp.py +0 -0
  97. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/hello_world.py +0 -0
  98. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/import_franka.py +0 -0
  99. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/not_isaac.py +0 -0
  100. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/official_hello_world.py +0 -0
  101. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/replicator_cubes.py +0 -0
  102. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/syntax_error.py +0 -0
  103. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/isaac/warehouse_sdg.py +0 -0
  104. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/matlab/empty_model.mdl +0 -0
  105. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/matlab/empty_model.slx +0 -0
  106. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/matlab/matlab_ok.m +0 -0
  107. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_good.py +0 -0
  108. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_no_import.py +0 -0
  109. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_no_mesh.py +0 -0
  110. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mfem_syntax_error.py +0 -0
  111. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mock_fail.py +0 -0
  112. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/mock_solver.py +0 -0
  113. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/newton/basic_pendulum.json +0 -0
  114. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/newton/cable_twist.py +0 -0
  115. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/newton/robot_g1.json +0 -0
  116. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/not_simulation.py +0 -0
  117. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_bad_import.py +0 -0
  118. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_crate_sweep.py +0 -0
  119. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_no_solve.py +0 -0
  120. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/pybamm/pybamm_spm_good.py +0 -0
  121. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_good.py +0 -0
  122. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_no_import.py +0 -0
  123. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_no_solve.py +0 -0
  124. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/fixtures/skfem_syntax_error.py +0 -0
  125. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/gui/__init__.py +0 -0
  126. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/gui/test_gui_facade.py +0 -0
  127. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/__init__.py +0 -0
  128. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/_extract_comsol_Tmax.py +0 -0
  129. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_channel_3_4_5_9.py +0 -0
  130. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_gui_probes.py +0 -0
  131. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_inspect_types.py +0 -0
  132. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_probes.py +0 -0
  133. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tests/inspect/test_snippet_timeout.py +0 -0
  134. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tools/audit_python_floor.py +0 -0
  135. {sim_cli_core-0.3.7 → sim_cli_core-0.3.9}/tools/extract_driver.py +0 -0
  136. {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** is a unified CLI + HTTP runtime that lets LLM agents (and engineers) launch, drive, and observe CAD/CAE simulations across multiple solvers through one consistent interface. It is the "container runtime for simulations" — agents talk to `sim`, `sim` talks to solvers.
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
- The runtime supports two execution modes:
9
+ **Know which tier you are working in, because their dependencies differ:**
10
10
 
11
- - **One-shot** (`sim run script --solver=X`): subprocess execution, result stored as a numbered run, `sim logs` to browse.
12
- - **Persistent session** (`sim serve` + `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.
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/test_lint.py # single test file
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.