vetcheck 0.1.0__py3-none-any.whl

vetcheck/__init__.py

@@ -0,0 +1,225 @@
+"""
+Vetcheck: Model health monitoring as veterinary care.
+
+In the working dog paradigm, dogs need regular checkups.
+This does the same for models.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from vetcheck.exam import ExamResult, run_physical_exam
+from vetcheck.drift import DriftReport, check_weight_drift
+from vetcheck.quarantine import QuarantineStatus, quarantine_model, release_model, get_quarantine_status
+
+__version__ = "0.1.0"
+__all__ = [
+    "VetCheck",
+    "ExamResult",
+    "DriftReport",
+    "QuarantineStatus",
+    "HealthStatus",
+    "HealthCertificate",
+]
+
+
+class HealthStatus(str, Enum):
+    """Overall health status of a model — like a vet's diagnosis."""
+    HEALTHY = "healthy"
+    UNDER_OBSERVATION = "under_observation"
+    QUARANTINED = "quarantined"
+    CRITICAL = "critical"
+
+
+@dataclass
+class HealthCertificate:
+    """A clean bill of health — like a health certificate from the vet."""
+    model_id: str
+    status: HealthStatus
+    issued_at: float
+    expires_at: float
+    last_exam_passed: bool
+    weight_stable: bool
+    quarantine_active: bool
+    notes: str = ""
+
+    def is_valid(self, now: float | None = None) -> bool:
+        """Check if this certificate is still within its expiry."""
+        now = now or time.time()
+        return now < self.expires_at
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model_id": self.model_id,
+            "status": self.status.value,
+            "issued_at": self.issued_at,
+            "expires_at": self.expires_at,
+            "last_exam_passed": self.last_exam_passed,
+            "weight_stable": self.weight_stable,
+            "quarantine_active": self.quarantine_active,
+            "notes": self.notes,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"HealthCertificate(model={self.model_id!r}, status={self.status.value}, "
+            f"valid_until={time.strftime('%Y-%m-%d %H:%M', time.gmtime(self.expires_at))} UTC)"
+        )
+
+
+class VetCheck:
+    """
+    The veterinarian for your models.
+
+    Usage:
+        vet = VetCheck(model_id="llama-3-70b")
+        report = vet.physical_exam()
+        drift = vet.weight_check()
+    """
+
+    def __init__(
+        self,
+        model_id: str,
+        baseline: list[dict[str, Any]] | None = None,
+        registry: dict[str, Any] | None = None,
+        exam_suite: list[dict[str, Any]] | None = None,
+        certificate_ttl: float = 86400.0,  # 24 hours
+    ):
+        self.model_id = model_id
+        self._baseline = baseline or []
+        self._registry = registry or {}
+        self._exam_suite = exam_suite or _default_exam_suite()
+        self._certificate_ttl = certificate_ttl
+        self._last_exam: ExamResult | None = None
+        self._last_drift: DriftReport | None = None
+
+    def physical_exam(self, suite: list[dict[str, Any]] | None = None) -> ExamResult:
+        """
+        Run a full physical exam — the regression test suite.
+
+        Each test is a vital sign check. Returns a full ExamResult
+        with pass/fail per test and an overall health assessment.
+        """
+        suite = suite or self._exam_suite
+        result = run_physical_exam(self.model_id, suite)
+        self._last_exam = result
+
+        # Auto-quarantine on critical failures
+        if result.critical_failures > 0:
+            self.quarantine(reason=f"Critical failures in physical exam: {result.critical_failures}")
+
+        return result
+
+    def weight_check(
+        self,
+        recent_outputs: list[dict[str, Any]] | None = None,
+        window: int = 100,
+        threshold: float = 0.05,
+    ) -> DriftReport:
+        """
+        Check for weight drift — output distribution shift over time.
+
+        Like weighing a dog at every visit, this compares recent
+        outputs against the baseline to detect statistically
+        significant drift.
+        """
+        recent = recent_outputs or self._baseline[-window:]
+        baseline = self._baseline[:window] if len(self._baseline) > window else self._baseline
+        report = check_weight_drift(self.model_id, baseline, recent, threshold=threshold)
+        self._last_drift = report
+        return report
+
+    def quarantine(self, reason: str) -> QuarantineStatus:
+        """
+        Quarantine a sick model — isolate it from production traffic.
+
+        The model stays in quarantine until a clean physical exam
+        passes and release() is explicitly called.
+        """
+        return quarantine_model(self.model_id, reason, registry=self._registry)
+
+    def release(self) -> QuarantineStatus:
+        """
+        Release a model from quarantine back to active duty.
+
+        Requires a recent, passing physical exam.
+        """
+        if self._last_exam and not self._last_exam.passed:
+            raise ValueError(
+                f"Cannot release {self.model_id}: last physical exam did not pass. "
+                "Run physical_exam() and ensure it passes before releasing."
+            )
+        return release_model(self.model_id, registry=self._registry)
+
+    @property
+    def status(self) -> HealthStatus:
+        """Current health status of the model."""
+        q = get_quarantine_status(self.model_id, registry=self._registry)
+        if q.is_quarantined:
+            return HealthStatus.QUARANTINED
+
+        if self._last_exam and not self._last_exam.passed:
+            return HealthStatus.CRITICAL
+
+        if self._last_drift and self._last_drift.is_significant:
+            return HealthStatus.UNDER_OBSERVATION
+
+        return HealthStatus.HEALTHY
+
+    def health_certificate(self, force: bool = False) -> HealthCertificate:
+        """
+        Issue a health certificate — a clean bill of health.
+
+        Verifies:
+        - Last physical exam passed
+        - No active quarantine
+        - Weight (drift) is stable
+
+        Raises ValueError if the model is not healthy unless force=True.
+        """
+        last_passed = self._last_exam is not None and self._last_exam.passed
+        weight_stable = self._last_drift is None or not self._last_drift.is_significant
+        q = get_quarantine_status(self.model_id, registry=self._registry)
+        quarantined = q.is_quarantined
+
+        if not force:
+            issues = []
+            if not last_passed:
+                issues.append("last physical exam did not pass (or no exam on record)")
+            if quarantined:
+                issues.append("model is under quarantine")
+            if not weight_stable:
+                issues.append("weight drift detected")
+            if issues:
+                raise ValueError(
+                    f"Cannot issue health certificate for {self.model_id}: "
+                    + "; ".join(issues)
+                )
+
+        now = time.time()
+        return HealthCertificate(
+            model_id=self.model_id,
+            status=self.status,
+            issued_at=now,
+            expires_at=now + self._certificate_ttl,
+            last_exam_passed=last_passed,
+            weight_stable=weight_stable,
+            quarantine_active=quarantined,
+            notes="Issued by Vetcheck" if last_passed and not quarantined else "Force-issued",
+        )
+
+
+def _default_exam_suite() -> list[dict[str, Any]]:
+    """Default vital signs checked during a physical exam."""
+    return [
+        {"name": "temperature", "description": "Edge case handling", "critical": True},
+        {"name": "heart_rate", "description": "Response latency within bounds", "critical": True},
+        {"name": "blood_pressure", "description": "Load handling without degradation", "critical": False},
+        {"name": "reflexes", "description": "Function calling and structured output", "critical": True},
+        {"name": "vision", "description": "Context window utilization", "critical": False},
+    ]

