ccp-sdk 0.1.0__tar.gz

ccp_sdk-0.1.0/LICENSE

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

ccp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: ccp-sdk
+Version: 0.1.0
+Summary: Reference Python SDK for Cortex Capsule Protocol (CCP)
+Author: CCP contributors
+License: MIT License
+        
+        Copyright (c) 2026 Jonathan Hidalgo
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/<your-org>/<your-repo>
+Project-URL: Repository, https://github.com/<your-org>/<your-repo>
+Keywords: ccp,protocol,iot,robotics,gateway
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.21
+Dynamic: license-file
+
+# CCP
+Cortex Capsule Protocol (CCP) — v0.1 Draft
+
+CCP standardizes communication between devices (robots, microcontrollers, gateways) and Cortex Capsule servers (local or cloud brain runtime).
+
+## Contents
+- Core specification
+- HTTP mapping
+- JSON schemas
+- Message examples
+
+## Structure
+- [docs/](docs/README.md)
+- [schemas/](schemas)
+- [examples/](examples)
+
+## Get started
+1. Read the core spec: [docs/spec/ccp-core.md](docs/spec/ccp-core.md)
+2. Check HTTP mapping: [docs/spec/http-binding.md](docs/spec/http-binding.md)
+3. See schemas: [docs/spec/message-schemas.md](docs/spec/message-schemas.md)
+4. See examples: [examples/](examples)
+
+## How to use CCP
+- This repo is the **specification**, not a dependency to install.
+- Projects should depend on a **CCP SDK** (language/runtime specific) that implements the protocol.
+- If you need JSON schemas in production, the SDK should bundle them or reference a published schema package.
+
+## Python SDK (reference)
+
+This repository now includes a minimal reference Python SDK that you can install with pip.
+
+### Install (local dev)
+From the repo root:
+
+```bash
+python -m pip install -e .
+```
+
+### Install (from PyPI)
+After you publish it:
+
+```bash
+python -m pip install ccp-sdk
+```
+
+### Usage
+See a runnable example in [examples/python_client.py](examples/python_client.py).
+
+If your ESP32 sends data to a Python gateway API, see: [examples/esp32_gateway_api/](examples/esp32_gateway_api/).
+
+## ESP32 note
+ESP32 (Arduino/ESP-IDF) does not run `pip` packages directly.
+
+Typical architecture:
+- ESP32 handles hardware (mic/speaker/LED/display) and sends events/audio to a gateway over Wi-Fi/serial.
+- The gateway (Raspberry Pi / PC) runs the Python CCP SDK and talks to the CCP server over HTTP.
+
+Practical mapping:
+- Mic (I2S) -> capture audio -> upload to `/v1/media/audio` -> send `turn` with `audio_ref`
+- Speaker (I2S) <- receive `turn_result.payload.reply.audio_ref` -> download audio -> play
+- LED strip / display <- drive UI based on `turn_result.payload.state`, `safety`, or `actions`
+
+## SDKs (planned)
+- `ccp-python` — reference SDK for capsules/gateways
+- `ccp-esp32` — thin device SDK for microcontrollers
+
+## Version
+CCP v0.1 (Draft)
+
+## Roadmap
+See [docs/roadmap.md](docs/roadmap.md).
+
+## Community
+Discord: invite link TBD.
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose changes and submit PRs.
+
+## Code of Conduct
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Security
+See [SECURITY.md](SECURITY.md).

ccp_sdk-0.1.0/README.md

