coda-node 0.1.0__tar.gz

coda_node-0.1.0/.agents/skills/read-docs/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: read-docs
+description: Gather context from docs/ before implementing or modifying a feature. Use when starting work on a feature, investigating how something works, or onboarding to the codebase.
+---
+
+Gather context from `docs/` before implementing or modifying a feature.
+
+## How to use
+
+1. **Start at `docs/INDEX.md`** — read it to discover all feature areas and the source layout.
+2. **Navigate to the relevant area** — open the area's `INDEX.md` to see its topics, key source files, and cloud counterparts.
+3. **Read the topic files** that relate to your task for detailed behavior, API formats, config fields, sequence diagrams, and cross-references.
+4. **Check `README.md`** for user-facing quickstart, CLI flags, configuration tables, and endpoint summaries.
+
+## Tips
+
+- Area `INDEX.md` files list the source files that implement each feature — use these to locate code quickly.
+- Cross-links between topic files connect related concepts (e.g. auth ↔ node ↔ VPN).
+- Cloud counterpart tables (where present) point to the corresponding cloud-side files and endpoints.
+- If a doc file references a config field or env var, the full reference is in the `configuration/` area.

coda_node-0.1.0/.agents/skills/update-docs/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: update-docs
+description: Keep docs/ and README.md in sync with source code changes. Use after modifying source files to update affected documentation.
+---
+
+Keep `docs/` and `README.md` in sync with source code changes.
+
+## Documentation layout
+
+The `docs/` directory is organized into feature-area subdirectories.
+Discover the current structure by reading `docs/INDEX.md` and listing
+subdirectories — do not assume a fixed set of areas or files.
+
+Each feature area follows this pattern:
+
+```
+docs/<area>/
+├── INDEX.md          # Overview, topics table, key source files, cloud counterparts
+├── <topic-a>.md
+└── <topic-b>.md
+```
+
+`docs/INDEX.md` is the top-level entry point linking to all areas.
+`README.md` is the user-facing quickstart (not a duplicate of `docs/`).
+
+## Conventions
+
+- Each feature area has its own subdirectory with an `INDEX.md`.
+- `INDEX.md` files contain: overview, topics table, key source files table, and cloud counterparts (if any).
+- Topic files document: purpose, API/format details, code references, and cross-links.
+- Use "node" (not "bootstrap" or "self-service") for provisioning terminology.
+- External identifiers from other codebases keep their original names with a "(cloud-side naming)" annotation.
+
+## How to update
+
+1. **Read the staged diff** (`git diff --cached`) to identify which source files changed and what behavior was added/modified/removed.
+2. **Discover affected docs**: read `docs/INDEX.md` to understand the current areas, then find the doc files that cover the changed source files. Look at existing cross-references and `INDEX.md` "Key Files" tables to map source → docs.
+3. **Read the affected doc files** and compare against the new source behavior.
+4. **Update docs** to reflect changes: signatures, config fields, env vars, error types, endpoints, sequence diagrams, etc.
+5. **Update `README.md`** if the change affects quickstart, configuration, CLI, endpoints, or error handling.
+6. **Update `docs/INDEX.md`** if you add/remove/rename a feature area or the source layout changes.
+7. **Print a short summary** of what was updated and why.
+
+## Rules
+
+- Do NOT assume a fixed file/directory structure — always discover it.
+- Do NOT create new feature subdirectories without clear justification.
+- Do NOT add speculative documentation for unimplemented features.
+- Keep doc files concise — describe behavior, not implementation details line-by-line.
+- Every doc file must have a `# Title` and be linked from its area's `INDEX.md`.
+- If no docs need updating (e.g. test-only changes, formatting), say so and exit.

coda_node-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+      - name: Mypy
+        run: uv run mypy src/coda_node
+
+      - name: Package build
+        run: uv build
+
+      - name: Pytest
+        run: uv run pytest --cov --cov-report=term-missing

coda_node-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types:
+      - created
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

coda_node-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+.DS_Store
+.e2e-credentials.json

