sim-cli-core 0.3.4__tar.gz → 0.3.6__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 (133) hide show
  1. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/CLAUDE.md +8 -14
  2. sim_cli_core-0.3.6/PKG-INFO +419 -0
  3. sim_cli_core-0.3.6/README.md +378 -0
  4. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/docs/DEVELOPMENT.md +15 -16
  5. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/docs/architecture/version-compat.md +43 -25
  6. sim_cli_core-0.3.6/docs/plugin-install.md +204 -0
  7. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/pyproject.toml +1 -1
  8. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/_plugin_install.py +11 -11
  9. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/cli.py +0 -41
  10. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/describe.py +0 -4
  11. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_plugin_install.py +2 -2
  12. sim_cli_core-0.3.6/tests/base/test_python_floor_audit.py +127 -0
  13. sim_cli_core-0.3.6/tools/audit_python_floor.py +339 -0
  14. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/uv.lock +1 -1
  15. sim_cli_core-0.3.4/PKG-INFO +0 -362
  16. sim_cli_core-0.3.4/README.md +0 -321
  17. sim_cli_core-0.3.4/docs/README.de.md +0 -248
  18. sim_cli_core-0.3.4/docs/README.ja.md +0 -247
  19. sim_cli_core-0.3.4/docs/README.zh.md +0 -256
  20. sim_cli_core-0.3.4/docs/plugin-install.md +0 -143
  21. sim_cli_core-0.3.4/src/sim/plugin_catalog.py +0 -232
  22. sim_cli_core-0.3.4/tests/base/test_plugin_catalog.py +0 -137
  23. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/.github/workflows/publish.yml +0 -0
  24. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/.gitignore +0 -0
  25. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/CONTRIBUTING.md +0 -0
  26. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/LICENSE +0 -0
  27. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/NOTICE +0 -0
  28. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/assets/architecture.svg +0 -0
  29. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/assets/banner.svg +0 -0
  30. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/assets/logo.svg +0 -0
  31. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/docs/agent-readability.md +0 -0
  32. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/docs/architecture/multi-session-and-config.md +0 -0
  33. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/docs/architecture/skills-layering-plan.md +0 -0
  34. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/__init__.py +0 -0
  35. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/__main__.py +0 -0
  36. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/_timeout.py +0 -0
  37. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/compat.py +0 -0
  38. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/config.py +0 -0
  39. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/driver.py +0 -0
  40. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/drivers/__init__.py +0 -0
  41. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/gui/LICENSES/ATTRIBUTION.md +0 -0
  42. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/gui/__init__.py +0 -0
  43. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/gui/_pywinauto_tools.py +0 -0
  44. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/gui/_win32_dialog.py +0 -0
  45. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/history.py +0 -0
  46. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/inspect.py +0 -0
  47. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/plugins.py +0 -0
  48. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/runner.py +0 -0
  49. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/server.py +0 -0
  50. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/session.py +0 -0
  51. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/testing/__init__.py +0 -0
  52. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/src/sim/testing/protocol_conformance.py +0 -0
  53. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/__init__.py +0 -0
  54. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/__init__.py +0 -0
  55. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_cli.py +0 -0
  56. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_compat.py +0 -0
  57. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_config.py +0 -0
  58. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_connect.py +0 -0
  59. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_describe.py +0 -0
  60. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_driver_discovery.py +0 -0
  61. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_history.py +0 -0
  62. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_init_setup.py +0 -0
  63. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_lint.py +0 -0
  64. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_lint_public_corpus.py +0 -0
  65. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_logs.py +0 -0
  66. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_multi_session.py +0 -0
  67. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_plugins.py +0 -0
  68. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_protocol_conformance.py +0 -0
  69. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/base/test_run.py +0 -0
  70. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/conftest.py +0 -0
  71. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/drivers/__init__.py +0 -0
  72. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/calculix_e2e_cantilever_run.py +0 -0
  73. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/coolprop/water_props.py +0 -0
  74. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/elmer_e2e_heat_square.py +0 -0
  75. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/gmsh_e2e_sphere_mesh.py +0 -0
  76. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/lammps_e2e_lj_nvt.py +0 -0
  77. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/meshio_e2e_gmsh_to_vtk.py +0 -0
  78. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/pymfem_e2e_poisson.py +0 -0
  79. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/pyvista_e2e_sphere_stats.py +0 -0
  80. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/scikit_fem_e2e_poisson.py +0 -0
  81. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/scikitrf/short_load.py +0 -0
  82. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/execution/su2_e2e_inviscid_bump.py +0 -0
  83. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/comsol/comsol_good.py +0 -0
  84. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/comsol/comsol_no_client.py +0 -0
  85. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/comsol/comsol_no_import.py +0 -0
  86. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/hypermesh_good.py +0 -0
  87. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/hypermesh_gui.py +0 -0
  88. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/hypermesh_no_import.py +0 -0
  89. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/hypermesh_no_usage.py +0 -0
  90. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/hypermesh_syntax_error.py +0 -0
  91. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/bad_import_order.py +0 -0
  92. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/bad_no_close.py +0 -0
  93. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/bad_no_simapp.py +0 -0
  94. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/hello_world.py +0 -0
  95. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/import_franka.py +0 -0
  96. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/not_isaac.py +0 -0
  97. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/official_hello_world.py +0 -0
  98. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/replicator_cubes.py +0 -0
  99. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/syntax_error.py +0 -0
  100. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/isaac/warehouse_sdg.py +0 -0
  101. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/matlab/empty_model.mdl +0 -0
  102. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/matlab/empty_model.slx +0 -0
  103. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/matlab/matlab_ok.m +0 -0
  104. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/mfem_good.py +0 -0
  105. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/mfem_no_import.py +0 -0
  106. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/mfem_no_mesh.py +0 -0
  107. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/mfem_syntax_error.py +0 -0
  108. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/mock_fail.py +0 -0
  109. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/mock_solver.py +0 -0
  110. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/newton/basic_pendulum.json +0 -0
  111. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/newton/cable_twist.py +0 -0
  112. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/newton/robot_g1.json +0 -0
  113. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/not_simulation.py +0 -0
  114. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/pybamm/pybamm_bad_import.py +0 -0
  115. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/pybamm/pybamm_crate_sweep.py +0 -0
  116. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/pybamm/pybamm_no_solve.py +0 -0
  117. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/pybamm/pybamm_spm_good.py +0 -0
  118. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/skfem_good.py +0 -0
  119. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/skfem_no_import.py +0 -0
  120. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/skfem_no_solve.py +0 -0
  121. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/fixtures/skfem_syntax_error.py +0 -0
  122. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/gui/__init__.py +0 -0
  123. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/gui/test_connect_tools_field.py +0 -0
  124. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/gui/test_gui_facade.py +0 -0
  125. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/__init__.py +0 -0
  126. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/_extract_comsol_Tmax.py +0 -0
  127. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/test_channel_3_4_5_9.py +0 -0
  128. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/test_gui_probes.py +0 -0
  129. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/test_inspect_types.py +0 -0
  130. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/test_probes.py +0 -0
  131. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tests/inspect/test_snippet_timeout.py +0 -0
  132. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tools/extract_driver.py +0 -0
  133. {sim_cli_core-0.3.4 → sim_cli_core-0.3.6}/tools/lint-public-corpus.py +0 -0
