poelis-sdk 0.1.0__py3-none-any.whl

poelis_sdk/.github/workflows/sdk-ci.yml

@@ -0,0 +1,34 @@
+name: SDK CI
+
+on:
+  push:
+    paths:
+      - 'sdk/python/**'
+  pull_request:
+    paths:
+      - 'sdk/python/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/python
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+      - name: Install deps
+        run: |
+          ~/.local/bin/uv pip install -e .
+          ~/.local/bin/uv pip install pytest ruff
+      - name: Lint (ruff)
+        run: ~/.local/bin/uv run ruff check src tests
+      - name: Test (pytest)
+        run: ~/.local/bin/uv run pytest -q
+
+

poelis_sdk/.github/workflows/sdk-docs.yml

@@ -0,0 +1,55 @@
+name: SDK Docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'sdk/python/docs/**'
+      - 'sdk/python/mkdocs.yml'
+      - 'sdk/python/src/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/python
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+      - name: Install docs deps
+        run: |
+          ~/.local/bin/uv pip install -e .[docs]
+      - name: Build docs
+        run: |
+          ~/.local/bin/uv run mkdocs build --strict
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: sdk/python/site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+

poelis_sdk/.github/workflows/sdk-publish-testpypi.yml

@@ -0,0 +1,31 @@
+name: SDK Publish (TestPyPI)
+
+on:
+  push:
+    tags:
+      - 'sdk-v*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/python
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+      - name: Build wheel and sdist
+        run: ~/.local/bin/uv build
+      - name: Publish to TestPyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        run: |
+          ~/.local/bin/uv pip install twine
+          ~/.local/bin/uv run twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+

