ads-agent-bridge 0.1.0a17__tar.gz

ads_agent_bridge-0.1.0a17/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install ".[test]" build
+      - run: python -m pytest
+      - run: python -m build
+      - run: python -m pip check

ads_agent_bridge-0.1.0a17/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+.coverage
+.codex_tmp/
+.ads-agent/

ads_agent_bridge-0.1.0a17/AGENTS.md

@@ -0,0 +1,31 @@
+# ADS Agent Bridge Development Contract
+
+This repository is the clean, public product repository. Keep research,
+customer workspaces, vendor documentation, generated indexes, and private
+paths out of Git.
+
+The critical user path is:
+
+```text
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+Work that does not improve or protect that path is not a v0.1 release blocker.
+Read `docs/RELEASE_CONTRACT.md` before expanding scope.
+
+Rules:
+
+- Windows and Linux are equal release gates.
+- ADS 2025 and later are the stable support target. Earlier Python-capable
+  generations remain preview or experimental until their real runtime gates
+  pass.
+- Bind docs, capabilities, sessions, and examples to an explicit ADS instance.
+- Prefer runtime feature probes over version-only assumptions.
+- Keep the ADS embedded addon standard-library-only when practical.
+- Listen on localhost and require a random session token.
+- Never distribute Keysight documentation or a generated copy of it.
+- Run tests from a non-system-drive temporary directory when available.
+- A partial quickstart must return a non-zero status and name every unpassed
+  gate; never report docs lookup as a completed automation roundtrip.

ads_agent_bridge-0.1.0a17/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable public changes are documented here.
+
+## 0.1.0a17 — 2026-08-05
+
+Initial limited public alpha.
+
+- Discover and explicitly select local ADS installations on Windows and Linux.
+- Classify stable, preview, experimental, and unsupported ADS generations.
+- Build a private per-installation search index from locally installed HTML
+  documentation without redistributing Keysight content.
+- Install, inspect, upgrade, and uninstall the DE/DDS user add-on with backups.
+- Connect to authenticated localhost-only DE and DDS bridge sessions.
+- Keep arbitrary Python and AEL execution behind explicit two-sided unsafe
+  opt-in.
+- Run a disposable headless minimal-AC workspace and validate its ADS dataset.
+- Locate Windows ADS user configuration through Keysight `eeenv/HOME` registry
+  values, with an explicit config-directory override.
+- Redact session bearer tokens from public CLI output.
+
+Momentum, RFPro, FEM, SIPro, and PIPro are not part of this alpha's supported
+workflow claim.

ads_agent_bridge-0.1.0a17/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Contributions should keep the three-command path reliable:
+
+```console
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+## Local checks
+
+Use Python 3.10 or later in an isolated environment:
+
+```console
+python -m pip install -e ".[test]"
+python -m pytest
+python -m build
+python -m pip check
+```
+
+Do not commit Keysight documentation, generated indexes, ADS workspaces,
+session files, license data, private paths, or customer material. Live ADS and
+solver claims need observable evidence from a disposable or explicitly
+authorized workspace.
+
+Keep pull requests focused and explain the user-facing capability or failure
+mode they change. Security reports belong in private vulnerability reporting,
+not public issues.

ads_agent_bridge-0.1.0a17/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ADS 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.

