bee-sdk 0.1.1__py3-none-any.whl

bee_sdk/__init__.py

@@ -0,0 +1,42 @@
+"""Bee Python SDK — official client for the Bee Intelligence Engine API.
+
+    pip install bee-sdk
+
+    from bee_sdk import Bee
+
+    bee = Bee()  # reads BEE_API_URL + BEE_API_KEY from env
+    print(bee.chat("Explain quantum error correction", domain="quantum"))
+
+    # Streaming
+    for chunk in bee.chat_stream("Write a fibonacci function", domain="programming"):
+        print(chunk, end="", flush=True)
+
+    # Async
+    import asyncio
+    async def main():
+        client = Bee.async_client()
+        result = await client.chat("Audit this code for SQL injection", domain="cybersecurity")
+        print(result)
+    asyncio.run(main())
+
+The SDK calls the Bee FastAPI surface (see bee/server.py for the full
+endpoint catalogue). For MCP-tool integration (Claude Desktop, Cursor,
+etc.) see bee/mcp_server.py — the SDK and the MCP server are independent
+surfaces over the same model.
+"""
+from .client import Bee, AsyncBee, BeeError, RateLimitError, BeeAPIError
+from .types import ChatMessage, ChatResponse, Domain, ModelTier
+
+__version__ = "0.1.1"
+__all__ = [
+    "Bee",
+    "AsyncBee",
+    "BeeError",
+    "RateLimitError",
+    "BeeAPIError",
+    "ChatMessage",
+    "ChatResponse",
+    "Domain",
+    "ModelTier",
+    "__version__",
+]

bee_sdk/client.py