poelis_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Poelis Python SDK public exports."""
+
+from .client import PoelisClient
+
+__version__ = "0.1.0"
+__all__ = ["PoelisClient"]
+
+

poelis_sdk/_transport.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+"""HTTP transport abstraction for the Poelis SDK.
+
+Provides a thin wrapper around httpx with sensible defaults for timeouts,
+retries, and headers including authentication and optional org scoping.
+"""
+
+from typing import Any, Dict, Mapping, Optional
+
+import time
+import random
+import httpx
+
+from .exceptions import ClientError, HTTPError, NotFoundError, RateLimitError, ServerError, UnauthorizedError
+
+
+class Transport:
+    """Synchronous HTTP transport using httpx.Client.
+
+    This wrapper centralizes auth headers, tenant scoping, timeouts, and
+    retry behavior. Retries are implemented here in a simple, explicit way to
+    avoid external dependencies, following the professional defaults defined
+    in the SDK planning document.
+    """
+
+    def __init__(self, base_url: str, api_key: str, org_id: str, timeout_seconds: float) -> None:
+        """Initialize the transport.
+
+        Args:
+            base_url: Base API URL.
+            token: Bearer token for Authorization header.
+            org_id: Optional organization id for tenant scoping.
+            timeout_seconds: Request timeout in seconds.
+        """
+
+        self._client = httpx.Client(base_url=base_url, timeout=timeout_seconds)
+        self._api_key = api_key
+        self._org_id = org_id
+        self._timeout = timeout_seconds
+
+    def _headers(self, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        headers["Authorization"] = f"ApiKey {self._api_key}"
+        headers["X-Poelis-Org"] = self._org_id
+        if extra:
+            headers.update(dict(extra))
+        return headers
+
+    def get(self, path: str, params: Optional[Mapping[str, Any]] = None) -> httpx.Response:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: Any = None) -> httpx.Response:  # noqa: A003
+        return self._request("POST", path, json=json)
+
+    def patch(self, path: str, json: Any = None) -> httpx.Response:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> httpx.Response:
+        return self._request("DELETE", path)
+
+    def graphql(self, query: str, variables: Optional[Mapping[str, Any]] = None) -> httpx.Response:
+        """Post a GraphQL operation to /v1/graphql.
+
+        Args:
+            query: GraphQL document string.
+            variables: Optional mapping of variables.
+        """
+
+        payload: Dict[str, Any] = {"query": query, "variables": dict(variables or {})}
+        return self._request("POST", "/v1/graphql", json=payload)
+
+    def _request(self, method: str, path: str, *, params: Optional[Mapping[str, Any]] = None, json: Any = None) -> httpx.Response:
+        # Retries: up to 3 attempts on idempotent GET/HEAD and 429s respecting Retry-After.
+        max_attempts = 3
+        last_exc: Optional[Exception] = None
+        for attempt in range(1, max_attempts + 1):
+            try:
+                response = self._client.request(method, path, headers=self._headers(), params=params, json=json)
+                # Map common error codes
+                if 200 <= response.status_code < 300:
+                    return response
+                if response.status_code == 401:
+                    raise UnauthorizedError(401, message=_safe_message(response))
+                if response.status_code == 404:
+                    raise NotFoundError(404, message=_safe_message(response))
+                if response.status_code == 429:
+                    retry_after_header = response.headers.get("Retry-After")
+                    retry_after: Optional[float] = None
+                    if retry_after_header:
+                        try:
+                            retry_after = float(retry_after_header)
+                        except Exception:
+                            retry_after = None
+                    if attempt < max_attempts:
+                        if retry_after is not None:
+                            time.sleep(retry_after)
+                        else:
+                            # fallback exponential backoff with jitter
+                            time.sleep(_backoff_sleep(attempt))
+                        continue
+                    raise RateLimitError(429, message=_safe_message(response), retry_after_seconds=retry_after)
+                if 400 <= response.status_code < 500:
+                    raise ClientError(response.status_code, message=_safe_message(response))
+                if 500 <= response.status_code < 600:
+                    # Retry on idempotent
+                    if method in {"GET", "HEAD"} and attempt < max_attempts:
+                        time.sleep(_backoff_sleep(attempt))
+                        continue
+                    raise ServerError(response.status_code, message=_safe_message(response))
+                # Fallback
+                raise HTTPError(response.status_code, message=_safe_message(response))
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if method not in {"GET", "HEAD"} or attempt == max_attempts:
+                    raise
+        assert last_exc is not None
+        raise last_exc
+
+
+def _safe_message(response: httpx.Response) -> str:
+    try:
+        data = response.json()
+        if isinstance(data, dict):
+            msg = data.get("message") or data.get("detail") or data.get("error")
+            if isinstance(msg, str):
+                return msg
+        return response.text
+    except Exception:
+        return response.text
+
+
+def _backoff_sleep(attempt: int) -> float:
+    # Exponential backoff with jitter: base 0.5s, cap ~4s
+    base = 0.5 * (2 ** (attempt - 1))
+    return min(4.0, base + random.uniform(0, 0.25))
+
+

poelis_sdk/browser.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+"""GraphQL-backed dot-path browser for Poelis SDK.
+
+Provides lazy, name-based navigation across workspaces → products → items → child items,
+with optional property listing on items. Designed for notebook UX.
+"""
+
+from typing import Any, Dict, List, Optional
+import re
+
+
+class _Node:
+    def __init__(self, client: Any, level: str, parent: Optional["_Node"], node_id: Optional[str], name: Optional[str]) -> None:
+        self._client = client
+        self._level = level
+        self._parent = parent
+        self._id = node_id
+        self._name = name
+        self._children_cache: Dict[str, "_Node"] = {}
+        self._props_cache: Optional[List[Dict[str, Any]]] = None
+
+    def __repr__(self) -> str:  # pragma: no cover - notebook UX
+        path = []
+        cur: Optional[_Node] = self
+        while cur is not None and cur._name:
+            path.append(cur._name)
+            cur = cur._parent
+        return f"<{self._level}:{'.'.join(reversed(path)) or '*'}>"
+
+    def __dir__(self) -> List[str]:  # pragma: no cover - notebook UX
+        # Ensure children are loaded so TAB shows options immediately
+        self._load_children()
+        keys = list(self._children_cache.keys()) + ["properties", "id", "name", "refresh", "names", "props"]
+        if self._level == "item":
+            # Include property names directly on item for suggestions
+            prop_keys = list(self._props_key_map().keys())
+            keys.extend(prop_keys)
+        return sorted(keys)
+
+    @property
+    def id(self) -> Optional[str]:
+        return self._id
+
+    @property
+    def name(self) -> Optional[str]:
+        return self._name
+
+    def refresh(self) -> "_Node":
+        self._children_cache.clear()
+        self._props_cache = None
+        return self
+
+    def names(self) -> List[str]:
+        """Return display names of children at this level (forces a lazy load)."""
+        self._load_children()
+        return [child._name or "" for child in self._children_cache.values()]
+
+    def __getattr__(self, attr: str) -> Any:
+        if attr in {"properties", "id", "name", "refresh"}:
+            return object.__getattribute__(self, attr)
+        if attr == "props":  # item-level properties pseudo-node
+            if self._level != "item":
+                raise AttributeError("props")
+            return _PropsNode(self)
+        if attr not in self._children_cache:
+            self._load_children()
+        if attr in self._children_cache:
+            return self._children_cache[attr]
+        # Expose properties as direct attributes on item level
+        if self._level == "item":
+            pk = self._props_key_map()
+            if attr in pk:
+                return pk[attr]
+        raise AttributeError(attr)
+
+    def __getitem__(self, key: str) -> "_Node":
+        """Access child by display name or a safe attribute key.
+
+        This enables names with spaces or symbols: browser["Workspace Name"].
+        """
+        self._load_children()
+        if key in self._children_cache:
+            return self._children_cache[key]
+        for child in self._children_cache.values():
+            if child._name == key:
+                return child
+        safe = _safe_key(key)
+        if safe in self._children_cache:
+            return self._children_cache[safe]
+        raise KeyError(key)
+
+    @property
+    def properties(self) -> List[Dict[str, Any]]:
+        if self._props_cache is not None:
+            return self._props_cache
+        if self._level != "item":
+            self._props_cache = []
+            return self._props_cache
+        # Try direct properties(item_id: ...) first; fallback to searchProperties
+        q = (
+            "query($iid: ID!) {\n"
+            "  properties(item_id: $iid) {\n"
+            "    __typename id name owner\n"
+            "    ... on NumericProperty { integerPart exponent category }\n"
+            "    ... on TextProperty { value }\n"
+            "    ... on DateProperty { value }\n"
+            "  }\n"
+            "}"
+        )
+        try:
+            r = self._client._transport.graphql(q, {"iid": self._id})
+            r.raise_for_status()
+            data = r.json()
+            if "errors" in data:
+                raise RuntimeError(data["errors"])  # trigger fallback
+            self._props_cache = data.get("data", {}).get("properties", []) or []
+        except Exception:
+            q2 = (
+                "query($iid: ID!, $limit: Int!, $offset: Int!) {\n"
+                "  searchProperties(q: \"*\", itemId: $iid, limit: $limit, offset: $offset) {\n"
+                "    hits { id name propertyType category textValue numericValue dateValue owner }\n"
+                "  }\n"
+                "}"
+            )
+            r2 = self._client._transport.graphql(q2, {"iid": self._id, "limit": 100, "offset": 0})
+            r2.raise_for_status()
+            data2 = r2.json()
+            if "errors" in data2:
+                raise RuntimeError(data2["errors"])  # propagate
+            self._props_cache = data2.get("data", {}).get("searchProperties", {}).get("hits", []) or []
+        return self._props_cache
+
+    def _props_key_map(self) -> Dict[str, Dict[str, Any]]:
+        """Map safe keys to property wrappers for item-level attribute access."""
+        out: Dict[str, Dict[str, Any]] = {}
+        if self._level != "item":
+            return out
+        props = self.properties
+        for pr in props:
+            display = pr.get("name") or pr.get("id")
+            safe = _safe_key(str(display))
+            out[safe] = _PropWrapper(pr)
+        return out
+
+    def _load_children(self) -> None:
+        if self._level == "root":
+            rows = self._client.workspaces.list(limit=200, offset=0)
+            for w in rows:
+                display = w.get("name") or str(w.get("id"))
+                nm = _safe_key(display)
+                self._children_cache[nm] = _Node(self._client, "workspace", self, w["id"], display)
+        elif self._level == "workspace":
+            page = self._client.products.list_by_workspace(workspace_id=self._id, limit=200, offset=0)
+            for p in page.data:
+                display = p.name or str(p.id)
+                nm = _safe_key(display)
+                self._children_cache[nm] = _Node(self._client, "product", self, p.id, display)
+        elif self._level == "product":
+            rows = self._client.items.list_by_product(product_id=self._id, limit=1000, offset=0)
+            for it in rows:
+                if it.get("parentId") is None:
+                    display = it.get("name") or str(it["id"]) 
+                    nm = _safe_key(display)
+                    self._children_cache[nm] = _Node(self._client, "item", self, it["id"], display)
+        elif self._level == "item":
+            # Fetch children items by parent; derive productId from ancestor product
+            anc = self
+            pid: Optional[str] = None
+            while anc is not None:
+                if anc._level == "product":
+                    pid = anc._id
+                    break
+                anc = anc._parent  # type: ignore[assignment]
+            if not pid:
+                return
+            q = (
+                "query($pid: ID!, $parent: ID!, $limit: Int!, $offset: Int!) {\n"
+                "  items(productId: $pid, parentItemId: $parent, limit: $limit, offset: $offset) { id name code description productId parentId owner }\n"
+                "}"
+            )
+            r = self._client._transport.graphql(q, {"pid": pid, "parent": self._id, "limit": 1000, "offset": 0})
+            r.raise_for_status()
+            data = r.json()
+            if "errors" in data:
+                raise RuntimeError(data["errors"])  # surface
+            rows = data.get("data", {}).get("items", []) or []
+            for it2 in rows:
+                # Skip the current item (GraphQL returns parent + direct children)
+                if str(it2.get("id")) == str(self._id):
+                    continue
+                display = it2.get("name") or str(it2["id"]) 
+                nm = _safe_key(display)
+                self._children_cache[nm] = _Node(self._client, "item", self, it2["id"], display)
+
+
+class Browser:
+    """Public browser entrypoint."""
+
+    def __init__(self, client: Any) -> None:
+        self._root = _Node(client, "root", None, None, None)
+
+    def __getattr__(self, attr: str) -> Any:  # pragma: no cover - notebook UX
+        return getattr(self._root, attr)
+
+    def __repr__(self) -> str:  # pragma: no cover - notebook UX
+        return "<browser root>"
+
+    def __getitem__(self, key: str) -> Any:  # pragma: no cover - notebook UX
+        """Delegate index-based access to the root node so names work: browser["Workspace Name"]."""
+        return self._root[key]
+
+    def __dir__(self) -> list[str]:  # pragma: no cover - notebook UX
+        # Ensure children are loaded so TAB shows options
+        self._root._load_children()
+        return sorted([*self._root._children_cache.keys(), "names"]) 
+
+
+def _safe_key(name: str) -> str:
+    """Convert arbitrary display name to a safe attribute key (letters/digits/_)."""
+    key = re.sub(r"[^0-9a-zA-Z_]+", "_", name)
+    key = key.strip("_")
+    return key or "_"
+
+
+class _PropsNode:
+    """Pseudo-node that exposes item properties as child attributes by display name.
+
+    Usage: item.props.<Property_Name> or item.props["Property Name"].
+    Returns the raw property dictionaries from GraphQL.
+    """
+
+    def __init__(self, item_node: _Node) -> None:
+        self._item = item_node
+        self._children_cache: Dict[str, _PropWrapper] = {}
+        self._names: List[str] = []
+
+    def __repr__(self) -> str:  # pragma: no cover - notebook UX
+        return f"<props of {self._item.name or self._item.id}>"
+
+    def _ensure_loaded(self) -> None:
+        if self._children_cache:
+            return
+        props = self._item.properties
+        for pr in props:
+            display = pr.get("name") or pr.get("id")
+            safe = _safe_key(str(display))
+            self._children_cache[safe] = _PropWrapper(pr)
+        self._names = [p.get("name") or p.get("id") for p in props]
+
+    def __dir__(self) -> List[str]:  # pragma: no cover - notebook UX
+        self._ensure_loaded()
+        return sorted(list(self._children_cache.keys()) + ["names"]) 
+
+    def names(self) -> List[str]:
+        self._ensure_loaded()
+        return list(self._names)
+
+    def __getattr__(self, attr: str) -> Any:
+        self._ensure_loaded()
+        if attr in self._children_cache:
+            return self._children_cache[attr]
+        raise AttributeError(attr)
+
+    def __getitem__(self, key: str) -> Any:
+        self._ensure_loaded()
+        if key in self._children_cache:
+            return self._children_cache[key]
+        # match by display name
+        for safe, data in self._children_cache.items():
+            if data.raw.get("name") == key:
+                return data
+        safe = _safe_key(key)
+        if safe in self._children_cache:
+            return self._children_cache[safe]
+        raise KeyError(key)
+
+
+class _PropWrapper:
+    """Lightweight accessor for a property dict, exposing `.value` and `.raw`.
+
+    Normalizes different property result shapes (union vs search) into `.value`.
+    """
+
+    def __init__(self, prop: Dict[str, Any]) -> None:
+        self._raw = prop
+
+    @property
+    def raw(self) -> Dict[str, Any]:
+        return self._raw
+
+    @property
+    def value(self) -> Any:  # type: ignore[override]
+        p = self._raw
+        # searchProperties shape
+        if "numericValue" in p and p.get("numericValue") is not None:
+            return p["numericValue"]
+        if "textValue" in p and p.get("textValue") is not None:
+            return p["textValue"]
+        if "dateValue" in p and p.get("dateValue") is not None:
+            return p["dateValue"]
+        # union shape
+        if "integerPart" in p:
+            integer_part = p.get("integerPart")
+            exponent = p.get("exponent", 0) or 0
+            try:
+                return (integer_part or 0) * (10 ** int(exponent))
+            except Exception:
+                return integer_part
+        if "value" in p:
+            return p.get("value")
+        return None
+
+    def __repr__(self) -> str:  # pragma: no cover - notebook UX
+        name = self._raw.get("name") or self._raw.get("id")
+        return f"<property {name}: {self.value}>"
+
+

poelis_sdk/client.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+"""Core client for the Poelis Python SDK.
+
+This module exposes the `PoelisClient` which configures base URL, authentication,
+tenant scoping, and provides accessors for resource clients. The initial
+implementation is sync-first and keeps the transport layer swappable for
+future async parity.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, HttpUrl
+from ._transport import Transport
+from .products import ProductsClient
+from .items import ItemsClient
+from .search import SearchClient
+from .workspaces import WorkspacesClient
+from .browser import Browser
+import os
+
+
+class ClientConfig(BaseModel):
+    """Configuration for `PoelisClient`.
+
+    Attributes:
+        base_url: Base URL of the Poelis API.
+        api_key: API key used for authentication.
+        org_id: Organization id for multi-tenancy scoping.
+        timeout_seconds: Request timeout in seconds.
+    """
+
+    base_url: HttpUrl
+    api_key: str = Field(min_length=1)
+    org_id: str = Field(min_length=1)
+    timeout_seconds: float = 30.0
+
+
+class PoelisClient:
+    """Synchronous Poelis SDK client.
+
+    Provides access to resource-specific clients (e.g., `products`, `items`).
+    This prototype only validates configuration and exposes placeholders for
+    resource accessors to unblock incremental development.
+    """
+
+    def __init__(self, base_url: str, api_key: str, org_id: str, timeout_seconds: float = 30.0) -> None:
+        """Initialize the client with API endpoint and credentials.
+
+        Args:
+            base_url: Base URL of the Poelis API.
+            api_key: API key for API authentication.
+            org_id: Tenant organization id to scope requests.
+            timeout_seconds: Network timeout in seconds.
+        """
+
+        self._config = ClientConfig(
+            base_url=base_url,
+            api_key=api_key,
+            org_id=org_id,
+            timeout_seconds=timeout_seconds,
+        )
+
+        # Shared transport
+        self._transport = Transport(
+            base_url=str(self._config.base_url),
+            api_key=self._config.api_key,
+            org_id=self._config.org_id,
+            timeout_seconds=self._config.timeout_seconds,
+        )
+
+        # Resource clients
+        self.products = ProductsClient(self._transport)
+        self.items = ItemsClient(self._transport)
+        self.search = SearchClient(self._transport)
+        self.workspaces = WorkspacesClient(self._transport)
+        self.browser = Browser(self)
+
+    @classmethod
+    def from_env(cls) -> "PoelisClient":
+        """Construct a client using environment variables.
+
+        Expected variables:
+        - POELIS_BASE_URL
+        - POELIS_API_KEY
+        - POELIS_ORG_ID
+        """
+
+        base_url = os.environ.get("POELIS_BASE_URL")
+        api_key = os.environ.get("POELIS_API_KEY")
+        org_id = os.environ.get("POELIS_ORG_ID")
+
+        if not base_url:
+            raise ValueError("POELIS_BASE_URL must be set")
+        if not api_key:
+            raise ValueError("POELIS_API_KEY must be set")
+        if not org_id:
+            raise ValueError("POELIS_ORG_ID must be set")
+
+        return cls(base_url=base_url, api_key=api_key, org_id=org_id)
+
+    @property
+    def base_url(self) -> str:
+        """Return the configured base URL as a string."""
+
+        return str(self._config.base_url)
+
+    @property
+    def org_id(self) -> Optional[str]:
+        """Return the configured organization id if any."""
+
+        return self._config.org_id
+
+
+class _Deprecated:  # pragma: no cover
+    pass
+
+

