copass-core 0.1.0__py3-none-any.whl

copass_core/__init__.py

@@ -0,0 +1,99 @@
+"""Copass Python client SDK.
+
+Python mirror of `@copass/core`_. v0.1.0 scope:
+
+- ``CopassClient`` top-level entry point
+- Auth providers: ``ApiKeyAuthProvider``, ``BearerAuthProvider``
+- ``HttpClient`` with retry + middleware
+- Retrieval resource: ``discover`` / ``interpret`` / ``search``
+- Context resource: ``/context/for-agent/{minimal,adaptive,comprehensive}``
+
+Deferred to a future release (``v0.2+``): crypto primitives + Supabase
+auth provider, ContextWindow / SourcesResource / IngestResource,
+full resource coverage (matrix, sandboxes, projects, entities, vault,
+usage, api-keys, users).
+
+.. _`@copass/core`: https://github.com/olane-labs/copass-harness/tree/main/typescript/packages/core
+"""
+
+from copass_core.auth import (
+    ApiKeyAuthProvider,
+    AuthProvider,
+    BearerAuthProvider,
+    SessionContext,
+)
+from copass_core.client import (
+    DEFAULT_API_URL,
+    ApiKeyAuth,
+    AuthConfig,
+    BearerAuth,
+    CopassClient,
+    ProviderAuth,
+)
+from copass_core.http import (
+    CopassApiError,
+    CopassNetworkError,
+    CopassValidationError,
+    HttpClient,
+    HttpClientOptions,
+    RequestContext,
+    RequestMiddleware,
+    RequestOptions,
+    ResponseContext,
+    ResponseMiddleware,
+    retry_with_backoff,
+)
+from copass_core.resources import (
+    BaseResource,
+    ContextResource,
+    ContextTier,
+    RetrievalResource,
+)
+from copass_core.types import (
+    ChatMessage,
+    ChatRole,
+    RetryConfig,
+    SearchPreset,
+    WindowLike,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Client
+    "CopassClient",
+    "AuthConfig",
+    "ApiKeyAuth",
+    "BearerAuth",
+    "ProviderAuth",
+    "DEFAULT_API_URL",
+    # Auth
+    "AuthProvider",
+    "SessionContext",
+    "ApiKeyAuthProvider",
+    "BearerAuthProvider",
+    # HTTP
+    "HttpClient",
+    "HttpClientOptions",
+    "RequestOptions",
+    "RequestContext",
+    "ResponseContext",
+    "RequestMiddleware",
+    "ResponseMiddleware",
+    "CopassApiError",
+    "CopassNetworkError",
+    "CopassValidationError",
+    "retry_with_backoff",
+    # Resources
+    "BaseResource",
+    "RetrievalResource",
+    "ContextResource",
+    "ContextTier",
+    # Types
+    "RetryConfig",
+    "ChatMessage",
+    "ChatRole",
+    "WindowLike",
+    "SearchPreset",
+]

copass_core/auth/__init__.py

@@ -0,0 +1,12 @@
+"""Authentication providers."""
+
+from copass_core.auth.api_key import ApiKeyAuthProvider
+from copass_core.auth.bearer import BearerAuthProvider
+from copass_core.auth.types import AuthProvider, SessionContext
+
+__all__ = [
+    "AuthProvider",
+    "SessionContext",
+    "ApiKeyAuthProvider",
+    "BearerAuthProvider",
+]

copass_core/auth/api_key.py

@@ -0,0 +1,27 @@
+"""API key auth provider.
+
+Hand-ported from ``typescript/packages/core/src/auth/api-key.ts``.
+"""
+
+from __future__ import annotations
+
+from copass_core.auth.types import AuthProvider, SessionContext
+
+
+class ApiKeyAuthProvider:
+    """Sends a long-lived API key (``olk_...``) as a bearer token.
+
+    No session token; API keys don't support DEK wrapping in this
+    release.
+    """
+
+    def __init__(self, key: str) -> None:
+        if not key:
+            raise ValueError("ApiKeyAuthProvider requires a non-empty key")
+        self._key = key
+
+    async def get_session(self) -> SessionContext:
+        return SessionContext(access_token=self._key)
+
+
+__all__ = ["ApiKeyAuthProvider"]

copass_core/auth/bearer.py