ads_agent_bridge-0.1.0a17/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: ads-agent-bridge
+Version: 0.1.0a17
+Summary: Unofficial local documentation and automation bridge for Keysight ADS
+Project-URL: Homepage, https://github.com/cottman99/ads-agent-bridge
+Project-URL: Repository, https://github.com/cottman99/ads-agent-bridge
+Project-URL: Issues, https://github.com/cottman99/ads-agent-bridge/issues
+Project-URL: Changelog, https://github.com/cottman99/ads-agent-bridge/blob/main/CHANGELOG.md
+Author: ADS Agent Bridge contributors
+License: MIT License
+        
+        Copyright (c) 2026 ADS 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: ads,automation,eda,keysight,rf
+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: beautifulsoup4<5,>=4.12
+Requires-Dist: html2text<2027,>=2024.2.26
+Requires-Dist: platformdirs<5,>=4
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ADS Agent Bridge
+
+An unofficial, local-first documentation and automation bridge for Keysight
+Advanced Design System (ADS).
+
+> [!IMPORTANT]
+> This is a limited public alpha. Use disposable ADS workspaces and review the
+> reported capability gates before relying on automation results.
+> Keysight and ADS are trademarks of Keysight Technologies. This project is
+> not affiliated with or endorsed by Keysight.
+
+The first release is designed around three commands:
+
+```text
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+The current alpha slice implements cross-platform ADS installation discovery,
+capability/support reporting, per-installation local documentation indexing,
+DE/DDS add-on registration, and a headless minimal-AC quickstart with dataset
+readback.
+
+It does **not** currently claim a completed Momentum, RFPro, FEM, SIPro, or
+PIPro workflow. Those lanes require separate solver-side acceptance evidence.
+
+Official ADS documentation is never distributed with this package. Indexes
+are built privately from documentation already installed on the user's
+machine.
+
+Set `ADS_AGENT_HOME` to place configuration, data, and caches under an explicit
+directory. This is useful for isolated tests, remote servers, and systems where
+the normal user cache location is not appropriate.
+
+## Install and verify
+
+Prerequisites:
+
+- a locally licensed ADS installation;
+- Python 3.10 or later for the `ads-agent` command;
+- `pipx` (recommended) or an isolated virtual environment.
+
+```console
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+When several ADS versions are found, interactive setup asks which one to use.
+For an unattended or version-specific setup:
+
+```console
+ads-agent setup --ads-root /path/to/ADS2026_Update2 --non-interactive
+```
+
+A successful quickstart independently reports documentation, add-on,
+workspace, circuit simulation, and dataset readback gates. It creates a new
+disposable workspace and refuses to overwrite an existing path.
+
+## Current commands
+
+```text
+ads-agent instances scan [--ads-root PATH]
+ads-agent instances list
+ads-agent instances use INSTANCE_ID
+ads-agent compatibility explain [--ads INSTANCE_ID]
+ads-agent docs ensure [--ads INSTANCE_ID]
+ads-agent docs status [--ads INSTANCE_ID]
+ads-agent docs query QUERY [--ads INSTANCE_ID]
+ads-agent setup [--ads-root PATH] [--non-interactive] [--config-dir PATH]
+ads-agent quickstart [--ads INSTANCE_ID] [--workspace PATH] [--config-dir PATH]
+ads-agent addon status
+ads-agent bridge sessions
+```
+
+Documentation queries stay on the local machine:
+
+```console
+ads-agent docs query "keysight.ads.de workspace" --limit 5
+```
+
+The bridge listens only on localhost and uses a random token per session.
+Arbitrary embedded Python and dynamic AEL calls are disabled unless ADS is
+launched with `ADS_AGENT_UNSAFE=1` and the client command also includes
+`--unsafe`.
+
+On Windows, `setup` reads Keysight's per-version `eeenv/HOME` registry values
+to locate the real `hpeesof/config` directory. Use `--config-dir` (or
+`ADS_AGENT_ADS_CONFIG_DIR`) when maintaining separate ADS profiles.
+
+On Linux, ADS Python may still require an available X display even though the
+quickstart opens no ADS window. Set `DISPLAY` to the intended isolated display
+before running it. `setup` edits only the current user's ADS add-on XML files,
+creates timestamped backups, and preserves unrelated add-ons.
+
+Stable support is targeted at ADS 2025 and later. ADS 2024 Update 2 is a
+preview target; ADS 2023 Update 2 through ADS 2024 Update 1 are experimental.
+Runtime capability probes, rather than version numbers alone, decide which
+features are actually available.
+
+## Remove the integration
+
+```console
+ads-agent addon uninstall
+```
+
+The installer preserves unrelated ADS add-ons and creates timestamped XML
+backups before changing an existing configuration.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the evidence-backed
+[validation record](docs/VALIDATION_2026-08-05.md).

ads_agent_bridge-0.1.0a17/README.md

