Metadata-Version: 2.4
Name: aip-engine
Version: 0.3.0
Summary: Algebraic Independence Processor - auto-detects structure for optimal computation
Author: Carmen Esteban
License-Expression: MIT
Project-URL: Homepage, https://github.com/iafiscal1212/-aip-project-2026
Project-URL: Repository, https://github.com/iafiscal1212/-aip-project-2026
Project-URL: Documentation, https://github.com/iafiscal1212/-aip-project-2026/tree/main/aip-package/docs
Keywords: linear-algebra,sparse-matrix,graph-analysis,structure-detection,matrix-conversion,moe,optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Dynamic: license-file

# AIP Engine

**Algebraic Independence Processor** - Auto-detects structure in your data and picks the optimal computation path.

## Install

```bash
pip install aip-engine
```

## Quick start

```python
import aip
import numpy as np

# Matrix multiply: auto-detects sparse vs dense
A = np.eye(1000) * 3.0
B = np.eye(1000) * 2.0
C = aip.multiply(A, B)  # uses scipy.sparse automatically

# Solve linear system: auto-routes by shape and density
x = aip.solve(A, np.ones(1000))

# Graph analysis: communities, fraud detection
edges = [(0, 1), (1, 2), (2, 0), (3, 4)]
info = aip.analyze(edges)

# Matrix conversion: auto-detect optimal format
report = aip.analyze_format(A)
print(report['recommended'])  # 'DIA' (diagonal detected)
sparse_A = aip.to_sparse(A)   # auto-picks best sparse format

# MoE acceleration: only activate needed experts
result = aip.moe_forward(x_input, experts, router, n_active=4)
```

## Modules

### Detector (`aip.detect`, `aip.detect_matrix`)
Analyzes matrices and graphs to detect: density, sparsity, bipartition, connected components, max degree. Routes to optimal algorithm. Complexity: O(n + m).

### Matrix Operations (`aip.multiply`, `aip.solve`)
Auto-routing multiplication and linear system solving:

| Input | AIP detects | Routes to |
|-------|------------|-----------|
| Sparse matrix | density < 30% | `scipy.sparse` (CSR) |
| Dense matrix | density >= 30% | `numpy` / BLAS |
| Square sparse system | square + sparse | `spsolve` |
| Rectangular sparse | non-square + sparse | `LSQR` iterative |
| Rectangular dense | non-square + dense | `lstsq` |

### Matrix Conversion (`aip.convert`, `aip.to_sparse`, `aip.to_dense`)
Auto-detects internal structure (diagonal, banded, block, symmetric, triangular) and converts to the optimal storage format:

| Structure detected | Converts to |
|-------------------|-------------|
| Diagonal | DIA |
| Banded (narrow bandwidth) | DIA |
| Block-diagonal | BSR |
| General sparse | CSR |
| Dense (> 30%) | numpy array |

Includes `aip.analyze_format()` for full structural analysis with memory comparison, and `aip.benchmark_convert()` for actual timing benchmarks across formats.

### Graph Analysis (`aip.analyze`, `aip.detect_fraud`)
Community detection, critical nodes, and fraud pattern detection (odd cycle / carousel detection) in transaction networks.

### MoE Acceleration (`aip.moe_forward`, `aip.MoEEngine`)
Inference engine for Mixture-of-Experts models. Detects and activates only the needed experts (~3% of total), reducing compute and memory proportionally.

## Documentation

See the [docs/](docs/) folder for detailed API documentation of each module.

## Requirements

- Python 3.8+
- NumPy >= 1.20
- SciPy >= 1.7

## License

MIT - Carmen Esteban, 2025-2026
