Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/gcd-reference-verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,15 @@ jobs:
cache=$(python -c 'import json; print(json.load(open("toolchain.json"))["openroad"]["cache"])')
bash tools/install-cached-package.sh openroad "$openroad" "$cache" .cache/gcd-tools
echo "$PWD/.cache/gcd-tools/openroad/bin" >> "$GITHUB_PATH"
- name: Install native Python wheels and pinned pure-Python Kepler MCP package
- name: Install native Python wheels, pinned Kepler MCP package and the separate Naja-Scope environment
run: |
mkdir -p .cache/agent-config-codex .cache/agent-config-claude
python setup/mcp.py configure --client codex --project .cache/agent-config-codex \
--venv .cache/gcd-python --apply | tee .cache/gcd-tools/setup-codex.log
python setup/mcp.py configure --client claude-code --project .cache/agent-config-claude \
--venv .cache/gcd-python --apply | tee .cache/gcd-tools/setup-claude.log
.cache/gcd-python/bin/python -m pip freeze > .cache/gcd-tools/python-packages.txt
.cache/gcd-python-scope/bin/python -m pip freeze > .cache/gcd-tools/naja-scope-packages.txt
echo "$PWD/.cache/gcd-python/bin" >> "$GITHUB_PATH"
- name: Agent MCP discovery and direct live-session verification
run: |
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ __pycache__/
*.py[cod]
.DS_Store
.venv/
.venv-scope/
.cache/
runs/
result
Expand Down
3 changes: 2 additions & 1 deletion examples/backend/gcd/reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,8 @@ and [package guides](../../../../tools/README.md), not the model task.
Follow [tool installation](../../../../tools/README.md). Use the same OpenROAD
package for both runs. The prior demo used the Docker image recorded in
`toolchain.json`; do not substitute those historical measurements for a new run.
The shared Python environment pins Kepler Formal, NajaEDA and both MCP servers.
The editing environment pins Kepler Formal, NajaEDA and the Kepler MCP server;
Naja-Scope runs from its own pinned environment.

From the repository root, in the Python environment with NajaEDA installed:

Expand Down
49 changes: 45 additions & 4 deletions scripts/gcd_reference_regression.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,38 @@ def clean_env():
return env


def scope_python():
"""Interpreter of the Naja-Scope environment, which has its own NajaEDA.

Naja-Scope only ever runs as a separate MCP server that loads files, so it
is installed beside this environment: `<venv>-scope`, or NAJA_SCOPE_PYTHON.
"""
override = os.environ.get("NAJA_SCOPE_PYTHON")
prefix = Path(sys.prefix)
# Keep the venv's own executable path: resolving the symlink would leave it.
python = Path(override).expanduser().absolute() if override else (
prefix.with_name(prefix.name + "-scope")
/ ("Scripts/python.exe" if os.name == "nt" else "bin/python"))
if not python.is_file():
raise ValueError(f"Naja-Scope environment not found at {python}; "
"see tools/naja-scope/install.md")
return python


def scope_identity(python, pins):
"""Check the Naja-Scope pins in the environment its server runs from."""
code = ("import importlib.metadata as m, json, sys; "
"print(json.dumps({name: m.version(name) for name in sys.argv[1:]}))")
reply = subprocess.run([str(python), "-I", "-c", code, *pins], env=clean_env(),
stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=60)
if reply.returncode != 0:
raise ValueError("Naja-Scope environment is not usable: " + reply.stderr.strip()[-300:])
versions = json.loads(reply.stdout)
if versions != pins:
raise ValueError(f"Naja-Scope packages do not match toolchain.json: {versions}")
return versions


def run_command(directory, command, *, timeout, env=None, accept_nonzero=False):
directory.mkdir()
save(directory / "command.json", {"argv": [str(x) for x in command], "cwd": str(directory)})
Expand Down Expand Up @@ -129,6 +161,10 @@ def scope_payload(result):
value = result.structuredContent
if value is None:
value = json.loads(next(c.text for c in result.content if c.type == "text"))
# Naja-Scope 0.1.25+ publishes structured output, which the MCP SDK wraps
# as {"result": payload}; earlier releases return the payload itself.
if isinstance(value, dict) and set(value) == {"result"} and isinstance(value["result"], dict):
value = value["result"]
if not isinstance(value, dict) or "error" in value:
raise ValueError(f"Naja-Scope error: {value}")
return value
Expand All @@ -145,12 +181,12 @@ def validate_scope_query(name, value):
raise ValueError(f"Naja-Scope returned no {kind} for the reference boundary")


async def inspect_scope(directory, design, liberty):
async def inspect_scope(directory, design, liberty, python):
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

