Metadata-Version: 2.4
Name: structural-fuzzing
Version: 0.1.0
Summary: Structural fuzzing framework for parameterized model validation
Author-email: "Andrew H. Bond" <andrew.bond@sjsu.edu>
License: MIT
Keywords: fuzzing,model-validation,robustness,sensitivity-analysis,mutation-testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: examples
Requires-Dist: scikit-learn>=1.3; extra == "examples"
Requires-Dist: pandas>=2.0; extra == "examples"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Dynamic: license-file

# structural-fuzzing

Structural fuzzing framework for parameterized model validation.

Adapts the adversarial mindset of software fuzzing to model validation:
instead of mutating program inputs to find crashes, we mutate model
parameters to find prediction failures.

## Installation

```bash
pip install -e ".[dev,examples]"
```

## Quick Start

```python
import numpy as np
from structural_fuzzing import run_campaign

# Define your model's evaluate function
def evaluate_fn(params):
    """params: 1D array, one value per dimension.
    Returns: (mae, {target_name: error})
    """
    # Your model logic here
    errors = {"target_1": compute_error_1(params), ...}
    mae = sum(abs(v) for v in errors.values()) / len(errors)
    return mae, errors

# Run the full campaign
report = run_campaign(
    dim_names=["dim_a", "dim_b", "dim_c"],
    evaluate_fn=evaluate_fn,
)
print(report.summary())
```

## Components

1. **Dimension Enumeration** -- Exhaustive search over parameter subsets
2. **Pareto Frontier** -- Identify accuracy-complexity tradeoffs
3. **Sensitivity Profiling** -- Ablation-based importance ranking
4. **Model Robustness Index (MRI)** -- Quantify stability under perturbation
5. **Adversarial Threshold Search** -- Find parameter tipping points
6. **Compositional Testing** -- Greedy dimension-building sequences

## Examples

- `examples/geometric_economics/` -- 9D behavioral economics model with 16 prediction targets
- `examples/defect_prediction/` -- Software defect prediction with sklearn RandomForest

## Testing

```bash
pytest -v
```

## License

MIT