@@ -0,0 +1,83 @@
+# CCP
+Cortex Capsule Protocol (CCP) — v0.1 Draft
+
+CCP standardizes communication between devices (robots, microcontrollers, gateways) and Cortex Capsule servers (local or cloud brain runtime).
+
+## Contents
+- Core specification
+- HTTP mapping
+- JSON schemas
+- Message examples
+
+## Structure
+- [docs/](docs/README.md)
+- [schemas/](schemas)
+- [examples/](examples)
+
+## Get started
+1. Read the core spec: [docs/spec/ccp-core.md](docs/spec/ccp-core.md)
+2. Check HTTP mapping: [docs/spec/http-binding.md](docs/spec/http-binding.md)
+3. See schemas: [docs/spec/message-schemas.md](docs/spec/message-schemas.md)
+4. See examples: [examples/](examples)
+
+## How to use CCP
+- This repo is the **specification**, not a dependency to install.
+- Projects should depend on a **CCP SDK** (language/runtime specific) that implements the protocol.
+- If you need JSON schemas in production, the SDK should bundle them or reference a published schema package.
+
+## Python SDK (reference)
+
+This repository now includes a minimal reference Python SDK that you can install with pip.
+
+### Install (local dev)
+From the repo root:
+
+```bash
+python -m pip install -e .
+```
+
+### Install (from PyPI)
+After you publish it:
+
+```bash
+python -m pip install ccp-sdk
+```
+
+### Usage
+See a runnable example in [examples/python_client.py](examples/python_client.py).
+
+If your ESP32 sends data to a Python gateway API, see: [examples/esp32_gateway_api/](examples/esp32_gateway_api/).
+
+## ESP32 note
+ESP32 (Arduino/ESP-IDF) does not run `pip` packages directly.
+
+Typical architecture:
+- ESP32 handles hardware (mic/speaker/LED/display) and sends events/audio to a gateway over Wi-Fi/serial.
+- The gateway (Raspberry Pi / PC) runs the Python CCP SDK and talks to the CCP server over HTTP.
+
+Practical mapping:
+- Mic (I2S) -> capture audio -> upload to `/v1/media/audio` -> send `turn` with `audio_ref`
+- Speaker (I2S) <- receive `turn_result.payload.reply.audio_ref` -> download audio -> play
+- LED strip / display <- drive UI based on `turn_result.payload.state`, `safety`, or `actions`
+
+## SDKs (planned)
+- `ccp-python` — reference SDK for capsules/gateways
+- `ccp-esp32` — thin device SDK for microcontrollers
+
+## Version
+CCP v0.1 (Draft)
+
+## Roadmap
+See [docs/roadmap.md](docs/roadmap.md).
+
+## Community
+Discord: invite link TBD.
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose changes and submit PRs.
+
+## Code of Conduct
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Security
+See [SECURITY.md](SECURITY.md).

