invariant-daemon 0.1.0

Invariant local daemon for CAD integrations

Invariant

Local daemon for CAD and simulation integrations: FastAPI (HTTP + WebSocket), uvicorn, Typer CLI.

Install (development)

From the repository root:

pip install -e .
# optional: live Ansys MAPDL (PyMAPDL)
pip install -e ".[ansys]"

Run

invariant run

Optional flags and environment variables:

• --host / -H and --port / -p override bind address and port.
• INVARIANT_HOST and INVARIANT_PORT set defaults when flags are omitted.
• --reload enables auto-reload (development only; uses an import string so it works on Windows, Linux, and macOS).

Examples:

invariant run --port 8080
set INVARIANT_PORT=8080
invariant run

On Windows (cmd):

set INVARIANT_PORT=8080
invariant run

On Windows (PowerShell):

$env:INVARIANT_PORT = 8080
invariant run

API

• POST /models — JSON body; returns { "modelId": "m-1" }.
• POST /models/{model_id}/run — background job: mock solve if MAPDL is not connected; if live, records a MAPDL snapshot (does not start a new /SOLU solve).
• GET /jobs/{job_id}/result — { "status": "running" } until complete, then the result payload.
• GET /health — { "status": "ok" }.
• GET /integrations — { "integrations": [ { "id", "status", "label" } ] } for the Invariant IDE sidebar and @id chat mentions (e.g. @ansys).
• GET /integrations/{id}/context — JSON snapshot for the IDE agent. For ansys, see Ansys (MAPDL) below.
• GET /integrations/ansys/status — live vs mock mode, PyMAPDL version, gRPC target.
• WebSocket /ws — sends a hello message; echoes text frames as JSON.

Interactive docs: http://127.0.0.1:5000/docs (default).

Ansys (MAPDL via PyMAPDL)

Install the optional dependency, then start a Mechanical APDL session with gRPC on the expected port (default 50052):

pip install "invariant-daemon[ansys]"
# or: pip install ansys-mapdl-core

Environment variable	Purpose
INVARIANT_ANSYS_MODE	auto (default) try live MAPDL then mock, or mock to force synthetic data
INVARIANT_MAPDL_HOST	gRPC host (default 127.0.0.1; falls back to PYMAPDL_IP)
INVARIANT_MAPDL_PORT	gRPC port (default 50052; falls back to PYMAPDL_PORT)
INVARIANT_MAPDL_TRANSPORT	PyMAPDL transport_mode: default insecure (TCP gRPC). Use if your environment forces UDS.
INVARIANT_MAPDL_CONNECT_TIMEOUT	Seconds to wait for gRPC (default 15)

At startup, the daemon logs either a live connection line or a MOCK mode warning. GET /integrations/ansys/context returns source: "mapdl_grpc" with /STATUS excerpts, mesh and geometry counts, parameters, optional POST1 summaries, and an llm_digest string when MAPDL is connected; otherwise source: "mock".

Cross-platform notes

• Use Python 3.9+ from python.org on Windows; enable “Add Python to PATH” in the installer.
• Prefer a virtual environment (python -m venv .venv) so pip and the invariant script stay isolated.
• Binding to 127.0.0.1 (default) is appropriate for a local CAD companion; use 0.0.0.0 only if you need other machines on the LAN to reach the daemon (mind firewall rules).

Install from PyPI

pip install invariant-daemon
# with Ansys support:
pip install "invariant-daemon[ansys]"

Publishing to PyPI

The package is published as invariant-daemon on PyPI.

One-time setup

1. Create accounts on PyPI and TestPyPI if you do not have them.
2. Configure trusted publishing (recommended) or store credentials with a tool such as keyring; avoid committing tokens.
3. Install build tools: python -m pip install --upgrade build twine.

Build

From the project root:

python -m build

This produces dist/invariant_daemon-0.1.0-py3-none-any.whl and dist/invariant_daemon-0.1.0.tar.gz (names follow your version in pyproject.toml).

Test upload (recommended)

Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Install from TestPyPI in a clean venv:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ invariant-daemon

(--extra-index-url pulls dependencies like FastAPI from the real PyPI.)

Production upload

python -m twine upload dist/*

Version bumps

Increase version in pyproject.toml (and keep invariant/__init__.py in sync if you expose __version__) for every new release; PyPI rejects duplicate versions.