@@ -0,0 +1,114 @@
+# ADS Agent Bridge
+
+An unofficial, local-first documentation and automation bridge for Keysight
+Advanced Design System (ADS).
+
+> [!IMPORTANT]
+> This is a limited public alpha. Use disposable ADS workspaces and review the
+> reported capability gates before relying on automation results.
+> Keysight and ADS are trademarks of Keysight Technologies. This project is
+> not affiliated with or endorsed by Keysight.
+
+The first release is designed around three commands:
+
+```text
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+The current alpha slice implements cross-platform ADS installation discovery,
+capability/support reporting, per-installation local documentation indexing,
+DE/DDS add-on registration, and a headless minimal-AC quickstart with dataset
+readback.
+
+It does **not** currently claim a completed Momentum, RFPro, FEM, SIPro, or
+PIPro workflow. Those lanes require separate solver-side acceptance evidence.
+
+Official ADS documentation is never distributed with this package. Indexes
+are built privately from documentation already installed on the user's
+machine.
+
+Set `ADS_AGENT_HOME` to place configuration, data, and caches under an explicit
+directory. This is useful for isolated tests, remote servers, and systems where
+the normal user cache location is not appropriate.
+
+## Install and verify
+
+Prerequisites:
+
+- a locally licensed ADS installation;
+- Python 3.10 or later for the `ads-agent` command;
+- `pipx` (recommended) or an isolated virtual environment.
+
+```console
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+When several ADS versions are found, interactive setup asks which one to use.
+For an unattended or version-specific setup:
+
+```console
+ads-agent setup --ads-root /path/to/ADS2026_Update2 --non-interactive
+```
+
+A successful quickstart independently reports documentation, add-on,
+workspace, circuit simulation, and dataset readback gates. It creates a new
+disposable workspace and refuses to overwrite an existing path.
+
+## Current commands
+
+```text
+ads-agent instances scan [--ads-root PATH]
+ads-agent instances list
+ads-agent instances use INSTANCE_ID
+ads-agent compatibility explain [--ads INSTANCE_ID]
+ads-agent docs ensure [--ads INSTANCE_ID]
+ads-agent docs status [--ads INSTANCE_ID]
+ads-agent docs query QUERY [--ads INSTANCE_ID]
+ads-agent setup [--ads-root PATH] [--non-interactive] [--config-dir PATH]
+ads-agent quickstart [--ads INSTANCE_ID] [--workspace PATH] [--config-dir PATH]
+ads-agent addon status
+ads-agent bridge sessions
+```
+
+Documentation queries stay on the local machine:
+
+```console
+ads-agent docs query "keysight.ads.de workspace" --limit 5
+```
+
+The bridge listens only on localhost and uses a random token per session.
+Arbitrary embedded Python and dynamic AEL calls are disabled unless ADS is
+launched with `ADS_AGENT_UNSAFE=1` and the client command also includes
+`--unsafe`.
+
+On Windows, `setup` reads Keysight's per-version `eeenv/HOME` registry values
+to locate the real `hpeesof/config` directory. Use `--config-dir` (or
+`ADS_AGENT_ADS_CONFIG_DIR`) when maintaining separate ADS profiles.
+
+On Linux, ADS Python may still require an available X display even though the
+quickstart opens no ADS window. Set `DISPLAY` to the intended isolated display
+before running it. `setup` edits only the current user's ADS add-on XML files,
+creates timestamped backups, and preserves unrelated add-ons.
+
+Stable support is targeted at ADS 2025 and later. ADS 2024 Update 2 is a
+preview target; ADS 2023 Update 2 through ADS 2024 Update 1 are experimental.
+Runtime capability probes, rather than version numbers alone, decide which
+features are actually available.
+
+## Remove the integration
+
+```console
+ads-agent addon uninstall
+```
+
+The installer preserves unrelated ADS add-ons and creates timestamped XML
+backups before changing an existing configuration.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the evidence-backed
+[validation record](docs/VALIDATION_2026-08-05.md).

ads_agent_bridge-0.1.0a17/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+Do not report security vulnerabilities through a public issue. Use GitHub's
+private vulnerability reporting for this repository.
+
+The product security boundary is localhost-only transport with a random token
+per ADS session. Arbitrary Python or AEL execution will require explicit unsafe
+mode and is not part of the default quickstart path.
+
+Session JSON files contain bearer tokens. They are written to the local runtime
+directory with restrictive permissions where supported. The public
+`bridge sessions` command redacts tokens.
+
+This alpha is intended for local ADS installations and disposable workspaces.
+Do not expose bridge ports through a proxy, port forward, or public interface.

ads_agent_bridge-0.1.0a17/docs/RELEASE_CONTRACT.md

