copass-core 0.1.0__tar.gz

copass_core-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage/
+
+# Lerna
+lerna-debug.log
+.nx/cache
+.nx/workspace-data
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+venv/
+.olane

copass_core-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-core"
+version = "0.1.0"
+description = "Core client SDK for the Copass platform (Python mirror of @copass/core)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = ["copass", "knowledge-graph", "sdk", "client", "retrieval"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/olane-labs/copass-harness"
+Repository = "https://github.com/olane-labs/copass-harness.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copass_core"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["copass_core"]

copass_core-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]