cap-sdk-python 2.5.2__tar.gz → 2.5.4__tar.gz

{cap_sdk_python-2.5.2 → cap_sdk_python-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cap-sdk-python
-Version: 2.5.2
+Version: 2.5.4
 Summary: CAP (Cordum Agent Protocol) Python SDK
 Author-email: Cordum <eng@cordum.io>
 License-Expression: Apache-2.0
@@ -16,6 +16,8 @@ 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
+Provides-Extra: dev
+Requires-Dist: pdoc>=14.0; extra == "dev"
 
 # CAP Python SDK
 
@@ -97,6 +99,27 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 
 Swap out `cap.bus` if you need a different transport.
 
+## Testing
+
+The `cap.testing` module lets you test handlers without running NATS or Redis.
+
+```python
+from cap.testing import run_handler
+from cap.pb.cordum.agent.v1 import job_pb2
+
+async def test_echo():
+    result = await run_handler(
+        lambda ctx, data: {"echo": data["prompt"]},
+        {"prompt": "hello"},
+        topic="job.echo",
+    )
+    assert result.status == job_pb2.JOB_STATUS_SUCCEEDED
+```
+
+- `run_handler(handler, input, **options)` — runs a single handler invocation and returns the `JobResult`.
+- `create_test_agent(**options)` — returns `(agent, mock_nats, store)` pre-wired with `MockNATS` + `InMemoryBlobStore`.
+- `MockNATS` — in-memory NATS mock for custom test setups.
+
 ## Runtime (High-Level SDK)
 The runtime hides NATS/Redis plumbing and gives you typed handlers.
 
@@ -120,6 +143,92 @@ async def summarize(ctx: Context, data: Input) -> Output:
 asyncio.run(agent.run())
 ```
 
+### Middleware
+
+Add cross-cutting concerns (logging, auth, metrics) without modifying handlers:
+
+```python
+from cap.middleware import logging_middleware
+
+# Built-in logging middleware
+agent.use(logging_middleware())
+
+# Custom middleware
+async def timing(ctx, data, next_fn):
+    import time
+    start = time.monotonic()
+    result = await next_fn(ctx, data)
+    elapsed = time.monotonic() - start
+    print(f"job {ctx.job_id} took {elapsed:.3f}s")
+    return result
+
+agent.use(timing)
+```
+
+Middleware executes in registration order (FIFO). Each can inspect context,
+measure timing, or short-circuit by returning without calling `next_fn`.
+
 ### Environment
 - `NATS_URL` (default `nats://127.0.0.1:4222`)
 - `REDIS_URL` (default `redis://127.0.0.1:6379/0`)
+
+## Generating API Docs
+
+Generate HTML API reference locally using [pdoc](https://pdoc.dev/):
+
+```bash
+pip install cap-sdk-python[dev]
+pdoc ./cap --output-dir docs
+```
+
+Output is written to `docs/` (gitignored). Open `docs/index.html` to browse.
+
+## Observability
+
+### Structured Logging
+The runtime Agent and Worker use `logging.Logger` (stdlib) for structured logging. All log calls include contextual fields (`job_id`, `trace_id`, `topic`, `sender_id`). Pass a custom logger or leave as default:
+
+```python
+import logging
+from cap.runtime import Agent
+
+logger = logging.getLogger("my-agent")
+logger.setLevel(logging.DEBUG)
+agent = Agent(logger=logger)
+```
+
+### MetricsHook
+Implement the `MetricsHook` protocol to integrate with Prometheus, OpenTelemetry, or any metrics system:
+
+```python
+from cap.metrics import MetricsHook
+
+class MetricsHook(Protocol):
+    def on_job_received(self, job_id: str, topic: str) -> None: ...
+    def on_job_completed(self, job_id: str, duration_ms: int, status: str) -> None: ...
+    def on_job_failed(self, job_id: str, error_msg: str) -> None: ...
+    def on_heartbeat_sent(self, worker_id: str) -> None: ...
+```
+
+The default is `NoopMetrics` (zero overhead). Example Prometheus integration:
+
+```python
+from cap.runtime import Agent
+
+class PromMetrics:
+    def on_job_received(self, job_id, topic):
+        jobs_received.labels(topic=topic).inc()
+
+    def on_job_completed(self, job_id, duration_ms, status):
+        job_duration.labels(status=status).observe(duration_ms)
+
+    def on_job_failed(self, job_id, error_msg):
+        jobs_failed.inc()
+
+    def on_heartbeat_sent(self, worker_id):
+        pass
+
+agent = Agent(metrics=PromMetrics())
+```
+
+The `trace_id` is propagated through all log and metrics calls for distributed tracing correlation.

{cap_sdk_python-2.5.2 → cap_sdk_python-2.5.4}/README.md

@@ -78,6 +78,27 @@ Asyncio-first SDK with NATS helpers for CAP workers and clients.
 
 Swap out `cap.bus` if you need a different transport.
 
+## Testing
+
+The `cap.testing` module lets you test handlers without running NATS or Redis.
+
+```python
+from cap.testing import run_handler
+from cap.pb.cordum.agent.v1 import job_pb2
+
+async def test_echo():
+    result = await run_handler(
+        lambda ctx, data: {"echo": data["prompt"]},
+        {"prompt": "hello"},
+        topic="job.echo",
+    )
+    assert result.status == job_pb2.JOB_STATUS_SUCCEEDED
+```
+
+- `run_handler(handler, input, **options)` — runs a single handler invocation and returns the `JobResult`.
+- `create_test_agent(**options)` — returns `(agent, mock_nats, store)` pre-wired with `MockNATS` + `InMemoryBlobStore`.
+- `MockNATS` — in-memory NATS mock for custom test setups.
+
 ## Runtime (High-Level SDK)
 The runtime hides NATS/Redis plumbing and gives you typed handlers.
 
@@ -101,6 +122,92 @@ async def summarize(ctx: Context, data: Input) -> Output:
 asyncio.run(agent.run())
 ```
 
+### Middleware
+
+Add cross-cutting concerns (logging, auth, metrics) without modifying handlers:
+
+```python
+from cap.middleware import logging_middleware
+
+# Built-in logging middleware
+agent.use(logging_middleware())
+
+# Custom middleware
+async def timing(ctx, data, next_fn):
+    import time
+    start = time.monotonic()
+    result = await next_fn(ctx, data)
+    elapsed = time.monotonic() - start
+    print(f"job {ctx.job_id} took {elapsed:.3f}s")
+    return result
+
+agent.use(timing)
+```
+
+Middleware executes in registration order (FIFO). Each can inspect context,
+measure timing, or short-circuit by returning without calling `next_fn`.
+
 ### Environment
 - `NATS_URL` (default `nats://127.0.0.1:4222`)
 - `REDIS_URL` (default `redis://127.0.0.1:6379/0`)
+
+## Generating API Docs
+
+Generate HTML API reference locally using [pdoc](https://pdoc.dev/):
+
+```bash
+pip install cap-sdk-python[dev]
+pdoc ./cap --output-dir docs
+```
+
+Output is written to `docs/` (gitignored). Open `docs/index.html` to browse.
+
+## Observability
+
+### Structured Logging
+The runtime Agent and Worker use `logging.Logger` (stdlib) for structured logging. All log calls include contextual fields (`job_id`, `trace_id`, `topic`, `sender_id`). Pass a custom logger or leave as default:
+
+```python
+import logging
+from cap.runtime import Agent
+
+logger = logging.getLogger("my-agent")
+logger.setLevel(logging.DEBUG)
+agent = Agent(logger=logger)
+```
+
+### MetricsHook
+Implement the `MetricsHook` protocol to integrate with Prometheus, OpenTelemetry, or any metrics system:
+
+```python
+from cap.metrics import MetricsHook
+
+class MetricsHook(Protocol):
+    def on_job_received(self, job_id: str, topic: str) -> None: ...
+    def on_job_completed(self, job_id: str, duration_ms: int, status: str) -> None: ...
+    def on_job_failed(self, job_id: str, error_msg: str) -> None: ...
+    def on_heartbeat_sent(self, worker_id: str) -> None: ...
+```
+
+The default is `NoopMetrics` (zero overhead). Example Prometheus integration:
+
+```python
+from cap.runtime import Agent
+
+class PromMetrics:
+    def on_job_received(self, job_id, topic):
+        jobs_received.labels(topic=topic).inc()
+
+    def on_job_completed(self, job_id, duration_ms, status):
+        job_duration.labels(status=status).observe(duration_ms)
+
+    def on_job_failed(self, job_id, error_msg):
+        jobs_failed.inc()
+
+    def on_heartbeat_sent(self, worker_id):
+        pass
+
+agent = Agent(metrics=PromMetrics())
+```
+
+The `trace_id` is propagated through all log and metrics calls for distributed tracing correlation.

cap_sdk_python-2.5.4/cap/__init__.py

@@ -0,0 +1,145 @@
+"""CAP (Cordum Agent Protocol) SDK for Python.
+
+Provides helpers for submitting jobs, running workers, and building
+high-level agents on the CAP bus.
+"""
+
+import sys
+import types
+
+try:
+    from google.protobuf import runtime_version as _runtime_version  # noqa: F401
+except Exception:
+    try:
+        import google.protobuf as _protobuf
+    except Exception:
+        _protobuf = None
+
+    _shim = types.SimpleNamespace()
+
+    class _Domain:
+        PUBLIC = 0
+
+    def _validate(*_args, **_kwargs):
+        return None
+
+    _shim.Domain = _Domain
+    _shim.ValidateProtobufRuntimeVersion = _validate
+    sys.modules["google.protobuf.runtime_version"] = _shim
+    if _protobuf is not None:
+        setattr(_protobuf, "runtime_version", _shim)
+
+from .client import submit_job
+from .worker import run_worker
+from .bus import connect_nats
+from .runtime import Agent, Context, BlobStore, RedisBlobStore, InMemoryBlobStore
+from .middleware import Middleware, NextFn, logging_middleware
+from .metrics import MetricsHook, NoopMetrics
+from .heartbeat import (
+    heartbeat_payload,
+    heartbeat_payload_with_memory,
+    heartbeat_payload_with_progress,
+    emit_heartbeat,
+    heartbeat_loop,
+)
+from .progress import (
+    progress_payload,
+    cancel_payload,
+    emit_progress,
+    emit_cancel,
+)
+from .validate import (
+    ValidationError,
+    validate_job_request,
+    validate_job_result,
+    validate_bus_packet,
+)
+from .errors import (
+    CAPError,
+    VersionMismatchError,
+    MalformedPacketError,
+    UnknownPayloadError,
+    SignatureInvalidError,
+    SignatureMissingError,
+    JobTimeoutError,
+    ResourceExhaustedError,
+    PermissionDeniedError,
+    InvalidInputError,
+    JobNotFoundError,
+    DuplicateJobError,
+    WorkerUnavailableError,
+    SafetyDeniedError,
+    PolicyViolationError,
+    RiskTagBlockedError,
+    PublishFailedError,
+    SubscribeFailedError,
+    ConnectionLostError,
+)
+from .subjects import (
+    SUBJECT_SUBMIT,
+    SUBJECT_RESULT,
+    SUBJECT_HEARTBEAT,
+    SUBJECT_ALERT,
+    SUBJECT_PROGRESS,
+    SUBJECT_CANCEL,
+    SUBJECT_DLQ,
+    SUBJECT_WORKFLOW_EVENT,
+    SUBJECT_HANDSHAKE,
+)
+
+__all__ = [
+    "submit_job",
+    "run_worker",
+    "connect_nats",
+    "Agent",
+    "Context",
+    "BlobStore",
+    "RedisBlobStore",
+    "InMemoryBlobStore",
+    "Middleware",
+    "NextFn",
+    "logging_middleware",
+    "MetricsHook",
+    "NoopMetrics",
+    "heartbeat_payload",
+    "heartbeat_payload_with_memory",
+    "heartbeat_payload_with_progress",
+    "emit_heartbeat",
+    "heartbeat_loop",
+    "progress_payload",
+    "cancel_payload",
+    "emit_progress",
+    "emit_cancel",
+    "ValidationError",
+    "validate_job_request",
+    "validate_job_result",
+    "validate_bus_packet",
+    "SUBJECT_SUBMIT",
+    "SUBJECT_RESULT",
+    "SUBJECT_HEARTBEAT",
+    "SUBJECT_ALERT",
+    "SUBJECT_PROGRESS",
+    "SUBJECT_CANCEL",
+    "SUBJECT_DLQ",
+    "SUBJECT_WORKFLOW_EVENT",
+    "SUBJECT_HANDSHAKE",
+    "CAPError",
+    "VersionMismatchError",
+    "MalformedPacketError",
+    "UnknownPayloadError",
+    "SignatureInvalidError",
+    "SignatureMissingError",
+    "JobTimeoutError",
+    "ResourceExhaustedError",
+    "PermissionDeniedError",
+    "InvalidInputError",
+    "JobNotFoundError",
+    "DuplicateJobError",
+    "WorkerUnavailableError",
+    "SafetyDeniedError",
+    "PolicyViolationError",
+    "RiskTagBlockedError",
+    "PublishFailedError",
+    "SubscribeFailedError",
+    "ConnectionLostError",
+]

{cap_sdk_python-2.5.2 → cap_sdk_python-2.5.4}/cap/bus.py

@@ -3,6 +3,8 @@ from typing import Optional
 
 
 class NATSConfig:
+    """NATS connection configuration."""
+
     def __init__(
         self,
         url: str,
@@ -19,6 +21,17 @@ class NATSConfig:
 
 
 async def connect_nats(cfg: NATSConfig):
+    """Open a NATS connection using the provided configuration.
+
+    Args:
+        cfg: Connection settings.
+
+    Returns:
+        A connected NATS client.
+
+    Raises:
+        RuntimeError: If the ``nats-py`` package is not installed.
+    """
     try:
         import nats  # type: ignore
     except ImportError as exc:

{cap_sdk_python-2.5.2 → cap_sdk_python-2.5.4}/cap/client.py

@@ -17,6 +17,15 @@ async def submit_job(
     sender_id: str,
     private_key: Optional[ec.EllipticCurvePrivateKey] = None,
 ):
+    """Publish a JobRequest onto the CAP submit subject.
+
+    Args:
+        nc: An active NATS connection.
+        job_request: A protobuf JobRequest message.
+        trace_id: Distributed trace identifier propagated through the bus.
+        sender_id: Identity of the sender (used in the BusPacket envelope).
+        private_key: Optional ECDSA private key for signing the packet.
+    """
     ts = timestamp_pb2.Timestamp()
     ts.GetCurrentTime()
     packet = buspacket_pb2.BusPacket()

cap_sdk_python-2.5.4/cap/errors.py

@@ -0,0 +1,116 @@
+"""Typed error classes matching the CAP ErrorCode registry.
+
+See spec/13-error-codes.md for the full taxonomy.
+"""
+
+
+class CAPError(Exception):
+    """Base class for all CAP protocol errors."""
+
+    code: str = "ERROR_CODE_UNSPECIFIED"
+    numeric_code: int = 0
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+# Protocol errors (100-199)
+
+
+class VersionMismatchError(CAPError):
+    code = "ERROR_CODE_PROTOCOL_VERSION_MISMATCH"
+    numeric_code = 100
+
+
+class MalformedPacketError(CAPError):
+    code = "ERROR_CODE_PROTOCOL_MALFORMED_PACKET"
+    numeric_code = 101
+
+
+class UnknownPayloadError(CAPError):
+    code = "ERROR_CODE_PROTOCOL_UNKNOWN_PAYLOAD"
+    numeric_code = 102
+
+
+class SignatureInvalidError(CAPError):
+    code = "ERROR_CODE_PROTOCOL_SIGNATURE_INVALID"
+    numeric_code = 103
+
+
+class SignatureMissingError(CAPError):
+    code = "ERROR_CODE_PROTOCOL_SIGNATURE_MISSING"
+    numeric_code = 104
+
+
+# Job errors (200-299)
+
+
+class JobTimeoutError(CAPError):
+    code = "ERROR_CODE_JOB_TIMEOUT"
+    numeric_code = 200
+
+
+class ResourceExhaustedError(CAPError):
+    code = "ERROR_CODE_JOB_RESOURCE_EXHAUSTED"
+    numeric_code = 201
+
+
+class PermissionDeniedError(CAPError):
+    code = "ERROR_CODE_JOB_PERMISSION_DENIED"
+    numeric_code = 202
+
+
+class InvalidInputError(CAPError):
+    code = "ERROR_CODE_JOB_INVALID_INPUT"
+    numeric_code = 203
+
+
+class JobNotFoundError(CAPError):
+    code = "ERROR_CODE_JOB_NOT_FOUND"
+    numeric_code = 204
+
+
+class DuplicateJobError(CAPError):
+    code = "ERROR_CODE_JOB_DUPLICATE"
+    numeric_code = 205
+
+
+class WorkerUnavailableError(CAPError):
+    code = "ERROR_CODE_JOB_WORKER_UNAVAILABLE"
+    numeric_code = 206
+
+
+# Safety errors (300-399)
+
+
+class SafetyDeniedError(CAPError):
+    code = "ERROR_CODE_SAFETY_DENIED"
+    numeric_code = 300
+
+
+class PolicyViolationError(CAPError):
+    code = "ERROR_CODE_SAFETY_POLICY_VIOLATION"
+    numeric_code = 301
+
+
+class RiskTagBlockedError(CAPError):
+    code = "ERROR_CODE_SAFETY_RISK_TAG_BLOCKED"
+    numeric_code = 302
+
+
+# Transport errors (400-499)
+
+
+class PublishFailedError(CAPError):
+    code = "ERROR_CODE_TRANSPORT_PUBLISH_FAILED"
+    numeric_code = 400
+
+
+class SubscribeFailedError(CAPError):
+    code = "ERROR_CODE_TRANSPORT_SUBSCRIBE_FAILED"
+    numeric_code = 401
+
+
+class ConnectionLostError(CAPError):
+    code = "ERROR_CODE_TRANSPORT_CONNECTION_LOST"
+    numeric_code = 402

cap_sdk_python-2.5.4/cap/heartbeat.py

@@ -0,0 +1,153 @@
+"""Heartbeat helpers for CAP Python SDK.
+
+These helpers build and publish heartbeat BusPacket envelopes.
+"""
+
+import asyncio
+import logging
+from typing import Callable, Optional
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from google.protobuf import timestamp_pb2
+
+from cap.client import DEFAULT_PROTOCOL_VERSION
+from cap.metrics import MetricsHook
+from cap.pb.cordum.agent.v1 import buspacket_pb2, heartbeat_pb2
+from cap.subjects import SUBJECT_HEARTBEAT
+
+_logger = logging.getLogger("cap.heartbeat")
+
+
+def heartbeat_payload(
+    worker_id: str,
+    pool: str,
+    active_jobs: int,
+    max_parallel: int,
+    cpu_load: float,
+) -> bytes:
+    """Build a heartbeat payload with CPU utilization only."""
+    return heartbeat_payload_with_progress(
+        worker_id=worker_id,
+        pool=pool,
+        active_jobs=active_jobs,
+        max_parallel=max_parallel,
+        cpu_load=cpu_load,
+    )
+
+
+def heartbeat_payload_with_memory(
+    worker_id: str,
+    pool: str,
+    active_jobs: int,
+    max_parallel: int,
+    cpu_load: float,
+    memory_load: float,
+) -> bytes:
+    """Build a heartbeat payload including memory utilization."""
+    return heartbeat_payload_with_progress(
+        worker_id=worker_id,
+        pool=pool,
+        active_jobs=active_jobs,
+        max_parallel=max_parallel,
+        cpu_load=cpu_load,
+        memory_load=memory_load,
+    )
+
+
+def heartbeat_payload_with_progress(
+    worker_id: str,
+    pool: str,
+    active_jobs: int,
+    max_parallel: int,
+    cpu_load: float,
+    memory_load: float = 0.0,
+    progress_pct: int = 0,
+    last_memo: str = "",
+) -> bytes:
+    """Build a heartbeat payload including optional progress fields."""
+    ts = timestamp_pb2.Timestamp()
+    ts.GetCurrentTime()
+
+    packet = buspacket_pb2.BusPacket()
+    packet.sender_id = worker_id
+    packet.protocol_version = DEFAULT_PROTOCOL_VERSION
+    packet.created_at.CopyFrom(ts)
+    packet.heartbeat.CopyFrom(
+        heartbeat_pb2.Heartbeat(
+            worker_id=worker_id,
+            pool=pool,
+            active_jobs=active_jobs,
+            max_parallel_jobs=max_parallel,
+            cpu_load=cpu_load,
+            memory_load=memory_load,
+            progress_pct=progress_pct,
+            last_memo=last_memo,
+        )
+    )
+    return packet.SerializeToString(deterministic=True)
+
+
+async def emit_heartbeat(
+    nc,
+    payload: bytes,
+    private_key: Optional[ec.EllipticCurvePrivateKey] = None,
+) -> None:
+    """Publish one heartbeat packet to the heartbeat subject."""
+    data = payload
+    if private_key is not None:
+        packet = buspacket_pb2.BusPacket()
+        packet.ParseFromString(payload)
+        packet.ClearField("signature")
+        unsigned_data = packet.SerializeToString(deterministic=True)
+        packet.signature = private_key.sign(unsigned_data, ec.ECDSA(hashes.SHA256()))
+        data = packet.SerializeToString(deterministic=True)
+
+    await nc.publish(SUBJECT_HEARTBEAT, data)
+
+
+async def heartbeat_loop(
+    nc,
+    payload_fn: Callable[[], bytes],
+    interval: float = 5.0,
+    private_key: Optional[ec.EllipticCurvePrivateKey] = None,
+    metrics: MetricsHook | None = None,
+    cancel_event: asyncio.Event | None = None,
+) -> None:
+    """Emit heartbeat packets periodically until cancelled."""
+    sleep_interval = max(0.0, interval)
+
+    while True:
+        if cancel_event is not None and cancel_event.is_set():
+            return
+
+        if cancel_event is None:
+            await asyncio.sleep(sleep_interval)
+        else:
+            sleep_task = asyncio.create_task(asyncio.sleep(sleep_interval))
+            cancel_task = asyncio.create_task(cancel_event.wait())
+            done, pending = await asyncio.wait(
+                {sleep_task, cancel_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for task in pending:
+                task.cancel()
+            if pending:
+                await asyncio.gather(*pending, return_exceptions=True)
+
+            if cancel_task in done and cancel_event.is_set():
+                return
+
+        try:
+            payload = payload_fn()
+            await emit_heartbeat(nc=nc, payload=payload, private_key=private_key)
+            if metrics is not None:
+                packet = buspacket_pb2.BusPacket()
+                packet.ParseFromString(payload)
+                worker_id = packet.heartbeat.worker_id or packet.sender_id
+                metrics.on_heartbeat_sent(worker_id)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            _logger.exception("heartbeat emission failed")