feat: implement Python SDK

Author: nkavian

README.md

@@ -3,46 +3,193 @@
 [![CI](https://github.com/offering-protocol/odp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/offering-protocol/odp-python/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
 [![PyPI](https://img.shields.io/pypi/v/offering-protocol)](https://pypi.org/project/offering-protocol/)
+[![Codecov](https://codecov.io/gh/offering-protocol/odp-python/graph/badge.svg)](https://codecov.io/gh/offering-protocol/odp-python)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
 Official Python software development kit for the
 [Offering Discovery Protocol](https://www.offeringprotocol.org/), the open protocol for discovering
 Services and navigating their Offerings.
 
-ODP separates Service discovery from catalog discovery. An Agent searches the canonical Directory
-for candidate Services, inspects each Service's live ODP document, and then navigates or searches
-that Service's Collections and Offerings.
+ODP separates two levels of discovery:
+
+1. An Agent searches the canonical Directory for Services.
+2. The Agent inspects a Service's live ODP document and navigates that Service's Collections and
+   Offerings.
+
+The Directory does not copy every Service catalog. Catalog searches go directly to each Service.
 
 ## Installation
 
 ```sh
 python -m pip install offering-protocol
 ```
 
-The distribution provides one typed Python package with modules for each integration role:
+Python 3.11 or newer is required. The distribution provides one typed package with modules for each
+integration role:
+
+| Goal | Module |
+| --- | --- |
+| Parse protocol models and validate normative documents | `offering_protocol.core` |
+| Search the canonical production or sandbox Directory | `offering_protocol.directory` |
+| Inspect Services and navigate their catalogs | `offering_protocol.agent` |
+| Publish an ODP Service | `offering_protocol.service` |
+
+## Search the Directory
+
+`DirectoryClient` uses the one canonical production Directory. Select `Environment.SANDBOX` when
+working against InFlow's sandbox.
+
+```python
+import asyncio
+
+from offering_protocol.directory import DirectoryClient, SearchRequest, ServiceFilters
+
+
+async def main() -> None:
+    async with DirectoryClient() as directory:
+        page = await directory.search(
+            SearchRequest(
+                query="indoor plants",
+                filters=ServiceFilters(keywords=["plants"]),
+                limit=20,
+            )
+        )
+        for service in page.items:
+            print(service.name, service.service_origin)
+
+        if page.next:
+            next_page = await directory.continue_search(page.next)
+            print(f"Next page contains {len(next_page.items)} Services")
+
+
+asyncio.run(main())
+```
+
+Use `search_services()` when the application wants bounded automatic pagination. Use `suggest()` to
+discover keyword completions supported by the Directory.
+
+## Inspect and navigate a Service
+
+`ServiceClient` checks the Service document before calling an operation. Calling an operation the
+Service does not advertise raises `UnsupportedOperationError` before a catalog request is sent.
+
+```python
+import asyncio
+
+from offering_protocol.agent import ServiceClient
+from offering_protocol.core import OfferingSearchRequest, Representation
+
+
+async def main() -> None:
+    async with ServiceClient("https://demo.inflowpay.ai") as service:
+        inspection = await service.inspect()
+        print(inspection.document.name)
+        print([operation.name.value for operation in inspection.document.operations])
+
+        page = await service.search_offerings(
+            OfferingSearchRequest(query="plant"),
+            Representation.TERSE,
+        )
+        for offering in page.items:
+            print(offering.id, offering.name, offering.price)
+
+        details = await service.get_offering_details(page.items[0].id)
+        for action in details.actions:
+            print(action.id, action.rel.value, action.authentication.value)
+
+
+asyncio.run(main())
+```
+
+`get_offering_details()` resolves and validates an Offering's Attribute Schema, normalizes usable
+Actions, and reports non-fatal issues separately from the Offering. `resolve_action()` resolves a
+specific Action's HTTP or OpenAPI target and request schema. It never calls the target, enrolls,
+authenticates, or pays.
+
+The Agent module also provides:
+
+- Collection list, get, search, and bounded traversal operations.
+- Offering list, get, search, collection listing, continuation, and bounded traversal operations.
+- Effective inline and linked Filter and Sort definitions for Service and Collection scopes.
+- Directory-to-Service federated Offering discovery through `Agent`.
+- Conditional request and representation caching with injectable `Cache` and `Transport` protocols.
+
+Default fallback cache lifetimes are four hours for Service documents, one hour for Collections,
+and five minutes for Offerings. HTTP cache directives take precedence. Provide distinct `transport`
+and `supporting_transport` instances when protocol resources and linked schemas require different
+credentials or network policy.
+
+## Publish a Service
+
+`Service` is framework-neutral. Adapt the incoming framework request to `Request`, call
+`Service.handle()`, and copy the returned status, headers, and body into the framework response.
+
+```python
+from offering_protocol.core import Collection, Offering
+from offering_protocol.service import ServiceBuilder, StaticCatalog, StaticCatalogOptions
+
+catalog = StaticCatalog(
+    StaticCatalogOptions(
+        collections=(Collection(id="plants", name="Plants", odp_version="1.0"),),
+        offerings=(
+            Offering(
+                collection_ids=["plants"],
+                description="A resilient indoor plant.",
+                id="rubber-plant",
+                name="Rubber Plant",
+                odp_version="1.0",
+            ),
+        ),
+    )
+)
+
+service = (
+    ServiceBuilder(
+        name="Indica Flowers",
+        description="An AI-enabled store for houseplants and plant care.",
+        language="en",
+        endpoint_base="/odp",
+    )
+    .keywords(["houseplants", "indoor-plants"])
+    .website_url("https://example.com")
+    .build(catalog)
+)
+```
+
+Every Service integration must implement `list-offerings` and `get-offering`. `StaticCatalog` is the
+small-Service implementation: it adds Collection operations when Collections are provided and uses
+stateless, expiring continuations. Larger Services can implement the typed `Catalog` protocol over
+their existing indexed catalog and search infrastructure.
 
-| Goal                                          | Module                        |
-| --------------------------------------------- | ----------------------------- |
-| Work with protocol models and validation      | `offering_protocol.core`      |
-| Search the canonical Directory                | `offering_protocol.directory` |
-| Discover Services and navigate their catalogs | `offering_protocol.agent`     |
-| Publish an ODP Service                        | `offering_protocol.service`   |
+Service responses are validated against the bundled normative schemas before they are returned.
+The handler enforces fixed operation paths and methods, ODP media types, request and response byte
+limits, local identifiers, page limits, and protocol Problem Details.
 
-The dependency direction remains narrow: Core is transport-independent, Directory depends toward
-Core, Agent composes Core and Directory, and Service depends toward Core without depending on Agent
-behavior.
+See [examples/README.md](./examples/README.md) for a runnable Service and Agent.
 
 ## Protocol composition
 
-ODP discovers what a Service offers and how an Agent can act on an Offering. A Service Document and
+ODP discovers what a Service offers and how an Agent can act on an Offering. A Service document and
 its Actions can advertise AEP enrollment and MPP or x402 payment requirements, but ODP does not
 create credentials, invoke Actions, or submit payments. Applications compose the appropriate
-enrollment and payment clients around an Action resolved through ODP.
+enrollment and payment client around an Action resolved through ODP.
+
+## Errors and validation
+
+Each role exposes typed errors:
+
+- `OdpValidationError` includes deterministic schema and semantic issues.
+- `DirectoryError` and `DirectoryRequestError` describe canonical Directory failures.
+- `AgentError`, `ServiceRequestError`, and `UnsupportedOperationError` describe Agent-side failures.
+- `ServiceError`, `CatalogError`, and `RequestError` describe Service integration failures.
+
+Protocol models preserve additive members in `model.additional` and round-trip them through
+`model.to_dict()`. Parsing remains strict for normative constraints and fields that prohibit unknown
+members.
 
 ## Development
 
-Python 3.11 or newer and [uv](https://docs.astral.sh/uv/) are required. Install the locked development
-environment and run the complete merge gate with:
+Python 3.11 or newer and [uv](https://docs.astral.sh/uv/) are required.
 
 ```sh
 make sync
@@ -55,8 +202,9 @@ Format source files with:
 make format
 ```
 
-The merge gate checks formatting, linting, strict type checking, branch coverage, distribution
-metadata, and installation of the built wheel into a clean virtual environment.
+The merge gate checks formatting, linting, strict type checking, 100 percent line and branch
+coverage, distribution metadata, bundled runtime schemas, and installation of the built wheel into
+a clean virtual environment.
 
 See [`odp-specs`](https://github.com/offering-protocol/odp-specs) for the normative draft, schemas,
 examples, and test vectors.

examples/README.md

@@ -0,0 +1,30 @@
+# Runnable examples
+
+The examples use the installed `offering-protocol` package and require no web framework.
+
+From the repository root, start the sample Service:
+
+```sh
+uv run python examples/service.py
+```
+
+In another terminal, inspect it and list its Offerings:
+
+```sh
+uv run python examples/agent.py
+```
+
+The Agent example defaults to `http://127.0.0.1:4103`. Pass another Service origin as its first
+argument to inspect any ODP Service:
+
+```sh
+uv run python examples/agent.py https://demo.inflowpay.ai
+```
+
+`service.py` demonstrates the minimum Service integration: a framework adapter, `StaticCatalog`,
+`list-offerings`, and `get-offering`. It also includes a Collection so the Collection operations can
+be exercised. It is intentionally an in-memory example; production Services can implement the same
+typed `Catalog` protocol over their own data source.
+
+`agent.py` prints the Service document, lists Collections and Offerings only when those operations
+are advertised, and fetches full details for the first Offering. It does not invoke an Action.

examples/agent.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from offering_protocol.agent import ServiceClient
+from offering_protocol.core import Operation
+
+
+async def main() -> None:
+    origin = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:4103"
+    async with ServiceClient(origin) as service:
+        inspection = await service.inspect()
+        operations = {item.name for item in inspection.document.operations}
+
+        print("Service")
+        print(f"  Name: {inspection.document.name}")
+        print(f"  Description: {inspection.document.description}")
+        print(f"  Origin: {inspection.service_origin}")
+        print(f"  Operations: {', '.join(sorted(item.value for item in operations))}")
+
+        if Operation.LIST_COLLECTIONS in operations:
+            collections = await service.list_collections()
+            print("\nCollections")
+            for collection in collections.items:
+                print(f"  {collection.id}: {collection.name}")
+
+        offerings = await service.list_offerings()
+        print("\nOfferings")
+        for offering in offerings.items:
+            print(f"  {offering.id}: {offering.name}")
+
+        if offerings.items:
+            details = await service.get_offering_details(offerings.items[0].id)
+            print("\nFirst Offering")
+            print(f"  Name: {details.offering.name}")
+            print(f"  Description: {details.offering.description}")
+            print(f"  Actions: {', '.join(action.id for action in details.actions) or 'None'}")
+            for issue in details.issues:
+                print(f"  Issue: {issue.message}")
+
+
+asyncio.run(main())

examples/service.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlsplit
+
+from offering_protocol.core import Collection, Offering
+from offering_protocol.service import Request, ServiceBuilder, StaticCatalog, StaticCatalogOptions
+
+catalog = StaticCatalog(
+    StaticCatalogOptions(
+        collections=(Collection(id="plants", name="Plants", odp_version="1.0"),),
+        offerings=(
+            Offering(
+                collection_ids=["plants"],
+                description="A resilient indoor plant with broad, glossy leaves.",
+                id="rubber-plant",
+                name="Rubber Plant",
+                odp_version="1.0",
+            ),
+            Offering(
+                collection_ids=["plants"],
+                description="A low-maintenance plant with upright patterned leaves.",
+                id="snake-plant",
+                name="Snake Plant",
+                odp_version="1.0",
+            ),
+        ),
+    )
+)
+
+service = (
+    ServiceBuilder(
+        "Example Plant Store",
+        "An ODP-enabled store for indoor plants.",
+        "en",
+        "/odp",
+    )
+    .keywords(["houseplants", "indoor-plants"])
+    .build(catalog)
+)
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        self._handle()
+
+    def do_POST(self) -> None:
+        self._handle()
+
+    def _handle(self) -> None:
+        parsed = urlsplit(self.path)
+        length = int(self.headers.get("content-length", "0"))
+        response = asyncio.run(
+            service.handle(
+                Request(
+                    body=self.rfile.read(length),
+                    headers={name: value for name, value in self.headers.items()},
+                    method=self.command,
+                    path=parsed.path,
+                    query=parsed.query,
+                )
+            )
+        )
+        self.send_response(response.status)
+        for name, value in response.headers.items():
+            self.send_header(name, value)
+        self.send_header("content-length", str(len(response.body)))
+        self.end_headers()
+        self.wfile.write(response.body)
+
+    def log_message(self, format: str, *args: object) -> None:
+        print(f"{self.command} {self.path} - {format % args}")
+
+
+if __name__ == "__main__":
+    server = ThreadingHTTPServer(("127.0.0.1", 4103), Handler)
+    print("ODP Service listening at http://127.0.0.1:4103")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()