directory.mkdir()
params = StdioServerParameters(command=sys.executable,
params = StdioServerParameters(command=str(python),
args=["-m", "naja_scope.server"], env=clean_env())
with (directory / "server.log").open("w") as log:
async with stdio_client(params, errlog=log) as streams:
Expand Down Expand Up @@ -179,6 +215,7 @@ def input_hashes():
return {str(path.relative_to(ROOT)): digest(path) for path in
(EXAMPLE / "input.v", EXAMPLE / "constraints.sdc", REFERENCE / "edit.py",
PLATFORM / "run.tcl", ROOT / "toolchain.json", ROOT / "tools/python-requirements.txt",
ROOT / "tools/naja-scope/requirements.txt",
ROOT / "tools/kepler-formal/verify.py", ROOT / "tools/kepler-formal/mcp-requirements.txt")}


Expand All @@ -194,6 +231,8 @@ def prepare(work, fixture):
run_command(work / "openroad-version", [tools["openroad"], "-version"], timeout=30)
version = (work / "openroad-version/tool.log").read_text()
require_openroad_revision(version, pins["openroad"]["source_revision"])
tools["naja_scope_python"] = str(scope_python())
scope_packages = scope_identity(tools["naja_scope_python"], pins["naja_scope_packages"])
save(work / "kepler-packages.json", SEC.package_identity())
spec = importlib.util.spec_from_file_location("gcd_fixture", PLATFORM / "fetch_fixture.py")
module = importlib.util.module_from_spec(spec)
Expand All @@ -210,7 +249,7 @@ def prepare(work, fixture):
"fixture_manifest_sha256": digest(fixture / "manifest.json"),
"tools": tools, "openroad_version": version.strip(),
"python": sys.version, "python_packages": packages,
"toolchain": pins}
"naja_scope_packages": scope_packages, "toolchain": pins}
save(work / "metadata.json", metadata)
return metadata

Expand Down Expand Up @@ -255,7 +294,9 @@ def stage(name, work, fixture, timeout):
timeout=timeout, env=env)
save(directory / "summary.json", physical_summary(directory))
elif name == "inspect":
asyncio.run(asyncio.wait_for(inspect_scope(directory, design, liberty), timeout=timeout))
asyncio.run(asyncio.wait_for(
inspect_scope(directory, design, liberty, metadata["tools"]["naja_scope_python"]),
timeout=timeout))
elif name == "edit":
ast.parse((REFERENCE / "edit.py").read_text())
run_command(directory, [sys.executable, str(REFERENCE / "edit.py"), "--liberty", str(liberty),
Expand Down
5 changes: 3 additions & 2 deletions scripts/live_inspection_regression.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))

from scripts.gcd_reference_regression import clean_env, save, scope_payload
from scripts.gcd_reference_regression import clean_env, save, scope_payload, scope_python
from scripts.live_session_regression import LIBERTY, FIRST, SECOND
from tools.live_session import LiveDesignSession

