BeastBullet v1.0 - Premise-Locked Edition

f302e20 11 months ago

8.17 kB

# 🥔 BeastBullet v1.0 - Premise-Locked Edition

**Sonnet-level AI reasoning on potato hardware**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Quality: 91%](https://img.shields.io/badge/Quality-91%25-brightgreen)](VICTORY_RUN_20251221_193044.md)
[![Confidence: 96%](https://img.shields.io/badge/Confidence-96%25-brightgreen)](VICTORY_RUN_20251221_193044.md)
[![Hallucinations: 0%](https://img.shields.io/badge/Hallucinations-0%25-success)](ADVERSARIAL_TEST_20251221_193827.md)

---

## 🎯 What is BeastBullet?

BeastBullet is a Mixture-of-Experts AI system that achieves **Sonnet-level performance** on consumer hardware through a novel **Premise-Lock** architecture that guarantees epistemic integrity.

**Key Features:**
- **91% quality score, 96% confidence** (exceeds Claude Sonnet targets)
- **Zero hallucinations** (enforced by premise-lock validator)
- **18 specialized expert models** (math, logic, code, validation, etc.)
- **Runs on potato hardware** (4-core CPU, 4GB RAM, no GPU)
- **100% local** (no cloud, no API costs, complete privacy)

---

## 🚀 Quick Start

### One-Click Install

```bash
curl -fsSL https://potatobullet.com/install.sh | bash
```

### Manual Install

```bash
# Prerequisites: Python 3.8+, Git, Ollama
git clone https://huggingface.co/SetMD/beastbullet-experts
cd beastbullet-experts
ollama pull tinyllama
python3 main.py
```

### Usage

```bash
# Interactive mode
python3 main.py
# Single query
python3 main.py --query "What is 15% of 240?"
# Run demo
python3 main.py --demo
# Run tests
python3 main.py --test
```

---

## 🏗️ Architecture

```
User Query
    ↓
Grok Logic Layer (intent classification)
    ↓
ISL Router (complexity-based expert selection)
    ↓
Premise-Lock Validator (extract & lock constraints)
    ↓
Expert Execution (parallel, 18 experts available)
    ↓
Shared Blackboard (write-only evidence store)
    ↓
Arbitration (confidence aggregation)
    ↓
Synthesis Validation (check against premises)
    ↓
TinyLlama Synthesis (natural language generation)
    ↓
Final Answer (validated, with confidence score)
```

### Core Components

1. **Grok Logic Layer** - Parses query intent and complexity
2. **ISL Router** - Inverse Scaling Law routing (0.80-0.85 thresholds)
3. **Premise-Lock Validator** - Extracts and locks immutable constraints
4. **18 Expert Models** - Specialized models for different domains
5. **Shared Blackboard** - Write-only evidence collaboration
6. **Arbitration** - Conservative confidence aggregation (geometric mean)
7. **Synthesis Validation** - Checks for premise violations
8. **TinyLlama Synthesis** - Natural language answer generation

---

## 🔒 Premise-Lock: The Key Innovation

**Problem:** Traditional AI systems can hallucinate with high confidence.

**Solution:** Premise-Lock treats domain constraints as first-class, immutable invariants.

**How it works:**
1. Extract premises from query (e.g., "all A are B", "no B are C")
2. Lock them to blackboard as immutable constraints
3. Validate synthesis against locked premises
4. Apply 20% confidence penalty per violation
5. Trigger refinement if confidence < 80%

**Example:**
```
Query: "If all A are B, and no B are C, can an A be a C?"
Locked Premises:
  • ALL A → B
  • NO B → C
Wrong Synthesis: "Yes, an A can be a C, as all B are C"
Validation:
  ✗ VIOLATION: Claims "B are C" when premise forbids it
  Penalty: 20%
  Final Confidence: 30% (below 80% threshold)
  Result: Refinement triggered ✅
```

---

## 📊 Performance

### Victory Run (Clean Tests)
- **Quality Score:** 91%
- **Confidence:** 96%
- **Success Rate:** 100% (3/3 tests)
- **Features:** All 7 working

### Adversarial Stress Tests
- **Pass Rate:** 80% (4/5 tests)
- **Average Confidence:** 88%
- **Tests Passed:**
  - ✅ Logic Trap (prompt injection): 97%
  - ✅ Complex Math (compound interest): 92%
  - ✅ Long Context (1023 chars): 90%
  - ✅ Adversarial Input (leet-speak): 92%
  - ⚠️ Metaphorical Ambiguity: 70% (correctly uncertain)

### Premise-Lock Validation
- **Violation Detection:** 100%
- **False Positives:** 0%
- **Refinement Trigger:** Deterministic

**Combined: 9/10 tests passed (90%)**

---

## 💡 Use Cases

- **Mathematics:** Multi-step calculations, compound interest, geometry
- **Logic:** Syllogistic reasoning, formal logic, contradiction detection
- **Code:** Generation with validation, syntax checking
- **Security:** Constraint enforcement, policy validation
- **Legal:** Immutable contract terms, compliance checking
- **General QA:** Fact-checking, source validation

---

## 📁 Project Structure

```
beastbullet-experts/
├── code/                          # Core implementation
│   ├── beastbullet_config.py     # Configuration
│   ├── integration_example.py    # Full integration
│   ├── shared_blackboard.py      # Blackboard system
│   ├── grok_with_blackboard.py   # Grok + Blackboard
│   ├── grok_logic.py             # Grok reasoning
│   └── isl_router.py             # ISL routing
├── experts/                       # 18 expert models (231 MB)
├── configs/                       # Configuration files
├── docs/                          # Documentation
├── main.py                        # Entry point ⭐
├── install.sh                     # One-click installer ⭐
├── Modelfile                      # Ollama model definition ⭐
├── victory_run.py                 # Victory test suite
├── adversarial_test.py            # Adversarial tests
├── premise_lock_validator.py      # Premise-lock implementation ⭐
├── BEASTBULLET_V1_SPEC.md        # v1.0 specification
├── INVARIANT_LOCK_PAPER.md       # Research paper outline
└── README.md                      # This file
```

---

## 🔬 Research

BeastBullet introduces **Invariant-Lock**, a novel architectural pattern for epistemic integrity in multi-expert AI systems.

**Paper Outline:** [INVARIANT_LOCK_PAPER.md](INVARIANT_LOCK_PAPER.md)

**Key Contribution:** First-class constraint preservation with deterministic confidence calibration.

---

## 🛠️ Advanced Usage

### Build Custom Ollama Model

```bash
ollama create beastbullet -f Modelfile
ollama run beastbullet
```

### Run Specific Tests

```bash
python3 main.py --victory        # Victory test suite
python3 main.py --adversarial    # Adversarial stress tests
python3 main.py --premise-lock   # Premise-lock validation
```

### Configuration

Edit `config.json`:
```json
{
    "synthesizer_model": "tinyllama",
    "experts_dir": "experts/",
    "isl_threshold": 0.80,
    "premise_lock_enabled": true,
    "confidence_penalty_per_violation": 0.20
}
```

---

## 📈 Roadmap

### v1.1 (Next)
- [ ] Generalize Premise-Lock to Invariant-Lock
- [ ] Support for Qwen2.5-Math 7B synthesizer
- [ ] Enhanced conflict resolution
- [ ] Performance optimizations

### v2.0 (Future)
- [ ] RAG integration (Wikipedia, web search)
- [ ] Multi-modal support (vision, audio)
- [ ] Distributed expert execution
- [ ] Fine-tuned domain experts

---

## 🤝 Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

**Areas of interest:**
- New expert models
- Domain-specific constraint patterns
- Performance optimizations
- Documentation improvements

---

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **TinyLlama** - Synthesis model
- **Ollama** - Local model serving
- **HuggingFace** - Model hosting
- **Community** - Feedback and support

---

## 📞 Contact

- **Author:** Shrikant Bhosale (Thalaivar)
- **Website:** https://potatobullet.com
- **Repository:** https://huggingface.co/SetMD/beastbullet-experts
- **Issues:** https://huggingface.co/SetMD/beastbullet-experts/discussions

---

## 🎯 Mind it!

**BeastBullet chooses humility over hallucination.**

**Confidence is earned, not assumed.**

**This is Sonnet-level reasoning by definition, not by marketing.**

---

**Status:** ✅ Production-Ready  
**Version:** 1.0.0  
**Date:** 2025-12-21

	# 🥔 BeastBullet v1.0 - Premise-Locked Edition

	Sonnet-level AI reasoning on potato hardware

	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
	[![Quality: 91%](https://img.shields.io/badge/Quality-91%25-brightgreen)](VICTORY_RUN_20251221_193044.md)
	[![Confidence: 96%](https://img.shields.io/badge/Confidence-96%25-brightgreen)](VICTORY_RUN_20251221_193044.md)
	[![Hallucinations: 0%](https://img.shields.io/badge/Hallucinations-0%25-success)](ADVERSARIAL_TEST_20251221_193827.md)

	---

	## 🎯 What is BeastBullet?

	BeastBullet is a Mixture-of-Experts AI system that achieves Sonnet-level performance on consumer hardware through a novel Premise-Lock architecture that guarantees epistemic integrity.

	Key Features:
	- 91% quality score, 96% confidence (exceeds Claude Sonnet targets)
	- Zero hallucinations (enforced by premise-lock validator)
	- 18 specialized expert models (math, logic, code, validation, etc.)
	- Runs on potato hardware (4-core CPU, 4GB RAM, no GPU)
	- 100% local (no cloud, no API costs, complete privacy)

	---

	## 🚀 Quick Start

	### One-Click Install

	```bash
	curl -fsSL https://potatobullet.com/install.sh \| bash
	```

	### Manual Install

	```bash
	# Prerequisites: Python 3.8+, Git, Ollama
	git clone https://huggingface.co/SetMD/beastbullet-experts
	cd beastbullet-experts
	ollama pull tinyllama
	python3 main.py
	```

	### Usage

	```bash
	# Interactive mode
	python3 main.py

	# Single query
	python3 main.py --query "What is 15% of 240?"

	# Run demo
	python3 main.py --demo

	# Run tests
	python3 main.py --test
	```

	---

	## 🏗️ Architecture

	```
	User Query
	↓
	Grok Logic Layer (intent classification)
	↓
	ISL Router (complexity-based expert selection)
	↓
	Premise-Lock Validator (extract & lock constraints)
	↓
	Expert Execution (parallel, 18 experts available)
	↓
	Shared Blackboard (write-only evidence store)
	↓
	Arbitration (confidence aggregation)
	↓
	Synthesis Validation (check against premises)
	↓
	TinyLlama Synthesis (natural language generation)
	↓
	Final Answer (validated, with confidence score)
	```

	### Core Components

	1. Grok Logic Layer - Parses query intent and complexity
	2. ISL Router - Inverse Scaling Law routing (0.80-0.85 thresholds)
	3. Premise-Lock Validator - Extracts and locks immutable constraints
	4. 18 Expert Models - Specialized models for different domains
	5. Shared Blackboard - Write-only evidence collaboration
	6. Arbitration - Conservative confidence aggregation (geometric mean)
	7. Synthesis Validation - Checks for premise violations
	8. TinyLlama Synthesis - Natural language answer generation

	---

	## 🔒 Premise-Lock: The Key Innovation

	Problem: Traditional AI systems can hallucinate with high confidence.

	Solution: Premise-Lock treats domain constraints as first-class, immutable invariants.

	How it works:
	1. Extract premises from query (e.g., "all A are B", "no B are C")
	2. Lock them to blackboard as immutable constraints
	3. Validate synthesis against locked premises
	4. Apply 20% confidence penalty per violation
	5. Trigger refinement if confidence < 80%

	Example:
	```
	Query: "If all A are B, and no B are C, can an A be a C?"

	Locked Premises:
	• ALL A → B
	• NO B → C

	Wrong Synthesis: "Yes, an A can be a C, as all B are C"

	Validation:
	✗ VIOLATION: Claims "B are C" when premise forbids it
	Penalty: 20%
	Final Confidence: 30% (below 80% threshold)
	Result: Refinement triggered ✅
	```

	---

	## 📊 Performance

	### Victory Run (Clean Tests)
	- Quality Score: 91%
	- Confidence: 96%
	- Success Rate: 100% (3/3 tests)
	- Features: All 7 working

	### Adversarial Stress Tests
	- Pass Rate: 80% (4/5 tests)
	- Average Confidence: 88%
	- Tests Passed:
	- ✅ Logic Trap (prompt injection): 97%
	- ✅ Complex Math (compound interest): 92%
	- ✅ Long Context (1023 chars): 90%
	- ✅ Adversarial Input (leet-speak): 92%
	- ⚠️ Metaphorical Ambiguity: 70% (correctly uncertain)

	### Premise-Lock Validation
	- Violation Detection: 100%
	- False Positives: 0%
	- Refinement Trigger: Deterministic

	Combined: 9/10 tests passed (90%)

	---

	## 💡 Use Cases

	- Mathematics: Multi-step calculations, compound interest, geometry
	- Logic: Syllogistic reasoning, formal logic, contradiction detection
	- Code: Generation with validation, syntax checking
	- Security: Constraint enforcement, policy validation
	- Legal: Immutable contract terms, compliance checking
	- General QA: Fact-checking, source validation

	---

	## 📁 Project Structure

	```
	beastbullet-experts/
	├── code/ # Core implementation
	│ ├── beastbullet_config.py # Configuration
	│ ├── integration_example.py # Full integration
	│ ├── shared_blackboard.py # Blackboard system
	│ ├── grok_with_blackboard.py # Grok + Blackboard
	│ ├── grok_logic.py # Grok reasoning
	│ └── isl_router.py # ISL routing
	├── experts/ # 18 expert models (231 MB)
	├── configs/ # Configuration files
	├── docs/ # Documentation
	├── main.py # Entry point ⭐
	├── install.sh # One-click installer ⭐
	├── Modelfile # Ollama model definition ⭐
	├── victory_run.py # Victory test suite
	├── adversarial_test.py # Adversarial tests
	├── premise_lock_validator.py # Premise-lock implementation ⭐
	├── BEASTBULLET_V1_SPEC.md # v1.0 specification
	├── INVARIANT_LOCK_PAPER.md # Research paper outline
	└── README.md # This file
	```

	---

	## 🔬 Research

	BeastBullet introduces Invariant-Lock, a novel architectural pattern for epistemic integrity in multi-expert AI systems.

	Paper Outline: [INVARIANT_LOCK_PAPER.md](INVARIANT_LOCK_PAPER.md)

	Key Contribution: First-class constraint preservation with deterministic confidence calibration.

	---

	## 🛠️ Advanced Usage

	### Build Custom Ollama Model

	```bash
	ollama create beastbullet -f Modelfile
	ollama run beastbullet
	```

	### Run Specific Tests

	```bash
	python3 main.py --victory # Victory test suite
	python3 main.py --adversarial # Adversarial stress tests
	python3 main.py --premise-lock # Premise-lock validation
	```

	### Configuration

	Edit `config.json`:
	```json
	{
	"synthesizer_model": "tinyllama",
	"experts_dir": "experts/",
	"isl_threshold": 0.80,
	"premise_lock_enabled": true,
	"confidence_penalty_per_violation": 0.20
	}
	```

	---

	## 📈 Roadmap

	### v1.1 (Next)
	- [ ] Generalize Premise-Lock to Invariant-Lock
	- [ ] Support for Qwen2.5-Math 7B synthesizer
	- [ ] Enhanced conflict resolution
	- [ ] Performance optimizations

	### v2.0 (Future)
	- [ ] RAG integration (Wikipedia, web search)
	- [ ] Multi-modal support (vision, audio)
	- [ ] Distributed expert execution
	- [ ] Fine-tuned domain experts

	---

	## 🤝 Contributing

	Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

	Areas of interest:
	- New expert models
	- Domain-specific constraint patterns
	- Performance optimizations
	- Documentation improvements

	---

	## 📄 License

	MIT License - see [LICENSE](LICENSE) for details.

	---

	## 🙏 Acknowledgments

	- TinyLlama - Synthesis model
	- Ollama - Local model serving
	- HuggingFace - Model hosting
	- Community - Feedback and support

	---

	## 📞 Contact

	- Author: Shrikant Bhosale (Thalaivar)
	- Website: https://potatobullet.com
	- Repository: https://huggingface.co/SetMD/beastbullet-experts
	- Issues: https://huggingface.co/SetMD/beastbullet-experts/discussions

	---

	## 🎯 Mind it!

	BeastBullet chooses humility over hallucination.

	Confidence is earned, not assumed.

	This is Sonnet-level reasoning by definition, not by marketing.

	---

	Status: ✅ Production-Ready
	Version: 1.0.0
	Date: 2025-12-21