Metadata-Version: 2.4
Name: catml
Version: 0.9.0rc1
Summary: The Agent-Native AutoML Engine for Humans and AI Agents
Author: Jfenic
Maintainer: Jfenic
License-Expression: Apache-2.0
Project-URL: Homepage, https://catml.vercel.app
Project-URL: Repository, https://github.com/Jfenic/catml
Project-URL: Issues, https://github.com/Jfenic/catml/issues
Project-URL: Documentation, https://github.com/Jfenic/catml#readme
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
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: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: optuna>=3.0
Requires-Dist: scipy>=1.10
Requires-Dist: joblib>=1.3
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: wheel>=0.40; extra == "dev"
Requires-Dist: pyarrow>=14.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"
Provides-Extra: agents
Requires-Dist: langgraph>=0.2.0; extra == "agents"
Requires-Dist: langgraph-checkpoint>=2.0.0; extra == "agents"
Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0; extra == "agents"
Provides-Extra: models
Requires-Dist: catboost>=1.2; extra == "models"
Requires-Dist: lightgbm>=4.0; extra == "models"
Requires-Dist: xgboost>=2.0; extra == "models"
Provides-Extra: vision
Requires-Dist: torch>=2.0; extra == "vision"
Requires-Dist: torchvision>=0.15; extra == "vision"
Requires-Dist: timm>=0.9; extra == "vision"
Requires-Dist: pillow>=9.0; extra == "vision"
Provides-Extra: parquet
Requires-Dist: pyarrow>=14.0; extra == "parquet"
Provides-Extra: all
Requires-Dist: catml[agents,mcp,models,parquet,vision]; extra == "all"
Dynamic: license-file

# CATML