@@ -0,0 +1,36 @@
+"""Bearer JWT auth provider.
+
+Hand-ported from ``typescript/packages/core/src/auth/bearer.ts``. In
+v0.1.0 the encryption-key path is deferred — the provider simply
+forwards the caller-supplied JWT. A later release will add
+``createSessionToken`` integration once the crypto module lands.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from copass_core.auth.types import AuthProvider, SessionContext
+
+
+class BearerAuthProvider:
+    """Forwards a caller-managed JWT as the bearer token.
+
+    The caller is responsible for refreshing the JWT when it expires —
+    mint a new provider with the new token or wrap your own refresh
+    logic in a custom :class:`AuthProvider` implementation.
+    """
+
+    def __init__(self, token: str, encryption_key: Optional[str] = None) -> None:
+        if not token:
+            raise ValueError("BearerAuthProvider requires a non-empty token")
+        self._token = token
+        # Stored but unused in v0.1.0 — reserved for the forthcoming
+        # crypto module (session-token derivation for vault access).
+        self._encryption_key = encryption_key
+
+    async def get_session(self) -> SessionContext:
+        return SessionContext(access_token=self._token)
+
+
+__all__ = ["BearerAuthProvider"]

copass_core/auth/types.py

@@ -0,0 +1,47 @@
+"""Authentication interfaces.
+
+Hand-ported from ``typescript/packages/core/src/auth/types.ts``. The
+Python port drops the session-token / encryption fields that aren't
+needed by v0.1.0 consumers; add them back when the crypto module
+lands in a later release.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class SessionContext:
+    """Active session context with resolved credentials.
+
+    Attributes:
+        access_token: The JWT or API key for the ``Authorization``
+            header.
+        session_token: Optional wrapped DEK for the
+            ``X-Encryption-Token`` header. ``None`` in v0.1.0 — the
+            crypto module is deferred.
+        user_id: User id extracted from the token. ``None`` for API
+            keys (not decoded).
+    """
+
+    access_token: str
+    session_token: Optional[str] = None
+    user_id: Optional[str] = None
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Structural contract for authentication providers.
+
+    Each auth strategy (API key, bearer JWT, future Supabase) exposes
+    :meth:`get_session`. The HTTP client calls it before each request
+    to obtain fresh credentials; providers are free to cache + refresh
+    under the hood.
+    """
+
+    async def get_session(self) -> SessionContext: ...
+
+
+__all__ = ["AuthProvider", "SessionContext"]

copass_core/client.py

@@ -0,0 +1,119 @@
+"""CopassClient — top-level entry point.
+
+Hand-ported from ``typescript/packages/core/src/client.ts``. v0.1.0
+exposes the two resources that v0.1.0 consumers need:
+:class:`RetrievalResource` (``discover`` / ``interpret`` / ``search``)
+and :class:`ContextResource` (``/context/for-agent/*``). Additional
+resources (``sandboxes``, ``sources``, ``ingest``, ``vault``, etc.)
+land incrementally.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+from copass_core.auth.api_key import ApiKeyAuthProvider
+from copass_core.auth.bearer import BearerAuthProvider
+from copass_core.auth.types import AuthProvider
+from copass_core.http.http_client import (
+    HttpClient,
+    HttpClientOptions,
+    RequestMiddleware,
+    ResponseMiddleware,
+)
+from copass_core.resources.context import ContextResource
+from copass_core.resources.retrieval import RetrievalResource
+from copass_core.types import RetryConfig
+
+
+DEFAULT_API_URL = "https://ai.copass.id"
+
+
+@dataclass(frozen=True)
+class ApiKeyAuth:
+    """``auth=ApiKeyAuth(key="olk_...")``."""
+
+    key: str
+
+
+@dataclass(frozen=True)
+class BearerAuth:
+    """``auth=BearerAuth(token="eyJ...")``. Caller owns refresh."""
+
+    token: str
+    encryption_key: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ProviderAuth:
+    """``auth=ProviderAuth(provider=MyCustomAuthProvider(...))``."""
+
+    provider: AuthProvider
+
+
+AuthConfig = Union[ApiKeyAuth, BearerAuth, ProviderAuth]
+"""Discriminated-union of auth configurations. Supabase OTP auth is
+deferred to a later release."""
+
+
+def _build_auth_provider(auth: AuthConfig) -> AuthProvider:
+    if isinstance(auth, ApiKeyAuth):
+        return ApiKeyAuthProvider(auth.key)
+    if isinstance(auth, BearerAuth):
+        return BearerAuthProvider(auth.token, auth.encryption_key)
+    if isinstance(auth, ProviderAuth):
+        return auth.provider
+    raise TypeError(f"Unsupported AuthConfig type: {type(auth).__name__}")
+
+
+class CopassClient:
+    """Main entry point for the Copass Python SDK.
+
+    Resources are accessed as instance attributes (Stripe-style).
+
+    Example:
+        >>> client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+        >>> menu = await client.retrieval.discover(
+        ...     sandbox_id="sb-1",
+        ...     query="How does auth work?",
+        ... )
+    """
+
+    retrieval: RetrievalResource
+    context: ContextResource
+
+    def __init__(
+        self,
+        *,
+        auth: AuthConfig,
+        api_url: str = DEFAULT_API_URL,
+        retry: Optional[RetryConfig] = None,
+        on_request: Optional[List[RequestMiddleware]] = None,
+        on_response: Optional[List[ResponseMiddleware]] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        auth_provider = _build_auth_provider(auth)
+        http = HttpClient(
+            HttpClientOptions(
+                api_url=api_url,
+                auth_provider=auth_provider,
+                retry=retry,
+                on_request=list(on_request or []),
+                on_response=list(on_response or []),
+                timeout=timeout,
+            )
+        )
+        self._http = http
+        self.retrieval = RetrievalResource(http)
+        self.context = ContextResource(http)
+
+
+__all__ = [
+    "CopassClient",
+    "AuthConfig",
+    "ApiKeyAuth",
+    "BearerAuth",
+    "ProviderAuth",
+    "DEFAULT_API_URL",
+]

copass_core/http/__init__.py

@@ -0,0 +1,31 @@
+"""HTTP client primitives."""
+
+from copass_core.http.errors import (
+    CopassApiError,
+    CopassNetworkError,
+    CopassValidationError,
+)
+from copass_core.http.http_client import (
+    HttpClient,
+    HttpClientOptions,
+    RequestContext,
+    RequestMiddleware,
+    RequestOptions,
+    ResponseContext,
+    ResponseMiddleware,
+)
+from copass_core.http.retry import retry_with_backoff
+
+__all__ = [
+    "HttpClient",
+    "HttpClientOptions",
+    "RequestOptions",
+    "RequestContext",
+    "ResponseContext",
+    "RequestMiddleware",
+    "ResponseMiddleware",
+    "CopassApiError",
+    "CopassNetworkError",
+    "CopassValidationError",
+    "retry_with_backoff",
+]

copass_core/http/errors.py

@@ -0,0 +1,60 @@
+"""HTTP error types.
+
+Hand-ported from ``typescript/packages/core/src/http/errors.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+
+class CopassApiError(Exception):
+    """Raised when the Copass API returns a non-2xx response.
+
+    Attributes:
+        status: HTTP status code.
+        body: Parsed JSON body (if parseable) or raw response text.
+        path: Request path that failed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        body: Any = None,
+        path: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.path = path
+
+
+class CopassNetworkError(Exception):
+    """Raised on network-level failures (DNS, timeout, connection
+    refused). Caller should retry at a higher level or surface to the
+    end user."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class CopassValidationError(Exception):
+    """Raised for client-side validation failures before the request
+    leaves the SDK (e.g., missing required parameter).
+
+    Attributes:
+        fields: The field name(s) that failed validation.
+    """
+
+    def __init__(self, message: str, fields: Optional[List[str]] = None) -> None:
+        super().__init__(message)
+        self.fields = fields or []
+
+
+__all__ = [
+    "CopassApiError",
+    "CopassNetworkError",
+    "CopassValidationError",
+]

copass_core/http/http_client.py

@@ -0,0 +1,171 @@
+"""Internal async HTTP client for the Copass API.
+
+Port of ``typescript/packages/core/src/http/http-client.ts`` with the
+v0.1.0 scope trimmed:
+
+- No encrypted-payload path (crypto module deferred).
+- No file-upload path (single consumer today is retrieval; can be
+  added when ingest lands).
+- Middleware hooks supported — mirror the TS ``onRequest`` /
+  ``onResponse`` signatures so telemetry-hook patterns transfer.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+
+import httpx
+
+from copass_core.auth.types import AuthProvider
+from copass_core.http.errors import CopassApiError
+from copass_core.http.retry import retry_with_backoff
+from copass_core.types import RetryConfig
+
+
+@dataclass
+class RequestContext:
+    """Metadata about a request, passed to middleware."""
+
+    method: str
+    path: str
+    url: str
+    headers: Dict[str, str]
+    body: Optional[str] = None
+
+
+@dataclass
+class ResponseContext:
+    """Metadata about a completed response, passed to middleware."""
+
+    request: RequestContext
+    status: int
+    duration_ms: int
+
+
+RequestMiddleware = Callable[[RequestContext], Union[None, Awaitable[None]]]
+"""Middleware invoked before each request. May mutate the
+:class:`RequestContext` (headers, body)."""
+
+ResponseMiddleware = Callable[[ResponseContext], Union[None, Awaitable[None]]]
+"""Middleware invoked after each successful response."""
+
+
+@dataclass(frozen=True)
+class HttpClientOptions:
+    api_url: str
+    auth_provider: AuthProvider
+    retry: Optional[RetryConfig] = None
+    on_request: List[RequestMiddleware] = field(default_factory=list)
+    on_response: List[ResponseMiddleware] = field(default_factory=list)
+    timeout: float = 30.0
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    method: str = "GET"
+    body: Any = None
+    query: Optional[Dict[str, Optional[str]]] = None
+    headers: Optional[Dict[str, str]] = None
+
+
+class HttpClient:
+    """Thin async wrapper around ``httpx.AsyncClient`` that handles
+    auth-header injection, retry, error normalization, and middleware.
+
+    A single client instance is safe to share across resources — each
+    :meth:`request` opens its own short-lived ``httpx.AsyncClient`` so
+    connection pooling is not attempted at this layer. (Add a shared
+    ``AsyncClient`` in a later release if latency telemetry shows
+    per-request handshake cost matters.)
+    """
+
+    def __init__(self, options: HttpClientOptions) -> None:
+        self._api_url = options.api_url.rstrip("/")
+        self._auth_provider = options.auth_provider
+        self._retry_config = options.retry
+        self._on_request = list(options.on_request or [])
+        self._on_response = list(options.on_response or [])
+        self._timeout = options.timeout
+
+    async def request(self, path: str, options: Optional[RequestOptions] = None) -> Any:
+        opts = options or RequestOptions()
+        session = await self._auth_provider.get_session()
+
+        headers: Dict[str, str] = {
+            "Authorization": f"Bearer {session.access_token}",
+            **(opts.headers or {}),
+        }
+        if "Content-Type" not in headers and "content-type" not in headers:
+            headers["Content-Type"] = "application/json"
+        if session.session_token:
+            headers["X-Encryption-Token"] = session.session_token
+
+        body_text: Optional[str] = None
+        if opts.body is not None:
+            body_text = json.dumps(opts.body)
+
+        url = self._api_url + path
+        if opts.query:
+            non_null = {k: v for k, v in opts.query.items() if v is not None}
+            if non_null:
+                url = f"{url}?{httpx.QueryParams(non_null)}"
+
+        ctx = RequestContext(
+            method=opts.method,
+            path=path,
+            url=url,
+            headers=headers,
+            body=body_text,
+        )
+        for mw in self._on_request:
+            result = mw(ctx)
+            if hasattr(result, "__await__"):
+                await result  # type: ignore[misc]
+
+        async def _do_request() -> Any:
+            start = time.monotonic()
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.request(
+                    method=ctx.method,
+                    url=ctx.url,
+                    headers=ctx.headers,
+                    content=body_text,
+                )
+            duration_ms = int((time.monotonic() - start) * 1000)
+
+            if response.status_code >= 400:
+                try:
+                    error_body = response.json()
+                except Exception:  # noqa: BLE001
+                    error_body = response.text
+                raise CopassApiError(
+                    f"API request failed: {response.status_code} {response.reason_phrase}",
+                    status=response.status_code,
+                    body=error_body,
+                    path=path,
+                )
+
+            for mw in self._on_response:
+                result = mw(ResponseContext(request=ctx, status=response.status_code, duration_ms=duration_ms))
+                if hasattr(result, "__await__"):
+                    await result  # type: ignore[misc]
+
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+
+        return await retry_with_backoff(_do_request, self._retry_config)
+
+
+__all__ = [
+    "HttpClient",
+    "HttpClientOptions",
+    "RequestOptions",
+    "RequestContext",
+    "ResponseContext",
+    "RequestMiddleware",
+    "ResponseMiddleware",
+]

copass_core/http/retry.py

@@ -0,0 +1,77 @@
+"""Retry helper with configurable backoff.
+
+Hand-ported from ``typescript/packages/core/src/http/retry.ts``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import Awaitable, Callable, Optional, TypeVar
+
+from copass_core.http.errors import CopassNetworkError
+from copass_core.types import RetryConfig
+
+T = TypeVar("T")
+
+
+_RETRYABLE_PATTERN = re.compile(
+    r"5\d{2}|ECONNRESET|ETIMEDOUT|ECONNREFUSED|ENOTFOUND|fetch failed|connection",
+    re.IGNORECASE,
+)
+_NETWORK_ERROR_PATTERN = re.compile(
+    r"fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|connection",
+    re.IGNORECASE,
+)
+
+
+def _compute_delay_ms(attempt: int, strategy: str, base_ms: int) -> int:
+    """Compute the delay for ``attempt`` (0-indexed)."""
+    if strategy == "exponential":
+        return (2**attempt) * base_ms
+    if strategy == "linear":
+        return (attempt + 1) * base_ms
+    # fixed
+    return base_ms
+
+
+async def retry_with_backoff(
+    fn: Callable[[], Awaitable[T]],
+    config: Optional[RetryConfig] = None,
+) -> T:
+    """Run ``fn`` with retry on transient failures.
+
+    Only retryable errors (5xx status messages, common network error
+    tokens) trigger a retry. Non-retryable failures bubble up
+    immediately. Network-level failures are wrapped in
+    :class:`CopassNetworkError` before raising.
+    """
+    cfg = config or RetryConfig()
+    last_error: Optional[BaseException] = None
+
+    for attempt in range(cfg.max_attempts):
+        try:
+            return await fn()
+        except BaseException as error:  # noqa: BLE001 — we re-classify below
+            last_error = error
+            message = str(error)
+            is_retryable = bool(_RETRYABLE_PATTERN.search(message))
+
+            if not is_retryable or attempt == cfg.max_attempts - 1:
+                if _NETWORK_ERROR_PATTERN.search(message):
+                    raise CopassNetworkError(
+                        "Network request failed — check your internet "
+                        "connection and try again",
+                        cause=error if isinstance(error, Exception) else None,
+                    ) from error
+                raise
+
+            delay_ms = _compute_delay_ms(attempt, cfg.backoff_strategy, cfg.backoff_base_ms)
+            await asyncio.sleep(delay_ms / 1000)
+
+    # Unreachable — max_attempts >= 1.
+    assert last_error is not None
+    raise last_error
+
+
+__all__ = ["retry_with_backoff"]

copass_core/resources/__init__.py

@@ -0,0 +1,12 @@
+"""Resource modules — thin wrappers around specific API paths."""
+
+from copass_core.resources.base import BaseResource
+from copass_core.resources.context import ContextResource, ContextTier
+from copass_core.resources.retrieval import RetrievalResource
+
+__all__ = [
+    "BaseResource",
+    "RetrievalResource",
+    "ContextResource",
+    "ContextTier",
+]

copass_core/resources/base.py

@@ -0,0 +1,78 @@
+"""Base resource — shared :class:`HttpClient` reference + typed HTTP
+convenience methods.
+
+Mirrors ``typescript/packages/core/src/resources/base.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from copass_core.http.http_client import HttpClient, RequestOptions
+
+
+class BaseResource:
+    """Base class for all API resource modules.
+
+    Concrete resources (retrieval, context, future sandboxes/etc.)
+    subclass this and call the protected helpers (:meth:`_post`,
+    :meth:`_get`, :meth:`_patch`, :meth:`_delete`) rather than going
+    through :class:`HttpClient` directly. Keeps every resource's
+    surface narrow and consistent.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    async def _post(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        query: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        return await self._http.request(
+            path,
+            RequestOptions(method="POST", body=body, query=query, headers=headers),
+        )
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        query: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        return await self._http.request(
+            path,
+            RequestOptions(method="GET", query=query, headers=headers),
+        )
+
+    async def _patch(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        query: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        return await self._http.request(
+            path,
+            RequestOptions(method="PATCH", body=body, query=query, headers=headers),
+        )
+
+    async def _delete(
+        self,
+        path: str,
+        *,
+        query: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        return await self._http.request(
+            path,
+            RequestOptions(method="DELETE", query=query, headers=headers),
+        )
+
+
+__all__ = ["BaseResource"]

copass_core/resources/context.py

@@ -0,0 +1,74 @@
+"""Context-for-agent resource — ``/api/v1/context/for-agent/*``.
+
+Thin Python wrapper over the server-side tiered context endpoints
+(``minimal`` / ``adaptive`` / ``comprehensive``). Shipped in v0.1.0
+because SDK consumers (notably ``copass-anthropic-agents`` context
+injection) need it.
+
+The full server-side response shape is heterogeneous across tiers;
+we return the decoded JSON dict directly rather than forcing a typed
+response model. Callers pick the fields they care about.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from copass_core.resources.base import BaseResource
+
+
+ContextTier = Literal["minimal", "adaptive", "comprehensive"]
+
+
+class ContextResource(BaseResource):
+    """``/api/v1/context/for-agent/{tier}``.
+
+    Three tiers, ordered by breadth vs. cost:
+
+    - ``"minimal"`` — tight context blob, fastest.
+    - ``"adaptive"`` — lets the server pick tier based on a budget.
+    - ``"comprehensive"`` — maximum breadth, heaviest.
+    """
+
+    async def for_agent(
+        self,
+        *,
+        sandbox_id: str,
+        tier: ContextTier = "adaptive",
+        project_id: Optional[str] = None,
+        query: Optional[str] = None,
+        history: Optional[List[Dict[str, str]]] = None,
+        max_tokens: Optional[int] = None,
+        extra: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """POST to the configured tier endpoint. Returns the decoded
+        JSON body.
+
+        Args:
+            sandbox_id: Sandbox to retrieve context from.
+            tier: Which ``for-agent`` variant to hit.
+            project_id: Narrow to a single project within the sandbox.
+            query: Natural-language query to shape context around.
+                Optional — some tiers retrieve window-based context
+                without one.
+            history: Recent chat turns to feed the window-aware
+                retriever.
+            max_tokens: Hint for the server's context-size budget.
+            extra: Any additional body fields — escape hatch for
+                server-side flags not yet exposed via typed kwargs.
+        """
+        body: Dict[str, Any] = {"sandbox_id": sandbox_id}
+        if project_id is not None:
+            body["project_id"] = project_id
+        if query is not None:
+            body["query"] = query
+        if history is not None:
+            body["history"] = history
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if extra:
+            body.update(extra)
+        return await self._post(f"/api/v1/context/for-agent/{tier}", body)
+
+
+__all__ = ["ContextResource", "ContextTier"]

copass_core/resources/retrieval.py

@@ -0,0 +1,147 @@
+"""Retrieval resource — ``discover`` / ``interpret`` / ``search``.
+
+Hand-ported from ``typescript/packages/core/src/resources/retrieval.ts``.
+
+All three accept either a ``window`` (a :class:`WindowLike` — typically
+a ``ContextWindow``) or a raw ``history`` list. When ``window`` is set
+it wins and ``history`` is ignored. Server caps at 20 turns.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Dict, List, Optional
+
+from copass_core.resources.base import BaseResource
+from copass_core.types import ChatMessage, SearchPreset, WindowLike
+
+
+def _turns_from(window: Optional[WindowLike]) -> List[Dict[str, str]]:
+    if window is None:
+        return []
+    turns = window.get_turns()
+    if not turns:
+        return []
+    return [_turn_to_dict(t) for t in turns]
+
+
+def _turn_to_dict(turn: Any) -> Dict[str, str]:
+    """Accept either a :class:`ChatMessage` dataclass or a plain dict
+    (``{"role": ..., "content": ...}``) so callers can mix and match."""
+    if isinstance(turn, ChatMessage):
+        return {"role": turn.role, "content": turn.content}
+    if isinstance(turn, dict) and "role" in turn and "content" in turn:
+        return {"role": str(turn["role"]), "content": str(turn["content"])}
+    raise ValueError(
+        f"Unexpected turn type {type(turn).__name__}; expected ChatMessage or dict."
+    )
+
+
+def _history(
+    window: Optional[WindowLike],
+    history: Optional[List[Any]],
+) -> List[Dict[str, str]]:
+    """``window`` wins; fall back to ``history``; empty list if both None."""
+    if window is not None:
+        return _turns_from(window)
+    if history:
+        return [_turn_to_dict(t) for t in history]
+    return []
+
+
+class RetrievalResource(BaseResource):
+    """``/api/v1/query/sandboxes/{sandbox_id}/{discover,interpret,search}``."""
+
+    async def discover(
+        self,
+        sandbox_id: str,
+        *,
+        query: str,
+        window: Optional[WindowLike] = None,
+        history: Optional[List[Any]] = None,
+        project_id: Optional[str] = None,
+        reference_date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Ranked menu of context items relevant to ``query``.
+
+        Window-aware: repeated calls skip items already surfaced
+        earlier in the conversation.
+        """
+        body: Dict[str, Any] = {
+            "query": query,
+            "history": _history(window, history),
+        }
+        if project_id is not None:
+            body["project_id"] = project_id
+        if reference_date is not None:
+            body["reference_date"] = reference_date
+        return await self._post(
+            f"/api/v1/query/sandboxes/{sandbox_id}/discover",
+            body,
+        )
+
+    async def interpret(
+        self,
+        sandbox_id: str,
+        *,
+        query: str,
+        items: List[List[str]],
+        window: Optional[WindowLike] = None,
+        history: Optional[List[Any]] = None,
+        project_id: Optional[str] = None,
+        reference_date: Optional[str] = None,
+        preset: Optional[SearchPreset] = None,
+    ) -> Dict[str, Any]:
+        """Synthesized 1–2 paragraph brief pinned to specific
+        ``items`` picked from a prior ``discover`` call."""
+        body: Dict[str, Any] = {
+            "query": query,
+            "items": items,
+            "history": _history(window, history),
+        }
+        if project_id is not None:
+            body["project_id"] = project_id
+        if reference_date is not None:
+            body["reference_date"] = reference_date
+        if preset is not None:
+            body["preset"] = preset
+        return await self._post(
+            f"/api/v1/query/sandboxes/{sandbox_id}/interpret",
+            body,
+        )
+
+    async def search(
+        self,
+        sandbox_id: str,
+        *,
+        query: str,
+        window: Optional[WindowLike] = None,
+        history: Optional[List[Any]] = None,
+        project_id: Optional[str] = None,
+        reference_date: Optional[str] = None,
+        preset: Optional[SearchPreset] = None,
+        detail_level: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """One-shot synthesized natural-language answer."""
+        body: Dict[str, Any] = {
+            "query": query,
+            "history": _history(window, history),
+        }
+        if project_id is not None:
+            body["project_id"] = project_id
+        if reference_date is not None:
+            body["reference_date"] = reference_date
+        if preset is not None:
+            body["preset"] = preset
+        if detail_level is not None:
+            body["detail_level"] = detail_level
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        return await self._post(
+            f"/api/v1/query/sandboxes/{sandbox_id}/search",
+            body,
+        )
+
+
+__all__ = ["RetrievalResource"]

copass_core/types.py

@@ -0,0 +1,77 @@
+"""Shared value types for the Copass Python client.
+
+Hand-ported from ``typescript/packages/core/src/types/common.ts`` and
+the retrieval/context subsets actually needed by v0.1.0 consumers.
+Richer resource-specific types land incrementally as more resources
+are ported.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Literal, Optional, Protocol
+
+
+BackoffStrategy = Literal["exponential", "linear", "fixed"]
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Retry configuration for transient HTTP failures.
+
+    Attributes:
+        max_attempts: Max total attempts (including the first). Default 3.
+        backoff_base_ms: Base delay in milliseconds.
+        backoff_strategy: ``"exponential"`` (2^attempt * base),
+            ``"linear"`` ((attempt + 1) * base), or ``"fixed"`` (base).
+    """
+
+    max_attempts: int = 3
+    backoff_base_ms: int = 1000
+    backoff_strategy: BackoffStrategy = "exponential"
+
+
+ChatRole = Literal["user", "assistant", "system"]
+
+
+@dataclass(frozen=True)
+class ChatMessage:
+    """One chat turn. Mirrors the TS ``ChatMessage``."""
+
+    role: ChatRole
+    content: str
+
+
+class WindowLike(Protocol):
+    """Structural contract the retrieval resource accepts in place of a
+    raw ``history`` list. Any object with a ``get_turns()`` method
+    returning a list of :class:`ChatMessage` satisfies this.
+
+    Mirrors the TS ``WindowLike`` interface — the Python
+    ``ContextWindow`` class (v0.2) will satisfy this protocol.
+    """
+
+    def get_turns(self) -> List[ChatMessage]: ...
+
+
+SearchPreset = Literal[
+    "fast",
+    "auto",
+    "discover",
+    "sql",
+    "max",
+    "fast-decompose",
+    "auto-decompose",
+    "discover-decompose",
+    "sql-decompose",
+]
+
+
+__all__ = [
+    "BackoffStrategy",
+    "RetryConfig",
+    "ChatRole",
+    "ChatMessage",
+    "WindowLike",
+    "SearchPreset",
+]

copass_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: copass-core
+Version: 0.1.0
+Summary: Core client SDK for the Copass platform (Python mirror of @copass/core)
+Project-URL: Homepage, https://github.com/olane-labs/copass-harness
+Project-URL: Repository, https://github.com/olane-labs/copass-harness.git
+Author: Olane Inc.
+License: MIT
+Keywords: client,copass,knowledge-graph,retrieval,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-core
+
+Core client SDK for the Copass platform. Python mirror of [`@copass/core`](../../typescript/packages/core) — shared foundation for every Python Copass adapter.
+
+## Install
+
+```bash
+pip install copass-core
+```
+
+Requires `httpx>=0.27`. Python ≥ 3.10.
+
+## Quickstart
+
+```python
+import asyncio
+from copass_core import CopassClient, ApiKeyAuth
+
+async def main():
+    client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+
+    # Retrieval
+    menu = await client.retrieval.discover(
+        sandbox_id="sb_...",
+        query="How does auth work?",
+    )
+    print(menu["items"])
+
+    # Context for agent
+    context = await client.context.for_agent(
+        sandbox_id="sb_...",
+        tier="adaptive",
+        query="auth flow",
+    )
+    print(context)
+
+asyncio.run(main())
+```
+
+## Auth options
+
+```python
+from copass_core import CopassClient, ApiKeyAuth, BearerAuth, ProviderAuth
+
+# Long-lived API key (olk_ prefix)
+CopassClient(auth=ApiKeyAuth(key="olk_..."))
+
+# Raw Bearer JWT (caller owns refresh)
+CopassClient(auth=BearerAuth(token="eyJ..."))
+
+# Custom AuthProvider implementation
+class MyProvider:
+    async def get_session(self):
+        from copass_core import SessionContext
+        return SessionContext(access_token=await _mint_token())
+
+CopassClient(auth=ProviderAuth(provider=MyProvider()))
+```
+
+## v0.1.0 scope
+
+**Shipped:**
+- `CopassClient` top-level entry point
+- Auth providers: `ApiKeyAuthProvider`, `BearerAuthProvider`
+- `HttpClient` with retry + request/response middleware
+- `RetrievalResource` — `discover` / `interpret` / `search`
+- `ContextResource` — `/context/for-agent/{minimal,adaptive,comprehensive}`
+
+**Deferred to a future release:**
+- Crypto primitives (HKDF, AES-GCM, session tokens, DEK) + Supabase auth provider
+- `ContextWindow` + `SourcesResource` + `IngestResource`
+- `MatrixResource`, `SandboxesResource`, `ProjectsResource`, `EntitiesResource`, `VaultResource`, `UsageResource`, `ApiKeysResource`, `UsersResource`
+
+Add incrementally when a concrete Python consumer needs each. Opening a PR with a scoped addition is the expected path.
+
+## License
+
+MIT.

copass_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+copass_core/__init__.py,sha256=tCnaYxjvbjN_e5kAjEwgIBcJWb7NjjNEWR6p2Ys0JdQ,2245
+copass_core/client.py,sha256=TwiYn-7WVVtp1Ztkn8iD6UdIv-1SlHSkiSTCPBoZmSo,3364
+copass_core/types.py,sha256=33W3eg0XE45uu4dlahY6sIoPYOgs7vGNElrjClO9gr0,1890
+copass_core/auth/__init__.py,sha256=30P2JKrGkEiXAij14pyXeITTIPStgumf6Wxg2Ht7yqE,317
+copass_core/auth/api_key.py,sha256=rdLvm1q7cl21k2QogyTnYlagKJr27mlRLCHmJGgmmpQ,686
+copass_core/auth/bearer.py,sha256=lClUY1sICjrhG8RBLMnxu7N2vWo9jnDlAPiydWiL4gw,1260
+copass_core/auth/types.py,sha256=lXaRDYvsXjKiY_n8NME02LytiJAiQTP6IuUwnszO2dE,1417
+copass_core/http/__init__.py,sha256=moHB5u-R8x0wKp2l-tLN-V13ugip5668u2aC45zOgVY,667
+copass_core/http/errors.py,sha256=RKffCQfkWB3tjFLc9Nf8b2rRnis66As-mMleL-wpOr0,1531
+copass_core/http/http_client.py,sha256=aiWV0ARsgXtAGp4rs9xJEEEv2xW7I0qG-XlBUet9nWQ,5650
+copass_core/http/retry.py,sha256=fSdcT4jggqoWbuGeeeLVSleuYrS0-IGvdTsn8trKw-Y,2428
+copass_core/resources/__init__.py,sha256=rkzSZH0VktglD30YyT1drimoM_qAPTSMbFjxx2KJB0A,356
+copass_core/resources/base.py,sha256=uo_cK7oCUBehcHsk5Vq73j2YwZ289Ti_4Ln8BCUJIFM,2060
+copass_core/resources/context.py,sha256=VkCzdAop4sBFknRcRhO4QyWtKyU9k9EiuAKz8errDIM,2659
+copass_core/resources/retrieval.py,sha256=bdEWdh0Urb6oaMeuiEToaXNAYFjBg0CIuxjIUZq2SVM,4888
+copass_core-0.1.0.dist-info/METADATA,sha256=Gq6kRHhOSFGEAP3u4Nq04jPJ4DGlV-mp4rsBypgQbRg,3064
+copass_core-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+copass_core-0.1.0.dist-info/RECORD,,

copass_core-0.1.0.dist-info/WHEEL

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