graphcore-studio 0.2.0__py3-none-win_amd64.whl

graphcore/__init__.py

@@ -0,0 +1,303 @@
+"""Dependency-free Python SDK for the GraphCore native runtime.
+
+Build the shared library first and set GRAPHCORE_LIBRARY if it is outside build/.
+State values are JSON encoded individually; Python objects stay out of checkpoints.
+"""
+import asyncio
+import ctypes as C
+import inspect
+import json
+import os
+from pathlib import Path
+import sys
+import threading
+import traceback
+from dataclasses import dataclass, field
+from typing import Optional
+
+END = "__end__"
+__version__ = "0.2.0"
+
+class GraphCoreError(RuntimeError):
+    pass
+
+@dataclass
+class Context:
+    resumed: bool = False
+    response: object = None
+
+@dataclass
+class Update:
+    values: dict = field(default_factory=dict)
+    next: Optional[str] = None
+
+@dataclass
+class Interrupt:
+    prompt: str
+
+@dataclass
+class Result:
+    state: dict
+    suspended: bool
+    prompt: str
+    steps: int
+
+_EVENT = C.CFUNCTYPE(None, C.c_char_p, C.c_char_p, C.c_void_p)
+_CALLBACK = C.CFUNCTYPE(C.c_int, C.c_char_p, C.c_int, C.c_char_p, C.c_void_p, C.c_void_p)
+
+def _text(value):
+    if not isinstance(value, str) or "\0" in value:
+        raise ValueError("Expected a string without NUL characters")
+    return value.encode("utf-8")
+
+def _dump(value):
+    return json.dumps(value, ensure_ascii=True, allow_nan=False, sort_keys=True)
+
+def _encode(state):
+    return "".join(_text(k).hex() + ":" + _dump(v).encode().hex() + "\n"
+                   for k, v in state.items()).encode()
+
+def _decode(wire):
+    result = {}
+    for line in wire.decode().splitlines():
+        key, value = line.split(":", 1)
+        result[bytes.fromhex(key).decode()] = json.loads(bytes.fromhex(value).decode())
+    return result
+
+def _load():
+    suffix = ".dll" if sys.platform == "win32" else ".dylib" if sys.platform == "darwin" else ".so"
+    name = ("" if sys.platform == "win32" else "lib") + "graphcore" + suffix
+    root = Path(__file__).resolve().parents[2]
+    candidates = [Path(os.environ["GRAPHCORE_LIBRARY"])] if "GRAPHCORE_LIBRARY" in os.environ else [
+        Path(__file__).parent / name, root / "build" / name, root / "build" / "Release" / name]
+    path = next((p for p in candidates if p.is_file()), None)
+    if path is None:
+        raise GraphCoreError("Native library missing. Build it first; see README or set GRAPHCORE_LIBRARY.")
+    lib = C.CDLL(str(path))
+    definitions = {
+        "gc_cancel": ([C.c_void_p], None),
+        "gc_set_observer": ([C.c_void_p, _EVENT, C.c_void_p], C.c_int),
+        "gc_add_condition": ([C.c_void_p, C.c_char_p, C.c_char_p, C.c_char_p, C.c_char_p, C.c_char_p], C.c_int),
+        "gc_create": ([C.c_char_p], C.c_void_p),
+        "gc_destroy": ([C.c_void_p], None),
+        "gc_error": ([C.c_void_p], C.c_char_p),
+        "gc_add_node": ([C.c_void_p, C.c_char_p, _CALLBACK, C.c_void_p, C.c_uint], C.c_int),
+        "gc_add_edge": ([C.c_void_p, C.c_char_p, C.c_char_p], C.c_int),
+        "gc_set_entry": ([C.c_void_p, C.c_char_p], C.c_int),
+        "gc_run": ([C.c_void_p, C.c_char_p, C.c_char_p, C.c_int, C.c_char_p, C.c_size_t], C.c_int),
+        "gc_inspect_checkpoint": ([C.c_void_p, C.c_char_p], C.c_int),
+        "gc_result": ([C.c_void_p], C.c_char_p),
+        "gc_prompt": ([C.c_void_p], C.c_char_p),
+        "gc_suspended": ([C.c_void_p], C.c_int),
+        "gc_steps": ([C.c_void_p], C.c_size_t),
+        "gc_reply_update": ([C.c_void_p, C.c_char_p, C.c_char_p], C.c_int),
+        "gc_reply_next": ([C.c_void_p, C.c_char_p], C.c_int),
+        "gc_reply_suspend": ([C.c_void_p, C.c_char_p], C.c_int),
+        "gc_reply_error": ([C.c_void_p, C.c_char_p], C.c_int),
+    }
+    for name, (args, result) in definitions.items():
+        fn = getattr(lib, name)
+        fn.argtypes, fn.restype = args, result
+    return lib
+
+class Graph:
+    """Sequential durable graph. Use a separate Graph instance for concurrent runs.
+
+    Python callbacks return a dict, Update, or Interrupt. Async callbacks require
+    ainvoke/aresume. Explicitly close the graph or use it as a context manager.
+    """
+    def __init__(self, version="1"):
+        self._lib = _load()
+        self._handle = self._lib.gc_create(_text(version))
+        if not self._handle:
+            raise GraphCoreError("Cannot create graph")
+        self._callbacks = []
+        self._lock = threading.Lock()
+        self._loop = None
+        self._has_async = False
+        self._observer = None
+        self._lifecycle = threading.Lock()
+
+    def _check(self, code):
+        if code:
+            raise GraphCoreError(self._lib.gc_error(self._handle).decode())
+
+    def _enter(self):
+        if not self._lock.acquire(blocking=False):
+            raise GraphCoreError("Graph is in use; concurrent calls are unsupported")
+        if not self._handle:
+            self._lock.release()
+            raise GraphCoreError("Graph is closed")
+
+    def add_condition(self, name, field, expected, yes, no):
+        """Compare canonical JSON values and select a route entirely in C++."""
+        self._enter()
+        try:
+            self._check(self._lib.gc_add_condition(self._handle, _text(name), _text(field),
+                        _text(_dump(expected)), _text(yes), _text(no)))
+        finally:
+            self._lock.release()
+        return self
+
+    def observe(self, callback):
+        def emit(kind, node, user):
+            try:
+                callback(kind.decode(), node.decode())
+            except Exception:
+                pass
+        self._enter()
+        try:
+            observer = _EVENT(emit)
+            self._check(self._lib.gc_set_observer(self._handle, observer, None))
+            self._observer = observer
+        finally:
+            self._lock.release()
+        return self
+
+    def cancel(self):
+        """Cooperatively cancel; use a new Graph after cancellation."""
+        with self._lifecycle:
+            if self._handle:
+                self._lib.gc_cancel(self._handle)
+
+    def add_node(self, name, function, retries=0):
+        if not callable(function):
+            raise TypeError("Node must be callable")
+        if not isinstance(retries, int) or not 0 <= retries <= 1000:
+            raise ValueError("retries must be between 0 and 1000")
+        is_async = inspect.iscoroutinefunction(function)
+        def call(wire, resumed, response, reply, user):
+            try:
+                context = Context(bool(resumed), json.loads(response) if resumed else None)
+                result = function(_decode(wire), context)
+                if inspect.isawaitable(result):
+                    if self._loop is None:
+                        if inspect.iscoroutine(result):
+                            result.close()
+                        raise GraphCoreError("Async callbacks require ainvoke/aresume")
+                    async def await_result():
+                        return await result
+                    result = asyncio.run_coroutine_threadsafe(await_result(), self._loop).result()
+                if isinstance(result, Interrupt):
+                    if self._lib.gc_reply_suspend(reply, _text(result.prompt)):
+                        raise GraphCoreError("Cannot construct interrupt")
+                else:
+                    update = result if isinstance(result, Update) else Update(result)
+                    if not isinstance(update.values, dict):
+                        raise TypeError("Node must return dict, Update, or Interrupt")
+                    for key, value in update.values.items():
+                        if self._lib.gc_reply_update(reply, _text(key), _text(_dump(value))):
+                            raise GraphCoreError("Cannot construct update")
+                    if update.next is not None and self._lib.gc_reply_next(reply, _text(update.next)):
+                        raise GraphCoreError("Cannot construct route")
+                return 0
+            except BaseException:
+                self._lib.gc_reply_error(reply, traceback.format_exc().replace("\0", "\\0").encode())
+                return -1
+        callback = _CALLBACK(call)
+        self._enter()
+        try:
+            self._check(self._lib.gc_add_node(self._handle, _text(name), callback, None, retries))
+            self._callbacks.append(callback)
+            self._has_async |= is_async
+        finally:
+            self._lock.release()
+        return self
+
+    def add_edge(self, source, target):
+        self._enter()
+        try:
+            self._check(self._lib.gc_add_edge(self._handle, _text(source), _text(target)))
+        finally:
+            self._lock.release()
+        return self
+
+    def set_entry(self, name):
+        self._enter()
+        try:
+            self._check(self._lib.gc_set_entry(self._handle, _text(name)))
+        finally:
+            self._lock.release()
+        return self
+
+    def _run(self, state, checkpoint, resume, response, max_steps):
+        if not isinstance(max_steps, int) or max_steps < 1:
+            raise ValueError("max_steps must be positive")
+        path = _text(os.fspath(checkpoint)) if checkpoint is not None else None
+        reply = _text(_dump(response)) if response is not _MISSING else None
+        self._check(self._lib.gc_run(self._handle, _encode(state), path, resume, reply, max_steps))
+        return Result(_decode(self._lib.gc_result(self._handle)),
+                      bool(self._lib.gc_suspended(self._handle)),
+                      self._lib.gc_prompt(self._handle).decode(), self._lib.gc_steps(self._handle))
+
+    def inspect_checkpoint(self, checkpoint):
+        """Read saved state without executing callbacks or advancing the graph."""
+        self._enter()
+        try:
+            self._check(self._lib.gc_inspect_checkpoint(self._handle, _text(os.fspath(checkpoint))))
+            return Result(_decode(self._lib.gc_result(self._handle)),
+                          bool(self._lib.gc_suspended(self._handle)),
+                          self._lib.gc_prompt(self._handle).decode(), self._lib.gc_steps(self._handle))
+        finally:
+            self._lock.release()
+
+    def invoke(self, state=None, *, checkpoint=None, max_steps=100):
+        return self._sync(state or {}, checkpoint, False, _MISSING, max_steps)
+
+    def resume(self, checkpoint, *, response=None, max_steps=100):
+        return self._sync({}, checkpoint, True, response, max_steps)
+
+    def recover(self, checkpoint, *, max_steps=100):
+        return self._sync({}, checkpoint, True, _MISSING, max_steps)
+
+    def _sync(self, *args):
+        if self._has_async:
+            raise GraphCoreError("Async callbacks require ainvoke/aresume")
+        self._enter()
+        try:
+            return self._run(*args)
+        finally:
+            self._lock.release()
+
+    async def ainvoke(self, state=None, *, checkpoint=None, max_steps=100):
+        return await self._async(state or {}, checkpoint, False, _MISSING, max_steps)
+
+    async def aresume(self, checkpoint, *, response=None, max_steps=100):
+        return await self._async({}, checkpoint, True, response, max_steps)
+
+    async def arecover(self, checkpoint, *, max_steps=100):
+        return await self._async({}, checkpoint, True, _MISSING, max_steps)
+
+    async def _async(self, *args):
+        self._enter()
+        self._loop = asyncio.get_running_loop()
+        future = self._loop.run_in_executor(None, self._run, *args)
+        # Native execution cannot be safely abandoned. Keep references and loop
+        # association until it finishes, even if the awaiting caller cancels.
+        def finish(_):
+            self._loop = None
+            self._lock.release()
+            if not future.cancelled():
+                future.exception()  # Retrieve errors if the caller was cancelled.
+        future.add_done_callback(finish)
+        return await asyncio.shield(future)
+
+    def close(self):
+        if not self._handle:
+            return
+        self._enter()
+        try:
+            with self._lifecycle:
+                self._lib.gc_destroy(self._handle)
+                self._handle = None
+            self._callbacks.clear()
+        finally:
+            self._lock.release()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+_MISSING = object()

