verdi-bridge 0.3.1__tar.gz

verdi_bridge-0.3.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Report a reproducible bridge or tool problem
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Expected and observed behavior**
+
+**Environment**
+- Bridge version:
+- Verdi version:
+- Client/host OS and Python versions:
+- Local or SSH connection:
+
+**Reproduction**
+Include the tool name, sanitized arguments and error output.
+For timing issues, include the waveform's native time unit.
+
+**Minimal public example**
+If possible, use an open-source RTL fixture. Do not attach confidential RTL, FSDB,
+credentials, license configuration or proprietary vendor documentation.

verdi_bridge-0.3.1/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## Change
+
+Describe the problem and resulting behavior.
+
+## Validation
+
+List the relevant tests. For vendor API changes, include the Verdi version and
+actual observed result. Distinguish fake-GUI tests from real tool runs.

verdi_bridge-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish package and MCP registry
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to publish (e.g. v0.3.1)
+        required: true
+        type: string
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: sudo apt-get update && sudo apt-get install -y tcl8.6
+      - run: python -m pip install . build twine pytest ruff
+      - name: Verify matching versions
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: |
+          python - <<'PY'
+          import json, os, tomllib
+          from verdi_bridge import __version__
+          project = tomllib.load(open('pyproject.toml', 'rb'))['project']
+          server = json.load(open('server.json'))
+          assert os.environ['RELEASE_TAG'] == 'v' + project['version']
+          assert __version__ == project['version'] == server['version'] == server['packages'][0]['version']
+          PY
+      - run: ruff check . && pytest -q
+      - run: python -m build && python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/verdi-bridge
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+  registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
+      - name: Install pinned MCP publisher
+        run: |
+          curl -fsSLO https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_linux_amd64.tar.gz
+          curl -fsSLO https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/registry_1.8.1_checksums.txt
+          grep ' mcp-publisher_linux_amd64.tar.gz$' registry_1.8.1_checksums.txt | sha256sum --check --strict
+          tar xzf mcp-publisher_linux_amd64.tar.gz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

verdi_bridge-0.3.1/.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Tests
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: sudo apt-get update && sudo apt-get install -y tcl8.6
+      - run: python -m pip install . pytest ruff
+      - run: ruff check .
+      - run: pytest -q

verdi_bridge-0.3.1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.env
+*.fsdb
+*.vcd
+novas.*
+verdiLog/

verdi_bridge-0.3.1/AGENTS.md

@@ -0,0 +1,19 @@
+# Working in this repository
+
+Verdi Bridge connects an MCP client to a licensed, live Verdi GUI. Start with
+README.md, docs/architecture.md and docs/tools.md.
+
+- Keep tool arguments as data. Do not add arbitrary Tcl or shell evaluation to MCP.
+- Consult installed vendor documentation before introducing Verdi API calls.
+  Do not redistribute vendor documentation, binaries or license settings.
+- Preserve request IDs, session checks, source-root boundaries and timeout semantics.
+- Keep core operations independent of any particular RTL module or testbench.
+- Distinguish simulator doubles from real-Verdi validation. Record the vendor version.
+- A driver location is not a fault label. Known injected mutations are not blind accuracy.
+- Keep upstream revision, hash and license notices with benchmark fixtures.
+- Exclude credentials, personal hostnames, runtime directories, FSDB/VCD and proprietary RTL
+  from commits. Public benchmark traces and logs are intentionally retained in docs/evidence.
+
+Run `uv sync`, `uv run pytest`, `uv run ruff check .`, and `uv build` for code changes.
+Documentation changes need link/example checks; they do not require rerunning licensed
+simulation. Real EDA experiments require an explicitly authorized, licensed environment.

