Metadata-Version: 2.4
Name: godml
Version: 1.1.1
Summary: Governed, Observable & Declarative Machine Learning Framework
Author-email: Arturo Gutierrez Rubio Rojas <agtzrubio@dagmalia.com>
Maintainer-email: Arturo Gutierrez Rubio Rojas <agtzrubio@dagmalia.com>
License: MIT
Project-URL: Documentation, https://godmlcore.com
Project-URL: Homepage, https://godmlcore.com
Project-URL: Source, https://github.com/DAGMALIA/godml
Project-URL: PyPI, https://pypi.org/project/godml/
Project-URL: SLSA Framework, https://slsa.dev/
Project-URL: Supply Chain Verified, https://search.sigstore.dev/?q=DAGMALIA
Keywords: mlops,machine learning,framework,governance,observability,mlflow,sagemaker,dagmalia,supply-chain-security,slsa,cosign,sigstore
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Classifier: Natural Language :: English
Classifier: Natural Language :: Spanish
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE_REPORT.md
Requires-Dist: typer<1,>=0.12.0
Requires-Dist: click<9,>=8.1.0
Requires-Dist: rich<16,>=13.0.0
Requires-Dist: pydantic<3,>=2.11.0
Requires-Dist: pyyaml<7,>=6.0.0
Requires-Dist: pandas<4,>=2.0.0
Requires-Dist: numpy<3.0,>=1.24.0
Requires-Dist: scikit-learn<2,>=1.5.0
Requires-Dist: xgboost<4,>=2.0.0
Requires-Dist: mlflow<4,>=2.13.0
Requires-Dist: joblib<2,>=1.3.0
Requires-Dist: urllib3<3,>=2.0.0
Requires-Dist: protobuf<8,>=4.25.0
Provides-Extra: api
Requires-Dist: fastapi<1,>=0.110.0; extra == "api"
Requires-Dist: uvicorn[standard]<1,>=0.29.0; extra == "api"
Provides-Extra: aws
Requires-Dist: boto3<2,>=1.34.0; extra == "aws"
Requires-Dist: sagemaker<4,>=2.200.0; extra == "aws"
Provides-Extra: deep
Requires-Dist: tensorflow<3,>=2.16.0; extra == "deep"
Requires-Dist: keras<4,>=3.0.0; extra == "deep"
Provides-Extra: advisor
Requires-Dist: gpt4all<3,>=2.0.0; extra == "advisor"
Requires-Dist: lightgbm<5,>=4.0.0; extra == "advisor"
Provides-Extra: data
Requires-Dist: pyarrow<25,>=15.0.0; extra == "data"
Requires-Dist: pymysql<2,>=1.1.0; extra == "data"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov<8,>=5.0.0; extra == "dev"
Requires-Dist: pytest-mock<4,>=3.14.0; extra == "dev"
Requires-Dist: moto[all]<6,>=5.0.0; extra == "dev"
Requires-Dist: httpx<1,>=0.27.0; extra == "dev"
Provides-Extra: all
Requires-Dist: godml[api]; extra == "all"
Requires-Dist: godml[aws]; extra == "all"
Requires-Dist: godml[deep]; extra == "all"
Requires-Dist: godml[advisor]; extra == "all"
Requires-Dist: godml[data]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/pypi/v/godml?color=0066cc&label=godml&logo=pypi&logoColor=white" alt="PyPI">
  <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue?logo=python&logoColor=white" alt="Python">
  <img src="https://github.com/DAGMALIA/godml/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI">
  <img src="https://github.com/DAGMALIA/godml/actions/workflows/safety_scan.yml/badge.svg?branch=main" alt="Supply Chain">
  <img src="https://img.shields.io/badge/SLSA-Level%203-green?logo=slsa&logoColor=white" alt="SLSA L3">
  <img src="https://img.shields.io/badge/Sigstore-Verified-blueviolet?logo=sigstore&logoColor=white" alt="Sigstore">
  <img src="https://api.securityscorecards.dev/projects/github.com/DAGMALIA/godml/badge" alt="OpenSSF Scorecard">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT">
</p>

