layr8 0.2.0__tar.gz

layr8-0.2.0/.claude/CLAUDE.md

@@ -0,0 +1,37 @@
+# Python SDK Principles
+
+## Public Repository
+
+This is a public repository. Every commit is visible to the world.
+
+### Before every commit, verify:
+
+- **No real API keys, passwords, or tokens.** Test keys must be obviously fake (e.g., contain `testkey` in the string).
+- **No internal infrastructure references.** No cloud account IDs, cluster names, or internal domain names. Only `*.localhost` and `example.com` are acceptable.
+- **No internal documentation links.** No references to private repos, internal wikis, or private channels.
+- **No customer data or PII.**
+
+### Acceptable
+
+- Local-dev test keys with obvious patterns (e.g., `alice_abcd1234_testkeyalicetestkeyali24`)
+- `*.localhost` URLs for local development
+- `did:web:*.localhost:*` test DIDs
+- Unit test sentinel values like `"test-api-key"`
+
+### Not acceptable
+
+- Keys that follow production format without obvious test markers
+- Internal service URLs (`.internal`, `.corp`, `.svc.cluster.local`)
+- `.env` files with real values (`.env.example` with placeholders is fine)
+
+## Testing
+
+- Run tests before every commit
+- Integration tests require a local dev environment with two cloud-nodes (alice-test, bob-test)
+
+## Conventions
+
+- Async/await with `asyncio`
+- `@dataclass` for structured types (`Credential`, `StoredCredential`, `VerifiedPresentation`)
+- Custom `aiohttp` resolver (`_LocalhostResolver`) for `*.localhost` resolution (RFC 6761)
+- Snake_case for all public API methods (e.g., `sign_credential`, `verify_presentation`)

layr8-0.2.0/.claude/skills/build-layr8-agent.md