coda_node-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format-check
+        name: Ruff format check
+        entry: uv run ruff format --check .
+        language: system
+        pass_filenames: false
+      - id: ruff-lint
+        name: Ruff lint
+        entry: uv run ruff check .
+        language: system
+        pass_filenames: false
+      - id: update-docs
+        name: Update docs
+        entry: bash -c 'claude -p --dangerously-skip-permissions --allowedTools "Read,Edit,Write,Bash,Glob,Grep" --append-system-prompt-file .agents/skills/update-docs/SKILL.md "Review the staged diff and update any docs that are out of date. If nothing needs updating, do nothing." && git add docs/ README.md 2>/dev/null || true'
+        language: system
+        pass_filenames: false
+        files: ^src/coda_node/
+        stages: [pre-commit]

coda_node-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

coda_node-0.1.0/Dockerfile.e2e

@@ -0,0 +1,17 @@
+FROM python:3.12-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends openvpn iproute2 curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+COPY pyproject.toml LICENSE README.md ./
+COPY src/ src/
+COPY tests/ tests/
+
+RUN uv sync --frozen --no-install-workspace 2>/dev/null || uv sync
+
+ENTRYPOINT ["uv", "run", "pytest"]
+CMD ["tests/test_node_smoketest.py", "-v", "-m", "smoketest"]

coda_node-0.1.0/LICENSE

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