<h1 align="center">GODML</h1>
<p align="center"><strong>Governed, Observable & Declarative Machine Learning Framework</strong></p>
<p align="center">
  Production-grade MLOps for teams that need traceability, compliance, and a verified supply chain — without the infrastructure overhead.
</p>

---

## Quick start

```bash
pip install godml
godml init my-project
godml run -f godml.yml
```

That's it. No cloud account required for local training.

---

## What is GODML?

GODML is a Python framework that wraps the full ML lifecycle — data prep, training, evaluation, monitoring, and deployment — behind a single declarative YAML config. Every run produces a signed, auditable artifact trail.

```
Raw data → Compliance check → Train → Evaluate → Registry → Deploy → Monitor
               (PII/GDPR)    (XGB/RF/LR)  (cross-val)  (MLflow)  (Docker)  (drift)
```

### Why GODML over plain sklearn + MLflow?

| Problem | Without GODML | With GODML |
|---------|--------------|------------|
| Reproducibility | Manual notebooks | Declarative YAML, locked hashes |
| Compliance | Ad-hoc checks | Built-in PCI-DSS, GDPR, HIPAA |
| Supply chain | No SBOM | SLSA L3 provenance + signed SBOM |
| Audit trail | Scattered logs | Unified lineage per run |
| Multi-model | Custom glue code | Registry + `notebook_api` |

---

## Installation

### Core (no optional deps)

```bash
pip install godml
```

### With extras

```bash
pip install "godml[advisor]"   # LLM-powered recommendations (gpt4all)
pip install "godml[deep]"      # LSTM forecasting (tensorflow + keras)
pip install "godml[aws]"       # SageMaker deployment
pip install "godml[api]"       # REST inference server (fastapi + uvicorn)
pip install "godml[dev]"       # Full dev suite (tests, lint, coverage)
```

---

## Configuration

A minimal `godml.yml`:

```yaml
name: customer-churn
version: 1.0.0
provider: mlflow

dataset:
  uri: ./data/churn.csv
  hash: auto

model:
  type: xgboost
  hyperparameters:
    max_depth: 6
    learning_rate: 0.1
    n_estimators: 300

metrics:
  - name: auc
    threshold: 0.85
  - name: accuracy
    threshold: 0.80

governance:
  owner: ml-team@company.com
  tags:
    - compliance: gdpr
    - environment: production

deploy:
  realtime: true
  batch_output: ./outputs/predictions.csv
```

Run it:

```bash
godml run -f godml.yml
```

---

## Notebook API

For interactive work in Jupyter:

```python
from godml import GodmlNotebook

nb = GodmlNotebook()
nb.load_data("./data/churn.csv", target="churn")
nb.train_model("xgboost", {"max_depth": 6, "n_estimators": 300})
nb.evaluate(["auc", "accuracy", "f1"])
nb.save_model("churn_v1")
```

### AI-powered advisor

```python
from godml.notebook_api import advisor_full_report, tune_model

# Get model + metric recommendations for your dataset
report = advisor_full_report(df, target="churn")
print(report["recommended_models"])   # ['xgboost', 'random_forest']
print(report["data_quality"])         # quality score + issues

# Auto-tune with Optuna
result = tune_model(
    model_type="xgboost",
    X=X_train, y=y_train,
    max_trials=50,
    metric="auc",
)
print(f"Best AUC: {result['best_score']:.4f}")
```

### Supported model types

| Key | Algorithm |
|-----|-----------|
| `xgboost` / `xgb` | XGBoost |
| `random_forest` / `rf` | scikit-learn RandomForest |
| `logistic_regression` / `logreg` | scikit-learn LogisticRegression |
| `lstm` | LSTM forecasting *(requires `[deep]`)* |

---

## Compliance

```python
from godml.compliance_service import PciDssCompliance, GdprCompliance

compliance = PciDssCompliance()
clean_df = compliance.apply(df)          # masks PAN, CVV, account numbers

gdpr = GdprCompliance()
report = gdpr.apply(df)                  # anonymizes PII per GDPR rules
```

Built-in compliance modules: `PCI-DSS`, `GDPR`, `HIPAA`, `SOX`.  
Custom rules: subclass `BaseCompliance` and implement `apply(df)`.