@@ -0,0 +1,371 @@
+---
+name: build-layr8-agent
+description: Use when building a Python agent for the Layr8 platform. Covers the full SDK API — config, handlers, messaging, error handling, and DIDComm conventions.
+---
+
+# Building Layr8 Agents with the Python SDK
+
+Full documentation: https://docs.layr8.io/reference/python-sdk
+
+## Import
+
+```python
+from layr8 import Client, Config, Message, log_errors
+```
+
+Requires Python 3.11+. The SDK is fully async, built on `asyncio` and `websockets`.
+
+## Config
+
+```python
+client = Client(Config(
+    node_url="ws://mynode.localhost/plugin_socket/websocket",
+    api_key="my_api_key",
+    agent_did="did:web:mynode.localhost:my-agent",
+), log_errors())
+```
+
+The `Client` constructor takes two required arguments:
+1. `Config(...)` — connection configuration
+2. `on_error` — a `Callable[[SDKError], None]` that receives all SDK-level errors
+
+Use `log_errors()` for a convenient default that logs errors via `logging.getLogger("layr8")`.
+
+All Config fields fall back to environment variables if empty:
+- `node_url`  → `LAYR8_NODE_URL`
+- `api_key`   → `LAYR8_API_KEY`
+- `agent_did` → `LAYR8_AGENT_DID`
+
+`agent_did` is optional — if omitted, the node assigns an ephemeral DID on connect.
+
+## Lifecycle
+
+```
+Client(Config, on_error) → handle (register handlers) → connect → ... → close
+```
+
+Or using the async context manager:
+
+```
+Client(Config, on_error) → handle → async with client: ...
+```
+
+- `handle` must be called BEFORE `connect` — raises `AlreadyConnectedError` after.
+- `connect()` establishes WebSocket and joins the Phoenix Channel. Returns a coroutine.
+- `close()` sends `phx_leave` and shuts down gracefully. Returns a coroutine.
+- `did` (property) returns the agent's DID (explicit or node-assigned).
+- Supports `async with` context manager (`__aenter__`/`__aexit__`).
+
+## Registering Handlers
+
+### Decorator Syntax
+
+```python
+@client.handle("https://layr8.io/protocols/echo/1.0/request")
+async def echo(msg: Message) -> Message:
+    body = msg.unmarshal_body()
+    return Message(
+        type="https://layr8.io/protocols/echo/1.0/response",
+        body={"echo": body["message"]},
+    )
+```
+
+### Direct Call
+
+```python
+async def echo(msg: Message) -> Message:
+    body = msg.unmarshal_body()
+    return Message(
+        type="https://layr8.io/protocols/echo/1.0/response",
+        body={"echo": body["message"]},
+    )
+
+client.handle("https://layr8.io/protocols/echo/1.0/request", echo)
+```
+
+Handler return values:
+- `Message(...)` → send response to sender (auto-fills `id`, `from_`, `to`, `thread_id`)
+- `None` → no response (fire-and-forget inbound)
+- Raised exception → send DIDComm problem report to sender
+
+The protocol base URI is derived automatically from the message type
+(last path segment removed) and registered with the node on connect.
+
+## Sending Messages
+
+### Send (with server ack)
+
+By default, `send()` waits for the server to acknowledge receipt. If the server rejects the message, a `RuntimeError` is raised.
+
+```python
+await client.send(Message(
+    type="https://didcomm.org/basicmessage/2.0/message",
+    to=["did:web:other-node:agent"],
+    body={"content": "Hello!"},
+))
+```
+
+### Fire-and-forget
+
+To skip waiting for the server acknowledgment, pass `fire_and_forget=True`:
+
+```python
+await client.send(
+    Message(
+        type="https://didcomm.org/basicmessage/2.0/message",
+        to=["did:web:other-node:agent"],
+        body={"content": "Hello!"},
+    ),
+    fire_and_forget=True,
+)
+```
+
+### Request/Response
+
+```python
+resp = await client.request(
+    Message(
+        type="https://layr8.io/protocols/echo/1.0/request",
+        to=["did:web:other-node:agent"],
+        body={"message": "ping"},
+    ),
+    timeout=5.0,
+)
+
+body = resp.unmarshal_body()
+# resp is the correlated response (matched by thread ID)
+```
+
+## Message Structure
+
+```python
+@dataclass
+class Message:
+    id: str = ""                        # auto-generated if empty
+    type: str = ""                      # DIDComm message type URI
+    from_: str = ""                     # auto-filled with agent DID (wire: "from")
+    to: list[str] = field(default_factory=list)  # recipient DIDs
+    thread_id: str = ""                 # auto-generated for request (wire: "thid")
+    parent_thread_id: str = ""          # set via parent_thread param (wire: "pthid")
+    body: Any = None                    # serialized to JSON
+    context: MessageContext | None = None  # populated on inbound messages
+```
+
+**Important:** The `from` field is named `from_` because `from` is a Python reserved word. On the wire, it serializes as `"from"`.
+
+### Inbound Message Context
+
+```python
+if msg.context:
+    msg.context.authorized           # bool — node authorization result
+    msg.context.recipient            # str — recipient DID
+    msg.context.sender_credentials   # list[Credential] — each has .id, .name
+```
+
+### Unmarshaling Body
+
+```python
+# As a dict
+body = msg.unmarshal_body()
+
+# As a typed dataclass
+@dataclass
+class EchoRequest:
+    message: str
+
+body = msg.unmarshal_body(EchoRequest)
+print(body.message)  # typed attribute access
+```
+
+## Options
+
+### Manual Ack
+
+By default, messages are auto-acked before the handler runs.
+Use `manual_ack` to control ack timing (e.g., ack only after DB write):
+
+```python
+@client.handle(msg_type, manual_ack=True)
+async def handler(msg: Message) -> Message:
+    result = process(msg)
+    msg.ack()  # explicitly ack after processing
+    return Message(type=result_type, body=result)
+```
+
+### Parent Thread
+
+For nested thread correlation:
+
+```python
+resp = await client.request(msg, parent_thread="parent-thread-id", timeout=10.0)
+```
+
+## Error Handling
+
+### ErrorHandler (on_error callback)
+
+The `on_error` callback receives `SDKError` instances for all SDK-level errors:
+
+```python
+from layr8 import SDKError, ErrorKind
+
+def my_handler(err: SDKError) -> None:
+    print(f"[{err.kind.value}] {err.cause}")
+
+client = Client(Config(...), my_handler)
+```
+
+`ErrorKind` values:
+- `PARSE_FAILURE` — inbound message could not be parsed
+- `NO_HANDLER` — no handler registered for the message type
+- `HANDLER_EXCEPTION` — a handler raised an exception
+- `SERVER_REJECT` — the server rejected a sent message
+- `TRANSPORT_WRITE` — failed to write to WebSocket
+
+### Problem Reports
+
+When a remote handler raises, `request` raises `ProblemReportError`:
+
+```python
+from layr8 import ProblemReportError
+
+try:
+    resp = await client.request(msg)
+except ProblemReportError as e:
+    print(f"remote error [{e.code}]: {e.comment}")
+```
+
+### Error Classes
+
+- `NotConnectedError` — `send`/`request` called before `connect`
+- `AlreadyConnectedError` — `handle` called after `connect`
+- `ClientClosedError` — `connect` called after `close`
+- `Layr8ConnectionError` — failed to connect to node (`.url`, `.reason`)
+
+```python
+from layr8.errors import Layr8ConnectionError
+
+try:
+    await client.connect()
+except Layr8ConnectionError as e:
+    print(f"failed to connect to {e.url}: {e.reason}")
+```
+
+Note: `request()` raises `asyncio.TimeoutError` on timeout (uses `asyncio.wait_for`).
+
+## Connection Resilience
+
+The SDK automatically reconnects when the WebSocket connection drops (node restart, network interruption). Reconnection uses exponential backoff (1s → 2s → 4s → ... → 30s max).
+
+During reconnection:
+- `send()`, `request()`, and other operations raise `NotConnectedError` immediately — no message queuing
+- `close()` stops the reconnect loop
+
+```python
+@client.on_disconnect
+def handle_disconnect(err: Exception):
+    print(f"connection lost: {err}")
+
+@client.on_reconnect
+def handle_reconnect():
+    print("reconnected")
+```
+
+`on_disconnect` fires only on unexpected drops, not on `close()`.
+
+## DID and Protocol Conventions
+
+### DID Format
+
+```
+did:web:{node-domain}:{agent-path}
+```
+
+Examples:
+- `did:web:alice-test.localhost:my-agent`
+- `did:web:earth.node.layr8.org:echo-service`
+
+### Protocol URI Format
+
+```
+https://layr8.io/protocols/{name}/{version}/{message-type}
+```
+
+The base URI (without the last segment) is the protocol identifier.
+Example: `https://layr8.io/protocols/echo/1.0/request` → protocol `https://layr8.io/protocols/echo/1.0`
+
+### Standard Protocols
+
+- Basic message: `https://didcomm.org/basicmessage/2.0/message`
+- Problem report: `https://didcomm.org/report-problem/2.0/problem-report`
+
+## Complete Example: Echo Agent
+
+```python
+import asyncio
+from layr8 import Client, Config, Message, log_errors
+
+ECHO_REQUEST = "https://layr8.io/protocols/echo/1.0/request"
+ECHO_RESPONSE = "https://layr8.io/protocols/echo/1.0/response"
+
+client = Client(Config(), log_errors())
+
+@client.handle(ECHO_REQUEST)
+async def echo(msg: Message) -> Message:
+    body = msg.unmarshal_body()
+    return Message(
+        type=ECHO_RESPONSE,
+        body={"echo": body["message"]},
+    )
+
+async def main():
+    async with client:
+        print(f"echo agent running as {client.did}")
+        await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+## Complete Example: Request/Response Client
+
+```python
+import asyncio
+from layr8 import Client, Config, Message, ProblemReportError, log_errors
+
+ECHO_REQUEST = "https://layr8.io/protocols/echo/1.0/request"
+
+client = Client(Config(), log_errors())
+
+# Must register the protocol even if not handling inbound
+@client.handle(ECHO_REQUEST)
+async def noop(msg: Message) -> None:
+    return None
+
+async def main():
+    async with client:
+        try:
+            resp = await client.request(
+                Message(
+                    type=ECHO_REQUEST,
+                    to=["did:web:other-node:echo-agent"],
+                    body={"message": "Hello!"},
+                ),
+                timeout=5.0,
+            )
+
+            body = resp.unmarshal_body()
+            print(f"response: {body['echo']}")
+        except ProblemReportError as e:
+            print(f"remote error [{e.code}]: {e.comment}")
+        except asyncio.TimeoutError:
+            print("request timed out")
+
+asyncio.run(main())
+```
+
+## More Examples
+
+See the `examples/` directory in the SDK repo for complete working agents:
+- `examples/echo_agent.py` — minimal echo service
+- `examples/chat.py` — interactive chat client
+- `examples/durable_handler.py` — persist-then-ack with JSON-lines

layr8-0.2.0/.github/workflows/ci.yaml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: pytest -v
+
+  compat-unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install SDK and compat deps
+        run: |
+          pip install -e .
+          pip install -e "compat/[test]"
+
+      - name: Compat unit tests
+        run: cd compat && pytest tests/ -v --ignore=tests/conftest.py -k "not layer1"

layr8-0.2.0/.github/workflows/release.yaml

@@ -0,0 +1,120 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: pytest -v
+
+  compat-unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install SDK and compat deps
+        run: |
+          pip install -e .
+          pip install -e "compat/[test]"
+
+      - name: Compat unit tests
+        run: cd compat && pytest tests/ -v --ignore=tests/conftest.py -k "not layer1"
+
+  validate-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Validate tag matches pyproject.toml
+        id: check
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          TOML_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$TOML_VERSION" ]; then
+            echo "::error::Tag $TAG_VERSION != pyproject.toml $TOML_VERSION"
+            exit 1
+          fi
+          echo "version=$TAG_VERSION" >> "$GITHUB_OUTPUT"
+
+  publish-pypi:
+    needs: [test, compat-unit, validate-version]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: pip install build && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-compat-image:
+    needs: [publish-pypi, validate-version]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push compat image
+        run: |
+          VERSION=${{ needs.validate-version.outputs.version }}
+          IMAGE=ghcr.io/layr8/python-sdk/compat
+          docker build \
+            --build-arg SDK_VERSION=$VERSION \
+            -t $IMAGE:$VERSION \
+            -f compat/Dockerfile compat/
+          docker push $IMAGE:$VERSION
+
+  # compat-gate:
+  #   needs: [publish-compat-image, validate-version]
+  #   uses: layr8/compat-suite/.github/workflows/gate.yml@main
+  #   with:
+  #     sdk: python
+  #     version: ${{ needs.validate-version.outputs.version }}

layr8-0.2.0/.gitignore

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

layr8-0.2.0/CONTEXT.md

@@ -0,0 +1,17 @@
+# Context — Layr8 Python SDK
+
+## Ubiquitous Language
+
+| Term | Definition |
+|---|---|
+| **Agent** | A software process that connects to a cloud-node and exchanges DIDComm v2 messages. An agent is identified by a DID. |
+| **Cloud-node** | A Layr8 infrastructure component that routes DIDComm messages between agents. Agents connect via WebSocket using the Phoenix Channel V2 protocol. |
+| **DID** | Decentralized Identifier — a globally unique agent identity (e.g., `did:web:myorg:my-agent`). May be configured explicitly or assigned by the cloud-node on connect. |
+| **Handler** | An async function registered for a specific DIDComm message type. Receives a `Message`, returns a response `Message`, `None`, or `PASS`. |
+| **PASS** | A sentinel value returned by a handler to decline a message — signals to the cloud-node that this agent does not handle this message type. |
+| **Scenario** | A compat-suite test case. Each scenario is a pair of async functions (`run_receiver`, `run_sender`) that exercise a specific SDK behavior against a cloud-node. |
+| **Compat image** | A Docker image (`ghcr.io/layr8/python-sdk/compat:{version}`) that packages the scenario code and CLI adapter. Consumed by the compat-suite orchestrator. |
+| **Ready signal** | A JSON line (`{"status":"ready","did":"..."}`) printed to stdout by a receiver process after connecting and registering handlers. The compat-suite orchestrator waits for this before launching the sender. |
+| **Layer 1** | Pytest + testcontainers adapter — runs scenarios against real cloud-node Docker containers. |
+| **Layer 2** | CLI adapter — implements the compat-suite orchestrator's interface (`--mode`, `--scenario`, `--node`, `--did`). |
+| **Compat-suite orchestrator** | A separate repo (`layr8/compat-suite`) that pairs SDK compat images across languages and cloud-node versions, runs test matrices, and produces compatibility reports. |

layr8-0.2.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: layr8
+Version: 0.2.0
+Summary: Layr8 DIDComm Agent SDK for Python
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/plain
+
+Layr8 DIDComm Agent SDK for Python