codespar 0.1.0__tar.gz

codespar-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg

codespar-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: codespar
+Version: 0.1.0
+Summary: Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America.
+Project-URL: Homepage, https://codespar.dev
+Project-URL: Documentation, https://docs.codespar.dev
+Project-URL: Repository, https://github.com/codespar/codespar
+Project-URL: Issues, https://github.com/codespar/codespar/issues
+Author-email: CodeSpar <hello@codespar.dev>
+License: MIT
+Keywords: agents,ai,commerce,latam,mcp,nfe,pix,stripe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# codespar — Python SDK
+
+Commerce infrastructure for AI agents in Latin America. Pix, NF-e,
+WhatsApp, shipping, banking — one API, no provider-key boilerplate.
+
+[![PyPI](https://img.shields.io/pypi/v/codespar.svg)](https://pypi.org/project/codespar/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codespar.svg)](https://pypi.org/project/codespar/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/codespar/codespar/blob/main/LICENSE)
+
+## Install
+
+```bash
+pip install codespar
+```
+
+Python 3.10+ required.
+
+## Quick start
+
+```python
+from codespar import CodeSpar
+
+cs = CodeSpar(api_key="csk_live_...")
+
+session = cs.create(
+    "user_123",
+    preset="brazilian",   # zoop, nuvem-fiscal, melhor-envio, z-api, omie
+    # project_id="prj_...", # optional — defaults to the org's default project
+)
+
+result = session.send(
+    "Charge R$500 via Pix to +5511999887766 and send the QR code by WhatsApp."
+)
+print(result.message)
+for call in result.tool_calls:
+    print(f"  → {call.tool_name} ({call.duration_ms}ms)")
+
+session.close()
+cs.close()
+```
+
+Or as a context manager:
+
+```python
+with CodeSpar(api_key="csk_live_...") as cs:
+    session = cs.create("user_123", preset="brazilian")
+    print(session.send("Quero pagar R$125 via Pix").message)
+```
+
+## Streaming
+
+```python
+for event in session.send_stream("Process order #BR-7721"):
+    if event.type == "assistant_text":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool_use":
+        print(f"\n→ calling {event.name}...")
+    elif event.type == "tool_result":
+        print(f"  {event.tool_call.status} in {event.tool_call.duration_ms}ms")
+```
+
+## Async
+
+```python
+import asyncio
+from codespar import AsyncCodeSpar
+
+async def main():
+    async with AsyncCodeSpar(api_key="csk_live_...") as cs:
+        session = await cs.create("user_123", preset="brazilian")
+        result = await session.send("charge R$500 via Pix")
+        print(result.message)
+        await session.close()
+
+asyncio.run(main())
+```
+
+## Multi-environment (projects)
+
+CodeSpar scopes every session to an environment (`prj_<id>`). Pass a
+project id on the client for the whole lifetime, or per-session when
+you want to target a different environment:
+
+```python
+# Pin every session this client spawns to the staging project
+cs = CodeSpar(api_key="csk_live_...", project_id="prj_staging0123abcd")
+
+# Override per session
+session = cs.create("user_123", preset="brazilian", project_id="prj_prod0123abcd")
+```
+
+When you omit `project_id`, CodeSpar routes to the org's **default
+project** — always defined, self-healed on first read.
+
+## Raw HTTP proxy
+
+Skip the agent loop and hit a provider API directly through CodeSpar's
+credential vault:
+
+```python
+from codespar import ProxyRequest
+
+response = session.proxy_execute(ProxyRequest(
+    server="stripe-acp",
+    endpoint="/v1/charges",
+    method="POST",
+    body={"amount": 2000, "currency": "brl"},
+))
+print(response.status, response.data)
+```
+
+No API key leaves your machine — CodeSpar injects it server-side.
+
+## Connect Links (OAuth)
+
+```python
+from codespar import AuthConfig
+
+link = session.authorize(
+    "stripe-acp",
+    AuthConfig(redirect_uri="https://your.app/connected"),
+)
+print(f"Open this URL to connect Stripe: {link.authorize_url}")
+```
+
+After the user completes the OAuth flow, CodeSpar stores the tokens in
+the per-project vault and forwards them back to `redirect_uri` with
+`?status=connected&connection_id=<id>` appended.
+
+## Errors
+
+Every failure is wrapped:
+
+```python
+from codespar import ApiError, ConfigError, StreamError
+
+try:
+    session = cs.create("user_123", preset="brazilian")
+except ConfigError as exc:
+    print(f"Bad config: {exc}")
+except ApiError as exc:
+    print(f"Backend said {exc.status}: {exc.code}")
+```
+
+## Design parity with the JS SDK
+
+This package mirrors [`@codespar/sdk`](https://www.npmjs.com/package/@codespar/sdk)
+method-for-method. Same backend, same payloads, same preset names — pick
+the language that fits your stack without giving anything up.
+
+## Links
+
+- [Documentation](https://docs.codespar.dev)
+- [Dashboard](https://dashboard.codespar.dev)
+- [JS SDK (npm)](https://www.npmjs.com/package/@codespar/sdk)
+- [Report a bug](https://github.com/codespar/codespar/issues)

codespar-0.1.0/README.md

@@ -0,0 +1,156 @@
+# codespar — Python SDK
+
+Commerce infrastructure for AI agents in Latin America. Pix, NF-e,
+WhatsApp, shipping, banking — one API, no provider-key boilerplate.
+
+[![PyPI](https://img.shields.io/pypi/v/codespar.svg)](https://pypi.org/project/codespar/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codespar.svg)](https://pypi.org/project/codespar/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/codespar/codespar/blob/main/LICENSE)
+
+## Install
+
+```bash
+pip install codespar
+```
+
+Python 3.10+ required.
+
+## Quick start
+
+```python
+from codespar import CodeSpar
+
+cs = CodeSpar(api_key="csk_live_...")
+
+session = cs.create(
+    "user_123",
+    preset="brazilian",   # zoop, nuvem-fiscal, melhor-envio, z-api, omie
+    # project_id="prj_...", # optional — defaults to the org's default project
+)
+
+result = session.send(
+    "Charge R$500 via Pix to +5511999887766 and send the QR code by WhatsApp."
+)
+print(result.message)
+for call in result.tool_calls:
+    print(f"  → {call.tool_name} ({call.duration_ms}ms)")
+
+session.close()
+cs.close()
+```
+
+Or as a context manager:
+
+```python
+with CodeSpar(api_key="csk_live_...") as cs:
+    session = cs.create("user_123", preset="brazilian")
+    print(session.send("Quero pagar R$125 via Pix").message)
+```
+
+## Streaming
+
+```python
+for event in session.send_stream("Process order #BR-7721"):
+    if event.type == "assistant_text":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool_use":
+        print(f"\n→ calling {event.name}...")
+    elif event.type == "tool_result":
+        print(f"  {event.tool_call.status} in {event.tool_call.duration_ms}ms")
+```
+
+## Async
+
+```python
+import asyncio
+from codespar import AsyncCodeSpar
+
+async def main():
+    async with AsyncCodeSpar(api_key="csk_live_...") as cs:
+        session = await cs.create("user_123", preset="brazilian")
+        result = await session.send("charge R$500 via Pix")
+        print(result.message)
+        await session.close()
+
+asyncio.run(main())
+```
+
+## Multi-environment (projects)
+
+CodeSpar scopes every session to an environment (`prj_<id>`). Pass a
+project id on the client for the whole lifetime, or per-session when
+you want to target a different environment:
+
+```python
+# Pin every session this client spawns to the staging project
+cs = CodeSpar(api_key="csk_live_...", project_id="prj_staging0123abcd")
+
+# Override per session
+session = cs.create("user_123", preset="brazilian", project_id="prj_prod0123abcd")
+```
+
+When you omit `project_id`, CodeSpar routes to the org's **default
+project** — always defined, self-healed on first read.
+
+## Raw HTTP proxy
+
+Skip the agent loop and hit a provider API directly through CodeSpar's
+credential vault:
+
+```python
+from codespar import ProxyRequest
+
+response = session.proxy_execute(ProxyRequest(
+    server="stripe-acp",
+    endpoint="/v1/charges",
+    method="POST",
+    body={"amount": 2000, "currency": "brl"},
+))
+print(response.status, response.data)
+```
+
+No API key leaves your machine — CodeSpar injects it server-side.
+
+## Connect Links (OAuth)
+
+```python
+from codespar import AuthConfig
+
+link = session.authorize(
+    "stripe-acp",
+    AuthConfig(redirect_uri="https://your.app/connected"),
+)
+print(f"Open this URL to connect Stripe: {link.authorize_url}")
+```
+
+After the user completes the OAuth flow, CodeSpar stores the tokens in
+the per-project vault and forwards them back to `redirect_uri` with
+`?status=connected&connection_id=<id>` appended.
+
+## Errors
+
+Every failure is wrapped:
+
+```python
+from codespar import ApiError, ConfigError, StreamError
+
+try:
+    session = cs.create("user_123", preset="brazilian")
+except ConfigError as exc:
+    print(f"Bad config: {exc}")
+except ApiError as exc:
+    print(f"Backend said {exc.status}: {exc.code}")
+```
+
+## Design parity with the JS SDK
+
+This package mirrors [`@codespar/sdk`](https://www.npmjs.com/package/@codespar/sdk)
+method-for-method. Same backend, same payloads, same preset names — pick
+the language that fits your stack without giving anything up.
+
+## Links
+
+- [Documentation](https://docs.codespar.dev)
+- [Dashboard](https://dashboard.codespar.dev)
+- [JS SDK (npm)](https://www.npmjs.com/package/@codespar/sdk)
+- [Report a bug](https://github.com/codespar/codespar/issues)

codespar-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codespar"
+version = "0.1.0"
+description = "Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "CodeSpar", email = "hello@codespar.dev" },
+]
+keywords = ["ai", "agents", "commerce", "latam", "mcp", "stripe", "pix", "nfe"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[project.urls]
+Homepage = "https://codespar.dev"
+Documentation = "https://docs.codespar.dev"
+Repository = "https://github.com/codespar/codespar"
+Issues = "https://github.com/codespar/codespar/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codespar"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true

codespar-0.1.0/src/codespar/__init__.py

@@ -0,0 +1,107 @@
+"""
+CodeSpar Python SDK — commerce infrastructure for AI agents in Latin America.
+
+Two import surfaces:
+
+* ``CodeSpar`` — sync client. Use from scripts, Jupyter, sync web
+  frameworks (Flask, Django views).
+* ``AsyncCodeSpar`` — async client. Use from FastAPI, LangChain,
+  anything already running on asyncio.
+
+Both wrap the same backend (``api.codespar.dev``) and expose the same
+session API, so you can start with sync and upgrade to async without
+changing the surrounding code.
+
+Quick start::
+
+    from codespar import CodeSpar
+
+    cs = CodeSpar(api_key="csk_live_...")
+    session = cs.create("user_123", preset="brazilian")
+    result = session.send("Charge R$500 via Pix to +5511999887766")
+    print(result.message)
+    session.close()
+    cs.close()
+"""
+
+from __future__ import annotations
+
+from ._async_client import AsyncCodeSpar
+from ._async_session import AsyncSession
+from ._sync_client import CodeSpar, Session
+from .errors import (
+    ApiError,
+    CodeSparError,
+    ConfigError,
+    NotConnectedError,
+    StreamError,
+)
+from .types import (
+    AssistantTextEvent,
+    AuthConfig,
+    AuthResult,
+    DoneEvent,
+    ErrorEvent,
+    HttpMethod,
+    ManageConnections,
+    Preset,
+    ProxyRequest,
+    ProxyResult,
+    SendResult,
+    ServerConnection,
+    SessionConfig,
+    SessionInfo,
+    SessionStatus,
+    StreamEvent,
+    Tool,
+    ToolCallRecord,
+    ToolResult,
+    ToolResultEvent,
+    ToolUseEvent,
+    UserMessageEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApiError",
+    "AssistantTextEvent",
+    "AsyncCodeSpar",
+    "AsyncSession",
+    # Connect Links
+    "AuthConfig",
+    "AuthResult",
+    # Clients
+    "CodeSpar",
+    # Errors
+    "CodeSparError",
+    "ConfigError",
+    "DoneEvent",
+    "ErrorEvent",
+    "HttpMethod",
+    "ManageConnections",
+    "NotConnectedError",
+    "Preset",
+    # Proxy
+    "ProxyRequest",
+    "ProxyResult",
+    "SendResult",
+    "ServerConnection",
+    "Session",
+    # Configuration
+    "SessionConfig",
+    # Session output
+    "SessionInfo",
+    "SessionStatus",
+    "StreamError",
+    # Streaming events
+    "StreamEvent",
+    "Tool",
+    "ToolCallRecord",
+    "ToolResult",
+    "ToolResultEvent",
+    "ToolUseEvent",
+    "UserMessageEvent",
+    # Version
+    "__version__",
+]

codespar-0.1.0/src/codespar/_async_client.py

@@ -0,0 +1,178 @@
+"""
+``AsyncCodeSpar`` — the canonical client class.
+
+Holds an httpx.AsyncClient, exposes ``create(user_id, ...)`` to start a
+session, and mirrors the TS ``CodeSpar`` constructor 1:1. The sync
+``CodeSpar`` in ``_sync_client.py`` wraps every call through
+``asyncio.run`` so the lightweight use-case works without the caller
+having to write ``async def``.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._async_session import (
+    AsyncSession,
+    build_session_info,
+    wait_for_connections,
+)
+from ._http import DEFAULT_BASE_URL, request_json
+from ._presets import preset_to_servers
+from .errors import ApiError, ConfigError
+from .types import SessionConfig
+
+
+class AsyncCodeSpar:
+    """
+    Async CodeSpar client. Pass an API key, create sessions, run them,
+    close them. One client can spawn many sessions in parallel.
+
+    Example::
+
+        async with AsyncCodeSpar(api_key="csk_live_...") as cs:
+            session = await cs.create("user_123", preset="brazilian")
+            result = await session.send("charge R$500 via Pix")
+            print(result.message)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        project_id: str | None = None,
+        timeout: float = 60.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key or not api_key.startswith("csk_"):
+            raise ConfigError(
+                "api_key is required and must start with 'csk_'. "
+                "Get one from https://dashboard.codespar.dev."
+            )
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._project_id = project_id
+        # Share one transport across every session spawned by this
+        # client. Closing the client closes every in-flight request.
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=timeout,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def project_id(self) -> str | None:
+        return self._project_id
+
+    async def create(
+        self,
+        user_id: str,
+        config: SessionConfig | None = None,
+        /,
+        **kwargs: object,
+    ) -> AsyncSession:
+        """
+        Start a session scoped to ``user_id``.
+
+        ``config`` can be passed as a ``SessionConfig`` dataclass or as
+        keyword arguments — both shapes work::
+
+            await cs.create("user_123", preset="brazilian")
+            await cs.create("user_123", SessionConfig(preset="brazilian"))
+        """
+        resolved = self._resolve_config(config, kwargs)
+        servers = resolved.servers or preset_to_servers(resolved.preset)
+        project_id = resolved.project_id or self._project_id
+
+        body: dict[str, object] = {"servers": servers, "user_id": user_id}
+        if resolved.metadata:
+            body["metadata"] = resolved.metadata
+
+        data = await request_json(
+            self._client,
+            "POST",
+            "/v1/sessions",
+            api_key=self._api_key,
+            project_id=project_id,
+            body=body,
+        )
+        if not isinstance(data, dict):
+            raise ApiError("create: malformed response", status=0, body=data)
+
+        info = build_session_info(
+            data,
+            base_url=self._base_url,
+            api_key=self._api_key,
+            project_id=project_id,
+        )
+        session = AsyncSession(
+            info=info,
+            client=self._client,
+            api_key=self._api_key,
+            project_id=project_id,
+            base_url=self._base_url,
+        )
+
+        if resolved.manage_connections and resolved.manage_connections.wait_for_connections:
+            await wait_for_connections(
+                session,
+                timeout_ms=resolved.manage_connections.timeout,
+            )
+
+        return session
+
+    # ── lifecycle ───────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx transport."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncCodeSpar:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    # ── internals ───────────────────────────────────────────────────────
+
+    def _resolve_config(
+        self,
+        config: SessionConfig | None,
+        kwargs: dict[str, object],
+    ) -> SessionConfig:
+        """Accept either a SessionConfig dataclass or kwargs, never both."""
+        if config is not None and kwargs:
+            raise ConfigError(
+                "Pass SessionConfig or keyword arguments, not both."
+            )
+        if config is not None:
+            return config
+        if not kwargs:
+            return SessionConfig()
+
+        allowed = {
+            "servers",
+            "preset",
+            "manage_connections",
+            "metadata",
+            "project_id",
+        }
+        unknown = set(kwargs) - allowed
+        if unknown:
+            raise ConfigError(
+                f"create(): unknown keyword argument(s): {', '.join(sorted(unknown))}"
+            )
+        return SessionConfig(**kwargs)  # type: ignore[arg-type]