poelis_sdk/exceptions.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+"""SDK exception hierarchy for Poelis."""
+
+from typing import Optional
+
+
+class PoelisError(Exception):
+    """Base SDK exception."""
+
+
+class HTTPError(PoelisError):
+    """HTTP error from API response."""
+
+    def __init__(self, status_code: int, message: str | None = None) -> None:
+        super().__init__(message or f"HTTP error: {status_code}")
+        self.status_code = status_code
+        self.message = message or ""
+
+
+class UnauthorizedError(HTTPError):
+    """Raised on 401 Unauthorized."""
+
+
+class NotFoundError(HTTPError):
+    """Raised on 404 Not Found."""
+
+
+class RateLimitError(HTTPError):
+    """Raised on 429 Too Many Requests with optional retry-after seconds."""
+
+    def __init__(self, status_code: int, message: str | None = None, retry_after_seconds: Optional[float] = None) -> None:
+        super().__init__(status_code=status_code, message=message)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ClientError(HTTPError):
+    """Raised on other 4xx errors."""
+
+
+class ServerError(HTTPError):
+    """Raised on 5xx errors."""
+
+

poelis_sdk/items.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+"""Items resource client."""
+
+from typing import Generator, Any, Optional, Dict, List
+
+from ._transport import Transport
+
+
+class ItemsClient:
+    """Client for item resources (prototype exposes listing iterator only)."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list_by_product(self, *, product_id: str, q: Optional[str] = None, limit: int = 100, offset: int = 0) -> List[Dict[str, Any]]:
+        """List items for a product via GraphQL with optional text filter."""
+
+        query = (
+            "query($pid: ID!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  items(productId: $pid, q: $q, limit: $limit, offset: $offset) { id name code description productId parentId owner }\n"
+            "}"
+        )
+        variables = {"pid": product_id, "q": q, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        return payload.get("data", {}).get("items", [])
+
+    def get(self, item_id: str) -> Dict[str, Any]:
+        """Get a single item by id via GraphQL."""
+
+        query = (
+            "query($id: ID!) {\n"
+            "  item(id: $id) { id name code description productId parentId owner }\n"
+            "}"
+        )
+        resp = self._t.graphql(query=query, variables={"id": item_id})
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        return payload.get("data", {}).get("item")
+
+    def iter_all_by_product(self, *, product_id: str, q: Optional[str] = None, page_size: int = 100) -> Generator[dict, None, None]:
+        """Iterate items via GraphQL for a given product."""
+
+        offset = 0
+        while True:
+            data = self.list_by_product(product_id=product_id, q=q, limit=page_size, offset=offset)
+            if not data:
+                break
+            for item in data:
+                yield item
+            offset += len(data)
+
+

poelis_sdk/models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+"""Pydantic models for SDK resources."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class Product(BaseModel):
+    """Product resource representation."""
+
+    id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    workspace_id: Optional[str] = None
+
+
+class PaginatedProducts(BaseModel):
+    """Paginated response for products list."""
+
+    data: list[Product]
+    limit: int
+    offset: int
+
+