verdi_bridge-0.3.1/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.3.1 — 2026-10-13
+
+- Prepare PyPI distribution metadata, MCP Registry manifest, and an OIDC publishing workflow.
+- Lead English/Chinese documentation with live waveform observation and GUI navigation.
+- Add pip/uvx installation instructions and a central validation index; all paired-pilot
+  outcomes and limitations remain public. No runtime tool behavior changes.
+
+## 0.3.0 — 2026-10-13
+
+- Convert physical times exactly to integer native ticks; reject off-grid times and
+  ticks beyond 2^53−1. Preserve exact `(start, end]` comparisons and decimal output.
+- **Migration:** Dec is now unsigned (like UDec); request SDec for two’s complement.
+  `find_signals` is literal by default; pass `glob=True` for wildcard paths. Bus
+  brackets stay literal. Configure `VERDI_BRIDGE_LOG_ROOTS` separately for log reads.
+- Bound interval work with a cooperative 200 ms default budget and resumable
+  per-signal partial results. One blocking vendor call cannot be preempted.
+- Default both polling intervals to 10 ms; cache signal listings within a request.
+  Clock windows default to a physical 100 ns regardless of requested unit.
+- Remove constant driver type fields; document per-Client and GUI serialization.
+- 42 automated tests plus live Verdi checks. A 2×2 transport experiment measured
+  106 ms to 47 ms persistent median latency after lowering polling.
+- Run and publish an eight-mutation paired pilot: 8/8 exact localization in both
+  arms, zero diagnostic tool calls. No accuracy or agent call-count benefit shown.
+
+Upgrade Python and the loaded Tcl adapter together in a fresh session directory.
+The wire arguments changed; mixing adapter/package versions is unsupported.
+
+## 0.2.1 — 2026-10-13
+
+- Detect an exited SSH process before writing another request, even if a surviving
+  descendant still holds a pipe. Never continue or replay through a dead transport.
+- Make the local SSH shim exec its helper consistently on macOS and Linux.
+- The initial v0.2.0 tag failed Linux CI on this disconnect scenario. Its history
+  is retained; v0.2.1 is the release build.
+
+## 0.2.0 — 2026-10-13
+
+- Add bounded transition/window queries, recursive signal search, clock measurement,
+  log reads, and direct source-file reads (16 MCP tools total).
+- Add optional observed-clock edge snapping to `jump_before_error` and signed Dec.
+- Reuse a remote SSH/helper connection; preserve per-request identity, timeout
+  semantics and no automatic replay. Add explicit client cleanup and one-shot opt-out.
+- Replace the FIFO-specific MCP prompt with generic `debug_failure`.
+- Preserve raw driver locations and add structured entries with type `unknown`:
+  the vendor API does not identify assignment types.
+- Add real-Verdi evidence, synthetic narrow-pulse probe, SSH-branch tests and paired
+  evaluation protocol. No new model accuracy or agent call-count claim.
+- Move old agent demo materials under `docs/evidence/archive/` without deleting
+  recordings or historical evidence. Current README links retain native EN/ZH demos.
+
+Upgrade both the Python package and the loaded Tcl adapter. Restart the adapter in
+an isolated fresh GUI/session directory; upgrading Python alone does not add GUI
+operations. `debug_fifo` prompt clients must switch to `debug_failure`.
+
+## 0.1.1 — 2026-10-13
+
+Initial public ten-tool bridge with real-Verdi examples, multi-design injected
+faults, independent-agent blind trial, and native English/Chinese demo recordings.
+Installed from this repository; no PyPI upload.

verdi_bridge-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Use Python 3.11+ and Tcl 8.6+. Run `uv sync`, `uv run pytest`, and
+`uv run ruff check .`. Package with `uv build`.
+
+Add tests for argument escaping, session/race behavior and time units when changing
+the transport. Test vendor API changes on a real licensed Verdi instance and record
+the exact version. The fake GUI tests only our protocol, not Synopsys behavior.
+Do not add generic Tcl evaluation to the MCP surface.
+
+Bug reports should include tool name, sanitized arguments, Verdi version, native time
+unit, and expected/observed results. Do not upload proprietary RTL, FSDB files,
+license server settings, credentials, or vendor documentation.
+
+Benchmark additions need a pinned source revision, compatible license, passing
+baseline, independent checker, deterministic mutation and honest diagnosis record.
+Report missing evidence and failed cases. Keep mutation ground truth separate from
+future blinded diagnosis inputs. A replay script is not a new LLM evaluation.

verdi_bridge-0.3.1/LICENSE

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

verdi_bridge-0.3.1/NOTICE

@@ -0,0 +1,34 @@
+Verdi Bridge is an independent community project, not a Synopsys product.
+No Synopsys binaries, libraries, or documentation are distributed.
+
+External benchmark source excerpts in docs/evidence are derived from:
+https://github.com/alexforencich/verilog-axis
+commit 48ff7a7e2ef782cf778d47910cf85835c64b1bce, rtl/axis_fifo.v
+Copyright (c) 2013-2023 Alex Forencich
+
+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.
+
+Additional MIT benchmark excerpts (the permission terms above also apply):
+- verilog-uart/rtl/uart_tx.v at 1b867e53af738e4a8bc7c839ca2f1c07f40382dc
+  Copyright (c) 2014-2017 Alex Forencich
+- verilog-axi/rtl/axil_reg_if_wr.v at 516bd5dadc3365b7f9e225d2af8fe0b8d804fe53
+  Copyright (c) 2021 Alex Forencich
+- verilog-axis/rtl/arbiter.v at 48ff7a7e2ef782cf778d47910cf85835c64b1bce
+  Copyright (c) 2014-2021 Alex Forencich
+Their repositories are hosted under https://github.com/alexforencich/.