ccp_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ccp-sdk"
+version = "0.1.0"
+description = "Reference Python SDK for Cortex Capsule Protocol (CCP)"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "CCP contributors" }
+]
+license = { file = "LICENSE" }
+keywords = ["ccp", "protocol", "iot", "robotics", "gateway"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27",
+  "jsonschema>=4.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/<your-org>/<your-repo>"
+Repository = "https://github.com/<your-org>/<your-repo>"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ccp_sdk = ["py.typed", "schemas/*.json"]

ccp_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ccp_sdk-0.1.0/src/ccp_sdk/__init__.py

@@ -0,0 +1,11 @@
+"""Reference Python SDK for Cortex Capsule Protocol (CCP)."""
+
+from .client import CCPClient
+from .errors import CCPError, CCPHTTPError, CCPSchemaError
+
+__all__ = [
+    "CCPClient",
+    "CCPError",
+    "CCPHTTPError",
+    "CCPSchemaError",
+]

ccp_sdk-0.1.0/src/ccp_sdk/client.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import CCPHTTPError
+from .messages import hello as hello_msg
+from .messages import session_end as session_end_msg
+from .messages import session_start as session_start_msg
+from .messages import turn_audio_ref as turn_audio_ref_msg
+from .messages import turn_text as turn_text_msg
+from .validator import validate_message
+
+
+class CCPClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        device_token: Optional[str] = None,
+        timeout_s: float = 10.0,
+        validate: bool = True,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._device_token = device_token
+        self._timeout_s = timeout_s
+        self._validate = validate
+        self._client = httpx.Client(timeout=timeout_s)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "CCPClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self._device_token:
+            headers["Authorization"] = f"Device {self._device_token}"
+        return headers
+
+    def _post_ccp(self, path: str, message: Dict[str, Any]) -> Dict[str, Any]:
+        if self._validate:
+            validate_message(message)
+
+        url = f"{self._base_url}{path}"
+        resp = self._client.post(url, headers=self._headers(), json=message)
+        if resp.status_code < 200 or resp.status_code >= 300:
+            body: Any
+            try:
+                body = resp.json()
+            except Exception:
+                body = resp.text
+            raise CCPHTTPError(resp.status_code, body)
+
+        data = resp.json()
+        if self._validate and isinstance(data, dict):
+            validate_message(data)
+        return data
+
+    def hello(
+        self,
+        *,
+        device_id: str,
+        device_token: str,
+        firmware: str,
+        capabilities: Dict[str, Any],
+        locale: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        msg = hello_msg(
+            device_id=device_id,
+            device_token=device_token,
+            firmware=firmware,
+            capabilities=capabilities,
+            locale=locale,
+        )
+        return self._post_ccp("/ccp/hello", msg)
+
+    def session_start(self, *, device_id: str) -> Dict[str, Any]:
+        return self._post_ccp("/ccp/session/start", session_start_msg(device_id=device_id))
+
+    def turn_text(self, *, session_id: str, text: str) -> Dict[str, Any]:
+        return self._post_ccp("/ccp/turn", turn_text_msg(session_id=session_id, text=text))
+
+    def turn_audio_ref(self, *, session_id: str, audio_ref: str) -> Dict[str, Any]:
+        return self._post_ccp(
+            "/ccp/turn", turn_audio_ref_msg(session_id=session_id, audio_ref=audio_ref)
+        )
+
+    def session_end(self, *, session_id: str) -> Dict[str, Any]:
+        return self._post_ccp("/ccp/session/end", session_end_msg(session_id=session_id))
+
+    def upload_audio(self, *, audio_bytes: bytes, content_type: str = "audio/wav") -> str:
+        url = f"{self._base_url}/v1/media/audio"
+        headers = {k: v for k, v in self._headers().items() if k.lower() != "content-type"}
+        headers["Content-Type"] = content_type
+        resp = self._client.post(
+            url,
+            headers=headers,
+            content=audio_bytes,
+        )
+        if resp.status_code < 200 or resp.status_code >= 300:
+            body: Any
+            try:
+                body = resp.json()
+            except Exception:
+                body = resp.text
+            raise CCPHTTPError(resp.status_code, body)
+
+        data = resp.json()
+        audio_ref = data.get("audio_ref") if isinstance(data, dict) else None
+        if not isinstance(audio_ref, str) or not audio_ref:
+            raise CCPHTTPError(resp.status_code, data)
+        return audio_ref
+

ccp_sdk-0.1.0/src/ccp_sdk/errors.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+class CCPError(Exception):
+    """Base error for the CCP SDK."""
+
+
+class CCPSchemaError(CCPError):
+    """Raised when a message fails JSON Schema validation."""
+
+
+class CCPHTTPError(CCPError):
+    """Raised when an HTTP call fails (non-2xx or invalid payload)."""
+
+    def __init__(self, status_code: int, body: object | None = None):
+        super().__init__(f"CCP HTTP error: {status_code}")
+        self.status_code = status_code
+        self.body = body

ccp_sdk-0.1.0/src/ccp_sdk/messages.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+
+def now_ts() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def envelope(
+    *,
+    type: str,
+    payload: Dict[str, Any],
+    ccp_version: str = "0.1",
+    id: Optional[str] = None,
+    ts: Optional[str] = None,
+) -> Dict[str, Any]:
+    return {
+        "ccp_version": ccp_version,
+        "type": type,
+        "id": id or str(uuid4()),
+        "ts": ts or now_ts(),
+        "payload": payload,
+    }
+
+
+def hello(
+    *,
+    device_id: str,
+    device_token: str,
+    firmware: str,
+    capabilities: Dict[str, Any],
+    locale: Optional[str] = None,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "device_id": device_id,
+        "device_token": device_token,
+        "firmware": firmware,
+        "capabilities": capabilities,
+    }
+    if locale is not None:
+        payload["locale"] = locale
+    return envelope(type="hello", payload=payload)
+
+
+def session_start(*, device_id: str) -> Dict[str, Any]:
+    return envelope(type="session_start", payload={"device_id": device_id})
+
+
+def turn_text(*, session_id: str, text: str) -> Dict[str, Any]:
+    return envelope(
+        type="turn",
+        payload={"session_id": session_id, "input": {"kind": "text", "text": text}},
+    )
+
+
+def turn_audio_ref(*, session_id: str, audio_ref: str) -> Dict[str, Any]:
+    return envelope(
+        type="turn",
+        payload={
+            "session_id": session_id,
+            "input": {"kind": "audio_ref", "audio_ref": audio_ref},
+        },
+    )
+
+
+def session_end(*, session_id: str) -> Dict[str, Any]:
+    return envelope(type="session_end", payload={"session_id": session_id})

ccp_sdk-0.1.0/src/ccp_sdk/schemas/ccp-message.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/ccp-message.json",
+  "title": "CCP Message Envelope",
+  "type": "object",
+  "required": ["ccp_version", "type", "id", "payload"],
+  "properties": {
+    "ccp_version": { "type": "string", "enum": ["0.1"] },
+    "type": { "type": "string" },
+    "id": { "type": "string", "minLength": 1 },
+    "ts": { "type": "string", "format": "date-time" },
+    "payload": { "type": "object" }
+  },
+  "additionalProperties": false
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/error.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/error.json",
+  "title": "CCP error",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "error" },
+        "payload": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "enum": [
+                "INVALID_REQUEST",
+                "UNAUTHORIZED",
+                "FORBIDDEN",
+                "NOT_FOUND",
+                "CONFLICT",
+                "RATE_LIMIT",
+                "SERVER_BUSY",
+                "MEDIA_TOO_LARGE",
+                "UNSUPPORTED_CAPABILITY"
+              ]
+            },
+            "message": { "type": "string" },
+            "retry_after_ms": { "type": "integer", "minimum": 0 },
+            "request_id": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/hello-ack.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/hello-ack.json",
+  "title": "CCP hello_ack",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "hello_ack" },
+        "payload": {
+          "type": "object",
+          "required": ["accepted", "device_id"],
+          "properties": {
+            "accepted": { "type": "boolean" },
+            "device_id": { "type": "string" },
+            "session_supported": { "type": "boolean" },
+            "negotiated": {
+              "type": "object",
+              "properties": {
+                "audio_codec": { "type": "string" },
+                "sample_rate": { "type": "integer" },
+                "max_audio_seconds": { "type": "number" },
+                "preferred_transport": { "type": "string" }
+              },
+              "additionalProperties": true
+            },
+            "limits": {
+              "type": "object",
+              "properties": {
+                "turns_per_min": { "type": "integer" },
+                "tts_seconds_per_min": { "type": "integer" }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/hello.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/hello.json",
+  "title": "CCP hello",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "hello" },
+        "payload": {
+          "type": "object",
+          "required": ["device_id", "device_token", "firmware", "capabilities"],
+          "properties": {
+            "device_id": { "type": "string" },
+            "device_token": { "type": "string" },
+            "firmware": { "type": "string" },
+            "capabilities": {
+              "type": "object",
+              "properties": {
+                "audio_in": {
+                  "type": "object",
+                  "properties": {
+                    "codecs": { "type": "array", "items": { "type": "string" } },
+                    "sample_rates": { "type": "array", "items": { "type": "integer" } },
+                    "channels": { "type": "integer", "minimum": 1 }
+                  },
+                  "additionalProperties": true
+                },
+                "audio_out": {
+                  "type": "object",
+                  "properties": {
+                    "codecs": { "type": "array", "items": { "type": "string" } },
+                    "sample_rates": { "type": "array", "items": { "type": "integer" } },
+                    "channels": { "type": "integer", "minimum": 1 }
+                  },
+                  "additionalProperties": true
+                },
+                "io": {
+                  "type": "object",
+                  "properties": {
+                    "button": { "type": "boolean" },
+                    "led": { "type": "boolean" },
+                    "screen": { "type": "boolean" }
+                  },
+                  "additionalProperties": true
+                },
+                "actions": { "type": "array", "items": { "type": "string" } },
+                "streaming": {
+                  "type": "object",
+                  "properties": { "supported": { "type": "boolean" } },
+                  "additionalProperties": true
+                },
+                "network": {
+                  "type": "object",
+                  "properties": {
+                    "type": { "type": "string" },
+                    "metered": { "type": "boolean" }
+                  },
+                  "additionalProperties": true
+                },
+                "extensions": { "type": "array", "items": { "type": "string" } }
+              },
+              "additionalProperties": true
+            },
+            "locale": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/session-end.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/session-end.json",
+  "title": "CCP session_end",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "session_end" },
+        "payload": {
+          "type": "object",
+          "required": ["session_id"],
+          "properties": {
+            "session_id": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/session-ended.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/session-ended.json",
+  "title": "CCP session_ended",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "session_ended" },
+        "payload": {
+          "type": "object",
+          "required": ["session_id"],
+          "properties": {
+            "session_id": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/session-start.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/session-start.json",
+  "title": "CCP session_start",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "session_start" },
+        "payload": {
+          "type": "object",
+          "required": ["device_id"],
+          "properties": {
+            "device_id": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/session-started.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/session-started.json",
+  "title": "CCP session_started",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "session_started" },
+        "payload": {
+          "type": "object",
+          "required": ["session_id"],
+          "properties": {
+            "session_id": { "type": "string" },
+            "active_capsule_id": { "type": "string" },
+            "kid_safe_applied": { "type": "boolean" }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/turn-result.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/turn-result.json",
+  "title": "CCP turn_result",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "turn_result" },
+        "payload": {
+          "type": "object",
+          "required": ["session_id"],
+          "properties": {
+            "session_id": { "type": "string" },
+            "reply": {
+              "type": "object",
+              "properties": {
+                "text": { "type": "string" },
+                "audio_ref": { "type": "string" }
+              },
+              "additionalProperties": true
+            },
+            "state": { "type": "object", "additionalProperties": true },
+            "safety": {
+              "type": "object",
+              "properties": {
+                "blocked": { "type": "boolean" },
+                "kid_safe_applied": { "type": "boolean" },
+                "reason": { "type": ["string", "null"] }
+              },
+              "additionalProperties": true
+            },
+            "actions": { "type": "array", "items": { "type": "object" } },
+            "meta": { "type": "object", "additionalProperties": true }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas/turn.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ccp.dev/schemas/turn.json",
+  "title": "CCP turn",
+  "allOf": [
+    { "$ref": "ccp-message.json" },
+    {
+      "properties": {
+        "type": { "const": "turn" },
+        "payload": {
+          "type": "object",
+          "required": ["session_id", "input"],
+          "properties": {
+            "session_id": { "type": "string" },
+            "input": {
+              "type": "object",
+              "required": ["kind"],
+              "properties": {
+                "kind": { "type": "string", "enum": ["text", "audio_ref"] },
+                "text": { "type": "string" },
+                "audio_ref": { "type": "string" }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ccp_sdk-0.1.0/src/ccp_sdk/schemas.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any, Dict
+
+from jsonschema import Draft202012Validator
+from jsonschema.validators import RefResolver
+
+from .errors import CCPSchemaError
+
+
+_MESSAGE_TYPE_TO_SCHEMA = {
+    "hello": "hello.json",
+    "hello_ack": "hello-ack.json",
+    "session_start": "session-start.json",
+    "session_started": "session-started.json",
+    "turn": "turn.json",
+    "turn_result": "turn-result.json",
+    "session_end": "session-end.json",
+    "session_ended": "session-ended.json",
+    "error": "error.json",
+}
+
+
+def _load_all_schemas() -> Dict[str, Dict[str, Any]]:
+    schema_pkg = resources.files("ccp_sdk.schemas")
+    schemas: Dict[str, Dict[str, Any]] = {}
+    for entry in schema_pkg.iterdir():
+        if entry.name.endswith(".json"):
+            schemas[entry.name] = json.loads(entry.read_text(encoding="utf-8"))
+    return schemas
+
+
+_ALL_SCHEMAS = _load_all_schemas()
+
+
+def _make_resolver(schema: Dict[str, Any]) -> RefResolver:
+    store: Dict[str, Any] = {}
+    for filename, schema_obj in _ALL_SCHEMAS.items():
+        store[filename] = schema_obj
+        schema_id = schema_obj.get("$id")
+        if isinstance(schema_id, str):
+            store[schema_id] = schema_obj
+
+    return RefResolver.from_schema(schema, store=store)
+
+
+def validate_message(message: Dict[str, Any]) -> None:
+    msg_type = message.get("type")
+    if not isinstance(msg_type, str) or not msg_type:
+        raise CCPSchemaError("Missing or invalid message.type")
+
+    schema_filename = _MESSAGE_TYPE_TO_SCHEMA.get(msg_type)
+    if schema_filename is None:
+        raise CCPSchemaError(f"Unknown message type: {msg_type}")
+
+    schema = _ALL_SCHEMAS.get(schema_filename)
+    if schema is None:
+        raise CCPSchemaError(f"Schema not bundled: {schema_filename}")
+
+    validator = Draft202012Validator(schema, resolver=_make_resolver(schema))
+    errors = sorted(validator.iter_errors(message), key=lambda e: e.path)
+    if errors:
+        first = errors[0]
+        loc = "/".join(str(p) for p in first.path) or "<root>"
+        raise CCPSchemaError(f"Invalid CCP message at {loc}: {first.message}")

ccp_sdk-0.1.0/src/ccp_sdk/validator.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any, Dict
+
+from jsonschema import Draft202012Validator
+from jsonschema.validators import RefResolver
+
+from .errors import CCPSchemaError
+
+
+_MESSAGE_TYPE_TO_SCHEMA = {
+    "hello": "hello.json",
+    "hello_ack": "hello-ack.json",
+    "session_start": "session-start.json",
+    "session_started": "session-started.json",
+    "turn": "turn.json",
+    "turn_result": "turn-result.json",
+    "session_end": "session-end.json",
+    "session_ended": "session-ended.json",
+    "error": "error.json",
+}
+
+
+def _load_all_schemas() -> Dict[str, Dict[str, Any]]:
+    schema_pkg = resources.files("ccp_sdk.schemas")
+    schemas: Dict[str, Dict[str, Any]] = {}
+    for entry in schema_pkg.iterdir():
+        if entry.name.endswith(".json"):
+            schemas[entry.name] = json.loads(entry.read_text(encoding="utf-8"))
+    return schemas
+
+
+_ALL_SCHEMAS = _load_all_schemas()
+
+
+def _make_resolver(schema: Dict[str, Any]) -> RefResolver:
+    store: Dict[str, Any] = {}
+    for filename, schema_obj in _ALL_SCHEMAS.items():
+        store[filename] = schema_obj
+        schema_id = schema_obj.get("$id")
+        if isinstance(schema_id, str):
+            store[schema_id] = schema_obj
+
+    return RefResolver.from_schema(schema, store=store)
+
+
+def validate_message(message: Dict[str, Any]) -> None:
+    msg_type = message.get("type")
+    if not isinstance(msg_type, str) or not msg_type:
+        raise CCPSchemaError("Missing or invalid message.type")
+
+    schema_filename = _MESSAGE_TYPE_TO_SCHEMA.get(msg_type)
+    if schema_filename is None:
+        raise CCPSchemaError(f"Unknown message type: {msg_type}")
+
+    schema = _ALL_SCHEMAS.get(schema_filename)
+    if schema is None:
+        raise CCPSchemaError(f"Schema not bundled: {schema_filename}")
+
+    validator = Draft202012Validator(schema, resolver=_make_resolver(schema))
+    errors = sorted(validator.iter_errors(message), key=lambda e: e.path)
+    if errors:
+        first = errors[0]
+        loc = "/".join(str(p) for p in first.path) or "<root>"
+        raise CCPSchemaError(f"Invalid CCP message at {loc}: {first.message}")

ccp_sdk-0.1.0/src/ccp_sdk.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: ccp-sdk
+Version: 0.1.0
+Summary: Reference Python SDK for Cortex Capsule Protocol (CCP)
+Author: CCP contributors
+License: MIT License
+        
+        Copyright (c) 2026 Jonathan Hidalgo
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/<your-org>/<your-repo>
+Project-URL: Repository, https://github.com/<your-org>/<your-repo>
+Keywords: ccp,protocol,iot,robotics,gateway
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.21
+Dynamic: license-file
+
+# CCP
+Cortex Capsule Protocol (CCP) — v0.1 Draft
+
+CCP standardizes communication between devices (robots, microcontrollers, gateways) and Cortex Capsule servers (local or cloud brain runtime).
+
+## Contents
+- Core specification
+- HTTP mapping
+- JSON schemas
+- Message examples
+
+## Structure
+- [docs/](docs/README.md)
+- [schemas/](schemas)
+- [examples/](examples)
+
+## Get started
+1. Read the core spec: [docs/spec/ccp-core.md](docs/spec/ccp-core.md)
+2. Check HTTP mapping: [docs/spec/http-binding.md](docs/spec/http-binding.md)
+3. See schemas: [docs/spec/message-schemas.md](docs/spec/message-schemas.md)
+4. See examples: [examples/](examples)
+
+## How to use CCP
+- This repo is the **specification**, not a dependency to install.
+- Projects should depend on a **CCP SDK** (language/runtime specific) that implements the protocol.
+- If you need JSON schemas in production, the SDK should bundle them or reference a published schema package.
+
+## Python SDK (reference)
+
+This repository now includes a minimal reference Python SDK that you can install with pip.
+
+### Install (local dev)
+From the repo root:
+
+```bash
+python -m pip install -e .
+```
+
+### Install (from PyPI)
+After you publish it:
+
+```bash
+python -m pip install ccp-sdk
+```
+
+### Usage
+See a runnable example in [examples/python_client.py](examples/python_client.py).
+
+If your ESP32 sends data to a Python gateway API, see: [examples/esp32_gateway_api/](examples/esp32_gateway_api/).
+
+## ESP32 note
+ESP32 (Arduino/ESP-IDF) does not run `pip` packages directly.
+
+Typical architecture:
+- ESP32 handles hardware (mic/speaker/LED/display) and sends events/audio to a gateway over Wi-Fi/serial.
+- The gateway (Raspberry Pi / PC) runs the Python CCP SDK and talks to the CCP server over HTTP.
+
+Practical mapping:
+- Mic (I2S) -> capture audio -> upload to `/v1/media/audio` -> send `turn` with `audio_ref`
+- Speaker (I2S) <- receive `turn_result.payload.reply.audio_ref` -> download audio -> play
+- LED strip / display <- drive UI based on `turn_result.payload.state`, `safety`, or `actions`
+
+## SDKs (planned)
+- `ccp-python` — reference SDK for capsules/gateways
+- `ccp-esp32` — thin device SDK for microcontrollers
+
+## Version
+CCP v0.1 (Draft)
+
+## Roadmap
+See [docs/roadmap.md](docs/roadmap.md).
+
+## Community
+Discord: invite link TBD.
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose changes and submit PRs.
+
+## Code of Conduct
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Security
+See [SECURITY.md](SECURITY.md).

ccp_sdk-0.1.0/src/ccp_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+README.md
+pyproject.toml
+src/ccp_sdk/__init__.py
+src/ccp_sdk/client.py
+src/ccp_sdk/errors.py
+src/ccp_sdk/messages.py
+src/ccp_sdk/py.typed
+src/ccp_sdk/schemas.py
+src/ccp_sdk/validator.py
+src/ccp_sdk.egg-info/PKG-INFO
+src/ccp_sdk.egg-info/SOURCES.txt
+src/ccp_sdk.egg-info/dependency_links.txt
+src/ccp_sdk.egg-info/requires.txt
+src/ccp_sdk.egg-info/top_level.txt
+src/ccp_sdk/schemas/__init__.py
+src/ccp_sdk/schemas/ccp-message.json
+src/ccp_sdk/schemas/error.json
+src/ccp_sdk/schemas/hello-ack.json
+src/ccp_sdk/schemas/hello.json
+src/ccp_sdk/schemas/session-end.json
+src/ccp_sdk/schemas/session-ended.json
+src/ccp_sdk/schemas/session-start.json
+src/ccp_sdk/schemas/session-started.json
+src/ccp_sdk/schemas/turn-result.json
+src/ccp_sdk/schemas/turn.json

ccp_sdk-0.1.0/src/ccp_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ccp_sdk-0.1.0/src/ccp_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.27
+jsonschema>=4.21

ccp_sdk-0.1.0/src/ccp_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+ccp_sdk