occam-lite 1.0.0
A lightweight complexity classifier for code functions
Requires Python: >=3.8

# Occam Lite

> A lightweight code complexity classifier for code functions

**Occam Lite** is a machine learning model that predicts the algorithmic complexity of code functions.

## Features

- 🚀 **Fast**: ~100ms predictions
- 🎯 **Accurate**: 98.33% test accuracy
- 📦 **Lightweight**: 8-feature model (400 KB)
- 🔓 **Open Source**: Apache 2.0 licensed
- 🐍 **Pure Python**: No external APIs

## Installation

```bash
pip install scikit-learn radon numpy
```

## Usage

```python
from occam_lite import predict_complexity

code = """
def bubble_sort(arr):
    for i in range(len(arr)):
        for j in range(len(arr) - i - 1):
            if arr[j] > arr[j + 1]:
                arr[j], arr[j + 1] = arr[j + 1], arr[j]
"""

result = predict_complexity(code)

print(result['complexity'])   # 'complex'
print(result['confidence'])   # 0.95
print(result['metrics'])      # {'loc': 6, 'cyclomatic': 4, ...}
```

## Complexity Classes

- **Simple** (O(1), O(log n), O(n)): Basic operations, single loops
- **Moderate** (O(n log n)): Efficient sorting, divide-and-conquer
- **Complex** (O(n²), O(n³), O(2ⁿ)): Nested loops, exponential algorithms

## Model Details

**Algorithm**: Random Forest Classifier
**Features**: 8 (LOC, cyclomatic complexity, nesting depth, loops, conditionals, derived metrics)
**Test Accuracy**: 98.33%

### Features Used

1. Lines of Code (LOC)
2. Cyclomatic Complexity
3. Nesting Depth
4. Loop Count
5. Conditional Count
6. Complexity Density (cyclomatic / LOC)
7. Total Branches (loops + conditionals)
8. Complexity * Depth

## API Reference

### `predict_complexity(code)`

Quick prediction for a single function.

**Returns:**

```python
{
    'complexity': 'simple' | 'moderate' | 'complex',
    'confidence': float,  # 0-1
    'metrics': {
        'loc': int,
        'cyclomatic': int,
        'nesting': int,
        'loops': int,
        'conditionals': int
    },
    'probabilities': {
        'simple': float,
        'moderate': float,
        'complex': float
    }
}
```

### `BigOPredictor` Class

For multiple predictions (reuses loaded model).

```python
from occam_lite import BigOPredictor

predictor = BigOPredictor()

# Single prediction
result = predictor.predict(code)

# Batch predictions
results = predictor.predict_batch([code1, code2, code3])
```

## Examples

See `examples/` directory for more usage examples.

## Limitations

- **Python-focused**: Model uses `radon` for Python code analysis
- **8 features**: Lightweight feature set focused on core metrics
- **Heuristic nesting**: Nesting depth is approximated

## Version History

**v1.0.0** (2025-01-27)

- Initial release
- 8-feature Random Forest model
- 98.33% accuracy on test set

## License

Apache License 2.0 - see [LICENSE](LICENSE) file

Copyright 2025 Josh O'Brien

## Citation

If you use this model in your research or project, please cite:

```
@software{occam_lite_2025,
  author = {O'Brien, Josh},
  title = {Occam Lite},
  year = {2025},
  url = {https://github.com/jobrien874/occam-lite}
}
```

## Contributing

This repository contains the trained model only. Training data and scripts are kept private.

Contributions welcome:

- Bug fixes
- Documentation improvements
- Additional examples
- Integration guides

## Support

- GitHub Issues: Report bugs or request features
- Discussions: Ask questions or share use cases

## Acknowledgments

Built with:

- scikit-learn (Random Forest implementation)
- radon (Python code metrics)
- numpy (numerical operations)

Trained on functions from open-source projects under permissive licenses.