mlcompass

CLI komutu

0/200

kullanıcıya ulaşan halüsinasyon

v0.9

PyPI'da canlı

MIT

açık kaynak

Proje Özeti

ML ekosisteminde harika araçlar var — ama her biri pipeline'ın tek bir dilimine sahip ve hiçbiri tavsiye vermez: profiling kütüphaneleri (pandas-profiling) veriye bakar ama hedef kolonu kavramı yoktur; deney izleyicileri (W&B, TensorBoard) metrik kaydeder ama yorumlamaz; kod asistanları (Cursor, Copilot) sözdizimine bakar ama ML'e özgü semantik hatayı görmez. mlcompass bu boşluğu doldurur: veriden üretime kadar projenizi takip eden, her adımda bağlamı koruyan tek bir advisory katmanı.

Her komut paylaşılan bir proje bağlamına (.mlcompass/) yazar ve oradan okur — yani deploy aşamasına geldiğinizde araç datasetinizi, model seçiminizi, eğitim geçmişinizi ve değerlendirme sonuçlarınızı çoktan biliyordur. Bu, mlcompass'ı bir sohbet aracından fazlası yapan şey: .git/ ruhunda, kalıcı proje hafızası.

Bitirme Projesi olarak geliştirildi; PyPI'da v0.9.0 ile canlı, MIT lisanslı, Python 3.10–3.13 destekli. Kendi yazdığım agentlite kütüphanesi üzerine kuruludur.

Pipeline — Veriden Üretime

On bir komut ML pipeline'ının her aşamasını kapsar. init, status ve agent dışındaki her komutun tamamen deterministik bir varsayılan yolu vardır; isteğe bağlı --llm bayrağı bunun üzerine bir Claude yorum katmanı ekler.

data.csv train.py iki run results.csv üretim │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ advise ───► audit ───► compare ───► evaluate ───► deploy watch │ init · status · agent · monitor · optimize (her aşamada)

Öne Çıkan Katkı — Anti-Halüsinasyon Kontratı

mlcompass'ın araştırma katkısı burada. Bir LLM bir aracın yapılandırılmış çıktısını anlatırken uydurabilir: veride olmayan bir kolon adı, ölçülmemiş bir değer, kanıtı çelişen bir sayı söyleyebilir. evaluate şüpheli derecede iyi bir metrik gördüğünde (AUC > 0.995, R² > 0.999 — veri sızıntısının klasik imzası) kanıt-bağlı bir kontrat devreye girer:

$ mlcompass evaluate predictions.csv

⚠  Şüpheli derecede yüksek R² (1.0000)

┌──── 🔬 Sızıntı incelemesi — kanıt ──────────┐
│ Aday sızıntı kolonu: log_price              │
│ ŷ == y eşleşme oranı: %0.9                   │
│ log_price        r=+1.0000 (spearman)       │
└─────────────────────────────────────────────┘

Kontrat iki katmanlıdır. Tier A: anlatıcının araç-şemasındaki enum alanları çağrı anında deterministik kanıt sözlüğünden üretilir — model sadece var olan kolonları seçebilir. Tier B: dönen cevap düz kodla, sağlayıcıya güvenmeden doğrulanır (varlık sağlamlığı, değer sağlamlığı, tamlık); ihlal varsa düzeltici yeniden-deneme, kalırsa uydurma içerik kırpılır. Sonuç sağlayıcıdan bağımsız bir garanti: döndürülen her kolon ve her sayı kanıtta mevcuttur ve ona eşittir.

Canlı ölçümde (hücre başına N = 200) çıplak anlatıcı kanıtı aynı kalsa bile aynı talimatın altı farklı yeniden-ifadesinde %1 ile %100 arası uydurma yaptı; kontrat ise her iki görevin tüm kanallarında kullanıcıya ulaşan oranı 0/200'de tuttu. Bu çalışmayı anlatan akademik bir makale (kanıt-bağlı runtime şeması) hazırlık/değerlendirme aşamasındadır.

On Bir Komut

Komut	Ne zaman	Ne verir
`init`	Yeni proje	Kararları izleyen `.mlcompass/` klasörü
`advise`	CSV var, şimdi ne?	Denenecek modeller, türetilecek feature'lar, tuzaklar
`audit`	Eğitimden önce	Eğitim scriptinin statik analizi (8 AST kuralı)
`watch`	Eğitim sürerken	Plateau / overfit / NaN / divergence (log / TB / W&B)
`compare`	Birkaç run sonrası	Yan yana config + final-metrik farkı + hüküm
`evaluate`	Eğitim bitti	Metrikler, eşik taraması, sızıntı incelemesi
`deploy`	Üretime çıkış	Model + bağımlılık + hedefe-özel kontroller + checklist
`status`	Her an	Proje metaverisi, aktif durum, karar geçmişi
`agent`	"Sen hallet"	Diğer araçları süren LLM router'ı, hafızalı
`monitor`	Model canlı, yeni veri	PSI + KS + chi² drift, retrain hükmü
`optimize`	Birkaç run var, sıra?	HPO alt-agent'ı: leaderboard, hassasiyet, N öneri

Claude Desktop / Cursor'dan Kullanım (MCP)

mlcompass bir Model Context Protocol sunucusu ile gelir; MCP-uyumlu herhangi bir istemci (Claude Desktop, Claude Code, Cursor, Continue …) sekiz aracını doğrudan çağırabilir. Ayrıca pip install mlcompass on bir hazır Claude Code slash komutu gönderir — tek mlcompass install-slash-commands ile /mlc-advise, /mlc-evaluate, /mlc-leak … birer tuş vuruşuna dönüşür.

$ pip install "mlcompass[mcp]"

# claude_desktop_config.json
{
  "mcpServers": {
    "mlcompass": { "command": "mlcompass-mcp" }
  }
}

Kendi Kendini Süren Agent (CLI)

Claude Desktop'ta değilken — CI koşuları, cron, bir GPU kutusunda ssh — bir agent aynı sekiz aracı terminalden sürebilir. Her muhtemel mutasyon öncesi izin sorar (agentlite'ın izin sistemi birinci sınıf), her adımı transcript'e yazar.

$ pip install "mlcompass[agent]"
$ export ANTHROPIC_API_KEY="sk-ant-..."

$ mlcompass agent "data.csv'im var, beni model önerisine kadar götür"

Neden mlcompass

	pandas-profiling	W&B / TB	Cursor / Devin	mlcompass
Ham veriyi analiz	✅	❌	❌	✅
Model + feature önerir	❌	❌	kısmi	✅
Eğitim scriptini denetler	❌	❌	reaktif	✅
Proaktif teşhis	❌	❌	reaktif	✅
Kalıcı proje hafızası	❌	run başına	❌	✅
İzin-kapılı eylemler	❌	❌	kısmi	birinci sınıf

mlcompass bu araçların yerine geçmez — hepsinin yanında duran advisor'dır.

Teknik Yığın

Dil: Python 3.10–3.13
Çekirdek: pandas (deterministik analiz) + agentlite (LLM agent katmanı)
Analiz: komut başına saf analizör — pure pandas / pure AST / pure log parser
Arayüzler: CLI + MCP sunucusu (8 araç) + 11 Claude Code slash komutu
Agent backend: Anthropic API veya Claude Code (Claude Agent SDK)
Paket: src/ layout, pyproject.toml, PyPI'da mlcompass
Kalite: pytest, ruff, mypy (strict) — anti-halüsinasyon kontratı uçtan uca testli
Lisans: MIT