poelis_sdk/products.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+"""Products resource client."""
+
+from typing import Generator, Optional, List
+
+from ._transport import Transport
+from .models import PaginatedProducts, Product
+
+
+class ProductsClient:
+    """Client for product resources."""
+
+    def __init__(self, transport: Transport) -> None:
+        """Initialize with shared transport."""
+
+        self._t = transport
+
+    def list_by_workspace(self, *, workspace_id: str, q: Optional[str] = None, limit: int = 100, offset: int = 0) -> PaginatedProducts:
+        """List products using GraphQL for a given workspace.
+
+        Args:
+            workspace_id: Workspace ID to scope products.
+            q: Optional free-text filter.
+            limit: Page size.
+            offset: Offset for pagination.
+        """
+
+        query = (
+            "query($ws: ID!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  products(workspaceId: $ws, q: $q, limit: $limit, offset: $offset) { id name code description workspaceId }\n"
+            "}"
+        )
+        variables = {"ws": workspace_id, "q": q, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        rows: List[dict] = payload.get("data", {}).get("products", [])
+        return PaginatedProducts(data=[Product(**r) for r in rows], limit=limit, offset=offset)
+
+    def iter_all_by_workspace(self, *, workspace_id: str, q: Optional[str] = None, page_size: int = 100, start_offset: int = 0) -> Generator[Product, None, None]:
+        """Iterate products via GraphQL with offset pagination for a workspace."""
+
+        offset = start_offset
+        while True:
+            page = self.list_by_workspace(workspace_id=workspace_id, q=q, limit=page_size, offset=offset)
+            if not page.data:
+                break
+            for product in page.data:
+                yield product
+            offset += len(page.data)
+
+

poelis_sdk/search.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+"""Search resource client using GraphQL endpoints only."""
+
+from typing import Any, Dict, Optional
+
+from ._transport import Transport
+
+
+class SearchClient:
+    """Client for /v1/search endpoints (products, items, properties)."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def products(self, *, q: str, workspace_id: str, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Search/list products via GraphQL products(workspace_id, q)."""
+
+        query = (
+            "query($ws: ID!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  products(workspace_id: $ws, q: $q, limit: $limit, offset: $offset) { id name code description workspace_id }\n"
+            "}"
+        )
+        variables = {"ws": workspace_id, "q": q, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        hits = payload.get("data", {}).get("products", [])
+        return {"query": q, "hits": hits, "total": None, "limit": limit, "offset": offset}
+
+    def items(self, *, q: Optional[str], product_id: str, parent_item_id: Optional[str] = None, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Search/list items via GraphQL items(product_id, q, parent_item_id)."""
+
+        query = (
+            "query($pid: ID!, $q: String, $parent: ID, $limit: Int!, $offset: Int!) {\n"
+            "  items(productId: $pid, q: $q, parentItemId: $parent, limit: $limit, offset: $offset) { id name code description productId parentId owner }\n"
+            "}"
+        )
+        variables = {"pid": product_id, "q": q, "parent": parent_item_id, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        hits = payload.get("data", {}).get("items", [])
+        return {"query": q, "hits": hits, "total": None, "limit": limit, "offset": offset}
+
+    def properties(self, *, q: str, workspace_id: Optional[str] = None, product_id: Optional[str] = None, item_id: Optional[str] = None, property_type: Optional[str] = None, category: Optional[str] = None, limit: int = 20, offset: int = 0, sort: Optional[str] = None) -> Dict[str, Any]:
+        """Search properties via GraphQL search_properties."""
+
+        query = (
+            "query($q: String!, $ws: ID, $pid: ID, $iid: ID, $ptype: String, $cat: String, $limit: Int!, $offset: Int!, $sort: String) {\n"
+            "  searchProperties(q: $q, workspaceId: $ws, productId: $pid, itemId: $iid, propertyType: $ptype, category: $cat, limit: $limit, offset: $offset, sort: $sort) {\n"
+            "    query total limit offset processingTimeMs\n"
+            "    hits { id workspaceId productId itemId propertyType name category numericValue textValue dateValue owner }\n"
+            "  }\n"
+            "}"
+        )
+        variables: Dict[str, Any] = {
+            "q": q,
+            "ws": workspace_id,
+            "pid": product_id,
+            "iid": item_id,
+            "ptype": property_type,
+            "cat": category,
+            "limit": int(limit),
+            "offset": int(offset),
+            "sort": sort,
+        }
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        data = payload.get("data", {}).get("searchProperties", {})
+        # Normalize to match previous REST shape
+        return {
+            "query": data.get("query", q),
+            "hits": data.get("hits", []),
+            "total": data.get("total"),
+            "limit": data.get("limit", limit),
+            "offset": data.get("offset", offset),
+            "processing_time_ms": data.get("processingTimeMs", 0),
+        }
+
+

poelis_sdk/workspaces.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+"""Workspaces GraphQL client."""
+
+from typing import Any, Dict, List, Optional
+
+from ._transport import Transport
+
+
+class WorkspacesClient:
+    """Client for querying workspaces via GraphQL."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(self, *, limit: int = 50, offset: int = 0) -> List[Dict[str, Any]]:
+        """List workspaces (implicitly scoped by org via auth)."""
+
+        query = (
+            "query($limit: Int!, $offset: Int!) {\n"
+            "  workspaces(limit: $limit, offset: $offset) { id orgId name projectLimit }\n"
+            "}"
+        )
+        resp = self._t.graphql(query=query, variables={"limit": int(limit), "offset": int(offset)})
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        return payload.get("data", {}).get("workspaces", [])
+
+    def get(self, *, workspace_id: str) -> Optional[Dict[str, Any]]:
+        """Get a single workspace by id via GraphQL."""
+
+        query = (
+            "query($id: ID!) {\n"
+            "  workspace(id: $id) { id orgId name projectLimit }\n"
+            "}"
+        )
+        resp = self._t.graphql(query=query, variables={"id": workspace_id})
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        return payload.get("data", {}).get("workspace")
+
+

poelis_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: poelis-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Poelis
+Project-URL: Homepage, https://poelis.ai
+Project-URL: Source, https://github.com/PoelisTechnologies/poelis-python-sdk
+Project-URL: Issues, https://github.com/PoelisTechnologies/poelis-python-sdk/issues
+Author-email: Matteo Braceschi <matteo@poelis.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,client,poelis,sdk
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: build>=1.3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: twine>=6.2.0
+Description-Content-Type: text/markdown
+
+# Poelis Python SDK
+
+GraphQL-first Python SDK for Poelis with a focus on great developer experience.
+
+## Quickstart (API key + org ID)
+
+```python
+from poelis_sdk import PoelisClient
+
+client = PoelisClient(
+    base_url="https://api.poelis.ai",   # or your environment
+    api_key="poelis_live_A1B2C3...",    # Organization Settings → API Keys
+    org_id="tenant_uci_001",            # same section
+)
+
+# Workspaces → Products (GraphQL)
+workspaces = client.workspaces.list(limit=10, offset=0)
+ws_id = workspaces[0]["id"]
+
+page = client.products.list_by_workspace(workspace_id=ws_id, limit=10, offset=0)
+print([p.name for p in page.data])
+
+# Items for a product (GraphQL)
+pid = page.data[0].id
+items = client.items.list_by_product(product_id=pid, limit=10, offset=0)
+print([i.get("name") for i in items])
+
+# Property search (GraphQL)
+props = client.search.properties(q="*", workspace_id=ws_id, limit=10, offset=0)
+print(props["total"], len(props["hits"]))
+```
+
+## Configuration
+
+### Base URL
+
+- Local development: `http://localhost:8000`
+- Staging (example): `https://api.staging.poelis.ai`
+- Production (example): `https://api.poelis.ai`
+
+Confirm the exact URLs for your environments.
+
+Note: Multi-tenancy uses `org_id` for scoping. When using API keys, the SDK sets `X-Poelis-Org` automatically from `org_id`.
+
+### Getting your API key and org ID
+
+1. Navigate to Organization Settings → API Keys.
+2. Click “Create API key”, choose a name and scopes (read-only by default recommended).
+3. Copy the full key when shown (it will be visible only once). Keep it secret.
+4. The `org_id` for your organization is displayed in the same section.
+5. You can rotate or revoke keys anytime. Prefer storing as env vars:
+
+```bash
+export POELIS_BASE_URL=https://api.poelis.ai
+export POELIS_API_KEY=poelis_live_A1B2C3...
+export POELIS_ORG_ID=tenant_uci_001
+```
+
+
+## Dot-path browser (Notebook UX)
+
+The SDK exposes a dot-path browser for easy exploration:
+
+```python
+client.browser  # then use TAB to explore
+# client.browser.<workspace>.<product>.<item>.<child>.properties
+```
+
+- Lazy-loaded via GraphQL on-demand.
+- Autocomplete-friendly in Jupyter/VSCode.
+
+## Requirements
+
+- Python >= 3.11
+- API base URL reachable from your environment
+
+## License
+
+Apache-2.0

poelis_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+poelis_sdk/__init__.py,sha256=6pyvKcM6imsuCMm-VIINFNa-hXK9fUmcg86EWshPAlk,126
+poelis_sdk/_transport.py,sha256=RIyBffRR-9uz2iUb46AcRSR8rtsuyjSjFeY-EZ-BtP8,5831
+poelis_sdk/browser.py,sha256=2LblJveGsFMRXCK45S8hM1j3cWowLYYiR_YR7D6dQn8,12409
+poelis_sdk/client.py,sha256=lNjBZ7vVNsHzsHfkpxKdkP9UYjjBuzutS7tZXVSvtQI,3556
+poelis_sdk/exceptions.py,sha256=O7LJn8ZH1ZpaAx7xk7rnxkp6VgJy8ZbSV7yX6arI2tE,1101
+poelis_sdk/items.py,sha256=uKs9LBMP3en_TkUCkzj53KTfGeSjph5E3mfXeAl_YO0,2183
+poelis_sdk/models.py,sha256=OtGuv8w4n6p6X_Qlm8dE2B2Apq10gqwyPopitLz9A1Q,470
+poelis_sdk/products.py,sha256=qyZz-QnLgXTgxAXuTbnLEjIE_GrobtfVKkyIRSe7hxU,2073
+poelis_sdk/search.py,sha256=FSLkczztSQoYfolMRhUAZ7M4wI8PIeE6Ny0c40LGKng,4122
+poelis_sdk/workspaces.py,sha256=kqxIoFlSdaTWdeARjZgTUs_Gy-GF-tkRZCNKCChNsug,1518
+poelis_sdk/.github/workflows/sdk-ci.yml,sha256=hWO-igHeTAsxEJGCueteEQnAEi00GWXJJPa8DWgqhHM,750
+poelis_sdk/.github/workflows/sdk-docs.yml,sha256=bS1uUxOKRMA6TWrmzzJHTokyP0Nt0aJwojcLAgLoEhs,1166
+poelis_sdk/.github/workflows/sdk-publish-testpypi.yml,sha256=FBZcfDrtUijs6rcC8WeIimi9SfgoB8Xm5pTNtcztT44,776
+poelis_sdk-0.1.0.dist-info/METADATA,sha256=l9QximRzNb7kkKnqYLQjTT5xQo7IaOieH-2PqpU9gmQ,3108
+poelis_sdk-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+poelis_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=EEmE_r8wk_pdXB8CWp1LG6sBOl7--hNSS2kV94cI6co,1075
+poelis_sdk-0.1.0.dist-info/RECORD,,

poelis_sdk-0.1.0.dist-info/WHEEL

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

poelis_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PoelisTechnologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.