@@ -0,0 +1,66 @@
+# v0.1 Release Contract
+
+## Product promise
+
+A new user can install one package, select the intended local ADS installation,
+query that installation's private local documentation, and run one verified
+circuit workflow without learning the internal adapter or plugin architecture.
+
+## User path
+
+```text
+pipx install ads-agent-bridge
+ads-agent setup
+ads-agent quickstart
+```
+
+`setup` must discover installed ADS instances, select one without silently
+preferring the newest version, probe capabilities, install recoverable user
+integration, and make documentation lookup immediately useful.
+
+`quickstart` must report these gates independently:
+
+1. documentation index;
+2. documentation query;
+3. add-on registration when the selected ADS supports Python add-ons;
+4. disposable workspace creation;
+5. circuit simulation;
+6. dataset readback.
+
+It passes only when all required gates pass.
+
+## Support tiers
+
+- ADS 2025 and later: stable target.
+- ADS 2024 Update 2: preview target.
+- ADS 2023 Update 2 through ADS 2024 Update 1: experimental target.
+- Older versions: documentation-only when local docs can be discovered; no
+  live Python bridge promise.
+
+Version is a starting hint. Runtime capability probes decide whether DE, DDS,
+addons, AEL interoperability, headless automation, or EM routes are available.
+
+## v0.1 release blockers
+
+- clean wheel and offline wheelhouse installation;
+- automatic dependency installation;
+- multi-instance discovery and explicit selection;
+- Windows and Linux setup/docs/bridge gates;
+- resumable private documentation indexing;
+- recoverable addon install, upgrade, and uninstall;
+- localhost token-authenticated live bridge;
+- disposable-workspace headless circuit simulation and dataset readback;
+- one real two-port Momentum golden path;
+- no vendor docs, private paths, or monorepo runtime imports.
+
+## Non-blocking extensions
+
+The full plugin platform, RFPro/FEM completeness, SIPro/PIPro, broad PDK
+automation, AEL debugging, built-in SSH orchestration, and large example
+catalogs do not block the first public beta.
+
+## Evidence language
+
+Use `discovered`, `indexed`, `installed`, `connected`, `created`, `saved`,
+`reopened`, `simulated`, and `read_back` only when the corresponding observable
+gate passed. Filesystem presence alone is not live ADS or solver evidence.

ads_agent_bridge-0.1.0a17/docs/VALIDATION_2026-08-05.md

@@ -0,0 +1,96 @@
+# Validation record — 2026-08-05
+
+## Outcome
+
+`ads-agent-bridge 0.1.0a17` passes the minimum public core on Windows and
+Linux. The alpha package is suitable for a limited public release that claims
+installation discovery, private local documentation indexing, recoverable
+DE/DDS add-on registration, authenticated localhost bridge connectivity, and
+the minimal headless AC workflow.
+
+The full v0.1 contract is not yet complete because the real two-port Momentum
+golden path has not passed. No EM or RFPro solver-completion claim is made by
+this record.
+
+## Release artifact
+
+- Wheel: `ads_agent_bridge-0.1.0a17-py3-none-any.whl`
+- Source distribution: `ads_agent_bridge-0.1.0a17.tar.gz`
+- Clean Python 3.10 installation: passed, including declared dependencies.
+- `pip check`: no broken requirements.
+- Unit tests: 18 passed.
+- Wheel inspection: contains only the public package, metadata, and MIT
+  license; no documentation corpus, generated index, private path, host, or
+  monorepo runtime dependency was found.
+
+## Linux acceptance
+
+Target: ADS 2026 Update 2.1 with its bundled Python 3.13, using an isolated X
+display, state directory, user profile, workspace, slot, and ports.
+
+- Automatic installation discovery: passed.
+- Local documentation roots: ADS, Python, AEL, and DDS discovered.
+- Fast private index: 9,422 HTML pages indexed; repeat run reused the index.
+- `setup`: passed, including isolated DE and DDS registration.
+- Final a16 `quickstart`: passed all six reported gates.
+- Circuit evidence: 30-line generated netlist; 31 dataset rows; columns
+  `freq`, `R1_v`, and `SRC1.i`; frequency range 1 Hz to 1 MHz.
+- Live DE and DDS sessions: authenticated ping/status passed.
+- Safe/unsafe boundary: arbitrary Python rejected by default and worked only
+  after explicit process and client opt-in.
+- Project management: copied workspace open/readback passed.
+- AEL interoperability: bounded function discovery and workspace refresh
+  passed.
+- DDS: equation readback was valid with 31 complex samples.
+- Headless route: separate workspace simulation and dataset readback passed.
+- Cleanup: test ADS processes were terminated; pre-existing add-on XML files
+  were restored to their exact pre-test SHA-256 values.
+
+## Windows acceptance
+
+Stable-version headless matrix:
+
+| ADS version | Support | Indexed pages | Quickstart | Dataset rows |
+|---|---:|---:|---:|---:|
+| 2026 Update 2 | stable | 9,422 | passed | 31 |
+| 2026 Update 1 | stable | 8,825 | passed | 31 |
+| 2025 Update 2 | stable | 7,649 | passed | 31 |
+
+Additional Windows gates:
+
+- Clean wheel installation under Python 3.10: passed.
+- Multi-installation discovery found the three stable installations plus an
+  older ADS 2023 Update 1 installation without silently changing the default.
+- ADS user configuration discovery followed Keysight's per-version
+  `eeenv/HOME` registry value instead of assuming `%USERPROFILE%`.
+- Real isolated ADS 2026 Update 2 DE and DDS add-on startup: passed.
+- New DE and DDS sessions used localhost, random tokens, separate profiles,
+  and the expected disposable workspace; ping/status passed.
+- Public session listing redacted the token and reported only `has_token`;
+  authenticated requests continued to use the private session record.
+- Add-on XML recovery: byte-identical SHA-256 values before and after the live
+  test.
+- Test processes were terminated by exact new PID; the pre-existing user ADS
+  process set remained unchanged.
+- The final quickstart did not write ADS `.cfg` files into the caller's
+  current directory.
+
+## Older-version boundary
+
+ADS 2023 Update 1 was discovered and `setup` degraded cleanly: missing local
+HTML documentation was reported as `not_available`, and unsupported Python
+add-on registration was skipped. Its bundled Python lacks `keysight.ads.de`,
+so the circuit quickstart correctly failed. This is evidence for the current
+unsupported boundary, not a failure of the stable ADS 2025+ claim.
+
+## Remaining gates
+
+1. Build and accept a distributable two-port Momentum fixture with solver-side
+   port, terminal status, result-artifact, and numeric S-parameter evidence.
+2. Make the maintained RFPro/Momentum acceptance harness cross-platform; the
+   current external harness assumes the Windows `tools/python/python.exe`
+   layout and cannot validate a Linux solver run.
+3. Run the ADS 2024 Update 2 preview and ADS 2023 Update 2 experimental lanes
+   on real installations before strengthening their support language.
+4. Publishing to a public package index and creating a signed/tagged release
+   were not performed by this validation.

