💡 What is Buni?

Buni is a local-first CLI, gateway daemon, and MCP server that allows developers to build AI agents for industries where hallucinations and unverified outputs are unacceptable (healthcare, legal, finance, and enterprise compliance).

It acts as an intelligent hybrid router: routine, low-risk requests execute locally on your machine via Ollama ($0 COGS, zero network latency), while high-complexity or high-risk queries automatically escalate to the hosted buni_cognitive Cloud Engine for verifiable RAG grounding, deterministic safety scoring, and model arbitrage.

                      ┌───────────────────────────────────────┐
                      │    LOCAL DEVELOPER ENVIRONMENT        │
                      │  Your App / Cursor / Claude Desktop   │
                      └───────────────────┬───────────────────┘
                                          │
                                          ▼
                      ┌───────────────────────────────────────┐
                      │    buni-cli Daemon (localhost:8000)   │
                      │    - Local ETAT+ Safety Evaluator     │
                      │    - Confidence Score Check (≥0.85)   │
                      └─────────┬───────────────────┬─────────┘
                                │                   │
             ┌──────────────────┘                   └────────────────┐
             │ Routine / Low-Risk                                    │ High-Risk / Low Confidence
             ▼                                                       ▼
┌─────────────────────────┐                            ┌──────────────────────────┐
│  Tier 1: Local Ollama   │                            │ Tier 2: Buni Cloud       │
│  (llama3.2, qwen2.5)    │                            │ (buni_cognitive Engine)  │
│  - $0 COGS / 0ms Net    │                            │ - Global pgvector RAG    │
│  - 100% Private         │                            │ - Cryptographic SHA-256  │
└─────────────────────────┘                            │ - Gemini Flash / GPT-4.1 │
                                                       └──────────────────────────┘

🔥 Key Features

• 🏎️ Local-First Hybrid Cascading: Run routine prompts locally via Ollama or LM Studio. Only pay for cloud compute when queries breach your risk or uncertainty thresholds.
• 🛡️ Deterministic Safety Fallbacks: Python-enforced rule evaluation prevents critical edge cases from relying purely on LLM guesswork.
• 🔐 Cryptographic Truth (dataset_hash): Cloud completions attach an immutable SHA-256 fingerprint proving the exact vector snapshot used during RAG generation.
• 🔌 Native MCP Server: Plugs directly into Claude Desktop, Cursor, or autonomous agents to expose standardized risk-scoring and grounded RAG tools.
• ⚡ Dynamic COGS Arbitrage: Cloud requests automatically route low-risk queries to low-cost models (Gemini Flash at ~$0.0015/req) and escalate high-risk cases to GPT-4.1.
• 💳 Dual-Rail Billing Ready: Built-in credit check proxy supporting prepaid local rails (M-Pesa, Paystack) and post-paid global rails (Metronome, Stripe, x402).

🚀 Quickstart in 60 Seconds

1. Install via PyPI

pip install buni-cli

2. Initialize and Probe Local Models

Run buni init in your project directory. Buni will automatically scan your machine for running local LLM providers (e.g., Ollama at http://localhost:11434):

$ buni init

[Buni] Probing local environment...
[Buni] ✓ Apple Silicon M-Series GPU detected.
[Buni] ✓ Local Ollama instance found at http://localhost:11434.

Available local models:
  1) llama3.2:3b         (Installed - Recommended for local triage)
  2) qwen2.5-coder:7b    (Installed)
  3) Custom Endpoint...
  4) None (Cloud-Only Route)

Select primary local model [1-4]: 1

[Buni] Created buni.yaml successfully!

3. Start the Local Gateway Daemon

buni serve --port 8000

Your local daemon is now listening on http://localhost:8000/v1/chat/completions with full OpenAI API parity.

💻 Code Example

You can point any standard OpenAI SDK directly to your local Buni daemon:

from openai import OpenAI

# Point your client to the local Buni daemon
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="buni_cloud_key_optional_for_local"
)

response = client.chat.completions.create(
    model="buni-auto",  # Buni automatically routes local vs cloud
    messages=[
        {"role": "user", "content": "Patient reports mild headache for 2 hours."}
    ]
)

# Standard completion content
print(response.choices[0].message.content)

# Access Buni cryptographic metadata
x_buni = response.model_extra.get("x_buni", {})
print(f"Routed Tier: {x_buni.get('routed_tier')}")     # 'local' or 'cloud'
print(f"Dataset Hash: {x_buni.get('dataset_hash')}")    # SHA-256 RAG proof

🔌 MCP Server Support (Claude & Cursor)

Buni includes a native Model Context Protocol (MCP) server so your AI coding assistants and autonomous agents can invoke grounded reasoning tools.

Cursor / Claude Desktop Configuration

Add Buni to your claude_desktop_config.json or Cursor MCP settings:

{
  "mcpServers": {
    "buni": {
      "command": "buni",
      "args": ["mcp", "serve"],
      "env": {
        "BUNI_API_KEY": "buni_cloud_sk_..."
      }
    }
  }
}

Available MCP Tools

• evaluate_risk: Analyzes input text against deterministic rules engines and outputs a severity score (1–5).
• execute_grounded_query: Performs full vector RAG search and generates an answer backed by a cryptographic dataset_hash.

⚙️ Configuration (buni.yaml)

Control your edge-to-cloud escalation limits directly in buni.yaml:

version: "1.0"

# Local Edge Provider
local:
  provider: ollama
  endpoint: "http://localhost:11434"
  model: "llama3.2:3b"
  confidence_threshold: 0.85  # Escalate to cloud if local logprobs < 0.85

# Cloud Escalation Settings
cloud:
  api_key: "${BUNI_API_KEY}"
  endpoint: "https://api.buni.health/v1/cognitive/execute"
  auto_escalate_severity: 3   # Always send Severity >= 3 to cloud
  verify_rag_hash: true

📊 Local vs Cloud Decision Matrix

🌐 Community & Commercial Ecosystem

• Open-Core Engine: The buni-cli gateway, local Ollama router, and MCP server are 100% free and open source under the Apache 2.0 License.
• Buni Cloud (Managed Platform): Sign up at buni.health for managed vector index hosting, international Metronome/Stripe billing, M-Pesa local pre-paid developer wallets, and 99.99% cloud uptime SLAs.

📄 License

Distributed under the Apache License 2.0. See LICENSE for more information.