graphcore_studio-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,28 @@
+graphcore/__init__.py,sha256=7A3dUzs_gxgRho0k98uGT8OgdAAX8EYT5FU2UqdBneg,12408
+graphcore/graphcore.dll,sha256=g07jMRtss_Wm6CkfnSKiAyJcxRF7Jab-2e8EI8YwJRs,111104
+include/graphcore/c_api.h,sha256=H7IA88yP-Q9tazxr6Tx0QobFd-RqvuljzJQa9XNkIC0,2459
+include/graphcore/graphcore.hpp,sha256=-pH7yfUTiGw6JmxJ-vkUgFLEnvE3jdKuDLWkLTCu3iA,3103
+lib/cmake/GraphCore/GraphCoreConfig.cmake,sha256=jkFXP-6HfSoHZIpSGlRAZlNj-YOZodRj1KQ5HZ6lhRk,968
+lib/cmake/GraphCore/GraphCoreConfigVersion.cmake,sha256=lj3aqD85__gyE1RZL3MnzO7Q4qpa-d-QG0LEXVbnKT8,2827
+lib/cmake/GraphCore/GraphCoreTargets-release.cmake,sha256=31TYO8LSi6XmD7zN-dLOR9kK7Z934q5VGhhEOuGBmkA,896
+lib/cmake/GraphCore/GraphCoreTargets.cmake,sha256=czj1gBdRN4ZU_mEuJbK2GL4jPgF7W9TkBgae5fAfnyE,4291
+lib/graphcore.lib,sha256=sCtmI17LladE9z4aAV5tglsQkTlMXahW0Gf4czYLNQQ,1250444
+lib/graphcore_c.lib,sha256=_HuQeiOH9u0DvB9VBpSRzqcMg7DZlo8LNjqgEwV8FTg,5100
+studio/__init__.py,sha256=Cn0hUv9J3GXbu86e3qjzm5DFb2M8cOMRk_NX3oq2Ero,79
+studio/cli.py,sha256=Xjdg0DNRMK_falfV63WZZzp5bPVZOsvJ0hPYZy8y5ro,268
+studio/engine.py,sha256=_-XZaRlxjzfJRBXkzR2De3cttHLnB4Mvt1zyaqEVMfk,20118
+studio/example_plugin.py,sha256=WtIwtZOkFapr99IKGet_5igN8VxdMVuxsO_d1NEsl6I,495
+studio/server.py,sha256=lV7PbJJV3Lk-CIrcRlaVkFHHpVhLNpiUFlLzN9B5rbU,19834
+studio/templates/01-research.json,sha256=IG3U8oCKj-rb96LEcCIPS77YRL1GFNja8IFofpRpoj0,2860
+studio/templates/02-structured.json,sha256=jrX9r_rJoq_Exl9wBH_kyIfgfdJraHgPzJH8CIo2in4,2020
+studio/templates/03-tools.json,sha256=Yh80vAmODCSZ9-JQX_8r_nmW8rSws1MG5U9ABcd5lbs,1494
+studio/templates/04-team.json,sha256=mRoyXCA6ow3ZXFjhhkfQ3-b4K11lTgFkEsJsbbqGr9Y,2857
+studio/templates/05-model.json,sha256=-BQq4fr2V62B1uVhZqrFX8CNbwAgJZNqlmcquaY95mk,1140
+studio/web/app.js,sha256=2RlRUrSqW2o-xQ1TWbQ7QsiaEzO1Mtdq_u9dMpLMWkg,46513
+studio/web/index.html,sha256=Ls0ePIekgN91D7fXbgEffQH1Dpn3t9qtyuLCeg1476w,5376
+studio/web/style.css,sha256=RfxMCpe0LzNkR7AjSjO67P66mpo4Ln5gQlJvrBBfTmY,22282
+graphcore_studio-0.2.0.dist-info/METADATA,sha256=66QnViLSScawTjd7JF3SBNGU-zQOD-mBqojN0lf13yk,8617
+graphcore_studio-0.2.0.dist-info/WHEEL,sha256=QOQSSLDAidk39OMVpTfE4kjgcxpaKg4ohhjJQ7vAJpA,102
+graphcore_studio-0.2.0.dist-info/entry_points.txt,sha256=ICHwg3dwPHf5dLOh88EOwvkWol7nGIHK6NWo6pmrnUU,54
+graphcore_studio-0.2.0.dist-info/licenses/LICENSE,sha256=skdWxhD4isyrtl6JSxMWrkxVXlFV0Y5bIHulD9fHQUo,1100
+graphcore_studio-0.2.0.dist-info/RECORD,,