@@ -0,0 +1,329 @@
+"""Bee SDK client.
+
+Two flavours:
+  - `Bee`        synchronous, uses urllib stdlib only (zero deps)
+  - `AsyncBee`   async, uses httpx (optional dep — `pip install bee-sdk[async]`)
+
+Both expose the same surface:
+
+    .chat(message, domain=..., max_tokens=...)         → str
+    .chat_messages(messages, ...)                      → ChatResponse
+    .chat_stream(message, ...)                         → Iterator[str]
+    .feedback(interaction_id, rating)                  → None
+    .domains()                                         → list[str]
+    .next_domain()                                     → dict   (admin)
+    .training_runs(limit=20)                           → list[dict]
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, AsyncIterator, Iterator, Optional
+
+from .types import ChatMessage, ChatResponse, Domain
+
+
+# Public OpenAI-compatible proxy. MUST be the bee.cuilabs.io/bee gateway,
+# never the raw Modal app URL — the gateway is where API-key auth, plan /
+# per-tier allowance enforcement and usage metering happen. Pointing at
+# Modal directly bypasses billing entirely and a bee_sk_ key 401s there
+# (the backend only knows Supabase JWTs / the static BEE_API_KEYS env).
+DEFAULT_BASE_URL = "https://bee.cuilabs.io/bee"
+DEFAULT_TIMEOUT = 60
+DEFAULT_RETRIES = 3
+RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class BeeError(Exception):
+    """Base error class for the SDK."""
+
+
+class BeeAPIError(BeeError):
+    def __init__(self, status: int, body: str) -> None:
+        super().__init__(f"HTTP {status}: {body[:300]}")
+        self.status = status
+        self.body = body
+
+
+class RateLimitError(BeeAPIError):
+    """Raised on persistent 429 after retries exhausted."""
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get("BEE_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = api_key or os.environ.get("BEE_API_KEY") or os.environ.get("BEE_PORTAL_API_KEY")
+        self.timeout = timeout
+        self.retries = retries
+
+    def _headers(self, extra: Optional[dict] = None) -> dict:
+        h = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "bee-sdk/0.1.1",
+        }
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        if extra:
+            h.update(extra)
+        return h
+
+
+class Bee(_BaseClient):
+    """Synchronous client. Zero non-stdlib dependencies."""
+
+    @classmethod
+    def async_client(cls, **kwargs) -> "AsyncBee":
+        """Convenience factory for the async client."""
+        return AsyncBee(**kwargs)
+
+    # ── HTTP plumbing ───────────────────────────────────────────────────
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> dict:
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        last_err: Optional[Exception] = None
+        for attempt in range(self.retries + 1):
+            req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    raw = resp.read().decode("utf-8")
+                    return json.loads(raw) if raw else {}
+            except urllib.error.HTTPError as e:
+                body_text = e.read().decode(errors="replace")
+                if e.code in RETRYABLE_STATUS and attempt < self.retries:
+                    last_err = e
+                    time.sleep(min(2 ** attempt, 8))
+                    continue
+                if e.code == 429:
+                    raise RateLimitError(e.code, body_text)
+                raise BeeAPIError(e.code, body_text)
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+                last_err = e
+                if attempt < self.retries:
+                    time.sleep(min(2 ** attempt, 8))
+                    continue
+                raise BeeError(f"network error after {self.retries + 1} attempts: {e}") from e
+        raise BeeError(f"unreachable: {last_err}")
+
+    # ── Public API ──────────────────────────────────────────────────────
+    def chat(
+        self,
+        message: str,
+        domain: Domain = "general",
+        max_tokens: int = 512,
+        temperature: float = 0.3,
+        system: Optional[str] = None,
+    ) -> str:
+        """Single-turn chat. Returns the assistant text only.
+
+        For multi-turn or detailed response metadata, use `chat_messages`.
+        """
+        msgs: list[ChatMessage] = []
+        if system:
+            msgs.append(ChatMessage(role="system", content=system))
+        msgs.append(ChatMessage(role="user", content=message))
+        return self.chat_messages(msgs, domain=domain, max_tokens=max_tokens, temperature=temperature).content
+
+    def chat_messages(
+        self,
+        messages: list[ChatMessage],
+        domain: Domain = "general",
+        max_tokens: int = 512,
+        temperature: float = 0.3,
+    ) -> ChatResponse:
+        # Switch domain first (the Bee API has explicit /domain/switch).
+        try:
+            self._request("POST", "/domain/switch", {"domain": domain})
+        except BeeAPIError:
+            # Domain switch is best-effort — if the server hasn't loaded
+            # that domain's adapter, fall through and serve from current.
+            pass
+        body = {
+            "model": "bee-cell",
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        }
+        out = self._request("POST", "/chat/completions", body)
+        choice = (out.get("choices") or [{}])[0]
+        msg = choice.get("message", {})
+        return ChatResponse(
+            id=out.get("id", ""),
+            model=out.get("model", ""),
+            content=msg.get("content", ""),
+            role=msg.get("role", "assistant"),
+            finish_reason=choice.get("finish_reason"),
+            usage=out.get("usage", {}),
+            interaction_id=out.get("interaction_id"),
+            raw=out,
+        )
+
+    def chat_stream(
+        self,
+        message: str,
+        domain: Domain = "general",
+        max_tokens: int = 512,
+        temperature: float = 0.3,
+        system: Optional[str] = None,
+    ) -> Iterator[str]:
+        """Stream tokens as they're generated.
+
+        Falls back to a single-shot response if the server doesn't yet
+        emit SSE chunks (current /chat/completions doesn't stream;
+        this method preserves the API for when streaming lands).
+        """
+        try:
+            self._request("POST", "/domain/switch", {"domain": domain})
+        except BeeAPIError:
+            pass
+        msgs = []
+        if system:
+            msgs.append({"role": "system", "content": system})
+        msgs.append({"role": "user", "content": message})
+        body = {
+            "model": "bee-cell",
+            "messages": msgs,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "stream": True,
+        }
+        # Try SSE first; if the server returns plain JSON, yield it whole.
+        url = f"{self.base_url}/chat/completions"
+        req = urllib.request.Request(
+            url, data=json.dumps(body).encode(), headers=self._headers(), method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                ct = resp.headers.get("content-type", "")
+                if "text/event-stream" in ct:
+                    for line in resp:
+                        s = line.decode().strip()
+                        if not s or not s.startswith("data:"):
+                            continue
+                        payload = s[5:].strip()
+                        if payload == "[DONE]":
+                            return
+                        try:
+                            d = json.loads(payload)
+                            delta = (d.get("choices") or [{}])[0].get("delta", {})
+                            if "content" in delta:
+                                yield delta["content"]
+                        except json.JSONDecodeError:
+                            continue
+                else:
+                    # Server didn't honour stream=True — yield full response.
+                    out = json.loads(resp.read().decode())
+                    content = (out.get("choices") or [{}])[0].get("message", {}).get("content", "")
+                    if content:
+                        yield content
+        except urllib.error.HTTPError as e:
+            raise BeeAPIError(e.code, e.read().decode(errors="replace"))
+
+    def feedback(self, interaction_id: str, rating: str, comment: Optional[str] = None) -> None:
+        """Submit thumbs-up/down feedback. rating: 'up' | 'down'."""
+        self._request("POST", "/feedback", {
+            "interaction_id": interaction_id,
+            "rating": rating,
+            "comment": comment,
+        })
+
+    def domains(self) -> list[str]:
+        """List the domains Bee knows about."""
+        return self._request("GET", "/models").get("domains", [])
+
+    def health(self) -> dict:
+        return self._request("GET", "/health")
+
+    def adapters(self) -> dict:
+        """Currently-loaded LoRA adapters per domain (added 2026-04-28)."""
+        return self._request("GET", "/adapters")
+
+
+class AsyncBee(_BaseClient):
+    """Async client — requires httpx. `pip install bee-sdk[async]`."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        try:
+            import httpx  # noqa: F401
+        except ImportError as e:
+            raise ImportError(
+                "AsyncBee requires httpx. Install with `pip install bee-sdk[async]`."
+            ) from e
+
+    async def chat(
+        self,
+        message: str,
+        domain: Domain = "general",
+        max_tokens: int = 512,
+        temperature: float = 0.3,
+        system: Optional[str] = None,
+    ) -> str:
+        import httpx
+        msgs: list[dict] = []
+        if system:
+            msgs.append({"role": "system", "content": system})
+        msgs.append({"role": "user", "content": message})
+        async with httpx.AsyncClient(timeout=self.timeout, headers=self._headers()) as cl:
+            try:
+                await cl.post(f"{self.base_url}/domain/switch", json={"domain": domain})
+            except httpx.HTTPError:
+                pass
+            r = await cl.post(f"{self.base_url}/chat/completions", json={
+                "model": "bee-cell",
+                "messages": msgs,
+                "max_tokens": max_tokens,
+                "temperature": temperature,
+            })
+            r.raise_for_status()
+            out = r.json()
+            return (out.get("choices") or [{}])[0].get("message", {}).get("content", "")
+
+    async def chat_stream(
+        self,
+        message: str,
+        domain: Domain = "general",
+        max_tokens: int = 512,
+        temperature: float = 0.3,
+        system: Optional[str] = None,
+    ) -> AsyncIterator[str]:
+        import httpx
+        msgs: list[dict] = []
+        if system:
+            msgs.append({"role": "system", "content": system})
+        msgs.append({"role": "user", "content": message})
+        async with httpx.AsyncClient(timeout=self.timeout, headers=self._headers()) as cl:
+            try:
+                await cl.post(f"{self.base_url}/domain/switch", json={"domain": domain})
+            except httpx.HTTPError:
+                pass
+            async with cl.stream("POST", f"{self.base_url}/chat/completions", json={
+                "model": "bee-cell",
+                "messages": msgs,
+                "max_tokens": max_tokens,
+                "temperature": temperature,
+                "stream": True,
+            }) as resp:
+                async for line in resp.aiter_lines():
+                    s = line.strip()
+                    if not s or not s.startswith("data:"):
+                        continue
+                    payload = s[5:].strip()
+                    if payload == "[DONE]":
+                        return
+                    try:
+                        d = json.loads(payload)
+                        delta = (d.get("choices") or [{}])[0].get("delta", {})
+                        if "content" in delta:
+                            yield delta["content"]
+                    except json.JSONDecodeError:
+                        continue

