codespar 0.1.0__py3-none-any.whl

codespar/_http.py

@@ -0,0 +1,140 @@
+"""
+HTTP primitives shared by the async + sync clients.
+
+Every call through the SDK goes through ``request_json`` / ``stream_sse``
+so header injection, auth, project-id threading, and error mapping live
+in one place. Neither the public ``AsyncCodeSpar`` nor ``Session``
+classes import httpx directly — if we ever swap the transport, only
+this file changes.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from .errors import ApiError, StreamError
+
+DEFAULT_BASE_URL = "https://api.codespar.dev"
+
+
+def build_headers(
+    api_key: str, project_id: str | None, *, accept_sse: bool = False
+) -> dict[str, str]:
+    """Standard header set for every authenticated request."""
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": "codespar-python/0.1.0",
+    }
+    if project_id:
+        headers["x-codespar-project"] = project_id
+    if accept_sse:
+        headers["Accept"] = "text/event-stream"
+    else:
+        headers["Accept"] = "application/json"
+    return headers
+
+
+async def request_json(
+    client: httpx.AsyncClient,
+    method: str,
+    path: str,
+    *,
+    api_key: str,
+    project_id: str | None,
+    body: Any = None,
+) -> Any:
+    """Do an authenticated JSON request, return parsed body or raise ApiError."""
+    headers = build_headers(api_key, project_id)
+    try:
+        response = await client.request(
+            method,
+            path,
+            headers=headers,
+            json=body if body is not None else None,
+        )
+    except httpx.HTTPError as exc:  # network, timeout, connect failure
+        raise ApiError(f"{method} {path} failed: {exc}", status=0) from exc
+
+    # 204 No Content — used by close()
+    if response.status_code == 204:
+        return None
+
+    raw = response.text
+    parsed: Any = None
+    if raw:
+        try:
+            parsed = response.json()
+        except json.JSONDecodeError:
+            parsed = raw
+
+    if not response.is_success:
+        code: str | None = None
+        message = f"{method} {path} failed: {response.status_code}"
+        if isinstance(parsed, dict):
+            code = parsed.get("error") if isinstance(parsed.get("error"), str) else None
+            msg = parsed.get("message")
+            if isinstance(msg, str):
+                message = f"{message} — {msg}"
+            elif code:
+                message = f"{message} — {code}"
+        raise ApiError(message, status=response.status_code, body=parsed, code=code)
+
+    return parsed
+
+
+async def stream_sse(
+    client: httpx.AsyncClient,
+    path: str,
+    *,
+    api_key: str,
+    project_id: str | None,
+    body: Any,
+) -> AsyncIterator[dict[str, Any]]:
+    """
+    POST a JSON body and yield parsed SSE data frames from the response.
+
+    Only ``data:`` lines are surfaced to the caller; ``event:`` and
+    comment lines (``: keep-alive``) are swallowed. Each yielded dict
+    is the JSON payload from a single SSE frame. Callers interpret
+    the ``type`` field themselves.
+    """
+    headers = build_headers(api_key, project_id, accept_sse=True)
+    try:
+        async with client.stream(
+            "POST",
+            path,
+            headers=headers,
+            json=body,
+        ) as response:
+            if not response.is_success:
+                raw = await response.aread()
+                text = raw.decode("utf-8", errors="replace")
+                raise ApiError(
+                    f"POST {path} (stream) failed: {response.status_code} — {text[:200]}",
+                    status=response.status_code,
+                    body=text,
+                )
+
+            buffer = ""
+            async for chunk in response.aiter_text():
+                buffer += chunk
+                # SSE frames are separated by blank lines ("\n\n").
+                while "\n\n" in buffer:
+                    frame, buffer = buffer.split("\n\n", 1)
+                    payload: str | None = None
+                    for line in frame.split("\n"):
+                        if line.startswith("data:"):
+                            payload = (payload or "") + line[len("data:") :].strip()
+                    if not payload:
+                        continue
+                    try:
+                        yield json.loads(payload)
+                    except json.JSONDecodeError as exc:
+                        raise StreamError(f"malformed SSE payload: {payload[:120]}") from exc
+    except httpx.HTTPError as exc:
+        raise StreamError(f"POST {path} (stream) transport error: {exc}") from exc

codespar/_presets.py

@@ -0,0 +1,41 @@
+"""
+Server presets — a shortcut so callers can say ``preset="brazilian"``
+instead of listing every server id.
+
+Must stay byte-for-byte identical to the TypeScript SDK
+(``@codespar/sdk``, ``packages/core/src/session.ts``) so the same
+preset yields the same servers across runtimes.
+"""
+
+from __future__ import annotations
+
+from .types import Preset
+
+_PRESET_SERVERS: dict[Preset, list[str]] = {
+    "brazilian": ["zoop", "nuvem-fiscal", "melhor-envio", "z-api", "omie"],
+    "mexican": ["conekta", "facturapi", "skydropx"],
+    "argentinian": ["afip", "andreani"],
+    "colombian": ["wompi", "siigo", "coordinadora"],
+    "all": [
+        "zoop",
+        "nuvem-fiscal",
+        "melhor-envio",
+        "z-api",
+        "omie",
+        "conekta",
+        "facturapi",
+        "afip",
+        "wompi",
+    ],
+}
+
+# Sandbox default when the caller gives no preset + no servers list —
+# enough to demo Brazilian Pix + NF-e without the user picking.
+_SANDBOX_DEFAULT = ["zoop", "nuvem-fiscal"]
+
+
+def preset_to_servers(preset: Preset | None) -> list[str]:
+    """Expand a preset into a list of server ids. Falls back to sandbox default."""
+    if preset is None:
+        return list(_SANDBOX_DEFAULT)
+    return list(_PRESET_SERVERS[preset])

codespar/_sync_client.py

@@ -0,0 +1,232 @@
+"""
+Sync wrappers over ``AsyncCodeSpar`` / ``AsyncSession``.
+
+The async implementation is canonical; these classes do one thing:
+run async methods to completion on a dedicated background event loop
+so sync Python code can use the SDK without rewriting to asyncio.
+
+Using a dedicated loop (not ``asyncio.run`` per call) keeps the
+underlying httpx connection pool alive across calls, which matters
+for scripts that create a session and then iterate over send() ten
+times — we don't want to tear down TLS on every turn.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Coroutine, Iterator
+from types import TracebackType
+from typing import Any, TypeVar
+
+from ._async_client import AsyncCodeSpar
+from ._async_session import AsyncSession
+from .errors import ConfigError
+from .types import (
+    AuthConfig,
+    AuthResult,
+    ProxyRequest,
+    ProxyResult,
+    SendResult,
+    ServerConnection,
+    SessionConfig,
+    SessionInfo,
+    StreamEvent,
+    Tool,
+    ToolResult,
+)
+
+T = TypeVar("T")
+
+
+class _LoopRunner:
+    """Background thread hosting a persistent asyncio loop."""
+
+    def __init__(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._loop.run_forever,
+            name="codespar-async-loop",
+            daemon=True,
+        )
+        self._thread.start()
+
+    def run(self, coro: Coroutine[Any, Any, T]) -> T:
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result()
+
+    def close(self) -> None:
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        self._thread.join(timeout=5)
+        self._loop.close()
+
+
+class Session:
+    """Sync Session — blocking wrapper around ``AsyncSession``."""
+
+    def __init__(self, async_session: AsyncSession, runner: _LoopRunner) -> None:
+        self._async = async_session
+        self._runner = runner
+
+    # ── identity passthroughs ───────────────────────────────────────────
+
+    @property
+    def id(self) -> str:
+        return self._async.id
+
+    @property
+    def user_id(self) -> str:
+        return self._async.user_id
+
+    @property
+    def servers(self) -> list[str]:
+        return self._async.servers
+
+    @property
+    def info(self) -> SessionInfo:
+        return self._async.info
+
+    @property
+    def mcp(self) -> dict[str, Any]:
+        return self._async.mcp
+
+    # ── blocking calls ──────────────────────────────────────────────────
+
+    def tools(self) -> list[Tool]:
+        return self._runner.run(self._async.tools())
+
+    def find_tools(self, intent: str) -> list[Tool]:
+        return self._runner.run(self._async.find_tools(intent))
+
+    def execute(self, tool_name: str, params: dict[str, Any]) -> ToolResult:
+        return self._runner.run(self._async.execute(tool_name, params))
+
+    def proxy_execute(self, request: ProxyRequest) -> ProxyResult:
+        return self._runner.run(self._async.proxy_execute(request))
+
+    def send(self, message: str) -> SendResult:
+        return self._runner.run(self._async.send(message))
+
+    def send_stream(self, message: str) -> Iterator[StreamEvent]:
+        """
+        Sync generator that yields stream events as they arrive on the
+        background event loop. Bridges the async iterator via a queue
+        so calling code stays plain-``for event in session.send_stream``.
+        """
+        import queue
+
+        q: queue.Queue[StreamEvent | object] = queue.Queue()
+        sentinel = object()
+
+        async def pump() -> None:
+            try:
+                async for event in self._async.send_stream(message):
+                    q.put(event)
+            except Exception as exc:
+                q.put(exc)
+            finally:
+                q.put(sentinel)
+
+        future = asyncio.run_coroutine_threadsafe(pump(), self._runner._loop)
+        try:
+            while True:
+                item = q.get()
+                if item is sentinel:
+                    break
+                if isinstance(item, BaseException):
+                    raise item
+                yield item  # type: ignore[misc]
+        finally:
+            # Make sure pump() finishes before the caller moves on.
+            future.result(timeout=1)
+
+    def authorize(self, server_id: str, config: AuthConfig) -> AuthResult:
+        return self._runner.run(self._async.authorize(server_id, config))
+
+    def connections(self) -> list[ServerConnection]:
+        return self._runner.run(self._async.connections())
+
+    def close(self) -> None:
+        self._runner.run(self._async.close())
+
+
+class CodeSpar:
+    """
+    Sync CodeSpar client. Drop-in replacement for the async client when
+    you're writing a script or a sync framework handler.
+
+    Example::
+
+        cs = CodeSpar(api_key="csk_live_...")
+        try:
+            session = cs.create("user_123", preset="brazilian")
+            print(session.send("charge R$500 via Pix").message)
+        finally:
+            cs.close()
+
+    Or as a context manager::
+
+        with CodeSpar(api_key="csk_live_...") as cs:
+            ...
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        project_id: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self._runner = _LoopRunner()
+        # Build the async client *on* the runner's loop so its httpx
+        # transport binds to the right loop from day one.
+        kwargs: dict[str, Any] = {"api_key": api_key, "timeout": timeout}
+        if base_url is not None:
+            kwargs["base_url"] = base_url
+        if project_id is not None:
+            kwargs["project_id"] = project_id
+
+        async def factory() -> AsyncCodeSpar:
+            return AsyncCodeSpar(**kwargs)
+
+        self._async = self._runner.run(factory())
+
+    @property
+    def base_url(self) -> str:
+        return self._async.base_url
+
+    @property
+    def project_id(self) -> str | None:
+        return self._async.project_id
+
+    def create(
+        self,
+        user_id: str,
+        config: SessionConfig | None = None,
+        /,
+        **kwargs: object,
+    ) -> Session:
+        if config is not None and kwargs:
+            raise ConfigError("Pass SessionConfig or keyword arguments, not both.")
+        async_session = self._runner.run(
+            self._async.create(user_id, config, **kwargs)
+        )
+        return Session(async_session, self._runner)
+
+    def close(self) -> None:
+        try:
+            self._runner.run(self._async.aclose())
+        finally:
+            self._runner.close()
+
+    def __enter__(self) -> CodeSpar:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()

codespar/errors.py

@@ -0,0 +1,49 @@
+"""
+Exception hierarchy for the CodeSpar SDK.
+
+Kept shallow — one ``CodeSparError`` root with a handful of
+specialised subclasses. Every network / API failure is wrapped so
+callers can ``except CodeSparError`` without catching the raw httpx
+exception tree (which would bleed the transport into user code).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CodeSparError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(self, message: str, *, cause: BaseException | None = None):
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class ApiError(CodeSparError):
+    """HTTP-level failure returned by the CodeSpar backend."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        body: Any = None,
+        code: str | None = None,
+    ):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.code = code
+
+
+class ConfigError(CodeSparError):
+    """Raised when the SDK is constructed with invalid / missing config."""
+
+
+class NotConnectedError(CodeSparError):
+    """Raised when an operation needs a connected session that isn't ready."""
+
+
+class StreamError(CodeSparError):
+    """Raised when the SSE stream itself fails (parse / transport)."""

