copass-agent-router 0.5.0__tar.gz

copass_agent_router-0.5.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_agent_router-0.5.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: copass-agent-router
+Version: 0.5.0
+Summary: High-level Copass agent SDK — hosted agent-runtime routing + integrations + one-liner OAuth flow (Python mirror of @copass/agent-router)
+Project-URL: Homepage, https://github.com/olane-labs/copass
+Project-URL: Repository, https://github.com/olane-labs/copass.git
+Author: Olane Inc.
+License: MIT
+Keywords: agent-router,agents,copass,integrations,oauth,pipedream
+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: copass-core-agents>=0.1.0
+Requires-Dist: copass-core>=0.2.0
+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-agent-router
+
+High-level Copass agent SDK. Python mirror of [`@copass/agent-router`](../../typescript/packages/agent-router) — wraps `copass-core` + `copass-core-agents` into a one-import surface that runs a full agent lifecycle: connect an integration, run an agent turn, stream events.
+
+## Install
+
+```bash
+pip install copass-agent-router
+```
+
+## Quickstart
+
+```python
+import asyncio, webbrowser
+from copass_agent_router import AgentRouter, RunAgentOptions
+from copass_core import ApiKeyAuth
+
+async def main():
+    router = AgentRouter(
+        auth=ApiKeyAuth(key="olk_..."),
+        sandbox_id="sb_...",
+    )
+
+    # Connect an integration (OAuth, local browser, webhook fallback via reconcile).
+    result = await router.integrations.connect(
+        "github",
+        on_connect_url=lambda url: webbrowser.open(url),
+    )
+    print("connected:", result.connection["app"], result.connection["name"])
+
+    # Run an agent.
+    async for event in router.run(RunAgentOptions(
+        provider="anthropic",
+        model="claude-opus-4-7",
+        system="You are a helpful agent.",
+        message="Summarize my latest GitHub issues.",
+        end_user_id="u-123",
+    )):
+        t = type(event).__name__
+        if t == "AgentTextDelta":
+            print(event.text, end="", flush=True)
+        elif t == "AgentFinish":
+            print(f"\n[done] {event.stop_reason}")
+
+asyncio.run(main())
+```
+
+## License
+
+MIT.

copass_agent_router-0.5.0/README.md

@@ -0,0 +1,50 @@
+# copass-agent-router
+
+High-level Copass agent SDK. Python mirror of [`@copass/agent-router`](../../typescript/packages/agent-router) — wraps `copass-core` + `copass-core-agents` into a one-import surface that runs a full agent lifecycle: connect an integration, run an agent turn, stream events.
+
+## Install
+
+```bash
+pip install copass-agent-router
+```
+
+## Quickstart
+
+```python
+import asyncio, webbrowser
+from copass_agent_router import AgentRouter, RunAgentOptions
+from copass_core import ApiKeyAuth
+
+async def main():
+    router = AgentRouter(
+        auth=ApiKeyAuth(key="olk_..."),
+        sandbox_id="sb_...",
+    )
+
+    # Connect an integration (OAuth, local browser, webhook fallback via reconcile).
+    result = await router.integrations.connect(
+        "github",
+        on_connect_url=lambda url: webbrowser.open(url),
+    )
+    print("connected:", result.connection["app"], result.connection["name"])
+
+    # Run an agent.
+    async for event in router.run(RunAgentOptions(
+        provider="anthropic",
+        model="claude-opus-4-7",
+        system="You are a helpful agent.",
+        message="Summarize my latest GitHub issues.",
+        end_user_id="u-123",
+    )):
+        t = type(event).__name__
+        if t == "AgentTextDelta":
+            print(event.text, end="", flush=True)
+        elif t == "AgentFinish":
+            print(f"\n[done] {event.stop_reason}")
+
+asyncio.run(main())
+```
+
+## License
+
+MIT.

