podium-sdk 0.1.0__tar.gz

podium_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: podium-sdk
+Version: 0.1.0
+Summary: Thin HTTP client for the Podium registry.
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10

podium_sdk-0.1.0/README.md

@@ -0,0 +1,29 @@
+# podium-py
+
+Thin HTTP client for the Podium registry.
+
+Distributed on PyPI as `podium-sdk`; the import name is `podium`:
+
+```sh
+pip install podium-sdk
+```
+
+```python
+from podium import Client
+
+client = Client.from_env()
+results = client.search_artifacts("variance", type="skill")
+artifact = client.load_artifact(results.results[0].id)
+print(artifact.manifest_body)
+```
+
+The client covers the meta-tool surface. OAuth device code, streaming
+subscriptions, and dependency walks remain on the roadmap.
+
+## Test
+
+```sh
+cd sdks/podium-py
+pip install -e .
+pytest
+```

podium_sdk-0.1.0/podium/__init__.py

@@ -0,0 +1,13 @@
+"""Podium Python SDK — thin HTTP client over the registry API."""
+
+from .client import Client, DeviceCodeRequired, RegistryError
+
+try:
+    # Generated by setuptools-scm at build/install time. See pyproject.toml
+    # → [tool.setuptools_scm]. Gitignored in source; regenerated by any
+    # `pip install`.
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["Client", "DeviceCodeRequired", "RegistryError"]

podium_sdk-0.1.0/podium/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g9ba62dc66'

podium_sdk-0.1.0/podium/client.py

