Metadata-Version: 2.4
Name: beethovain
Version: 0.3.1
Summary: AI Model Blending Toolkit — orchestrate multiple models for superior performance
Author: Beethovain
License-Expression: MIT
Project-URL: Homepage, https://beethovain.com
Project-URL: Documentation, https://beethovain.com
Keywords: ai,blending,ensemble,llm,slm,model-orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pyyaml<7.0,>=6.0
Provides-Extra: hf
Requires-Dist: transformers<5.0,>=4.40; extra == "hf"
Requires-Dist: torch<3.0,>=2.0; extra == "hf"
Provides-Extra: api
Requires-Dist: fastapi<1.0,>=0.115; extra == "api"
Requires-Dist: uvicorn<1.0,>=0.30; extra == "api"
Requires-Dist: pydantic<3.0,>=2.0; extra == "api"
Provides-Extra: tui
Requires-Dist: textual<2.0,>=1.0; extra == "tui"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: beethovain[api,hf,mcp,tui]; extra == "all"
Dynamic: license-file

# Beethovain

**AI Model Blending Toolkit** — Orchestrate multiple models for superior performance.

Blend small language models (SLMs) together to achieve results that rival larger models, at a fraction of the cost.

## Quick Start

```bash
pip install beethovain
```

```python
from beethovain import BlendSession

session = BlendSession.from_yaml("experiment.yaml")
result = await session.blend("Classify this article", "judge")
print(result.parsed)  # {"is_benefit": true, "confidence": 0.82}
```

## What is Blending?

Instead of using one large model, combine multiple smaller models:

- **Routing** — Fast model first, escalate to strong model if confidence is low
- **Ensemble** — Multiple models vote, weighted majority wins
- **Cascade** — Primary generates, secondary verifies/corrects

**Real result**: 3 SLMs (1.2B + 4B + 7.8B) blended → **F1 80.1%** on a classification task.

## Features

| Feature | Command |
|---------|---------|
| **SDK** | `from beethovain import BlendSession` |
| **CLI** | `beethovain blend config.yaml judge --prompt "..."` |
| **Record** | `beethovain record --function sfm --models colmap --project "..."` — log any experiment (vision/3D/training too) |
| **MCP** | `beethovain mcp` — AI agents record/query/push as MCP tools |
| **REST API** | `beethovain serve config.yaml` |
| **Dashboard** | Browser → `http://localhost:8000` |
| **TUI** | `beethovain watch` |
| **Push** | `beethovain push --project "MyProject" [--private]` → beethovain.com |

## For AI Agents (MCP)

```bash
pip install beethovain[mcp]
claude mcp add beethovain -- beethovain mcp
```

Exposes `record_experiment` / `list_experiments` / `get_experiment` / `get_stats` / `push_to_hub`.
Working in another project and told to "use beethovain"? → read **[AGENT_GUIDE.md](AGENT_GUIDE.md)**.

## Projects & Runs (like GitHub repos & commits)

Every run belongs to a **project**. Set it via `--project`, the YAML `project:` key,
or `BlendSession.from_yaml(..., project=...)`. beethovain.com lists projects, not raw runs.

## YAML Config

```yaml
judge:
  strategy: ensemble
  models:
    - name: "exaone3.5:7.8b"
      tier: strong
      weight: 0.95
    - name: "gemma3:1b"
      tier: fast
      weight: 0.6
  min_agreement: 2
  result_type: binary
```

## Requirements

- Python 3.11+
- [Ollama](https://ollama.com) running locally (for model inference)

## Optional Dependencies

```bash
pip install beethovain[api]   # REST API + Dashboard
pip install beethovain[tui]   # Terminal dashboard
pip install beethovain[hf]    # HuggingFace models
pip install beethovain[all]   # Everything
```

## Links

- **Website**: [beethovain.com](https://beethovain.com)
- **Docs**: Coming soon
