cominty-sdk 0.1.0__py3-none-any.whl

cominty_sdk/__init__.py

@@ -0,0 +1,50 @@
+"""Cominty SDK — async Python client for the managed agent chat API."""
+
+from cominty_sdk.client import AsyncCominty
+from cominty_sdk.config import ComintyEnvironment
+from cominty_sdk.exceptions import (
+    AuthenticationError,
+    ComintyAPIError,
+    ComintyError,
+    ComintyServerShuttingDownError,
+    ComintyTimeoutError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from cominty_sdk.models.files import ConversationFileOut
+from cominty_sdk.models.messages import (
+    DocumentCitation,
+    HumanMessage,
+    MessageOut,
+    Question,
+    WebCitation,
+)
+from cominty_sdk.models.threads import ThreadOut, ThreadSummaryOut
+from cominty_sdk.models.usage import UsageReport
+
+__all__ = [
+    "AsyncCominty",
+    "AuthenticationError",
+    "ComintyAPIError",
+    "ComintyEnvironment",
+    "ComintyError",
+    "ComintyServerShuttingDownError",
+    "ComintyTimeoutError",
+    "ConversationFileOut",
+    "DocumentCitation",
+    "HumanMessage",
+    "MessageOut",
+    "NotFoundError",
+    "Question",
+    "RateLimitError",
+    "ServerError",
+    "ThreadOut",
+    "ThreadSummaryOut",
+    "UsageReport",
+    "ValidationError",
+    "WebCitation",
+]
+
+__version__ = "0.1.0"

cominty_sdk/_http.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from cominty_sdk.config import AUTH_HEADER, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from cominty_sdk.exceptions import ComintyTimeoutError, raise_for_status
+from cominty_sdk.retry import compute_backoff, is_retryable_exception, maybe_raise_for_status
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class AsyncHTTPClient:
+    """Internal async HTTP client with auth, retries, and error mapping."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+        stream_timeout: float | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self.stream_timeout = stream_timeout or timeout
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=httpx.Timeout(timeout),
+            headers={AUTH_HEADER: api_key},
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        parse_json: bool = True,
+    ) -> Any:
+        """Send a request with retries and return parsed JSON or raw response."""
+        last_exc: BaseException | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                )
+                body: Any
+                if parse_json:
+                    body = response.json() if response.content else None
+                else:
+                    body = response.content
+
+                if response.status_code >= 400:
+                    maybe_raise_for_status(
+                        response.status_code,
+                        body,
+                        f"{method} {path} failed",
+                    )
+                return body
+            except Exception as exc:
+                if not is_retryable_exception(exc) or attempt >= self.max_retries:
+                    if isinstance(exc, httpx.TimeoutException):
+                        raise ComintyTimeoutError(str(exc)) from exc
+                    raise
+                last_exc = exc
+                await asyncio.sleep(compute_backoff(attempt))
+        assert last_exc is not None
+        raise last_exc
+
+    async def request_model(
+        self,
+        method: str,
+        path: str,
+        model: type[T],
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> T:
+        data = await self.request(method, path, params=params, json=json, headers=headers)
+        return model.model_validate(data)
+
+    async def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> bytes:
+        last_exc: BaseException | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    headers=headers,
+                )
+                if response.status_code >= 400:
+                    body: Any = None
+                    if response.content:
+                        try:
+                            body = response.json()
+                        except Exception:
+                            body = response.text
+                    raise_for_status(
+                        response.status_code,
+                        body,
+                        f"{method} {path} failed",
+                    )
+                return response.content
+            except Exception as exc:
+                if not is_retryable_exception(exc) or attempt >= self.max_retries:
+                    if isinstance(exc, httpx.TimeoutException):
+                        raise ComintyTimeoutError(str(exc)) from exc
+                    raise
+                last_exc = exc
+                await asyncio.sleep(compute_backoff(attempt))
+        assert last_exc is not None
+        raise last_exc
+
+    async def stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Open a streaming HTTP response (caller must close context)."""
+        response = await self._client.stream(
+            method,
+            path,
+            params=params,
+            headers=headers,
+            timeout=httpx.Timeout(self.stream_timeout),
+        ).__aenter__()
+        if response.status_code >= 400:
+            await response.aread()
+            body: Any = None
+            if response.content:
+                try:
+                    body = response.json()
+                except Exception:
+                    body = response.text
+            raise_for_status(response.status_code, body, f"{method} {path} failed")
+        return response
+
+    @property
+    def raw_client(self) -> httpx.AsyncClient:
+        """Expose the underlying httpx client for non-API requests (e.g. S3 upload)."""
+        return self._client

cominty_sdk/_qa.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+StreamEvent = dict[str, Any]
+
+DOCUMENT_CITE_PATTERN = re.compile(
+    r'<cite\s+document_id="([^"]+)"\s+pages="([^"]+)"\s+name="([^"]+)"\s*/>',
+)
+WEB_CITE_PATTERN = re.compile(r'<cite\s+url="(https?://[^"]+)"\s*/>')
+CITE_TAG_PATTERN = re.compile(r"<cite[^>]*/>")
+
+
+def extract_tool_names(events: list[dict[str, Any]] | None) -> list[str]:
+    """Extract tool names from message events, deduplicated preserving order."""
+    if not events:
+        return []
+    names: list[str] = []
+    seen: set[str] = set()
+    for event in events:
+        name = _extract_tool_name_from_event(event)
+        if name and name not in seen:
+            seen.add(name)
+            names.append(name)
+    return names
+
+
+def _extract_tool_name_from_event(event: dict[str, Any]) -> str | None:
+    for key in ("tool_name", "tool", "name"):
+        value = event.get(key)
+        if isinstance(value, str) and value:
+            return value
+    event_type = event.get("type") or event.get("event")
+    if event_type in ("tool_call", "tool_use", "tool"):
+        for key in ("tool_name", "tool", "name"):
+            value = event.get(key)
+            if isinstance(value, str) and value:
+                return value
+    data = event.get("data")
+    if isinstance(data, dict):
+        return _extract_tool_name_from_event(data)
+    return None
+
+
+def extract_cite_tags(content: str) -> list[str]:
+    """Return raw <cite .../> tags found in message content."""
+    return CITE_TAG_PATTERN.findall(content)
+
+
+def parse_document_citations(content: str) -> list[dict[str, str]]:
+    """Parse document citation tags from content."""
+    return [
+        {"document_id": m.group(1), "pages": m.group(2), "name": m.group(3)}
+        for m in DOCUMENT_CITE_PATTERN.finditer(content)
+    ]
+
+
+def parse_web_citations(content: str) -> list[dict[str, str]]:
+    """Parse web citation tags from content."""
+    return [{"url": m.group(1)} for m in WEB_CITE_PATTERN.finditer(content)]
+
+
+async def iter_jsonl_events(response: httpx.Response) -> AsyncIterator[StreamEvent]:
+    """Parse a JSONL stream into async event dicts."""
+    async for line in response.aiter_lines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        yield json.loads(stripped)

cominty_sdk/_streaming.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+from cominty_sdk._qa import StreamEvent, iter_jsonl_events
+
+if TYPE_CHECKING:
+    from cominty_sdk._http import AsyncHTTPClient
+
+
+async def stream_message_events(
+    http: AsyncHTTPClient,
+    message_id: str,
+    *,
+    last_event_id: str | None = None,
+) -> AsyncIterator[StreamEvent]:
+    """Stream JSONL events for a message."""
+    headers: dict[str, str] = {}
+    if last_event_id is not None:
+        headers["last-event-id"] = last_event_id
+
+    response = await http.stream_request(
+        "GET",
+        f"/chat/messages/{message_id}/stream",
+        headers=headers or None,
+    )
+    try:
+        async for event in iter_jsonl_events(response):
+            yield event
+    finally:
+        await response.aclose()

cominty_sdk/client.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import os
+from typing import Self
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from cominty_sdk._http import AsyncHTTPClient
+from cominty_sdk.config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_STREAM_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    ComintyEnvironment,
+)
+from cominty_sdk.exceptions import resolve_base_url
+from cominty_sdk.resources.chat import ChatResource
+from cominty_sdk.resources.files import FilesResource
+from cominty_sdk.resources.messages import MessagesResource
+from cominty_sdk.resources.threads import ThreadsResource
+from cominty_sdk.resources.usage import UsageResource
+
+
+class ClientSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="COMINTY_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    api_key: str | None = None
+    api_url: str | None = None
+    environment: ComintyEnvironment = ComintyEnvironment.PRODUCTION
+    agent_id: str | None = None
+    max_retries: int = DEFAULT_MAX_RETRIES
+    timeout: float = DEFAULT_TIMEOUT
+    stream_timeout: float = DEFAULT_STREAM_TIMEOUT
+
+
+class AsyncCominty:
+    """Async client for the Cominty managed agent chat API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        environment: ComintyEnvironment | str | None = None,
+        agent_id: str | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+        stream_timeout: float = DEFAULT_STREAM_TIMEOUT,
+    ) -> None:
+        settings = ClientSettings()
+        resolved_api_key = api_key or settings.api_key or os.environ.get("COMINTY_API_KEY")
+        if not resolved_api_key:
+            raise ValueError(
+                "API key is required. Pass api_key= or set COMINTY_API_KEY."
+            )
+
+        resolved_base_url = resolve_base_url(
+            base_url=base_url or settings.api_url,
+            environment=environment or settings.environment,
+        )
+        resolved_agent_id = agent_id or settings.agent_id
+        if max_retries != DEFAULT_MAX_RETRIES:
+            resolved_max_retries = max_retries
+        else:
+            resolved_max_retries = settings.max_retries
+        resolved_timeout = timeout if timeout != DEFAULT_TIMEOUT else settings.timeout
+        resolved_stream_timeout = (
+            stream_timeout
+            if stream_timeout != DEFAULT_STREAM_TIMEOUT
+            else settings.stream_timeout
+        )
+
+        self._http = AsyncHTTPClient(
+            base_url=resolved_base_url,
+            api_key=resolved_api_key,
+            max_retries=resolved_max_retries,
+            timeout=resolved_timeout,
+            stream_timeout=resolved_stream_timeout,
+        )
+
+        self.threads = ThreadsResource(self._http)
+        self.messages = MessagesResource(
+            self._http,
+            default_agent_id=resolved_agent_id,
+            threads=self.threads,
+        )
+        self.chat = ChatResource(
+            self._http,
+            default_agent_id=resolved_agent_id,
+            threads=self.threads,
+            messages=self.messages,
+        )
+        self.files = FilesResource(self._http)
+        self.usage = UsageResource(self._http)
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

cominty_sdk/config.py

@@ -0,0 +1,29 @@
+from enum import StrEnum
+from typing import Literal
+
+DEFAULT_BASE_URLS: dict[str, str] = {
+    "dev": "https://api.dev.cominty.com",
+    "staging": "https://api.staging.cominty.com",
+    "production": "https://api.cominty.com",
+}
+
+
+class ComintyEnvironment(StrEnum):
+    DEV = "dev"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+
+EnvironmentName = Literal["dev", "staging", "production"]
+
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_STREAM_TIMEOUT = 300.0
+DEFAULT_POLL_INTERVAL = 1.0
+DEFAULT_POLL_TIMEOUT = 120.0
+
+# Message statuses that indicate the agent is still processing.
+NON_TERMINAL_STATUSES = frozenset({"pending", "running", "in_progress", "processing"})
+
+# Header used for API key authentication.
+AUTH_HEADER = "x-cominty-token"

cominty_sdk/exceptions.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+
+from cominty_sdk.config import DEFAULT_BASE_URLS, ComintyEnvironment
+
+
+class ComintyError(Exception):
+    """Base exception for all Cominty SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+
+
+class ComintyAPIError(ComintyError):
+    """Raised when the API returns an error response."""
+
+
+class AuthenticationError(ComintyAPIError):
+    """Raised on 401 Unauthorized."""
+
+
+class NotFoundError(ComintyAPIError):
+    """Raised on 404 Not Found."""
+
+
+class ValidationError(ComintyAPIError):
+    """Raised on 422 Unprocessable Entity."""
+
+
+class RateLimitError(ComintyAPIError):
+    """Raised on 429 Too Many Requests."""
+
+
+class ServerError(ComintyAPIError):
+    """Raised on 5xx server errors."""
+
+
+class ComintyTimeoutError(ComintyError):
+    """Raised when a request or poll operation times out."""
+
+
+class ComintyServerShuttingDownError(ComintyError):
+    """Raised when the API returns a partial response due to server shutdown."""
+
+
+def raise_for_status(status_code: int, body: Any, message: str | None = None) -> None:
+    """Map HTTP status codes to typed exceptions."""
+    msg = message or f"API request failed with status {status_code}"
+    if status_code == 401:
+        raise AuthenticationError(msg, status_code=status_code, body=body)
+    if status_code == 404:
+        raise NotFoundError(msg, status_code=status_code, body=body)
+    if status_code == 422:
+        raise ValidationError(msg, status_code=status_code, body=body)
+    if status_code == 429:
+        raise RateLimitError(msg, status_code=status_code, body=body)
+    if 500 <= status_code < 600:
+        raise ServerError(msg, status_code=status_code, body=body)
+    if 400 <= status_code < 500:
+        raise ComintyAPIError(msg, status_code=status_code, body=body)
+
+
+def resolve_base_url(
+    *,
+    base_url: str | None = None,
+    environment: ComintyEnvironment | str | None = None,
+) -> str:
+    """Resolve the API base URL from explicit override or environment name."""
+    if base_url is not None:
+        return base_url.rstrip("/")
+    env = environment or ComintyEnvironment.PRODUCTION
+    env_name = env.value if isinstance(env, ComintyEnvironment) else env
+    try:
+        return DEFAULT_BASE_URLS[env_name].rstrip("/")
+    except KeyError as exc:
+        raise ValueError(
+            f"Unknown environment {env_name!r}. "
+            f"Expected one of: {', '.join(DEFAULT_BASE_URLS)}"
+        ) from exc

