Metadata-Version: 2.4
Name: buni-cli
Version: 0.1.5
Summary: The open-core hybrid edge-cloud framework for high-stakes AI agents.
License-File: LICENSE
Author: Buni Health
Author-email: engineering@buni.health
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Dist: fastapi (>=0.110.0,<0.111.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: mcp (>=1.0.0,<2.0.0)
Requires-Dist: pydantic (>=2.6.0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: typer (>=0.12.5)
Requires-Dist: uvicorn (>=0.29.0,<0.30.0)
Description-Content-Type: text/markdown

<div align="center">

# 🧠 Buni

**The open-core hybrid edge-cloud framework for high-stakes, cryptographically grounded AI agents.**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![PyPI version](https://img.shields.io/pypi/v/buni-cli.svg)](https://pypi.org/project/buni-cli/)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![Discord](https://img.shields.io/badge/Discord-Join_Community-7289da.svg)](https://discord.gg/buni)

[Quickstart](#-quickstart-in-60-seconds) • [Architecture](#-hybrid-edge-cloud-architecture) • [MCP Integration](#-mcp-server-support) • [Documentation](https://docs.buni.health) • [Buni Cloud](https://buni.health)

</div>

---

## 💡 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.

```text
                      ┌───────────────────────────────────────┐
                      │    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

```bash
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`):

```bash
$ 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

```bash
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:

```python
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:

```json
{
  "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`:

```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

| Metric / Gate | Local Execution (`Ollama`) | Cloud Execution (`buni_cognitive`) |
| :--- | :--- | :--- |
| **Severity Score** | Severity 1–2 (Routine, simple prompts) | Severity 3–5 (High risk, critical alerts) |
| **Model Confidence** | Local logprobs >= 0.85 | Local logprobs < 0.85 |
| **RAG Requirement** | Local cached knowledge base | Global verified dataset with SHA-256 proof |
| **Latency & Cost** | **< 50ms / $0.00 COGS** | Sub-700ms P95 / Billed via Cloud Credits |

---

## 🌐 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](https://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`](./LICENSE) for more information.

