cap-sdk-python 2.0.16__tar.gz → 2.0.18__tar.gz

{cap_sdk_python-2.0.16/cap_sdk_python.egg-info → cap_sdk_python-2.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cap-sdk-python
-Version: 2.0.16
+Version: 2.0.18
 Summary: CAP (Cordum Agent Protocol) Python SDK
 Project-URL: Homepage, https://github.com/cordum-io/cap
 Requires-Python: >=3.9
@@ -8,6 +8,9 @@ Description-Content-Type: text/markdown
 Requires-Dist: protobuf>=4.25.0
 Requires-Dist: grpcio>=1.59.0
 Requires-Dist: nats-py>=2.6.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: redis>=5.0.0
 
 # CAP Python SDK
 
@@ -77,7 +80,7 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 ## Defaults
 - Subjects: `sys.job.submit`, `sys.job.result`, `sys.heartbeat`.
 - Protocol version: `1`.
-- Signing: `submit_job` and `run_worker` sign envelopes when given an `ec.EllipticCurvePrivateKey`. Generate a keypair with `cryptography`:
+- Signing: `submit_job` and `run_worker` sign envelopes when given an `ec.EllipticCurvePrivateKey`. Signatures use deterministic protobuf serialization (map entries ordered by key) for cross-SDK verification. Generate a keypair with `cryptography`:
   ```python
   from cryptography.hazmat.primitives.asymmetric import ec
   priv = ec.generate_private_key(ec.SECP256R1())
@@ -88,3 +91,30 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 - Pass `private_key=None` to `submit_job` if you want to send unsigned envelopes.
 
 Swap out `cap.bus` if you need a different transport.
+
+## Runtime (High-Level SDK)
+The runtime hides NATS/Redis plumbing and gives you typed handlers.
+
+```python
+import asyncio
+from pydantic import BaseModel
+from cap.runtime import Agent, Context
+
+class Input(BaseModel):
+    prompt: str
+
+class Output(BaseModel):
+    summary: str
+
+agent = Agent(retries=2)
+
+@agent.job("job.summarize", input_model=Input, output_model=Output)
+async def summarize(ctx: Context, data: Input) -> Output:
+    return Output(summary=data.prompt[:140])
+
+asyncio.run(agent.run())
+```
+
+### Environment
+- `NATS_URL` (default `nats://127.0.0.1:4222`)
+- `REDIS_URL` (default `redis://127.0.0.1:6379/0`)

cap_sdk_python-2.0.16/PKG-INFO → cap_sdk_python-2.0.18/README.md

@@ -1,14 +1,3 @@
-Metadata-Version: 2.4
-Name: cap-sdk-python
-Version: 2.0.16
-Summary: CAP (Cordum Agent Protocol) Python SDK
-Project-URL: Homepage, https://github.com/cordum-io/cap
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: protobuf>=4.25.0
-Requires-Dist: grpcio>=1.59.0
-Requires-Dist: nats-py>=2.6.0
-
 # CAP Python SDK
 
 Asyncio-first SDK with NATS helpers for CAP workers and clients.
@@ -77,7 +66,7 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 ## Defaults
 - Subjects: `sys.job.submit`, `sys.job.result`, `sys.heartbeat`.
 - Protocol version: `1`.
-- Signing: `submit_job` and `run_worker` sign envelopes when given an `ec.EllipticCurvePrivateKey`. Generate a keypair with `cryptography`:
+- Signing: `submit_job` and `run_worker` sign envelopes when given an `ec.EllipticCurvePrivateKey`. Signatures use deterministic protobuf serialization (map entries ordered by key) for cross-SDK verification. Generate a keypair with `cryptography`:
   ```python
   from cryptography.hazmat.primitives.asymmetric import ec
   priv = ec.generate_private_key(ec.SECP256R1())
@@ -88,3 +77,30 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 - Pass `private_key=None` to `submit_job` if you want to send unsigned envelopes.
 
 Swap out `cap.bus` if you need a different transport.
+
+## Runtime (High-Level SDK)
+The runtime hides NATS/Redis plumbing and gives you typed handlers.
+
+```python
+import asyncio
+from pydantic import BaseModel
+from cap.runtime import Agent, Context
+
+class Input(BaseModel):
+    prompt: str
+
+class Output(BaseModel):
+    summary: str
+
+agent = Agent(retries=2)
+
+@agent.job("job.summarize", input_model=Input, output_model=Output)
+async def summarize(ctx: Context, data: Input) -> Output:
+    return Output(summary=data.prompt[:140])
+
+asyncio.run(agent.run())
+```
+
+### Environment
+- `NATS_URL` (default `nats://127.0.0.1:4222`)
+- `REDIS_URL` (default `redis://127.0.0.1:6379/0`)

{cap_sdk_python-2.0.16 → cap_sdk_python-2.0.18}/cap/__init__.py

@@ -26,5 +26,15 @@ except Exception:
 from .client import submit_job
 from .worker import run_worker
 from .bus import connect_nats
+from .runtime import Agent, Context, BlobStore, RedisBlobStore, InMemoryBlobStore
 
-__all__ = ["submit_job", "run_worker", "connect_nats"]
+__all__ = [
+    "submit_job",
+    "run_worker",
+    "connect_nats",
+    "Agent",
+    "Context",
+    "BlobStore",
+    "RedisBlobStore",
+    "InMemoryBlobStore",
+]

{cap_sdk_python-2.0.16 → cap_sdk_python-2.0.18}/cap/client.py

@@ -26,8 +26,8 @@ async def submit_job(
     packet.job_request.CopyFrom(job_request)
 
     if private_key:
-        unsigned_data = packet.SerializeToString()
+        unsigned_data = packet.SerializeToString(deterministic=True)
         signature = private_key.sign(unsigned_data, ec.ECDSA(hashes.SHA256()))
         packet.signature = signature
 
-    await nc.publish(SUBJECT_SUBMIT, packet.SerializeToString())
+    await nc.publish(SUBJECT_SUBMIT, packet.SerializeToString(deterministic=True))

cap_sdk_python-2.0.18/cap/runtime.py

@@ -0,0 +1,394 @@
+import asyncio
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Dict, Optional, Protocol, Type, TypeVar, Union
+
+from google.protobuf import timestamp_pb2
+from cap.pb.cordum.agent.v1 import buspacket_pb2, job_pb2
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives import hashes
+
+try:
+    import redis.asyncio as redis_async  # type: ignore
+except Exception:  # pragma: no cover - optional until runtime used
+    redis_async = None
+
+try:
+    from pydantic import BaseModel, ValidationError
+except Exception:  # pragma: no cover - optional until runtime used
+    BaseModel = None
+    ValidationError = Exception
+
+
+DEFAULT_PROTOCOL_VERSION = 1
+SUBJECT_RESULT = "sys.job.result"
+
+
+class BlobStore(Protocol):
+    async def get(self, key: str) -> Optional[bytes]:
+        ...
+
+    async def set(self, key: str, data: bytes) -> None:
+        ...
+
+    async def close(self) -> None:
+        ...
+
+
+class RedisBlobStore:
+    def __init__(self, redis_url: str) -> None:
+        if redis_async is None:
+            raise RuntimeError("redis is required for RedisBlobStore")
+        self._client = redis_async.from_url(redis_url)
+
+    async def get(self, key: str) -> Optional[bytes]:
+        value = await self._client.get(key)
+        return value
+
+    async def set(self, key: str, data: bytes) -> None:
+        await self._client.set(key, data)
+
+    async def close(self) -> None:
+        await self._client.close()
+
+
+class InMemoryBlobStore:
+    def __init__(self) -> None:
+        self._data: Dict[str, bytes] = {}
+
+    async def get(self, key: str) -> Optional[bytes]:
+        return self._data.get(key)
+
+    async def set(self, key: str, data: bytes) -> None:
+        self._data[key] = data
+
+    async def close(self) -> None:
+        return None
+
+
+def pointer_for_key(key: str) -> str:
+    return "redis://" + key
+
+
+def key_from_pointer(ptr: str) -> str:
+    if not ptr:
+        raise ValueError("empty pointer")
+    if not ptr.startswith("redis://"):
+        raise ValueError("unsupported pointer scheme")
+    key = ptr[len("redis://") :]
+    if not key:
+        raise ValueError("missing pointer key")
+    return key
+
+
+def _default_logger() -> logging.Logger:
+    logger = logging.getLogger("cap.runtime")
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter("%(levelname)s %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger
+
+
+@dataclass
+class Context:
+    job: job_pb2.JobRequest
+    packet: buspacket_pb2.BusPacket
+    logger: logging.LoggerAdapter
+
+    @property
+    def job_id(self) -> str:
+        return self.job.job_id
+
+    @property
+    def trace_id(self) -> str:
+        return self.packet.trace_id
+
+
+TIn = TypeVar("TIn")
+TOut = TypeVar("TOut")
+TAny = TypeVar("TAny")
+
+
+@dataclass
+class HandlerSpec:
+    topic: str
+    func: Callable[[Context, Any], Union[Awaitable[Any], Any]]
+    input_model: Optional[Type[Any]]
+    output_model: Optional[Type[Any]]
+    retries: int
+
+
+class Agent:
+    def __init__(
+        self,
+        *,
+        nats_url: Optional[str] = None,
+        redis_url: Optional[str] = None,
+        store: Optional[BlobStore] = None,
+        public_keys: Optional[Dict[str, ec.EllipticCurvePublicKey]] = None,
+        private_key: Optional[ec.EllipticCurvePrivateKey] = None,
+        sender_id: str = "cap-runtime",
+        retries: int = 0,
+        io_timeout: Optional[float] = 5.0,
+        max_context_bytes: Optional[int] = 2 * 1024 * 1024,
+        max_result_bytes: Optional[int] = 2 * 1024 * 1024,
+        connect_fn: Optional[Callable[..., Awaitable[Any]]] = None,
+        logger: Optional[logging.Logger] = None,
+    ) -> None:
+        self._nats_url = nats_url or os.getenv("NATS_URL", "nats://127.0.0.1:4222")
+        self._redis_url = redis_url or os.getenv("REDIS_URL", "redis://127.0.0.1:6379/0")
+        self._store = store
+        self._public_keys = public_keys
+        self._private_key = private_key
+        self._sender_id = sender_id
+        self._default_retries = max(0, retries)
+        self._io_timeout = io_timeout if io_timeout and io_timeout > 0 else None
+        self._max_context_bytes = max_context_bytes if max_context_bytes and max_context_bytes > 0 else None
+        self._max_result_bytes = max_result_bytes if max_result_bytes and max_result_bytes > 0 else None
+        self._connect_fn = connect_fn
+        self._logger = logger or _default_logger()
+        self._handlers: Dict[str, HandlerSpec] = {}
+        self._nc = None
+
+    def job(
+        self,
+        topic: str,
+        *,
+        input_model: Optional[Type[Any]] = None,
+        output_model: Optional[Type[Any]] = None,
+        retries: Optional[int] = None,
+    ) -> Callable[
+        [Callable[[Context, Any], Union[Awaitable[Any], Any]]],
+        Callable[[Context, Any], Union[Awaitable[Any], Any]],
+    ]:
+        def decorator(func: Callable[[Context, Any], Union[Awaitable[Any], Any]]):
+            spec = HandlerSpec(
+                topic=topic,
+                func=func,
+                input_model=input_model,
+                output_model=output_model,
+                retries=self._default_retries if retries is None else max(0, retries),
+            )
+            self._handlers[topic] = spec
+            return func
+
+        return decorator
+
+    async def start(self) -> None:
+        if not self._handlers:
+            raise RuntimeError("no handlers registered")
+        if self._connect_fn is None:
+            try:
+                import nats  # type: ignore
+            except ImportError as exc:
+                raise RuntimeError("nats-py is required to connect to NATS") from exc
+            self._connect_fn = nats.connect
+
+        self._nc = await self._with_timeout(
+            self._connect_fn(servers=self._nats_url, name=self._sender_id),
+            "nats connect",
+        )
+        if self._store is None:
+            self._store = RedisBlobStore(self._redis_url)
+
+        for topic, spec in self._handlers.items():
+            await self._nc.subscribe(topic, queue=topic, cb=lambda msg, s=spec: asyncio.create_task(self._on_msg(msg, s)))
+
+    async def close(self) -> None:
+        if self._nc is not None:
+            await self._nc.drain()
+        if self._store is not None:
+            await self._store.close()
+
+    async def run(self) -> None:
+        await self.start()
+        try:
+            while True:
+                await asyncio.sleep(1)
+        finally:
+            await self.close()
+
+    async def _on_msg(self, msg: Any, spec: HandlerSpec) -> None:
+        packet = buspacket_pb2.BusPacket()
+        try:
+            packet.ParseFromString(msg.data)
+        except Exception as exc:
+            self._logger.error("runtime: decode failed: %s", exc)
+            return
+
+        if self._public_keys is not None:
+            sender_key = self._public_keys.get(packet.sender_id)
+            if not sender_key:
+                self._logger.warning("runtime: no public key for sender %s", packet.sender_id)
+                return
+            if not packet.signature:
+                self._logger.warning("runtime: missing signature for sender %s", packet.sender_id)
+                return
+            signature = packet.signature
+            packet.ClearField("signature")
+            unsigned = packet.SerializeToString(deterministic=True)
+            packet.signature = signature
+            try:
+                sender_key.verify(signature, unsigned, ec.ECDSA(hashes.SHA256()))
+            except Exception:
+                self._logger.warning("runtime: invalid signature from sender %s", packet.sender_id)
+                return
+
+        req = packet.job_request
+        if not req.job_id:
+            return
+
+        ctx_logger = logging.LoggerAdapter(
+            self._logger,
+            {
+                "job_id": req.job_id,
+                "trace_id": packet.trace_id,
+                "topic": req.topic,
+            },
+        )
+        ctx = Context(job=req, packet=packet, logger=ctx_logger)
+
+        store = self._store
+        if store is None:
+            ctx_logger.error("runtime: blob store not initialized")
+            return
+
+        try:
+            key = key_from_pointer(req.context_ptr)
+            payload = await self._with_timeout(store.get(key), "context fetch")
+            if payload is None:
+                raise ValueError("context not found")
+            if self._max_context_bytes is not None and len(payload) > self._max_context_bytes:
+                raise ValueError("context exceeds max size")
+        except Exception as exc:
+            await self._publish_failure(ctx, req, str(exc), execution_ms=0)
+            return
+
+        try:
+            raw = json.loads(payload.decode("utf-8"))
+        except Exception as exc:
+            await self._publish_failure(ctx, req, f"context decode failed: {exc}", execution_ms=0)
+            return
+
+        try:
+            input_data = self._validate_input(spec, raw)
+        except Exception as exc:
+            await self._publish_failure(ctx, req, f"input validation failed: {exc}", execution_ms=0)
+            return
+
+        start_time = time.monotonic()
+        error: Optional[str] = None
+        output: Any = None
+        for attempt in range(spec.retries + 1):
+            try:
+                output = spec.func(ctx, input_data)
+                if asyncio.iscoroutine(output):
+                    output = await output
+                output = self._validate_output(spec, output)
+                error = None
+                break
+            except Exception as exc:
+                error = str(exc)
+                ctx_logger.warning("runtime: handler failed (attempt %d/%d): %s", attempt + 1, spec.retries + 1, exc)
+                if attempt >= spec.retries:
+                    break
+
+        elapsed_ms = int((time.monotonic() - start_time) * 1000)
+        if error is not None:
+            await self._publish_failure(ctx, req, error, execution_ms=elapsed_ms)
+            return
+
+        try:
+            result_payload = self._serialize_output(output)
+            if self._max_result_bytes is not None and len(result_payload) > self._max_result_bytes:
+                raise ValueError("result exceeds max size")
+            result_key = f"res:{req.job_id}"
+            await self._with_timeout(store.set(result_key, result_payload), "result write")
+            result_ptr = pointer_for_key(result_key)
+        except Exception as exc:
+            await self._publish_failure(ctx, req, f"result write failed: {exc}", execution_ms=elapsed_ms)
+            return
+
+        result = job_pb2.JobResult(
+            job_id=req.job_id,
+            status=job_pb2.JOB_STATUS_SUCCEEDED,
+            result_ptr=result_ptr,
+            worker_id=self._sender_id,
+            execution_ms=elapsed_ms,
+        )
+        await self._publish_result(ctx, result)
+
+    def _validate_input(self, spec: HandlerSpec, data: Any) -> Any:
+        if spec.input_model is None:
+            return data
+        if BaseModel is not None and isinstance(spec.input_model, type) and issubclass(spec.input_model, BaseModel):
+            return spec.input_model.model_validate(data)
+        return spec.input_model(**data)
+
+    def _validate_output(self, spec: HandlerSpec, data: Any) -> Any:
+        if spec.output_model is None:
+            return data
+        if BaseModel is not None and isinstance(spec.output_model, type) and issubclass(spec.output_model, BaseModel):
+            return spec.output_model.model_validate(data)
+        return spec.output_model(**data)
+
+    def _serialize_output(self, data: Any) -> bytes:
+        if BaseModel is not None and isinstance(data, BaseModel):
+            return json.dumps(data.model_dump(mode="json")).encode("utf-8")
+        if isinstance(data, (dict, list, str, int, float, bool)) or data is None:
+            return json.dumps(data).encode("utf-8")
+        if hasattr(data, "__dict__"):
+            return json.dumps(data.__dict__).encode("utf-8")
+        raise ValueError("output is not JSON serializable")
+
+    async def _publish_failure(
+        self,
+        ctx: Context,
+        req: job_pb2.JobRequest,
+        error: str,
+        execution_ms: int,
+    ) -> None:
+        result = job_pb2.JobResult(
+            job_id=req.job_id,
+            status=job_pb2.JOB_STATUS_FAILED,
+            error_message=error,
+            worker_id=self._sender_id,
+            execution_ms=execution_ms,
+        )
+        await self._publish_result(ctx, result)
+
+    async def _publish_result(self, ctx: Context, result: job_pb2.JobResult) -> None:
+        if self._nc is None:
+            ctx.logger.error("runtime: NATS not initialized")
+            return
+        packet = buspacket_pb2.BusPacket()
+        packet.trace_id = ctx.packet.trace_id
+        packet.sender_id = self._sender_id
+        packet.protocol_version = DEFAULT_PROTOCOL_VERSION
+        ts = timestamp_pb2.Timestamp()
+        ts.GetCurrentTime()
+        packet.created_at.CopyFrom(ts)
+        packet.job_result.CopyFrom(result)
+
+        if self._private_key is not None:
+            unsigned = packet.SerializeToString(deterministic=True)
+            packet.signature = self._private_key.sign(unsigned, ec.ECDSA(hashes.SHA256()))
+
+        await self._with_timeout(
+            self._nc.publish(SUBJECT_RESULT, packet.SerializeToString(deterministic=True)),
+            "result publish",
+        )
+
+    async def _with_timeout(self, coro: Awaitable[TAny], label: str) -> TAny:
+        if self._io_timeout is None:
+            return await coro
+        try:
+            return await asyncio.wait_for(coro, timeout=self._io_timeout)
+        except asyncio.TimeoutError as exc:
+            raise TimeoutError(f"{label} timed out") from exc

{cap_sdk_python-2.0.16 → cap_sdk_python-2.0.18}/cap/worker.py

@@ -38,7 +38,8 @@ async def run_worker(nats_url: str, subject: str, handler: Callable[[job_pb2.Job
 
             signature = packet.signature
             packet.ClearField("signature")
-            unsigned_data = packet.SerializeToString()
+            unsigned_data = packet.SerializeToString(deterministic=True)
+            packet.signature = signature
             try:
                 public_key.verify(signature, unsigned_data, ec.ECDSA(hashes.SHA256()))
             except Exception:
@@ -76,11 +77,11 @@ async def run_worker(nats_url: str, subject: str, handler: Callable[[job_pb2.Job
         out.job_result.CopyFrom(res)
 
         if private_key:
-            unsigned_data = out.SerializeToString()
+            unsigned_data = out.SerializeToString(deterministic=True)
             signature = private_key.sign(unsigned_data, ec.ECDSA(hashes.SHA256()))
             out.signature = signature
 
-        await nc.publish(SUBJECT_RESULT, out.SerializeToString())
+        await nc.publish(SUBJECT_RESULT, out.SerializeToString(deterministic=True))
 
     await nc.subscribe(subject, queue=subject, cb=on_msg)
     try:

cap_sdk_python-2.0.16/README.md → cap_sdk_python-2.0.18/cap_sdk_python.egg-info/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: cap-sdk-python
+Version: 2.0.18
+Summary: CAP (Cordum Agent Protocol) Python SDK
+Project-URL: Homepage, https://github.com/cordum-io/cap
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: grpcio>=1.59.0
+Requires-Dist: nats-py>=2.6.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: redis>=5.0.0
+
 # CAP Python SDK
 
 Asyncio-first SDK with NATS helpers for CAP workers and clients.
@@ -66,7 +80,7 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 ## Defaults
 - Subjects: `sys.job.submit`, `sys.job.result`, `sys.heartbeat`.
 - Protocol version: `1`.
-- Signing: `submit_job` and `run_worker` sign envelopes when given an `ec.EllipticCurvePrivateKey`. Generate a keypair with `cryptography`:
+- Signing: `submit_job` and `run_worker` sign envelopes when given an `ec.EllipticCurvePrivateKey`. Signatures use deterministic protobuf serialization (map entries ordered by key) for cross-SDK verification. Generate a keypair with `cryptography`:
   ```python
   from cryptography.hazmat.primitives.asymmetric import ec
   priv = ec.generate_private_key(ec.SECP256R1())
@@ -77,3 +91,30 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 - Pass `private_key=None` to `submit_job` if you want to send unsigned envelopes.
 
 Swap out `cap.bus` if you need a different transport.
+
+## Runtime (High-Level SDK)
+The runtime hides NATS/Redis plumbing and gives you typed handlers.
+
+```python
+import asyncio
+from pydantic import BaseModel
+from cap.runtime import Agent, Context
+
+class Input(BaseModel):
+    prompt: str
+
+class Output(BaseModel):
+    summary: str
+
+agent = Agent(retries=2)
+
+@agent.job("job.summarize", input_model=Input, output_model=Output)
+async def summarize(ctx: Context, data: Input) -> Output:
+    return Output(summary=data.prompt[:140])
+
+asyncio.run(agent.run())
+```
+
+### Environment
+- `NATS_URL` (default `nats://127.0.0.1:4222`)
+- `REDIS_URL` (default `redis://127.0.0.1:6379/0`)

{cap_sdk_python-2.0.16 → cap_sdk_python-2.0.18}/cap_sdk_python.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 cap/__init__.py
 cap/bus.py
 cap/client.py
+cap/runtime.py
 cap/worker.py
 cap/pb/__init__.py
 cap/pb/cordum/__init__.py
@@ -23,4 +24,6 @@ cap_sdk_python.egg-info/SOURCES.txt
 cap_sdk_python.egg-info/dependency_links.txt
 cap_sdk_python.egg-info/requires.txt
 cap_sdk_python.egg-info/top_level.txt
+tests/test_conformance.py
+tests/test_runtime.py
 tests/test_sdk.py

cap_sdk_python-2.0.18/cap_sdk_python.egg-info/requires.txt

@@ -0,0 +1,6 @@
+protobuf>=4.25.0
+grpcio>=1.59.0
+nats-py>=2.6.0
+cryptography>=41.0.0
+pydantic>=2.6.0
+redis>=5.0.0

{cap_sdk_python-2.0.16 → cap_sdk_python-2.0.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cap-sdk-python"
-version = "2.0.16"
+version = "2.0.18"
 description = "CAP (Cordum Agent Protocol) Python SDK"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -12,6 +12,9 @@ dependencies = [
   "protobuf>=4.25.0",
   "grpcio>=1.59.0",
   "nats-py>=2.6.0",
+  "cryptography>=41.0.0",
+  "pydantic>=2.6.0",
+  "redis>=5.0.0",
 ]
 
 [project.urls]

cap_sdk_python-2.0.18/tests/test_conformance.py

@@ -0,0 +1,109 @@
+import os
+import sys
+import unittest
+
+_repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+_sdk_root = os.path.join(_repo_root, "sdk", "python")
+
+# Avoid loading duplicate generated stubs from both /python and sdk/python/cap/pb.
+sys.path = [p for p in sys.path if not p.rstrip("/").endswith("python")]
+# Ensure the SDK package and generated modules are discoverable from repo root.
+sys.path.insert(0, _sdk_root)
+sys.path.append(os.path.join(_sdk_root, "cap", "pb"))
+
+from cap.pb.cordum.agent.v1 import buspacket_pb2
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+FIXTURE_DIR = os.path.join(_repo_root, "spec", "conformance", "fixtures")
+
+
+def load_packet(name: str) -> buspacket_pb2.BusPacket:
+    pkt = buspacket_pb2.BusPacket()
+    with open(os.path.join(FIXTURE_DIR, name), "rb") as handle:
+        pkt.ParseFromString(handle.read())
+    return pkt
+
+
+class TestConformanceFixtures(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        with open(os.path.join(FIXTURE_DIR, "public_key.pem"), "rb") as handle:
+            cls.public_key = serialization.load_pem_public_key(handle.read())
+
+    def _verify_signature(self, pkt: buspacket_pb2.BusPacket):
+        signature = pkt.signature
+        pkt.ClearField("signature")
+        unsigned = pkt.SerializeToString(deterministic=True)
+        pkt.signature = signature
+        self.public_key.verify(signature, unsigned, ec.ECDSA(hashes.SHA256()))
+
+    def _assert_common(self, pkt: buspacket_pb2.BusPacket, trace_id: str, sender_id: str):
+        self._verify_signature(pkt)
+        self.assertEqual(pkt.trace_id, trace_id)
+        self.assertEqual(pkt.sender_id, sender_id)
+        self.assertEqual(pkt.protocol_version, 1)
+        self.assertEqual(pkt.created_at.seconds, 1704164645)
+
+    def test_job_request_fixture(self):
+        pkt = load_packet("buspacket_job_request.bin")
+        self._assert_common(pkt, "trace-job-request", "client-1")
+        req = pkt.job_request
+        self.assertEqual(req.job_id, "job-req-1")
+        self.assertEqual(req.topic, "job.tools")
+        self.assertEqual(req.priority, 1)
+        self.assertEqual(req.context_ptr, "redis://ctx:job-req-1")
+        self.assertEqual(req.env["region"], "us-east-1")
+        self.assertEqual(req.env["sandbox"], "true")
+        self.assertEqual(req.labels["env"], "prod")
+        self.assertEqual(req.labels["team"], "platform")
+        self.assertEqual(req.meta.idempotency_key, "idem-123")
+        self.assertEqual(req.meta.labels["source"], "conformance")
+        self.assertEqual(req.compensation.topic, "job.rollback")
+        self.assertEqual(req.compensation.labels["rollback"], "true")
+
+    def test_job_result_fixture(self):
+        pkt = load_packet("buspacket_job_result.bin")
+        self._assert_common(pkt, "trace-job-result", "worker-1")
+        res = pkt.job_result
+        self.assertEqual(res.job_id, "job-res-1")
+        self.assertEqual(res.worker_id, "worker-1")
+        self.assertEqual(res.status, 10)
+        self.assertEqual(res.error_code, "E_TEMP")
+        self.assertEqual(len(res.artifact_ptrs), 2)
+
+    def test_heartbeat_fixture(self):
+        pkt = load_packet("buspacket_heartbeat.bin")
+        self._assert_common(pkt, "trace-heartbeat", "worker-1")
+        hb = pkt.heartbeat
+        self.assertEqual(hb.worker_id, "worker-1")
+        self.assertEqual(hb.pool, "job.tools")
+        self.assertEqual(hb.labels["zone"], "us-east-1a")
+        self.assertEqual(hb.progress_pct, 60)
+
+    def test_job_progress_fixture(self):
+        pkt = load_packet("buspacket_job_progress.bin")
+        self._assert_common(pkt, "trace-progress", "worker-1")
+        progress = pkt.job_progress
+        self.assertEqual(progress.job_id, "job-prog-1")
+        self.assertEqual(progress.percent, 50)
+        self.assertEqual(progress.status, 4)
+
+    def test_job_cancel_fixture(self):
+        pkt = load_packet("buspacket_job_cancel.bin")
+        self._assert_common(pkt, "trace-cancel", "scheduler-1")
+        cancel = pkt.job_cancel
+        self.assertEqual(cancel.job_id, "job-cancel-1")
+        self.assertEqual(cancel.requested_by, "user-7")
+
+    def test_alert_fixture(self):
+        pkt = load_packet("buspacket_alert.bin")
+        self._assert_common(pkt, "trace-alert", "scheduler-1")
+        alert = pkt.alert
+        self.assertEqual(alert.level, "WARN")
+        self.assertEqual(alert.component, "scheduler")
+
+
+if __name__ == "__main__":
+    unittest.main()

cap_sdk_python-2.0.18/tests/test_runtime.py

@@ -0,0 +1,130 @@
+import asyncio
+import json
+import unittest
+
+from pydantic import BaseModel
+
+from cap.runtime import Agent, InMemoryBlobStore
+from cap.pb.cordum.agent.v1 import buspacket_pb2, job_pb2
+
+
+class MockNATS:
+    def __init__(self):
+        self.subscriptions = {}
+        self.published = asyncio.Queue()
+
+    async def publish(self, subject, data):
+        await self.published.put((subject, data))
+
+    async def subscribe(self, subject, queue, cb):
+        self.subscriptions[subject] = cb
+
+    async def connect(self, servers, name):
+        return self
+
+    async def drain(self):
+        return None
+
+
+class InputModel(BaseModel):
+    prompt: str
+
+
+class OutputModel(BaseModel):
+    summary: str
+
+
+class TestRuntime(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.store = InMemoryBlobStore()
+        self.mock = MockNATS()
+
+    async def _send_job(self, job_id: str, topic: str, context_ptr: str):
+        req = job_pb2.JobRequest(job_id=job_id, topic=topic, context_ptr=context_ptr)
+        packet = buspacket_pb2.BusPacket()
+        packet.trace_id = "trace-1"
+        packet.sender_id = "client-1"
+        packet.protocol_version = 1
+        packet.job_request.CopyFrom(req)
+        await self.mock.subscriptions[topic](type("obj", (object,), {"data": packet.SerializeToString(deterministic=True)})())
+
+    async def test_runtime_success(self):
+        job_id = "job-1"
+        ctx_key = f"ctx:{job_id}"
+        await self.store.set(ctx_key, json.dumps({"prompt": "hello"}).encode("utf-8"))
+
+        agent = Agent(store=self.store, connect_fn=self.mock.connect, sender_id="worker-1")
+
+        @agent.job("job.test", input_model=InputModel, output_model=OutputModel)
+        async def handler(ctx, data: InputModel) -> OutputModel:
+            return OutputModel(summary=data.prompt.upper())
+
+        await agent.start()
+        await self._send_job(job_id, "job.test", f"redis://{ctx_key}")
+
+        subject, payload = await asyncio.wait_for(self.mock.published.get(), timeout=1)
+        self.assertEqual(subject, "sys.job.result")
+        result_packet = buspacket_pb2.BusPacket()
+        result_packet.ParseFromString(payload)
+        self.assertEqual(result_packet.job_result.status, job_pb2.JOB_STATUS_SUCCEEDED)
+
+        result_data = await self.store.get(f"res:{job_id}")
+        self.assertIsNotNone(result_data)
+        parsed = json.loads(result_data.decode("utf-8"))
+        self.assertEqual(parsed["summary"], "HELLO")
+
+        await agent.close()
+
+    async def test_runtime_input_validation_failure(self):
+        job_id = "job-2"
+        ctx_key = f"ctx:{job_id}"
+        await self.store.set(ctx_key, json.dumps({"wrong": "field"}).encode("utf-8"))
+
+        agent = Agent(store=self.store, connect_fn=self.mock.connect, sender_id="worker-2")
+
+        @agent.job("job.validate", input_model=InputModel, output_model=OutputModel)
+        async def handler(ctx, data: InputModel) -> OutputModel:
+            return OutputModel(summary=data.prompt)
+
+        await agent.start()
+        await self._send_job(job_id, "job.validate", f"redis://{ctx_key}")
+
+        subject, payload = await asyncio.wait_for(self.mock.published.get(), timeout=1)
+        self.assertEqual(subject, "sys.job.result")
+        result_packet = buspacket_pb2.BusPacket()
+        result_packet.ParseFromString(payload)
+        self.assertEqual(result_packet.job_result.status, job_pb2.JOB_STATUS_FAILED)
+        self.assertIn("input validation failed", result_packet.job_result.error_message)
+
+        await agent.close()
+
+    async def test_runtime_retries(self):
+        job_id = "job-3"
+        ctx_key = f"ctx:{job_id}"
+        await self.store.set(ctx_key, json.dumps({"prompt": "retry"}).encode("utf-8"))
+
+        agent = Agent(store=self.store, connect_fn=self.mock.connect, sender_id="worker-3", retries=1)
+        attempts = {"count": 0}
+
+        @agent.job("job.retry", input_model=InputModel, output_model=OutputModel)
+        async def handler(ctx, data: InputModel) -> OutputModel:
+            attempts["count"] += 1
+            if attempts["count"] == 1:
+                raise RuntimeError("boom")
+            return OutputModel(summary=data.prompt)
+
+        await agent.start()
+        await self._send_job(job_id, "job.retry", f"redis://{ctx_key}")
+
+        subject, payload = await asyncio.wait_for(self.mock.published.get(), timeout=1)
+        self.assertEqual(subject, "sys.job.result")
+        result_packet = buspacket_pb2.BusPacket()
+        result_packet.ParseFromString(payload)
+        self.assertEqual(result_packet.job_result.status, job_pb2.JOB_STATUS_SUCCEEDED)
+        self.assertEqual(attempts["count"], 2)
+
+        await agent.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

{cap_sdk_python-2.0.16 → cap_sdk_python-2.0.18}/tests/test_sdk.py

@@ -93,7 +93,7 @@ class TestSDK(unittest.TestCase):
             result_packet.ParseFromString(data)
             signature = result_packet.signature
             result_packet.ClearField("signature")
-            unsigned_data = result_packet.SerializeToString()
+            unsigned_data = result_packet.SerializeToString(deterministic=True)
             worker_key.public_key().verify(signature, unsigned_data, ec.ECDSA(hashes.SHA256()))
 
             worker_task.cancel()

cap_sdk_python-2.0.16/cap_sdk_python.egg-info/requires.txt

@@ -1,3 +0,0 @@
-protobuf>=4.25.0
-grpcio>=1.59.0
-nats-py>=2.6.0