holokai-neuron-sdk 0.1.0__tar.gz

holokai_neuron_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/

holokai_neuron_sdk-0.1.0/LICENSE

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

holokai_neuron_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: holokai-neuron-sdk
+Version: 0.1.0
+Summary: SDK for building Holokai neurons in Python — connect to a BigBrain gateway over HTTP+SSE and execute capability-typed tasks.
+Project-URL: Homepage, https://github.com/holok-ai/bigbrain/tree/main/packages/neuron-sdk-python#readme
+Project-URL: Repository, https://github.com/holok-ai/bigbrain
+Project-URL: Issues, https://github.com/holok-ai/bigbrain/issues
+Author: Holokai
+License: MIT
+License-File: LICENSE
+Keywords: agent,bigbrain,holokai,neuron,sdk,sse,workflow
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.21
+Requires-Dist: pydantic<3,>=2.6
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.9; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# holokai-neuron-sdk
+
+SDK for building **Holokai neurons** in Python — connect to a BigBrain
+gateway over HTTP+SSE and execute capability-typed tasks.
+
+This is the Python sibling of [`@holokai/neuron-sdk`][ts-sdk] (TypeScript)
+and speaks the same wire protocol byte-for-byte
+(`packages/neuron-protocol`).
+
+[ts-sdk]: ../neuron-sdk
+
+## Install
+
+```bash
+pip install holokai-neuron-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import asyncio
+import logging
+
+from holokai_neuron_sdk import Capability, HandlerContext, Neuron
+
+
+async def echo(input, ctx: HandlerContext):
+    await ctx.progress(percent=50, message="halfway")
+    return {"echo": input}
+
+
+async def main():
+    neuron = Neuron(
+        gateway_url="https://api.holokai.dev",
+        neuron_id="my-neuron-1",
+        auth=lambda: "<bearer token>",  # sync or async; called per request
+        logger=logging.getLogger("neuron"),
+    )
+
+    neuron.register_handler(
+        Capability(type="example/echo", scope="any", concurrency=4),
+        echo,
+        input_schema={"type": "object"},
+        output_schema={
+            "type": "object",
+            "properties": {"echo": {}},
+            "required": ["echo"],
+        },
+    )
+
+    await neuron.start()
+    try:
+        await asyncio.Event().wait()  # run until cancelled
+    finally:
+        await neuron.stop(drain=True, timeout=30)
+
+
+asyncio.run(main())
+```
+
+## Concepts
+
+| Concept | What it is |
+| ------- | ---------- |
+| **Neuron** | A process that registers itself with a BigBrain gateway and offers one or more capabilities. |
+| **Capability** | A namespaced task type (`owner/package[/name][.variant]`) with a scope (`"any"` or `{onBehalfOf: userId}`) and a per-capability concurrency. |
+| **Lease** | A single in-flight task delivery. Carries the input, schemas, and a deadline. The neuron acks (success), nacks (failure), or progresses. |
+| **Cancel** | The gateway can revoke a lease mid-flight. The handler's cancellation `asyncio.Event` is set, the task is cancelled, and a `cancelled` nack is sent. |
+| **Heartbeat** | The SDK posts a heartbeat every 10s with the current in-flight lease list. The gateway uses it to detect dead neurons and to renew lease TTLs for long-running tasks. |
+
+## Wire protocol
+
+* **Transport**: SSE (server → neuron) + HTTPS POST (neuron → server).
+* **Endpoints**:
+  * `GET /neuron/events?neuronId=…` — SSE stream
+  * `POST /neuron/{register, update-capability, heartbeat, ack, nack, progress}`
+* **Authentication**: `Authorization: Bearer <jwt>`. The `auth` callback is
+  invoked on every POST and SSE open, and is given one chance to refresh on
+  401 before the SDK escalates to reconnect-with-backoff.
+* **Schemas**: input/output JSON Schema arrives on the lease frame; the SDK
+  validates with `jsonschema` and emits a `schema-mismatch` nack on failure.
+* **Versioning**: `PROTOCOL_VERSION = "1.0.0"` (free-form on the wire; the
+  gateway negotiates compatibility).
+
+## Handler contract
+
+```python
+async def handler(input, ctx: HandlerContext):
+    # ctx.task         — the full task payload
+    # ctx.lease_id     — the lease the gateway holds for this delivery
+    # ctx.cancelled    — asyncio.Event set on cancel / shutdown
+    # ctx.log          — logger scoped to this lease
+    # ctx.progress(...) — non-blocking progress update
+    # ctx.fail(reason, code=...) — terminal nack (do not catch)
+    return {...}
+```
+
+* **Sync handlers** are supported; the runner awaits awaitable return values
+  and otherwise treats the return as the result.
+* **Cancellation**: handlers wrapping I/O should cooperate with
+  `ctx.cancelled` (e.g. `asyncio.wait` with `[ctx.cancelled.wait(), …]`).
+* **Idempotency** is the handler author's responsibility — the framework
+  does not checkpoint mid-task.
+
+## Failure classification
+
+| Outcome                              | Wire kind          |
+|--------------------------------------|--------------------|
+| Handler returns                      | `ack`              |
+| Handler raises `asyncio.CancelledError` (or cancel event set) | `nack: cancelled` |
+| `ctx.fail(...)`                      | `nack: terminal`   |
+| Handler raises any other exception   | `nack: retryable`  |
+| Input/output fails JSON Schema       | `nack: schema-mismatch` |
+
+Retry policy lives on the workflow (server-side), never on the SDK.
+
+## Architecture
+
+```
+┌────────────┐   POST register / heartbeat / ack / nack / progress
+│   Neuron   │──────────────────────────────────────────────────────▶│
+│  (this    │                                                       │ BigBrain
+│   SDK)    │◀──────────────────────────── SSE: lease / cancel ────│ gateway
+└────────────┘
+```
+
+* `HttpTransport` owns one SSE stream and a shared `httpx.AsyncClient`.
+* `Neuron` wires the transport to a heartbeat loop and a per-capability
+  semaphore-bounded dispatcher.
+* `run_lease(...)` validates input, invokes the handler, validates output,
+  and posts the right ack/nack frame.
+
+## Examples
+
+| Example | Capability | What it does |
+| ------- | ---------- | ------------ |
+| [`examples/http_fetch/`](examples/http_fetch/) | `examples/http.fetch` | Fetches an arbitrary HTTP(S) URL via `httpx` and returns status/headers/body. |
+| [`examples/web_search/`](examples/web_search/) | `examples/web.search` | Keyless web search via DuckDuckGo HTML scrape. No API key, but inherently brittle — see the example README for caveats. |
+
+Each ships with input/output JSON Schemas, cooperative cancellation
+(`ctx.cancelled`), and a CLI runner. Run them the same way:
+
+```bash
+pip install -e .
+BIGBRAIN_GATEWAY_URL=https://api.holokai.dev \
+BIGBRAIN_NEURON_ID=my-python-neuron-1 \
+BIGBRAIN_TOKEN=eyJ... \
+python -m examples.http_fetch    # or examples.web_search
+```
+
+## Custom transports
+
+`HttpTransport` is the default but the public `Transport` shape is documented
+on `TransportCallbacks` and `Neuron(transport=…)` accepts any object that
+matches the protocol — handy for tests or in-process embeddings.
+
+## Tests
+
+```bash
+# Unit + deterministic e2e (default — no network).
+pytest
+
+# Network-gated e2e: hits real DuckDuckGo through the real SDK to catch
+# scraper drift. Skipped unless explicitly enabled.
+E2E_NETWORK=1 pytest -m e2e_network
+```
+
+The e2e tests stand up a tiny aiohttp server on loopback that serves both
+the BigBrain `/neuron/*` surface and a stub for DuckDuckGo, then run the
+real `Neuron` SDK against it. Every byte flows over real HTTP — SSE in,
+POSTs out — exercising the full `register → lease → handler → ack` loop.
+See [`tests/e2e/`](tests/e2e/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

holokai_neuron_sdk-0.1.0/README.md

@@ -0,0 +1,178 @@
+# holokai-neuron-sdk
+
+SDK for building **Holokai neurons** in Python — connect to a BigBrain
+gateway over HTTP+SSE and execute capability-typed tasks.
+
+This is the Python sibling of [`@holokai/neuron-sdk`][ts-sdk] (TypeScript)
+and speaks the same wire protocol byte-for-byte
+(`packages/neuron-protocol`).
+
+[ts-sdk]: ../neuron-sdk
+
+## Install
+
+```bash
+pip install holokai-neuron-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import asyncio
+import logging
+
+from holokai_neuron_sdk import Capability, HandlerContext, Neuron
+
+
+async def echo(input, ctx: HandlerContext):
+    await ctx.progress(percent=50, message="halfway")
+    return {"echo": input}
+
+
+async def main():
+    neuron = Neuron(
+        gateway_url="https://api.holokai.dev",
+        neuron_id="my-neuron-1",
+        auth=lambda: "<bearer token>",  # sync or async; called per request
+        logger=logging.getLogger("neuron"),
+    )
+
+    neuron.register_handler(
+        Capability(type="example/echo", scope="any", concurrency=4),
+        echo,
+        input_schema={"type": "object"},
+        output_schema={
+            "type": "object",
+            "properties": {"echo": {}},
+            "required": ["echo"],
+        },
+    )
+
+    await neuron.start()
+    try:
+        await asyncio.Event().wait()  # run until cancelled
+    finally:
+        await neuron.stop(drain=True, timeout=30)
+
+
+asyncio.run(main())
+```
+
+## Concepts
+
+| Concept | What it is |
+| ------- | ---------- |
+| **Neuron** | A process that registers itself with a BigBrain gateway and offers one or more capabilities. |
+| **Capability** | A namespaced task type (`owner/package[/name][.variant]`) with a scope (`"any"` or `{onBehalfOf: userId}`) and a per-capability concurrency. |
+| **Lease** | A single in-flight task delivery. Carries the input, schemas, and a deadline. The neuron acks (success), nacks (failure), or progresses. |
+| **Cancel** | The gateway can revoke a lease mid-flight. The handler's cancellation `asyncio.Event` is set, the task is cancelled, and a `cancelled` nack is sent. |
+| **Heartbeat** | The SDK posts a heartbeat every 10s with the current in-flight lease list. The gateway uses it to detect dead neurons and to renew lease TTLs for long-running tasks. |
+
+## Wire protocol
+
+* **Transport**: SSE (server → neuron) + HTTPS POST (neuron → server).
+* **Endpoints**:
+  * `GET /neuron/events?neuronId=…` — SSE stream
+  * `POST /neuron/{register, update-capability, heartbeat, ack, nack, progress}`
+* **Authentication**: `Authorization: Bearer <jwt>`. The `auth` callback is
+  invoked on every POST and SSE open, and is given one chance to refresh on
+  401 before the SDK escalates to reconnect-with-backoff.
+* **Schemas**: input/output JSON Schema arrives on the lease frame; the SDK
+  validates with `jsonschema` and emits a `schema-mismatch` nack on failure.
+* **Versioning**: `PROTOCOL_VERSION = "1.0.0"` (free-form on the wire; the
+  gateway negotiates compatibility).
+
+## Handler contract
+
+```python
+async def handler(input, ctx: HandlerContext):
+    # ctx.task         — the full task payload
+    # ctx.lease_id     — the lease the gateway holds for this delivery
+    # ctx.cancelled    — asyncio.Event set on cancel / shutdown
+    # ctx.log          — logger scoped to this lease
+    # ctx.progress(...) — non-blocking progress update
+    # ctx.fail(reason, code=...) — terminal nack (do not catch)
+    return {...}
+```
+
+* **Sync handlers** are supported; the runner awaits awaitable return values
+  and otherwise treats the return as the result.
+* **Cancellation**: handlers wrapping I/O should cooperate with
+  `ctx.cancelled` (e.g. `asyncio.wait` with `[ctx.cancelled.wait(), …]`).
+* **Idempotency** is the handler author's responsibility — the framework
+  does not checkpoint mid-task.
+
+## Failure classification
+
+| Outcome                              | Wire kind          |
+|--------------------------------------|--------------------|
+| Handler returns                      | `ack`              |
+| Handler raises `asyncio.CancelledError` (or cancel event set) | `nack: cancelled` |
+| `ctx.fail(...)`                      | `nack: terminal`   |
+| Handler raises any other exception   | `nack: retryable`  |
+| Input/output fails JSON Schema       | `nack: schema-mismatch` |
+
+Retry policy lives on the workflow (server-side), never on the SDK.
+
+## Architecture
+
+```
+┌────────────┐   POST register / heartbeat / ack / nack / progress
+│   Neuron   │──────────────────────────────────────────────────────▶│
+│  (this    │                                                       │ BigBrain
+│   SDK)    │◀──────────────────────────── SSE: lease / cancel ────│ gateway
+└────────────┘
+```
+
+* `HttpTransport` owns one SSE stream and a shared `httpx.AsyncClient`.
+* `Neuron` wires the transport to a heartbeat loop and a per-capability
+  semaphore-bounded dispatcher.
+* `run_lease(...)` validates input, invokes the handler, validates output,
+  and posts the right ack/nack frame.
+
+## Examples
+
+| Example | Capability | What it does |
+| ------- | ---------- | ------------ |
+| [`examples/http_fetch/`](examples/http_fetch/) | `examples/http.fetch` | Fetches an arbitrary HTTP(S) URL via `httpx` and returns status/headers/body. |
+| [`examples/web_search/`](examples/web_search/) | `examples/web.search` | Keyless web search via DuckDuckGo HTML scrape. No API key, but inherently brittle — see the example README for caveats. |
+
+Each ships with input/output JSON Schemas, cooperative cancellation
+(`ctx.cancelled`), and a CLI runner. Run them the same way:
+
+```bash
+pip install -e .
+BIGBRAIN_GATEWAY_URL=https://api.holokai.dev \
+BIGBRAIN_NEURON_ID=my-python-neuron-1 \
+BIGBRAIN_TOKEN=eyJ... \
+python -m examples.http_fetch    # or examples.web_search
+```
+
+## Custom transports
+
+`HttpTransport` is the default but the public `Transport` shape is documented
+on `TransportCallbacks` and `Neuron(transport=…)` accepts any object that
+matches the protocol — handy for tests or in-process embeddings.
+
+## Tests
+
+```bash
+# Unit + deterministic e2e (default — no network).
+pytest
+
+# Network-gated e2e: hits real DuckDuckGo through the real SDK to catch
+# scraper drift. Skipped unless explicitly enabled.
+E2E_NETWORK=1 pytest -m e2e_network
+```
+
+The e2e tests stand up a tiny aiohttp server on loopback that serves both
+the BigBrain `/neuron/*` surface and a stub for DuckDuckGo, then run the
+real `Neuron` SDK against it. Every byte flows over real HTTP — SSE in,
+POSTs out — exercising the full `register → lease → handler → ack` loop.
+See [`tests/e2e/`](tests/e2e/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

holokai_neuron_sdk-0.1.0/examples/http_fetch/README.md

@@ -0,0 +1,74 @@
+# `examples/http.fetch` — runnable Python neuron
+
+Generic outbound HTTP fetcher exposed as a BigBrain capability. A workflow
+plan that resolves to `examples/http.fetch` will arrive at this neuron as a
+lease, run an `httpx` request, and ack with the response.
+
+## Run
+
+```bash
+cd packages/neuron-sdk-python
+pip install -e .
+BIGBRAIN_GATEWAY_URL=https://api.holokai.dev \
+BIGBRAIN_NEURON_ID=my-python-neuron-1 \
+BIGBRAIN_TOKEN=eyJhbGciOi... \
+python -m examples.http_fetch
+```
+
+`BIGBRAIN_TOKEN_FILE=/path/to/token` is supported as an alternative — the
+file is re-read on every auth refresh, so you can rotate the token without
+restarting.
+
+## Capability shape
+
+| Field | Value |
+| ----- | ----- |
+| `type` | `examples/http.fetch` |
+| `scope` | `any` |
+| `concurrency` | 8 (handle up to 8 leases in parallel per neuron) |
+| `leaseTtlMs` | 60_000 (longer than the default to cover slow upstreams) |
+
+### Input
+
+```json
+{
+  "url": "https://example.com/api/thing",
+  "method": "GET",
+  "headers": {"User-Agent": "bigbrain-neuron"},
+  "body": null,
+  "timeout_ms": 10000,
+  "max_response_bytes": 1000000,
+  "follow_redirects": true
+}
+```
+
+Only `url` is required.
+
+### Output
+
+```json
+{
+  "status": 200,
+  "headers": {"content-type": "application/json", "...": "..."},
+  "body": "{\"hello\":\"world\"}",
+  "truncated": false,
+  "duration_ms": 87,
+  "final_url": "https://example.com/api/thing"
+}
+```
+
+* HTTP non-2xx responses are returned as-is — the workflow author decides
+  whether a 4xx/5xx is fatal.
+* Response bodies are decoded as UTF-8 (replacement on errors) and clipped
+  to `max_response_bytes`. `truncated: true` means there was more.
+* Network errors (DNS, connect refused, timeout) propagate as a
+  `retryable` nack — the workflow's retry policy decides what's next.
+* If the gateway sends a `cancel` frame mid-request the in-flight `httpx`
+  call is aborted and the lease is nacked as `cancelled`.
+
+## Files
+
+| File | What |
+| ---- | ---- |
+| [`capability.py`](capability.py) | Handler, JSON schemas, `Capability` definition. Importable on its own. |
+| [`__main__.py`](__main__.py) | CLI runner. Reads gateway URL / neuron id / token from env, registers the handler, runs until SIGINT. |

holokai_neuron_sdk-0.1.0/examples/web_search/README.md

@@ -0,0 +1,80 @@
+# `examples/web.search` — keyless web search
+
+Exposes web search to BigBrain workflows by scraping DuckDuckGo's HTML
+endpoint (`https://html.duckduckgo.com/html/`). No API key, no extra
+dependencies beyond `httpx` and stdlib `html.parser`.
+
+## ⚠️ Caveats
+
+* **Brittle by design** — DuckDuckGo can change the HTML markup or
+  tighten rate-limits at any time. If results stop coming back, look at
+  the response (`LOG_LEVEL=DEBUG`) and adjust the parser, or swap in
+  another provider.
+* **Rate-limited** — DDG returns HTTP 202 (with no results) when it
+  decides you're hitting too hard. The handler surfaces that as a
+  `terminal` nack so the workflow author chooses a back-off rather than
+  the framework retrying into a tighter ban.
+* **No personalization / safe-search controls** — kept intentionally
+  thin. Wire those in via the `region` field (passed through as
+  DuckDuckGo's `kl=` parameter) or replace the handler.
+
+## Run
+
+```bash
+cd packages/neuron-sdk-python
+pip install -e .
+BIGBRAIN_GATEWAY_URL=https://api.holokai.dev \
+BIGBRAIN_NEURON_ID=my-python-neuron-1 \
+BIGBRAIN_TOKEN=eyJ... \
+python -m examples.web_search
+```
+
+Optional overrides:
+
+| Env var | Default | What it does |
+| ------- | ------- | ------------ |
+| `EXAMPLES_WEB_SEARCH_ENDPOINT` | `https://html.duckduckgo.com/html/` | Swap providers (e.g. a private SearXNG instance — though parser will need to be adjusted to the new HTML shape). |
+| `EXAMPLES_WEB_SEARCH_UA` | a desktop Chrome UA | Set the `User-Agent`. DDG returns empty results for the stock httpx UA. |
+
+## Capability shape
+
+| Field | Value |
+| ----- | ----- |
+| `type` | `examples/web.search` |
+| `scope` | `any` |
+| `concurrency` | 4 |
+| `leaseTtlMs` | 30_000 |
+
+### Input
+
+```json
+{
+  "query": "neuron protocol holokai",
+  "max_results": 10,
+  "region": "wt-wt"
+}
+```
+
+Only `query` is required.
+
+### Output
+
+```json
+{
+  "query": "neuron protocol holokai",
+  "results": [
+    {
+      "title": "Holokai BigBrain — Neuron architecture",
+      "url": "https://example.test/neuron",
+      "snippet": "Lease-based capability dispatch over SSE+POST..."
+    }
+  ]
+}
+```
+
+## Files
+
+| File | What |
+| ---- | ---- |
+| [`capability.py`](capability.py) | Handler, JSON Schemas, `Capability` definition, defensive HTML parser. |
+| [`__main__.py`](__main__.py) | CLI runner. Reads gateway URL / neuron id / token from env, registers the handler, runs until SIGINT. |

holokai_neuron_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "holokai-neuron-sdk"
+version = "0.1.0"
+description = "SDK for building Holokai neurons in Python — connect to a BigBrain gateway over HTTP+SSE and execute capability-typed tasks."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Holokai" }]
+keywords = ["holokai", "bigbrain", "neuron", "sdk", "workflow", "sse", "agent"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.6,<3",
+    "jsonschema>=4.21,<5",
+]
+
+[project.urls]
+Homepage = "https://github.com/holok-ai/bigbrain/tree/main/packages/neuron-sdk-python#readme"
+Repository = "https://github.com/holok-ai/bigbrain"
+Issues = "https://github.com/holok-ai/bigbrain/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "aiohttp>=3.9",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/holokai_neuron_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/holokai_neuron_sdk", "README.md", "LICENSE", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-ra"
+pythonpath = ["."]
+markers = [
+    "e2e: end-to-end tests that spin up a fake gateway and exercise the full SDK loop",
+    "e2e_network: e2e tests that hit the real internet (gated by E2E_NETWORK=1)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "ASYNC"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true