Expand All @@ -22,7 +22,8 @@ async def run(work):
source, library = work / "input.v", work / "cells.lib"
source.write_text("module top(input a, output y); BUF g(.A(a), .Y(y)); endmodule\n")
library.write_text(LIBERTY)
params = StdioServerParameters(command=sys.executable, args=["-m", "naja_scope.server"],
# Scope reads the exported files from its own environment, not from this kernel's.
params = StdioServerParameters(command=str(scope_python()), args=["-m", "naja_scope.server"],
env=clean_env(), cwd=str(ROOT))
with LiveDesignSession(source, [library], work / "session") as live:
assert live.verify()["status"] == "proved"
Expand Down
13 changes: 10 additions & 3 deletions setup/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,20 @@ python3.13 setup/mcp.py configure --client claude-code --apply

The same installer checks and reuses `.venv`, installs only missing/mismatched
pins, tests real MCP initialization, lists tools and calls Kepler's native
information tool, then writes the selected client's **project-local** config:
information tool, then writes the selected client's **project-local** config.
It also creates or reuses `.venv-scope`, the separate
[Naja-Scope environment](../tools/naja-scope/install.md); registering the
Naja-Scope server with the agent remains a manual step described there.

| Client | Generated file | Activation |
| --- | --- | --- |
| Codex | `.codex/config.toml` | Trust the project, reload the client, check `/mcp` |
| Claude Code | `.mcp.json` | Approve the project MCP server, reload, check `/mcp` |

Use `--venv /absolute/existing-venv` to reuse the kernel's environment, and
`--project /absolute/project` to configure a different project. An existing venv
`--project /absolute/project` to configure a different project. The Naja-Scope
environment defaults to that venv's path plus `-scope`; `--scope-venv` selects
another one. An existing venv
is modified only with `--apply`; use a dedicated one if its other packages must
remain unchanged. Config entries use absolute paths to that interpreter and
this checkout's launcher, so keep both at those paths. Regenerate after moving.
Expand All @@ -41,6 +46,7 @@ The standard generated files are ignored by this repository.
The installer uses [pinned native wheels](../tools/python-requirements.txt),
[kernel packages](../tools/session-requirements.txt) and the
[pinned pure-Python wrapper](../tools/kepler-formal/mcp-requirements.txt).
The Naja-Scope environment gets only [its own pins](../tools/naja-scope/requirements.txt).
No Nix, native build or source submodule is needed for this MCP. Missing native
wheels are an error, not permission to compile. The launcher checks the package
pins on every startup. Transitive dependencies are not fully locked.
Expand All @@ -51,7 +57,8 @@ Check an existing installation without installing or changing configuration:
python3.13 setup/mcp.py check --venv .venv
```

This checks transport/tool discovery and native loading, **not** whether your
This checks transport/tool discovery and native loading, and that the
Naja-Scope environment matches its pins, **not** whether your
agent has approved or displayed the tools, and not circuit equivalence. In the
agent's tool list confirm `get_kepler_formal_info`, `attach_session`,
`verify_session` and `get_session_reports`. Existing user/admin settings can
Expand Down
62 changes: 58 additions & 4 deletions setup/mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,18 @@ def python_in(directory):
return directory / ("Scripts/python.exe" if os.name == "nt" else "bin/python")


def install(directory):
def ensure_venv(directory, option):
python = python_in(directory)
if directory.exists():
if not (directory / "pyvenv.cfg").is_file() or not python.is_file():
raise ValueError("Existing environment is not a usable venv; choose another --venv")
raise ValueError(f"Existing environment is not a usable venv; choose another {option}")
else:
venv.EnvBuilder(with_pip=True).create(directory)
return python


def install(directory):
python = ensure_venv(directory, "--venv")
state = json.loads(run([python, "-I", SCRIPT, "identity"], capture=True).stdout)
if not state["packages_match"]:
run([python, "-I", "-m", "pip", "install", "--only-binary=:all:",
Expand All @@ -85,6 +90,50 @@ def install(directory):
return python


def scope_directory(directory):
"""Naja-Scope's own venv, beside Kepler's: it needs a newer NajaEDA than Kepler pins."""
return directory.with_name(directory.name + "-scope")


def scope_state(python):
"""Compare the Naja-Scope pins with what its environment has installed."""
pins = json.loads((ROOT / "toolchain.json").read_text())["naja_scope_packages"]
code = ("import importlib.metadata as m, json, sys\n"
"def version(name):\n"
" try:\n"
" return m.version(name)\n"
" except m.PackageNotFoundError:\n"
" return None\n"
"print(json.dumps({name: version(name) for name in sys.argv[1:]}))")
versions = json.loads(run([python, "-I", "-c", code, *pins], capture=True).stdout)
return {"packages_match": versions == pins, "versions": versions}


def install_scope(directory):
"""Create or reuse the Naja-Scope environment, kept separate from Kepler's."""
python = ensure_venv(directory, "--scope-venv")
if scope_state(python)["packages_match"]:
print("Reusing the matching Naja-Scope installation.", flush=True)
else:
run([python, "-I", "-m", "pip", "install", "--only-binary=:all:",
"-r", ROOT / "tools/naja-scope/requirements.txt"])
run([python, "-I", "-m", "pip", "check"])
return python


def check_scope(directory):
"""Read-only: the Naja-Scope server interpreter exists and matches its pins."""
python = python_in(directory)
if not python.is_file():
raise ValueError(f"Naja-Scope environment not found: {directory}")
state = scope_state(python)
if not state["packages_match"]:
raise ValueError(f"Naja-Scope environment does not match the toolchain pins: {state['versions']}")
result = {"naja_scope": "ready", "python": str(python), "packages": state["versions"]}
print(json.dumps(result, indent=2), flush=True)
return result


def configuration(client, python):
config = {"command": str(python), "args": ["-I", str(LAUNCHER)]}
if client == "codex":
Expand Down Expand Up @@ -200,6 +249,8 @@ def main(argv=None):
parser.add_argument("--client", choices=("codex", "claude-code"))
parser.add_argument("--project", type=Path, default=ROOT)
parser.add_argument("--venv", type=Path, help="Existing/new dedicated venv (default: PROJECT/.venv)")
parser.add_argument("--scope-venv", type=Path,
help="Existing/new Naja-Scope venv (default: the --venv path plus -scope)")
parser.add_argument("--name", default="kepler-formal")
parser.add_argument("--apply", action="store_true", help="Install and write project config; otherwise preview only")
args = parser.parse_args(argv)
Expand All @@ -211,9 +262,11 @@ def main(argv=None):
return
project = args.project.resolve(strict=True)
directory = args.venv.resolve() if args.venv else project / ".venv"
scope = args.scope_venv.resolve() if args.scope_venv else scope_directory(directory)
python = python_in(directory)
if args.action == "check":
check(python)
check_scope(scope)
return
if not args.client:
parser.error("configure requires --client")
Expand All @@ -224,12 +277,13 @@ def main(argv=None):
old = read_config(path)
new = render_config(old, args.client, args.name, entry)
print(json.dumps({"client": args.client, "scope": "project", "config": str(path),
"environment": str(directory), "server": entry,
"apply": args.apply}, indent=2), flush=True)
"environment": str(directory), "naja_scope_environment": str(scope),
"server": entry, "apply": args.apply}, indent=2), flush=True)
if not args.apply:
print("Preview only. Add --apply to install, test MCP discovery, and register.")
return
install(directory)
install_scope(scope)
check(python)
write_config(path, old, new)
print("Registered. Reload the agent and approve the trusted project/server. "
Expand Down
Loading
Loading