sim-cli-core 0.3.4__tar.gz → 0.3.5__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.5}/CLAUDE.md +8 -14
  2. sim_cli_core-0.3.5/PKG-INFO +390 -0
  3. sim_cli_core-0.3.5/README.md +349 -0
  4. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/docs/DEVELOPMENT.md +15 -15
  5. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/docs/architecture/version-compat.md +43 -25
  6. sim_cli_core-0.3.5/docs/plugin-install.md +210 -0
  7. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/pyproject.toml +1 -1
  8. sim_cli_core-0.3.5/tests/base/test_python_floor_audit.py +127 -0
  9. sim_cli_core-0.3.5/tools/audit_python_floor.py +339 -0
  10. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/uv.lock +1 -1
  11. sim_cli_core-0.3.4/PKG-INFO +0 -362
  12. sim_cli_core-0.3.4/README.md +0 -321
  13. sim_cli_core-0.3.4/docs/README.de.md +0 -248
  14. sim_cli_core-0.3.4/docs/README.ja.md +0 -247
  15. sim_cli_core-0.3.4/docs/README.zh.md +0 -256
  16. sim_cli_core-0.3.4/docs/plugin-install.md +0 -143
  17. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/.github/workflows/publish.yml +0 -0
  18. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/.gitignore +0 -0
  19. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/CONTRIBUTING.md +0 -0
  20. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/LICENSE +0 -0
  21. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/NOTICE +0 -0
  22. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/assets/architecture.svg +0 -0
  23. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/assets/banner.svg +0 -0
  24. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/assets/logo.svg +0 -0
  25. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/docs/agent-readability.md +0 -0
  26. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/docs/architecture/multi-session-and-config.md +0 -0
  27. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/docs/architecture/skills-layering-plan.md +0 -0
  28. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/__init__.py +0 -0
  29. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/__main__.py +0 -0
  30. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/_plugin_install.py +0 -0
  31. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/_timeout.py +0 -0
  32. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/cli.py +0 -0
  33. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/compat.py +0 -0
  34. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/config.py +0 -0
  35. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/describe.py +0 -0
  36. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/driver.py +0 -0
  37. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/drivers/__init__.py +0 -0
  38. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/gui/LICENSES/ATTRIBUTION.md +0 -0
  39. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/gui/__init__.py +0 -0
  40. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/gui/_pywinauto_tools.py +0 -0
  41. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/gui/_win32_dialog.py +0 -0
  42. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/history.py +0 -0
  43. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/inspect.py +0 -0
  44. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/plugin_catalog.py +0 -0
  45. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/plugins.py +0 -0
  46. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/runner.py +0 -0
  47. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/server.py +0 -0
  48. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/session.py +0 -0
  49. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/testing/__init__.py +0 -0
  50. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/src/sim/testing/protocol_conformance.py +0 -0
  51. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/__init__.py +0 -0
  52. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/__init__.py +0 -0
  53. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_cli.py +0 -0
  54. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_compat.py +0 -0
  55. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_config.py +0 -0
  56. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_connect.py +0 -0
  57. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_describe.py +0 -0
  58. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_driver_discovery.py +0 -0
  59. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_history.py +0 -0
  60. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_init_setup.py +0 -0
  61. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_lint.py +0 -0
  62. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_lint_public_corpus.py +0 -0
  63. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_logs.py +0 -0
  64. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_multi_session.py +0 -0
  65. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_plugin_catalog.py +0 -0
  66. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_plugin_install.py +0 -0
  67. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_plugins.py +0 -0
  68. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_protocol_conformance.py +0 -0
  69. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/base/test_run.py +0 -0
  70. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/conftest.py +0 -0
  71. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/drivers/__init__.py +0 -0
  72. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/calculix_e2e_cantilever_run.py +0 -0
  73. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/coolprop/water_props.py +0 -0
  74. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/elmer_e2e_heat_square.py +0 -0
  75. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/gmsh_e2e_sphere_mesh.py +0 -0
  76. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/lammps_e2e_lj_nvt.py +0 -0
  77. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/meshio_e2e_gmsh_to_vtk.py +0 -0
  78. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/pymfem_e2e_poisson.py +0 -0
  79. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/pyvista_e2e_sphere_stats.py +0 -0
  80. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/scikit_fem_e2e_poisson.py +0 -0
  81. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/scikitrf/short_load.py +0 -0
  82. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/execution/su2_e2e_inviscid_bump.py +0 -0
  83. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/comsol/comsol_good.py +0 -0
  84. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/comsol/comsol_no_client.py +0 -0
  85. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/comsol/comsol_no_import.py +0 -0
  86. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/hypermesh_good.py +0 -0
  87. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/hypermesh_gui.py +0 -0
  88. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/hypermesh_no_import.py +0 -0
  89. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/hypermesh_no_usage.py +0 -0
  90. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/hypermesh_syntax_error.py +0 -0
  91. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/bad_import_order.py +0 -0
  92. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/bad_no_close.py +0 -0
  93. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/bad_no_simapp.py +0 -0
  94. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/hello_world.py +0 -0
  95. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/import_franka.py +0 -0
  96. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/not_isaac.py +0 -0
  97. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/official_hello_world.py +0 -0
  98. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/replicator_cubes.py +0 -0
  99. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/syntax_error.py +0 -0
  100. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/isaac/warehouse_sdg.py +0 -0
  101. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/matlab/empty_model.mdl +0 -0
  102. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/matlab/empty_model.slx +0 -0
  103. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/matlab/matlab_ok.m +0 -0
  104. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/mfem_good.py +0 -0
  105. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/mfem_no_import.py +0 -0
  106. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/mfem_no_mesh.py +0 -0
  107. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/mfem_syntax_error.py +0 -0
  108. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/mock_fail.py +0 -0
  109. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/mock_solver.py +0 -0
  110. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/newton/basic_pendulum.json +0 -0
  111. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/newton/cable_twist.py +0 -0
  112. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/newton/robot_g1.json +0 -0
  113. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/not_simulation.py +0 -0
  114. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/pybamm/pybamm_bad_import.py +0 -0
  115. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/pybamm/pybamm_crate_sweep.py +0 -0
  116. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/pybamm/pybamm_no_solve.py +0 -0
  117. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/pybamm/pybamm_spm_good.py +0 -0
  118. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/skfem_good.py +0 -0
  119. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/skfem_no_import.py +0 -0
  120. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/skfem_no_solve.py +0 -0
  121. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/fixtures/skfem_syntax_error.py +0 -0
  122. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/gui/__init__.py +0 -0
  123. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/gui/test_connect_tools_field.py +0 -0
  124. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/gui/test_gui_facade.py +0 -0
  125. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/__init__.py +0 -0
  126. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/_extract_comsol_Tmax.py +0 -0
  127. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/test_channel_3_4_5_9.py +0 -0
  128. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/test_gui_probes.py +0 -0
  129. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/test_inspect_types.py +0 -0
  130. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/test_probes.py +0 -0
  131. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tests/inspect/test_snippet_timeout.py +0 -0
  132. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/tools/extract_driver.py +0 -0
  133. {sim_cli_core-0.3.4 → sim_cli_core-0.3.5}/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,390 @@