vetcheck/drift.py

@@ -0,0 +1,133 @@
+"""
+Drift module — output drift detection over time (weight monitoring).
+
+Like weighing a dog at every visit, this compares recent model
+outputs against an established baseline to detect statistically
+significant drift.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+try:
+    from statistics import mean, pstdev
+
+    _HAS_STATS = True
+except ImportError:
+    _HAS_STATS = False
+
+
+@dataclass
+class DriftReport:
+    """
+    Weight check results — drift report for a model.
+
+    Like a vet's weight log, tracking whether the model's
+    outputs have shifted from the baseline.
+    """
+    model_id: str
+    baseline_mean: float
+    recent_mean: float
+    drift_score: float
+    threshold: float
+    is_significant: bool
+    trend: str  # "stable", "increasing", "decreasing"
+    timestamp: float = field(default_factory=time.time)
+    sample_size: int = 0
+
+    def summary(self) -> str:
+        icon = "✅" if not self.is_significant else "⚖️"
+        return (
+            f"{icon} Weight Check for {self.model_id}\n"
+            f"   Baseline: {self.baseline_mean:.4f}\n"
+            f"   Recent:   {self.recent_mean:.4f}\n"
+            f"   Drift:    {self.drift_score:.4f} (threshold: {self.threshold:.4f})\n"
+            f"   Trend:    {self.trend}\n"
+            f"   Verdict:  {'SIGNIFICANT DRIFT' if self.is_significant else 'Within normal range'}"
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model_id": self.model_id,
+            "baseline_mean": self.baseline_mean,
+            "recent_mean": self.recent_mean,
+            "drift_score": self.drift_score,
+            "threshold": self.threshold,
+            "is_significant": self.is_significant,
+            "trend": self.trend,
+            "timestamp": self.timestamp,
+            "sample_size": self.sample_size,
+        }
+
+
+def _extract_metric(output: dict[str, Any], key: str = "score") -> float:
+    """Extract a numeric metric from an output dict."""
+    if key in output:
+        return float(output[key])
+    # Try common alternatives
+    for k in ("value", "metric", "confidence", "loss", "accuracy"):
+        if k in output:
+            return float(output[k])
+    return 0.0
+
+
+def check_weight_drift(
+    model_id: str,
+    baseline: list[dict[str, Any]],
+    recent: list[dict[str, Any]],
+    metric_key: str = "score",
+    threshold: float = 0.05,
+) -> DriftReport:
+    """
+    Compare recent outputs to baseline — the weight check.
+
+    Uses a simple statistical comparison: the absolute difference
+    of means relative to the baseline standard deviation, similar
+    to a Cohen's d effect size.
+
+    Args:
+        model_id: The model being weighed.
+        baseline: Historical output samples (the established weight).
+        recent: Recent output samples (the current weight).
+        metric_key: Key to extract the numeric metric from each sample.
+        threshold: Drift score above which drift is "significant".
+
+    Returns:
+        DriftReport with the assessment.
+    """
+    baseline_values = [_extract_metric(o, metric_key) for o in baseline] if baseline else [0.0]
+    recent_values = [_extract_metric(o, metric_key) for o in recent] if recent else [0.0]
+
+    b_mean = mean(baseline_values) if _HAS_STATS else sum(baseline_values) / len(baseline_values)
+    r_mean = mean(recent_values) if _HAS_STATS else sum(recent_values) / len(recent_values)
+
+    b_std = pstdev(baseline_values) if len(baseline_values) > 1 and _HAS_STATS else 0.0001
+    b_std = max(b_std, 1e-6)  # avoid division by zero
+
+    # Cohen's d-style drift score
+    drift_score = abs(r_mean - b_mean) / b_std
+
+    is_significant = drift_score > threshold
+
+    # Trend determination
+    if abs(drift_score) < threshold * 0.5:
+        trend = "stable"
+    elif r_mean > b_mean:
+        trend = "increasing"
+    else:
+        trend = "decreasing"
+
+    return DriftReport(
+        model_id=model_id,
+        baseline_mean=b_mean,
+        recent_mean=r_mean,
+        drift_score=drift_score,
+        threshold=threshold,
+        is_significant=is_significant,
+        trend=trend,
+        sample_size=len(recent_values),
+    )

vetcheck/exam.py

@@ -0,0 +1,161 @@
+"""
+Exam module — regression test runner as health check (physical exam).
+
+Each test is a vital sign. The runner executes them and produces
+an ExamResult with a full health assessment.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class VitalSign:
+    """A single test result — one vital sign from the physical."""
+    name: str
+    description: str
+    critical: bool
+    passed: bool
+    duration_ms: float = 0.0
+    error: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ExamResult:
+    """Full results of a physical exam — the vet's report."""
+    model_id: str
+    vitals: list[VitalSign] = field(default_factory=list)
+    timestamp: float = field(default_factory=time.time)
+    duration_ms: float = 0.0
+
+    @property
+    def passed(self) -> bool:
+        """Overall pass — no critical vital signs failed."""
+        return all(v.passed for v in self.vitals if v.critical)
+
+    @property
+    def all_passed(self) -> bool:
+        """Every vital sign passed, including non-critical."""
+        return all(v.passed for v in self.vitals)
+
+    @property
+    def critical_failures(self) -> int:
+        return sum(1 for v in self.vitals if v.critical and not v.passed)
+
+    @property
+    def warnings(self) -> int:
+        return sum(1 for v in self.vitals if not v.critical and not v.passed)
+
+    def summary(self) -> str:
+        """Human-readable summary — like the vet's notes."""
+        lines = [
+            f"📋 Physical Exam Report for {self.model_id}",
+            f"   Date: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime(self.timestamp))}",
+            f"   Duration: {self.duration_ms:.1f}ms",
+            f"   Overall: {'✅ PASSED' if self.passed else '❌ FAILED'}",
+            "",
+        ]
+        for v in self.vitals:
+            icon = "✅" if v.passed else ("🚨" if v.critical else "⚠️")
+            tag = " [CRITICAL]" if v.critical else " [warning]" if not v.passed else ""
+            lines.append(f"   {icon} {v.name}{tag} — {v.description}")
+            if v.error:
+                lines.append(f"      Error: {v.error}")
+        lines.append("")
+        lines.append(
+            f"   Critical failures: {self.critical_failures} | Warnings: {self.warnings}"
+        )
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model_id": self.model_id,
+            "timestamp": self.timestamp,
+            "duration_ms": self.duration_ms,
+            "passed": self.passed,
+            "all_passed": self.all_passed,
+            "critical_failures": self.critical_failures,
+            "warnings": self.warnings,
+            "vitals": [
+                {
+                    "name": v.name,
+                    "description": v.description,
+                    "critical": v.critical,
+                    "passed": v.passed,
+                    "duration_ms": v.duration_ms,
+                    "error": v.error,
+                    "details": v.details,
+                }
+                for v in self.vitals
+            ],
+        }
+
+
+def run_physical_exam(
+    model_id: str,
+    suite: list[dict[str, Any]],
+    runner: Callable[[dict[str, Any]], bool] | None = None,
+) -> ExamResult:
+    """
+    Execute the regression suite as a physical exam.
+
+    Args:
+        model_id: The model being examined.
+        suite: List of test definitions. Each must have:
+            - name: vital sign name
+            - description: what it checks
+            - critical: whether failure means quarantine
+            - check (optional): a callable that returns bool
+        runner: Optional custom runner. If None, uses default which
+            calls each test's "check" callable or defaults to pass.
+
+    Returns:
+        ExamResult with all vital signs recorded.
+    """
+    start = time.time()
+    vitals: list[VitalSign] = []
+
+    for test in suite:
+        name = test.get("name", "unknown")
+        desc = test.get("description", "")
+        critical = test.get("critical", False)
+        check = test.get("check")
+
+        v_start = time.time()
+        passed = True
+        error = None
+
+        try:
+            if runner is not None:
+                passed = bool(runner(test))
+            elif check is not None:
+                passed = bool(check())
+            # If no runner and no check, default to pass (assume external)
+        except Exception as e:
+            passed = False
+            error = str(e)
+
+        v_duration = (time.time() - v_start) * 1000
+
+        vitals.append(
+            VitalSign(
+                name=name,
+                description=desc,
+                critical=critical,
+                passed=passed,
+                duration_ms=v_duration,
+                error=error,
+            )
+        )
+
+    total_duration = (time.time() - start) * 1000
+
+    return ExamResult(
+        model_id=model_id,
+        vitals=vitals,
+        duration_ms=total_duration,
+    )

