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.