1
+ Metadata-Version: 2.4
2
+ Name: sim-cli-core
3
+ Version: 0.3.5
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
+ **Let AI agents operate real CAE and physics solvers step by step.**
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 steps,
54
+ capture artifacts, and leave checkpoints for an engineer to review.
55
+
56
+ <p align="center">
57
+ <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>
58
+ <a href="#solver-plugins"><img src="https://img.shields.io/badge/Solvers-plugin_based-22c55e?style=for-the-badge" alt="Solver plugins"></a>
59
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-eab308?style=for-the-badge" alt="License"></a>
60
+ </p>
61
+
62
+ <p align="center">
63
+ <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+">
64
+ <img src="https://img.shields.io/badge/CLI-Click_8-blue" alt="Click">
65
+ <img src="https://img.shields.io/badge/server-FastAPI-009688?logo=fastapi&logoColor=white" alt="FastAPI">
66
+ <img src="https://img.shields.io/badge/transport-HTTP%2FJSON-orange" alt="HTTP/JSON">
67
+ <img src="https://img.shields.io/badge/status-alpha-f97316" alt="Status: alpha">
68
+ </p>
69
+
70
+ [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)
71
+
72
+ </div>
73
+
74
+ ---
75
+
76
+ ## Who this is for
77
+
78
+ `sim` is for agents and people trying to get real simulation work done.
79
+
80
+ - **CAE engineers who already script solvers** and want an agent to help
81
+ automate COMSOL, Fluent, MATLAB, LTspice, Abaqus, HFSS, and similar tools
82
+ without losing inspection and recovery between steps.
83
+ - **Design engineers and occasional simulation users** who have agent
84
+ experience and want a "vibe CAE" workflow: ask for a simulation, watch the
85
+ model evolve, review screenshots or plots, and keep final artifacts.
86
+ - **AI agents** reading this repository to learn the safe setup and operating
87
+ loop before touching a solver.
88
+ - **Engineering leaders** evaluating whether agent-assisted simulation can be
89
+ repeatable, reviewable, and compatible with existing solver installations.
90
+
91
+ Plugin authoring, runtime internals, and driver protocol details live in
92
+ [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
93
+
94
+ ## What sim gives an agent
95
+
96
+ LLMs can often write solver scripts, but a one-shot script is a weak workflow:
97
+ it hides intermediate state, fails late, and makes recovery difficult.
98
+
99
+ `sim` gives an agent a small, repeatable control surface:
100
+
101
+ ```text
102
+ check solver -> connect -> inspect -> execute one bounded step
103
+ -> inspect result/state -> save artifact or checkpoint -> continue
104
+ ```
105
+
106
+ The solver-specific knowledge is not baked into the core CLI. It comes from
107
+ plugins. A plugin can provide both:
108
+
109
+ - a **driver**, so `sim` can launch or talk to the solver
110
+ - a **skill**, so the agent knows the solver-specific workflow, pitfalls, and
111
+ inspection rules
112
+
113
+ ## Human-in-the-loop collaboration
114
+
115
+ `sim` is designed for shared control, not unattended black-box automation.
116
+ When a solver plugin exposes live state through `sim inspect`, the agent can
117
+ re-read the current solver session after each meaningful step. That means an
118
+ engineer can cut in through the solver GUI, change geometry, parameters,
119
+ boundary conditions, plots, or saved artifacts, then ask the agent to inspect
120
+ again and continue from the real current state.
121
+
122
+ This is the collaboration model: the human can watch, correct, and steer; the
123
+ agent keeps using inspection and checkpoints instead of assuming its previous
124
+ script still matches the real solver state.
125
+
126
+ ## Quick Start: agent setup
127
+
128
+ Use this path when the agent and solver are on the same machine. You do not
129
+ need to start `sim serve` manually for the local happy path; `sim connect`
130
+ will use the local runtime. The default docs use
131
+ [`uv`](https://docs.astral.sh/uv/) so agents run the `sim` and plugins declared
132
+ by the current project instead of guessing which executable is on `PATH`.
133
+
134
+ `uv run sim ...` runs `sim` from this project environment, so it sees this
135
+ project's installed solver plugins. Run from the project root:
136
+
137
+ ```bash
138
+ uv init # only if this is not already a uv project
139
+ uv add sim-cli-core sim-plugin-comsol
140
+ uv run sim plugin sync-skills --target .agents/skills --copy
141
+ uv run sim check comsol
142
+ uv run sim plugin doctor comsol --deep
143
+ ```
144
+
145
+ Use `.agents/skills` for Codex and GitHub Copilot projects. For Claude Code,
146
+ sync to `.claude/skills` instead:
147
+
148
+ ```bash
149
+ uv run sim plugin sync-skills --target .claude/skills --copy
150
+ ```
151
+
152
+ ### Without uv
153
+
154
+ If you cannot use `uv`, create a normal Python virtual environment, install
155
+ `sim-cli-core` and the solver plugin into that environment, then run `sim`
156
+ from the activated environment.
157
+
158
+ macOS/Linux:
159
+
160
+ ```bash
161
+ python -m venv .venv
162
+ source .venv/bin/activate
163
+ python -m pip install --upgrade pip
164
+ python -m pip install sim-cli-core sim-plugin-comsol
165
+ sim plugin sync-skills --target .agents/skills --copy
166
+ sim check comsol
167
+ sim plugin doctor comsol --deep
168
+ ```
169
+
170
+ Windows PowerShell:
171
+
172
+ ```powershell
173
+ py -m venv .venv
174
+ .\.venv\Scripts\Activate.ps1
175
+ python -m pip install --upgrade pip
176
+ python -m pip install sim-cli-core sim-plugin-comsol
177
+ sim plugin sync-skills --target .agents/skills --copy
178
+ sim check comsol
179
+ sim plugin doctor comsol --deep
180
+ ```
181
+
182
+ ## Hand this prompt to your agent
183
+
184
+ After setup, give your coding agent a direct instruction like this:
185
+
186
+ ```text
187
+ Use the installed solver skill. Run sim through this project with
188
+ `uv run sim ...`. Check my local solver installation before connecting. Work
189
+ one bounded step at a time: connect, inspect the session, execute a small step,
190
+ inspect last.result and the live model state, then save or update a checkpoint
191
+ before continuing. Do not guess solver API names; inspect the live model or the
192
+ solver's local docs first. If I make manual changes in the solver UI,
193
+ re-inspect the live state before continuing instead of assuming your previous
194
+ script still matches the model. Report saved artifacts, numerical checks,
195
+ warnings, and anything that still needs human engineering review.
196
+ ```
197
+
198
+ ## Example: COMSOL and Codex on one machine
199
+
200
+ If COMSOL and Codex are on the same machine, start by installing the COMSOL
201
+ plugin and syncing its bundled skill into the `.agents/skills` project target:
202
+
203
+ ```bash
204
+ uv add sim-cli-core sim-plugin-comsol
205
+ uv run sim plugin sync-skills --target .agents/skills --copy
206
+ uv run sim check comsol
207
+ uv run sim plugin doctor comsol --deep
208
+ ```
209
+
210
+ Then ask Codex:
211
+
212
+ ```text
213
+ Use the installed COMSOL skill. Start by checking COMSOL through `uv run sim
214
+ check comsol`. If you need a visible live COMSOL Desktop session, use:
215
+
216
+ uv run sim connect --solver comsol --ui-mode gui --driver-option visual_mode=shared-desktop
217
+
218
+ After connecting, inspect session.health and comsol.model.identity. Confirm the
219
+ live model binding is healthy before treating the GUI as synchronized. For
220
+ non-trivial work, establish a case folder and save .mph checkpoints after major
221
+ layers. Build and solve one bounded step at a time.
222
+ ```
223
+
224
+ For COMSOL-specific details such as shared Desktop mode, offline `.mph`
225
+ inspection, Desktop attach fallback, model identity checks, and checkpoint
226
+ policy, follow the bundled COMSOL skill.
227
+
228
+ ## The agent loop
229
+
230
+ For any solver, the agent should prefer this loop over one large generated
231
+ script:
232
+
233
+ 1. `uv run sim check <solver>` to detect installed solver versions and plugin
234
+ compatibility.
235
+ 2. `uv run sim connect --solver <solver> ...` for live stateful work, or
236
+ `uv run sim run` for a deterministic one-shot script.
237
+ 3. `uv run sim inspect session.versions` and the solver-specific health or
238
+ identity target before changing state.
239
+ 4. `uv run sim exec --file step.py --label <step>` for one bounded modeling
240
+ or analysis step.
241
+ 5. `uv run sim inspect last.result` and solver-specific state before
242
+ continuing.
243
+ 6. Save checkpoints and artifacts when the solver plugin or skill requires
244
+ them.
245
+ 7. `uv run sim disconnect` when the session is done.
246
+
247
+ Screenshots and plots help humans review the result, but engineering
248
+ acceptance should prefer numeric evidence when the solver skill defines it:
249
+ mesh statistics, convergence, finite probes, conservation checks, tolerances,
250
+ or expected trends.
251
+
252
+ ## Local vs remote solvers
253
+
254
+ **Same machine:** install `sim-cli-core` and the solver plugin into the project
255
+ environment, sync the skill to your agent, then use `uv run sim connect`. Do
256
+ not add `--host` unless you are intentionally talking to a remote `sim serve`.
257
+
258
+ **Remote solver workstation, lab box, or HPC login node:** install
259
+ `sim-cli-core` and the solver plugin on the solver host, start `sim serve`
260
+ there, then point the local agent at that host:
261
+
262
+ ```bash
263
+ # On the solver host.
264
+ uv run sim serve --host 0.0.0.0 --port 7600
265
+
266
+ # On the agent/control machine.
267
+ uv run sim --host <solver-host-ip> check <solver>
268
+ uv run sim --host <solver-host-ip> connect --solver <solver>
269
+ uv run sim --host <solver-host-ip> inspect session.summary
270
+ uv run sim --host <solver-host-ip> disconnect
271
+ ```
272
+
273
+ Only bind `sim serve` to a trusted network such as a VPN, Tailscale, or a
274
+ protected LAN. The runtime currently has no auth layer, and `/connect` plus
275
+ `/exec` can execute solver-side code.
276
+
277
+ ## Solver plugins
278
+
279
+ `sim-cli-core` ships with no solver drivers built in. Each simulation solver is
280
+ reached through an explicit plugin package.
281
+
282
+ Ready-to-use plugins:
283
+
284
+ | Solver | Package spec |
285
+ | --- | --- |
286
+ | COMSOL | `sim-plugin-comsol` |
287
+ | MATLAB / Simulink | `git+https://github.com/svd-ai-lab/sim-plugin-matlab@main` |
288
+ | Ansys Workbench | `sim-plugin-workbench` |
289
+ | Ansys Mechanical | `sim-plugin-mechanical` |
290
+ | Ansys Fluent | `sim-plugin-fluent` |
291
+ | Ansys HFSS | `sim-plugin-hfss` |
292
+ | Abaqus | `sim-plugin-abaqus` |
293
+ | LTspice | `sim-plugin-ltspice` |
294
+ | OpenFOAM | `git+https://github.com/svd-ai-lab/sim-plugin-openfoam@main` |
295
+
296
+ Under development: Amesim, Dymola, and Flotherm.
297
+
298
+ After adding any plugin package, sync its bundled skill and verify that the local
299
+ solver can be reached:
300
+
301
+ ```bash
302
+ uv run sim plugin list
303
+
304
+ # Codex or Copilot
305
+ uv run sim plugin sync-skills --target .agents/skills --copy
306
+
307
+ # Claude Code
308
+ uv run sim plugin sync-skills --target .claude/skills --copy
309
+
310
+ uv run sim check <solver>
311
+ uv run sim plugin doctor <solver> --deep
312
+ ```
313
+
314
+ For direct wheel, Git, local checkout, or non-uv workflows, see
315
+ [docs/plugin-install.md](docs/plugin-install.md).
316
+
317
+ ## Project setup with sim.toml
318
+
319
+ For reproducible Python packages, commit the `pyproject.toml` and `uv.lock`
320
+ created by `uv add`. Use `sim.toml` for solver defaults and workspace settings:
321
+
322
+ ```bash
323
+ uv run sim init
324
+ ```
325
+
326
+ Example:
327
+
328
+ ```toml
329
+ [sim]
330
+ default_solver = "comsol"
331
+ workspace = "./workspace"
332
+
333
+ [[sim.plugins]]
334
+ name = "comsol"
335
+ package = "sim-plugin-comsol"
336
+ ```
337
+
338
+ Then a fresh checkout can run:
339
+
340
+ ```bash
341
+ uv sync
342
+ uv run sim setup --dry-run
343
+
344
+ # Codex or Copilot
345
+ uv run sim plugin sync-skills --target .agents/skills --copy
346
+
347
+ # Claude Code
348
+ uv run sim plugin sync-skills --target .claude/skills --copy
349
+ ```
350
+
351
+ ## Common commands
352
+
353
+ | Command | Use it for |
354
+ |---|---|
355
+ | `uv run sim plugin list` | Show plugins visible in this project environment. |
356
+ | `uv run sim plugin info <solver>` | Show plugin metadata and compatibility summary. |
357
+ | `uv run sim plugin doctor <solver> --deep` | Check plugin wiring plus local solver detection. |
358
+ | `uv run sim plugin sync-skills --target .agents/skills --copy` | Materialize installed plugin skills for Codex or Copilot. |
359
+ | `uv run sim plugin sync-skills --target .claude/skills --copy` | Materialize installed plugin skills for Claude Code. |
360
+ | `uv run sim check <solver>` | Detect local or remote solver installs. |
361
+ | `uv run sim connect --solver <solver>` | Open a persistent solver session. |
362
+ | `uv run sim exec --file step.py` | Run one bounded step in the live session. |
363
+ | `uv run sim inspect <target>` | Query session, result, or solver-specific state. |
364
+ | `uv run sim run script.py --solver <solver>` | Run a deterministic one-shot script. |
365
+ | `uv run sim disconnect` | Tear down the active session. |
366
+ | `uv run sim setup` | Apply plugin declarations from `sim.toml` when you use them. |
367
+
368
+ Run `uv run sim describe` for a machine-readable command manifest, or
369
+ `uv run sim <command> --help` for exact options.
370
+
371
+ ## Solver ownership
372
+
373
+ `sim-cli` does not bundle or redistribute simulation solvers or vendor SDKs.
374
+ Install and operate each underlying solver according to its vendor terms. See
375
+ [NOTICE](NOTICE) for optional SDK dependency notes.
376
+
377
+ `sim-cli` is an independent open-source project and is not affiliated with,
378
+ endorsed by, or sponsored by any solver vendor. Product, solver, and company
379
+ names remain the property of their respective owners.
380
+
381
+ ## Developer docs
382
+
383
+ - [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - project setup, layout, driver
384
+ development, and architecture notes
385
+ - [docs/plugin-install.md](docs/plugin-install.md) - plugin installation
386
+ reference
387
+
388
+ ## License
389
+
390
+ Apache-2.0 - see [LICENSE](LICENSE).