bee_sdk/types.py

@@ -0,0 +1,51 @@
+"""Public types for the Bee SDK.
+
+Mirrors the JSON shape of the Bee FastAPI surface (`bee/server.py`).
+Kept as plain dataclasses — no pydantic dependency on the SDK so it's
+lightweight to install.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+# Tier-1 domains, mirror of bee/domains.py.
+Domain = Literal[
+    "general",
+    "programming",
+    "ai",
+    "cybersecurity",
+    "quantum",
+    "fintech",
+    "blockchain",
+    "infrastructure",
+    "research",
+    "business",
+]
+
+# Trainable tier names, mirror of bee/tiers.py.
+ModelTier = Literal["cell", "brood", "comb", "buzz", "hive", "swarm", "enclave", "ignite"]
+
+
+@dataclass
+class ChatMessage:
+    role: Literal["system", "user", "assistant"]
+    content: str
+
+
+@dataclass
+class ChatResponse:
+    """Response shape from POST /chat/completions.
+
+    Mirrors the OpenAI ChatCompletion shape because that's what the
+    Bee API emits — preserves drop-in compatibility for callers that
+    already know the OpenAI SDK.
+    """
+    id: str
+    model: str
+    content: str
+    role: str = "assistant"
+    finish_reason: Optional[str] = None
+    usage: dict = field(default_factory=dict)
+    interaction_id: Optional[str] = None
+    raw: dict = field(default_factory=dict)

bee_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: bee-sdk
+Version: 0.1.1
+Summary: Official Python client for the Bee Intelligence Engine — domain-specialized LoRA-routed LLM by CUI Labs.
+Project-URL: Homepage, https://bee.cuilabs.io
+Project-URL: Documentation, https://bee.cuilabs.io/docs/sdks
+Project-URL: Repository, https://github.com/cuilabs/bee
+Project-URL: Issues, https://github.com/cuilabs/bee-community/issues
+Project-URL: Changelog, https://bee.cuilabs.io/changelog
+Project-URL: Hugging Face, https://huggingface.co/cuilabs
+Author-email: "CUI Labs (Pte.) Ltd." <engineering@cuilabs.io>
+License: Apache-2.0
+Keywords: ai,bee,blockchain,cybersecurity,domain-experts,huggingface,llm,lora,mcp,quantum
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bee-sdk
+
+Official Python client for the **Bee Intelligence Engine** — a domain-specialized LLM by [CUI Labs](https://bee.cuilabs.io) routing per-domain LoRA adapters over a verified open-weight base.
+
+SDK version: `0.1.1` (pre-release).
+
+> **Status:** functional sync + async client (stdlib + optional `httpx`).
+> The SDK targets the Bee `/chat/completions` API contract on
+> production via the public gateway `https://bee.cuilabs.io/bee` — this
+> is the default and it is where API-key auth, plan / per-tier allowance
+> enforcement and usage metering happen. Do **not** point `BEE_API_URL`
+> at the raw Modal app URL: that bypasses billing and a `bee_sk_` key
+> is rejected there (the backend only trusts Supabase JWTs / the
+> static `BEE_API_KEYS` env, not customer-issued keys). Override
+> `BEE_API_URL` only for a self-hosted Bee Enclave or staging.
+
+## Install
+
+The PyPI `cuilabs` organisation is currently pending approval; until it
+lands, install directly from GitHub:
+
+```bash
+# From GitHub (recommended while PyPI approval is pending)
+pip install "git+https://github.com/cuilabs/bee.git#subdirectory=sdks/python"
+
+# With the optional async client (adds httpx)
+pip install "git+https://github.com/cuilabs/bee.git#subdirectory=sdks/python" httpx
+```
+
+Once PyPI approval lands, the canonical install is:
+
+```bash
+pip install bee-sdk          # sync client (stdlib only — zero deps)
+pip install bee-sdk[async]   # async client (adds httpx)
+```
+
+Install + quickstart on the marketing site:
+[bee.cuilabs.io/docs/sdks](https://bee.cuilabs.io/docs/sdks).
+
+## Quick start
+
+```python
+from bee_sdk import Bee
+
+bee = Bee()  # reads BEE_API_URL + BEE_API_KEY from env
+print(bee.chat("Explain Shor's algorithm at NISQ depth", domain="quantum"))
+```
+
+### Streaming
+
+```python
+for chunk in bee.chat_stream("Write a Rust fibonacci function", domain="programming"):
+    print(chunk, end="", flush=True)
+```
+
+### Async
+
+```python
+import asyncio
+from bee_sdk import AsyncBee
+
+async def main():
+    client = AsyncBee()
+    text = await client.chat("Audit this contract for re-entrancy", domain="blockchain")
+    print(text)
+
+asyncio.run(main())
+```
+
+### Multi-turn
+
+```python
+from bee_sdk import Bee, ChatMessage
+
+bee = Bee()
+resp = bee.chat_messages(
+    [
+        ChatMessage(role="system", content="You are a senior security auditor."),
+        ChatMessage(role="user", content="Review this nginx config for hardening gaps:\n\n..."),
+    ],
+    domain="cybersecurity",
+    max_tokens=1024,
+)
+print(resp.content)
+print(resp.usage, resp.interaction_id)
+```
+
+### Feedback loop
+
+```python
+resp = bee.chat_messages([...], domain="ai")
+if user_likes_answer:
+    bee.feedback(resp.interaction_id, rating="up")
+```
+
+## Domains
+
+The `domain=` parameter selects which LoRA adapter Bee routes through. Tier-1 domains:
+
+| domain | what it's tuned for |
+|---|---|
+| `general` | balanced, no specialization |
+| `programming` | code generation, refactoring, debugging |
+| `ai` | ML/AI papers, training, evaluation |
+| `cybersecurity` | threat modelling, audits, defensive analysis |
+| `quantum` | NISQ-aware quantum computing, Qiskit |
+| `fintech` | payments, risk, compliance |
+| `blockchain` | smart contract audits, protocol design |
+| `infrastructure` | systems, networking, devops |
+| `research` | literature review, paper critique |
+| `business` | strategy, GTM, ops |
+
+Adapters live at [`cuilabs/bee-cell`](https://huggingface.co/cuilabs/bee-cell) on branches `<domain>-<UTC-timestamp>`.
+
+## Environment variables
+
+| var | purpose |
+|---|---|
+| `BEE_API_URL` | Endpoint override. Defaults to the public gateway `https://bee.cuilabs.io/bee` (where auth + billing + metering run). Set this **only** for a self-hosted Bee Enclave or a staging environment — never the raw Modal app URL (that bypasses billing and rejects `bee_sk_` keys). |
+| `BEE_API_KEY` | Bearer token (also accepts `BEE_PORTAL_API_KEY`) |
+
+## Errors
+
+```python
+from bee_sdk import BeeAPIError, RateLimitError, BeeError
+
+try:
+    bee.chat("...", domain="quantum")
+except RateLimitError as e:        # 429 after retries
+    ...
+except BeeAPIError as e:           # other HTTP errors
+    print(e.status, e.body)
+except BeeError:                   # network / timeout
+    ...
+```
+
+The sync client retries 429/5xx with exponential backoff (max 4 attempts).
+
+## Versioning
+
+`bee-sdk` follows the Bee API surface in `bee/server.py`. Breaking API changes bump the **minor** version pre-1.0; the SDK is currently **0.1.1** and the API is `v1`.
+
+## License
+
+Apache-2.0 © 2026 CUI Labs (Pte.) Ltd.

bee_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+bee_sdk/__init__.py,sha256=QMDcS1Gz1SwF8v3ZYu21dHCLOMUCLtEwcojv2bQNW5s,1238
+bee_sdk/client.py,sha256=x56s82E4DzDsh44IPDPM1-5BqEwbTOIIimVFUN_WjfI,12976
+bee_sdk/types.py,sha256=09qs8Uyx1f10kL9E7NyuCV9H340aT31637s9LebpWYY,1295
+bee_sdk-0.1.1.dist-info/METADATA,sha256=Z-il7GsmUtlYAkDmihoFPJuzBtXLqKE1-xQlCqdTbHk,6281
+bee_sdk-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+bee_sdk-0.1.1.dist-info/RECORD,,

bee_sdk-0.1.1.dist-info/WHEEL

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