Metadata-Version: 2.4
Name: vestigraph
Version: 0.2.1
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

Vestigraph 0.2.1 is available on [PyPI](https://pypi.org/project/vestigraph/0.2.1/).

```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. Rust scanning is selected automatically when the native module is available; if it cannot be imported, Vestigraph falls back to the Python scanner with a diagnostic reason. Supported Linux, macOS, and Windows wheel platforms do not need a local Rust toolchain.

`klink plugin install` installs or upgrades the KLayout plugin. Restarting the MCP client lets the existing Klink MCP server discover Vestigraph and register the local companion for that Python environment. No separate MCP server or `vestigraph setup` step is needed. Installing Python packages does not configure a chat client.

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

## 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).