cominty_sdk/models/__init__.py

@@ -0,0 +1,38 @@
+from cominty_sdk.models.files import (
+    ConversationFileOut,
+    FileUploadConfirmation,
+    FileUploadPermission,
+)
+from cominty_sdk.models.messages import (
+    ChatOptions,
+    ChatRequest,
+    DocumentCitation,
+    HumanMessage,
+    MessageOut,
+    Question,
+    StartChatOptions,
+    StartChatRequest,
+    WebCitation,
+)
+from cominty_sdk.models.threads import ThreadOut, ThreadSummaryOut, ThreadUpdate
+from cominty_sdk.models.usage import AgentDetail, UsageReport
+
+__all__ = [
+    "AgentDetail",
+    "ChatOptions",
+    "ChatRequest",
+    "ConversationFileOut",
+    "DocumentCitation",
+    "FileUploadConfirmation",
+    "FileUploadPermission",
+    "HumanMessage",
+    "MessageOut",
+    "Question",
+    "StartChatOptions",
+    "StartChatRequest",
+    "ThreadOut",
+    "ThreadSummaryOut",
+    "ThreadUpdate",
+    "UsageReport",
+    "WebCitation",
+]

cominty_sdk/models/files.py

@@ -0,0 +1,30 @@
+"""Pydantic models for chat file operations."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FileUploadPermission(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    url: str
+    fields: dict[str, str] = Field(default_factory=dict)
+
+
+class FileUploadConfirmation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    etag: str
+    key: str
+
+
+class ConversationFileOut(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    name: str
+    size: int
+    mimetype: str
+    origin: str
+    url: str | None = None