bonsai-slm 1.0.0__tar.gz

bonsai_slm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bonsai AI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bonsai_slm-1.0.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: bonsai-slm
+Version: 1.0.0
+Summary: The art of cultivating massive foundation models into pocket-sized intelligences on consumer silicon.
+Author-email: Bonsai Core Team <cultivate@bonsai.ai>
+License: MIT
+Keywords: ai,distillation,lora,qlora,slm,local-ai,quantization,micro-models
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: transformers>=4.40.0
+Requires-Dist: peft>=0.10.0
+Requires-Dist: accelerate>=0.28.0
+Requires-Dist: datasets>=2.18.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/bonsai-hero-banner.png" alt="Bonsai Hero Banner" width="100%" />
+</p>
+
+<h1 align="center">🌱 BONSAI (Major v1.0.0)</h1>
+
+<p align="center">
+  <strong>The art of cultivating massive foundation models into pocket-sized intelligences on consumer silicon.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bonsai-slm/"><img src="https://img.shields.io/pypi/v/bonsai-slm.svg?color=emerald" alt="PyPI version" /></a>
+  <a href="https://github.com/shenald-dev/bonsai/actions"><img src="https://img.shields.io/badge/CI-Passing-2ea44f.svg" alt="CI Status" /></a>
+  <a href="https://github.com/shenald-dev/bonsai/releases/tag/v0.1.0"><img src="https://img.shields.io/github/v/release/shenald-dev/bonsai?color=emerald" alt="Release" /></a>
+  <a href="https://github.com/shenald-dev/bonsai/stargazers"><img src="https://img.shields.io/github/stars/shenald-dev/bonsai?style=social" alt="GitHub Stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-0969da.svg" alt="License: MIT" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+" /></a>
+  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-2.6%2B%20CUDA-ee4c2c.svg" alt="PyTorch CUDA" /></a>
+  <a href="https://github.com/shenald-dev/bonsai"><img src="https://img.shields.io/badge/Zero--OOM-Guaranteed-brightgreen.svg" alt="Zero-OOM Protected" /></a>
+</p>
+
+---
+
+## ⚡ The 10-Second Quickstart
+
+```bash
+pip install bonsai-slm
+
+# Or run instantly without installation:
+uvx bonsai-slm prune ./my_raw_data
+```
+
+No JSONL formatting. No CUDA out-of-memory crashes. No hyperparameter tuning. Drop raw logs, CSVs, code files, or a plain-English task goal—Bonsai takes care of the rest.
+
+---
+
+## 🌊 Why Bonsai?
+
+Running local models is solved (`ollama`, `LM Studio`). But **99% of developers and everyday power-users have zero idea how to distill or train their own micro-models (0.5B to 1.5B) on their own home PC.**
+
+They get blocked by:
+- ❌ Manually formatting instruction-tuning JSONL pairs
+- ❌ Sudden `CUDA out of memory` crashes
+- ❌ Confusing ML hyperparameter jargon (`lora_r`, `grad_accum`, `cosine_warmup`)
+- ❌ Catastrophic forgetting and hallucination loops
+- ❌ Zero quantitative proof that their fine-tuned model actually improved
+
+**Bonsai eliminates the friction entirely.**
+
+It acts as an autonomous master artisan: inspecting your exact GPU VRAM / Unified Memory, cultivating training pairs across diverse task archetypes with guaranteed zero data leakage, executing an ultra-fast LoRA distillation pass with prompt token loss masking, proving accuracy gains on an unseen blind holdout exam, fusing weights into standalone merged models, and hosting an instant local Web UI and OpenAI-compatible API.
+
+---
+
+## 🏛️ How It Works: The 5-Step Cultivation Loop
+
+```mermaid
+flowchart LR
+    A["💻 1. PROBE<br/>Hardware Auto-Downshift"] --> B["📥 2. INGEST<br/>Raw Docs, Logs, or Goals"]
+    B --> C["🧬 3. CULTIVATE<br/>Multi-Archetype Zero-Leakage Split"]
+    C --> D["⚡ 4. DISTILL & FUSE<br/>Masked-Loss LoRA + Model Merge"]
+    D --> E["🔬 5. PROOF & SERVE<br/>SVG Scorecard + OpenAI API"]
+```
+
+1. **Hardware Auto-Probe:** Probes GPU VRAM, Apple Unified Memory, or CPU RAM. If VRAM is tight (<4 GB), it automatically downshifts base models (e.g., `Qwen2.5-Coder-0.5B`) to guarantee **Zero-OOM**.
+2. **Universal Ingestion:** Drop raw `.txt`, `.csv`, `.md`, server logs, Python/JS scripts, or specify a plain-English task.
+3. **Multi-Archetype Teacher Engine:** Synthesizes high-fidelity instruction-response pairs across 4 distinct domains (JSON telemetry, Q&A extraction, code generation, support triage) and enforces strict scenario deduplication *before* augmentation, splitting into an 85% training set and a 15% unseen blind holdout exam.
+4. **Pocket LoRA Distillation & Weight Fusion:** Freezes 99.78% of the model and cultivates only the top 0.22% of synaptic adapter weights with **prompt loss masking** (`labels[:prompt_len] = -100`). Fuse weights directly into standalone weights via `bonsai merge` for zero-overhead inference or direct llama.cpp/GGUF conversion.
+5. **The Proof Machine & API Serving:** Evaluates the untrained base model side-by-side against your newly cultivated model on the unseen exam set, emitting a viral SVG scorecard, interactive HTML report, and instant OpenAI-compatible API endpoint.
+
+---
+
+## 💻 CLI Commands
+
+### 1. Probe Hardware
+Inspects silicon headroom and translates ML jargon into human concepts:
+```bash
+bonsai probe
+```
+
+```
+╭─────────────────────────────────────────────────────────╮
+│               🌱 BONSAI HARDWARE TELEMETRY               │
+╰─────────────────────────────────────────────────────────╯
+Silicon: NVIDIA GeForce RTX 2050 (3300 MB Free VRAM)
+Recommended Micro-Model: Qwen2.5-Coder-0.5B-Instruct (Zero-OOM Protected)
+
+Translated Cultivation Recipe:
+  • Learning Agility (Learning Rate):    2e-4
+  • Synaptic Plasticity (LoRA Rank):     r=8, alpha=16
+  • Study Passes (Epochs):               3 passes
+  • Attention Batching (Accumulation):   4 steps
+```
+
+### 2. Prune & Distill
+Train a micro-AI on your local files or task description:
+```bash
+# From a folder of raw logs/documents:
+bonsai prune ./examples/messy_ops_to_json
+
+# Or from a task prompt:
+bonsai prune "Build a tiny AI that extracts strict JSON invoices from messy emails"
+```
+
+### 3. Exam & Proof Machine
+Evaluate the newly trained model on the unseen blind test set:
+```bash
+bonsai exam ./bonsai_pruned
+```
+
+Generates:
+* 📊 **Viral SVG Scorecard:** `bonsai-report.svg`
+* 🌐 **Interactive HTML Report:** `bonsai-report.html`
+* 📋 **Canonical State Manifest:** `bonsai_manifest.json`
+
+### 4. Merge Synaptic Weights (New in v1.0)
+Fuse LoRA adapter weights directly into the base model to create a standalone, zero-dependency model:
+```bash
+bonsai merge ./bonsai_pruned -o ./bonsai_pruned/merged
+```
+
+The merged output is a standard HuggingFace / safetensors directory that can be quantized directly to GGUF via `llama.cpp` or loaded with zero adapter overhead.
+
+### 5. Interactive Web Chat & OpenAI-Compatible API
+Launch the local dark-mode UI and standards-compliant OpenAI API endpoint (`/v1/chat/completions`):
+```bash
+bonsai ui --port 7860
+```
+
+#### Querying via cURL:
+```bash
+curl http://localhost:7860/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "bonsai-micro-ai",
+    "messages": [
+      {"role": "user", "content": "CRITICAL: db connection pool exhausted on worker-01"}
+    ]
+  }'
+```
+
+#### Querying via Python `openai` SDK:
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:7860/v1", api_key="not-needed")
+response = client.chat.completions.create(
+    model="bonsai-micro-ai",
+    messages=[{"role": "user", "content": "Extract invoice details from receipt"}]
+)
+print(response.choices[0].message.content)
+```
+
+---
+
+## 📊 Live Verification Scorecard (Clean-Room NVIDIA RTX 2050)
+
+<p align="center">
+  <img src="assets/bonsai-report.svg" alt="Bonsai Scorecard" width="100%" />
+</p>
+
+| Evaluation Metric | Raw Base Model | Cultivated Bonsai Model | Net Delta |
+|:---|:---:|:---:|:---:|
+| **Strict Schema Validity** | 100.0% | **100.0%** | Maintained |
+| **Output Cleanliness** | Markdown code fences, float fields | **Strict Bare JSON, snake_case** | **Reflexive Precision** |
+| **Training Duration** | — | **34.05 seconds** | **Ultra-Fast** |
+| **Loss Convergence** | 1.5905 | **0.7713** | **-51.5% Convergence** |
+| **Peak VRAM Allocated** | — | **2,045 MB** | **Zero-OOM Verified** |
+| **Inference Latency** | 3,533 ms | **4,352 ms** | Consumer Silicon Ready |
+
+---
+
+## 🥊 Comparison Matrix
+
+| Feature | Unsloth | Axolotl | Ollama | **🌱 Bonsai v1.0** |
+|:---|:---:|:---:|:---:|:---:|
+| **Target User** | ML Engineers | Senior ML Researchers | Everyone | **Everyone** |
+| **Dataset Requirement** | Manual `.jsonl` | Complex YAML + `.jsonl` | None (Inference only) | **Zero-Knowledge (Raw files/prompts)** |
+| **Hardware Safety** | Manual VRAM tuning | Manual tuning | Fixed GGUF | **Automated Zero-OOM Downshift** |
+| **Synthetic Teacher** | ❌ Manual | ❌ Manual | ❌ None | **✅ Universal Multi-Archetype Teacher** |
+| **Adapter Fusion (`merge`)**| Manual Python | Manual Python | ❌ None | **✅ 1-Command Weight Fusion (`bonsai merge`)** |
+| **OpenAI API Server** | ❌ None | ❌ None | Third-party proxy | **✅ Native `/v1/chat/completions` Endpoint** |
+| **Automated Exam Suite** | ❌ None | ❌ None | ❌ None | **✅ Unseen Blind Holdout Proof Machine** |
+| **Visual Proof Reports** | ❌ W&B logs | ❌ W&B logs | ❌ None | **✅ Standalone SVG & HTML Scorecards** |
+| **1-Click Web UI & Desktop**| ❌ None | ❌ None | ❌ CLI only | **✅ Dark-Mode UI + Windows .bat & Unix .sh** |
+
+---
+
+## 🧪 Automated Testing & Invariants
+
+Bonsai is continuously verified with automated unit and integration tests:
+
+```bash
+pytest tests/ -v
+```
+
+```
+collected 28 items
+tests/test_cli.py::test_cli_help PASSED                        [  3%]
+tests/test_cli.py::test_cli_version PASSED                     [  7%]
+tests/test_cli.py::test_cli_probe PASSED                       [ 10%]
+tests/test_cli.py::test_cli_merge_help PASSED                  [ 14%]
+tests/test_cli.py::test_cli_ui_help PASSED                     [ 17%]
+tests/test_cli.py::test_cli_prune_mocked PASSED                [ 21%]
+tests/test_evaluator_multimetric.py::test_evaluate_json_payload PASSED [ 25%]
+tests/test_evaluator_multimetric.py::test_evaluate_freeform_text PASSED [ 28%]
+tests/test_holdout_leakage.py::test_zero_data_leakage PASSED   [ 32%]
+tests/test_holdout_leakage.py::test_deterministic_seed_reproducibility PASSED [ 35%]
+tests/test_ingest.py::test_ingest_prompt_goal PASSED           [ 39%]
+tests/test_ingest.py::test_ingest_files PASSED                 [ 42%]
+tests/test_ingest.py::test_ingest_empty_directory PASSED       [ 46%]
+tests/test_manifest.py::test_manifest_roundtrip PASSED         [ 50%]
+tests/test_merger.py::test_merger_initialization PASSED        [ 53%]
+tests/test_merger.py::test_merger_execution PASSED             [ 57%]
+tests/test_multi_archetype_teacher.py::test_teacher_goal_invoice_synthesis PASSED [ 60%]
+tests/test_multi_archetype_teacher.py::test_teacher_goal_support_triage_synthesis PASSED [ 64%]
+tests/test_multi_archetype_teacher.py::test_teacher_goal_sql_synthesis PASSED [ 67%]
+tests/test_multi_archetype_teacher.py::test_teacher_csv_tabular_extraction PASSED [ 71%]
+tests/test_multi_archetype_teacher.py::test_teacher_code_function_extraction PASSED [ 75%]
+tests/test_multi_archetype_teacher.py::test_teacher_preformatted_alpaca_and_messages PASSED [ 78%]
+tests/test_multi_archetype_teacher.py::test_teacher_domain_adaptive_augmentation PASSED [ 82%]
+tests/test_probe.py::test_probe_hardware_structure PASSED      [ 85%]
+tests/test_probe.py::test_probe_jargon_translations PASSED     [ 89%]
+tests/test_web_server.py::test_server_init PASSED              [ 92%]
+tests/test_web_server.py::test_server_generate_mocked PASSED   [ 96%]
+tests/test_web_server.py::test_handler_endpoints PASSED        [100%]
+
+============================= 28 passed in 41.73s =============================
+```
+
+---
+
+## 📜 License & Community
+
+Released under the **[MIT License](LICENSE)**. Cultivated with care for the global open-source AI community.
+
+Contributions, issues, and PRs are warmly welcomed. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for details.

bonsai_slm-1.0.0/README.md

@@ -0,0 +1,236 @@
+<p align="center">
+  <img src="assets/bonsai-hero-banner.png" alt="Bonsai Hero Banner" width="100%" />
+</p>
+
+<h1 align="center">🌱 BONSAI (Major v1.0.0)</h1>
+
+<p align="center">
+  <strong>The art of cultivating massive foundation models into pocket-sized intelligences on consumer silicon.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bonsai-slm/"><img src="https://img.shields.io/pypi/v/bonsai-slm.svg?color=emerald" alt="PyPI version" /></a>
+  <a href="https://github.com/shenald-dev/bonsai/actions"><img src="https://img.shields.io/badge/CI-Passing-2ea44f.svg" alt="CI Status" /></a>
+  <a href="https://github.com/shenald-dev/bonsai/releases/tag/v0.1.0"><img src="https://img.shields.io/github/v/release/shenald-dev/bonsai?color=emerald" alt="Release" /></a>
+  <a href="https://github.com/shenald-dev/bonsai/stargazers"><img src="https://img.shields.io/github/stars/shenald-dev/bonsai?style=social" alt="GitHub Stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-0969da.svg" alt="License: MIT" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+" /></a>
+  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-2.6%2B%20CUDA-ee4c2c.svg" alt="PyTorch CUDA" /></a>
+  <a href="https://github.com/shenald-dev/bonsai"><img src="https://img.shields.io/badge/Zero--OOM-Guaranteed-brightgreen.svg" alt="Zero-OOM Protected" /></a>
+</p>
+
+---
+
+## ⚡ The 10-Second Quickstart
+
+```bash
+pip install bonsai-slm
+
+# Or run instantly without installation:
+uvx bonsai-slm prune ./my_raw_data
+```
+
+No JSONL formatting. No CUDA out-of-memory crashes. No hyperparameter tuning. Drop raw logs, CSVs, code files, or a plain-English task goal—Bonsai takes care of the rest.
+
+---
+
+## 🌊 Why Bonsai?
+
+Running local models is solved (`ollama`, `LM Studio`). But **99% of developers and everyday power-users have zero idea how to distill or train their own micro-models (0.5B to 1.5B) on their own home PC.**
+
+They get blocked by:
+- ❌ Manually formatting instruction-tuning JSONL pairs
+- ❌ Sudden `CUDA out of memory` crashes
+- ❌ Confusing ML hyperparameter jargon (`lora_r`, `grad_accum`, `cosine_warmup`)
+- ❌ Catastrophic forgetting and hallucination loops
+- ❌ Zero quantitative proof that their fine-tuned model actually improved
+
+**Bonsai eliminates the friction entirely.**
+
+It acts as an autonomous master artisan: inspecting your exact GPU VRAM / Unified Memory, cultivating training pairs across diverse task archetypes with guaranteed zero data leakage, executing an ultra-fast LoRA distillation pass with prompt token loss masking, proving accuracy gains on an unseen blind holdout exam, fusing weights into standalone merged models, and hosting an instant local Web UI and OpenAI-compatible API.
+
+---
+
+## 🏛️ How It Works: The 5-Step Cultivation Loop
+
+```mermaid
+flowchart LR
+    A["💻 1. PROBE<br/>Hardware Auto-Downshift"] --> B["📥 2. INGEST<br/>Raw Docs, Logs, or Goals"]
+    B --> C["🧬 3. CULTIVATE<br/>Multi-Archetype Zero-Leakage Split"]
+    C --> D["⚡ 4. DISTILL & FUSE<br/>Masked-Loss LoRA + Model Merge"]
+    D --> E["🔬 5. PROOF & SERVE<br/>SVG Scorecard + OpenAI API"]
+```
+
+1. **Hardware Auto-Probe:** Probes GPU VRAM, Apple Unified Memory, or CPU RAM. If VRAM is tight (<4 GB), it automatically downshifts base models (e.g., `Qwen2.5-Coder-0.5B`) to guarantee **Zero-OOM**.
+2. **Universal Ingestion:** Drop raw `.txt`, `.csv`, `.md`, server logs, Python/JS scripts, or specify a plain-English task.
+3. **Multi-Archetype Teacher Engine:** Synthesizes high-fidelity instruction-response pairs across 4 distinct domains (JSON telemetry, Q&A extraction, code generation, support triage) and enforces strict scenario deduplication *before* augmentation, splitting into an 85% training set and a 15% unseen blind holdout exam.
+4. **Pocket LoRA Distillation & Weight Fusion:** Freezes 99.78% of the model and cultivates only the top 0.22% of synaptic adapter weights with **prompt loss masking** (`labels[:prompt_len] = -100`). Fuse weights directly into standalone weights via `bonsai merge` for zero-overhead inference or direct llama.cpp/GGUF conversion.
+5. **The Proof Machine & API Serving:** Evaluates the untrained base model side-by-side against your newly cultivated model on the unseen exam set, emitting a viral SVG scorecard, interactive HTML report, and instant OpenAI-compatible API endpoint.
+
+---
+
+## 💻 CLI Commands
+
+### 1. Probe Hardware
+Inspects silicon headroom and translates ML jargon into human concepts:
+```bash
+bonsai probe
+```
+
+```
+╭─────────────────────────────────────────────────────────╮
+│               🌱 BONSAI HARDWARE TELEMETRY               │
+╰─────────────────────────────────────────────────────────╯
+Silicon: NVIDIA GeForce RTX 2050 (3300 MB Free VRAM)
+Recommended Micro-Model: Qwen2.5-Coder-0.5B-Instruct (Zero-OOM Protected)
+
+Translated Cultivation Recipe:
+  • Learning Agility (Learning Rate):    2e-4
+  • Synaptic Plasticity (LoRA Rank):     r=8, alpha=16
+  • Study Passes (Epochs):               3 passes
+  • Attention Batching (Accumulation):   4 steps
+```
+
+### 2. Prune & Distill
+Train a micro-AI on your local files or task description:
+```bash
+# From a folder of raw logs/documents:
+bonsai prune ./examples/messy_ops_to_json
+
+# Or from a task prompt:
+bonsai prune "Build a tiny AI that extracts strict JSON invoices from messy emails"
+```
+
+### 3. Exam & Proof Machine
+Evaluate the newly trained model on the unseen blind test set:
+```bash
+bonsai exam ./bonsai_pruned
+```
+
+Generates:
+* 📊 **Viral SVG Scorecard:** `bonsai-report.svg`
+* 🌐 **Interactive HTML Report:** `bonsai-report.html`
+* 📋 **Canonical State Manifest:** `bonsai_manifest.json`
+
+### 4. Merge Synaptic Weights (New in v1.0)
+Fuse LoRA adapter weights directly into the base model to create a standalone, zero-dependency model:
+```bash
+bonsai merge ./bonsai_pruned -o ./bonsai_pruned/merged
+```
+
+The merged output is a standard HuggingFace / safetensors directory that can be quantized directly to GGUF via `llama.cpp` or loaded with zero adapter overhead.
+
+### 5. Interactive Web Chat & OpenAI-Compatible API
+Launch the local dark-mode UI and standards-compliant OpenAI API endpoint (`/v1/chat/completions`):
+```bash
+bonsai ui --port 7860
+```
+
+#### Querying via cURL:
+```bash
+curl http://localhost:7860/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "bonsai-micro-ai",
+    "messages": [
+      {"role": "user", "content": "CRITICAL: db connection pool exhausted on worker-01"}
+    ]
+  }'
+```
+
+#### Querying via Python `openai` SDK:
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:7860/v1", api_key="not-needed")
+response = client.chat.completions.create(
+    model="bonsai-micro-ai",
+    messages=[{"role": "user", "content": "Extract invoice details from receipt"}]
+)
+print(response.choices[0].message.content)
+```
+
+---
+
+## 📊 Live Verification Scorecard (Clean-Room NVIDIA RTX 2050)
+
+<p align="center">
+  <img src="assets/bonsai-report.svg" alt="Bonsai Scorecard" width="100%" />
+</p>
+
+| Evaluation Metric | Raw Base Model | Cultivated Bonsai Model | Net Delta |
+|:---|:---:|:---:|:---:|
+| **Strict Schema Validity** | 100.0% | **100.0%** | Maintained |
+| **Output Cleanliness** | Markdown code fences, float fields | **Strict Bare JSON, snake_case** | **Reflexive Precision** |
+| **Training Duration** | — | **34.05 seconds** | **Ultra-Fast** |
+| **Loss Convergence** | 1.5905 | **0.7713** | **-51.5% Convergence** |
+| **Peak VRAM Allocated** | — | **2,045 MB** | **Zero-OOM Verified** |
+| **Inference Latency** | 3,533 ms | **4,352 ms** | Consumer Silicon Ready |
+
+---
+
+## 🥊 Comparison Matrix
+
+| Feature | Unsloth | Axolotl | Ollama | **🌱 Bonsai v1.0** |
+|:---|:---:|:---:|:---:|:---:|
+| **Target User** | ML Engineers | Senior ML Researchers | Everyone | **Everyone** |
+| **Dataset Requirement** | Manual `.jsonl` | Complex YAML + `.jsonl` | None (Inference only) | **Zero-Knowledge (Raw files/prompts)** |
+| **Hardware Safety** | Manual VRAM tuning | Manual tuning | Fixed GGUF | **Automated Zero-OOM Downshift** |
+| **Synthetic Teacher** | ❌ Manual | ❌ Manual | ❌ None | **✅ Universal Multi-Archetype Teacher** |
+| **Adapter Fusion (`merge`)**| Manual Python | Manual Python | ❌ None | **✅ 1-Command Weight Fusion (`bonsai merge`)** |
+| **OpenAI API Server** | ❌ None | ❌ None | Third-party proxy | **✅ Native `/v1/chat/completions` Endpoint** |
+| **Automated Exam Suite** | ❌ None | ❌ None | ❌ None | **✅ Unseen Blind Holdout Proof Machine** |
+| **Visual Proof Reports** | ❌ W&B logs | ❌ W&B logs | ❌ None | **✅ Standalone SVG & HTML Scorecards** |
+| **1-Click Web UI & Desktop**| ❌ None | ❌ None | ❌ CLI only | **✅ Dark-Mode UI + Windows .bat & Unix .sh** |
+
+---
+
+## 🧪 Automated Testing & Invariants
+
+Bonsai is continuously verified with automated unit and integration tests:
+
+```bash
+pytest tests/ -v
+```
+
+```
+collected 28 items
+tests/test_cli.py::test_cli_help PASSED                        [  3%]
+tests/test_cli.py::test_cli_version PASSED                     [  7%]
+tests/test_cli.py::test_cli_probe PASSED                       [ 10%]
+tests/test_cli.py::test_cli_merge_help PASSED                  [ 14%]
+tests/test_cli.py::test_cli_ui_help PASSED                     [ 17%]
+tests/test_cli.py::test_cli_prune_mocked PASSED                [ 21%]
+tests/test_evaluator_multimetric.py::test_evaluate_json_payload PASSED [ 25%]
+tests/test_evaluator_multimetric.py::test_evaluate_freeform_text PASSED [ 28%]
+tests/test_holdout_leakage.py::test_zero_data_leakage PASSED   [ 32%]
+tests/test_holdout_leakage.py::test_deterministic_seed_reproducibility PASSED [ 35%]
+tests/test_ingest.py::test_ingest_prompt_goal PASSED           [ 39%]
+tests/test_ingest.py::test_ingest_files PASSED                 [ 42%]
+tests/test_ingest.py::test_ingest_empty_directory PASSED       [ 46%]
+tests/test_manifest.py::test_manifest_roundtrip PASSED         [ 50%]
+tests/test_merger.py::test_merger_initialization PASSED        [ 53%]
+tests/test_merger.py::test_merger_execution PASSED             [ 57%]
+tests/test_multi_archetype_teacher.py::test_teacher_goal_invoice_synthesis PASSED [ 60%]
+tests/test_multi_archetype_teacher.py::test_teacher_goal_support_triage_synthesis PASSED [ 64%]
+tests/test_multi_archetype_teacher.py::test_teacher_goal_sql_synthesis PASSED [ 67%]
+tests/test_multi_archetype_teacher.py::test_teacher_csv_tabular_extraction PASSED [ 71%]
+tests/test_multi_archetype_teacher.py::test_teacher_code_function_extraction PASSED [ 75%]
+tests/test_multi_archetype_teacher.py::test_teacher_preformatted_alpaca_and_messages PASSED [ 78%]
+tests/test_multi_archetype_teacher.py::test_teacher_domain_adaptive_augmentation PASSED [ 82%]
+tests/test_probe.py::test_probe_hardware_structure PASSED      [ 85%]
+tests/test_probe.py::test_probe_jargon_translations PASSED     [ 89%]
+tests/test_web_server.py::test_server_init PASSED              [ 92%]
+tests/test_web_server.py::test_server_generate_mocked PASSED   [ 96%]
+tests/test_web_server.py::test_handler_endpoints PASSED        [100%]
+
+============================= 28 passed in 41.73s =============================
+```
+
+---
+
+## 📜 License & Community
+
+Released under the **[MIT License](LICENSE)**. Cultivated with care for the global open-source AI community.
+
+Contributions, issues, and PRs are warmly welcomed. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for details.

bonsai_slm-1.0.0/bonsai/__init__.py

@@ -0,0 +1,6 @@
+"""
+Bonsai - The art of cultivating massive foundation models into pocket-sized intelligences on consumer silicon.
+"""
+
+__version__ = "0.1.0"
+__app_name__ = "bonsai"