Metadata-Version: 2.4
Name: vestigraph
Version: 0.2.0
Summary: Local file and layout history with KLayout integration
License: Apache-2.0
Keywords: klayout,gds,oasis,layout-history,eda
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: fastapi<1,>=0.110
Requires-Dist: pydantic<3,>=2
Requires-Dist: uvicorn<1,>=0.27
Requires-Dist: klayout<0.31,>=0.30
Requires-Dist: vestigraph-scan-core<0.3,>=0.2
Requires-Dist: klayout-klink<0.7,>=0.6.0
Provides-Extra: klink
Requires-Dist: klayout-klink<0.7,>=0.6.0; extra == "klink"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn>=0.27; extra == "web"
Provides-Extra: preview
Requires-Dist: klayout>=0.28; extra == "preview"
Provides-Extra: storage-delta
Requires-Dist: bsdiff4>=1.2.6; extra == "storage-delta"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: httpx>=0.25; extra == "test"
Requires-Dist: playwright>=1.50; extra == "test"
Dynamic: license-file

<p align="right">
  <a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a>
</p>

# Vestigraph

Vestigraph is local file and layout history for KLayout users. It stores versions on the user's machine, shows a browser timeline, previews GDS/OASIS content, imports older files, and exports saved versions for recovery.

Vestigraph requires Python 3.10 or newer, KLayout desktop 0.30.x, `klayout-klink>=0.6.0,<0.7`, and the `vestigraph-scan-core` scanner package. The normal installation resolves Klink and the scanner as dependencies. Install the Klink KLayout plugin with the Klink command, restart MCP so Vestigraph registers its local companion for the active Python environment, then restart KLayout and open **HIST**.

## What it does

- Saves file checkpoints and history data in local user storage.
- Runs a loopback-only browser service for browsing, naming, importing, and exporting history.
- Previews GDS/OASIS versions with the Python `klayout` package.
- Uses Klink's KLayout plugin and companion-service path to record saved GDS/OASIS documents automatically.
- Exposes local history and skill-refinement tools through the existing Klink MCP extension registry.
- Keeps history, evidence, drafts, revisions, exports, login links, and control files on the user's machine.

Vestigraph does not provide cloud sync, remote collaboration, hosted storage, a model service, or automatic chat-client configuration.

## Install

The commands below install published PyPI releases. For a version not yet on PyPI, download the build-only wheel and sdist artifacts from [GitHub Actions](https://github.com/klinkdev2026/vestigraph/actions/workflows/release.yml).

```console
python -m pip install vestigraph
klink plugin install
# restart the MCP client that runs klink-mcp
# restart KLayout, open a saved GDS/OASIS layout, then click HIST
python -m vestigraph doctor --integration
```

`pip install vestigraph` installs the compatible `klayout-klink` and `vestigraph-scan-core` dependencies. `klink plugin install` is still the Klink command that installs or upgrades the KLayout plugin. Restarting the MCP client lets the Klink extension registry discover Vestigraph and register the companion for that Python environment. No separate Vestigraph MCP server is needed. Installing Python packages does not configure arbitrary chat clients.

The scanner prefers the Rust `vestigraph-scan-core` backend when it is importable and falls back to the Python scanner with a diagnostic reason if the native wheel is unavailable. Users on supported wheel platforms do not need a local Rust toolchain.

After KLayout restarts, open a saved GDS/OASIS layout and click **HIST**. The panel opens the local web history UI and shows recording status. Confirm that recording is active before editing.

## Release artifacts before PyPI

Download the Vestigraph artifact archive from the [release workflow](https://github.com/klinkdev2026/vestigraph/actions/workflows/release.yml), extract it, and install the wheel with its matching scanner wheel from that directory:

```console
python -m pip install --find-links ./wheels "vestigraph-scan-core" ./wheels/vestigraph-0.2.0-py3-none-any.whl
klink plugin install
```

Before both projects are on PyPI, put the matching platform wheels in one local directory: the two Klink Rust wheels, the `klayout_klink` core wheel, the `vestigraph_scan_core` wheel, and the Vestigraph wheel. Then install from that directory:

```console
python -m pip install --find-links ./wheels "klayout-klink>=0.6.0,<0.7" "vestigraph-scan-core" "vestigraph>=0.2,<0.3"
klink plugin install
```

Then restart the MCP client, restart KLayout, open a saved layout, and click **HIST**.

## Upgrade

Stop the old Vestigraph service if one is running. Upgrade packages, upgrade the Klink plugin, then restart MCP and KLayout:

```console
python -m pip install --upgrade "vestigraph>=0.2,<0.3"
klink plugin install
python -m vestigraph doctor --integration
```

The underlying storage CLI can still save and export local file versions, but it is not the main product installation path. Full KLayout history, HIST, and local agent tools require Klink.

## Local skills and agents

Skill refinement is experimental and disabled by default. When enabled, users can select a history range, save a request, freeze evidence, let a chosen local agent submit a draft, review validation feedback, save revisions, and export files. The package does not include private skills and does not call a model by itself.

After installation and MCP restart, use the existing Klink MCP server:

```json
{"tool":"klink.find_tools","arguments":{"domain":"vestigraph"}}
```

Then call `vestigraph.guide` and follow `next_action`. See [Local agents and skills](docs/AGENT_LOCAL.md).

## Documentation

- [Installation and upgrades](docs/INSTALLATION.md)
- [Files and history](docs/HISTORY.md)
- [Recovery and data locations](docs/RECOVERY.md)
- [Command line](docs/CLI.md)
- [Local agents and skills](docs/AGENT_LOCAL.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Release scope](docs/PUBLIC_RELEASE.md)

Vestigraph is Apache-2.0. See [Security and local access](SECURITY.md), [third-party notices](THIRD_PARTY_NOTICES.md), and [changelog](CHANGELOG.md).
