cominty-sdk 0.1.0__tar.gz

cominty_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.env

cominty_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: cominty-sdk
+Version: 0.1.0
+Summary: Official async Python client for the Cominty managed agent chat API
+Project-URL: Homepage, https://github.com/cominty/python-sdk
+Project-URL: Repository, https://github.com/cominty/python-sdk
+Author: Cominty
+License: MIT
+Keywords: agent,chat,cominty,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cominty Python SDK
+
+Official async Python client for the Cominty managed agent chat API.
+
+## Requirements
+
+- Python 3.11+
+- A Cominty API key
+
+## Installation
+
+```bash
+pip install cominty-sdk
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add cominty-sdk
+```
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `COMINTY_API_KEY` | API key (required) |
+| `COMINTY_API_URL` | Override base URL (optional, takes priority) |
+| `COMINTY_ENVIRONMENT` | `dev`, `staging`, or `production` (default: `production`) |
+| `COMINTY_AGENT_ID` | Default agent ID for chat operations |
+| `COMINTY_MAX_RETRIES` | Max retries on transient errors (default: `3`) |
+| `COMINTY_TIMEOUT` | Request timeout in seconds (default: `60`) |
+
+Default base URLs are placeholders and can be overridden with `COMINTY_API_URL`:
+
+- `dev`: `https://api.dev.cominty.com`
+- `staging`: `https://api.staging.cominty.com`
+- `production`: `https://api.cominty.com`
+
+Authentication uses the `x-cominty-token` header.
+
+## Quick start
+
+```python
+import asyncio
+
+from cominty_sdk import AsyncCominty, HumanMessage
+
+
+async def main() -> None:
+    async with AsyncCominty() as client:
+        thread, reply = await client.chat.start_and_wait(
+            HumanMessage(content="What is Cominty?"),
+            agent_id="your-agent-id",
+        )
+        print(reply.content)
+        print(reply.tool_names)
+
+
+asyncio.run(main())
+```
+
+## Send a message in an existing thread
+
+```python
+message = await client.messages.send_and_wait(
+    thread_id=thread.id,
+    message=HumanMessage(
+        content="Search our docs for onboarding steps",
+        source_ids=[42],
+        disabled_tools=["web"],
+    ),
+    agent_id="your-agent-id",
+)
+```
+
+## Upload a file
+
+Upload is a single high-level call that performs the 3-step S3 flow internally:
+
+```python
+file_id = await client.files.upload("report.pdf")
+
+await client.messages.send_and_wait(
+    thread_id=thread.id,
+    message=HumanMessage(content="Summarize this file", file_ids=[file_id]),
+    agent_id="your-agent-id",
+)
+```
+
+## Streaming
+
+The API returns JSONL events on the stream endpoint:
+
+```python
+async for event in client.messages.stream(message.id):
+    print(event)
+```
+
+## QA helpers
+
+`MessageOut` exposes convenience accessors for automated QA:
+
+```python
+reply.tool_names           # tools invoked (from events)
+reply.cite_tags            # raw <cite .../> tags
+reply.document_citations   # parsed document citations
+reply.web_citations        # parsed web citations
+```
+
+## Covered endpoints
+
+| Resource | Methods |
+|----------|---------|
+| Threads | `list`, `get`, `update`, `archive` |
+| Chat | `start`, `start_and_wait` |
+| Messages | `send`, `send_and_wait`, `wait_until_done`, `cancel`, `export`, `stream` |
+| Files | `upload`, `download` |
+| Usage | `get` |
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+uv run ruff check .
+uv run mypy
+```
+
+Integration tests are opt-in:
+
+```bash
+COMINTY_API_KEY=... COMINTY_AGENT_ID=... uv run pytest -m integration
+```
+
+## License
+
+MIT

cominty_sdk-0.1.0/README.md

@@ -0,0 +1,137 @@
+# Cominty Python SDK
+
+Official async Python client for the Cominty managed agent chat API.
+
+## Requirements
+
+- Python 3.11+
+- A Cominty API key
+
+## Installation
+
+```bash
+pip install cominty-sdk
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add cominty-sdk
+```
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `COMINTY_API_KEY` | API key (required) |
+| `COMINTY_API_URL` | Override base URL (optional, takes priority) |
+| `COMINTY_ENVIRONMENT` | `dev`, `staging`, or `production` (default: `production`) |
+| `COMINTY_AGENT_ID` | Default agent ID for chat operations |
+| `COMINTY_MAX_RETRIES` | Max retries on transient errors (default: `3`) |
+| `COMINTY_TIMEOUT` | Request timeout in seconds (default: `60`) |
+
+Default base URLs are placeholders and can be overridden with `COMINTY_API_URL`:
+
+- `dev`: `https://api.dev.cominty.com`
+- `staging`: `https://api.staging.cominty.com`
+- `production`: `https://api.cominty.com`
+
+Authentication uses the `x-cominty-token` header.
+
+## Quick start
+
+```python
+import asyncio
+
+from cominty_sdk import AsyncCominty, HumanMessage
+
+
+async def main() -> None:
+    async with AsyncCominty() as client:
+        thread, reply = await client.chat.start_and_wait(
+            HumanMessage(content="What is Cominty?"),
+            agent_id="your-agent-id",
+        )
+        print(reply.content)
+        print(reply.tool_names)
+
+
+asyncio.run(main())
+```
+
+## Send a message in an existing thread
+
+```python
+message = await client.messages.send_and_wait(
+    thread_id=thread.id,
+    message=HumanMessage(
+        content="Search our docs for onboarding steps",
+        source_ids=[42],
+        disabled_tools=["web"],
+    ),
+    agent_id="your-agent-id",
+)
+```
+
+## Upload a file
+
+Upload is a single high-level call that performs the 3-step S3 flow internally:
+
+```python
+file_id = await client.files.upload("report.pdf")
+
+await client.messages.send_and_wait(
+    thread_id=thread.id,
+    message=HumanMessage(content="Summarize this file", file_ids=[file_id]),
+    agent_id="your-agent-id",
+)
+```
+
+## Streaming
+
+The API returns JSONL events on the stream endpoint:
+
+```python
+async for event in client.messages.stream(message.id):
+    print(event)
+```
+
+## QA helpers
+
+`MessageOut` exposes convenience accessors for automated QA:
+
+```python
+reply.tool_names           # tools invoked (from events)
+reply.cite_tags            # raw <cite .../> tags
+reply.document_citations   # parsed document citations
+reply.web_citations        # parsed web citations
+```
+
+## Covered endpoints
+
+| Resource | Methods |
+|----------|---------|
+| Threads | `list`, `get`, `update`, `archive` |
+| Chat | `start`, `start_and_wait` |
+| Messages | `send`, `send_and_wait`, `wait_until_done`, `cancel`, `export`, `stream` |
+| Files | `upload`, `download` |
+| Usage | `get` |
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+uv run ruff check .
+uv run mypy
+```
+
+Integration tests are opt-in:
+
+```bash
+COMINTY_API_KEY=... COMINTY_AGENT_ID=... uv run pytest -m integration
+```
+
+## License
+
+MIT

cominty_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "cominty-sdk"
+version = "0.1.0"
+description = "Official async Python client for the Cominty managed agent chat API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Cominty" }]
+keywords = ["cominty", "sdk", "agent", "chat"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2",
+    "pydantic-settings>=2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/cominty/python-sdk"
+Repository = "https://github.com/cominty/python-sdk"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cominty_sdk"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/cominty_sdk", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = [
+    "integration: opt-in tests requiring COMINTY_API_KEY",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/cominty_sdk"]
+warn_return_any = true
+warn_unused_configs = true

cominty_sdk-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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()