@@ -82,12 +82,11 @@ The server supports multiple concurrent sessions keyed by session_id. Each `Sess
82
82
 
83
83
  `LintResult`, `Diagnostic`, `RunResult`, `ConnectionInfo` are dataclasses with `to_dict()` for JSON serialization.
84
84
 
85
- ### Driver registry (`src/sim/drivers/__init__.py`)
85
+ ### Driver registry (plugin entry points)
86
86
 
87
- Drivers are resolved lazily through two channels:
87
+ `sim-cli-core` is solver-agnostic and ships with no in-tree solver drivers. Drivers are provided by installed plugin packages that expose the `sim.drivers` entry-point group. Use `sim plugin list` and `sim plugin info <name>` to inspect the plugins visible in the active environment.
88
88
 
89
- - **`_BUILTIN_REGISTRY`** — an ordered list of `(name, "module:Class")` tuples for the open-source drivers that ship with `sim-cli-core` itself (PyBaMM, OpenFOAM, CalculiX, gmsh, SU2, LAMMPS, Elmer, scikit-fem, MFEM, OpenSeesPy, SfePy, OpenMDAO, FiPy, pymoo, Pyomo, SimPy, Trimesh, Devito, CoolProp, scikit-rf, pandapower, ParaView, meshio, PyVista, Newton, Isaac Sim, LTspice). The canonical list lives in `src/sim/drivers/__init__.py`.
90
- - **`sim.drivers` entry-point group** — external drivers register themselves via standard Python entry points and are discovered at import time, validated, and appended after the built-ins. Built-ins win on name collisions. Each plugin lives in its own out-of-tree package with its own `compatibility.yaml`.
89
+ Plugin implementation work belongs in the owning `sim-plugin-<solver>` repository, where the package metadata, `DriverProtocol` implementation, `compatibility.yaml`, bundled skills, and plugin tests live. Do not add solver drivers under `src/sim/drivers/<name>` in this repo.
91
90
 
92
91
  A driver may set `supports_session = True` to implement the persistent-session lifecycle (`launch`/`run`/`query`/`disconnect`); the rest are one-shot only. `get_driver(name)` looks up by `.name` attribute and lazily imports the implementation module on first use, so a broken plugin does not crash the CLI.
93
92
 
@@ -105,14 +104,11 @@ A driver may set `supports_session = True` to implement the persistent-session l
105
104
 
106
105
  Session routing rules: an explicit `X-Sim-Session` header wins (404 if unknown); otherwise the server falls back to the sole live session; otherwise `/exec` returns 400. Clients can also set `SIM_SESSION` env var or pass `sim --session <id> ...` to scope a whole CLI invocation.
107
106
 
108
- ## Adding a new driver
107
+ ## Adding or changing a solver driver
109
108
 
110
- 1. Create `src/sim/drivers/<name>/driver.py` implementing `DriverProtocol`
111
- 2. (Optional) `runtime.py` for persistent-session support
112
- 3. Register in `src/sim/drivers/__init__.py`: import and append to `DRIVERS`
113
- 4. If the driver needs server-side launch logic, extend `server.py`'s `/connect` handler accordingly
109
+ Create or update solver drivers in the owning `sim-plugin-<solver>` repository. A plugin should implement `DriverProtocol`, register the driver through `[project.entry-points."sim.drivers"]` in its `pyproject.toml`, and carry its own compatibility metadata, bundled skills, and tests.
114
110
 
115
- See `pybamm/driver.py` for the smallest reference implementation. Persistent-session examples live in the out-of-tree plugin packages.
111
+ 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.
116
112
 
117
113
  ## Test Layout
118
114
 
@@ -131,12 +127,10 @@ tests/
131
127
  test_logs.py sim logs CLI
132
128
  test_multi_session.py session routing + concurrency
133
129
  test_run.py one-shot subprocess execution
134
- drivers/ per-driver unit + integration tests for in-tree drivers
135
- fixtures/ mock solver scripts (one set per in-tree driver, plus shared mocks)
136
- execution/ optional end-to-end scripts for in-tree drivers
130
+ fixtures/ mock scripts and shared test assets
137
131
  ```