copass_agent_router-0.5.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-agent-router"
+version = "0.5.0"
+description = "High-level Copass agent SDK — hosted agent-runtime routing + integrations + one-liner OAuth flow (Python mirror of @copass/agent-router)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = ["copass", "agents", "agent-router", "oauth", "integrations", "pipedream"]
+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 = [
+    "copass-core>=0.2.0",
+    "copass-core-agents>=0.1.0",
+    "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"
+Repository = "https://github.com/olane-labs/copass.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copass_agent_router"]
+
+[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_agent_router"]

copass_agent_router-0.5.0/src/copass_agent_router/__init__.py

@@ -0,0 +1,32 @@
+"""High-level Copass agent SDK.
+
+Mirror of ``@copass/agent-router`` on the TypeScript side. Wraps
+``copass-core`` and the provider-neutral agent events so one import
+runs the full lifecycle: connect an integration, start an agent turn,
+stream events.
+"""
+
+from copass_agent_router.router import AgentRouter, IntegrationsFacade, RunAgentOptions
+from copass_agent_router.connect_flow import ConnectFlowResult, run_connect_flow
+from copass_core_agents.events import (
+    AgentEvent,
+    AgentFinish,
+    AgentTextDelta,
+    AgentToolCall,
+    AgentToolResult,
+)
+
+__all__ = [
+    "AgentRouter",
+    "IntegrationsFacade",
+    "RunAgentOptions",
+    "ConnectFlowResult",
+    "run_connect_flow",
+    "AgentEvent",
+    "AgentTextDelta",
+    "AgentToolCall",
+    "AgentToolResult",
+    "AgentFinish",
+]
+
+__version__ = "0.5.0"

copass_agent_router-0.5.0/src/copass_agent_router/connect_flow.py

@@ -0,0 +1,195 @@
+"""End-to-end OAuth connect flow helper.
+
+Mirror of the TS ``runConnectFlow``. Uses Python's ``http.server`` for
+the short-lived success/error redirect listener and polls
+``integrations.reconcile`` until the DataSource lands.
+
+Server-side / CLI flows use this; webapp flows typically skip the
+listener and handle redirects in the browser directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import http.server
+import logging
+import socket
+import threading
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Optional, Union
+
+from copass_core import CopassClient
+
+logger = logging.getLogger(__name__)
+
+
+OnConnectUrl = Callable[[str], Union[None, Awaitable[None]]]
+
+
+@dataclass(frozen=True)
+class ConnectFlowResult:
+    connection: dict
+    session_id: str
+
+
+class _RedirectListener:
+    """One-shot HTTP listener on ``127.0.0.1:<random>`` capturing
+    ``/oauth/success`` or ``/oauth/error``."""
+
+    def __init__(self) -> None:
+        self._outcome: Optional[str] = None
+        self._event = threading.Event()
+        self._server: Optional[http.server.HTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+
+    def start(self) -> tuple[str, str]:
+        outer = self
+
+        class _Handler(http.server.BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802
+                path = (self.path or "/").split("?")[0]
+                if path == "/oauth/success":
+                    outer._outcome = "success"
+                    body = (
+                        "<html><body style='font-family:sans-serif;padding:3rem'>"
+                        "<h2>\u2713 Connection complete</h2>"
+                        "<p>You can close this tab.</p></body></html>"
+                    )
+                elif path == "/oauth/error":
+                    outer._outcome = "error"
+                    body = (
+                        "<html><body style='font-family:sans-serif;padding:3rem'>"
+                        "<h2>\u2717 Connection failed</h2>"
+                        "<p>You can close this tab and retry.</p></body></html>"
+                    )
+                else:
+                    self.send_response(404)
+                    self.end_headers()
+                    return
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(body.encode("utf-8"))
+                outer._event.set()
+
+            def log_message(self, *_args: Any) -> None:  # silence stdlib stdout
+                return
+
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.bind(("127.0.0.1", 0))
+        port = sock.getsockname()[1]
+        sock.close()
+        self._server = http.server.HTTPServer(("127.0.0.1", port), _Handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        base = f"http://127.0.0.1:{port}"
+        return f"{base}/oauth/success", f"{base}/oauth/error"
+
+    async def wait(self, timeout_seconds: float) -> Optional[str]:
+        """Return 'success' | 'error' | None (timeout)."""
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._event.wait, timeout_seconds)
+        return self._outcome
+
+    def close(self) -> None:
+        if self._server is not None:
+            try:
+                self._server.shutdown()
+                self._server.server_close()
+            except Exception:  # pragma: no cover
+                pass
+
+
+async def run_connect_flow(
+    client: CopassClient,
+    sandbox_id: str,
+    *,
+    app: str,
+    on_connect_url: OnConnectUrl,
+    scope: str = "user",
+    project_id: Optional[str] = None,
+    timeout_seconds: float = 300.0,
+    success_uri: Optional[str] = None,
+    error_uri: Optional[str] = None,
+) -> ConnectFlowResult:
+    """Run the Copass integrations connect flow end-to-end.
+
+    1. Snapshots current connections for diff detection.
+    2. Starts a localhost listener for the success redirect (unless
+       caller supplied ``success_uri`` / ``error_uri``).
+    3. Mints a Connect URL via :meth:`IntegrationsResource.connect`.
+    4. Calls ``on_connect_url(url)`` — typically opens the browser.
+    5. Polls ``integrations.reconcile`` every 2s until a new connection
+       not in the pre-snapshot appears, OR the listener fires error, OR
+       the timeout elapses.
+    """
+    # Snapshot
+    try:
+        existing = await client.integrations.list(sandbox_id, app=app)
+        known_before = {c["source_id"] for c in existing.get("items", [])}
+    except Exception:  # pragma: no cover — non-fatal
+        known_before = set()
+
+    listener: Optional[_RedirectListener] = None
+    if success_uri is None or error_uri is None:
+        listener = _RedirectListener()
+        s, e = listener.start()
+        success_uri = success_uri or s
+        error_uri = error_uri or e
+
+    try:
+        resp = await client.integrations.connect(
+            sandbox_id,
+            app=app,
+            scope=scope,
+            success_redirect_uri=success_uri,
+            error_redirect_uri=error_uri,
+            project_id=project_id,
+        )
+        session_id = str(resp["session_id"])
+        connect_url = str(resp["connect_url"])
+        result = on_connect_url(connect_url)
+        if asyncio.iscoroutine(result):
+            await result
+
+        # Poll reconcile until a new connection appears or the listener
+        # signals 'error' or the timeout elapses.
+        deadline = asyncio.get_event_loop().time() + timeout_seconds
+        redirect_task: Optional[asyncio.Task[Optional[str]]] = (
+            asyncio.create_task(listener.wait(timeout_seconds)) if listener else None
+        )
+
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                r = await client.integrations.reconcile(
+                    sandbox_id, app=app, scope=scope
+                )
+                for c in r.get("connections", []):
+                    if c["source_id"] not in known_before:
+                        if redirect_task is not None:
+                            redirect_task.cancel()
+                        return ConnectFlowResult(
+                            connection=dict(c), session_id=session_id
+                        )
+            except Exception:
+                pass
+
+            if redirect_task is not None and redirect_task.done():
+                outcome = redirect_task.result()
+                if outcome == "error":
+                    raise RuntimeError(
+                        "User denied the authorization or provider returned an error."
+                    )
+
+            await asyncio.sleep(2.0)
+
+        raise TimeoutError(
+            f"Timed out after {int(timeout_seconds)}s — the connection may still "
+            "land. Check `client.integrations.list(sandbox_id)` or run reconcile."
+        )
+    finally:
+        if listener is not None:
+            listener.close()
+
+
+__all__ = ["run_connect_flow", "ConnectFlowResult", "OnConnectUrl"]

copass_agent_router-0.5.0/src/copass_agent_router/router.py

@@ -0,0 +1,194 @@
+"""``AgentRouter`` — high-level Copass agent SDK.
+
+Mirrors ``@copass/agent-router`` on the TS side. Hides SSE parsing and
+OAuth connect-flow orchestration behind a :class:`CopassClient` built
+from the caller's auth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, List, Optional
+
+import httpx
+
+from copass_core import CopassClient
+from copass_core.client import AuthConfig
+from copass_core_agents.events import AgentEvent
+
+from copass_agent_router.connect_flow import (
+    ConnectFlowResult,
+    OnConnectUrl,
+    run_connect_flow,
+)
+from copass_agent_router.sse import frame_to_agent_event, iterate_sse_frames
+
+
+DEFAULT_API_URL = "https://ai.copass.id"
+
+
+@dataclass
+class RunAgentOptions:
+    """Options for :meth:`AgentRouter.run`."""
+
+    provider: str
+    model: str
+    system: str
+    end_user_id: str
+    message: Optional[str] = None
+    messages: Optional[List[dict]] = None
+    session_id: Optional[str] = None
+    reasoning_engine_id: Optional[str] = None
+    location: Optional[str] = None
+
+
+class IntegrationsFacade:
+    """Provider-neutral integrations surface with flow helpers."""
+
+    def __init__(self, client: CopassClient, default_sandbox_id: str) -> None:
+        self._client = client
+        self._default_sandbox_id = default_sandbox_id
+
+    def _sb(self, sandbox_id: Optional[str]) -> str:
+        sid = sandbox_id or self._default_sandbox_id
+        if not sid:
+            raise ValueError("sandbox_id is required (no default on AgentRouter).")
+        return sid
+
+    async def catalog(
+        self,
+        *,
+        q: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> dict:
+        return await self._client.integrations.catalog(
+            self._sb(sandbox_id), q=q, limit=limit, cursor=cursor
+        )
+
+    async def connect(
+        self,
+        app: str,
+        *,
+        on_connect_url: OnConnectUrl,
+        scope: str = "user",
+        project_id: Optional[str] = None,
+        timeout_seconds: float = 300.0,
+        success_uri: Optional[str] = None,
+        error_uri: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ConnectFlowResult:
+        return await run_connect_flow(
+            self._client,
+            self._sb(sandbox_id),
+            app=app,
+            on_connect_url=on_connect_url,
+            scope=scope,
+            project_id=project_id,
+            timeout_seconds=timeout_seconds,
+            success_uri=success_uri,
+            error_uri=error_uri,
+        )
+
+    async def list(
+        self, *, app: Optional[str] = None, sandbox_id: Optional[str] = None
+    ) -> dict:
+        return await self._client.integrations.list(self._sb(sandbox_id), app=app)
+
+    async def disconnect(
+        self, source_id: str, *, sandbox_id: Optional[str] = None
+    ) -> None:
+        await self._client.integrations.disconnect(self._sb(sandbox_id), source_id)
+
+    async def reconcile(
+        self,
+        *,
+        app: Optional[str] = None,
+        scope: str = "user",
+        project_id: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> dict:
+        return await self._client.integrations.reconcile(
+            self._sb(sandbox_id), app=app, scope=scope, project_id=project_id
+        )
+
+
+class AgentRouter:
+    """Top-level agent router SDK."""
+
+    def __init__(
+        self,
+        *,
+        auth: AuthConfig,
+        sandbox_id: str,
+        api_url: str = DEFAULT_API_URL,
+        client: Optional[CopassClient] = None,
+    ) -> None:
+        self.client = client or CopassClient(auth=auth, api_url=api_url)
+        self._api_url = api_url
+        self._default_sandbox_id = sandbox_id
+        self.integrations = IntegrationsFacade(self.client, sandbox_id)
+
+    async def run(
+        self,
+        options: RunAgentOptions,
+        *,
+        sandbox_id: Optional[str] = None,
+    ) -> AsyncIterator[AgentEvent]:
+        """Run an agent turn and yield neutral :class:`AgentEvent` values."""
+        sb = sandbox_id or self._default_sandbox_id
+        if not sb:
+            raise ValueError("sandbox_id is required.")
+
+        messages = options.messages
+        if messages is None:
+            if not options.message:
+                raise ValueError("Either `message` or `messages` must be supplied.")
+            messages = [{"role": "user", "content": options.message}]
+
+        body: dict[str, Any] = {
+            "provider": options.provider,
+            "model": options.model,
+            "system_prompt": options.system,
+            "messages": messages,
+            "end_user_id": options.end_user_id,
+        }
+        if options.session_id is not None:
+            body["session_id"] = options.session_id
+        if options.reasoning_engine_id is not None:
+            body["reasoning_engine_id"] = options.reasoning_engine_id
+        if options.location is not None:
+            body["location"] = options.location
+
+        # Resolve auth via the client's auth provider so headers match.
+        auth_provider = getattr(self.client, "_auth_provider", None)
+        session = (
+            await auth_provider.get_session() if auth_provider is not None else None
+        )
+        headers = {
+            "content-type": "application/json",
+            "accept": "text/event-stream",
+        }
+        token = getattr(session, "access_token", None) if session else None
+        if token:
+            headers["authorization"] = f"Bearer {token}"
+
+        url = (
+            f"{self._api_url.rstrip('/')}"
+            f"/api/v1/storage/sandboxes/{sb}/agents/run"
+        )
+        async with httpx.AsyncClient(timeout=None) as http:
+            async with http.stream("POST", url, headers=headers, json=body) as resp:
+                if resp.status_code >= 400:
+                    text = (await resp.aread()).decode("utf-8", errors="replace")
+                    raise RuntimeError(
+                        f"agents.run: HTTP {resp.status_code} {text[:300]}"
+                    )
+                async for frame in iterate_sse_frames(resp):
+                    event = frame_to_agent_event(frame)
+                    if event is not None:
+                        yield event
+
+
+__all__ = ["AgentRouter", "IntegrationsFacade", "RunAgentOptions"]

copass_agent_router-0.5.0/src/copass_agent_router/sse.py

@@ -0,0 +1,116 @@
+"""Minimal SSE parser for Copass's agent-run endpoint.
+
+Translates raw SSE frames into neutral :class:`AgentEvent` values from
+``copass-core-agents``. Handles CRLF/LF line endings, multi-line
+``data:`` fields, and comment/id/retry skipping.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import AsyncIterator, Optional
+
+import httpx
+
+from copass_core_agents.events import (
+    AgentEvent,
+    AgentFinish,
+    AgentTextDelta,
+    AgentToolCall,
+    AgentToolResult,
+)
+
+
+@dataclass(frozen=True)
+class RawSseFrame:
+    event: str
+    data: str
+
+
+def _parse_block(block: str) -> Optional[RawSseFrame]:
+    event = "message"
+    data_lines: list[str] = []
+    for raw in block.split("\n"):
+        line = raw.rstrip("\r")
+        if not line or line.startswith(":"):
+            continue
+        colon = line.find(":")
+        if colon < 0:
+            continue
+        field = line[:colon]
+        value = line[colon + 1 :]
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event = value
+        elif field == "data":
+            data_lines.append(value)
+    if not data_lines:
+        return None
+    return RawSseFrame(event=event, data="\n".join(data_lines))
+
+
+async def iterate_sse_frames(response: httpx.Response) -> AsyncIterator[RawSseFrame]:
+    """Async-iterate SSE frames off an ``httpx`` streaming Response.
+
+    Caller is expected to have opened the response with ``stream=True``
+    (i.e. via ``client.stream(...)``). We don't read the full body in
+    one shot — each frame is yielded as it arrives.
+    """
+    buffer = ""
+    async for chunk in response.aiter_text():
+        buffer += chunk
+        buffer = buffer.replace("\r\n", "\n")
+        while True:
+            sep = buffer.find("\n\n")
+            if sep < 0:
+                break
+            block = buffer[:sep]
+            buffer = buffer[sep + 2 :]
+            frame = _parse_block(block)
+            if frame is not None:
+                yield frame
+    tail = buffer.strip()
+    if tail:
+        frame = _parse_block(tail)
+        if frame is not None:
+            yield frame
+
+
+def frame_to_agent_event(frame: RawSseFrame) -> Optional[AgentEvent]:
+    """Translate a Copass SSE frame into a neutral :class:`AgentEvent`.
+
+    Returns ``None`` for unrecognized event names or malformed JSON.
+    """
+    try:
+        payload = json.loads(frame.data)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    if frame.event == "agent_text_delta":
+        return AgentTextDelta(text=str(payload.get("text", "")))
+    if frame.event == "agent_tool_call":
+        return AgentToolCall(
+            call_id=str(payload.get("call_id", "")),
+            name=str(payload.get("name", "")),
+            arguments=dict(payload.get("arguments") or {}),
+        )
+    if frame.event == "agent_tool_result":
+        return AgentToolResult(
+            call_id=str(payload.get("call_id", "")),
+            name=str(payload.get("name", "")),
+            result=dict(payload.get("result") or {}),
+            error=(str(payload["error"]) if payload.get("error") else None),
+        )
+    if frame.event == "agent_finish":
+        return AgentFinish(
+            stop_reason=str(payload.get("stop_reason", "unknown")),
+            session_id=(payload.get("session_id") or None),
+            usage=dict(payload.get("usage") or {}),
+        )
+    return None
+
+
+__all__ = ["RawSseFrame", "iterate_sse_frames", "frame_to_agent_event"]