ansysem-agent-bridge 0.2.0a2__tar.gz

ansysem_agent_bridge-0.2.0a2/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[test]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: python -m pytest
+      - run: python -m pip wheel --no-deps . --wheel-dir dist

ansysem_agent_bridge-0.2.0a2/.github/workflows/publish.yml

@@ -0,0 +1,98 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to publish
+        required: true
+        default: v0.2.0a2
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Verify tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: |
+          PACKAGE_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          test "$RELEASE_TAG" = "v$PACKAGE_VERSION"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m pip install -e ".[test]"
+      - run: python -m pytest
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish_pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ansysem-agent-bridge
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  publish_github:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Upload the same distributions to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: gh release upload "$RELEASE_TAG" dist/* --repo "$GITHUB_REPOSITORY"
+
+  verify_release:
+    needs: [build, publish_pypi]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Install the exact published version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: |
+          VERSION=${RELEASE_TAG#v}
+          for attempt in 1 2 3 4 5 6; do
+            if python -m pip install --no-cache-dir "ansysem-agent-bridge==$VERSION"; then
+              ansysem-agent --help >/dev/null
+              python -c "import ansysem_agent_bridge, eda_bridge_runtime; assert ansysem_agent_bridge.__version__ == '$VERSION'; assert eda_bridge_runtime.__version__ == '0.1.0a5'"
+              exit 0
+            fi
+            sleep 10
+          done
+          exit 1

ansysem_agent_bridge-0.2.0a2/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+dist/
+build/
+.venv/
+.codex_tmp/
+.ansysem-agent/
+*.aedt
+*.aedt.lock
+*.aedb/
+*.aedtz
+*.log

ansysem_agent_bridge-0.2.0a2/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Keep changes small, testable, and within the public product boundary. Do not
+commit customer data, vendor documentation, private indexes, credentials,
+private infrastructure paths, or generated AEDT projects.
+
+Before opening a pull request, run:
+
+```text
+python -m pytest
+python -m build
+```
+
+New runtime claims require a version-specific capability probe, a bounded
+semantic operation, independent readback, and an update to the capability
+matrix. A failed exploratory script is not evidence that an AEDT capability is
+absent.

ansysem_agent_bridge-0.2.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnsysEM Agent Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ansysem_agent_bridge-0.2.0a2/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.5
+Name: ansysem-agent-bridge
+Version: 0.2.0a2
+Summary: Unofficial local-first agent bridge for Ansys Electronics Desktop
+Project-URL: Homepage, https://github.com/cottman99/ansysem-agent-bridge
+Project-URL: Repository, https://github.com/cottman99/ansysem-agent-bridge
+Project-URL: Issues, https://github.com/cottman99/ansysem-agent-bridge/issues
+Author: AnsysEM Agent Bridge contributors
+License: MIT License
+        
+        Copyright (c) 2026 AnsysEM Agent Bridge contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: aedt,ansys,automation,eda,hfss,pyaedt,pyedb
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: eda-bridge-runtime<0.2,>=0.1.0a5
+Provides-Extra: test
+Requires-Dist: jsonschema<5,>=4.23; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Requires-Dist: ruff<1,>=0.12; extra == 'test'
+Description-Content-Type: text/markdown
+
+# AnsysEM Agent Bridge
+
+[![PyPI](https://img.shields.io/pypi/v/ansysem-agent-bridge)](https://pypi.org/project/ansysem-agent-bridge/)
+[![CI](https://github.com/cottman99/ansysem-agent-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/cottman99/ansysem-agent-bridge/actions/workflows/ci.yml)
+
+AnsysEM Agent Bridge is an unofficial, local-first documentation and
+automation bridge for Ansys Electronics Desktop (AEDT). It gives a
+general-purpose Agent a stable CLI for exact target identity, capability
+discovery, project-bundle checks, bounded live HFSS 3D Layout readback, typed
+non-overwriting mutations, local documentation retrieval, and evidence-bearing
+artifacts.
+
+> Alpha software. It is not affiliated with or endorsed by Ansys, Inc. Ansys,
+> AEDT, HFSS, Maxwell, Q3D, and related names are trademarks of their respective
+> owners.
+
+![Abstract visualization of an Agent connected through a bounded local bridge to an electromagnetic design environment](docs/assets/ansysem-agent-bridge-hero.png)
+
+## Why a Bridge
+
+EDA automation fails when an Agent must guess the active project, API version,
+object-ID domain, execution lane, or whether a visible result reached the
+solver. The Bridge turns those implicit assumptions into machine-readable
+contracts:
+
+```text
+User goal
+   ↓
+Agent + one required Bridge Skill
+   ↓
+target identity + capability state + bounded operation
+   ↓
+PyAEDT / PyEDB / native AEDT adapter
+   ↓
+readback + artifact hash + explicit evidence boundary
+```
+
+The Bridge owns runtime facts and bounded tool access. A future Harness may
+compose it with workflows, authorization, engineering memory, and promotion
+policy without duplicating the Bridge transport or AEDT adapters.
+
+## Current alpha surface
+
+- explicit AEDT installation configuration and discovery;
+- `.aedt` plus `.aedb/edb.def` project-bundle verification;
+- revision-aware compact runtime snapshots;
+- capability descriptors separating declared, compatible, available, healthy,
+  and authorized state;
+- bounded live HFSS 3D Layout identity readback through PyAEDT;
+- native `ZoomToFit` plus `ExportImage` behind a checked image-export command;
+- named runtime profiles for the exact Python, display, module paths, and
+  bounded environment changes;
+- non-overwriting HFSS 3D Layout transactions with registered native and
+  PyEDB bondwire operations, save/close, fresh reopen, and assertions;
+- resumable candidate workspaces with idempotent typed patches, internal
+  checkpoints, rollback, abort, and clean-replay promotion;
+- detached durable jobs with reconnectable receipts, events, and unified
+  execution-ledger timing across local and persistent SSH transport;
+- a lightweight AEDT Automation-tab Context Add-in using secret-free
+  `EDA_CONTEXT/v1` locators;
+- private local documentation query/get commands;
+- one required Bridge Skill and one optional documentation Skill;
+- conflict-safe Skill install, status, and uninstall.
+
+See the [capability matrix](docs/CAPABILITY_MATRIX.md) for exact claims and stop
+rules.
+
+## Install
+
+```console
+pipx install ansysem-agent-bridge
+ansysem-agent --pretty doctor
+```
+
+Installing `ansysem-agent-bridge` also installs the small
+`eda-bridge-runtime` Python library automatically. This makes
+`ansysem-agent runtime serve` and the Context Add-in available without asking
+the user to choose an extra package. If the Agent runs on another machine,
+install and enable the Runtime MCP/plugin on that Agent host as described by
+the [EDA Bridge Runtime](https://github.com/cottman99/eda-bridge-runtime); the
+AEDT-only host does not need the Agent-facing plugin.
+
+Configure one explicit installation. Documentation is optional and remains on
+the AEDT host:
+
+```console
+ansysem-agent --pretty setup \
+  --aedt-root /path/to/AnsysEM/v261 \
+  --version 2026.1 \
+  --docs-root /path/to/private/local/docs
+```
+
+`setup` installs one small Bridge Skill by default:
+
+- `ansysem-agent-bridge` for setup, exact target identity, runtime state,
+  bounded operation, artifacts, and safe lifecycle;
+
+The separately selectable `ansysem-kb-docs` Skill supports version-matched
+local documentation without launching or mutating AEDT; it is not required for
+runtime operation.
+
+## Pin one runtime profile
+
+Do this once on the AEDT host. Before importing live AEDT libraries, the Bridge
+re-executes only its own fixed CLI under the profile's exact Python and
+pre-launch environment; it never accepts an arbitrary command:
+
+```console
+ansysem-agent --pretty profiles set \
+  --profile-id aedt-2026r1-display4 \
+  --python /path/to/exact/python \
+  --display :4.0 \
+  --python-path /path/to/version-matched/modules \
+  --prepend-env LD_LIBRARY_PATH=/path/to/version-matched/libraries
+
+ansysem-agent --pretty profiles show aedt-2026r1-display4
+```
+
+## Inspect before live work
+
+```console
+ansysem-agent --pretty instances list
+ansysem-agent --pretty project inspect --project /path/to/model.aedt
+ansysem-agent --pretty capabilities --project /path/to/model.aedt
+ansysem-agent --pretty runtime-snapshot \
+  --project /path/to/model.aedt --version 2026.1 --display :4.0
+```
+
+Suppress unchanged bounded state with the returned revision:
+
+```console
+ansysem-agent runtime-snapshot \
+  --project /path/to/model.aedt \
+  --since-revision <sha256>
+```
+
+## Live HFSS 3D Layout gate
+
+Run the CLI on the AEDT host. A new session is closed only when the command
+created it:
+
+```console
+ansysem-agent --pretty --profile aedt-2026r1-display4 \
+  runtime-snapshot \
+  --live --project /path/to/model.aedt --version 2026.1
+```
+
+Export a bounded visual artifact through the native editor API:
+
+```console
+ansysem-agent --pretty --profile aedt-2026r1-display4 \
+  layout export-image \
+  --project /path/to/model.aedt \
+  --version 2026.1 \
+  --output /path/to/new-layout-view.png
+```
+
+The image proves only that AEDT exported the named live editor state. It does
+not prove electrical correctness, solver input, mesh, convergence, or results.
+
+## Typed mutation paths
+
+Put task-specific names and values in project-local or streamed JSON, not in the
+Bridge or its Skill. Use one-shot `model apply` when the complete mutation and
+its final assertions are already known:
+
+```console
+ansysem-agent --pretty --profile aedt-2026r1-display4 \
+  model apply --plan /path/to/operation-plan.json --redact-paths
+```
+
+The v1 plan schema is
+[`ansysem-operation-plan-v1`](docs/schemas/ansysem-operation-plan-v1.schema.json).
+The Bridge refuses source/output identity, refuses an existing output, can pin
+the source `.aedt` and `edb.def` hashes, and exposes no arbitrary command,
+Python, or raw APD block field. The native adapter accepts registered property
+and gap-port operations. The PyEDB-native adapter accepts only structured APD
+profile definitions and exact-name bondwire changes. It commits the output
+only after separate fresh AEDT and PyEDB reopens pass all typed assertions. It
+never solves, packages, publishes, or creates a release as part of this
+command.
+
+For iterative work, begin one candidate workspace for the task instead of
+creating a permanent model version for every attempt:
+
+```console
+ansysem-agent --pretty --profile aedt-2026r1-display4 \
+  model workspace begin \
+  --source /path/to/frozen.aedt \
+  --workspace /path/to/task-candidate \
+  --adapter hfss3dlayout.pyedb-native/v1 \
+  --version 2026.1 --design Layout1
+
+ansysem-agent --pretty --profile aedt-2026r1-display4 \
+  model workspace reconcile \
+  --workspace /path/to/task-candidate --plan - < patch.json
+```
+
+Each `ansysem-workspace-patch/v1` carries a stable `patch_id`, the last returned
+`expected_workspace_revision`, registered operations, and scoped assertions.
+An identical retry is preserved without another EDA call. A passing reconcile
+creates only an internal checkpoint. Use `status`, `rollback`, or `abort` on the
+same workspace; none creates a customer-facing model revision.
+
+Batch all compatible edits known from the same observation into one patch so a
+single save/close/fresh-reopen gate validates the cycle. Promotion records its
+intent before launching EDA: after interruption, the exact same request either
+verifies an already-complete output or safely removes only its owned partial
+output and staging directory before replaying.
+
+Create one immutable output only at the explicit gate:
+
+```console
+ansysem-agent --pretty --profile aedt-2026r1-display4 \
+  model workspace promote \
+  --workspace /path/to/task-candidate \
+  --expected-revision <workspace-revision> \
+  --promotion-id <stable-promotion-id> \
+  --output /path/to/revision.aedt
+```
+
+Promotion ignores the mutable candidate as a delivery source. It replays the
+typed journal from the frozen source, performs the final assertion registry in
+fresh sessions, verifies full bundle digests, and only then commits the output.
+An exact retry of a committed promotion returns `preserved` without another EDA
+call; output or retention-policy drift is rejected.
+See [candidate workspace lifecycle](docs/WORKSPACE_LIFECYCLE.md).
+
+## Documentation
+
+```console
+ansysem-agent --pretty docs status
+ansysem-agent --pretty docs query "AddRefPortUsingEdges" \
+  --module hfss_3d_layout --limit 6
+ansysem-agent --pretty docs get <source-ref> \
+  --focus "AddRefPortUsingEdges" --max-chars 4000
+```
+
+The package does not contain or redistribute Ansys documentation. Queries use
+a corpus configured on the user's machine.
+
+## Remote topology
+
+Run `ansysem-agent` on the AEDT machine through SSH. One-off administration can
+still call the CLI directly. Repeated Agent operations use one persistent stdio
+channel:
+
+```console
+ansysem-agent runtime serve
+```
+
+The service persists a job before starting the exact runtime-profile worker,
+returns a receipt immediately, and detaches the worker from the SSH connection.
+Use `runtime job-status` and `runtime job-events` after reconnecting. The generic
+Runtime ledger records declared purpose, actual phases, timing, and normalized
+result. Keep AEDT automation, projects, documentation, and artifacts on that
+host unless the user explicitly exports a sanitized result.
+
+## Explicit AEDT context
+
+Install the three small Automation-tab actions with the configured PyAEDT
+profile:
+
+```console
+ansysem-agent --profile <profile-id> context-addin install \
+  --version 2026.1 --port <grpc-port> --process-id <aedt-pid>
+ansysem-agent context-addin status --personal-lib <live-personal-lib>
+ansysem-agent --profile <profile-id> context-addin refresh \
+  --version <version> --port <grpc-port> --process-id <aedt-pid>
+```
+
+The actions are **Use Current Design with Agent**, **Copy Agent Context**, and
+**Agent Connection Status**. The clipboard token contains only a host-local
+context ID, generation, display label, and capability hints. The exact project
+path remains in the private registry on the AEDT host. A context selects a
+target; it does not authorize mutation or solving.
+
+## Safety boundary
+
+- no implicit newest-version selection;
+- no foreground-window guessing;
+- no `.aedt`-only claim for HFSS 3D Layout bundles;
+- no arbitrary Python execution in the default public interface;
+- no source overwrite and no successful mutation claim before fresh reopen;
+- no permanent model version for a candidate attempt; only explicit promotion
+  creates a delivery output;
+- no blind GUI coordinates or screenshot-only success;
+- no force-kill or silent discard of modified work;
+- no claim that documentation, a visible object, or an exported image proves a
+  successful solve.
+
+See [the execution context contract](docs/EXECUTION_CONTEXT_CONTRACT.md),
+[architecture](docs/ARCHITECTURE.md), [release contract](docs/RELEASE_CONTRACT.md),
+[sanitized AEDT 2026 R1 Linux acceptance](docs/VALIDATION_AEDT_2026R1_LINUX.md),
+and [security policy](SECURITY.md).
+
+## Development
+
+```console
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The public repository contains synthetic tests only. Customer projects and
+vendor documentation are intentionally excluded.