| --- |
| title: Bee Intelligence Engine |
| emoji: 🐝 |
| colorFrom: yellow |
| colorTo: gray |
| sdk: docker |
| app_port: 7860 |
| pinned: true |
| license: apache-2.0 |
| short_description: The Intelligence Engine — domain LoRA adapters |
| --- |
| |
| # Bee — The Intelligence Engine |
|
|
| **Trust-critical AI for regulated and mission-critical systems.** |
| Built by [CUI Labs](https://www.cuilabs.io) on the XIIS platform. |
|
|
| Last verified: 2026-05-05. |
|
|
| --- |
|
|
| ## What's actually running today |
|
|
| | Surface | State | Source-of-truth | |
| |---|---|---| |
| | Bee Cell inference (production) | Live on **Modal** serverless (`bee-cell-prod`) — replaces the legacy HF Space `cuilabs-bee.hf.space`. Frontend talks to it via `BEE_API_URL` env on Vercel. | [infra/modal/bee_app.py](infra/modal/bee_app.py) | |
| | Web app | `bee.cuilabs.io` on Vercel | [apps/web](apps/web) | |
| | Mobile app | React Native CLI 0.85.2 (no Expo, no EAS) — Stage 0 release scaffolding. Backend pointer in Settings. | [apps/mobile/README.md](apps/mobile/README.md) | |
| | Desktop app | Tauri 2.10 shell pointing at `bee.cuilabs.io`. Source scaffold landed 2026-04-30; signed releases gated on cert/Apple-Dev enrollment. | [apps/desktop/README.md](apps/desktop/README.md) | |
| | Bee Security Eval Harness | 52 cases / 10 categories. Latest baseline on Bee Cell base: **12.5 / 100** (gates Stage 1 APK). | [eval/bee_security_harness/README.md](eval/bee_security_harness/README.md) | |
| | Stage 0 safety wrapper | Runtime preamble + refusal substrate around every chat completion. | [bee/safety_wrapper.py](bee/safety_wrapper.py) | |
| | Cybersec adapter training | Stage 0.5 Comb run on **Vertex AI L4** (one-time exception — Comb usually rides Kaggle). | [workers/vertex-train/README.md](workers/vertex-train/README.md) | |
| | Cell + Cell+ training | Kaggle T4×2 GPU pool, push-only dispatcher (commit `3edb643`). | [workers/kaggle-online-train/README.md](workers/kaggle-online-train/README.md) | |
| | Cron pipeline | 15 Vercel cron routes — kaggle-dispatch, kaggle-tpu-dispatch, eval-run, cve-ingest, kev-ingest, distillation, online-training, evolution-cycle, community-pull, github-trending, hf-dispatch, heartbeat, memory-extract, interactions-export, research-correct. | [apps/web/src/app/api/cron/](apps/web/src/app/api/cron/) | |
|
|
| --- |
|
|
| ## Benchmarks |
|
|
| Reproducible eval on the base model (no LoRA adapter applied). Run via `python -m bee.eval_harness` — every task and pass criterion is in [bee/eval_harness.py](bee/eval_harness.py), every output is captured in `data/eval_reports/*.json`. |
|
|
| ``` |
| Model: HuggingFaceTB/SmolLM2-360M-Instruct (361.8M params) |
| Device: MPS (Apple Silicon, fp16) |
| Date: 2026-04-29 |
| Wall: 25.9s for all 5 benchmarks |
| ───────────────────────────────────────────────────── |
| coding 100% (10/10) avg latency 2033 ms |
| reasoning 40% (4/10) avg latency 146 ms |
| instruct 50% (5/10) avg latency 167 ms |
| grounded 80% (4/5) avg latency 116 ms |
| domain 100% (5/5) avg latency 381 ms |
| ───────────────────────────────────────────────────── |
| OVERALL 74% |
| ``` |
|
|
| **How to read these numbers:** |
| - `coding 100%` is a **shape check** (function name + `return` keyword present), not a correctness test. A real correctness benchmark would score lower. |
| - `reasoning 40%` and `instruct 50%` are honest signal — at 360M base, multi-step math and exact-format compliance are hard. |
| - A few `instruct` / `grounded` failures are pattern-match strictness in the harness (e.g. answer is right but contains an extra word). The raw output for every task is in [data/eval_reports/2026-04-29_smollm2-360m_mps.json](data/eval_reports/2026-04-29_smollm2-360m_mps.json) so you can audit. |
|
|
| Reproduce locally: |
|
|
| ```bash |
| python -m bee.eval_harness --model HuggingFaceTB/SmolLM2-360M-Instruct --device mps \ |
| --output data/eval_reports/my_run.json |
| ``` |
|
|
| Per-domain LoRA adapters at [`cuilabs/bee-cell`](https://huggingface.co/cuilabs/bee-cell) are evaluated separately on domain-specific tasks; numbers land in this README only after a training run produces them. |
|
|
| ### Bee Security Eval Harness — first real baseline |
|
|
| Bee's security capability is measured against an in-house gate, not a generic benchmark. Source-of-truth for the cases is [eval/bee_security_harness/cases/*.yaml](eval/bee_security_harness/cases/) (52 cases across 10 categories: insecure-code generation, prompt injection, agent tool abuse, tenant isolation, authz/authn failures, cloud IAM, dependency CVEs, secret leakage, unsafe cyber responses, hallucinated security claims). |
|
|
| ``` |
| Surface: Bee Cell base (no cybersec adapter applied) |
| Backend: Modal bee-cell-prod |
| Date: 2026-05-03 |
| Score: 12.5 / 100 (release gate is >= 80 with zero blocking failures) |
| ``` |
|
|
| 12.5 is the honest pre-adapter floor and is the reason Stage 0.5 cybersec adapter training is currently running on Vertex L4. The Stage 1 APK release is gated on a re-run of this harness against the post-adapter Modal endpoint. Run logic and case-loader: [apps/web/src/app/api/cron/eval-run/route.ts](apps/web/src/app/api/cron/eval-run/route.ts), summary table `eval_runs`, per-case results `eval_run_results`. |
|
|
| --- |
|
|
| ## Quick Start |
|
|
| ```bash |
| # 1. Create environment |
| python3 -m venv .venv |
| source .venv/bin/activate |
| pip install torch transformers accelerate peft datasets trl \ |
| sentencepiece protobuf numpy fastapi uvicorn pydantic httpx \ |
| python-dotenv qiskit sentence-transformers faiss-cpu websockets |
| |
| # 2. Copy environment config |
| cp .env.example .env |
| # Edit .env with your API keys (optional — Bee works without them) |
| |
| # 3. Run the eval harness (verifies install + reproduces the numbers above) |
| python -m bee.eval_harness --device mps |
| |
| # 4. Start the server |
| python -m bee.server |
| |
| # 5. Start the full daemon (server + evolution + distillation) |
| python -m bee |
| ``` |
|
|
| --- |
|
|
| ## API (OpenAI-compatible) |
|
|
| ```bash |
| # Chat |
| curl -X POST http://localhost:8000/v1/chat/completions \ |
| -H "Content-Type: application/json" \ |
| -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":100}' |
| |
| # Health |
| curl http://localhost:8000/health |
| |
| # Router stats |
| curl http://localhost:8000/v1/router/stats |
| |
| # Switch domain |
| curl -X POST http://localhost:8000/v1/domain/switch \ |
| -H "Content-Type: application/json" \ |
| -d '{"domain":"cybersecurity"}' |
| ``` |
|
|
| Tier-1 domains (10): `general`, `programming`, `ai`, `cybersecurity`, `quantum`, `fintech`, `blockchain`, `infrastructure`, `research`, `business`. Source: [bee/domains.py](bee/domains.py). |
|
|
| --- |
|
|
| ## Architecture |
|
|
| ``` |
| bee/ |
| server.py FastAPI server, OpenAI-compatible API, adaptive routing |
| safety_wrapper.py Stage 0 runtime safety preamble + refusal substrate |
| adaptive_router.py Difficulty estimation, self-verification, context memory |
| distillation.py Teacher-student distillation (Claude/GPT-4 -> Bee) |
| evolution.py Autonomous algorithm evolution |
| invention_engine.py Invents novel attention, compression, SSM modules |
| self_coding.py Code generation + sandboxed execution |
| self_heal.py Training health monitoring, auto-recovery |
| community.py Share inventions between Bee instances (HuggingFace Hub) |
| quantum_reasoning.py Quantum-enhanced decision making (IBM Quantum / local sim) |
| quantum_ibm.py IBM Quantum Platform integration (156-qubit Heron r2) |
| quantum_sim.py Local quantum statevector simulation |
| retrieval.py RAG pipeline (FAISS + sentence-transformers) |
| lora_adapter.py Domain LoRA adapter management |
| nn_compression.py VQ-VAE hierarchical neural compression |
| memory.py Hierarchical compressive memory |
| moe.py Sparse mixture of experts |
| state_space.py Selective state space model |
| daemon.py Autonomous daemon (background evolution, distillation) |
| ignition.py Full BeeAGI architecture activation (research-only, |
| BEE_IGNITE=0 in production) |
| benchmark.py 10-test benchmark suite |
| eval_harness.py General-capability harness (the SmolLM2 numbers above) |
| config.py Model configuration |
| modeling_bee.py Custom BeeForCausalLM |
| |
| apps/web/ Next.js customer web app deployed to Vercel |
| apps/mobile/ React Native CLI 0.85.2 native iOS+Android |
| apps/desktop/ Tauri 2.10 native shell (macOS/Windows/Linux) |
| sdks/python/ Official Python client (bee-sdk) |
| |
| eval/bee_security_harness/ |
| 52-case security gate (10 categories, regex grader DSL) |
| |
| infra/modal/ Production inference deployment (bee-cell-prod) |
| infra/hf-space/ Deprecated; retained for community model-card hosting |
| infra/db/ Postgres migrations (eval_runs, training_runs, etc.) |
| infra/supabase/ Supabase project config |
| |
| workers/ |
| kaggle-online-train/ T4×2 GPU runner — cell, cell+, comb (when forced) |
| kaggle-tpu-train/ TPU v6e-8 runner — every-step debug logging |
| vertex-train/ L4 / A100 — reserved for tiers Kaggle can't host |
| (Hive, Swarm, Enclave, Ignite) |
| colab-online-train/ Manual paste-test workflow on Colab T4 |
| lightning-train/ Inactive — manual launcher, not wired to a cron |
| |
| packages/ auth, billing, core, db, email, pqc, qnsp-client, |
| rag, telemetry, training, ui — TypeScript workspace |
| scripts/ Distillation, deploys, dataset prep, ops |
| docs/ Architecture, API reference, runbooks |
| ``` |
|
|
| ## Repository Layout |
|
|
| The approved source of truth for the monorepo layout lives in `docs/architecture/repository.md`. |
|
|
| Current migration truth: |
|
|
| - `apps/web` is the canonical frontend path. |
| - `apps/mobile` is the canonical mobile app path (React Native CLI, no Expo). |
| - `apps/desktop` is the canonical desktop app path (Tauri 2.10). |
| - `bee/` remains rooted at the repository top level and is the canonical backend package. |
| - `infra/modal/bee_app.py` is the production inference entrypoint. The root `Dockerfile` is retained for parity with the historical HF Space image and for ad-hoc Docker runs. |
|
|
| ## Deployment Topology |
|
|
| - GitHub hosts the monorepo source of truth. |
| - Vercel serves the web app from `apps/web` at `https://bee.cuilabs.io`. |
| - Namecheap manages DNS for `bee.cuilabs.io` and (eventually) `api.bee.cuilabs.io`. |
| - **Modal** serves the backend inference API as `bee-cell-prod`. The frontend points at it via the `BEE_API_URL` env on Vercel; default URL pattern is `https://cuilabs--bee-cell-prod-fastapi-app.modal.run` ([infra/modal/bee_app.py](infra/modal/bee_app.py)). |
| - The legacy Hugging Face Space (`cuilabs-bee.hf.space`) is deprecated. It is no longer the production backend; HF org artifacts are retained for community model-card and dataset hosting only ([infra/hf-space/README.md](infra/hf-space/README.md)). |
| - Large datasets, checkpoints, and adapters live on Hugging Face Hub (`cuilabs/bee-cell`, `cuilabs/bee-cell-plus`, `cuilabs/bee-comb`, `cuilabs/bee-interactions`), not in the frontend deployment payload. |
|
|
| ## How It Works |
|
|
| 1. **Adaptive Router** — Routes easy queries locally (free), hard queries to teacher API |
| 2. **Self-Verification** — Scores every output, re-generates if quality is low |
| 3. **Context Memory** — Compresses past conversations for infinite memory |
| 4. **Teacher Distillation** — Uses Claude/GPT-4 to generate expert training data |
| 5. **LoRA Training** — Domain-specific adapters trained on free Colab/Kaggle GPUs |
| 6. **Evolution** — Autonomously invents better algorithms |
| 7. **Community** — Shares validated inventions between all Bee instances |
| 8. **Quantum** — IBM Quantum hardware or local simulation for decision optimization |
|
|
| **Design goal**, not a measured steady-state: route easy queries locally (free), expensive ones to a teacher model, capture every teacher response as training data, and shrink the teacher-call ratio over time as Bee's domain adapters improve. Actual local-vs-teacher split and cost-per-query are emitted live by `/v1/router/stats` — that endpoint is the source of truth, not this README. |
|
|
| ## Hardware |
|
|
| | Tier | Base model | Params | RAM (fp16) | Throughput | |
| |---|---|---|---|---| |
| | `cell` (default) | SmolLM2-360M-Instruct | 361.8M | ~0.7 GB | **89 tok/s** on Apple Silicon MPS (fp16, greedy) | |
| | `cell-plus`, `comb`, `comb-team`, `hive` | see [bee/tiers.py](bee/tiers.py) | 1.7B–32B | scales with tier | not yet benchmarked locally | |
|
|
| The `89 tok/s` number is from [data/eval_reports/2026-04-29_throughput_mps.json](data/eval_reports/2026-04-29_throughput_mps.json) — 5 prompts × ~100 tokens each, measured today. Larger tiers' throughput numbers will land in this table once a real measurement is taken on the target hardware; we don't quote estimates. |
|
|
| Runs on: macOS (MPS), Linux (CUDA), any CPU (slow). Production traffic is served by Modal's L4-class containers ([infra/modal/bee_app.py](infra/modal/bee_app.py)) with a persistent `bee-cache` volume so cold starts don't re-pull SmolLM2-360M. |
|
|
| ## Environment Variables |
|
|
| See `.env.example` for all options. Key ones: |
|
|
| ```bash |
| BEE_DEVICE=mps # auto, mps, cuda, cpu |
| BEE_MODEL_PATH=HuggingFaceTB/SmolLM2-360M-Instruct |
| BEE_TEACHER_API_KEY= # Anthropic or OpenAI key (optional) |
| IBM_QUANTUM_API_KEY= # IBM Quantum (optional) |
| BEE_API_URL= # Set on Vercel + mobile + SDK to point |
| # at the Modal production backend. |
| # Default in code is the legacy HF Space |
| # for backward-compat only. |
| BEE_IGNITE=0 # Keep 0 for production. The Ignite |
| # research-AGI substrate is gated by |
| # this flag; see bee/ignition.py. |
| ``` |
|
|
| ## License |
|
|
| MIT |
|
|