codespar/types.py

@@ -0,0 +1,209 @@
+"""
+Type definitions for the CodeSpar Python SDK.
+
+Every shape here mirrors the TypeScript @codespar/sdk types so the
+payloads on the wire match byte-for-byte — the backend
+(codespar-enterprise) is the single source of truth, and both SDKs
+are just client-side adapters over the same HTTP contract.
+
+Using plain dataclasses (not pydantic) to keep the dependency footprint
+small and imports fast. If we need runtime validation later, we can
+layer pydantic on without changing this surface.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+Preset = Literal["brazilian", "mexican", "argentinian", "colombian", "all"]
+HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+SessionStatus = Literal["active", "closed", "error"]
+AuthType = Literal["oauth", "api_key", "cert", "none"]
+
+
+@dataclass(slots=True)
+class ManageConnections:
+    """Options for blocking session creation until servers are connected."""
+
+    wait_for_connections: bool = False
+    timeout: int = 30_000
+
+
+@dataclass(slots=True)
+class SessionConfig:
+    """Per-session configuration passed to ``CodeSpar.create``."""
+
+    servers: list[str] | None = None
+    preset: Preset | None = None
+    manage_connections: ManageConnections | None = None
+    metadata: dict[str, str] | None = None
+    project_id: str | None = None
+
+
+@dataclass(slots=True)
+class Tool:
+    """A tool exposed by a connected server."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    server: str
+
+
+@dataclass(slots=True)
+class ToolResult:
+    """Result of a single tool execution."""
+
+    success: bool
+    data: Any
+    error: str | None
+    duration: int
+    server: str
+    tool: str
+    tool_call_id: str | None = None
+    called_at: str | None = None
+
+
+@dataclass(slots=True)
+class ToolCallRecord:
+    """A row in the backend's session_tool_calls table, surfaced on send/sendStream."""
+
+    id: str
+    tool_name: str
+    server_id: str
+    status: Literal["success", "error"]
+    duration_ms: int
+    input: Any
+    output: Any
+    error_code: str | None
+
+
+@dataclass(slots=True)
+class SendResult:
+    """Final payload of a Session.send natural-language turn."""
+
+    message: str
+    tool_calls: list[ToolCallRecord] = field(default_factory=list)
+    iterations: int = 0
+
+
+@dataclass(slots=True)
+class ServerConnection:
+    """A server the session can call, as seen by the backend."""
+
+    id: str
+    name: str
+    category: str
+    country: str
+    auth_type: AuthType
+    connected: bool
+
+
+@dataclass(slots=True)
+class ProxyRequest:
+    """Raw HTTP proxy call to a connected server's upstream API."""
+
+    server: str
+    endpoint: str
+    method: HttpMethod
+    body: Any = None
+    params: dict[str, Any] | None = None
+    headers: dict[str, str] | None = None
+
+
+@dataclass(slots=True)
+class ProxyResult:
+    """Response of a raw proxy call. `data` is parsed JSON when possible."""
+
+    status: int
+    data: Any
+    headers: dict[str, str]
+    duration: int
+    proxy_call_id: str | None = None
+
+
+@dataclass(slots=True)
+class AuthConfig:
+    """Input to ``Session.authorize`` — where the provider redirects the user."""
+
+    redirect_uri: str
+    scopes: str | None = None
+
+
+@dataclass(slots=True)
+class AuthResult:
+    """Output of ``Session.authorize`` — the Connect Link the end user opens."""
+
+    link_token: str
+    authorize_url: str
+    expires_at: str
+
+
+# Streaming event shapes. These mirror the TS StreamEvent discriminated
+# union; Python doesn't have discriminated unions as first-class, so we
+# use a base + subclasses with a literal `type` tag.
+
+
+@dataclass(slots=True)
+class UserMessageEvent:
+    content: str
+    type: Literal["user_message"] = "user_message"
+
+
+@dataclass(slots=True)
+class AssistantTextEvent:
+    content: str
+    iteration: int
+    type: Literal["assistant_text"] = "assistant_text"
+
+
+@dataclass(slots=True)
+class ToolUseEvent:
+    id: str
+    name: str
+    input: dict[str, Any]
+    type: Literal["tool_use"] = "tool_use"
+
+
+@dataclass(slots=True)
+class ToolResultEvent:
+    tool_call: ToolCallRecord
+    type: Literal["tool_result"] = "tool_result"
+
+
+@dataclass(slots=True)
+class DoneEvent:
+    result: SendResult
+    type: Literal["done"] = "done"
+
+
+@dataclass(slots=True)
+class ErrorEvent:
+    error: str
+    message: str | None = None
+    type: Literal["error"] = "error"
+
+
+StreamEvent = (
+    UserMessageEvent
+    | AssistantTextEvent
+    | ToolUseEvent
+    | ToolResultEvent
+    | DoneEvent
+    | ErrorEvent
+)
+
+
+@dataclass(slots=True)
+class SessionInfo:
+    """Read-only metadata about a session, attached to the Session instance."""
+
+    id: str
+    user_id: str
+    servers: list[str]
+    created_at: datetime
+    status: SessionStatus
+    mcp_url: str
+    mcp_headers: dict[str, str]