graphcore_studio-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 1.1.0
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

graphcore_studio-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+graphcore-studio = studio.cli:main
+

graphcore_studio-0.2.0.dist-info/licenses/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.

include/graphcore/c_api.h

@@ -0,0 +1,51 @@
+#ifndef GRAPHCORE_C_API_H
+#define GRAPHCORE_C_API_H
+#include <stddef.h>
+#if defined(_WIN32)
+# if defined(GRAPHCORE_BUILD_SHARED)
+#  define GC_API __declspec(dllexport)
+# else
+#  define GC_API __declspec(dllimport)
+# endif
+#else
+# define GC_API __attribute__((visibility("default")))
+#endif
+#ifdef __cplusplus
+extern "C" {
+#endif
+/* One handle per graph/run; handles must not be used concurrently.
+   Strings are UTF-8, NUL terminated. Returned strings live until the next call.
+   Callback state is hex wire format; callback and user data must outlive handle. */
+typedef struct gc_handle gc_handle;
+typedef int (*gc_callback)(const char* state, int resumed, const char* response,
+                           void* reply, void* user_data);
+typedef void (*gc_event_callback)(const char* type, const char* node, void* user_data);
+/* Set observer before running; cancel is the only method safe during gc_run. */
+GC_API int gc_set_observer(gc_handle*, gc_event_callback, void* user_data);
+GC_API void gc_cancel(gc_handle*);
+/* Native equality branch; values use the caller's state encoding. */
+GC_API int gc_add_condition(gc_handle*, const char* name, const char* key,
+                            const char* expected, const char* yes, const char* no);
+GC_API gc_handle* gc_create(const char* version);
+GC_API void gc_destroy(gc_handle*);
+GC_API const char* gc_error(gc_handle*);
+GC_API int gc_add_node(gc_handle*, const char* name, gc_callback, void* user_data, unsigned retries);
+GC_API int gc_add_edge(gc_handle*, const char* source, const char* target);
+GC_API int gc_set_entry(gc_handle*, const char* name);
+/* checkpoint=NULL disables persistence; response=NULL means no resume response. */
+GC_API int gc_run(gc_handle*, const char* initial_wire, const char* checkpoint,
+                  int resume, const char* response, size_t max_steps);
+GC_API int gc_inspect_checkpoint(gc_handle*, const char* path);
+GC_API const char* gc_result(gc_handle*);
+GC_API const char* gc_prompt(gc_handle*);
+GC_API int gc_suspended(gc_handle*);
+GC_API size_t gc_steps(gc_handle*);
+/* Reply helpers return -1 on failure; callback must propagate failure. */
+GC_API int gc_reply_update(void*, const char* key, const char* value);
+GC_API int gc_reply_next(void*, const char* target);
+GC_API int gc_reply_suspend(void*, const char* prompt);
+GC_API int gc_reply_error(void*, const char* message);
+#ifdef __cplusplus
+}
+#endif
+#endif

