graphcore-studio 0.2.0__tar.gz

graphcore_studio-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: build-and-test
+on: [push, pull_request]
+jobs:
+  packaging:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install build twine
+      - run: python -m build --sdist --wheel
+      - run: python -m twine check dist/*.whl dist/*.tar.gz
+      - name: Install the wheel and exercise the native runtime
+        shell: bash
+        run: |
+          python -m pip install --no-deps --target "$RUNNER_TEMP/graphcore-installed" dist/*.whl
+          cd "$RUNNER_TEMP"
+          PYTHONPATH="$RUNNER_TEMP/graphcore-installed" python - <<'PY'
+          from graphcore import END, Graph
+          from studio.server import TEMPLATES, WEB
+          assert (WEB / "index.html").is_file()
+          assert len(list(TEMPLATES.glob("*.json"))) == 5
+          with Graph() as graph:
+              graph.add_node("check", lambda state, context: {"ok": True})
+              graph.set_entry("check").add_edge("check", END)
+              assert graph.invoke().state["ok"] is True
+          PY
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ['3.9', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+      - run: cmake --build build --config Release
+      - run: ctest --test-dir build -C Release --output-on-failure
+  sanitizers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: >-
+          c++ -std=c++17 -g -fsanitize=address,undefined -fno-omit-frame-pointer
+          -Iinclude src/graphcore.cpp tests/core_tests.cpp -o core_tests
+      - run: ./core_tests

graphcore_studio-0.2.0/.github/workflows/wheels.yml

@@ -0,0 +1,84 @@
+name: build-release-artifacts
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: wheels (${{ matrix.runner }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        runner:
+          - ubuntu-latest
+          - ubuntu-24.04-arm
+          - windows-latest
+          - macos-15-intel
+          - macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build wheels for supported CPython versions
+        run: python -m pip install cibuildwheel && python -m cibuildwheel --output-dir wheelhouse
+        env:
+          CIBW_BUILD: 'cp39-* cp310-* cp311-* cp312-* cp313-*'
+          CIBW_SKIP: '*-musllinux_*'
+          CIBW_TEST_COMMAND: >-
+            python -c "from graphcore import END, Graph; g=Graph(); g.add_node('probe', lambda s,c: {'ok': True}); g.set_entry('probe').add_edge('probe', END); assert g.invoke().state['ok']; g.close()"
+          CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET=11.0
+          CIBW_BUILD_VERBOSITY: '1'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-wheels-${{ matrix.runner }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+          retention-days: 14
+
+  sdist:
+    name: source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install build twine
+      - run: python -m build --sdist --outdir dist
+      - run: python -m twine check dist/*.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 14
+
+  collect:
+    name: collect and check release files
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install twine
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: package-*
+          path: dist
+          merge-multiple: true
+      - run: python -m twine check dist/*.whl dist/*.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          name: graphcore-studio-distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 30

graphcore_studio-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+/build/
+/build-*/
+*.checkpoint
+*.checkpoint.tmp
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+/dist/
+/studio/data/*
+!/studio/data/.gitkeep
+/.env
+/studio/data/.env

graphcore_studio-0.2.0/CMakeLists.txt

@@ -0,0 +1,55 @@
+cmake_minimum_required(VERSION 3.16)
+project(GraphCore VERSION 0.2.0 LANGUAGES CXX)
+option(GRAPHCORE_BUILD_TESTS "Build tests" ON)
+option(GRAPHCORE_BUILD_EXAMPLES "Build examples" ON)
+option(GRAPHCORE_BUILD_PYTHON "Build C ABI shared library for Python" ON)
+set(GRAPHCORE_PYTHON_PACKAGE_DIR "" CACHE STRING "Install the shared library inside this Python package directory")
+add_library(graphcore STATIC src/graphcore.cpp)
+add_library(GraphCore::graphcore ALIAS graphcore)
+target_compile_features(graphcore PUBLIC cxx_std_17)
+target_include_directories(graphcore PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include>)
+set_target_properties(graphcore PROPERTIES POSITION_INDEPENDENT_CODE ON)
+if(GRAPHCORE_BUILD_PYTHON)
+  add_library(graphcore_shared SHARED src/c_api.cpp)
+  target_link_libraries(graphcore_shared PRIVATE graphcore)
+  target_compile_definitions(graphcore_shared PRIVATE GRAPHCORE_BUILD_SHARED)
+  set_target_properties(graphcore_shared PROPERTIES OUTPUT_NAME graphcore ARCHIVE_OUTPUT_NAME graphcore_c)
+endif()
+if(GRAPHCORE_BUILD_EXAMPLES)
+  add_executable(graphcore_demo examples/approval.cpp)
+  target_link_libraries(graphcore_demo PRIVATE graphcore)
+endif()
+if(GRAPHCORE_BUILD_TESTS)
+  enable_testing()
+  add_executable(graphcore_tests tests/core_tests.cpp)
+  target_link_libraries(graphcore_tests PRIVATE graphcore)
+  add_test(NAME core COMMAND graphcore_tests)
+  if(GRAPHCORE_BUILD_PYTHON)
+    find_package(Python3 COMPONENTS Interpreter QUIET)
+    if(Python3_FOUND)
+      add_test(NAME python COMMAND ${CMAKE_COMMAND} -E env
+        "PYTHONPATH=${CMAKE_CURRENT_SOURCE_DIR}/python"
+        "GRAPHCORE_LIBRARY=$<TARGET_FILE:graphcore_shared>"
+        ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_python.py)
+    endif()
+  endif()
+endif()
+include(GNUInstallDirs)
+install(TARGETS graphcore EXPORT GraphCoreTargets ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+if(GRAPHCORE_BUILD_PYTHON)
+  if(GRAPHCORE_PYTHON_PACKAGE_DIR)
+    set(GRAPHCORE_SHARED_INSTALL_DIR ${GRAPHCORE_PYTHON_PACKAGE_DIR})
+  else()
+    set(GRAPHCORE_SHARED_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR})
+  endif()
+  install(TARGETS graphcore_shared
+    LIBRARY DESTINATION ${GRAPHCORE_SHARED_INSTALL_DIR}
+    RUNTIME DESTINATION ${GRAPHCORE_SHARED_INSTALL_DIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+endif()
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(EXPORT GraphCoreTargets NAMESPACE GraphCore:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/GraphCore)
+include(CMakePackageConfigHelpers)
+configure_package_config_file(cmake/GraphCoreConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/GraphCoreConfig.cmake INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/GraphCore)
+write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/GraphCoreConfigVersion.cmake VERSION ${PROJECT_VERSION} COMPATIBILITY SameMajorVersion)
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/GraphCoreConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/GraphCoreConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/GraphCore)

graphcore_studio-0.2.0/LICENSE

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

graphcore_studio-0.2.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: graphcore-studio
+Version: 0.2.0
+Summary: A local-first visual agent workflow studio powered by a native C++ graph runtime
+Keywords: agents,agentic-workflows,graph,C++,visual-workflow-builder
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: models
+Requires-Dist: openrouter<1,>=0.10; extra == "models"
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2; extra == "pydantic"
+Description-Content-Type: text/markdown
+
+# GraphCore Studio
+
+**Design local agent workflows on a canvas. Run them with a C++ engine. Extend them with Python.**
+
+GraphCore Studio is an interactive, local-first visual agent framework. Drag nodes onto a canvas, connect agent handoffs, add conditional branches, validate structured output, call Python tools, and pause for human approval. Save and run workflows on your own machine.
+
+## Start Studio
+
+Requirements: Python 3.9+ and a C++17 compiler. You do not need CMake, Node.js, Docker, API keys, an internet connection, or a model to try the included workflows.
+
+From the project folder, run one command:
+
+```bash
+python3 run_studio.py
+```
+
+Open [http://127.0.0.1:8787](http://127.0.0.1:8787). The launcher compiles the C++ shared library on first run, then opens a server accessible only from your machine. On Windows, use PowerShell in a Visual Studio Developer Terminal with the C++ workload installed:
+
+```powershell
+py run_studio.py
+```
+
+If Python was installed through the Windows Store and `py` is unavailable, run `python run_studio.py` from the Visual Studio Developer Terminal.
+
+Stop the server with Ctrl+C. Workflows and run history live in `studio/data/`; drafts are saved in this browser. Run `python3 run_studio.py --help` to configure the port, data directory, or Python tool plugins.
+
+### Install the PyPI package
+
+After the first release is published, install the prebuilt package with:
+
+```bash
+python -m pip install "graphcore-studio[models,pydantic]"
+graphcore-studio
+```
+
+The wheel bundles the C++ runtime and Studio UI. Source installs build the native runtime and therefore require a C++17 compiler and CMake. The distribution is named `graphcore-studio`; its Python API imports as `graphcore`.
+
+### Use Pydantic
+
+The built-in structured-output validator works offline with no extra packages. To enable optional Pydantic v2 validation:
+
+```bash
+python3 -m pip install -r requirements-pydantic.txt
+python3 run_studio.py
+```
+
+On Windows, replace `python3` with `py -3`. Restart Studio after installing packages. The Structured output node shows whether Pydantic is available.
+
+### Use OpenRouter models
+
+The **Chat Model** and **Agent** nodes use GraphCore's model adapter with the official OpenRouter Python SDK. C++ owns graph scheduling, state commits, conditions, and checkpoints; the Python wrapper calls the SDK. The OpenRouter request runs through the project-owned adapter rather than a chain framework.
+
+Install the SDK into the Python environment used to run Studio:
+
+```bash
+python3 -m pip install -r requirements-models.txt
+python3 run_studio.py
+```
+
+For a PyPI installation, use the `models` extra instead: `python -m pip install "graphcore-studio[models]"`.
+
+In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Select **OpenRouter** on a Chat Model node and enter a model ID from the [OpenRouter model catalog](https://openrouter.ai/models). Compose system/user/assistant messages and use **Insert variable** to reference workflow inputs and prior node outputs. Studio loads the local `.env` file automatically; secret values are not included in workflow files. The offline fixture needs no SDK, key, or network call.
+
+## Build a workflow
+
+1. Pick a template or drag a node from the left panel.
+2. Connect the output dots to the next node's input. Conditional nodes have separate true and false outputs.
+3. Select nodes to edit prompts, tools, schemas, and routing rules.
+4. Give the workflow JSON input in the panel under the canvas.
+5. Run it and inspect the output, state, and per-node trace.
+6. Save locally, export the workflow JSON, or approve a saved human checkpoint.
+
+The starter templates cover research and review, structured output, Python tools, a supervisor delegating work to specialist agents, and a chat-model playground. The canvas also supports node search, keyboard undo/redo, zoom, pan, layout changes, validation, and run history.
+
+Prompt templates reference state with `{{input}}`, `{{research}}`, or nested fields such as `{{record.summary}}`. Structured Output defines required fields and types. Python plugins extend the node's registered-tool list without placing executable source code in the workflow document.
+
+## Register a Python library or tool
+
+A plugin is a local, trusted Python module. Studio loads it when the server starts. Import a library in your tool and register an ordinary function:
+
+```python
+def register(add_tool):
+    from my_library import Client
+    client = Client()
+
+    def search(value, config):
+        return {"matches": client.search(str(value))}
+
+    add_tool("search", search, "Search our knowledge base")
+```
+
+Start Studio with `python3 run_studio.py --plugin path/to/plugin.py`, then select the registered function in a Python Tool node. Plugins execute as the current user; load only modules you trust. The included `studio/example_plugin.py` shows a small plugin.
+
+## What runs where?
+
+```text
+Visual editor & local HTTP API
+                │ workflow JSON and node registrations
+        Python integrations ───── OpenRouter SDK / Pydantic / your packages
+                │ Python C ABI
+       C++17 graph scheduler ─── conditions / routes / checkpoints
+                │
+        Local workflow & run files
+```
+
+The C++ runtime owns graph validation at compile time, step scheduling, native equality conditions, and checkpoint transitions. Python supplies model and tool integrations and the local editor server. Model and Python tool code executes in Python; agent handoffs are sequential. Performance benefits depend on the workload. No blanket speedup claim is made.
+
+## Build or embed the C++ core
+
+The editor launcher builds the native shared library automatically. To build the core tests and examples as well:
+
+```bash
+./scripts/build.sh
+```
+
+For CMake users with CMake 3.16 or newer:
+
+```sh
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release
+ctest --test-dir build -C Release --output-on-failure
+```
+
+Compile a C++ example directly with a compiler:
+
+```sh
+c++ -std=c++17 -O2 -Iinclude src/graphcore.cpp examples/approval.cpp -o graphcore_demo
+```
+
+The C++ interface is in `include/graphcore/graphcore.hpp`; the experimental C ABI used by Python is in `include/graphcore/c_api.h`.
+
+## Scope and guarantees
+
+This is an early, working local framework. The UI has runnable templates and a native backend. The runtime currently executes one node at a time. Retries can repeat side effects; use idempotency keys in external systems. File checkpoints support local process-restart recovery but do not promise power-loss durability, multiple writers, encryption, or database transactions. Python async cancellation is cooperative only between callbacks. See the [execution contract](docs/SEMANTICS.md).
+
+Parallel fan-out and joins, database-backed persistence, distributed worker coordination, and an authenticated server remain future work. A release workflow now builds CPython wheels for Linux, macOS, and Windows; those hosted builds still need to run before the wheels are verified for release. The local server uses a session token and origin checks, and binds only to loopback; it is not designed for public network exposure.
+
+## Project notes
+
+- [Architecture and extension points](docs/ARCHITECTURE.md)
+- [Local UI and runtime semantics](docs/SEMANTICS.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Local verification record](docs/VALIDATION.md)
+- [PyPI release checklist](docs/PYPI_RELEASE.md)
+- [Example plugin](studio/example_plugin.py)

graphcore_studio-0.2.0/README.md

@@ -0,0 +1,145 @@
+# GraphCore Studio
+
+**Design local agent workflows on a canvas. Run them with a C++ engine. Extend them with Python.**
+
+GraphCore Studio is an interactive, local-first visual agent framework. Drag nodes onto a canvas, connect agent handoffs, add conditional branches, validate structured output, call Python tools, and pause for human approval. Save and run workflows on your own machine.
+
+## Start Studio
+
+Requirements: Python 3.9+ and a C++17 compiler. You do not need CMake, Node.js, Docker, API keys, an internet connection, or a model to try the included workflows.
+
+From the project folder, run one command:
+
+```bash
+python3 run_studio.py
+```
+
+Open [http://127.0.0.1:8787](http://127.0.0.1:8787). The launcher compiles the C++ shared library on first run, then opens a server accessible only from your machine. On Windows, use PowerShell in a Visual Studio Developer Terminal with the C++ workload installed:
+
+```powershell
+py run_studio.py
+```
+
+If Python was installed through the Windows Store and `py` is unavailable, run `python run_studio.py` from the Visual Studio Developer Terminal.
+
+Stop the server with Ctrl+C. Workflows and run history live in `studio/data/`; drafts are saved in this browser. Run `python3 run_studio.py --help` to configure the port, data directory, or Python tool plugins.
+
+### Install the PyPI package
+
+After the first release is published, install the prebuilt package with:
+
+```bash
+python -m pip install "graphcore-studio[models,pydantic]"
+graphcore-studio
+```
+
+The wheel bundles the C++ runtime and Studio UI. Source installs build the native runtime and therefore require a C++17 compiler and CMake. The distribution is named `graphcore-studio`; its Python API imports as `graphcore`.
+
+### Use Pydantic
+
+The built-in structured-output validator works offline with no extra packages. To enable optional Pydantic v2 validation:
+
+```bash
+python3 -m pip install -r requirements-pydantic.txt
+python3 run_studio.py
+```
+
+On Windows, replace `python3` with `py -3`. Restart Studio after installing packages. The Structured output node shows whether Pydantic is available.
+
+### Use OpenRouter models
+
+The **Chat Model** and **Agent** nodes use GraphCore's model adapter with the official OpenRouter Python SDK. C++ owns graph scheduling, state commits, conditions, and checkpoints; the Python wrapper calls the SDK. The OpenRouter request runs through the project-owned adapter rather than a chain framework.
+
+Install the SDK into the Python environment used to run Studio:
+
+```bash
+python3 -m pip install -r requirements-models.txt
+python3 run_studio.py
+```
+
+For a PyPI installation, use the `models` extra instead: `python -m pip install "graphcore-studio[models]"`.
+
+In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Select **OpenRouter** on a Chat Model node and enter a model ID from the [OpenRouter model catalog](https://openrouter.ai/models). Compose system/user/assistant messages and use **Insert variable** to reference workflow inputs and prior node outputs. Studio loads the local `.env` file automatically; secret values are not included in workflow files. The offline fixture needs no SDK, key, or network call.
+
+## Build a workflow
+
+1. Pick a template or drag a node from the left panel.
+2. Connect the output dots to the next node's input. Conditional nodes have separate true and false outputs.
+3. Select nodes to edit prompts, tools, schemas, and routing rules.
+4. Give the workflow JSON input in the panel under the canvas.
+5. Run it and inspect the output, state, and per-node trace.
+6. Save locally, export the workflow JSON, or approve a saved human checkpoint.
+
+The starter templates cover research and review, structured output, Python tools, a supervisor delegating work to specialist agents, and a chat-model playground. The canvas also supports node search, keyboard undo/redo, zoom, pan, layout changes, validation, and run history.
+
+Prompt templates reference state with `{{input}}`, `{{research}}`, or nested fields such as `{{record.summary}}`. Structured Output defines required fields and types. Python plugins extend the node's registered-tool list without placing executable source code in the workflow document.
+
+## Register a Python library or tool
+
+A plugin is a local, trusted Python module. Studio loads it when the server starts. Import a library in your tool and register an ordinary function:
+
+```python
+def register(add_tool):
+    from my_library import Client
+    client = Client()
+
+    def search(value, config):
+        return {"matches": client.search(str(value))}
+
+    add_tool("search", search, "Search our knowledge base")
+```
+
+Start Studio with `python3 run_studio.py --plugin path/to/plugin.py`, then select the registered function in a Python Tool node. Plugins execute as the current user; load only modules you trust. The included `studio/example_plugin.py` shows a small plugin.
+
+## What runs where?
+
+```text
+Visual editor & local HTTP API
+                │ workflow JSON and node registrations
+        Python integrations ───── OpenRouter SDK / Pydantic / your packages
+                │ Python C ABI
+       C++17 graph scheduler ─── conditions / routes / checkpoints
+                │
+        Local workflow & run files
+```
+
+The C++ runtime owns graph validation at compile time, step scheduling, native equality conditions, and checkpoint transitions. Python supplies model and tool integrations and the local editor server. Model and Python tool code executes in Python; agent handoffs are sequential. Performance benefits depend on the workload. No blanket speedup claim is made.
+
+## Build or embed the C++ core
+
+The editor launcher builds the native shared library automatically. To build the core tests and examples as well:
+
+```bash
+./scripts/build.sh
+```
+
+For CMake users with CMake 3.16 or newer:
+
+```sh
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release
+ctest --test-dir build -C Release --output-on-failure
+```
+
+Compile a C++ example directly with a compiler:
+
+```sh
+c++ -std=c++17 -O2 -Iinclude src/graphcore.cpp examples/approval.cpp -o graphcore_demo
+```
+
+The C++ interface is in `include/graphcore/graphcore.hpp`; the experimental C ABI used by Python is in `include/graphcore/c_api.h`.
+
+## Scope and guarantees
+
+This is an early, working local framework. The UI has runnable templates and a native backend. The runtime currently executes one node at a time. Retries can repeat side effects; use idempotency keys in external systems. File checkpoints support local process-restart recovery but do not promise power-loss durability, multiple writers, encryption, or database transactions. Python async cancellation is cooperative only between callbacks. See the [execution contract](docs/SEMANTICS.md).
+
+Parallel fan-out and joins, database-backed persistence, distributed worker coordination, and an authenticated server remain future work. A release workflow now builds CPython wheels for Linux, macOS, and Windows; those hosted builds still need to run before the wheels are verified for release. The local server uses a session token and origin checks, and binds only to loopback; it is not designed for public network exposure.
+
+## Project notes
+
+- [Architecture and extension points](docs/ARCHITECTURE.md)
+- [Local UI and runtime semantics](docs/SEMANTICS.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Local verification record](docs/VALIDATION.md)
+- [PyPI release checklist](docs/PYPI_RELEASE.md)
+- [Example plugin](studio/example_plugin.py)

graphcore_studio-0.2.0/cmake/GraphCoreConfig.cmake.in

@@ -0,0 +1,2 @@
+@PACKAGE_INIT@
+include("${CMAKE_CURRENT_LIST_DIR}/GraphCoreTargets.cmake")

graphcore_studio-0.2.0/docs/ARCHITECTURE.md

@@ -0,0 +1,52 @@
+# Architecture
+
+```text
+Browser visual canvas (plain HTML/CSS/JS)
+             │ local JSON API with per-launch token
+Python standard-library HTTP server and run manager
+      ├── registered Python / optional Pydantic nodes
+      ├── official OpenRouter Python SDK adapter
+      └── ctypes C ABI bridge
+                  │
+C++17 GraphCore runtime
+      ├── workflow compiler and node routing
+      ├── equality condition node
+      └── crash-recoverable local checkpoint files
+```
+
+## Source map
+
+- `studio/web/`: dependency-free visual editor; editing, drag-to-place, routes, inspector, templates, history and export.
+- `studio/server.py`: loopback-only HTTP API, plugin registration, run workers, workflow/run storage and crash recovery.
+- `studio/engine.py`: workflow validation, Python/Pydantic integrations, OpenRouter SDK adapter and C++ graph compilation.
+- `studio/templates/`: four runnable design examples.
+- `include/graphcore/graphcore.hpp`, `src/graphcore.cpp`: C++ API, sequential scheduler and checkpoint store.
+- `include/graphcore/c_api.h`, `src/c_api.cpp`: C ABI used by the Python runtime.
+- `python/graphcore/`: Python SDK and asyncio callback bridge.
+- `run_studio.py`: one-command native compilation and local startup.
+
+No Node.js, frontend bundler, database, C++ package manager or Python web framework is required. The OpenRouter Python SDK is optional and required only for live model calls; the offline fixture works with the base install. Pydantic remains optional. The canvas is served as local files and does not send workflow data to a remote service.
+
+## Extending nodes
+
+### Python tools
+
+Write a trusted Python module with `register(add_tool)`, then launch using `python3 run_studio.py --plugin path/to/tools.py`. Register a concise name, callable and description. A tool callable receives `(value, config)` and returns a JSON-compatible value. Put credentials and configured library clients in the plugin process environment or its local configuration, never in workflow JSON. Plugin modules are trusted code and run with full user permissions.
+
+### Model adapters
+
+Chat Model and Agent nodes use OpenRouter through the official Python SDK. The `.env` file is loaded at Studio startup and API keys stay out of workflow JSON and execution traces. The graph itself is scheduled by the C++ runtime. Add other providers only after defining their configuration, response/error mapping, limits, cancellation behavior, and tests.
+
+### Structured outputs
+
+Fields currently support flat names and strict primitive/object/array types. The built-in validator works without dependencies. Optional Pydantic mode uses Pydantic v2 models generated from that list. Nested schemas, custom validators, unions and secret fields are future UI features. Python users who need custom object types can validate them inside a registered Python tool.
+
+### Native C++ nodes
+
+Use the C++ builder API for native applications. Native equality-condition nodes can also be constructed through the current C API. The graph designer exposes Python integrations as nodes. A general user-authored native-code plugin system would require a stable ABI, safe compilation strategy, and platform builds; it is not part of this release.
+
+## Performance and scale
+
+C++ removes the scheduler from the Python runtime and makes its transitions native. Python callbacks, model requests, Pydantic and library processing remain Python. For network-bound LLM flows, remote model time will often dominate. Measure complete representative workflows before drawing a speed conclusion.
+
+The UI caps a workflow at 100 nodes and four simultaneous runs. The native runtime executes each graph sequentially and stores state in local files. It is not yet a distributed service, a sandbox, or a database-backed workflow platform.

graphcore_studio-0.2.0/docs/PYPI_RELEASE.md

@@ -0,0 +1,37 @@
+# PyPI release checklist
+
+The distribution name is `graphcore-studio`; the Python import is `graphcore`. The shorter PyPI name `graphcore` is already registered by another project. Recheck `graphcore-studio` availability at upload time. Keep the version synchronized in `pyproject.toml`, `CMakeLists.txt`, and `python/graphcore/__init__.py`.
+
+## Build and validate locally
+
+Use Python 3.9 or newer, a C++17 compiler, and a working network connection for isolated build dependencies:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build --sdist --wheel
+python -m twine check dist/graphcore_studio-*.whl dist/graphcore_studio-*.tar.gz
+```
+
+The source archive builds a native library at install time. Wheels contain the C++ shared library and Studio assets. `.github/workflows/wheels.yml` builds and tests CPython 3.9–3.13 wheels for Linux x86-64/ARM64, Windows x86-64, and macOS x86-64/ARM64. Run it manually from GitHub Actions or push a `v*` tag. The `graphcore-studio-distributions` artifact contains the combined wheels and source archive after Twine validation. Download those exact files for TestPyPI and release.
+
+Never upload old `*-source.zip` files from `dist/`. Upload only the `.whl` and `.tar.gz` artifacts emitted by the build command. Inspect the archives before release: `studio/data/` is intentionally excluded because it may contain local workflows, run history, and secrets.
+
+## TestPyPI first
+
+Download the `graphcore-studio-distributions` artifact from a successful workflow run, create a TestPyPI project and API token, then upload the exact validated artifacts:
+
+```bash
+python -m twine upload --repository testpypi dist/*.whl dist/*.tar.gz
+```
+
+Install and test from a clean environment against TestPyPI before publishing to PyPI. Avoid pasting API tokens into the repository or chat; configure them through Twine's secure prompt or a protected environment variable.
+
+## Publish
+
+Confirm the package name is still available, the GitHub repository and release tag are correct, and the final artifacts have passed CI. Then publish those same tested artifacts:
+
+```bash
+python -m twine upload dist/*.whl dist/*.tar.gz
+```
+
+PyPI does not allow replacing files for an existing version. Increment the version in both metadata files for every subsequent release.

graphcore_studio-0.2.0/docs/ROADMAP.md

@@ -0,0 +1,24 @@
+# Roadmap
+
+## Shipped in this local Studio prototype
+
+- Drag-and-drop canvas with reusable JSON templates, condition routes and agent handoff flows.
+- Supervisor-to-specialist example, Python tools, output inspection, execution trace and run history.
+- Structured output with a dependency-free validator and optional Pydantic v2 integration.
+- OpenRouter SDK adapter, human approval checkpoints, workflow export/import and local save.
+- C++17 sequential scheduler and file checkpoints behind a C ABI, launched with one command.
+- Loopback-only server, run input limits, per-launch write token and origin validation.
+
+## Remaining work before production
+
+1. Persisted parallel supersteps, explicit fan-out/join groups, stable reducers, and durable task results.
+2. SQLite/PostgreSQL transaction backends, checkpoint fsync policy, integrity checks, schema migration and retention.
+3. Streaming provider responses, classified retries, idempotent effect journal, and Python cancellation/deadline propagation.
+4. Nested JSON Schema/Pydantic models, user-defined validators, typed output ports, and richer state/secret handling.
+5. Run the multi-platform wheel release workflow and verify Linux, macOS, and Windows artifacts before publishing.
+6. Trace redaction/export, automated frontend accessibility and visual regression checks, and a full developer guide.
+7. Authentication and worker leases only if a remote/team deployment becomes a goal; current Studio remains a local single-user tool.
+
+## Release gates
+
+Pass the compiler-only build and CTest on Linux, macOS and Windows. Test Pydantic-enabled and dependency-free environments, real restart/interrupt recovery, OpenRouter request limits and JSON responses, malformed workflow import, cross-origin write rejection and cancellation behavior. Benchmark native scheduler time separately from Python/model calls. Do not publish an overall speedup figure without comparable workloads and measured data.