CATML

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

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):

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.

Quickstart (Command Line)

# 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):

=================================================================
  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:

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 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:

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

Connect to Claude Desktop or Cursor

Add CATML to your claude_desktop_config.json:

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

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

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

# 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

# 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]"

Advanced Architecture (CQRS Application Bus)

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

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

# 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

Documentation Navigation

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

License

Starting with version 0.8.0, CATML is licensed under the Apache License, Version 2.0 - see the LICENSE and 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. Full texts for vendored UI assets ship in the package under automl/interfaces/web/static/vendor/licenses/.