> **AutoML you can trust an AI agent to operate.**  
> Local-first AutoML with automatic leakage protection, reproducible experiments, and controlled AI agent access.

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/Version-0.9.0--rc1-blue.svg)](src/automl/__init__.py)
[![CI](https://github.com/Jfenic/catml/actions/workflows/ci.yml/badge.svg)](https://github.com/Jfenic/catml/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/badge/Tests-788%20Collected-brightgreen.svg)](https://github.com/Jfenic/catml/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/Coverage-%E2%89%A585%25%20(CI%20gate)-brightgreen.svg)](https://github.com/Jfenic/catml/actions/workflows/ci.yml)
[![Architecture](https://img.shields.io/badge/Architecture-Hexagonal%20%2B%20CQRS-orange.svg)](ARCHITECTURE.md)
[![MCP](https://img.shields.io/badge/MCP-Ready-purple.svg)](src/automl/interfaces/mcp/)

---

## Why CATML?

Most AutoML platforms (AutoGluon, H2O, FLAML, PyCaret) are monolithic libraries or proprietary cloud silos designed before the rise of autonomous AI coding agents. 

CATML is engineered from the ground up with **five distinct advantages**:

1. **Fail-Safe Anti-Leakage Guardian:** Automatically detects target leakage, group leakage, and pseudo-identifiers before training. Contaminated columns are automatically excluded by default.
2. **Agent-Native by Design (MCP Server):** Native Model Context Protocol (MCP) dual transport (stdio/HTTP) enables external AI agents (Claude, Cursor, OpenAI) to discover features, run trials, and explore hypotheses within budget-aware leases and cooperative cancellation controls.
3. **3-Line Ergonomics & Reproducibility:** Simple, scikit-learn compatible facade (`AutoML(random_state=42).fit(df, target="churn")`) over the same CQRS/hexagonal stages used by CLI and agents—not a separate monolithic engine.
4. **Portable Artifacts (Database-Free Inference Runtime):** Winning models serialize into `model.pkl` + `.sha256` sidecars for workspace-independent inference. Runtime still needs compatible scientific Python stacks (see security note below)—not a zero-dependency binary.
5. **Local-First by Default:** Workbench and MCP bind to `127.0.0.1` by default, confine filesystem access to the workspace, and keep an SQLite ledger locally. CATML does not phone home or upload dataset rows. Optional extras (vision weight downloads, remote LLM endpoints) may use the network when you enable them. Workbench UI chrome (Tailwind, Chart.js, Lucide, fonts) is vendored offline in the wheel.

---

## Quickstart (Python API)

Works after `pip install catml` with no repository checkout (uses a built-in scikit-learn dataset):

```python
from sklearn.datasets import load_breast_cancer
from catml import AutoML, ModelArtifact

# 1. Any tabular DataFrame with a target column
df = load_breast_cancer(as_frame=True).frame

# 2. Fit candidate models with automatic leakage protection & reproducible seed
automl = AutoML(metric="roc_auc", random_state=42)
result = automl.fit(df, target="target")

# 3. View the experiment leaderboard
print(result.leaderboard())

# 4. Save portable winning model for production inference
result.save_model("model.pkl")

# 5. Load and predict (workspace-independent; requires matching scientific deps)
model = ModelArtifact.load("model.pkl")
predictions = model.predict(df.head(5))
probabilities = model.predict_proba(df.head(5))
```

CSV examples under `examples/data/` ship with the **Git repository**, not the PyPI wheel.

> **Public API note:** Install/import the distribution as `catml`. The implementation package remains `automl` for CQRS modules (`from automl.application...`). See [`ARCHITECTURE.md`](ARCHITECTURE.md).

> [!WARNING]
> **Model Artifact Deserialization Security:** Never load `.pkl` / `joblib` artifacts received from untrusted third parties. Deserialization can execute arbitrary code. Companion `.sha256` checksums detect accidental corruption only—not authenticity. Artifacts embed dependency version manifests; keep scikit-learn/numpy/pandas aligned with training. HMAC/PKI signatures and ONNX export are on the hardening roadmap ([`SECURITY.md`](SECURITY.md), [`docs/trusted-deployment.md`](docs/trusted-deployment.md)).

---

## Quickstart (Command Line)

```bash
# After cloning the repo (examples/ is not inside the wheel):
catml fit examples/data/customers_churn.csv --target churn

# Or point at any local CSV after pip install:
catml fit data.csv --target churn --models logistic_regression,random_forest --json
```

Example output (illustrative scores; `lightgbm` requires the optional `catml[models]` extra):
```text
=================================================================
  CATML Automated Machine Learning (Platform 0.9.0-rc1)
=================================================================
  Dataset:     examples/data/customers_churn.csv
  Target:      churn
  Candidates:  logistic_regression, random_forest, lightgbm

  Evaluating candidate models and tuning...

  Leaderboard:
  ------------------------------------------------------------
  Rank  Model                   Metric      Score     Time (s)  
  ------------------------------------------------------------
  1     lightgbm                roc_auc     0.8924    0.28      
  2     random_forest           roc_auc     0.8750    0.16      
  3     logistic_regression     roc_auc     0.8512    0.12      
  ------------------------------------------------------------

  ✓ Best Model:   lightgbm (roc_auc: 0.8924)
  ✓ Model Saved:  /home/user/project/catml-runs/model.pkl
  ✓ Run in Prod:  ModelArtifact.load("catml-runs/model.pkl")
=================================================================
```

---

## Interactive Web Workbench (Visual ML Lab)

CATML includes a built-in interactive Tech Minimalista Premium visual dashboard for monitoring runs, inspecting datasets, and managing experiments:

```bash
catml ui --port 8080 --workspace .automl/default
```

Defaults to **`127.0.0.1`**. Binding a non-loopback host requires an auth token (fail-closed). Open **[http://127.0.0.1:8080](http://127.0.0.1:8080)** to access:
- **Mission Control Overview:** Live experiment status and resource telemetry.
- **Dataset Inspector:** Deep statistical profiling, cardinality detection, and feature recommendations.
- **Visual Experiment Studio:** Interactive comparison diffs, HPO trial history, and model explainability.
- **Persistent Job Queue:** Resilient SQLite worker with pause, resume, and cooperative cancellation.

> **Network note:** Training and dataset rows stay local. Workbench UI chrome is served from packaged `/static/vendor/*` and `/static/css/tailwind.built.css` (no browser CDN). Rebuild vendored assets with `bash scripts/vendor_workbench_assets.sh` when bumping Chart.js/Lucide/Tailwind/fonts.

---

## Agentic Protocol: Model Context Protocol (MCP)

CATML exposes AutoML capabilities to LLMs via MCP. Install the extra first:

```bash
pip install -e ".[mcp]"   # or: pip install "catml[mcp]"
```

### Connect to Claude Desktop or Cursor

Add CATML to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "catml": {
      "command": "catml",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}
```

Or start the streamable HTTP transport (loopback by default; remote bind requires a token):

```bash
catml mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

Available tools exposed to AI agents:
- `get_dataset_profile`: Deep statistical profiling and column cardinality.
- `list_models` / `list_plugins`: Inspect available algorithms and metric plugins.
- `create_experiment`: Propose targeted hypothesis-driven experiment runs.
- `get_leaderboard`: Inspect ranked metric scores and cross-validation variance.
- `cancel_operation`: Cooperative cancellation under budget constraints.

---

## Installation

```bash
# Clone the repository
git clone https://github.com/Jfenic/catml.git
cd CATML

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode (tests + parquet helpers)
pip install -e ".[dev]"

# MCP / agent extras are optional — install when you need those surfaces:
pip install -e ".[mcp,agents]"
```

### Optional Modality & Agentic Extensions

```bash
# Gradient boosting backends (LightGBM, XGBoost, CatBoost)
pip install "catml[models]"

# Deep learning vision representations (PyTorch, torchvision, timm, Pillow)
pip install "catml[vision]"

# MCP server SDK and LangGraph agent orchestration
pip install "catml[mcp]"
pip install "catml[agents]"

# Full stack with all extensions
pip install "catml[all]"
```

> [!NOTE]
> **Local-First & Offline Environments:** CATML executes completely local-first without transmitting dataset rows to external cloud services. However, when using deep neural vision backbones (`resnet18`, etc.), TorchVision downloads pretrained weights upon first execution if not already cached. For strictly offline or air-gapped environments, pre-populate the PyTorch cache directory (`~/.cache/torch/hub/checkpoints`).

---

## Advanced Architecture (CQRS Application Bus)

For power users, MLOps pipelines, and custom orchestrators, CATML provides strict CQRS separation via `CommandBus` and `QueryBus`:

```python
from automl.application.bootstrap import build_application
from automl.application.commands.workspace_commands import (
    PlanExperimentsCommand,
    RunScheduledExperimentsCommand,
)
from automl.application.queries.workspace_queries import GetLeaderboardQuery

# Build application workspace
ws, cmd, qry = build_application(root_dir=".automl/demo")

# Register dataset and create run
dataset = ws.register_dataset(
    name="churn",
    path="examples/data/customers_churn.csv",
    target="churn",
)
run = ws.create_run(dataset)

# Dispatch CQRS commands
cmd.dispatch(PlanExperimentsCommand(run_id=run.id))
cmd.dispatch(RunScheduledExperimentsCommand(run_id=run.id, max_experiments=3))

# Dispatch zero-side-effect queries
leaderboard = qry.dispatch(GetLeaderboardQuery(run.id))
for entry in leaderboard:
    print(f"{entry['model_id']}: {entry['metric']} = {entry['score']:.4f}")
```

---

## How to Test

```bash
# Run all unit and integration tests
pytest

# Run tests with strict coverage validation (>= 85%)
pytest --cov=src/automl --cov-fail-under=85
```

---

## Capabilities & Modality Status

| Modality / Workflow | Status | Details |
|---|---|---|
| **Tabular Classification & Regression** | **Stable** | LightGBM, XGBoost, CatBoost, Scikit-learn, Voting Ensembles, N-Model OOF Blending, Level-2 Stacking, Temporal Dynamics, and Group Anti-Leakage. |
| **Text Representations (NLP)** | **Available** | Sublinear TF-IDF n-gram extractor with automated `is_text_column` discovery and multimodal column fusion. |
| **Image Representations (Vision)** | **Available** | Representation-level vision with PyTorch/torchvision backbone (`catml[vision]`, feature extractor + downstream estimators), deterministic hash encoder (testing/benchmarks fallback), image path discovery, and gallery preview in Workbench. |
| **Agent Governance (MCP & LangGraph)** | **Available** | Native Model Context Protocol (stdio/HTTP), LangGraph StateGraph orchestrator, persistent SQLite ledger, human approval flow, and token auditing. |
| **Native Vision (Detection / Segmentation)** | *Roadmap* | Planned for future v1.x with specialized deep learning backends. |
| **Biomedical Extensions (`catml[medical]`)** | *Roadmap* | Planned extension for DICOM/NIfTI with strict zero data egress. |

---

## Documentation Navigation

- **System Architecture & Hexagonal Rules:** [`ARCHITECTURE.md`](ARCHITECTURE.md)
- **Technical Specification & Roadmap (historical):** [`docs/AutoML_Arquitectura_Tecnica.md`](docs/AutoML_Arquitectura_Tecnica.md)
- **Active Tasks & Operational Backlog:** [`TASKS.md`](TASKS.md)
- **Agent Rules & Development Guidelines:** [`AGENTS.md`](AGENTS.md)
- **Developer Extension Guide:** [`DEVELOPER_GUIDE.md`](DEVELOPER_GUIDE.md)
- **Feature Specifications & Plans:** [`docs/features/`](docs/features/)
- **Architectural Decision Records (ADRs):** [`docs/decisions/`](docs/decisions/)
- **Trusted Deployment & Threat Model:** [`docs/trusted-deployment.md`](docs/trusted-deployment.md)
- **Security Policy & Reporting:** [`SECURITY.md`](SECURITY.md)
- **Code of Conduct:** [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)

---

## License
 
Starting with version 0.8.0, CATML is licensed under the Apache License, Version 2.0 - see the [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) files for details. Earlier releases (<= 0.7.0) remain available under the MIT License.

Third-party Workbench libraries and fonts (Chart.js, Lucide, Tailwind CSS output, Geist, IBM Plex Mono) and Python dependencies are documented in [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md). Full texts for vendored UI assets ship in the package under `automl/interfaces/web/static/vendor/licenses/`.
