chatatp-studio 0.1.0__tar.gz

chatatp_studio-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: chatatp-studio
+Version: 0.1.0
+Summary: Official Python SDK for ChatATP Studio Developer API
+Author-email: Samuel Obinna Chimdi <sammyfirst6@gmail.com>
+License: MIT
+Project-URL: Homepage, https://studio.chat-atp.com
+Project-URL: Documentation, https://studio.chat-atp.com/docs
+Project-URL: Source, https://github.com/sam-14uel/chatatp_studio_python
+Project-URL: Issues, https://github.com/sam-14uel/chatatp_studio_python/issues
+Keywords: chatatp,chatatp-studio,agent-sdk,ai-agents,llm-agents,chatbot-sdk,api-client,developer-tools,async-client,python-sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# ChatATP Studio SDK
+
+Python SDK for building and interacting with agents created in ChatATP Studio.
+
+- Async-first API
+- Conversation lifecycle management
+- Streaming support
+- Fully typed
+
+![PyPI](https://img.shields.io/pypi/v/chatatp-studio)
+![Python](https://img.shields.io/pypi/pyversions/chatatp-studio)
+
+# chatatp-studio
+
+Official Python SDK for the [ChatATP Studio](https://studio.chat-atp.com) Developer API.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install chatatp-studio
+```
+
+## Quick start
+
+```python
+import asyncio
+from chatatp_studio import ChatATPClient
+
+async def main():
+    client = ChatATPClient(api_key="chatatp_sk_...")
+
+    # Send a message — conversation lifecycle handled automatically
+    result = await client.chat(
+        agent_id=7,
+        external_user_id="user_12345",
+        message="Do you ship to Lagos?",
+    )
+
+    print(result.agent_message.content)
+    # → "Yes, shipping is available."
+
+    await client.aclose()
+
+asyncio.run(main())
+```
+
+## Context manager
+
+```python
+async with ChatATPClient(api_key="chatatp_sk_...") as client:
+    result = await client.chat(
+        agent_id=7,
+        external_user_id="user_12345",
+        message="Hello!",
+    )
+```
+
+## Streaming
+
+```python
+async for event in await client.chat_stream(
+    agent_id=7,
+    external_user_id="user_12345",
+    message="Give me a summary of your return policy.",
+):
+    if event.type == "agent.response.completed":
+        print(event.data)
+```
+
+## Resources
+
+```python
+# Agents
+page  = await client.agents.list()
+agent = await client.agents.retrieve(7)
+
+# Conversations
+conv = await client.conversations.create(7, "user_12345")
+page = await client.conversations.list(agent_id=7)
+await client.conversations.delete(conv.id)
+
+# Messages
+history = await client.messages.list(conv.id)
+reply   = await client.messages.send(conv.id, "Hello")
+
+# Usage
+usage = await client.usage.retrieve()
+```
+
+## Error handling
+
+```python
+from chatatp_studio import NotFoundError, RateLimitError
+
+try:
+    await client.agents.retrieve(999)
+except NotFoundError:
+    print("Not found")
+except RateLimitError:
+    print("Rate limited")
+```
+
+## License
+
+MIT

chatatp_studio-0.1.0/README.md

@@ -0,0 +1,109 @@
+# ChatATP Studio SDK
+
+Python SDK for building and interacting with agents created in ChatATP Studio.
+
+- Async-first API
+- Conversation lifecycle management
+- Streaming support
+- Fully typed
+
+![PyPI](https://img.shields.io/pypi/v/chatatp-studio)
+![Python](https://img.shields.io/pypi/pyversions/chatatp-studio)
+
+# chatatp-studio
+
+Official Python SDK for the [ChatATP Studio](https://studio.chat-atp.com) Developer API.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install chatatp-studio
+```
+
+## Quick start
+
+```python
+import asyncio
+from chatatp_studio import ChatATPClient
+
+async def main():
+    client = ChatATPClient(api_key="chatatp_sk_...")
+
+    # Send a message — conversation lifecycle handled automatically
+    result = await client.chat(
+        agent_id=7,
+        external_user_id="user_12345",
+        message="Do you ship to Lagos?",
+    )
+
+    print(result.agent_message.content)
+    # → "Yes, shipping is available."
+
+    await client.aclose()
+
+asyncio.run(main())
+```
+
+## Context manager
+
+```python
+async with ChatATPClient(api_key="chatatp_sk_...") as client:
+    result = await client.chat(
+        agent_id=7,
+        external_user_id="user_12345",
+        message="Hello!",
+    )
+```
+
+## Streaming
+
+```python
+async for event in await client.chat_stream(
+    agent_id=7,
+    external_user_id="user_12345",
+    message="Give me a summary of your return policy.",
+):
+    if event.type == "agent.response.completed":
+        print(event.data)
+```
+
+## Resources
+
+```python
+# Agents
+page  = await client.agents.list()
+agent = await client.agents.retrieve(7)
+
+# Conversations
+conv = await client.conversations.create(7, "user_12345")
+page = await client.conversations.list(agent_id=7)
+await client.conversations.delete(conv.id)
+
+# Messages
+history = await client.messages.list(conv.id)
+reply   = await client.messages.send(conv.id, "Hello")
+
+# Usage
+usage = await client.usage.retrieve()
+```
+
+## Error handling
+
+```python
+from chatatp_studio import NotFoundError, RateLimitError
+
+try:
+    await client.agents.retrieve(999)
+except NotFoundError:
+    print("Not found")
+except RateLimitError:
+    print("Rate limited")
+```
+
+## License
+
+MIT

chatatp_studio-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chatatp-studio"
+version = "0.1.0"
+description = "Official Python SDK for ChatATP Studio Developer API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+
+authors = [
+  { name = "Samuel Obinna Chimdi", email = "sammyfirst6@gmail.com" }
+]
+
+keywords = [
+  "chatatp",
+  "chatatp-studio",
+  "agent-sdk",
+  "ai-agents",
+  "llm-agents",
+  "chatbot-sdk",
+  "api-client",
+  "developer-tools",
+  "async-client",
+  "python-sdk"
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "License :: OSI Approved :: MIT License"
+]
+
+dependencies = [
+  "httpx>=0.27"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "pytest-httpx>=0.30",
+  "mypy>=1.10",
+  "build",
+  "twine",
+  "ruff"
+]
+
+[project.urls]
+Homepage = "https://studio.chat-atp.com"
+Documentation = "https://studio.chat-atp.com/docs"
+Source = "https://github.com/sam-14uel/chatatp_studio_python"
+Issues = "https://github.com/sam-14uel/chatatp_studio_python/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true

chatatp_studio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chatatp_studio-0.1.0/src/chatatp_studio/__init__.py

@@ -0,0 +1,50 @@
+"""ChatATP Studio Python SDK."""
+
+from .client import ChatATPClient
+from .errors import (
+    ChatATPError,
+    AuthenticationError,
+    PermissionError,
+    ValidationError,
+    RateLimitError,
+    NotFoundError,
+    ServerError,
+    NetworkError,
+    TimeoutError,
+)
+from .models import (
+    Agent,
+    AgentCapabilities,
+    Conversation,
+    ConversationSummary,
+    Message,
+    SendMessageResponse,
+    Usage,
+    StreamEvent,
+    Page,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "ChatATPClient",
+    # Errors
+    "ChatATPError",
+    "AuthenticationError",
+    "PermissionError",
+    "ValidationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ServerError",
+    "NetworkError",
+    "TimeoutError",
+    # Models
+    "Agent",
+    "AgentCapabilities",
+    "Conversation",
+    "ConversationSummary",
+    "Message",
+    "SendMessageResponse",
+    "Usage",
+    "StreamEvent",
+    "Page",
+]

chatatp_studio-0.1.0/src/chatatp_studio/_requester.py

@@ -0,0 +1,180 @@
+"""Low-level HTTP client wrapping httpx."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import httpx
+
+from .errors import NetworkError, TimeoutError, build_api_error
+
+logger = logging.getLogger("chatatp")
+
+DEFAULT_BASE_URL = "https://chatatp-agent-builder-backend.onrender.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+RETRY_INITIAL_DELAY = 0.5
+RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+
+
+class Requester:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        debug: bool = False,
+    ) -> None:
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._debug = debug
+
+        if debug:
+            logging.basicConfig()
+            logger.setLevel(logging.DEBUG)
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=httpx.Timeout(timeout),
+            headers=self._auth_headers(),
+        )
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+
+        attempt = 0
+        delay = RETRY_INITIAL_DELAY
+
+        while True:
+            logger.debug("→ %s %s", method, path)
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    json=body,
+                    params=clean_params or None,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt < self._max_retries:
+                    logger.debug("timeout, retrying in %.1fs", delay)
+                    await _sleep(delay)
+                    delay *= 2
+                    attempt += 1
+                    continue
+                raise TimeoutError(f"Request to {path} timed out.") from exc
+            except httpx.RequestError as exc:
+                if attempt < self._max_retries:
+                    logger.debug("network error, retrying in %.1fs", delay)
+                    await _sleep(delay)
+                    delay *= 2
+                    attempt += 1
+                    continue
+                raise NetworkError(f"Network request failed: {exc}") from exc
+
+            logger.debug("← %s", response.status_code)
+
+            if response.status_code == 204:
+                return None
+
+            body_json: dict[str, Any] = {}
+            try:
+                body_json = response.json()
+            except Exception:
+                pass
+
+            if not response.is_success:
+                request_id = response.headers.get("x-request-id")
+                err = build_api_error(response.status_code, body_json, request_id)
+                if response.status_code in RETRYABLE_STATUSES and attempt < self._max_retries:
+                    logger.debug("retrying in %.1fs (attempt %d)", delay, attempt + 1)
+                    await _sleep(delay)
+                    delay *= 2
+                    attempt += 1
+                    continue
+                raise err
+
+            return body_json
+
+    async def stream(
+        self,
+        path: str,
+        body: Any,
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        """Yield parsed SSE events as dicts with ``type`` and ``data`` keys."""
+        headers = {**self._auth_headers(), "Accept": "text/event-stream"}
+        buffer = ""
+
+        async with self._client.stream(
+            "POST",
+            path,
+            json=body,
+            headers=headers,
+            timeout=httpx.Timeout(self._timeout * 4),
+        ) as response:
+            if not response.is_success:
+                raw = await response.aread()
+                body_json: dict[str, Any] = {}
+                try:
+                    body_json = json.loads(raw)
+                except Exception:
+                    pass
+                raise build_api_error(response.status_code, body_json)
+
+            async for chunk in response.aiter_text():
+                buffer += chunk
+                *events, buffer = buffer.split("\n\n")
+                for block in events:
+                    parsed = _parse_sse_block(block)
+                    if parsed:
+                        logger.debug("← event: %s", parsed["type"])
+                        yield parsed
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "Requester":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+
+def _parse_sse_block(block: str) -> dict[str, Any] | None:
+    event_type = ""
+    data_str = ""
+    for line in block.splitlines():
+        if line.startswith("event:"):
+            event_type = line[6:].strip()
+        elif line.startswith("data:"):
+            data_str = line[5:].strip()
+    if not data_str:
+        return None
+    try:
+        return {"type": event_type, "data": json.loads(data_str)}
+    except json.JSONDecodeError:
+        return {"type": event_type, "data": data_str}
+
+
+async def _sleep(seconds: float) -> None:
+    import asyncio
+    await asyncio.sleep(seconds)

chatatp_studio-0.1.0/src/chatatp_studio/client.py

@@ -0,0 +1,135 @@
+"""Main ChatATP Studio client."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from ._requester import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, Requester
+from .models import SendMessageResponse, StreamEvent
+from .resources import AgentsResource, ConversationsResource, MessagesResource, UsageResource
+
+
+class ChatATPClient:
+    """
+    Async client for the ChatATP Studio Developer API.
+
+    Usage::
+
+        import asyncio
+        from chatatp_studio import ChatATPClient
+
+        async def main():
+            client = ChatATPClient(api_key="chatatp_sk_...")
+            result = await client.chat(
+                agent_id=7,
+                external_user_id="user_12345",
+                message="Do you ship to Lagos?",
+            )
+            print(result.agent_message.content)
+            await client.aclose()
+
+        asyncio.run(main())
+
+    Or as a context manager::
+
+        async with ChatATPClient(api_key="chatatp_sk_...") as client:
+            ...
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        debug: bool = False,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._requester = Requester(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            debug=debug,
+        )
+
+        self.agents = AgentsResource(self._requester)
+        self.conversations = ConversationsResource(self._requester)
+        self.messages = MessagesResource(self._requester)
+        self.usage = UsageResource(self._requester)
+
+    # ──────────────────────────────────────────────
+    # High-level chat interface
+    # ──────────────────────────────────────────────
+
+    async def chat(
+        self,
+        agent_id: int,
+        external_user_id: str,
+        message: str,
+        *,
+        user_display_name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SendMessageResponse:
+        """
+        Send a message to an agent on behalf of a user.
+
+        The SDK automatically creates or retrieves the underlying conversation,
+        so you only need the agent ID, user ID, and message content.
+
+        :param agent_id: The ID of the agent to send the message to.
+        :param external_user_id: Your unique identifier for the end user.
+        :param message: The message content to send.
+        :param user_display_name: Optional human-readable name for the user.
+        :param metadata: Optional key-value metadata attached to the conversation.
+        :returns: A SendMessageResponse with ``user_message`` and ``agent_message``.
+        """
+        conversation = await self.conversations.create(
+            agent_id,
+            external_user_id,
+            user_display_name=user_display_name,
+            metadata=metadata,
+        )
+        return await self.messages.send(conversation.id, message)
+
+    async def chat_stream(
+        self,
+        agent_id: int,
+        external_user_id: str,
+        message: str,
+        *,
+        user_display_name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        """
+        Stream a message response from an agent.
+
+        Like :meth:`chat`, conversation lifecycle is handled automatically.
+
+        Usage::
+
+            async for event in client.chat_stream(7, "user_12345", "Hello"):
+                if event.type == "agent.response.completed":
+                    print(event.data)
+        """
+        conversation = await self.conversations.create(
+            agent_id,
+            external_user_id,
+            user_display_name=user_display_name,
+            metadata=metadata,
+        )
+        return await self.messages.stream(conversation.id, message)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._requester.aclose()
+
+    async def __aenter__(self) -> "ChatATPClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()