138
132
 
139
- Tests for out-of-tree plugin drivers live in their own plugin repos. Tests in this repo that require a real solver are gated by import-availability flags (e.g. `HAS_PYBAMM`) and skip gracefully when the package is missing.
133
+ Solver plugin tests live in their own plugin repos. Tests in this repo cover the shared CLI/runtime contract and plugin discovery behavior.
140
134
 
141
135
  ## Notes
142
136
 
@@ -0,0 +1,419 @@
1
+ Metadata-Version: 2.4
2
+ Name: sim-cli-core
3
+ Version: 0.3.6
4
+ Summary: Make every engineering tool agent-native — a CLI runtime that lets LLM agents launch, drive, and observe CAD/CAE software
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: tomli>=2.0; python_version < '3.11'
36
+ Requires-Dist: uvicorn>=0.34
37
+ Provides-Extra: dev
38
+ Requires-Dist: pytest>=8.0; extra == 'dev'
39
+ Requires-Dist: ruff>=0.4; extra == 'dev'
40
+ Description-Content-Type: text/markdown
41
+
42
+ <div align="center">
43
+
44
+ <img src="assets/banner.svg" alt="sim — agent runtime for physics simulations" width="820">
45
+
46
+ <br>
47
+
48
+ **sim-cli lets AI agents operate CAE solvers one verified step at a time.**
49
+
50
+ `sim` is an open-source CLI and local runtime that lets Codex, Claude Code,
51
+ GitHub Copilot, Gemini, and other agents work with simulation software through
52
+ solver-specific plugins and bundled skills. An agent can check what is
53
+ installed, connect to a solver, inspect live state, execute bounded modeling
54
+ or analysis steps, verify result/state, and save checkpoints/artifacts for
55
+ engineering review.
56
+
57
+ <p align="center">
58
+ <a href="#quick-start-agent-setup"><img src="https://img.shields.io/badge/Quick_Start-agent_setup-3b82f6?style=for-the-badge" alt="Quick Start"></a>
59
+ <a href="#solver-plugins"><img src="https://img.shields.io/badge/Solvers-plugin_based-22c55e?style=for-the-badge" alt="Solver plugins"></a>
60
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-eab308?style=for-the-badge" alt="License"></a>
61
+ </p>
62
+
63
+ <p align="center">
64
+ <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+">
65
+ <img src="https://img.shields.io/badge/CLI-Click_8-blue" alt="Click">
66
+ <img src="https://img.shields.io/badge/server-FastAPI-009688?logo=fastapi&logoColor=white" alt="FastAPI">
67
+ <img src="https://img.shields.io/badge/transport-HTTP%2FJSON-orange" alt="HTTP/JSON">
68
+ <img src="https://img.shields.io/badge/status-alpha-f97316" alt="Status: alpha">
69
+ </p>
70
+
71
+ [Quick Start](#quick-start-agent-setup) · [COMSOL + Codex](#example-comsol-and-codex-on-one-machine) · [Agent Loop](#the-agent-loop) · [Remote Solvers](#local-vs-remote-solvers) · [Plugins](#solver-plugins) · [Commands](#common-commands)
72
+
73
+ </div>
74
+
75
+ ---
76
+
77
+ ## Who this is for
78
+
79
+ `sim` is for agents and people trying to get real simulation work done.
80
+
81
+ - **CAE engineers who already script solvers** and want an agent to help
82
+ automate COMSOL, Fluent, MATLAB, LTspice, Abaqus, HFSS, and similar tools
83
+ without losing inspection and recovery between steps.
84
+ - **Design engineers and occasional simulation users** who have agent
85
+ experience and want an agent-assisted workflow: ask for a simulation, watch
86
+ the model evolve, review screenshots or plots, and keep final artifacts.
87
+ - **AI agents** reading this repository to learn the safe setup and operating
88
+ loop before touching a solver.
89
+ - **Engineering leaders** evaluating whether agent-assisted simulation can be
90
+ repeatable, reviewable, and compatible with existing solver installations.
91
+
92
+ Plugin authoring, runtime internals, and driver protocol details live in
93
+ [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
94
+
95
+ ## What sim gives an agent
96
+
97
+ LLMs can often write solver scripts, but a one-shot script is a weak workflow:
98
+ it hides intermediate state, fails late, and makes recovery difficult.
99
+
100
+ `sim` gives an agent a small, repeatable control surface:
101
+
102
+ ```text
103
+ check readiness → attach to live session → inspect model state
104
+ → run one bounded CAE step → verify result/state → save checkpoint/artifacts
105
+ ```
106
+
107
+ A bounded CAE step is one small modeling, meshing, solving, or postprocessing
108
+ action that can be inspected and verified before continuing. Examples: create a
109
+ geometry feature, assign a material, apply a boundary condition, generate a
110
+ mesh, run one study, extract a probe value, create a plot, or export a result
111
+ table.
112
+
113
+ The solver-specific knowledge is not baked into the core CLI. It comes from
114
+ plugins. A plugin can provide both:
115
+
116
+ - a **driver**, so `sim` can launch or talk to the solver
117
+ - a **skill**, so the agent knows the solver-specific workflow, pitfalls, and
118
+ inspection rules
119
+
120
+ ## Human-in-the-loop collaboration
121
+
122
+ `sim` is designed for shared control, not unattended black-box automation.
123
+ When a solver plugin exposes live state through `sim inspect`, the agent can
124
+ re-read the current solver session after each meaningful step. That means an
125
+ engineer can cut in through the solver GUI, change geometry, parameters,
126
+ boundary conditions, plots, or saved artifacts, then ask the agent to inspect
127
+ again and continue from the real current state.
128
+
129
+ This is the collaboration model: the human can watch, correct, and steer; the
130
+ agent keeps using inspection and checkpoints instead of assuming its previous
131
+ script still matches the real solver state.
132
+
133
+ ## Quick Start: agent setup
134
+
135
+ Use this path when the agent and solver are on the same machine. You do not
136
+ need to start `sim serve` manually for the local happy path; `sim connect`
137
+ will use the local runtime. The default docs use
138
+ [`uv`](https://docs.astral.sh/uv/) so agents run the `sim` and plugins declared
139
+ by the current project instead of guessing which executable is on `PATH`.
140
+
141
+ `uv run sim ...` runs `sim` from this project environment, so it sees this
142
+ project's installed solver plugins. Run from the project root:
143
+
144
+ ```bash
145
+ uv init # only if this is not already a uv project
146
+ uv add sim-cli-core sim-plugin-comsol
147
+ uv run sim plugin sync-skills --target .agents/skills --copy
148
+ uv run sim check comsol
149
+ uv run sim plugin doctor comsol --deep
150
+ ```
151
+
152
+ Use `.agents/skills` for Codex and GitHub Copilot projects. For Claude Code,
153
+ sync to `.claude/skills` instead:
154
+
155
+ ```bash
156
+ uv run sim plugin sync-skills --target .claude/skills --copy
157
+ ```
158
+
159
+ ### Without uv
160
+
161
+ If you cannot use `uv`, create a normal Python virtual environment, install
162
+ `sim-cli-core` and the solver plugin into that environment, then run `sim`
163
+ from the activated environment.
164
+
165
+ macOS/Linux:
166
+
167
+ ```bash
168
+ python -m venv .venv
169
+ source .venv/bin/activate
170
+ python -m pip install --upgrade pip
171
+ python -m pip install sim-cli-core sim-plugin-comsol
172
+ sim plugin sync-skills --target .agents/skills --copy
173
+ sim check comsol
174
+ sim plugin doctor comsol --deep
175
+ ```
176
+
177
+ Windows PowerShell:
178
+
179
+ ```powershell
180
+ py -m venv .venv
181
+ .\.venv\Scripts\Activate.ps1
182
+ python -m pip install --upgrade pip
183
+ python -m pip install sim-cli-core sim-plugin-comsol
184
+ sim plugin sync-skills --target .agents/skills --copy
185
+ sim check comsol
186
+ sim plugin doctor comsol --deep
187
+ ```
188
+
189
+ ## Hand this prompt to your agent
190
+
191
+ After setup, give your coding agent a direct instruction like this:
192
+
193
+ ```text
194
+ Use the installed solver skill. Run sim through this project with
195
+ `uv run sim ...`. Check my local solver installation before connecting. Work
196
+ one bounded step at a time: connect, inspect the session, execute a small step,
197
+ inspect last.result and the live model state, then save or update a checkpoint
198
+ before continuing. Do not guess solver API names; inspect the live model or the
199
+ solver's local docs first. If I make manual changes in the solver UI,
200
+ re-inspect the live state before continuing instead of assuming your previous
201
+ script still matches the model. Report saved artifacts, numerical checks,
202
+ warnings, and anything that still needs human engineering review.
203
+ ```
204
+
205
+ ## Example: COMSOL and Codex on one machine
206
+
207
+ If COMSOL and Codex are on the same machine, start by installing the COMSOL
208
+ plugin and syncing its bundled skill into the `.agents/skills` project target:
209
+
210
+ ```bash
211
+ uv add sim-cli-core sim-plugin-comsol
212
+ uv run sim plugin sync-skills --target .agents/skills --copy
213
+ uv run sim check comsol
214
+ uv run sim plugin doctor comsol --deep
215
+ ```
216
+
217
+ Then ask Codex:
218
+
219
+ ```text
220
+ Use the installed COMSOL skill. Start by checking COMSOL through `uv run sim
221
+ check comsol`. If you need a visible live COMSOL Desktop session, use:
222
+
223
+ uv run sim connect --solver comsol --ui-mode gui --driver-option visual_mode=shared-desktop
224
+
225
+ After connecting, inspect session.health and comsol.model.identity. Confirm the
226
+ live model binding is healthy before treating the GUI as synchronized. For
227
+ non-trivial work, establish a case folder and save .mph checkpoints after major
228
+ layers. Build and solve one bounded step at a time.
229
+ ```
230
+
231
+ For COMSOL-specific details such as shared Desktop mode, offline `.mph`
232
+ inspection, Desktop attach fallback, model identity checks, and checkpoint
233
+ policy, follow the bundled COMSOL skill.
234
+
235
+ ## Why CLI-first?
236
+
237
+ sim-cli is CLI-first because engineering simulation is file-based,
238
+ scriptable, local, artifact-heavy, and long-running.
239
+
240
+ CAE agents need to work with solver executables, model files,
241
+ Python/Java/journal scripts, shell commands, logs, checkpoints, plots,
242
+ and artifacts. A CLI command surface composes with all of that and
243
+ matches how Codex CLI, Claude Code, and other coding agents already
244
+ operate.
245
+
246
+ MCP is useful for API-style integrations and remote tool discovery,
247
+ but a broad MCP surface can add context overhead and wrapper
248
+ maintenance. For COMSOL, Abaqus, Ansys Workbench, OpenFOAM, LTspice,
249
+ and similar solvers, sim-cli keeps the source of truth as a small,
250
+ auditable command loop:
251
+
252
+ ```text
253
+ check readiness → attach to live session → inspect model state
254
+ → run one bounded CAE step → verify result/state → save checkpoint/artifacts
255
+ ```
256
+
257
+ Solver plugins provide solver-specific behavior. Agent skills teach
258
+ Codex, Claude Code, and other agents when and how to use the CLI
259
+ safely.
260
+
261
+ ## The agent loop
262
+
263
+ For any solver, the agent should prefer this loop over one large generated
264
+ script:
265
+
266
+ 1. `uv run sim check <solver>` to detect installed solver versions and plugin
267
+ compatibility.
268
+ 2. `uv run sim connect --solver <solver> ...` for live stateful work, or
269
+ `uv run sim run` for a deterministic one-shot script.
270
+ 3. `uv run sim inspect session.versions` and the solver-specific health or
271
+ identity target before changing state.
272
+ 4. `uv run sim exec --file step.py --label <step>` for one bounded modeling
273
+ or analysis step.
274
+ 5. `uv run sim inspect last.result` and solver-specific state.
275
+ 6. Verify the result/state using solver-specific numerical evidence when available.
276
+ 7. Save checkpoints and artifacts when the solver plugin or skill requires
277
+ them.
278
+ 8. `uv run sim disconnect` when the session is done.
279
+
280
+ Screenshots and plots help humans review the result, but engineering
281
+ acceptance should prefer numeric evidence when the solver skill defines it:
282
+ mesh statistics, convergence, finite probes, conservation checks, tolerances,
283
+ or expected trends.
284
+
285
+ ## Local vs remote solvers
286
+
287
+ **Same machine:** install `sim-cli-core` and the solver plugin into the project
288
+ environment, sync the skill to your agent, then use `uv run sim connect`. Do
289
+ not add `--host` unless you are intentionally talking to a remote `sim serve`.
290
+
291
+ **Remote solver workstation, lab box, or HPC login node:** install
292
+ `sim-cli-core` and the solver plugin on the solver host, start `sim serve`
293
+ there, then point the local agent at that host:
294
+
295
+ ```bash
296
+ # On the solver host.
297
+ uv run sim serve --host 0.0.0.0 --port 7600
298
+
299
+ # On the agent/control machine.
300
+ uv run sim --host <solver-host-ip> check <solver>
301
+ uv run sim --host <solver-host-ip> connect --solver <solver>
302
+ uv run sim --host <solver-host-ip> inspect session.summary
303
+ uv run sim --host <solver-host-ip> disconnect
304
+ ```
305
+
306
+ Only bind `sim serve` to a trusted network such as a VPN, Tailscale, or a
307
+ protected LAN. The runtime currently has no auth layer, and `/connect` plus
308
+ `/exec` can execute solver-side code.
309
+
310
+ ## Solver plugins
311
+
312
+ `sim-cli-core` ships with no solver drivers built in. Each simulation solver is
313
+ reached through an explicit plugin package.
314
+
315
+ A few representative plugins:
316
+
317
+ | Solver | Package spec | Plugin repo |
318
+ | --- | --- | --- |
319
+ | COMSOL | `sim-plugin-comsol` | [sim-plugin-comsol](https://github.com/svd-ai-lab/sim-plugin-comsol) |
320
+ | Abaqus | `sim-plugin-abaqus` | [sim-plugin-abaqus](https://github.com/svd-ai-lab/sim-plugin-abaqus) |
321
+ | Ansys Workbench | `sim-plugin-workbench` | [sim-plugin-workbench](https://github.com/svd-ai-lab/sim-plugin-workbench) |
322
+ | Autodesk Fusion 360 | _in development_ | [sim-plugin-fusion360](https://github.com/svd-ai-lab/sim-plugin-fusion360) |
323
+ | LTspice | `sim-plugin-ltspice` | [sim-plugin-ltspice](https://github.com/svd-ai-lab/sim-plugin-ltspice) |
324
+
325
+ For the curated full list, see [sim-plugin-index](https://github.com/svd-ai-lab/sim-plugin-index).
326
+
327
+ After adding any plugin package, sync its bundled skill and verify that the local
328
+ solver can be reached:
329
+
330
+ ```bash
331
+ uv run sim plugin list
332
+
333
+ # Codex or Copilot
334
+ uv run sim plugin sync-skills --target .agents/skills --copy
335
+
336
+ # Claude Code
337
+ uv run sim plugin sync-skills --target .claude/skills --copy
338
+
339
+ uv run sim check <solver>
340
+ uv run sim plugin doctor <solver> --deep
341
+ ```
342
+
343
+ For direct wheel, Git, local checkout, or non-uv workflows, see
344
+ [docs/plugin-install.md](docs/plugin-install.md).
345
+
346
+ ## Project setup with sim.toml
347
+
348
+ For reproducible Python packages, commit the `pyproject.toml` and `uv.lock`
349
+ created by `uv add`. Use `sim.toml` for solver defaults and workspace settings:
350
+
351
+ ```bash
352
+ uv run sim init
353
+ ```
354
+
355
+ Example:
356
+
357
+ ```toml
358
+ [sim]
359
+ default_solver = "comsol"
360
+ workspace = "./workspace"
361
+
362
+ [[sim.plugins]]
363
+ name = "comsol"
364
+ package = "sim-plugin-comsol"
365
+ ```
366
+
367
+ Then a fresh checkout can run:
368
+
369
+ ```bash
370
+ uv sync
371
+ uv run sim setup --dry-run
372
+
373
+ # Codex or Copilot
374
+ uv run sim plugin sync-skills --target .agents/skills --copy
375
+
376
+ # Claude Code
377
+ uv run sim plugin sync-skills --target .claude/skills --copy
378
+ ```
379
+
380
+ ## Common commands
381
+
382
+ | Command | Use it for |
383
+ |---|---|
384
+ | `uv run sim plugin list` | Show plugins visible in this project environment. |
385
+ | `uv run sim plugin info <solver>` | Show plugin metadata and compatibility summary. |
386
+ | `uv run sim plugin doctor <solver> --deep` | Check plugin wiring plus local solver detection. |
387
+ | `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for Codex or Copilot. |
388
+ | `uv run sim plugin sync-skills --target .claude/skills --copy` | Materialize installed plugin skills for Claude Code. |
389
+ | `uv run sim check <solver>` | Detect local or remote solver installs. |
390
+ | `uv run sim connect --solver <solver>` | Open a persistent solver session. |
391
+ | `uv run sim exec --file step.py` | Run one bounded step in the live session. |
392
+ | `uv run sim inspect <target>` | Query session, result, or solver-specific state. |
393
+ | `uv run sim run script.py --solver <solver>` | Run a deterministic one-shot script. |
394
+ | `uv run sim disconnect` | Tear down the active session. |
395
+ | `uv run sim setup` | Apply plugin declarations from `sim.toml` when you use them. |
396
+
397
+ Run `uv run sim describe` for a machine-readable command manifest, or
398
+ `uv run sim <command> --help` for exact options.
399
+
400
+ ## Solver ownership
401
+
402
+ `sim-cli` does not bundle or redistribute simulation solvers or vendor SDKs.
403
+ Install and operate each underlying solver according to its vendor terms. See
404
+ [NOTICE](NOTICE) for optional SDK dependency notes.
405
+
406
+ `sim-cli` is an independent open-source project and is not affiliated with,
407
+ endorsed by, or sponsored by any solver vendor. Product, solver, and company
408
+ names remain the property of their respective owners.
409
+
410
+ ## Developer docs
411
+
412
+ - [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - project setup, layout, driver
413
+ development, and architecture notes
414
+ - [docs/plugin-install.md](docs/plugin-install.md) - plugin installation
415
+ reference
416
+
417
+ ## License
418
+
419
+ Apache-2.0 - see [LICENSE](LICENSE).