ads_agent_bridge-0.1.0a17/examples/dds_readback.py

@@ -0,0 +1,66 @@
+"""Create a DDS file and validate an ADS dataset through an equation.
+
+Set ``WORKSPACE`` and ``DATASET`` in the DDS bridge namespace before running.
+The final stdout line is a JSON acceptance record. This intentionally avoids
+adding a plot, because raw complex data can open an interactive chooser.
+"""
+
+from __future__ import annotations
+
+import json
+import traceback
+from pathlib import Path
+
+from keysight.ads import dds
+
+
+def json_safe(value):
+    if isinstance(value, complex):
+        return {"real": value.real, "imag": value.imag}
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if isinstance(value, (list, tuple)):
+        return [json_safe(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): json_safe(item) for key, item in value.items()}
+    return repr(value)
+
+
+def main() -> dict:
+    record = {"ok": False}
+    try:
+        workspace = Path(globals()["WORKSPACE"]).resolve()
+        dataset_path = Path(globals()["DATASET"]).resolve()
+        if not dataset_path.is_file():
+            raise FileNotFoundError(dataset_path)
+        dds.init_dds_path(workspace)
+        dds_file = dds.new_dds_file(dataset_path, workspace)
+        dds_file.add_dataset_alias("minimal_ac", str(dataset_path))
+        page = dds_file.pages[0]
+        page.name = "Minimal AC dataset"
+        equation = page.add_equation("node_voltage", "R1_v")
+        values = equation.variable.to_dataframe().values.tolist()
+        dds_name = "minimal_ac_readback.dds"
+        dds_path = workspace / dds_name
+        dds_file.save(dds_name, workspace)
+        record.update(
+            {
+                "ok": equation.status == "Valid" and len(values) > 0 and dds_path.is_file(),
+                "workspace": str(workspace),
+                "dataset_path": str(dataset_path),
+                "dds_path": str(dds_path),
+                "dds_exists": dds_path.is_file(),
+                "equation": equation.expression,
+                "equation_status": equation.status,
+                "row_count": len(values),
+                "values_preview": json_safe(values[:3]),
+                "dataset_aliases": dict(dds_file.dataset_aliases),
+                "is_dds_app": bool(dds.is_dds_app()),
+            }
+        )
+    except Exception as exc:
+        record.update({"error": repr(exc), "traceback": traceback.format_exc()})
+    return record
+
+
+print(json.dumps(main(), ensure_ascii=False))