mlcompass 0.1.0__tar.gz

mlcompass-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hakan Sabunis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlcompass-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: mlcompass
+Version: 0.1.0
+Summary: An LLM agent that sits next to you through your whole ML pipeline
+Author-email: Hakan Sabunis <hakansabunis@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hakansabunis/mlcompass
+Project-URL: Repository, https://github.com/hakansabunis/mlcompass
+Project-URL: Issues, https://github.com/hakansabunis/mlcompass/issues
+Project-URL: Changelog, https://github.com/hakansabunis/mlcompass/blob/main/CHANGELOG.md
+Keywords: machine-learning,llm,agent,training,monitoring,claude,pytorch,tensorboard,wandb,mlops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agentlite-py>=0.2.0
+Requires-Dist: watchdog>=4.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pandas>=2.0.0
+Provides-Extra: tensorboard
+Requires-Dist: tbparse>=0.0.7; extra == "tensorboard"
+Provides-Extra: wandb
+Requires-Dist: wandb>=0.16.0; extra == "wandb"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: tbparse>=0.0.7; extra == "dev"
+Dynamic: license-file
+
+# mlcompass
+
+> An LLM agent that sits next to you through your whole ML pipeline —
+> from data, through training, all the way to deployment.
+
+[![PyPI](https://img.shields.io/pypi/v/mlcompass.svg)](https://pypi.org/project/mlcompass/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+🚧 **Pre-alpha (v0.0.1)** — under active development. APIs will change before v0.1.
+
+## What it does
+
+mlcompass is a single CLI that follows your ML project from start
+to finish, keeping context across every step.
+
+```
+data.csv          train.py             results.csv         production
+   │                  │                     │                  │
+   ▼                  ▼                     ▼                  ▼
+ advise   ────►   audit + watch  ────►  evaluate  ────►  deploy
+                      compare
+```
+
+Each command writes to and reads from a shared project context
+(`.mlcompass/`), so by the time you reach `deploy`, the tool already
+knows your dataset, your model choice, your training history, and
+your evaluation results.
+
+## Six commands, one tool
+
+| Command    | When you run it                          | What you get                                          |
+| ---------- | ---------------------------------------- | ----------------------------------------------------- |
+| `init`     | Starting a new project                   | A `.mlcompass/` folder that tracks decisions          |
+| `advise`   | You have a CSV, what now?                | Models to try, features to derive, pitfalls to avoid  |
+| `audit`    | Before you press train                   | Static analysis of training script (seed, val, etc.)  |
+| `watch`    | While training runs                      | Live plateau / overfit / NaN detection                |
+| `compare`  | After several runs                       | Hypothesis-driven diff between two runs               |
+| `evaluate` | Training done                            | Threshold tuning, confusion matrix, hard examples     |
+| `deploy`   | Going to production                      | Latency estimate, dependency check, ONNX advice       |
+
+## Quick example — `advise` mode
+
+```bash
+mlcompass init churn-project
+mlcompass advise data/customers.csv --target churn
+```
+
+Output:
+
+```
+📊 Dataset analysis (data/customers.csv)
+   • 10,000 rows × 23 columns
+   • Target: churn (binary, 12% positive)
+   • 4 categorical, 18 numerical, 1 datetime
+   • 3 columns with >50% missing values (consider dropping)
+
+💡 Recommended models
+   1. XGBoost / LightGBM   → tabular binary baseline
+                             expected AUC: 0.82 – 0.87
+   2. Logistic Regression  → interpretable baseline
+                             expected AUC: 0.76 – 0.80
+   3. FT-Transformer       → if GPU budget allows
+                             expected AUC: 0.83 – 0.86
+
+🔧 Suggested feature engineering
+   • signup_date → derive days_since_signup, month, dayofweek
+   • income (3 outliers >3σ) → winsorize at 99th percentile
+   • country (47 categories) → target encoding or top-N
+
+⚠️  Class imbalance (12% positive)
+   • Don't optimize accuracy — use AUC, F1, or recall@k
+   • Consider class_weight='balanced' or focal loss
+
+Generate a baseline notebook? [y/N]
+```
+
+## Quick example — `watch` mode (Faz 2)
+
+```bash
+mlcompass watch train.py
+```
+
+After 8 epochs:
+
+```
+⚠️  Epoch 8 — overfitting detected
+   Train loss: 0.118  |  Val loss: 0.387  (gap 0.27, normal <0.1)
+
+   Likely cause: regularization is too weak for the model capacity.
+
+   Suggested fix: increase dropout 0.1 → 0.3
+   Apply and restart training? [y/N]
+```
+
+## Why mlcompass
+
+The ML ecosystem already has great tools — but each owns one slice
+of the pipeline, and none of them advise:
+
+|                                 | pandas-profiling | W&B / TensorBoard | Cursor / Devin | **mlcompass** |
+| ------------------------------- | :--------------: | :---------------: | :------------: | :------------: |
+| Analyzes raw data               |        ✅        |         ❌        |       ❌       |       ✅       |
+| Recommends models + features    |        ❌        |         ❌        |     partial    |       ✅       |
+| Audits training scripts         |        ❌        |         ❌        |     reactive   |       ✅       |
+| Watches training in real time   |        ❌        |    dashboard      |       ❌       |       ✅       |
+| Diagnoses problems proactively  |        ❌        |         ❌        |     reactive   |       ✅       |
+| Post-training evaluation advice |        ❌        |       basic       |       ❌       |       ✅       |
+| Deployment readiness check      |        ❌        |         ❌        |       ❌       |       ✅       |
+| Persistent project memory       |        ❌        |    per-run        |       ❌       |       ✅       |
+| Permission-gated actions        |        ❌        |         ❌        |     partial    |   first-class  |
+
+mlcompass is the **advisor that sits next to all of these tools** —
+not a replacement for any.
+
+## Install
+
+```bash
+pip install mlcompass
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+## Usage
+
+```bash
+# Start a project
+mlcompass init my-project
+
+# Pre-training
+mlcompass advise data.csv --target label
+
+# Training-time          (Faz 2)
+mlcompass audit train.py
+mlcompass watch train.py
+mlcompass compare run-3 run-7
+
+# Post-training          (Faz 3)
+mlcompass evaluate results.csv
+
+# Deployment             (Faz 4)
+mlcompass deploy --target sagemaker
+```
+
+## How it works
+
+Built on [agentlite](https://github.com/hakansabunis/agentlite) — a
+small Claude agent library — mlcompass uses one orchestrator agent
+per command, plus focused sub-agents for sub-tasks:
+
+```
+       cli.py
+         │
+   ┌─────┴─────┐
+   ▼           ▼
+ advise      watch                ... deploy
+ agent       agent
+   │           │
+   ▼           ▼
+ ModelAdvisor  MetricsWatcher (Haiku, polls)
+  (Opus)       Diagnostician  (Opus, called on anomaly)
+```
+
+Every action that would modify your code, config, or run a training
+process **asks permission first** — agentlite's permission system is
+first-class, not an afterthought.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design.
+
+## Project context
+
+Each mlcompass project keeps a small folder, similar in spirit to
+`.git/`:
+
+```
+.mlcompass/
+├── project.yaml        # metadata
+├── context.json        # decisions, recommendations, active state
+├── datasets/           # registered datasets
+└── runs/               # training run history
+```
+
+This is what makes mlcompass more than a chat tool: by the time you
+run `deploy`, every earlier decision is still in memory.
+
+## Roadmap
+
+| Phase           | Commands                              |  Status       |
+| --------------- | ------------------------------------- | :-----------: |
+| **Faz 1 (v0.1)**| `init`, `advise`                      | 🚧 In progress |
+| **Faz 2 (v0.2)**| `audit`, `watch`, `compare`           | 📅 Planned    |
+| **Faz 3 (v0.3)**| `evaluate`                            | 📅 Planned    |
+| **Faz 4 (v0.4)**| `deploy`                              | 📅 Planned    |
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed plans and
+[ARCHITECTURE.md](ARCHITECTURE.md) for the design.
+
+## Non-goals
+
+To stay focused, mlcompass will **not** try to be:
+
+- **AutoML** (use AutoGluon, AutoSklearn)
+- **Experiment tracker** (use MLflow, W&B)
+- **Code assistant** (use Cursor, Copilot, aider)
+- **Monitoring dashboard** (use Grafana, Streamlit)
+
+mlcompass **advises**; you decide.
+
+## Contributing
+
+Pre-alpha — issues and discussions welcome, PRs after v0.1.
+
+## License
+
+MIT © 2026 Hakan Sabunis

mlcompass-0.1.0/README.md

@@ -0,0 +1,214 @@
+# mlcompass
+
+> An LLM agent that sits next to you through your whole ML pipeline —
+> from data, through training, all the way to deployment.
+
+[![PyPI](https://img.shields.io/pypi/v/mlcompass.svg)](https://pypi.org/project/mlcompass/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+🚧 **Pre-alpha (v0.0.1)** — under active development. APIs will change before v0.1.
+
+## What it does
+
+mlcompass is a single CLI that follows your ML project from start
+to finish, keeping context across every step.
+
+```
+data.csv          train.py             results.csv         production
+   │                  │                     │                  │
+   ▼                  ▼                     ▼                  ▼
+ advise   ────►   audit + watch  ────►  evaluate  ────►  deploy
+                      compare
+```
+
+Each command writes to and reads from a shared project context
+(`.mlcompass/`), so by the time you reach `deploy`, the tool already
+knows your dataset, your model choice, your training history, and
+your evaluation results.
+
+## Six commands, one tool
+
+| Command    | When you run it                          | What you get                                          |
+| ---------- | ---------------------------------------- | ----------------------------------------------------- |
+| `init`     | Starting a new project                   | A `.mlcompass/` folder that tracks decisions          |
+| `advise`   | You have a CSV, what now?                | Models to try, features to derive, pitfalls to avoid  |
+| `audit`    | Before you press train                   | Static analysis of training script (seed, val, etc.)  |
+| `watch`    | While training runs                      | Live plateau / overfit / NaN detection                |
+| `compare`  | After several runs                       | Hypothesis-driven diff between two runs               |
+| `evaluate` | Training done                            | Threshold tuning, confusion matrix, hard examples     |
+| `deploy`   | Going to production                      | Latency estimate, dependency check, ONNX advice       |
+
+## Quick example — `advise` mode
+
+```bash
+mlcompass init churn-project
+mlcompass advise data/customers.csv --target churn
+```
+
+Output:
+
+```
+📊 Dataset analysis (data/customers.csv)
+   • 10,000 rows × 23 columns
+   • Target: churn (binary, 12% positive)
+   • 4 categorical, 18 numerical, 1 datetime
+   • 3 columns with >50% missing values (consider dropping)
+
+💡 Recommended models
+   1. XGBoost / LightGBM   → tabular binary baseline
+                             expected AUC: 0.82 – 0.87
+   2. Logistic Regression  → interpretable baseline
+                             expected AUC: 0.76 – 0.80
+   3. FT-Transformer       → if GPU budget allows
+                             expected AUC: 0.83 – 0.86
+
+🔧 Suggested feature engineering
+   • signup_date → derive days_since_signup, month, dayofweek
+   • income (3 outliers >3σ) → winsorize at 99th percentile
+   • country (47 categories) → target encoding or top-N
+
+⚠️  Class imbalance (12% positive)
+   • Don't optimize accuracy — use AUC, F1, or recall@k
+   • Consider class_weight='balanced' or focal loss
+
+Generate a baseline notebook? [y/N]
+```
+
+## Quick example — `watch` mode (Faz 2)
+
+```bash
+mlcompass watch train.py
+```
+
+After 8 epochs:
+
+```
+⚠️  Epoch 8 — overfitting detected
+   Train loss: 0.118  |  Val loss: 0.387  (gap 0.27, normal <0.1)
+
+   Likely cause: regularization is too weak for the model capacity.
+
+   Suggested fix: increase dropout 0.1 → 0.3
+   Apply and restart training? [y/N]
+```
+
+## Why mlcompass
+
+The ML ecosystem already has great tools — but each owns one slice
+of the pipeline, and none of them advise:
+
+|                                 | pandas-profiling | W&B / TensorBoard | Cursor / Devin | **mlcompass** |
+| ------------------------------- | :--------------: | :---------------: | :------------: | :------------: |
+| Analyzes raw data               |        ✅        |         ❌        |       ❌       |       ✅       |
+| Recommends models + features    |        ❌        |         ❌        |     partial    |       ✅       |
+| Audits training scripts         |        ❌        |         ❌        |     reactive   |       ✅       |
+| Watches training in real time   |        ❌        |    dashboard      |       ❌       |       ✅       |
+| Diagnoses problems proactively  |        ❌        |         ❌        |     reactive   |       ✅       |
+| Post-training evaluation advice |        ❌        |       basic       |       ❌       |       ✅       |
+| Deployment readiness check      |        ❌        |         ❌        |       ❌       |       ✅       |
+| Persistent project memory       |        ❌        |    per-run        |       ❌       |       ✅       |
+| Permission-gated actions        |        ❌        |         ❌        |     partial    |   first-class  |
+
+mlcompass is the **advisor that sits next to all of these tools** —
+not a replacement for any.
+
+## Install
+
+```bash
+pip install mlcompass
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+## Usage
+
+```bash
+# Start a project
+mlcompass init my-project
+
+# Pre-training
+mlcompass advise data.csv --target label
+
+# Training-time          (Faz 2)
+mlcompass audit train.py
+mlcompass watch train.py
+mlcompass compare run-3 run-7
+
+# Post-training          (Faz 3)
+mlcompass evaluate results.csv
+
+# Deployment             (Faz 4)
+mlcompass deploy --target sagemaker
+```
+
+## How it works
+
+Built on [agentlite](https://github.com/hakansabunis/agentlite) — a
+small Claude agent library — mlcompass uses one orchestrator agent
+per command, plus focused sub-agents for sub-tasks:
+
+```
+       cli.py
+         │
+   ┌─────┴─────┐
+   ▼           ▼
+ advise      watch                ... deploy
+ agent       agent
+   │           │
+   ▼           ▼
+ ModelAdvisor  MetricsWatcher (Haiku, polls)
+  (Opus)       Diagnostician  (Opus, called on anomaly)
+```
+
+Every action that would modify your code, config, or run a training
+process **asks permission first** — agentlite's permission system is
+first-class, not an afterthought.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design.
+
+## Project context
+
+Each mlcompass project keeps a small folder, similar in spirit to
+`.git/`:
+
+```
+.mlcompass/
+├── project.yaml        # metadata
+├── context.json        # decisions, recommendations, active state
+├── datasets/           # registered datasets
+└── runs/               # training run history
+```
+
+This is what makes mlcompass more than a chat tool: by the time you
+run `deploy`, every earlier decision is still in memory.
+
+## Roadmap
+
+| Phase           | Commands                              |  Status       |
+| --------------- | ------------------------------------- | :-----------: |
+| **Faz 1 (v0.1)**| `init`, `advise`                      | 🚧 In progress |
+| **Faz 2 (v0.2)**| `audit`, `watch`, `compare`           | 📅 Planned    |
+| **Faz 3 (v0.3)**| `evaluate`                            | 📅 Planned    |
+| **Faz 4 (v0.4)**| `deploy`                              | 📅 Planned    |
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed plans and
+[ARCHITECTURE.md](ARCHITECTURE.md) for the design.
+
+## Non-goals
+
+To stay focused, mlcompass will **not** try to be:
+
+- **AutoML** (use AutoGluon, AutoSklearn)
+- **Experiment tracker** (use MLflow, W&B)
+- **Code assistant** (use Cursor, Copilot, aider)
+- **Monitoring dashboard** (use Grafana, Streamlit)
+
+mlcompass **advises**; you decide.
+
+## Contributing
+
+Pre-alpha — issues and discussions welcome, PRs after v0.1.
+
+## License
+
+MIT © 2026 Hakan Sabunis

mlcompass-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "mlcompass"
+version = "0.1.0"
+description = "An LLM agent that sits next to you through your whole ML pipeline"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Hakan Sabunis", email = "hakansabunis@gmail.com" },
+]
+keywords = [
+    "machine-learning",
+    "llm",
+    "agent",
+    "training",
+    "monitoring",
+    "claude",
+    "pytorch",
+    "tensorboard",
+    "wandb",
+    "mlops",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+
+dependencies = [
+    "agentlite-py>=0.2.0",
+    "watchdog>=4.0.0",
+    "rich>=13.0.0",
+    "click>=8.0.0",
+    "pyyaml>=6.0",
+    "pandas>=2.0.0",
+]
+
+[project.optional-dependencies]
+tensorboard = ["tbparse>=0.0.7"]
+wandb = ["wandb>=0.16.0"]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "tbparse>=0.0.7",
+]
+
+[project.scripts]
+mlcompass = "mlcompass.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hakansabunis/mlcompass"
+Repository = "https://github.com/hakansabunis/mlcompass"
+Issues = "https://github.com/hakansabunis/mlcompass/issues"
+Changelog = "https://github.com/hakansabunis/mlcompass/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

mlcompass-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mlcompass-0.1.0/src/mlcompass/__init__.py

@@ -0,0 +1,3 @@
+"""mlcompass — An LLM agent that sits next to you through your whole ML pipeline."""
+
+__version__ = "0.1.0"

mlcompass-0.1.0/src/mlcompass/agents/__init__.py

@@ -0,0 +1,5 @@
+"""agentlite-based agents that drive each mlcompass command.
+
+Each module exposes one or more factory functions that return a
+configured ``agentlite.Agent`` ready to be used by the CLI.
+"""