Metadata-Version: 2.4
Name: vulgaris
Version: 0.1.2
Summary: Foundational industrial AI model for real-time telemetry, IoT, and time-series
License: Apache-2.0
Project-URL: Homepage, https://github.com/vulgaris-ai/vulgaris
Project-URL: Documentation, https://github.com/vulgaris-ai/vulgaris#readme
Project-URL: Repository, https://github.com/vulgaris-ai/vulgaris
Project-URL: Bug Tracker, https://github.com/vulgaris-ai/vulgaris/issues
Keywords: machine-learning,deep-learning,time-series,industrial-ai,telemetry,iot,streaming,state-space-model,autograd,numpy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: serve
Requires-Dist: fastapi>=0.104; extra == "serve"
Requires-Dist: uvicorn[standard]>=0.24; extra == "serve"
Requires-Dist: pydantic>=2.4; extra == "serve"
Provides-Extra: train
Requires-Dist: tqdm>=4.66; extra == "train"
Requires-Dist: rich>=13.6; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.9; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.6; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: fastapi>=0.104; extra == "all"
Requires-Dist: uvicorn[standard]>=0.24; extra == "all"
Requires-Dist: pydantic>=2.4; extra == "all"
Requires-Dist: tqdm>=4.66; extra == "all"
Requires-Dist: rich>=13.6; extra == "all"
Dynamic: license-file

<div align="center">

# VULGARIS

**Foundational Industrial AI Model**

*Real-time telemetry · IoT · Telecom · Time-series*

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-vulgaris-orange.svg)](https://pypi.org/project/vulgaris)

</div>

---

VULGARIS is an open-source foundational model for industrial time-series data — built from scratch in pure NumPy with a custom reverse-mode autograd engine. No PyTorch. No TensorFlow. No CUDA required.

It is designed for real-world deployments in telecom networks, IoT sensor grids, SCADA systems, and edge hardware where data is streaming, multimodal, and non-stationary.

## Architecture

```
Input (B, C, T)
     │
     ▼
┌──────────────────────────────────────────────────────┐
│  ASE  — Adaptive Signal Embedding (Morlet wavelets)  │
│  HTD  — Hierarchical Timescale Decomposition (4×SSM) │
│  SSSR — Selective State-Space Recurrence (diag ZOH)  │
│  DAH  — Domain-Adaptive Hypernetwork (LoRA)          │
│  CRG  — Causal Routing Graph (NOTEARS DAG)           │
│  HMB  — Hierarchical Memory Bank (VAE slots)         │
│  Safety — Control Barrier Function head              │
│  ESE  — Explainability Engine (CART rules)           │
└──────────────────────────────────────────────────────┘
     │
     ▼
Output + Aux losses (DAG penalty, memory loss, CBF)
```

## Installation

```bash
# Core (numpy only — no optional deps)
pip install vulgaris

# With inference server
pip install "vulgaris[serve]"

# Full install
pip install "vulgaris[all]"
```

## Quick Start

```python
import numpy as np
from vulgaris import Vulgaris, ModelConfig

# Configure
config = ModelConfig(
    input_dim=9,      # number of input channels
    n_classes=5,      # set 0 for regression
    output_dim=1,
)

# Build model
model = Vulgaris(config)

# Forward pass
x = np.random.randn(8, 9, 64).astype(np.float32)  # (batch, channels, time)
from vulgaris import Tensor
output, aux = model(Tensor(x))
print(output.data.shape)   # (8, 5)

# Streaming single-step inference
state = model.init_state(batch_size=1)
x_t = Tensor(np.random.randn(1, 9).astype(np.float32))
out_t, state = model.step(x_t, state)
```

## Training

```python
from vulgaris import (
    Vulgaris, ModelConfig,
    TrainingPipeline, VulgarisLoss,
    SpectralAdamW, CosineSchedule,
)

config    = ModelConfig(input_dim=9, n_classes=5)
model     = Vulgaris(config)
loss_fn   = VulgarisLoss(config)
optimizer = SpectralAdamW(model.parameters(), lr=3e-4)
scheduler = CosineSchedule(optimizer, warmup_steps=1000,
                           max_steps=50_000, min_lr=1e-6)
pipeline  = TrainingPipeline(model, config, loss_fn, optimizer, scheduler)

# Train
x_np = np.random.randn(32, 9, 64).astype(np.float32)
y_np = np.zeros(32, dtype=np.float32)
metrics = pipeline.train_step(x_np, y_np)
print(metrics)
```

## From Environment (production)

```bash
export VULGARIS_INPUT_DIM=9
export VULGARIS_N_CLASSES=5
export VULGARIS_D_MODEL=256
```

```python
from vulgaris import ModelConfig, Vulgaris
config = ModelConfig.from_env()
model  = Vulgaris(config)
```

## Serve via REST API

```bash
pip install "vulgaris[serve]"
export VULGARIS_INPUT_DIM=9
export VULGARIS_N_CLASSES=5
vulgaris-serve
# → http://localhost:8000
# → http://localhost:8000/docs
# → http://localhost:8000/metrics
```

## Docker

```bash
docker compose up
```

## Key Features

| Feature | Description |
|---|---|
| **Pure NumPy** | No PyTorch/TF/JAX — runs anywhere Python runs |
| **Custom Autograd** | Tape-based reverse-mode with graph freeing |
| **State-Space Core** | Diagonal ZOH SSM, sub-quadratic in sequence length |
| **Causal Discovery** | NOTEARS DAG learns causal structure online |
| **Domain Adaptation** | LoRA hypernetwork, switch domains at inference time |
| **Explainability** | CART rule extraction from latent representations |
| **Safety** | Control Barrier Function output head |
| **Conformal Prediction** | Non-stationary coverage guarantees |
| **Streaming** | Single-step `.step()` API for edge deployment |
| **Multi-modal** | InfoNCE cross-modal alignment (CMLA) |
| **Federated** | Differential privacy + federated continual learning |
| **Drift Detection** | KS, MMD, Wasserstein-1D drift monitoring |

## Repository Structure

```
vulgaris-ai/
├── vulgaris/          ← Public API entry point
├── engine/            ← Autograd engine (Tensor, Module, Layers)
├── modules/           ← Model building blocks
├── model/             ← Full Vulgaris model
├── training/          ← Loss, optimizer, pipeline, self-supervised
├── inference/         ← FastAPI server + streaming
├── serve/             ← Auth, metrics, degradation, versioning
├── monitoring/        ← Drift detection
├── federated/         ← Federated continual learning
├── benchmarks/        ← Baselines + dataset loaders
├── tests/             ← Unit + integration tests
└── config.py          ← All configuration dataclasses
```

## Citation

```bibtex
@software{vulgaris2026,
  title   = {VULGARIS: Foundational Industrial AI Model},
  year    = {2026},
  url     = {https://github.com/vulgaris-ai/vulgaris},
  license = {Apache-2.0},
}
```

## License

Apache License 2.0 — see [LICENSE](LICENSE).
