[#9] feat: add top-level API, README docs, and integration tests (#14)

### What changes were proposed in this pull request?

Finalize the public API surface, documentation, and integration tests:

- `src/adp_sdk/__init__.py`: Complete public exports + `stdio_client()`
convenience async context manager
- `README.md`: Quick Start guide, API overview, error handling
documentation
- `tests/test_integration.py`: End-to-end tests with embedded mock ADP
server (full lifecycle: initialize → discover → describe → validate →
execute)

### Why are the changes needed?

Provides a polished developer experience with a convenient entry point
(`stdio_client()`), comprehensive documentation, and end-to-end test
coverage.

Fix: #9

### Does this PR introduce _any_ user-facing change?

Yes. Adds `stdio_client()` convenience function and complete public API
exports. Adds full README documentation.

### How was this patch tested?

Integration tests launch a mock ADP server subprocess and exercise the
full protocol lifecycle through the public API.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mchades

README.md

@@ -1,6 +1,12 @@
 # ADP Python SDK
 
-Python SDK for the Agentic Data Protocol (ADP) - a deterministic, policy-aware protocol that allows AI agents to access heterogeneous data systems safely and reproducibly via a unified intent interface.
+Python SDK for the **Agentic Data Protocol (ADP)** — a deterministic, policy-aware
+protocol that allows AI agents to access heterogeneous data systems safely and
+reproducibly via a unified intent interface.
+
+This SDK provides a **client-side** API for connecting to any ADP-compliant server
+(such as [adp-hypervisor](https://github.com/agntcy/adp-hypervisor)) over **stdio
+transport**.
 
 ## Installation
 
@@ -12,10 +18,74 @@ uv add adp-sdk
 pip install adp-sdk
 ```
 
+## Quick Start
+
+```python
+import asyncio
+from adp_sdk import stdio_client, QueryIntent, PredicateGroup
+
+async def main():
+    async with stdio_client("python", ["-m", "adp_hypervisor", "--config", "config.yaml"]) as session:
+        # 1. Discover available resources
+        discovery = await session.discover()
+        for resource in discovery.resources:
+            print(f"  {resource.resource_id}: {resource.description}")
+
+        # 2. Describe a resource to get its usage contract
+        contract = await session.describe("com.example:users", "QUERY")
+        print(f"Fields: {[f.field_id for f in contract.usage_contract.fields]}")
+
+        # 3. Execute an intent
+        intent = QueryIntent(
+            intentClass="QUERY",
+            predicates=PredicateGroup(op="AND", predicates=[]),
+        )
+        result = await session.execute("com.example:users", intent)
+        print(f"Got {len(result.results)} rows")
+
+asyncio.run(main())
+```
+
+## API Overview
+
+### `stdio_client` (convenience)
+
+```python
+async with stdio_client(command, args=None, env=None, cwd=None) as session:
+    ...
+```
+
+Launches an ADP server as a subprocess and returns an initialized `ClientSession`.
+
+### `ClientSession`
+
+| Method | Description |
+|--------|-------------|
+| `discover(filter?, cursor?)` | List available resources |
+| `describe(resource_id, intent_class, version?, cursor?)` | Get a resource's usage contract |
+| `validate(resource_id, intent)` | Check if an intent is valid |
+| `execute(resource_id, intent, cursor?)` | Run an intent against a resource |
+| `ping()` | Check server liveness |
+
+### Error Handling
+
+All server errors are mapped to typed exceptions:
+
+```python
+from adp_sdk import ResourceNotFoundError, ValidationFailedError
+
+try:
+    result = await session.execute("com.example:missing", intent)
+except ResourceNotFoundError as e:
+    print(f"Resource not found: {e}")
+except ValidationFailedError as e:
+    print(f"Invalid intent: {e}")
+```
+
 ## Development
 
 ```bash
-# Install development dependencies
+# Install dependencies
 uv sync --all-extras
 
 # Run tests

src/adp_sdk/__init__.py

@@ -1,10 +1,122 @@
 """ADP SDK - Python SDK for the Agentic Data Protocol."""
 
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from adp_sdk.client import ClientSession
+from adp_sdk.shared import (
+    ADPError,
+    ExecutionFailedError,
+    InternalError,
+    InvalidParamsError,
+    InvalidRequestError,
+    MethodNotFoundError,
+    ParseError,
+    ResourceNotFoundError,
+    UnauthorizedError,
+    ValidationFailedError,
+)
+from adp_sdk.transports import Transport
+from adp_sdk.transports.stdio import StdioClientTransport
 from adp_sdk.types import LATEST_PROTOCOL_VERSION
+from adp_sdk.types.common import (
+    Capabilities,
+    FieldDefinition,
+    IdentityPredicate,
+    IntentClass,
+    Predicate,
+    PredicateGroup,
+    Resource,
+    UsageContract,
+    ValidationIssue,
+)
+from adp_sdk.types.intents import (
+    IngestIntent,
+    Intent,
+    LookupIntent,
+    QueryIntent,
+    ReviseIntent,
+)
+from adp_sdk.types.responses import (
+    DescribeResult,
+    DiscoverResult,
+    ExecuteResult,
+    InitializeResult,
+    ValidateResult,
+)
 
 __version__ = "0.1.0"
 
+
+@asynccontextmanager
+async def stdio_client(
+    command: str,
+    args: list[str] | None = None,
+    env: dict[str, str] | None = None,
+    cwd: str | None = None,
+) -> AsyncIterator[ClientSession]:
+    """Create a :class:`ClientSession` connected via stdio transport.
+
+    Launches *command* as a subprocess and communicates over
+    stdin/stdout using newline-delimited JSON.
+
+    Usage::
+
+        async with stdio_client("python", ["-m", "adp_hypervisor"]) as session:
+            resources = await session.discover()
+
+    Args:
+        command: The executable to run.
+        args: Command-line arguments.
+        env: Additional environment variables.
+        cwd: Working directory for the subprocess.
+
+    Yields:
+        An initialized :class:`ClientSession`.
+    """
+    transport = StdioClientTransport(command, args=args, env=env, cwd=cwd)
+    async with ClientSession(transport) as session:
+        yield session
+
+
 __all__ = [
     "__version__",
     "LATEST_PROTOCOL_VERSION",
+    # Convenience
+    "stdio_client",
+    # Core classes
+    "ClientSession",
+    "Transport",
+    "StdioClientTransport",
+    # Protocol types
+    "Capabilities",
+    "DescribeResult",
+    "DiscoverResult",
+    "ExecuteResult",
+    "FieldDefinition",
+    "IdentityPredicate",
+    "IngestIntent",
+    "InitializeResult",
+    "Intent",
+    "IntentClass",
+    "LookupIntent",
+    "Predicate",
+    "PredicateGroup",
+    "QueryIntent",
+    "Resource",
+    "ReviseIntent",
+    "UsageContract",
+    "ValidateResult",
+    "ValidationIssue",
+    # Exceptions
+    "ADPError",
+    "ExecutionFailedError",
+    "InternalError",
+    "InvalidParamsError",
+    "InvalidRequestError",
+    "MethodNotFoundError",
+    "ParseError",
+    "ResourceNotFoundError",
+    "UnauthorizedError",
+    "ValidationFailedError",
 ]

src/adp_sdk/client/session.py

@@ -8,10 +8,10 @@
 
 import itertools
 import logging
+from importlib.metadata import version as _pkg_version
 from types import TracebackType
 from typing import Any
 
-from adp_sdk import __version__
 from adp_sdk.shared import (
     deserialize_json,
     get_exception_for_error_code,
@@ -45,6 +45,7 @@
 logger = logging.getLogger(__name__)
 
 _SDK_NAME = "adp-sdk-python"
+_SDK_VERSION = _pkg_version("adp-sdk")
 
 
 class ClientSession:
@@ -70,7 +71,7 @@ def __init__(
         self._transport = transport
         self._client_info = client_info or Implementation(
             name=_SDK_NAME,
-            version=__version__,
+            version=_SDK_VERSION,
         )
         self._capabilities = capabilities or ClientCapabilities()
         self._id_counter = itertools.count(1)