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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cap-sdk-python
-Version: 2.5.2
+Version: 2.5.3
 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.3}/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.2 → cap_sdk_python-2.5.3}/cap/__init__.py

@@ -1,3 +1,9 @@
+"""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
 
@@ -27,12 +33,35 @@ 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 .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,
@@ -54,6 +83,11 @@ __all__ = [
     "BlobStore",
     "RedisBlobStore",
     "InMemoryBlobStore",
+    "Middleware",
+    "NextFn",
+    "logging_middleware",
+    "MetricsHook",
+    "NoopMetrics",
     "ValidationError",
     "validate_job_request",
     "validate_job_result",
@@ -67,4 +101,23 @@ __all__ = [
     "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.3}/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.3}/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.3/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.3/cap/metrics.py

@@ -0,0 +1,33 @@
+"""MetricsHook for CAP SDK observability.
+
+Implement the MetricsHook protocol to integrate with Prometheus,
+StatsD, OpenTelemetry, or any other metrics system.
+The default is NoopMetrics which has zero overhead.
+"""
+
+from typing import Protocol
+
+
+class MetricsHook(Protocol):
+    """Receives lifecycle events for observability."""
+
+    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: ...
+
+
+class NoopMetrics:
+    """No-op metrics implementation with zero overhead."""
+
+    def on_job_received(self, job_id: str, topic: str) -> None:
+        pass
+
+    def on_job_completed(self, job_id: str, duration_ms: int, status: str) -> None:
+        pass
+
+    def on_job_failed(self, job_id: str, error_msg: str) -> None:
+        pass
+
+    def on_heartbeat_sent(self, worker_id: str) -> None:
+        pass

cap_sdk_python-2.5.3/cap/middleware.py

@@ -0,0 +1,50 @@
+"""Middleware support for CAP agents and workers."""
+
+import logging
+import time
+from typing import Any, Awaitable, Callable
+
+from cap.runtime import Context
+
+# NextFn calls the next middleware or the terminal handler.
+NextFn = Callable[[Context, Any], Awaitable[Any]]
+
+# Middleware intercepts handler execution. Call ``next_fn(ctx, data)`` to
+# invoke the next middleware or the terminal handler. Middleware is applied
+# in FIFO order: the first registered middleware is the outermost.
+Middleware = Callable[[Context, Any, NextFn], Awaitable[Any]]
+
+
+def logging_middleware(logger: logging.Logger = None) -> "Middleware":
+    """Return a middleware that logs job ID, topic, and duration.
+
+    Args:
+        logger: Logger to use. Defaults to ``logging.getLogger("cap.middleware")``.
+    """
+    if logger is None:
+        logger = logging.getLogger("cap.middleware")
+
+    async def middleware(ctx: Context, data: Any, next_fn: NextFn) -> Any:
+        start = time.monotonic()
+        try:
+            result = await next_fn(ctx, data)
+            elapsed = int((time.monotonic() - start) * 1000)
+            logger.info(
+                "middleware: job=%s topic=%s duration=%dms ok",
+                ctx.job_id,
+                ctx.job.topic,
+                elapsed,
+            )
+            return result
+        except Exception as exc:
+            elapsed = int((time.monotonic() - start) * 1000)
+            logger.info(
+                "middleware: job=%s topic=%s duration=%dms error=%s",
+                ctx.job_id,
+                ctx.job.topic,
+                elapsed,
+                exc,
+            )
+            raise
+
+    return middleware