# Math Expert

**Arithmetic, algebra, and mathematical reasoning**

---

## Purpose

The Math Expert validates mathematical claims, solves arithmetic problems, and performs algebraic reasoning within the BeastBullet system.

**Key Function**: Provide structured mathematical validation (VALID/INVALID/UNCERTAIN) for reasoning pipelines.

---

## Architecture

- **Input**: 256-dim embeddings (from shared encoder)
- **Hidden**: 256-dim, 3 layers
- **Output**: 3 classes (VALID, INVALID, UNCERTAIN)
- **Parameters**: 1.3M
- **Size**: 5.2MB

**Model Type**: Feed-forward neural network with ReLU activation

---

## Training

### Dataset
- **Primary**: Custom math dataset (1000+ examples)
- **Teacher Model**: Ollama/Mistral
- **Categories**: Arithmetic, algebra, percentages, fractions, word problems

### Methodology
- **Training Samples**: 1000+
- **Validation Samples**: 200+
- **Epochs**: 10
- **Batch Size**: 32
- **Learning Rate**: 1e-4
- **Accuracy**: 85.3% (validation)

---

## Performance

### Validation Metrics
- **Overall Accuracy**: 85.3%
- **Arithmetic**: 92% accuracy
- **Algebra**: 81% accuracy
- **Word Problems**: 78% accuracy

### Inference
- **Latency**: <10ms (CPU)
- **Deterministic**: 100% (same input → same output)

---

## Output Format

```python
{
  "class": "VALID",  # or "INVALID", "UNCERTAIN"
  "confidence": 0.89,
  "logits": [0.05, 0.06, 0.89]
}
```

---

## Use Cases

### ✅ Good Use Cases
- Validating mathematical claims
- Solving basic arithmetic (addition, subtraction, multiplication, division)
- Percentage calculations
- Simple algebra

### ❌ Not Suitable For
- Advanced calculus or differential equations
- Symbolic mathematics
- Theorem proving
- Multi-step complex proofs

---

## Integration Example

```python
from beastbullet.experts import MathExpert
from beastbullet.core import SharedEncoder

encoder = SharedEncoder("shared_encoder_v1.0.pt")
math_expert = MathExpert("math_expert_v1.0.pt")

# Validate calculation
claim = "15% of 240 is 36"
embedding = encoder.encode(claim)
result = math_expert.validate(embedding)

print(result)
# {"class": "VALID", "confidence": 0.92}
```

---

## Links

- **Main Repository**: https://huggingface.co/beastbullet/beastbullet-experts
- **Source Code**: https://codeberg.org/ishrikantbhosale/beastbullet-core

---