---

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                    GODML Framework                   │
├────────────────┬─────────────┬───────────────────────┤
│  Interfaces    │  Notebook   │  CLI  │  REST API      │
├────────────────┴─────────────┴───────────────────────┤
│  Core Services                                       │
│  ┌───────────┐ ┌───────────┐ ┌──────────────────────┐│
│  │ Advisor   │ │ Config    │ │ Pipeline Engine      ││
│  └───────────┘ └───────────┘ └──────────────────────┘│
├──────────────────────────────────────────────────────┤
│  ML Services                                         │
│  ┌───────────┐ ┌───────────┐ ┌──────────────────────┐│
│  │ DataPrep  │ │ Model     │ │ Monitoring           ││
│  │ +PII scan │ │ Registry  │ │ +Drift detection     ││
│  └───────────┘ └───────────┘ └──────────────────────┘│
├──────────────────────────────────────────────────────┤
│  Providers:  MLflow │ SageMaker │ Docker │ Local      │
└──────────────────────────────────────────────────────┘
```

---

## Supply chain & security

GODML ships with a **SLSA Level 3** supply chain — every release is built in an isolated GitHub Actions environment with unforgeable provenance.

| Artifact | Standard | Signature | Transparency |
|----------|----------|-----------|--------------|
| `sbom.spdx.json` | SPDX 2.3 | Cosign OIDC (keyless) | [Rekor log](https://search.sigstore.dev/?q=DAGMALIA) |
| `sbom.cyclonedx.json` | CycloneDX 1.6 | SLSA provenance | GitHub Release assets |
| `provenance.intoto.jsonl` | SLSA v1 / in-toto | slsa-github-generator | [Rekor log](https://search.sigstore.dev/?q=DAGMALIA) |

### Verify the SBOM yourself

```bash
# Download from GitHub Releases
cosign verify-blob \
  --bundle sbom.spdx.bundle \
  --certificate-identity-regexp "https://github.com/DAGMALIA/godml/.github/workflows/safety_scan.yml" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  sbom.spdx.json
```

### Verify SLSA provenance

```bash
slsa-verifier verify-artifact dist/godml-*.whl \
  --provenance-path provenance.intoto.jsonl \
  --source-uri github.com/DAGMALIA/godml \
  --source-tag v1.1.0
```

### CI security controls

| Control | Tool | Status |
|---------|------|--------|
| SAST | Bandit | ✅ Blocks on HIGH/CRITICAL |
| Dependency CVEs | pip-audit + Safety | ✅ Weekly + per PR |
| SHA-pinned actions | Dependabot | ✅ Auto-pinned |
| PyPI publish | OIDC Trusted Publisher | ✅ No API tokens |
| Branch protection | GitHub Ruleset | ✅ PR + status checks |
| Tag protection | GitHub Ruleset | ✅ `v*` immutable |
| Score | OpenSSF Scorecard | ✅ Published weekly |

---

## CLI reference

```bash
godml init <project>         # scaffold new project
godml run -f godml.yml       # execute pipeline from config
godml deploy <project> <env> # deploy model to environment
godml --version              # print version
```

---

## Roadmap

### v1.2.0 — Q3 2026
- [ ] Interactive drift dashboard (Streamlit)
- [ ] A/B testing framework
- [ ] Optuna distributed tuning

### v1.3.0 — Q4 2026
- [ ] Kubernetes operator
- [ ] Real-time streaming inference
- [ ] Multi-tenant model registry

### v2.0.0 — 2027
- [ ] Multi-cloud provider abstraction (Vertex AI, Azure ML)
- [ ] Federated learning support
- [ ] SOC2 / ISO27001 documentation kit

---

## Contributing

```bash
git clone https://github.com/DAGMALIA/godml.git
cd godml
pip install -e ".[dev]"
pytest tests/ --cov=godml
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for branch conventions and PR checklist.

---

## License

MIT — see [LICENSE](LICENSE).

---

<p align="center">
  Built by <a href="https://github.com/DAGMALIA">DAGMALIA</a> · 
  <a href="https://pypi.org/project/godml/">PyPI</a> · 
  <a href="mailto:agtzrubio@dagmalia.com">Support</a>
</p>
