agentplane-sdk 0.0.1__py3-none-any.whl

agentplane_sdk/__init__.py

@@ -0,0 +1,43 @@
+"""agentplane-sdk: thin typed client + CLI."""
+
+from agentplane_sdk.auth import (
+    OidcClientCredentialsProvider,
+    StaticTokenProvider,
+    TokenProvider,
+    as_token_provider,
+)
+from agentplane_sdk.client import (
+    RegistryClient,
+    RuntimeClient,
+    SyncRegistryClient,
+    SyncRuntimeClient,
+)
+from agentplane_sdk.errors import (
+    AgentplaneError,
+    ApiError,
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    TransportError,
+    ValidationFailedError,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AgentplaneError",
+    "ApiError",
+    "AuthError",
+    "ConflictError",
+    "NotFoundError",
+    "OidcClientCredentialsProvider",
+    "RegistryClient",
+    "RuntimeClient",
+    "StaticTokenProvider",
+    "SyncRegistryClient",
+    "SyncRuntimeClient",
+    "TokenProvider",
+    "TransportError",
+    "ValidationFailedError",
+    "as_token_provider",
+]

agentplane_sdk/auth.py

@@ -0,0 +1,99 @@
+"""Token providers: static bearer and OIDC client-credentials (SPEC §4.1)."""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol, runtime_checkable
+
+import httpx
+
+from agentplane_sdk.errors import AuthError, TransportError
+
+
+@runtime_checkable
+class TokenProvider(Protocol):
+    """Anything that can produce a bearer token."""
+
+    async def get_token(self) -> str: ...
+
+
+class StaticTokenProvider:
+    """Wraps a fixed bearer token."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    async def get_token(self) -> str:
+        return self._token
+
+
+class OidcClientCredentialsProvider:
+    """Fetches tokens via the OIDC client-credentials grant, cached until expiry."""
+
+    def __init__(
+        self,
+        issuer: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        audience: str | None = None,
+        leeway_s: float = 30.0,
+    ) -> None:
+        self._issuer = issuer.rstrip("/")
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._audience = audience
+        self._leeway_s = leeway_s
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+        self._token_endpoint: str | None = None
+
+    async def get_token(self) -> str:
+        if self._token is not None and time.monotonic() < self._expires_at:
+            return self._token
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                if self._token_endpoint is None:
+                    discovery = await client.get(f"{self._issuer}/.well-known/openid-configuration")
+                    discovery.raise_for_status()
+                    endpoint = discovery.json().get("token_endpoint")
+                    if not isinstance(endpoint, str):
+                        raise AuthError("issuer discovery returned no token_endpoint")
+                    self._token_endpoint = endpoint
+                data = {
+                    "grant_type": "client_credentials",
+                    "client_id": self._client_id,
+                    "client_secret": self._client_secret,
+                }
+                if self._audience:
+                    data["audience"] = self._audience
+                response = await client.post(self._token_endpoint, data=data)
+        except httpx.HTTPError as exc:
+            raise TransportError(f"token request failed: {exc}") from exc
+        if response.status_code != httpx.codes.OK:
+            raise AuthError(f"token endpoint returned {response.status_code}")
+        payload = response.json()
+        token = payload.get("access_token")
+        if not isinstance(token, str):
+            raise AuthError("token endpoint returned no access_token")
+        expires_in = payload.get("expires_in", 300)
+        ttl = float(expires_in) if isinstance(expires_in, int | float) else 300.0
+        self._token = token
+        self._expires_at = time.monotonic() + max(ttl - self._leeway_s, 5.0)
+        return token
+
+
+def as_token_provider(token: str | TokenProvider | None) -> TokenProvider | None:
+    if token is None:
+        return None
+    if isinstance(token, str):
+        return StaticTokenProvider(token)
+    return token
+
+
+__all__ = [
+    "OidcClientCredentialsProvider",
+    "StaticTokenProvider",
+    "TokenProvider",
+    "as_token_provider",
+]

agentplane_sdk/cli.py

@@ -0,0 +1,326 @@
+"""The ``agentplane`` CLI (SPEC §4.2).
+
+Exit codes: 0 ok, 1 validation failed, 2 transport/auth error, 3 not found.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Coroutine
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+import yaml
+from pydantic import TypeAdapter, ValidationError
+
+from agentplane_core import (
+    FlowDefinition,
+    Resource,
+    ValidationResult,
+    validate_structure,
+)
+from agentplane_sdk.client import RegistryClient, RuntimeClient
+from agentplane_sdk.config import resolve_config, token_provider_from_config
+from agentplane_sdk.errors import (
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    TransportError,
+    ValidationFailedError,
+)
+
+app = typer.Typer(name="agentplane", help="agentplane platform CLI", no_args_is_help=True)
+resources_app = typer.Typer(help="Manage runtime resources", no_args_is_help=True)
+app.add_typer(resources_app, name="resources")
+
+EXIT_OK = 0
+EXIT_VALIDATION = 1
+EXIT_TRANSPORT = 2
+EXIT_NOT_FOUND = 3
+
+_RESOURCE_ADAPTER: TypeAdapter[Resource] = TypeAdapter(Resource)
+
+RuntimeUrlOption = Annotated[
+    str | None, typer.Option("--runtime-url", envvar="AGENTPLANE_RUNTIME_URL")
+]
+RegistryUrlOption = Annotated[
+    str | None, typer.Option("--registry-url", envvar="AGENTPLANE_REGISTRY_URL")
+]
+TokenOption = Annotated[str | None, typer.Option("--token", envvar="AGENTPLANE_TOKEN")]
+JsonFlag = Annotated[bool, typer.Option("--json", help="machine-readable output")]
+
+
+def _fail(message: str, code: int) -> None:
+    typer.echo(message, err=True)
+    raise typer.Exit(code)
+
+
+def _run[R](coro: Coroutine[Any, Any, R]) -> R:
+    try:
+        return asyncio.run(coro)
+    except ValidationFailedError as exc:
+        _print_issues(exc.result, as_json=False)
+        raise typer.Exit(EXIT_VALIDATION) from None
+    except NotFoundError as exc:
+        _fail(f"not found: {exc}", EXIT_NOT_FOUND)
+    except (TransportError, AuthError) as exc:
+        _fail(str(exc), EXIT_TRANSPORT)
+    except ConflictError as exc:
+        _fail(f"conflict: {exc}", EXIT_TRANSPORT)
+    raise AssertionError("unreachable")
+
+
+def _load_yaml(path: Path) -> dict[str, object]:
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+    except FileNotFoundError:
+        _fail(f"file not found: {path}", EXIT_NOT_FOUND)
+    except yaml.YAMLError as exc:
+        _fail(f"invalid YAML in {path}: {exc}", EXIT_VALIDATION)
+    if not isinstance(data, dict):
+        _fail(f"{path} does not contain a mapping", EXIT_VALIDATION)
+    return {str(key): value for key, value in data.items()}
+
+
+def _print_issues(result: ValidationResult, *, as_json: bool) -> None:
+    if as_json:
+        typer.echo(result.model_dump_json(indent=2))
+        return
+    for issue in result.issues:
+        typer.echo(f"{issue.severity.upper()} {issue.code} {issue.path}: {issue.message}", err=True)
+
+
+def _runtime_client(runtime_url: str | None, token: str | None) -> RuntimeClient:
+    config = resolve_config(runtime_url=runtime_url, token=token)
+    if not config.runtime_url:
+        _fail(
+            "no runtime URL configured (flag --runtime-url / env AGENTPLANE_RUNTIME_URL)",
+            EXIT_TRANSPORT,
+        )
+    assert config.runtime_url is not None
+    return RuntimeClient(config.runtime_url, token_provider_from_config(config))
+
+
+def _registry_client(registry_url: str | None, token: str | None) -> RegistryClient:
+    config = resolve_config(registry_url=registry_url, token=token)
+    if not config.registry_url:
+        _fail(
+            "no registry URL configured (flag --registry-url / env AGENTPLANE_REGISTRY_URL)",
+            EXIT_TRANSPORT,
+        )
+    assert config.registry_url is not None
+    return RegistryClient(config.registry_url, token_provider_from_config(config))
+
+
+@app.command()
+def validate(
+    file: Annotated[Path, typer.Argument(help="flow definition YAML")],
+    json_output: JsonFlag = False,
+    remote: Annotated[
+        bool, typer.Option("--remote", help="ask the runtime (authoritative, adds E020-E022)")
+    ] = False,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Validate a definition; local by default, --remote for the runtime's answer."""
+    raw = _load_yaml(file)
+    if remote:
+
+        async def remote_validate() -> ValidationResult:
+            async with _runtime_client(runtime_url, token) as client:
+                return await client.validate(raw)
+
+        result = _run(remote_validate())
+    else:
+        result = ValidationResult.from_issues(validate_structure(raw))
+    _print_issues(result, as_json=json_output)
+    raise typer.Exit(EXIT_OK if result.valid else EXIT_VALIDATION)
+
+
+@app.command()
+def deploy(
+    file: Annotated[Path, typer.Argument(help="flow definition YAML")],
+    draft: Annotated[bool, typer.Option("--draft", help="create/update the draft only")] = False,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Create-or-update the definition by name; deploys unless --draft."""
+    raw = _load_yaml(file)
+    try:
+        defn = FlowDefinition.model_validate(raw)
+    except ValidationError:
+        result = ValidationResult.from_issues(validate_structure(raw))
+        _print_issues(result, as_json=False)
+        raise typer.Exit(EXIT_VALIDATION) from None
+
+    async def do_deploy() -> str:
+        async with _runtime_client(runtime_url, token) as client:
+            try:
+                await client.create_draft(defn)
+            except ConflictError:
+                await client.update_draft(defn.name, defn)
+            if draft:
+                return f"draft saved: {defn.name}"
+            info = await client.deploy(defn.name)
+            return f"deployed {info.name} v{info.version} -> {info.endpoint_url}"
+
+    typer.echo(_run(do_deploy()))
+
+
+@app.command()
+def undeploy(
+    name: str,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Stop serving a deployed definition and deregister it."""
+
+    async def do_undeploy() -> None:
+        async with _runtime_client(runtime_url, token) as client:
+            await client.undeploy(name)
+
+    _run(do_undeploy())
+    typer.echo(f"undeployed {name}")
+
+
+@app.command(name="list")
+def list_definitions(
+    status: Annotated[str | None, typer.Option("--status")] = None,
+    json_output: JsonFlag = False,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """List definitions known to the runtime."""
+
+    async def do_list() -> list[dict[str, object]]:
+        async with _runtime_client(runtime_url, token) as client:
+            return [i.model_dump(mode="json") for i in await client.list(status)]
+
+    infos = _run(do_list())
+    if json_output:
+        typer.echo(json.dumps(infos, indent=2))
+        return
+    for info in infos:
+        endpoint = info.get("endpoint_url") or "-"
+        typer.echo(f"{info['name']:<30} {info['status']:<10} {endpoint}")
+
+
+@app.command()
+def export(
+    name: str,
+    output: Annotated[Path | None, typer.Option("-o", "--output")] = None,
+    version: Annotated[int | None, typer.Option("--version")] = None,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Export the canonical serialized definition."""
+
+    async def do_export() -> FlowDefinition:
+        async with _runtime_client(runtime_url, token) as client:
+            return await client.export(name, version)
+
+    defn = _run(do_export())
+    text = yaml.safe_dump(defn.canonical_dict(), sort_keys=False, allow_unicode=True)
+    if output is None:
+        typer.echo(text)
+    else:
+        output.write_text(text, encoding="utf-8")
+        typer.echo(f"wrote {output}")
+
+
+@app.command()
+def search(
+    query: Annotated[str, typer.Argument()] = "",
+    tags: Annotated[list[str] | None, typer.Option("--tags")] = None,
+    semantic: Annotated[bool, typer.Option("--semantic")] = False,
+    kind: Annotated[str | None, typer.Option("--kind")] = None,
+    json_output: JsonFlag = False,
+    registry_url: RegistryUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Search the registry."""
+
+    async def do_search() -> list[dict[str, object]]:
+        async with _registry_client(registry_url, token) as client:
+            page = await client.search(query, tags=tags, kind=kind, semantic=semantic)
+            return [e.model_dump(mode="json") for e in page.items]
+
+    entries = _run(do_search())
+    if json_output:
+        typer.echo(json.dumps(entries, indent=2))
+        return
+    for entry in entries:
+        card = entry.get("card")
+        name = card.get("name", "?") if isinstance(card, dict) else "?"
+        typer.echo(f"{name:<30} {entry['kind']:<11} {entry['status']:<9} {entry['url']}")
+
+
+@resources_app.command(name="list")
+def resources_list(
+    kind: Annotated[str | None, typer.Option("--kind")] = None,
+    json_output: JsonFlag = False,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """List resources."""
+
+    async def do_list() -> list[dict[str, object]]:
+        async with _runtime_client(runtime_url, token) as client:
+            resources = await client.list_resources(kind)
+        return [_RESOURCE_ADAPTER.dump_python(r, mode="json") for r in resources]
+
+    resources = _run(do_list())
+    if json_output:
+        typer.echo(json.dumps(resources, indent=2))
+        return
+    for resource in resources:
+        typer.echo(f"{resource['name']:<30} {resource['kind']}")
+
+
+@resources_app.command(name="create")
+def resources_create(
+    file: Annotated[Path, typer.Option("-f", "--file", help="resource YAML")],
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Create a resource from a YAML file."""
+    raw = _load_yaml(file)
+    try:
+        resource = _RESOURCE_ADAPTER.validate_python(raw)
+    except ValidationError as exc:
+        _fail(f"invalid resource: {exc}", EXIT_VALIDATION)
+        raise AssertionError("unreachable") from None
+
+    async def do_create() -> str:
+        async with _runtime_client(runtime_url, token) as client:
+            created = await client.create_resource(resource)
+            return created.name
+
+    typer.echo(f"created resource {_run(do_create())}")
+
+
+@resources_app.command(name="delete")
+def resources_delete(
+    name: str,
+    runtime_url: RuntimeUrlOption = None,
+    token: TokenOption = None,
+) -> None:
+    """Delete a resource (refused while referenced)."""
+
+    async def do_delete() -> None:
+        async with _runtime_client(runtime_url, token) as client:
+            await client.delete_resource(name)
+
+    _run(do_delete())
+    typer.echo(f"deleted resource {name}")
+
+
+def main() -> None:  # pragma: no cover - thin wrapper
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

agentplane_sdk/client.py

@@ -0,0 +1,396 @@
+"""Typed async clients for the registry and runtime APIs (SPEC §4.1).
+
+Everything the SDK does is possible with plain HTTP — the SDK is
+convenience, not a requirement.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine, Mapping
+from types import TracebackType
+from typing import Any, Self, TypeVar
+from uuid import UUID
+
+import httpx
+from pydantic import TypeAdapter
+
+from agentplane_core import (
+    Capabilities,
+    DefinitionInfo,
+    DeploymentInfo,
+    FlowDefinition,
+    Page,
+    RegistryEntry,
+    RegistryEntryCreate,
+    RegistryEntryPatch,
+    Resource,
+    ValidationResult,
+)
+from agentplane_sdk.auth import TokenProvider, as_token_provider
+from agentplane_sdk.errors import (
+    ApiError,
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    TransportError,
+    ValidationFailedError,
+)
+
+_RESOURCE_ADAPTER: TypeAdapter[Resource] = TypeAdapter(Resource)
+_RESOURCE_LIST_ADAPTER: TypeAdapter[list[Resource]] = TypeAdapter(list[Resource])
+_DEFINITION_LIST_ADAPTER: TypeAdapter[list[DefinitionInfo]] = TypeAdapter(list[DefinitionInfo])
+
+T = TypeVar("T")
+
+# `list` is also a client method name (SPEC API); alias the builtin for annotations.
+_List = list
+
+
+class _BaseClient:
+    """Shared HTTP plumbing: base URL, bearer auth, error mapping."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | TokenProvider | None = None,
+        *,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._token_provider = as_token_provider(token)
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"), timeout=timeout, transport=transport
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: object | None = None,
+        params: Mapping[str, str | int | None] | None = None,
+    ) -> httpx.Response:
+        headers: dict[str, str] = {}
+        if self._token_provider is not None:
+            headers["Authorization"] = f"Bearer {await self._token_provider.get_token()}"
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                json=json,
+                params=self._clean_params(params),
+                headers=headers,
+            )
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+        self._raise_for_status(response)
+        return response
+
+    @staticmethod
+    def _clean_params(
+        params: Mapping[str, str | int | None] | None,
+    ) -> dict[str, str | int] | None:
+        if params is None:
+            return None
+        return {k: v for k, v in params.items() if v is not None}
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        status = response.status_code
+        if status < httpx.codes.BAD_REQUEST:
+            return
+        if status in (httpx.codes.UNAUTHORIZED, httpx.codes.FORBIDDEN):
+            raise AuthError(f"HTTP {status}: {response.text}")
+        if status == httpx.codes.NOT_FOUND:
+            raise NotFoundError(response.text)
+        if status == httpx.codes.CONFLICT:
+            raise ConflictError(response.text)
+        if status == httpx.codes.UNPROCESSABLE_ENTITY:
+            try:
+                result = ValidationResult.model_validate(response.json())
+            except ValueError:
+                raise ApiError(status, response.text) from None
+            raise ValidationFailedError(result)
+        raise ApiError(status, response.text)
+
+
+class RegistryClient(_BaseClient):
+    """Client for the agentplane-registry REST API (SPEC §5.1)."""
+
+    _prefix = "/api/v1"
+
+    async def register(self, entry: RegistryEntryCreate) -> RegistryEntry:
+        response = await self._request(
+            "POST", f"{self._prefix}/agents", json=entry.model_dump(mode="json")
+        )
+        return RegistryEntry.model_validate(response.json())
+
+    async def get(self, id: UUID) -> RegistryEntry:
+        response = await self._request("GET", f"{self._prefix}/agents/{id}")
+        return RegistryEntry.model_validate(response.json())
+
+    async def update(self, id: UUID, patch: RegistryEntryPatch) -> RegistryEntry:
+        response = await self._request(
+            "PUT",
+            f"{self._prefix}/agents/{id}",
+            json=patch.model_dump(mode="json", exclude_none=True),
+        )
+        return RegistryEntry.model_validate(response.json())
+
+    async def delete(self, id: UUID) -> None:
+        await self._request("DELETE", f"{self._prefix}/agents/{id}")
+
+    async def search(
+        self,
+        q: str = "",
+        tags: _List[str] | None = None,
+        kind: str | None = None,
+        status: str | None = None,
+        semantic: bool = False,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Page:
+        params: dict[str, str | int | None] = {
+            "q": q,
+            "kind": kind,
+            "status": status,
+            "semantic": "true" if semantic else None,
+            "limit": limit,
+            "offset": offset,
+        }
+        if tags:
+            params["tags"] = ",".join(tags)
+        response = await self._request("GET", f"{self._prefix}/agents/search", params=params)
+        return Page.model_validate(response.json())
+
+    async def list(
+        self,
+        kind: str | None = None,
+        status: str | None = None,
+        tags: _List[str] | None = None,
+        owner: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Page:
+        params: dict[str, str | int | None] = {
+            "kind": kind,
+            "status": status,
+            "owner": owner,
+            "limit": limit,
+            "offset": offset,
+        }
+        if tags:
+            params["tags"] = ",".join(tags)
+        response = await self._request("GET", f"{self._prefix}/agents", params=params)
+        return Page.model_validate(response.json())
+
+    async def capabilities(self) -> Capabilities:
+        response = await self._request("GET", f"{self._prefix}/capabilities")
+        return Capabilities.model_validate(response.json())
+
+
+class RuntimeClient(_BaseClient):
+    """Client for the agentplane-runtime definitions/resources API (SPEC §6.1/§6.3)."""
+
+    _prefix = "/api/v1"
+
+    async def validate(self, defn: FlowDefinition | Mapping[str, object]) -> ValidationResult:
+        payload = defn.canonical_dict() if isinstance(defn, FlowDefinition) else dict(defn)
+        response = await self._request("POST", f"{self._prefix}/definitions/validate", json=payload)
+        return ValidationResult.model_validate(response.json())
+
+    async def create_draft(self, defn: FlowDefinition) -> DefinitionInfo:
+        response = await self._request(
+            "POST", f"{self._prefix}/definitions", json=defn.canonical_dict()
+        )
+        return DefinitionInfo.model_validate(response.json())
+
+    async def update_draft(self, name: str, defn: FlowDefinition) -> DefinitionInfo:
+        response = await self._request(
+            "PUT", f"{self._prefix}/definitions/{name}", json=defn.canonical_dict()
+        )
+        return DefinitionInfo.model_validate(response.json())
+
+    async def deploy(
+        self, name: str, *, version: int | None = None, ephemeral: bool = False
+    ) -> DeploymentInfo:
+        params: dict[str, str | int | None] = {
+            "version": version,
+            "ephemeral": "true" if ephemeral else None,
+        }
+        response = await self._request(
+            "POST", f"{self._prefix}/definitions/{name}/deploy", params=params
+        )
+        return DeploymentInfo.model_validate(response.json())
+
+    async def undeploy(self, name: str) -> None:
+        await self._request("POST", f"{self._prefix}/definitions/{name}/undeploy")
+
+    async def get(self, name: str, *, include_definition: bool = False) -> DefinitionInfo:
+        params = {"include": "definition"} if include_definition else None
+        response = await self._request("GET", f"{self._prefix}/definitions/{name}", params=params)
+        return DefinitionInfo.model_validate(response.json())
+
+    async def list(self, status: str | None = None) -> _List[DefinitionInfo]:
+        response = await self._request(
+            "GET", f"{self._prefix}/definitions", params={"status": status}
+        )
+        return _DEFINITION_LIST_ADAPTER.validate_python(response.json())
+
+    async def export(self, name: str, version: int | None = None) -> FlowDefinition:
+        response = await self._request(
+            "GET", f"{self._prefix}/definitions/{name}/export", params={"version": version}
+        )
+        return FlowDefinition.model_validate(response.json())
+
+    async def delete(self, name: str) -> None:
+        await self._request("DELETE", f"{self._prefix}/definitions/{name}")
+
+    async def create_resource(self, resource: Resource) -> Resource:
+        response = await self._request(
+            "POST",
+            f"{self._prefix}/resources",
+            json=_RESOURCE_ADAPTER.dump_python(
+                resource, mode="json", context={"reveal_secrets": True}
+            ),
+        )
+        return _RESOURCE_ADAPTER.validate_python(response.json())
+
+    async def list_resources(self, kind: str | None = None) -> _List[Resource]:
+        response = await self._request("GET", f"{self._prefix}/resources", params={"kind": kind})
+        return _RESOURCE_LIST_ADAPTER.validate_python(response.json())
+
+    async def delete_resource(self, name: str) -> None:
+        await self._request("DELETE", f"{self._prefix}/resources/{name}")
+
+
+def _run_sync[R](coro: Coroutine[Any, Any, R]) -> R:
+    return asyncio.run(coro)
+
+
+class SyncRuntimeClient:
+    """Blocking convenience wrapper generated via ``asyncio.run`` (SPEC §4.1)."""
+
+    def __init__(self, base_url: str, token: str | TokenProvider | None = None) -> None:
+        self._base_url = base_url
+        self._token = token
+
+    def _call(self, fn: Callable[[RuntimeClient], Coroutine[Any, Any, T]]) -> T:
+        async def runner() -> T:
+            async with RuntimeClient(self._base_url, self._token) as client:
+                return await fn(client)
+
+        return _run_sync(runner())
+
+    def validate(self, defn: FlowDefinition | Mapping[str, object]) -> ValidationResult:
+        return self._call(lambda c: c.validate(defn))
+
+    def create_draft(self, defn: FlowDefinition) -> DefinitionInfo:
+        return self._call(lambda c: c.create_draft(defn))
+
+    def update_draft(self, name: str, defn: FlowDefinition) -> DefinitionInfo:
+        return self._call(lambda c: c.update_draft(name, defn))
+
+    def deploy(
+        self, name: str, *, version: int | None = None, ephemeral: bool = False
+    ) -> DeploymentInfo:
+        return self._call(lambda c: c.deploy(name, version=version, ephemeral=ephemeral))
+
+    def undeploy(self, name: str) -> None:
+        return self._call(lambda c: c.undeploy(name))
+
+    def get(self, name: str, *, include_definition: bool = False) -> DefinitionInfo:
+        return self._call(lambda c: c.get(name, include_definition=include_definition))
+
+    def list(self, status: str | None = None) -> _List[DefinitionInfo]:
+        return self._call(lambda c: c.list(status))
+
+    def export(self, name: str, version: int | None = None) -> FlowDefinition:
+        return self._call(lambda c: c.export(name, version))
+
+    def delete(self, name: str) -> None:
+        return self._call(lambda c: c.delete(name))
+
+    def create_resource(self, resource: Resource) -> Resource:
+        return self._call(lambda c: c.create_resource(resource))
+
+    def list_resources(self, kind: str | None = None) -> _List[Resource]:
+        return self._call(lambda c: c.list_resources(kind))
+
+    def delete_resource(self, name: str) -> None:
+        return self._call(lambda c: c.delete_resource(name))
+
+
+class SyncRegistryClient:
+    """Blocking convenience wrapper generated via ``asyncio.run`` (SPEC §4.1)."""
+
+    def __init__(self, base_url: str, token: str | TokenProvider | None = None) -> None:
+        self._base_url = base_url
+        self._token = token
+
+    def _call(self, fn: Callable[[RegistryClient], Coroutine[Any, Any, T]]) -> T:
+        async def runner() -> T:
+            async with RegistryClient(self._base_url, self._token) as client:
+                return await fn(client)
+
+        return _run_sync(runner())
+
+    def register(self, entry: RegistryEntryCreate) -> RegistryEntry:
+        return self._call(lambda c: c.register(entry))
+
+    def get(self, id: UUID) -> RegistryEntry:
+        return self._call(lambda c: c.get(id))
+
+    def update(self, id: UUID, patch: RegistryEntryPatch) -> RegistryEntry:
+        return self._call(lambda c: c.update(id, patch))
+
+    def delete(self, id: UUID) -> None:
+        return self._call(lambda c: c.delete(id))
+
+    def search(
+        self,
+        q: str = "",
+        tags: _List[str] | None = None,
+        kind: str | None = None,
+        status: str | None = None,
+        semantic: bool = False,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Page:
+        return self._call(
+            lambda c: c.search(
+                q,
+                tags=tags,
+                kind=kind,
+                status=status,
+                semantic=semantic,
+                limit=limit,
+                offset=offset,
+            )
+        )
+
+    def capabilities(self) -> Capabilities:
+        return self._call(lambda c: c.capabilities())
+
+
+__all__ = [
+    "RegistryClient",
+    "RuntimeClient",
+    "SyncRegistryClient",
+    "SyncRuntimeClient",
+]

agentplane_sdk/config.py

@@ -0,0 +1,78 @@
+"""CLI configuration resolution (SPEC §4.2).
+
+Order: flags → env (``AGENTPLANE_*``) → ``~/.config/agentplane/config.toml``.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from agentplane_sdk.auth import OidcClientCredentialsProvider, TokenProvider, as_token_provider
+
+CONFIG_PATH = Path.home() / ".config" / "agentplane" / "config.toml"
+
+
+class CliConfig(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    runtime_url: str | None = None
+    registry_url: str | None = None
+    token: str | None = None
+    oidc_issuer: str | None = None
+    oidc_client_id: str | None = None
+    oidc_client_secret: str | None = None
+    oidc_audience: str | None = None
+
+
+def _load_config_file(path: Path) -> CliConfig:
+    if not path.is_file():
+        return CliConfig()
+    with path.open("rb") as fh:
+        return CliConfig.model_validate(tomllib.load(fh))
+
+
+def resolve_config(
+    *,
+    runtime_url: str | None = None,
+    registry_url: str | None = None,
+    token: str | None = None,
+    config_path: Path | None = None,
+) -> CliConfig:
+    """Merge flags, environment and config file into one effective config."""
+    file_config = _load_config_file(config_path or CONFIG_PATH)
+
+    def pick(flag: str | None, env_name: str, file_value: str | None) -> str | None:
+        return flag or os.environ.get(env_name) or file_value
+
+    return CliConfig(
+        runtime_url=pick(runtime_url, "AGENTPLANE_RUNTIME_URL", file_config.runtime_url),
+        registry_url=pick(registry_url, "AGENTPLANE_REGISTRY_URL", file_config.registry_url),
+        token=pick(token, "AGENTPLANE_TOKEN", file_config.token),
+        oidc_issuer=pick(None, "AGENTPLANE_OIDC_ISSUER", file_config.oidc_issuer),
+        oidc_client_id=pick(None, "AGENTPLANE_OIDC_CLIENT_ID", file_config.oidc_client_id),
+        oidc_client_secret=pick(
+            None, "AGENTPLANE_OIDC_CLIENT_SECRET", file_config.oidc_client_secret
+        ),
+        oidc_audience=pick(None, "AGENTPLANE_OIDC_AUDIENCE", file_config.oidc_audience),
+    )
+
+
+def token_provider_from_config(config: CliConfig) -> TokenProvider | None:
+    """Static token wins; otherwise OIDC client credentials when configured."""
+    if config.token:
+        return as_token_provider(config.token)
+    if config.oidc_issuer and config.oidc_client_id and config.oidc_client_secret:
+        return OidcClientCredentialsProvider(
+            config.oidc_issuer,
+            config.oidc_client_id,
+            config.oidc_client_secret,
+            audience=config.oidc_audience,
+        )
+    return None
+
+
+__all__ = ["CONFIG_PATH", "CliConfig", "resolve_config", "token_provider_from_config"]

agentplane_sdk/errors.py

@@ -0,0 +1,54 @@
+"""SDK error hierarchy mapped from HTTP responses."""
+
+from __future__ import annotations
+
+from agentplane_core import ValidationResult
+
+
+class AgentplaneError(Exception):
+    """Base class for all SDK errors."""
+
+
+class TransportError(AgentplaneError):
+    """Network-level failure (connect, timeout, DNS)."""
+
+
+class AuthError(AgentplaneError):
+    """401/403 or token acquisition failure."""
+
+
+class NotFoundError(AgentplaneError):
+    """404 for a named object or entry."""
+
+
+class ConflictError(AgentplaneError):
+    """409 — duplicate name or referenced object."""
+
+
+class ApiError(AgentplaneError):
+    """Any other non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"HTTP {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class ValidationFailedError(AgentplaneError):
+    """422 with a machine-readable ValidationResult."""
+
+    def __init__(self, result: ValidationResult) -> None:
+        lines = ", ".join(f"{i.code}@{i.path}" for i in result.issues)
+        super().__init__(f"validation failed: {lines}")
+        self.result = result
+
+
+__all__ = [
+    "AgentplaneError",
+    "ApiError",
+    "AuthError",
+    "ConflictError",
+    "NotFoundError",
+    "TransportError",
+    "ValidationFailedError",
+]

agentplane_sdk-0.0.1.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: agentplane-sdk
+Version: 0.0.1
+Summary: agentplane typed client + CLI
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: agentplane-core<0.1.0,>=0.0.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# agentplane-sdk
+
+Thin typed client + CLI for the agentplane platform. Everything the SDK does
+is possible with plain HTTP — the SDK is convenience, not a requirement.
+
+```python
+from agentplane_sdk import RuntimeClient
+
+async with RuntimeClient("https://api.example/runtime", token="…") as client:
+    info = await client.deploy("support-rag")
+    print(info.endpoint_url)
+```
+
+CLI:
+
+```
+agentplane validate flow.yaml
+agentplane deploy flow.yaml [--draft]
+agentplane undeploy <name>
+agentplane list [--status deployed] [--json]
+agentplane export <name> [-o flow.yaml]
+agentplane search "invoice" [--tags rag] [--semantic]
+agentplane resources list|create -f res.yaml|delete <name>
+```
+
+Config resolution: flags → env (`AGENTPLANE_RUNTIME_URL`,
+`AGENTPLANE_REGISTRY_URL`, `AGENTPLANE_TOKEN` or OIDC vars) →
+`~/.config/agentplane/config.toml`. Exit codes: 0 ok, 1 validation failed,
+2 transport/auth error, 3 not found.

agentplane_sdk-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentplane_sdk/__init__.py,sha256=Kz_feTTmj5mF8Y0It8gEn9kkFDzFRbgs0KBBM-UMH2g,874
+agentplane_sdk/auth.py,sha256=K9jjuHv34FmCT-nH1R9DZHih1hAcpujv9iK-g-Cs2oQ,3337
+agentplane_sdk/cli.py,sha256=aVb_XvLg-t6Dl-qq0Gwns1ngCSXiI3sVnjeTVflYlRk,10887
+agentplane_sdk/client.py,sha256=VC2CQzHKdl7182VcKRy64hygtdXbTc3v4z9PfZwg8Q8,13901
+agentplane_sdk/config.py,sha256=S_cMisfJY3R1zwaDilxSPOCug-2fybZJseeHFBIlpWg,2716
+agentplane_sdk/errors.py,sha256=cHKdq5cjPYeGZ4xwKaBRpiDuTCq7ioZ30jdv-S23Nc0,1320
+agentplane_sdk-0.0.1.dist-info/METADATA,sha256=jz-_cFj-x-DJSFuCZBj2_fHEASto6Beb_ST5QO_Hwh0,1239
+agentplane_sdk-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agentplane_sdk-0.0.1.dist-info/entry_points.txt,sha256=ZmcN_fr8ZAin63wlIe7g0zhKZeV-vUf82XJsNMq8wMM,54
+agentplane_sdk-0.0.1.dist-info/RECORD,,

agentplane_sdk-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentplane_sdk-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentplane = agentplane_sdk.cli:app