@@ -0,0 +1,287 @@
+"""Podium HTTP client (spec §7.6 surface)."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class RegistryError(Exception):
+    """Raised when the registry returns a structured error envelope (§6.10)."""
+
+    def __init__(self, code: str, message: str, retryable: bool = False) -> None:
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        super().__init__(f"{code}: {message}")
+
+
+class DeviceCodeRequired(Exception):
+    """Raised when the configured identity provider needs a device-code flow.
+
+    Stage 3 does not implement OAuth; this exception is wired so callers
+    can catch it once oauth-device-code lands in Phase 11.
+    """
+
+
+@dataclass
+class ArtifactDescriptor:
+    """A single result returned by search_artifacts and load_domain."""
+
+    id: str
+    type: str
+    version: str = ""
+    description: str = ""
+    tags: list[str] = field(default_factory=list)
+    score: float = 0.0
+
+
+@dataclass
+class SearchResult:
+    """Envelope returned by search_artifacts and search_domains."""
+
+    query: str = ""
+    total_matched: int = 0
+    results: list[ArtifactDescriptor] = field(default_factory=list)
+    domains: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class LoadedArtifact:
+    """Manifest body and bundled resources returned by load_artifact."""
+
+    id: str
+    type: str
+    version: str
+    manifest_body: str
+    frontmatter: str
+    resources: dict[str, str] = field(default_factory=dict)
+
+
+class Client:
+    """Thin HTTP client over the registry's meta-tool API.
+
+    Construct with an explicit registry URL or call `Client.from_env()` to
+    pick up `PODIUM_REGISTRY`, `PODIUM_IDENTITY_PROVIDER`, and
+    `PODIUM_OVERLAY_PATH` per §6.2.
+    """
+
+    def __init__(
+        self,
+        registry: str,
+        *,
+        identity_provider: str = "oauth-device-code",
+        overlay_path: str | None = None,
+    ) -> None:
+        self.registry = registry.rstrip("/")
+        self.identity_provider = identity_provider
+        self.overlay_path = overlay_path
+
+    @classmethod
+    def from_env(cls) -> "Client":
+        registry = os.environ.get("PODIUM_REGISTRY")
+        if not registry:
+            raise RuntimeError("PODIUM_REGISTRY environment variable is required")
+        return cls(
+            registry=registry,
+            identity_provider=os.environ.get("PODIUM_IDENTITY_PROVIDER", "oauth-device-code"),
+            overlay_path=os.environ.get("PODIUM_OVERLAY_PATH"),
+        )
+
+    def load_domain(self, path: str = "", depth: int = 1) -> dict[str, Any]:
+        params = {}
+        if path:
+            params["path"] = path
+        if depth:
+            params["depth"] = depth
+        return self._get("/v1/load_domain", params)
+
+    def search_domains(
+        self, query: str = "", *, scope: str = "", top_k: int = 10
+    ) -> SearchResult:
+        params = {"top_k": top_k}
+        if query:
+            params["query"] = query
+        if scope:
+            params["scope"] = scope
+        body = self._get("/v1/search_domains", params)
+        return SearchResult(
+            query=body.get("query", ""),
+            total_matched=body.get("total_matched", 0),
+            domains=body.get("domains", []) or [],
+        )
+
+    def search_artifacts(
+        self,
+        query: str = "",
+        *,
+        type: str = "",
+        scope: str = "",
+        tags: list[str] | None = None,
+        top_k: int = 10,
+    ) -> SearchResult:
+        params: dict[str, Any] = {"top_k": top_k}
+        if query:
+            params["query"] = query
+        if type:
+            params["type"] = type
+        if scope:
+            params["scope"] = scope
+        if tags:
+            params["tags"] = ",".join(tags)
+        body = self._get("/v1/search_artifacts", params)
+        results = [
+            ArtifactDescriptor(
+                id=r.get("id", ""),
+                type=r.get("type", ""),
+                version=r.get("version", ""),
+                description=r.get("description", ""),
+                tags=r.get("tags") or [],
+                score=r.get("score", 0.0),
+            )
+            for r in body.get("results", []) or []
+        ]
+        return SearchResult(
+            query=body.get("query", ""),
+            total_matched=body.get("total_matched", 0),
+            results=results,
+        )
+
+    def load_artifact(self, artifact_id: str, *, version: str = "") -> LoadedArtifact:
+        params = {"id": artifact_id}
+        if version:
+            params["version"] = version
+        body = self._get("/v1/load_artifact", params)
+        return LoadedArtifact(
+            id=body.get("id", artifact_id),
+            type=body.get("type", ""),
+            version=body.get("version", ""),
+            manifest_body=body.get("manifest_body", ""),
+            frontmatter=body.get("frontmatter", ""),
+            resources=body.get("resources", {}) or {},
+        )
+
+    def load_artifacts(
+        self,
+        ids: list[str],
+        *,
+        session_id: str = "",
+        harness: str = "",
+        version_pins: dict[str, str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Bulk-fetch artifacts via §7.6.2 POST /v1/artifacts:batchLoad.
+
+        The §7.6.2 hard cap is 50 IDs per request; the SDK splits
+        larger sets transparently. Each returned envelope carries
+        ``status="ok"`` with the manifest body, or ``status="error"``
+        with a §6.10 envelope. Partial failure does not raise.
+        """
+        if not ids:
+            return []
+        out: list[dict[str, Any]] = []
+        chunk_size = 50
+        for chunk_start in range(0, len(ids), chunk_size):
+            chunk = ids[chunk_start : chunk_start + chunk_size]
+            body: dict[str, Any] = {"ids": chunk}
+            if session_id:
+                body["session_id"] = session_id
+            if harness:
+                body["harness"] = harness
+            if version_pins:
+                body["version_pins"] = {k: v for k, v in version_pins.items() if k in chunk}
+            data = json.dumps(body).encode()
+            req = urllib.request.Request(
+                self.registry + "/v1/artifacts:batchLoad",
+                data=data,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req) as resp:
+                    raw = resp.read()
+            except urllib.error.HTTPError as exc:
+                self._raise_from_http_error(exc)
+            out.extend(json.loads(raw))
+        return out
+
+    def dependents_of(self, artifact_id: str) -> list[ArtifactDescriptor]:
+        """Return artifacts that depend on artifact_id (spec §4.7.6)."""
+        body = self._get("/v1/dependents", {"id": artifact_id})
+        return [
+            ArtifactDescriptor(
+                id=r.get("id", ""),
+                type=r.get("type", ""),
+                version=r.get("version", ""),
+                description=r.get("description", ""),
+                tags=r.get("tags") or [],
+            )
+            for r in body.get("dependents", []) or []
+        ]
+
+    def preview_scope(
+        self,
+        *,
+        scope: str = "",
+        type: str = "",
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Preview a scope's effective artifact set (spec §6.4)."""
+        params: dict[str, Any] = {}
+        if scope:
+            params["scope"] = scope
+        if type:
+            params["type"] = type
+        if tags:
+            params["tags"] = ",".join(tags)
+        return self._get("/v1/scope/preview", params)
+
+    def subscribe(self, *, types: list[str] | None = None):
+        """Yield NDJSON events from /v1/events (spec §7.6).
+
+        Each yielded value is the parsed JSON body of one event. The
+        iterator runs until the underlying connection closes; callers
+        wrap it in a try/except to handle reconnects.
+        """
+        params: dict[str, Any] = {}
+        if types:
+            params["types"] = ",".join(types)
+        url = self.registry + "/v1/events"
+        if params:
+            url = url + "?" + urllib.parse.urlencode(params)
+        req = urllib.request.Request(url)
+        with urllib.request.urlopen(req) as resp:
+            for raw in resp:
+                line = raw.decode("utf-8").rstrip("\n")
+                if not line:
+                    continue
+                try:
+                    yield json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+    def _get(self, path: str, params: dict[str, Any]) -> dict[str, Any]:
+        url = self.registry + path
+        if params:
+            url = url + "?" + urllib.parse.urlencode(params)
+        req = urllib.request.Request(url)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                body = resp.read()
+        except urllib.error.HTTPError as exc:
+            self._raise_from_http_error(exc)
+        return json.loads(body)
+
+    def _raise_from_http_error(self, exc: urllib.error.HTTPError) -> None:
+        try:
+            envelope = json.loads(exc.read())
+        except Exception:
+            raise RegistryError("registry.unknown", f"HTTP {exc.code}: {exc.reason}") from exc
+        raise RegistryError(
+            code=envelope.get("code", "registry.unknown"),
+            message=envelope.get("message", str(exc)),
+            retryable=envelope.get("retryable", False),
+        )

podium_sdk-0.1.0/podium_sdk.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: podium-sdk
+Version: 0.1.0
+Summary: Thin HTTP client for the Podium registry.
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10

podium_sdk-0.1.0/podium_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+podium/__init__.py
+podium/_version.py
+podium/client.py
+podium_sdk.egg-info/PKG-INFO
+podium_sdk.egg-info/SOURCES.txt
+podium_sdk.egg-info/dependency_links.txt
+podium_sdk.egg-info/top_level.txt
+tests/test_client.py

podium_sdk-0.1.0/podium_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

podium_sdk-0.1.0/podium_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+podium

podium_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI. The plain "podium" name was taken; the
+# Python import name stays `podium` (PEP 8 prefers single-word
+# package names) so `from podium import Client` still works after
+# `pip install podium-sdk`. Same pattern as Pillow / BeautifulSoup4.
+name = "podium-sdk"
+dynamic = ["version"]
+description = "Thin HTTP client for the Podium registry."
+requires-python = ">=3.10"
+license = { text = "MIT" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["podium*"]
+
+# setuptools-scm derives the version from git tags at build time —
+# `pip install -e .` from a clean checkout at tag v0.1.0 produces
+# podium-sdk 0.1.0; an untagged commit produces 0.1.1.dev<N>+g<sha>.
+# Mirrors the Go side's `internal/buildinfo` + ldflags pattern.
+[tool.setuptools_scm]
+# pyproject.toml sits in sdks/podium-py/; the git root is two levels up.
+root = "../.."
+# Generated at build time and imported by podium/__init__.py.
+# Gitignored — never check it in.
+version_file = "podium/_version.py"
+# Local-version separator (PEP 440); keeps PyPI-uploaded versions
+# clean while local dev builds carry the git sha.
+local_scheme = "node-and-date"
+# Fallback when building from a tarball that has no .git directory.
+fallback_version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

podium_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

podium_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,186 @@
+"""Tests for the Podium Python SDK."""
+
+from __future__ import annotations
+
+import http.server
+import json
+import socket
+import threading
+
+import pytest
+
+from podium import Client, RegistryError
+
+
+class _StubHandler(http.server.BaseHTTPRequestHandler):
+    """Records the last request and replies with whatever the test sets."""
+
+    def log_message(self, format, *args):  # noqa: A002 - signature inherited
+        pass
+
+    def do_GET(self):  # noqa: N802 - signature inherited
+        self.server.last_path = self.path  # type: ignore[attr-defined]
+        body = json.dumps(self.server.next_response).encode()  # type: ignore[attr-defined]
+        self.send_response(self.server.next_status)  # type: ignore[attr-defined]
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):  # noqa: N802 - signature inherited
+        self.server.last_path = self.path  # type: ignore[attr-defined]
+        length = int(self.headers.get("Content-Length", "0"))
+        self.server.last_body = self.rfile.read(length)  # type: ignore[attr-defined]
+        body = json.dumps(self.server.next_response).encode()  # type: ignore[attr-defined]
+        self.send_response(self.server.next_status)  # type: ignore[attr-defined]
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+@pytest.fixture()
+def stub_server():
+    sock = socket.socket()
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+
+    server = http.server.HTTPServer(("127.0.0.1", port), _StubHandler)
+    server.next_status = 200
+    server.next_response = {}
+    server.last_path = ""
+
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    yield server
+    server.shutdown()
+    thread.join()
+
+
+# Spec: §7.6 SDK surface — search_artifacts forwards to GET /v1/search_artifacts
+# and decodes the SearchResult envelope.
+def test_search_artifacts_forwards_query(stub_server):
+    stub_server.next_response = {
+        "query": "variance",
+        "total_matched": 1,
+        "results": [
+            {
+                "id": "finance/run-variance",
+                "type": "skill",
+                "version": "1.0.0",
+                "description": "Variance analysis",
+            },
+        ],
+    }
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    out = client.search_artifacts("variance", top_k=5)
+
+    assert "search_artifacts" in stub_server.last_path
+    assert "query=variance" in stub_server.last_path
+    assert out.total_matched == 1
+    assert out.results[0].id == "finance/run-variance"
+
+
+# Spec: §7.6 SDK surface — load_artifact returns a LoadedArtifact with
+# manifest body and bundled resources.
+def test_load_artifact_returns_manifest_and_resources(stub_server):
+    stub_server.next_response = {
+        "id": "finance/run",
+        "type": "skill",
+        "version": "1.0.0",
+        "manifest_body": "Body.",
+        "frontmatter": "---\ntype: skill\n---\n",
+        "resources": {"scripts/run.py": "print('run')\n"},
+    }
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    art = client.load_artifact("finance/run")
+
+    assert art.id == "finance/run"
+    assert art.manifest_body == "Body."
+    assert art.resources == {"scripts/run.py": "print('run')\n"}
+
+
+# Spec: §6.10 — error envelopes from the registry surface as RegistryError
+# with the namespaced code preserved.
+def test_registry_error_envelope_translates_to_exception(stub_server):
+    stub_server.next_status = 404
+    stub_server.next_response = {
+        "code": "registry.not_found",
+        "message": "artifact not found",
+        "retryable": False,
+    }
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    with pytest.raises(RegistryError) as exc:
+        client.load_artifact("does/not/exist")
+    assert exc.value.code == "registry.not_found"
+    assert "artifact not found" in exc.value.message
+
+
+# Spec: §6.2 — Client.from_env reads PODIUM_REGISTRY and provider env vars.
+def test_from_env_reads_registry(monkeypatch):
+    monkeypatch.setenv("PODIUM_REGISTRY", "http://127.0.0.1:9999")
+    monkeypatch.setenv("PODIUM_OVERLAY_PATH", "/tmp/overlay")
+    client = Client.from_env()
+    assert client.registry == "http://127.0.0.1:9999"
+    assert client.overlay_path == "/tmp/overlay"
+
+
+# Spec: §4.7.6 — dependents_of returns artifacts that depend on the
+# given id, surfaced as ArtifactDescriptor instances.
+def test_dependents_of_decodes_envelope(stub_server):
+    stub_server.next_response = {
+        "dependents": [
+            {"id": "finance/run", "type": "skill", "version": "1.0.0",
+             "description": "Variance"},
+        ],
+    }
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    deps = client.dependents_of("finance/glossary")
+    assert "/v1/dependents" in stub_server.last_path
+    assert len(deps) == 1
+    assert deps[0].id == "finance/run"
+
+
+# Spec: §6.4 — preview_scope hits /v1/scope/preview with the
+# constraints; the SDK passes the response through unchanged so
+# callers can inspect the full envelope.
+def test_preview_scope_passes_constraints(stub_server):
+    stub_server.next_response = {
+        "scope": "finance/",
+        "matched": 12,
+        "results": [],
+    }
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    out = client.preview_scope(scope="finance/", type="skill", tags=["q4"])
+    assert "/v1/scope/preview" in stub_server.last_path
+    assert "scope=finance" in stub_server.last_path
+    assert "tags=q4" in stub_server.last_path
+    assert out["matched"] == 12
+
+
+# Spec: §7.6.2 — load_artifacts POSTs to /v1/artifacts:batchLoad
+# and returns per-item envelopes; partial failures do not raise.
+def test_load_artifacts_returns_envelopes(stub_server):
+    stub_server.next_response = [
+        {"id": "a", "status": "ok", "version": "1.0.0", "content_hash": "sha256:a"},
+        {"id": "b", "status": "error", "error": {"code": "registry.not_found", "message": "missing"}},
+    ]
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    out = client.load_artifacts(["a", "b"])
+
+    assert "/v1/artifacts:batchLoad" in stub_server.last_path
+    body = json.loads(stub_server.last_body)
+    assert body["ids"] == ["a", "b"]
+    assert len(out) == 2
+    assert out[0]["status"] == "ok"
+    assert out[1]["status"] == "error"
+
+
+# Spec: §7.6.2 — empty ids list short-circuits to an empty
+# response without a network call.
+def test_load_artifacts_empty_short_circuits(stub_server):
+    client = Client(registry=f"http://127.0.0.1:{stub_server.server_port}")
+    out = client.load_artifacts([])
+    assert out == []
+    assert stub_server.last_path == ""