commb-agent 0.3.0__py3-none-any.whl

commb_agent/__init__.py

@@ -0,0 +1,23 @@
+from .client import (
+    CommBClient,
+    AsyncCommBClient,
+    CommBConfigResponse,
+    BotConfig,
+    BotInfo,
+    KnowledgeDoc,
+    CatalogItem,
+    ChatMessage,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "CommBClient",
+    "AsyncCommBClient",
+    "CommBConfigResponse",
+    "BotConfig",
+    "BotInfo",
+    "KnowledgeDoc",
+    "CatalogItem",
+    "ChatMessage",
+]

commb_agent/client.py

@@ -0,0 +1,677 @@
+"""
+commb-agent — Official Python SDK
+v0.3.0 — Sannex Tech LTD <info@sannex.ng>
+"""
+
+from __future__ import annotations
+
+import asyncio
+import queue
+import threading
+import time
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional
+
+import httpx
+from pydantic import BaseModel, Field
+
+
+# ----------------------------------------------------------
+# Pydantic Response Models
+# ----------------------------------------------------------
+
+class BotConfig(BaseModel):
+    system_prompt: str = ""
+    temperature: float = 0.7
+    model_name: str = "gemini-2.5-flash"
+    llm_provider: str = "gemini"
+    bot_mode: str = "hybrid"
+    catalog_source: str = "local"
+    max_tokens: int = 1024
+
+
+class KnowledgeDoc(BaseModel):
+    id: str
+    title: str
+    category: Optional[str] = None
+    content: str
+    tags: Optional[str] = None
+
+
+class CatalogItem(BaseModel):
+    id: str
+    title: str
+    description: Optional[str] = None
+    price: float
+    currency: str
+    image_url: Optional[str] = None
+    source: Optional[str] = None
+
+
+class BotInfo(BaseModel):
+    id: str
+    name: str
+    slug: Optional[str] = None
+    reseller: Optional[str] = None
+    business_id: Optional[str] = None
+
+
+class AgentSummary(BaseModel):
+    id: str
+    name: str
+    slug: Optional[str] = None
+    description: Optional[str] = None
+    system_prompt: Optional[str] = None
+    model_name: Optional[str] = "gemini-2.5-flash"
+    temperature: Optional[float] = 0.7
+    max_tokens: Optional[int] = 1024
+    llm_provider: Optional[str] = "gemini"
+    is_active: bool = True
+    whatsapp_phone_number_id: Optional[str] = None
+    telegram_bot_token: Optional[str] = None
+    telegram_username: Optional[str] = None
+    widget_enabled: bool = True
+    access_tags: List[str] = Field(default_factory=list)
+
+
+class ReleaseNote(BaseModel):
+    version: str
+    title: str
+    description: Optional[str] = None
+    changelog: List[str] = Field(default_factory=list)
+    release_date: Optional[str] = None
+    is_critical: bool = False
+    download_url: Optional[str] = None
+
+
+class CommBConfigResponse(BaseModel):
+    status: str
+    tenant: Optional[BotInfo] = None
+    config: BotConfig = Field(default_factory=BotConfig)
+    knowledge_docs: List[KnowledgeDoc] = Field(default_factory=list)
+    catalog_items: List[CatalogItem] = Field(default_factory=list)
+    agents: List[AgentSummary] = Field(default_factory=list)
+    releases: List[ReleaseNote] = Field(default_factory=list)
+    support: Optional[Dict[str, Any]] = None
+
+
+class ChatMessage(BaseModel):
+    role: str  # "user" | "assistant"
+    content: str
+
+
+# ----------------------------------------------------------
+# CommBClient — Synchronous (thread-based background flush)
+# ----------------------------------------------------------
+
+class CommBClient:
+    """Official Python Telemetry & Remote Config Client for Sannex AI Operations."""
+
+    def __init__(
+        self,
+        api_key: str,
+        host: str = "https://commb.app",
+        flush_interval: float = 1.0,
+        max_queue_size: int = 1000,
+        agent_id: Optional[str] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key must not be empty.")
+        self.api_key = api_key
+        self.agent_id = agent_id
+        self.host = host.rstrip("/")
+        api_prefix = "/api/v1" if not self.host.endswith("/api") and not self.host.endswith("/v1") else ""
+        self.events_endpoint = f"{self.host}{api_prefix}/events"
+        self.config_endpoint = f"{self.host}{api_prefix}/sync"
+        self.chat_endpoint = f"{self.host}{api_prefix}/chat"
+        self.releases_endpoint = f"{self.host}{api_prefix}/releases"
+        self.feedback_endpoint = f"{self.host}{api_prefix}/feedback"
+        self.flush_interval = flush_interval
+        self._queue: queue.Queue = queue.Queue(maxsize=max_queue_size)
+        self._running = True
+        self._client = httpx.Client(timeout=10.0)
+
+        self._worker_thread = threading.Thread(target=self._worker, daemon=True)
+        self._worker_thread.start()
+
+    def _auth_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def track(
+        self,
+        channel: str,
+        customer_id: str,
+        event: str,
+        status: str = "success",
+        amount: float = 0.0,
+        metadata: Optional[Dict[str, Any]] = None,
+        agent_id: Optional[str] = None,
+    ) -> None:
+        """Enqueue a telemetry event for async dispatch. Never blocks or raises."""
+        eff_agent_id = agent_id or self.agent_id
+        payload = {
+            "channel": channel,
+            "customer_id": str(customer_id),
+            "event": event,
+            "status": status,
+            "amount": float(amount),
+            "metadata": metadata or {},
+            "timestamp": time.time(),
+        }
+        if eff_agent_id:
+            payload["agent_id"] = str(eff_agent_id)
+        try:
+            self._queue.put_nowait(payload)
+        except queue.Full:
+            pass  # Drop silently — telemetry must never degrade host performance
+
+    def get_config(self, agent_id: Optional[str] = None) -> CommBConfigResponse:
+        """Pull bot/agent config, knowledge docs, catalog, and agent roster from CommB collector."""
+        eff_agent_id = agent_id or self.agent_id
+        params = {"agent_id": eff_agent_id} if eff_agent_id else None
+        try:
+            res = self._client.get(self.config_endpoint, headers=self._auth_headers(), params=params)
+            if res.status_code == 200:
+                return CommBConfigResponse.model_validate(res.json())
+        except Exception:
+            pass
+        return CommBConfigResponse(status="error")
+
+    def get_bot(self, agent_id: Optional[str] = None) -> Optional[BotInfo]:
+        """Retrieve basic bot identity (id, name, slug, reseller)."""
+        cfg = self.get_config(agent_id=agent_id)
+        return cfg.tenant
+
+    def get_agents(self) -> List[AgentSummary]:
+        """Retrieve list of all agents under this business/instance."""
+        cfg = self.get_config()
+        return cfg.agents
+
+    def get_releases(
+        self,
+        app_name: str = "commb",
+        app_version: Optional[str] = None,
+    ) -> List[ReleaseNote]:
+        """Fetch CommB platform release notes and updates from CommB collector."""
+        headers = self._auth_headers()
+        headers["X-App-Name"] = str(app_name)
+        if app_version:
+            headers["X-App-Version"] = str(app_version)
+        try:
+            params: Dict[str, Any] = {"app": str(app_name)}
+            if app_version:
+                params["app_version"] = str(app_version)
+            res = self._client.get(
+                self.releases_endpoint,
+                headers=headers,
+                params=params,
+                timeout=10.0,
+            )
+            if res.is_success:
+                data = res.json()
+                items = data.get("releases", data) if isinstance(data, dict) else data
+                if isinstance(items, list):
+                    return [ReleaseNote.model_validate(r) for r in items]
+        except Exception:
+            pass
+        return []
+
+    def send_feedback(
+        self,
+        message: str,
+        category: str = "general",
+        contact_email: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """Send feedback, bug reports, or feature suggestions to CommB collector."""
+        body = {
+            "app": "commb",
+            "category": category,
+            "message": str(message),
+            "contact_email": contact_email,
+            "metadata": metadata or {},
+        }
+        if self.agent_id:
+            body["metadata"]["agent_id"] = self.agent_id
+        try:
+            res = self._client.post(
+                self.feedback_endpoint,
+                headers=self._auth_headers(),
+                json=body,
+                timeout=5.0,
+            )
+            return res.is_success
+        except Exception:
+            return False
+
+    def sync_conversation(
+        self,
+        channel: str,
+        customer_id: str,
+        messages: List[Dict[str, Any]],
+        agent_id: Optional[str] = None,
+    ) -> None:
+        """Push a batched conversation transcript up to CommB collector."""
+        eff_agent_id = agent_id or self.agent_id
+        payload = {
+            "type": "chat_transcript",
+            "channel": channel,
+            "customer_id": str(customer_id),
+            "messages": messages,
+            "timestamp": time.time(),
+        }
+        if eff_agent_id:
+            payload["agent_id"] = str(eff_agent_id)
+        try:
+            self._queue.put_nowait(payload)
+        except queue.Full:
+            pass
+
+    def ping(self) -> bool:
+        """Check if the CommB collector host is reachable. Returns True if healthy."""
+        try:
+            res = self._client.get(
+                f"{self.host}/api/health",
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=5.0,
+            )
+            return res.is_success
+        except Exception:
+            return False
+
+    def stream_chat(
+        self,
+        message: str,
+        user_id: str,
+        history: Optional[List[ChatMessage]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        agent_id: Optional[str] = None,
+    ) -> Iterator[str]:
+        """
+        Stream a chat response from the CommB engine via SSE.
+
+        Usage::
+
+            for chunk in client.stream_chat("Hello!", "user_123"):
+                print(chunk, end="", flush=True)
+        """
+        eff_agent_id = agent_id or self.agent_id
+        body: Dict[str, Any] = {
+            "message": message,
+            "user_id": user_id,
+            "history": [m.model_dump() for m in (history or [])],
+            "metadata": metadata or {},
+        }
+        if eff_agent_id:
+            body["agent_id"] = str(eff_agent_id)
+
+        with self._client.stream(
+            "POST",
+            self.chat_endpoint,
+            headers=self._auth_headers(),
+            json=body,
+        ) as res:
+            res.raise_for_status()
+            buffer = ""
+            for chunk in res.iter_text():
+                buffer += chunk
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    line = line.strip()
+                    if line.startswith("data: "):
+                        data = line[6:].strip()
+                        if data == "[DONE]":
+                            return
+                        try:
+                            import json
+                            parsed = json.loads(data)
+                            text = (
+                                parsed.get("choices", [{}])[0]
+                                .get("delta", {})
+                                .get("content")
+                                or parsed.get("text")
+                                or data
+                            )
+                            if text:
+                                yield text
+                        except Exception:
+                            if data:
+                                yield data
+
+    def _worker(self) -> None:
+        while self._running:
+            events: List[Dict[str, Any]] = []
+            while not self._queue.empty() and len(events) < 50:
+                try:
+                    events.append(self._queue.get_nowait())
+                except queue.Empty:
+                    break
+            if events:
+                self._flush(events)
+            time.sleep(self.flush_interval)
+
+    def _flush(self, events: List[Dict[str, Any]]) -> None:
+        try:
+            self._client.post(
+                self.events_endpoint,
+                json={"batch": events},
+                headers=self._auth_headers(),
+            )
+        except Exception:
+            pass  # Never crash the host
+
+    def flush(self) -> None:
+        """Manually flush all queued events immediately."""
+        events: List[Dict[str, Any]] = []
+        while not self._queue.empty():
+            try:
+                events.append(self._queue.get_nowait())
+            except queue.Empty:
+                break
+        if events:
+            self._flush(events)
+
+    def close(self) -> None:
+        self._running = False
+        self.flush()
+        try:
+            self._worker_thread.join(timeout=2.0)
+            self._client.close()
+        except Exception:
+            pass
+
+    def __enter__(self) -> "CommBClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+
+# ----------------------------------------------------------
+# AsyncCommBClient — async-first (FastAPI, asyncio)
+# ----------------------------------------------------------
+
+class AsyncCommBClient:
+    """
+    Async-first Sannex client for FastAPI and asyncio environments.
+
+    Usage::
+
+        async with AsyncCommBClient(api_key="snx_bot_xxxx", host="http://localhost:3000") as client:
+            config = await client.get_config()
+            async for chunk in client.stream_chat("Hello!", "user_123"):
+                print(chunk, end="", flush=True)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        host: str = "https://commb.app",
+        flush_interval: float = 2.0,
+        max_queue_size: int = 1000,
+        agent_id: Optional[str] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key must not be empty.")
+        self.api_key = api_key
+        self.agent_id = agent_id
+        self.host = host.rstrip("/")
+        api_prefix = "/api/v1" if not self.host.endswith("/api") and not self.host.endswith("/v1") else ""
+        self.events_endpoint = f"{self.host}{api_prefix}/events"
+        self.config_endpoint = f"{self.host}{api_prefix}/sync"
+        self.chat_endpoint = f"{self.host}{api_prefix}/chat"
+        self.releases_endpoint = f"{self.host}{api_prefix}/releases"
+        self.feedback_endpoint = f"{self.host}{api_prefix}/feedback"
+        self.flush_interval = flush_interval
+        self._queue: asyncio.Queue = asyncio.Queue(maxsize=max_queue_size)
+        self._client: Optional[httpx.AsyncClient] = None
+        self._flush_task: Optional[asyncio.Task] = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=10.0)
+        return self._client
+
+    def _auth_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def track(
+        self,
+        channel: str,
+        customer_id: str,
+        event: str,
+        status: str = "success",
+        amount: float = 0.0,
+        metadata: Optional[Dict[str, Any]] = None,
+        agent_id: Optional[str] = None,
+    ) -> None:
+        """Enqueue a telemetry event. Non-blocking — never raises."""
+        eff_agent_id = agent_id or self.agent_id
+        payload = {
+            "channel": channel,
+            "customer_id": str(customer_id),
+            "event": event,
+            "status": status,
+            "amount": float(amount),
+            "metadata": metadata or {},
+            "timestamp": time.time(),
+        }
+        if eff_agent_id:
+            payload["agent_id"] = str(eff_agent_id)
+        try:
+            self._queue.put_nowait(payload)
+        except asyncio.QueueFull:
+            pass
+
+    async def get_config(self, agent_id: Optional[str] = None) -> CommBConfigResponse:
+        """Pull bot/agent config, knowledge docs, catalog, and agent roster from CommB collector."""
+        eff_agent_id = agent_id or self.agent_id
+        params = {"agent_id": eff_agent_id} if eff_agent_id else None
+        try:
+            client = self._get_client()
+            res = await client.get(self.config_endpoint, headers=self._auth_headers(), params=params)
+            if res.is_success:
+                return CommBConfigResponse.model_validate(res.json())
+        except Exception:
+            pass
+        return CommBConfigResponse(status="error")
+
+    async def get_bot(self, agent_id: Optional[str] = None) -> Optional[BotInfo]:
+        """Retrieve basic bot identity (id, name, slug, reseller)."""
+        cfg = await self.get_config(agent_id=agent_id)
+        return cfg.tenant
+
+    async def get_agents(self) -> List[AgentSummary]:
+        """Retrieve list of all agents under this business/instance."""
+        cfg = await self.get_config()
+        return cfg.agents
+
+    async def get_releases(
+        self,
+        app_name: str = "commb",
+        app_version: Optional[str] = None,
+    ) -> List[ReleaseNote]:
+        """Fetch CommB platform release notes and updates from CommB collector."""
+        headers = self._auth_headers()
+        headers["X-App-Name"] = str(app_name)
+        if app_version:
+            headers["X-App-Version"] = str(app_version)
+        try:
+            params: Dict[str, Any] = {"app": str(app_name)}
+            if app_version:
+                params["app_version"] = str(app_version)
+            client = self._get_client()
+            res = await client.get(
+                self.releases_endpoint,
+                headers=headers,
+                params=params,
+                timeout=10.0,
+            )
+            if res.is_success:
+                data = res.json()
+                items = data.get("releases", data) if isinstance(data, dict) else data
+                if isinstance(items, list):
+                    return [ReleaseNote.model_validate(r) for r in items]
+        except Exception:
+            pass
+        return []
+
+    async def send_feedback(
+        self,
+        message: str,
+        category: str = "general",
+        contact_email: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """Send feedback, bug reports, or feature suggestions to CommB collector."""
+        body = {
+            "app": "commb",
+            "category": category,
+            "message": str(message),
+            "contact_email": contact_email,
+            "metadata": metadata or {},
+        }
+        if self.agent_id:
+            body["metadata"]["agent_id"] = self.agent_id
+        try:
+            client = self._get_client()
+            res = await client.post(
+                self.feedback_endpoint,
+                headers=self._auth_headers(),
+                json=body,
+                timeout=5.0,
+            )
+            return res.is_success
+        except Exception:
+            return False
+
+    async def sync_conversation(
+        self,
+        channel: str,
+        customer_id: str,
+        messages: List[Dict[str, Any]],
+        agent_id: Optional[str] = None,
+    ) -> None:
+        """Push a batched conversation transcript up to CommB collector."""
+        eff_agent_id = agent_id or self.agent_id
+        payload = {
+            "type": "chat_transcript",
+            "channel": channel,
+            "customer_id": str(customer_id),
+            "messages": messages,
+            "timestamp": time.time(),
+        }
+        if eff_agent_id:
+            payload["agent_id"] = str(eff_agent_id)
+        try:
+            self._queue.put_nowait(payload)
+        except asyncio.QueueFull:
+            pass
+
+    async def ping(self) -> bool:
+        """Check if the CommB collector host is reachable."""
+        try:
+            client = self._get_client()
+            res = await client.get(
+                f"{self.host}/api/health",
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=5.0,
+            )
+            return res.is_success
+        except Exception:
+            return False
+
+    async def stream_chat(
+        self,
+        message: str,
+        user_id: str,
+        history: Optional[List[ChatMessage]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        agent_id: Optional[str] = None,
+    ) -> AsyncIterator[str]:
+        """
+        Async-stream a chat response from the CommB engine via SSE.
+
+        Usage::
+
+            async for chunk in client.stream_chat("Hello!", "user_123"):
+                print(chunk, end="", flush=True)
+        """
+        eff_agent_id = agent_id or self.agent_id
+        body: Dict[str, Any] = {
+            "message": message,
+            "user_id": user_id,
+            "history": [m.model_dump() for m in (history or [])],
+            "metadata": metadata or {},
+        }
+        if eff_agent_id:
+            body["agent_id"] = str(eff_agent_id)
+
+        client = self._get_client()
+        async with client.stream(
+            "POST",
+            self.chat_endpoint,
+            headers=self._auth_headers(),
+            json=body,
+        ) as res:
+            res.raise_for_status()
+            buffer = ""
+            async for chunk in res.aiter_text():
+                buffer += chunk
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    line = line.strip()
+                    if line.startswith("data: "):
+                        data = line[6:].strip()
+                        if data == "[DONE]":
+                            return
+                        try:
+                            import json
+                            parsed = json.loads(data)
+                            text = (
+                                parsed.get("choices", [{}])[0]
+                                .get("delta", {})
+                                .get("content")
+                                or parsed.get("text")
+                                or data
+                            )
+                            if text:
+                                yield text
+                        except Exception:
+                            if data:
+                                yield data
+
+    async def flush(self) -> None:
+        """Flush all queued telemetry events immediately."""
+        events: List[Dict[str, Any]] = []
+        while not self._queue.empty():
+            try:
+                events.append(self._queue.get_nowait())
+            except asyncio.QueueEmpty:
+                break
+        if events:
+            try:
+                client = self._get_client()
+                await client.post(
+                    self.events_endpoint,
+                    json={"batch": events},
+                    headers=self._auth_headers(),
+                )
+            except Exception:
+                pass
+
+    async def close(self) -> None:
+        await self.flush()
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncCommBClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()

commb_agent/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

commb_agent-0.3.0.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: commb-agent
+Version: 0.3.0
+Summary: Official Python telemetry & remote-config client for CommB (Commercial Bots)
+Project-URL: Homepage, https://commb.app
+Project-URL: Repository, https://github.com/sannex-01/commb-agent
+Project-URL: Issues, https://github.com/sannex-01/commb-agent/issues
+Author-email: Sannex Tech LTD <info@sannex.ng>
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# commb-agent
+
+Official Python SDK for the **CommB platform** — connects standalone CommB bot engines to the CommB collector dashboard via telemetry tracking and remote config sync.
+
+[![PyPI version](https://img.shields.io/pypi/v/commb-agent)](https://pypi.org/project/commb-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Installation
+
+```bash
+pip install commb-agent
+# or
+uv add commb-agent
+```
+
+## How it works
+
+```
+CommB collector Dashboard (Supabase)
+       ▲▼  commb-agent SDK
+CommB Engine (standalone FastAPI bot)
+```
+
+- **CommB** calls `get_config()` to pull system prompt, knowledge docs, and catalog from CommB collector.
+- **CommB** calls `track()` after every message/order to push telemetry back.
+- **CommB** calls `sync_conversation()` to log 48h active session chat history to CommB collector CRM.
+- FastAPI streaming endpoints use `stream_chat()` for SSE responses to the Telegram Mini App.
+
+## Quick Start (Sync — for scripts & workers)
+
+```python
+from commb_agent import CommBClient
+
+client = CommBClient(
+    api_key="snx_bot_xxxx",
+    host="https://commb.app",
+)
+```
+
+## Quick Start (Async — for FastAPI)
+
+```python
+from commb_agent import AsyncCommBClient
+
+client = AsyncCommBClient(
+    api_key="snx_bot_xxxx",
+    host="https://commb.app",
+)
+```
+
+## API Reference
+
+### `get_config()` / `await client.get_config()` — Pull config from CommB collector
+
+```python
+# Sync
+config_resp = client.get_config()
+
+# Async
+config_resp = await client.get_config()
+
+print(config_resp.config.system_prompt)
+print(config_resp.config.model_name)        # "gemini-2.5-flash"
+print(len(config_resp.knowledge_docs))      # RAG docs
+print(len(config_resp.catalog_items))       # Product catalog
+```
+
+### `track()` / `await client.track()` — Push telemetry
+
+Non-blocking. Batches and flushes in the background. Never raises.
+
+```python
+# Sync (thread-safe, fire-and-forget)
+client.track(
+    channel="telegram",
+    customer_id="tg_123456",
+    event="order_created",
+    amount=45000.0,
+    metadata={"order_id": "ORD-001"},
+)
+
+# Async
+await client.track(
+    channel="whatsapp",
+    customer_id="+2348012345678",
+    event="message_received",
+)
+```
+
+### `sync_conversation()` / `await client.sync_conversation()` — 48h Chat Transcript Sync
+
+```python
+# Sync
+client.sync_conversation(
+    channel="whatsapp",
+    customer_id="+2348012345678",
+    messages=[
+        {"role": "user", "content": "How much is the blue dress?"},
+        {"role": "assistant", "content": "The blue dress is ₦15,000."}
+    ]
+)
+
+# Async
+await client.sync_conversation(
+    channel="telegram",
+    customer_id="tg_123456",
+    messages=[
+        {"role": "user", "content": "Is shipping free?"},
+        {"role": "assistant", "content": "Yes, on orders above ₦50,000."}
+    ]
+)
+```
+
+
+### `stream_chat()` — Stream AI responses (SSE)
+
+```python
+# Sync
+for chunk in client.stream_chat("What dresses do you have?", user_id="user_123"):
+    print(chunk, end="", flush=True)
+
+# Async (FastAPI SSE endpoint)
+async for chunk in client.stream_chat("What dresses do you have?", user_id="user_123"):
+    yield f"data: {chunk}\n\n"
+```
+
+### `ping()` / `await client.ping()` — Health check
+
+```python
+is_up = client.ping()          # sync
+is_up = await client.ping()    # async
+```
+
+### `get_bot()` / `await client.get_bot()` — Bot identity
+
+```python
+bot = client.get_bot()
+print(bot.name)      # "Elena Luxe Bot"
+print(bot.reseller)  # "Sannex Digital Agency"
+```
+
+## FastAPI CommB Engine Integration
+
+```python
+# commb_engine/main.py
+import os
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+from commb_agent import AsyncCommBClient, ChatMessage
+
+commb = AsyncCommBClient(
+    api_key=os.environ["BOT_API_KEY"],
+    host=os.environ.get("COMMB_COLLECTOR_URL", "https://commb.app"),
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Pull config from CommB collector on startup
+    config = await commb.get_config()
+    app.state.system_prompt = config.config.system_prompt
+    app.state.knowledge_docs = config.knowledge_docs
+    app.state.catalog_items = config.catalog_items
+    yield
+    await commb.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/v1/chat")
+async def chat(message: str, user_id: str):
+    async def event_stream():
+        async for chunk in commb.stream_chat(message, user_id):
+            yield f"data: {chunk}\n\n"
+        yield "data: [DONE]\n\n"
+
+    # Track the conversation event
+    await commb.track(
+        channel="telegram",
+        customer_id=user_id,
+        event="message_received",
+    )
+
+    return StreamingResponse(event_stream(), media_type="text/event-stream")
+```
+
+## Context Manager (Sync)
+
+```python
+with CommBClient(api_key="snx_bot_xxxx") as client:
+    config = client.get_config()
+    # ... use client
+# auto-flushes and closes on exit
+```
+
+## Context Manager (Async)
+
+```python
+async with AsyncCommBClient(api_key="snx_bot_xxxx") as client:
+    config = await client.get_config()
+    # ... use client
+```
+
+## Environment Variables
+
+```env
+BOT_API_KEY=snx_bot_xxxx              # From CommB collector Bot Settings
+COMMB_COLLECTOR_URL=https://commb.app  # CommB collector host
+```
+
+## Response Models (Pydantic v2)
+
+All responses are typed Pydantic models:
+
+```python
+from commb_agent import CommBConfigResponse, BotConfig, KnowledgeDoc, CatalogItem, BotInfo
+```
+
+## License
+
+MIT — Sannex Tech LTD

commb_agent-0.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+commb_agent/__init__.py,sha256=JHYnsPXzcFXnkf9N7pnOdi5WFYM9r9kLpOnf2kjUclU,389
+commb_agent/client.py,sha256=B2oLTGjA4EmcM2m8YJg2-Owmy4mw4uNTdaTl_yCuK6w,23649
+commb_agent/py.typed,sha256=TBDV9m9vjfnp9vsgTeJmpoNseoJEfHwvZaBLvLMfzz8,27
+commb_agent-0.3.0.dist-info/METADATA,sha256=jnALV4A2vOkyrKAxYRARQAsBuCXuxtbRGy2S3XjQMxE,6139
+commb_agent-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+commb_agent-0.3.0.dist-info/RECORD,,

commb_agent-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any