coda_node-0.1.0/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: coda-node
+Version: 0.1.0
+Summary: Minimal server runtime for connecting execution backends to Coda.
+Author: Conductor Quantum
+License: MIT License
+        
+        Copyright (c) 2026 Conductor Quantum
+        
+        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
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: pyjwt>=2.0.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: uvicorn>=0.30.0
+Description-Content-Type: text/markdown
+
+# coda-node
+
+Production-ready runtime for connecting an execution backend to the Coda
+cloud platform.
+
+It boots a FastAPI service, provisions or reconnects node credentials, manages
+VPN health, consumes Redis jobs, and posts signed execution results back to
+Coda.
+
+## What It Does
+
+- Provisions a node from a one-time node token
+- Reconnects on restart with persisted JWT credentials
+- Verifies and continuously monitors VPN connectivity
+- Sends periodic heartbeats to keep QPU status "online"
+- Consumes jobs from Redis Streams with crash recovery
+- Optionally batches Redis jobs when the executor implements `batch_run`
+- Sends JWT-signed webhook results to Coda with retry
+- Drains in-flight work on graceful shutdown
+- Supports pluggable execution backends via factory convention
+- Auto-discovers executor factories from installed packages
+
+## Install
+
+```bash
+uv sync --dev
+```
+
+Requires Python 3.11+.  Two equivalent CLI entry points are installed:
+
+- `coda`
+- `coda-node`
+
+## Quick Start
+
+Provision with a node token:
+
+```bash
+uv run coda-node start --token <node-token>
+```
+
+Or set the token as an environment variable:
+
+```bash
+export CODA_NODE_TOKEN=<node-token>
+uv run coda start
+```
+
+After a successful first run, credentials are persisted to disk and
+subsequent restarts reconnect automatically without a fresh token.
+
+## How It Works
+
+On startup the runtime:
+
+1. Loads configuration from `CODA_`-prefixed environment variables, then
+   persisted state on disk, then hardcoded defaults.
+2. Connects to Coda using either a node token or persisted JWT
+   credentials (with exponential-backoff retry on transient failures).
+3. Brings up or validates VPN connectivity when required.
+4. Starts the FastAPI service, a background Redis Streams consumer, and
+   a heartbeat loop that periodically POSTs node status to the cloud.
+5. Dispatches jobs to the configured executor, optionally in batches,
+   and posts signed results back via webhook.
+
+On shutdown the runtime drains the in-flight job (up to
+`CODA_SHUTDOWN_DRAIN_TIMEOUT_SEC`), cancels background tasks, closes
+connections, and stops the managed VPN daemon.
+
+## Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /health` | Liveness probe.  Returns `200` if the process is running. |
+| `GET /ready` | Readiness probe.  Returns `200` with component status when VPN and Redis are healthy; `503` when either is degraded or the check times out. |
+
+The `/ready` response body always includes `vpn_state`, `redis_healthy`,
+and `current_job` fields for observability.
+
+## Configuration
+
+All settings are driven by `CODA_`-prefixed environment variables.  When
+no node token is provided, the runtime automatically loads
+previously persisted config from disk.
+
+### Core
+
+| Variable | Default | Description |
+|---|---|---|
+| `CODA_NODE_TOKEN` | `""` | One-time node token for first-run provisioning. |
+| `CODA_JWT_PRIVATE_KEY` | `""` | PEM-encoded RSA private key for direct JWT startup. |
+| `CODA_JWT_KEY_ID` | `""` | `kid` header value for signed JWTs. |
+| `CODA_REDIS_URL` | `""` | Redis connection string (`redis://…`). |
+| `CODA_WEBAPP_URL` | `https://coda.conductorquantum.com` | Coda cloud base URL. Overridden by the node bundle on first connect. |
+| `CODA_HOST` | `0.0.0.0` | Bind address for the FastAPI server. |
+| `CODA_PORT` | `8080` | Bind port for the FastAPI server. |
+| `CODA_EXECUTOR_FACTORY` | `""` | Import path for a custom executor (see below). Highest priority when set. |
+| `CODA_DEVICE_CONFIG` | `""` | Path to a YAML device config read by the executor factory. Defaults to `./site/device.yaml` if that file exists. The runtime also looks for an optional top-level `executor_factory` key in this file when `CODA_EXECUTOR_FACTORY` is unset. |
+
+Provide either `CODA_NODE_TOKEN` for auto-provisioning, or both
+`CODA_JWT_PRIVATE_KEY` and `CODA_JWT_KEY_ID` for direct JWT startup.
+
+### VPN
+
+| Variable | Default | Description |
+|---|---|---|
+| `CODA_VPN_REQUIRED` | `true` | Fail preflight if no VPN tunnel is detected. |
+| `CODA_VPN_CHECK_INTERVAL_SEC` | `10` | Seconds between background VPN health checks. |
+| `CODA_VPN_INTERFACE_HINT` | `null` | Specific TUN/TAP interface name to look for. |
+| `CODA_ALLOW_DEGRADED_STARTUP` | `false` | Allow the server to start even if VPN preflight fails. |
+
+### Resilience
+
+| Variable | Default | Description |
+|---|---|---|
+| `CODA_NODE_CONNECT_RETRIES` | `3` | Max attempts when connecting to the Coda cloud. |
+| `CODA_SHUTDOWN_DRAIN_TIMEOUT_SEC` | `30` | Seconds to wait for an in-flight job before forced shutdown. |
+| `CODA_NODE_TIMEOUT_SEC` | `15` | HTTP timeout for node connect requests. |
+
+## Persisted State
+
+After successful node provisioning, the runtime writes:
+
+| File | Contents |
+|---|---|
+| `/tmp/coda.config` | JSON with QPU identity, Redis URL, API paths, and VPN settings. |
+| `/tmp/coda-private-key` | PEM-encoded RSA private key. |
+
+Both files use `0600` permissions on POSIX systems and are validated on
+read.  They enable token-free reconnects across restarts, preserving JWT
+credentials, machine fingerprint, VPN profile path, and connection
+settings.
+
+To wipe persisted state, run `coda reset`.
+
+## CLI
+
+```
+coda start [--token TOKEN] [--host HOST] [--port PORT] [--daemon]
+```
+
+Start the node server.  Pass `--token` on first run for node
+provisioning.  Use `--daemon` (or `-d`) to run as a background process.
+
+```
+coda stop
+```
+
+Stop the background daemon process.
+
+```
+coda status
+```
+
+Show daemon status (running/stopped, PID, log file, VPN interface).
+
+```
+coda logs [-n LINES]
+```
+
+Show recent daemon log output (default: last 50 lines).
+
+```
+coda doctor
+```
+
+Print a diagnostic summary (endpoints, executor, VPN interface, OpenVPN
+status).
+
+```
+coda stop-vpn
+```
+
+Stop the managed OpenVPN daemon without clearing credentials.
+
+```
+coda reset
+```
+
+Stop the daemon and VPN, then remove all persisted runtime files.
+
+## Executor Resolution
+
+`load_executor()` resolves the execution backend in priority order:
+
+1. **`CODA_EXECUTOR_FACTORY`** (explicit) -- set to a `module:attribute`
+   import path to force a specific executor factory.
+2. **`executor_factory` in `CODA_DEVICE_CONFIG`** -- optional top-level YAML
+   key used when the env var is unset.
+3. **Convention-based auto-discovery** -- scan installed packages for
+   `<pkg>.executor_factory:create_executor`.  If exactly one match is
+   found, use it.  If multiple match, log a warning and fall back.
+4. **`NoopExecutor`** fallback -- returns deterministic all-zeros results,
+   allowing the service to boot without hardware integration.
+
+### Factory Convention
+
+Backend packages should expose a factory at
+`<package>.executor_factory:create_executor`.  The factory must be
+either:
+
+- A callable that accepts a `Settings` object and returns an object
+  with an async `run(ir, shots)` method.
+- A callable that accepts no parameters and returns the same.
+- A pre-built object that already has a `run` method.
+
+### Example: Custom Executor
+
+```python
+from coda_node.server.executor import ExecutionResult
+from coda_node.server.ir import NativeGateIR
+
+
+class MyExecutor:
+    async def run(self, ir: NativeGateIR, shots: int) -> ExecutionResult:
+        counts = run_on_hardware(ir, shots)
+        return ExecutionResult(
+            counts=counts,
+            execution_time_ms=42.0,
+            shots_completed=shots,
+        )
+
+
+def create_executor() -> MyExecutor:
+    return MyExecutor()
+```
+
+Place this in `my_package/executor_factory.py` and install the package.
+The runtime will discover it automatically.  Or set it explicitly:
+
+```bash
+export CODA_EXECUTOR_FACTORY="my_package.executor_factory:create_executor"
+```
+
+## Error Handling
+
+All domain exceptions inherit from `CodaError`, making it easy to
+distinguish expected operational errors from unexpected bugs:
+
+| Exception | When |
+|---|---|
+| `ConfigError` | Invalid or missing configuration. |
+| `AuthError` | JWT signing or verification failure. |
+| `VPNError` | VPN tunnel or health check failure. |
+| `NodeError` | Node provisioning or reconnect failure. |
+| `ExecutorError` | Executor loading or job execution failure. |
+| `WebhookError` | Webhook delivery failure. |
+
+Import from the top-level package:
+
+```python
+from coda_node import CodaError
+from coda_node.errors import ConfigError, VPNError
+```
+
+## Development
+
+Install dependencies (including dev tools):
+
+```bash
+uv sync --dev
+```
+
+Run the full quality check suite:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src/coda_node
+uv build
+uv run pytest --cov --cov-report=term-missing
+```
+
+Run the opt-in live smoke tests against
+`https://coda.conductorquantum.com`:
+
+```bash
+export CODA_RUN_E2E=1
+export CODA_E2E_NODE_TOKEN=<node-token>
+uv run pytest -m e2e
+```
+
+To include the live VPN tunnel check as well:
+
+```bash
+export CODA_RUN_VPN_E2E=1
+uv run pytest -m e2e
+```
+
+Install pre-commit hooks (runs ruff format and lint on every commit):
+
+```bash
+uv run pre-commit install
+```
+
+Run all hooks manually:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+## Architecture
+
+- **FastAPI** -- HTTP service, lifespan management, health endpoints
+- **Pydantic Settings** -- environment-driven configuration with layered
+  defaults and persisted state
+- **Redis Streams** -- job delivery with consumer groups and crash recovery
+- **httpx** -- async HTTP for webhooks and node API calls
+- **RS256 JWT** -- authentication between the node and the Coda cloud
+- **OpenVPN** -- managed as a subprocess when VPN connectivity is required