verdi_bridge-0.3.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: verdi-bridge
+Version: 0.3.1
+Summary: Let AI agents inspect waveforms and navigate RTL in a live Synopsys Verdi session
+Project-URL: Repository, https://github.com/RuihongY/verdi_bridge
+Project-URL: Documentation, https://github.com/RuihongY/verdi_bridge/blob/main/docs/guide.md
+Project-URL: Issues, https://github.com/RuihongY/verdi_bridge/issues
+Author: Ruihong Yin
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asic,eda,mcp,rtl,verdi,verification,waveform
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.28
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.RuihongY/verdi-bridge -->
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/RuihongY/verdi_bridge/main/assets/banner.svg" alt="Verdi Bridge — connect AI agents to your live Verdi session" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/verdi-bridge/"><img src="https://img.shields.io/pypi/v/verdi-bridge" alt="PyPI" /></a>
+  <a href="https://github.com/RuihongY/verdi_bridge/actions/workflows/test.yml"><img src="https://github.com/RuihongY/verdi_bridge/actions/workflows/test.yml/badge.svg" alt="Tests" /></a>
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /></a>
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11 or newer" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/docs/guide.md"><b>Getting started</b></a> ·
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/docs/tools.md">Tool reference</a> ·
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/docs/architecture.md">Architecture</a> ·
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/README.zh-CN.md">中文</a>
+</p>
+
+# Give your RTL debugging agent eyes on the waveform
+
+Connect your AI agent to **live Synopsys Verdi**. Let it find signals, inspect
+transitions, move through simulation time, and open the driving RTL—all in the
+same GUI you use to debug.
+
+> “Add the FIFO read/write pointers, go 20 cycles before the error, and investigate why full stayed high.”
+>
+> “When did BVALID drop? Show the handshake signals and the code that drives it.”
+
+Verdi Bridge turns those requests into observations from your simulation and
+visible actions in nWave and nTrace. The agent reasons; the bridge observes.
+Sixteen typed MCP tools work locally or over SSH with your existing Verdi setup.
+
+## Video walkthrough
+
+Ask an agent to investigate a bug, then watch it choose signals, inspect live waveforms and navigate RTL. A 1m38s silent demo: an English prompt and original English agent replies beside synchronized Verdi capture. This is a separate English-language run, not a translation. Tool calls are selected by the agent, not a replay script.
+
+https://github.com/user-attachments/assets/b041c1bd-4be5-4040-b281-2f15001b1e35
+
+[English video](https://github.com/user-attachments/assets/b041c1bd-4be5-4040-b281-2f15001b1e35) · [中文视频](https://github.com/user-attachments/assets/3294e374-5c43-4b67-8e20-b8a6f319d8f7)
+
+[How this was recorded](https://github.com/RuihongY/verdi_bridge/blob/main/docs/agent-demo.md) · [Installation tutorial](https://github.com/RuihongY/verdi_bridge/blob/main/docs/video-walkthrough.md)
+
+## Quick start
+
+```sh
+pip install verdi-bridge
+```
+
+Or run without a checkout using uv:
+
+```sh
+uvx verdi-bridge tcl-path
+```
+
+This prints the bundled Tcl adapter path. [Load it in Verdi and connect your MCP
+client](https://github.com/RuihongY/verdi_bridge/blob/main/docs/guide.md), then use `uvx verdi-bridge serve` as the stdio server.
+A licensed Verdi installation is required. Client: Python 3.11+; remote host:
+Python 3.6+ and Verdi's Tcl 8.6. No vendor software is bundled.
+
+## What you can do
+
+| Workflow | Tools |
+|---|---|
+| Find and display signals | `find_signals`, `browse_scope`, `add_signals` |
+| Navigate an error window | `set_cursor`, `set_time_window`, `jump_before_error` |
+| Inspect actual waveform values | `find_transitions`, `get_value_changes`, `sample_signals` |
+| Discover error times and clocks | `read_log`, `measure_clock` |
+| Follow drivers into RTL | `trace_driver`, `read_source`, `read_source_file`, `goto_source` |
+
+Waveform queries preserve X/Z values. Time arguments carry explicit units.
+The same interface works with different RTL designs; no FIFO-specific logic is
+built into the bridge. See the [Python and CLI examples](https://github.com/RuihongY/verdi_bridge/blob/main/docs/tools.md).
+
+## See it in a real debugging session
+
+Tested with UART TX, AXI-Lite, FIFO and arbiter RTL in licensed VCS/Verdi sessions.
+The agent can put relevant signals on screen, inspect their changes, and navigate
+to source while you follow along.
+
+![UART waveform and source in Verdi](https://raw.githubusercontent.com/RuihongY/verdi_bridge/main/docs/evidence/multidesign/uart-multidesign.png)
+
+[Real RTL examples](https://github.com/RuihongY/verdi_bridge/blob/main/docs/multidesign-validation.md) ·
+[Blind debugging trial](https://github.com/RuihongY/verdi_bridge/blob/main/docs/blind-validation.md) ·
+[Validation results and limitations](https://github.com/RuihongY/verdi_bridge/blob/main/docs/validation-index.md)
+
+## Project status
+
+Experimental **v0.3.1**. Tested with Verdi T-2022.06-SP2-1 on Linux.
+New-session startup is verified; attachment to an arbitrary existing GUI is not yet
+separately validated. The bridge does not automatically compile, edit or repair RTL.
+
+[Contributing](https://github.com/RuihongY/verdi_bridge/blob/main/CONTRIBUTING.md) · [Trust boundary](https://github.com/RuihongY/verdi_bridge/blob/main/SECURITY.md) ·
+[Validation limits](https://github.com/RuihongY/verdi_bridge/blob/main/docs/validation.md) · [Report an issue](https://github.com/RuihongY/verdi_bridge/issues)
+
+Inspired by the agent-to-EDA-tool workflow of
+[virtuoso-bridge-lite](https://github.com/Arcadia-1/virtuoso-bridge-lite).
+This is an independent implementation. MIT licensed; see [third-party notices](https://github.com/RuihongY/verdi_bridge/blob/main/NOTICE).
+Not affiliated with Synopsys. Verdi is a Synopsys trademark.

verdi_bridge-0.3.1/README.md

@@ -0,0 +1,100 @@
+<!-- mcp-name: io.github.RuihongY/verdi-bridge -->
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/RuihongY/verdi_bridge/main/assets/banner.svg" alt="Verdi Bridge — connect AI agents to your live Verdi session" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/verdi-bridge/"><img src="https://img.shields.io/pypi/v/verdi-bridge" alt="PyPI" /></a>
+  <a href="https://github.com/RuihongY/verdi_bridge/actions/workflows/test.yml"><img src="https://github.com/RuihongY/verdi_bridge/actions/workflows/test.yml/badge.svg" alt="Tests" /></a>
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /></a>
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11 or newer" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/docs/guide.md"><b>Getting started</b></a> ·
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/docs/tools.md">Tool reference</a> ·
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/docs/architecture.md">Architecture</a> ·
+  <a href="https://github.com/RuihongY/verdi_bridge/blob/main/README.zh-CN.md">中文</a>
+</p>
+
+# Give your RTL debugging agent eyes on the waveform
+
+Connect your AI agent to **live Synopsys Verdi**. Let it find signals, inspect
+transitions, move through simulation time, and open the driving RTL—all in the
+same GUI you use to debug.
+
+> “Add the FIFO read/write pointers, go 20 cycles before the error, and investigate why full stayed high.”
+>
+> “When did BVALID drop? Show the handshake signals and the code that drives it.”
+
+Verdi Bridge turns those requests into observations from your simulation and
+visible actions in nWave and nTrace. The agent reasons; the bridge observes.
+Sixteen typed MCP tools work locally or over SSH with your existing Verdi setup.
+
+## Video walkthrough
+
+Ask an agent to investigate a bug, then watch it choose signals, inspect live waveforms and navigate RTL. A 1m38s silent demo: an English prompt and original English agent replies beside synchronized Verdi capture. This is a separate English-language run, not a translation. Tool calls are selected by the agent, not a replay script.
+
+https://github.com/user-attachments/assets/b041c1bd-4be5-4040-b281-2f15001b1e35
+
+[English video](https://github.com/user-attachments/assets/b041c1bd-4be5-4040-b281-2f15001b1e35) · [中文视频](https://github.com/user-attachments/assets/3294e374-5c43-4b67-8e20-b8a6f319d8f7)
+
+[How this was recorded](https://github.com/RuihongY/verdi_bridge/blob/main/docs/agent-demo.md) · [Installation tutorial](https://github.com/RuihongY/verdi_bridge/blob/main/docs/video-walkthrough.md)
+
+## Quick start
+
+```sh
+pip install verdi-bridge
+```
+
+Or run without a checkout using uv:
+
+```sh
+uvx verdi-bridge tcl-path
+```
+
+This prints the bundled Tcl adapter path. [Load it in Verdi and connect your MCP
+client](https://github.com/RuihongY/verdi_bridge/blob/main/docs/guide.md), then use `uvx verdi-bridge serve` as the stdio server.
+A licensed Verdi installation is required. Client: Python 3.11+; remote host:
+Python 3.6+ and Verdi's Tcl 8.6. No vendor software is bundled.
+
+## What you can do
+
+| Workflow | Tools |
+|---|---|
+| Find and display signals | `find_signals`, `browse_scope`, `add_signals` |
+| Navigate an error window | `set_cursor`, `set_time_window`, `jump_before_error` |
+| Inspect actual waveform values | `find_transitions`, `get_value_changes`, `sample_signals` |
+| Discover error times and clocks | `read_log`, `measure_clock` |
+| Follow drivers into RTL | `trace_driver`, `read_source`, `read_source_file`, `goto_source` |
+
+Waveform queries preserve X/Z values. Time arguments carry explicit units.
+The same interface works with different RTL designs; no FIFO-specific logic is
+built into the bridge. See the [Python and CLI examples](https://github.com/RuihongY/verdi_bridge/blob/main/docs/tools.md).
+
+## See it in a real debugging session
+
+Tested with UART TX, AXI-Lite, FIFO and arbiter RTL in licensed VCS/Verdi sessions.
+The agent can put relevant signals on screen, inspect their changes, and navigate
+to source while you follow along.
+
+![UART waveform and source in Verdi](https://raw.githubusercontent.com/RuihongY/verdi_bridge/main/docs/evidence/multidesign/uart-multidesign.png)
+
+[Real RTL examples](https://github.com/RuihongY/verdi_bridge/blob/main/docs/multidesign-validation.md) ·
+[Blind debugging trial](https://github.com/RuihongY/verdi_bridge/blob/main/docs/blind-validation.md) ·
+[Validation results and limitations](https://github.com/RuihongY/verdi_bridge/blob/main/docs/validation-index.md)
+
+## Project status
+
+Experimental **v0.3.1**. Tested with Verdi T-2022.06-SP2-1 on Linux.
+New-session startup is verified; attachment to an arbitrary existing GUI is not yet
+separately validated. The bridge does not automatically compile, edit or repair RTL.
+
+[Contributing](https://github.com/RuihongY/verdi_bridge/blob/main/CONTRIBUTING.md) · [Trust boundary](https://github.com/RuihongY/verdi_bridge/blob/main/SECURITY.md) ·
+[Validation limits](https://github.com/RuihongY/verdi_bridge/blob/main/docs/validation.md) · [Report an issue](https://github.com/RuihongY/verdi_bridge/issues)
+
+Inspired by the agent-to-EDA-tool workflow of
+[virtuoso-bridge-lite](https://github.com/Arcadia-1/virtuoso-bridge-lite).
+This is an independent implementation. MIT licensed; see [third-party notices](https://github.com/RuihongY/verdi_bridge/blob/main/NOTICE).
+Not affiliated with Synopsys. Verdi is a Synopsys trademark.

verdi_bridge-0.3.1/README.zh-CN.md

@@ -0,0 +1,79 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="Verdi Bridge" width="100%" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> ·
+  <a href="docs/guide.md">安装与连接</a> ·
+  <a href="docs/tools.md">工具接口</a> ·
+  <a href="docs/multidesign-validation.md">实测报告</a>
+</p>
+
+# 让 RTL 调试 agent 看见真实波形
+
+把 AI 助手接入正在运行的 **Synopsys Verdi**：找信号、查跳变、跳转时间、打开驱动源码，
+直接操作你调试时使用的 nWave 和 nTrace 界面。
+
+> “把 FIFO 的读写指针加进波形，跳到报错前 20 个周期，看看 full 为什么没撤。”
+>
+> “BVALID 到底什么时候掉下去了？把握手信号和驱动它的源码展示出来。”
+
+Agent 负责推理，bridge 返回实际仿真证据；操作过程在 Verdi 中可见。
+16 个通用 MCP 工具，支持本机和 SSH 连接。
+
+## 视频教程
+
+输入“现在有个 bug，帮我抓相关信号、分析问题”，看 agent 自己选信号、查波形并定位源码。约 1 分 56 秒，中文原文无声演示：左侧为真实 Codex 会话事件的同步排版，右侧为同次运行的 Verdi 录屏，未预编排工具调用。
+
+https://github.com/user-attachments/assets/3294e374-5c43-4b67-8e20-b8a6f319d8f7
+
+[English 原生会话](https://github.com/user-attachments/assets/b041c1bd-4be5-4040-b281-2f15001b1e35) · [中文视频](https://github.com/user-attachments/assets/3294e374-5c43-4b67-8e20-b8a6f319d8f7)
+
+[录制说明与真实调用记录](docs/agent-demo.md) · [安装教程](docs/video-walkthrough.md)
+
+## 开始使用
+
+```sh
+pip install verdi-bridge
+```
+
+也可以不 clone 仓库，直接运行：
+
+```sh
+uvx verdi-bridge tcl-path
+```
+
+按[连接指南](docs/guide.md)在 Verdi 中加载输出路径对应的 Tcl 适配器，
+再用 `uvx verdi-bridge serve` 配置 MCP 客户端。需要已有的 Verdi 安装与许可证；
+客户端 Python 3.11+，远程服务器 Python 3.6+ 和 Tcl 8.6。
+
+## 能做什么
+
+- 递归搜索信号、浏览设计层级，把信号加入波形。
+- 测量局部时钟周期和相位，向前定位并可选对齐到实际上升沿。
+- 查询指定时刻的值或整个窗口内的变化点，保留 X/Z，支持无符号 Dec 和显式有符号 SDec。
+- 读取错误日志，追踪驱动，按信号或文件读取带行号的源码并跳转。
+
+工具没有写死 FIFO 的信号或诊断规则，同一套接口已用于 UART、AXI-Lite 和仲裁器。
+
+## 真实调试过程
+
+已在 VCS/Verdi 中测试 UART、AXI-Lite、FIFO 和仲裁器 RTL。
+Agent 可以把相关信号加入波形，读取变化点，再跳转到源码；你可以在同一界面跟随检查。
+
+![Verdi 中的 UART 波形和源码](docs/evidence/multidesign/uart-multidesign.png)
+
+[实际 RTL 案例](docs/multidesign-validation.md) · [独立盲测](docs/blind-validation.md) ·
+[验证结果与限制（包含 A/B 对照）](docs/validation-index.md)
+
+## 当前状态
+
+实验版 **v0.3.1**，实测版本为 Linux 上的 Verdi T-2022.06-SP2-1。
+已验证新建 Verdi 会话的连接；接入任意已有 GUI 尚未单独验证。
+桥接工具本身不会自动编译、修改或修复 RTL。
+
+项目思路参考 [virtuoso-bridge-lite](https://github.com/Arcadia-1/virtuoso-bridge-lite)，
+代码为独立实现，采用 MIT 许可。项目与 Synopsys 无隶属关系。
+
+[参与开发](CONTRIBUTING.md) · [安全边界](SECURITY.md) ·
+[提交问题](https://github.com/RuihongY/verdi_bridge/issues)

verdi_bridge-0.3.1/SECURITY.md

@@ -0,0 +1,21 @@
+# Trust boundary
+
+The bridge is intended for one trusted OS user and a local stdio MCP client, with
+optional SSH to the same user's licensed EDA host. It exposes an operation allowlist,
+not generic code execution. It does not provide isolation from another process
+running as that user. Treat source/log content as untrusted data in LLM prompts.
+
+Keep the bridge directory owner-only (0700), use trusted parent directories, and
+allow only intended source and log roots. `VERDI_BRIDGE_SOURCE_ROOTS` governs
+source reads; `VERDI_BRIDGE_LOG_ROOTS` independently governs logs. Both default
+to the GUI working directory. Do not expose the filesystem to another user or
+publish SSH credentials. Tool results contain design data: choose an appropriate
+LLM deployment before connecting confidential designs.
+
+A timeout may leave an already running GUI action unresolved. Inspect the GUI and
+status before retrying. Use a new directory on GUI restart. Late results remain
+available for inspection, but UUID/session checks prevent their reuse as new results.
+
+For private vulnerability reporting, contact the repository maintainer through the
+hosting platform's private reporting mechanism if enabled. No public endpoint or
+maintainer email is invented by this initial local release.