vetcheck/quarantine.py

@@ -0,0 +1,188 @@
+"""
+Quarantine module — isolation and release for sick models.
+
+When a model fails a critical exam, it gets quarantined.
+Traffic is routed elsewhere until it passes a clean physical
+and is explicitly released.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class QuarantineState(str, Enum):
+    """State of a model in the quarantine system."""
+    ACTIVE = "active"          # In quarantine
+    RELEASED = "released"      # Released back to duty
+    NEVER_QUARANTINED = "never_quarantined"
+
+
+@dataclass
+class QuarantineStatus:
+    """
+    Current quarantine status of a model — like a kennel record.
+
+    Tracks when and why a model was isolated, and whether it's
+    been released.
+    """
+    model_id: str
+    state: QuarantineState = QuarantineState.NEVER_QUARANTINED
+    quarantined_at: float | None = None
+    released_at: float | None = None
+    reason: str = ""
+    history: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def is_quarantined(self) -> bool:
+        """Is this model currently in quarantine?"""
+        return self.state == QuarantineState.ACTIVE
+
+    @property
+    def duration(self) -> float | None:
+        """How long has this model been in quarantine (seconds)?"""
+        if self.quarantined_at is None:
+            return None
+        end = self.released_at or time.time()
+        return end - self.quarantined_at
+
+    def summary(self) -> str:
+        icon = "🔒" if self.is_quarantined else "🟢"
+        lines = [f"{icon} Quarantine Status for {self.model_id}"]
+        lines.append(f"   State: {self.state.value}")
+
+        if self.quarantined_at:
+            lines.append(
+                f"   Quarantined: {time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(self.quarantined_at))}"
+            )
+            lines.append(f"   Reason: {self.reason}")
+            if self.is_quarantined and self.duration is not None:
+                lines.append(f"   Duration: {self.duration:.0f}s")
+
+        if self.released_at:
+            lines.append(
+                f"   Released: {time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(self.released_at))}"
+            )
+
+        if self.history:
+            lines.append(f"   History: {len(self.history)} previous event(s)")
+
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model_id": self.model_id,
+            "state": self.state.value,
+            "quarantined_at": self.quarantined_at,
+            "released_at": self.released_at,
+            "reason": self.reason,
+            "duration": self.duration,
+            "history": self.history,
+        }
+
+
+# In-memory registry (shared across VetCheck instances in same process)
+_registry: dict[str, QuarantineStatus] = {}
+
+
+def _get_or_create(model_id: str, registry: dict[str, Any] | None = None) -> QuarantineStatus:
+    """Get existing status or create a fresh one."""
+    reg = registry if registry is not None else _registry
+    if model_id not in reg:
+        reg[model_id] = QuarantineStatus(model_id=model_id)
+    return reg[model_id]
+
+
+def quarantine_model(
+    model_id: str,
+    reason: str,
+    registry: dict[str, Any] | None = None,
+) -> QuarantineStatus:
+    """
+    Put a model into quarantine — isolate it from production.
+
+    Records the reason and timestamp. If already quarantined,
+    updates the reason but doesn't create a new record.
+
+    Args:
+        model_id: The model to quarantine.
+        reason: Why it's being quarantined.
+        registry: Optional custom registry (for testing/isolation).
+
+    Returns:
+        Updated QuarantineStatus.
+    """
+    status = _get_or_create(model_id, registry)
+
+    now = time.time()
+
+    # Record history if re-quarantining or state changes
+    if status.state != QuarantineState.ACTIVE:
+        status.history.append({
+            "event": "quarantined",
+            "timestamp": now,
+            "reason": reason,
+            "previous_state": status.state.value,
+        })
+
+    status.state = QuarantineState.ACTIVE
+    status.quarantined_at = now
+    status.released_at = None
+    status.reason = reason
+
+    return status
+
+
+def release_model(
+    model_id: str,
+    registry: dict[str, Any] | None = None,
+) -> QuarantineStatus:
+    """
+    Release a model from quarantine — return it to active duty.
+
+    The model must be in quarantine. Records the release timestamp.
+
+    Args:
+        model_id: The model to release.
+        registry: Optional custom registry.
+
+    Returns:
+        Updated QuarantineStatus.
+
+    Raises:
+        ValueError: If the model is not currently quarantined.
+    """
+    status = _get_or_create(model_id, registry)
+
+    if status.state != QuarantineState.ACTIVE:
+        raise ValueError(
+            f"Cannot release {model_id}: not in quarantine (state={status.state.value})"
+        )
+
+    now = time.time()
+    status.history.append({
+        "event": "released",
+        "timestamp": now,
+        "duration": status.duration,
+    })
+
+    status.state = QuarantineState.RELEASED
+    status.released_at = now
+
+    return status
+
+
+def get_quarantine_status(
+    model_id: str,
+    registry: dict[str, Any] | None = None,
+) -> QuarantineStatus:
+    """
+    Check the quarantine status of a model.
+
+    Returns the current status, creating a fresh "never quarantined"
+    record if the model has never been seen.
+    """
+    return _get_or_create(model_id, registry)

vetcheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: vetcheck
+Version: 0.1.0
+Summary: Model health monitoring as veterinary care — regression tests as physical exams, drift detection as weight monitoring, auto-quarantine on critical health breaches.
+Author: SuperInstance
+License: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/vetcheck
+Project-URL: Repository, https://github.com/SuperInstance/vetcheck
+Keywords: ml,monitoring,model-health,drift-detection,regression-testing,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Vetcheck: Model Health Monitoring as Veterinary Care
+
+> Working dogs need regular checkups. So do models.
+
+[![Python](https://img.shields.io/python/required-version-toml?toml=pyproject.toml)](https://python.org)
+[![License](https://img.shields.io/github/license/SuperInstance/vetcheck)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](tests/)
+
+A model that passed regression tests six months ago might silently degrade over time — distribution drift, fine-tuning side effects, dependency changes. Vetcheck treats model health monitoring like veterinary care because in the Working Animal Architecture paradigm, every model is a working animal that needs ongoing supervision to stay fit for duty. Physical exams catch regressions. Weight monitoring catches output drift. Quarantine isolates failures before they reach production.
+
+## What It Does
+
+Vetcheck provides three core exams and two lifecycle operations. The **physical exam** runs a full regression test suite against the model, checking vital signs: does it still handle edge cases (temperature), are response times within bounds (heart rate), does it handle load without degradation (blood pressure), do function-calling and structured outputs still work (reflexes)? The result is an `ExamResult` with pass/fail per test and an overall `HealthStatus`.
+
+The **weight check** monitors output distribution drift over time. Just as a vet weighs a dog at every visit and flags concerning changes, Vetcheck compares recent output embeddings or distributions to a baseline and flags statistically significant drift. Trends are tracked across checkups — a gradual 5% drift over a month is different from a sudden 20% shift overnight.
+
+When a model fails critically, **quarantine** auto-isolates it: traffic is routed elsewhere, alerts fire, and the model stays isolated until a clean physical exam passes. The **health certificate** is a signed attestation that a model is fit for production — it verifies the last physical exam passed, confirms no active quarantine, checks weight stability, and returns a certificate with an expiry date.
+
+## Install
+
+```bash
+pip install vetcheck
+```
+
+For development:
+
+```bash
+git clone https://github.com/SuperInstance/vetcheck.git
+cd vetcheck
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from vetcheck import VetCheck
+
+vet = VetCheck(model_id="llama-3-70b")
+
+# Run a full physical — executes regression suite
+report = vet.physical_exam()
+print(report.summary())
+# ════════════════════════════════════════════
+#   PHYSICAL EXAM: llama-3-70b
+#   Overall: HEALTHY
+#   Tests: 47 passed, 3 failed, 0 skipped
+# ════════════════════════════════════════════
+
+# Check for weight drift — compares recent outputs to baseline
+drift = vet.weight_check(window=100)
+if drift.significant:
+    print(f"⚠ Drift detected: {drift.magnitude:.1%} from baseline")
+    print(f"  Trend: {drift.trend}")  # "increasing", "decreasing", "stable"
+else:
+    print("✓ Weight stable")
+
+# Quarantine a sick model
+if report.critical_failures > 0:
+    vet.quarantine(reason="Critical regression detected")
+    print("Model quarantined — traffic routed to backup")
+
+# ... after fixes applied ...
+
+# Run physical again to verify recovery
+recovery = vet.physical_exam()
+if recovery.passed:
+    vet.release()
+    print("Model returned to active duty")
+
+# Issue a clean bill of health
+cert = vet.health_certificate()
+print(f"Health certificate issued, expires: {cert.expires_at}")
+print(f"Valid: {cert.is_valid()}")
+```
+
+## Architecture
+
+```
+src/vetcheck/
+├── __init__.py        # VetCheck orchestrator + HealthCertificate
+├── exam.py             # Regression test runner (physical exams)
+│   ├── run_physical_exam()
+│   ├── ExamResult
+│   └── TestCase / TestSuite
+├── drift.py            # Output drift detection (weight monitoring)
+│   ├── check_weight_drift()
+│   ├── DriftReport
+│   └── BaselineDistribution
+└── quarantine.py       # Quarantine and release system
+    ├── quarantine_model()
+    ├── release_model()
+    ├── get_quarantine_status()
+    └── QuarantineStatus
+```
+
+### Health States
+
+```
+HEALTHY ──────▶ UNDER_OBSERVATION ──────▶ QUARANTINED
+   ▲                    │                       │
+   │                    │                       │
+   └────────────────────┘                       │
+   release() (clean exam)                       │
+   ▲                                            │
+   └────────────────────────────────────────────┘
+                  release() (clean exam)
+```
+
+## API Reference
+
+### `VetCheck`
+
+```python
+class VetCheck:
+    def __init__(self, model_id: str, baseline_dir: str = "./baselines")
+
+    # Exams
+    def physical_exam(self, suite: str = "default") -> ExamResult
+    def weight_check(self, window: int = 100) -> DriftReport
+
+    # Lifecycle
+    def quarantine(self, reason: str) -> QuarantineStatus
+    def release(self) -> bool
+    @property
+    def is_quarantined(self) -> bool
+
+    # Certification
+    def health_certificate(self, validity_days: int = 7) -> HealthCertificate
+    @property
+    def health_status(self) -> HealthStatus
+```
+
+### Result Types
+
+```python
+@dataclass
+class ExamResult:
+    model_id: str
+    passed: bool
+    overall_status: HealthStatus
+    tests_passed: int
+    tests_failed: int
+    critical_failures: int
+    duration_seconds: float
+    details: list[TestResult]
+
+@dataclass
+class DriftReport:
+    model_id: str
+    significant: bool        # statistically significant drift
+    magnitude: float         # 0.0-1.0
+    trend: str               # "increasing", "decreasing", "stable"
+    window: int              # samples compared
+    p_value: float           # statistical test result
+
+@dataclass
+class HealthCertificate:
+    model_id: str
+    status: HealthStatus
+    issued_at: float
+    expires_at: float
+    last_exam_passed: bool
+    weight_stable: bool
+    quarantine_active: bool
+    notes: str
+
+    def is_valid(self, now: float | None = None) -> bool
+    def to_dict(self) -> dict
+```
+
+### `HealthStatus`
+
+```python
+class HealthStatus(str, Enum):
+    HEALTHY = "healthy"
+    UNDER_OBSERVATION = "under_observation"
+    QUARANTINED = "quarantined"
+    CRITICAL = "critical"
+```
+
+## The Analogy
+
+| Veterinary Care | Vetcheck |
+|-----------------|----------|
+| Physical exam | Regression test suite (`physical_exam`) |
+| Weight monitoring | Output drift detection (`weight_check`) |
+| Quarantine | Auto-isolation on critical health breach |
+| Health certificate | Clearance for production deployment |
+| Vaccination schedule | Periodic exam scheduling |
+| Breed-specific screening | Model-specific test suites |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+
+# Test exam runner
+pytest tests/test_exam.py -v
+
+# Test drift detection
+pytest tests/test_drift.py -v
+
+# Test quarantine lifecycle
+pytest tests/test_quarantine.py -v
+```
+
+## Philosophy
+
+In animal husbandry, preventative medicine is cheaper than emergency treatment. The same applies to AI systems: catching a regression before it reaches production is dramatically cheaper than responding to an outage. Vetcheck brings the discipline of veterinary preventative care to model operations — regular checkups, early detection, isolation of sick individuals, and structured health certificates before deployment.
+
+This is part of [Working Animal Architecture](https://github.com/SuperInstance/AI-Writings) — specifically the health monitoring layer that keeps the kennel (flux registry) populated with animals fit for duty. A model with an expired health certificate shouldn't be in production, just as a working dog that hasn't seen a vet in a year shouldn't be herding sheep.
+
+## Ecosystem
+
+| Repo | Role |
+|------|------|
+| **[vetcheck](https://github.com/SuperInstance/vetcheck)** | **This repo** — health monitoring |
+| [shepherds-console](https://github.com/SuperInstance/shepherds-console) | Dashboard (displays vetcheck health status) |
+| [breed-registry](https://github.com/SuperInstance/breed-registry) | Breed selection (uses health certificates) |
+| [lineage-tracker](https://github.com/SuperInstance/lineage-tracker) | Lineage (health data enriches lineage records) |
+| [baton](https://github.com/SuperInstance/baton) | Generational handoff (health informs sunset decisions) |
+
+
+
+## Integration Patterns
+
+### With Breed Registry: Pre-Deployment Health Check
+
+```python
+from vetcheck import VetCheck
+from breed_registry import select_breed
+
+# Select the best model for a task
+recommended = select_breed("code_generation")
+print(f"Recommended: {recommended.recommended}")
+
+# Before deploying, verify it's healthy
+vet = VetCheck(model_id=recommended.recommended)
+cert = vet.health_certificate(validity_days=14)
+
+if cert.is_valid():
+    print(f"✓ {recommended.recommended} is certified healthy — deploy")
+else:
+    print(f"✗ {recommended.recommended} failed health check")
+    print(f"  Falling back to alternatives...")
+    for alt in recommended.alternatives:
+        alt_vet = VetCheck(model_id=alt.breed)
+        alt_cert = alt_vet.health_certificate()
+        if alt_cert.is_valid():
+            print(f"  ✓ {alt.breed} is healthy (score: {alt.score:.1f})")
+            break
+```
+
+### With Lineage Tracker: Regression Source Detection
+
+```python
+from vetcheck import VetCheck
+from lineage_tracker import LineageTracker
+
+# Model failed its physical exam
+vet = VetCheck(model_id="prod-model-v7")
+report = vet.physical_exam()
+
+if not report.passed:
+    # Check if this is a known weakness in the lineage
+    tracker = LineageTracker("lineage.json")
+    lineage = tracker.get_lineage("prod-model-v7")
+
+    print("Failed exam. Checking lineage for inherited weaknesses:")
+    for gen in lineage:
+        model = gen.model
+        failed_areas = [t.name for t in report.details if not t.passed]
+        for area in failed_areas:
+            trait_key = area.lower().replace(" ", "_")
+            if model.traits and trait_key in model.traits:
+                print(f"  Gen {gen.generation} {model.name}: {trait_key}={model.traits[trait_key]}")
+
+    # If the weakness is inherited, quarantine and recommend retraining
+    vet.quarantine(reason=f"Inherited regression: {failed_areas}")
+```
+
+### Continuous Monitoring with Scheduled Exams
+
+```python
+from vetcheck import VetCheck
+import schedule  # pip install schedule
+import time
+
+vet = VetCheck(model_id="prod-model-v7", baseline_dir="./baselines")
+
+# Daily weight check (lightweight — compares output distributions)
+schedule.every().day.at("06:00").do(lambda: vet.weight_check(window=500))
+
+# Weekly physical (full regression suite)
+schedule.every().monday.at("02:00").do(lambda: vet.physical_exam())
+
+# Monthly health certificate renewal
+schedule.every(30).days.do(lambda: vet.health_certificate(validity_days=7))
+
+# Auto-quarantine on critical failure
+def full_checkup():
+    report = vet.physical_exam()
+    if report.critical_failures > 0:
+        vet.quarantine(reason=f"Auto-quarantine: {report.critical_failures} critical failures")
+        # Alert the team
+        print(f"🚨 {vet.model_id} QUARANTINED — {report.critical_failures} critical failures")
+    return report
+
+schedule.every().day.at("12:00").do(full_checkup)
+
+# Run the scheduler
+while True:
+    schedule.run_pending()
+    time.sleep(60)
+```
+
+### Fleet Health Dashboard
+
+```python
+from vetcheck import VetCheck
+from breed_registry import BreedMatcher
+
+matcher = BreedMatcher()
+fleet = ["gpt-4", "claude-3", "llama-3", "glm", "qwen"]
+
+print("FLEET HEALTH REPORT")
+print("=" * 60)
+
+for model_id in fleet:
+    vet = VetCheck(model_id=model_id)
+    status = vet.health_status
+    quarantined = "🔒 QUARANTINED" if vet.is_quarantined else "🟢 ACTIVE"
+
+    # Quick weight check
+    drift = vet.weight_check(window=100)
+    drift_indicator = "📉" if drift.significant else "✓"
+
+    print(f"  {model_id:15s} {status.value:20s} {quarantined} drift:{drift_indicator}")
+
+    # Recommend breed-specific action
+    aptitude = matcher.assess(model_id, "reasoning")
+    if status.value == "quarantined":
+        alternatives = matcher.select("reasoning").alternatives[:2]
+        print(f"    → Failover to: {[a.breed for a in alternatives]}")
+```
+
+## Monitoring Philosophy
+
+The veterinary metaphor runs deeper than naming. In real animal husbandry:
+
+- **Preventative care is cheaper than emergency treatment.** A daily weight check catches drift before it becomes a regression. A weekly physical catches regressions before they reach users.
+- **Quarantine is not punishment.** It's protection — for the model (no traffic to handle while recovering) and for the system (no degraded output reaching users). The quarantine is lifted the moment a clean physical passes.
+- **Health certificates expire.** A model that was healthy last month might not be healthy today. Certificate expiry isn't bureaucracy — it's the acknowledgment that model health is dynamic, not static.
+- **Breed-specific screening matters.** A Thoroughbred (GPT-4) needs different tests than a Mustang (Llama-3). Custom test suites per breed catch breed-specific failure modes that generic tests miss.
+- **The vet's authority overrides the registry.** A model with the best breed score should not be in production if its health certificate has expired. The registry says what's best on paper; the vet says what's fit for duty right now.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vetcheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+vetcheck/__init__.py,sha256=XKgcrg9wCFd6t0D3tXYx5RzO5sw8adu_XI_rW0UWTZs,7871
+vetcheck/drift.py,sha256=KU9RyTQQhnaKuLmko3Cp53s2OycYwNgks0N6eM6kZNY,4206
+vetcheck/exam.py,sha256=pwoJyMj4qdnwM2FHOY96QMfVqT243kkZ6u4OVtCatYA,5045
+vetcheck/quarantine.py,sha256=vvSvJwuqTUKUWL37sdSQBYga27_gtLlY1xjglworIiU,5474
+vetcheck-0.1.0.dist-info/licenses/LICENSE,sha256=oIZ4iMwyoGNfEZRn_qZ2bqd1wzV8oUQgjyS-ZAEDLEI,1070
+vetcheck-0.1.0.dist-info/METADATA,sha256=7WymTyVTa3uNA0m6iDE2S_0fP1RxlxeeSha4ttMWxc0,14874
+vetcheck-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+vetcheck-0.1.0.dist-info/top_level.txt,sha256=kAU5egbfyiDIm3UsljFnibIZykajIRDeAxvRECFCkwc,9
+vetcheck-0.1.0.dist-info/RECORD,,

vetcheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vetcheck-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperInstance
+
+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.

vetcheck-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vetcheck