Metadata-Version: 2.4
Name: modelstudio
Version: 0.1.0
Summary: A production-oriented MVP tensor framework foundation with CPU tensors and autograd.
Author: ModelStudio Contributors
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# ModelStudio

ModelStudio is an early, production-oriented foundation for a Python AI tensor framework. The current MVP provides a working CPU tensor API, NumPy-backed CPU kernels, reverse-mode autograd, neural-network modules, optimizers, dispatcher boundaries, and native backend scaffolding for future C++/CUDA/ROCm/oneAPI work.

It is not a complete PyTorch or TensorFlow replacement. GPU folders are intentionally scaffolding until real backend implementations are written, built, and tested.

## What Works Today

- Python package `modelstudio`, commonly imported as `ms`
- CPU tensors with shape, dtype, device, strides, `.numpy()`, `.item()`, `.to()`, `.detach()`, `.zero_grad()`, and `.backward()`
- DTypes: `float32`, `float64`, `int32`, `int64`, `bool`
- Device parsing for `cpu`, `cuda`, `rocm`, and `oneapi`
- CPU creation ops: `tensor`, `empty`, `zeros`, `ones`, `randn`, `arange`
- CPU math ops: `+`, `-`, `*`, `/`, negation, `@`, `sum`, `mean`, `reshape`, `transpose`, `.T`, `relu`, `gelu`
- Reverse-mode autograd for the MVP ops, including broadcasting gradients
- `no_grad()` and `is_grad_enabled()`
- `nn.Module`, `Parameter`, `Linear`, `ReLU`, `GELU`, `MSELoss`, `LayerNorm`
- `optim.SGD` and `optim.AdamW`
- Dispatcher with CPU backend registered by default
- Unavailable CUDA, ROCm, and oneAPI backends that fail with explicit runtime errors

## Not Implemented Yet

- Real CUDA kernels or memory management
- Real ROCm/HIP kernels or memory management
- Real oneAPI/SYCL kernels or memory management
- Native Python extension bindings
- Full compiler graph capture and lowering
- Serialization, distributed training, mixed precision, convolution, sparse tensors, and production profiler hooks

Unsupported GPU devices fail clearly, for example:

```text
ModelStudioBackendUnavailable: CUDA backend is not built. Install modelstudio-cuda or build with MODELSTUDIO_ENABLE_CUDA=ON.
```

## Architecture

```text
Python frontend API
  |
  v
Tensor + Autograd
  |
  v
Ops modules
  |
  v
Runtime Dispatcher
  |
  +--> CPU Backend (NumPy MVP today, replaceable with C++ kernels)
  |
  +--> CUDA Backend placeholder (not built)
  |
  +--> ROCm Backend placeholder (not built)
  |
  +--> oneAPI Backend placeholder (not built)

Native scaffolding
  |
  +--> core tensor metadata, dtype, device, storage
  +--> dispatcher/backend interfaces
  +--> CPU kernel source layout
  +--> CUDA/ROCm/oneAPI source layout
```

The public API is intentionally independent from NumPy. NumPy is an internal CPU backend detail for the MVP, so later native CPU kernels can replace it without breaking Python users.

## Install

From the repository root:

```bash
python -m pip install -e ".[dev]"
```

## Test

```bash
python -m pytest
```

## Example

```python
import modelstudio as ms
from modelstudio import nn

x = ms.randn((32, 784), device="cpu", requires_grad=True)
w = ms.randn((784, 10), device="cpu", requires_grad=True)

y = x @ w
loss = y.mean()
loss.backward()

print(w.grad)
```

Training example:

```python
import modelstudio as ms
from modelstudio import nn


class MLP(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc1 = nn.Linear(784, 256)
        self.fc2 = nn.Linear(256, 10)

    def forward(self, x):
        x = ms.gelu(self.fc1(x))
        return self.fc2(x)


model = MLP()
optimizer = ms.optim.AdamW(model.parameters(), lr=3e-4)

x = ms.randn((16, 784))
target = ms.randn((16, 10))

pred = model(x)
loss = ms.mse_loss(pred, target)

optimizer.zero_grad()
loss.backward()
optimizer.step()
```

Run the included example:

```bash
python examples/train_mlp.py
```

## Benchmarks

```bash
python benchmarks/bench_matmul.py
python benchmarks/bench_mlp.py
```

The CPU MVP routes through NumPy, so benchmarks are mainly smoke tests and baseline measurements for future native kernels.

## Native Backend Strategy

Native source lives under `csrc/` and uses the top-level C++ namespace `modelstudio`.

Build options:

```cmake
option(MODELSTUDIO_ENABLE_CUDA "Build CUDA backend" OFF)
option(MODELSTUDIO_ENABLE_ROCM "Build ROCm backend" OFF)
option(MODELSTUDIO_ENABLE_ONEAPI "Build oneAPI backend" OFF)
```

The intended path is:

1. Keep the Python dispatcher contract stable.
2. Replace NumPy CPU kernels with native CPU kernels behind the same backend interface.
3. Add allocator and kernel implementations for CUDA, ROCm, and oneAPI in their backend folders.
4. Package GPU backends as optional install targets, such as `modelstudio-cuda`.
5. Require backend-specific tests before claiming support.

## Roadmap

- Expand tensor op coverage and gradient coverage.
- Wire native CPU kernels into Python bindings.
- Add graph capture, shape inference, fusion, and lowering.
- Implement serialization and state dicts.
- Implement real CUDA, ROCm, and oneAPI backends with CI coverage on matching hardware.
- Add documentation pages beyond the README as APIs stabilize.