include/graphcore/graphcore.hpp

@@ -0,0 +1,83 @@
+#pragma once
+#include <atomic>
+#include <filesystem>
+#include <functional>
+#include <map>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <vector>
+#include <utility>
+
+namespace graphcore {
+using State = std::map<std::string, std::string>;
+inline constexpr const char* END = "__end__";
+struct Error : std::runtime_error { using std::runtime_error::runtime_error; };
+struct NodeResult {
+    State updates;
+    std::optional<std::string> next;
+    bool suspend = false;
+    std::string prompt;
+    NodeResult(State changes = {}, std::optional<std::string> target = {},
+               bool paused = false, std::string question = {})
+        : updates(std::move(changes)), next(std::move(target)), suspend(paused),
+          prompt(std::move(question)) {}
+};
+struct Context { bool resumed = false; std::string response; };
+using Node = std::function<NodeResult(const State&, const Context&)>;
+struct NodeOptions { unsigned retries = 0; }; // Only opt in for safe/idempotent nodes.
+struct Snapshot {
+    std::string graph_version, next;
+    State state;
+    std::size_t steps = 0;
+    bool suspended = false;
+    std::string prompt;
+};
+class CheckpointStore {
+public:
+    virtual ~CheckpointStore() = default;
+    virtual void save(const Snapshot&) = 0;
+    virtual Snapshot load() = 0;
+};
+class FileCheckpoint final : public CheckpointStore {
+    std::filesystem::path path_;
+public:
+    explicit FileCheckpoint(std::filesystem::path path) : path_(std::move(path)) {}
+    void save(const Snapshot&) override;
+    Snapshot load() override;
+};
+class Graph {
+public:
+    struct Entry { Node fn; NodeOptions options; std::vector<std::string> targets; };
+    std::map<std::string, Entry> nodes;
+    std::string entry, version;
+};
+class GraphBuilder {
+    Graph graph_;
+public:
+    explicit GraphBuilder(std::string version);
+    GraphBuilder& add_node(std::string name, Node node, NodeOptions options = {});
+    // All dynamic routes must be declared; the first is the default route.
+    GraphBuilder& edges(const std::string& source, std::vector<std::string> targets);
+    GraphBuilder& entry(std::string name);
+    Graph compile() const;
+};
+struct RunOptions {
+    std::size_t max_steps = 100;
+    const std::atomic<bool>* cancelled = nullptr;
+    // Observer exceptions are isolated from execution.
+    std::function<void(const std::string&, const std::string&)> on_event;
+};
+class Runtime {
+    Snapshot execute(const Graph&, Snapshot, CheckpointStore*, const RunOptions&, Context);
+public:
+    Snapshot invoke(const Graph&, State initial = {}, CheckpointStore* store = nullptr,
+                    const RunOptions& options = {});
+    // A response is required only when the saved snapshot is suspended.
+    Snapshot resume(const Graph&, CheckpointStore&, std::optional<std::string> response = {},
+                    const RunOptions& options = {});
+};
+// Portable text wire format shared by the C ABI and Python wrapper.
+std::string encode_state(const State&);
+State decode_state(const std::string&);
+}