modelalive 0.1.0__py3-none-any.whl

modelalive/__init__.py

@@ -0,0 +1,15 @@
+"""Model Alive — pre-flight check for LLM model IDs."""
+
+from modelalive.check import alive, check, resolve
+from modelalive.exceptions import ModelDeprecatedError, ModelRetiredError
+from modelalive.types import AliveResult
+
+__all__ = [
+    "alive",
+    "check",
+    "resolve",
+    "AliveResult",
+    "ModelRetiredError",
+    "ModelDeprecatedError",
+]
+__version__ = "0.1.0"

modelalive/check.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+from modelalive.exceptions import ModelDeprecatedError, ModelRetiredError
+from modelalive.registry import days_until, get_model_entry, registry_version
+from modelalive.types import AliveResult
+
+
+def alive(
+    model: str,
+    *,
+    registry_path: str | Path | None = None,
+    today: date | None = None,
+) -> AliveResult:
+    """Return lifecycle status for a model ID without raising."""
+    entry = get_model_entry(model, registry_path=registry_path)
+    version = registry_version(registry_path=registry_path)
+
+    if entry is None:
+        return AliveResult(
+            model=model,
+            alive=True,
+            status="unknown",
+            message="Model not in registry — assumed alive. Register at modelalive.dev or pin a known ID.",
+            registry_version=version,
+        )
+
+    status = entry.get("status", "unknown")
+    retired_at = entry.get("retired_at")
+    days_left = days_until(retired_at, today=today)
+
+    if status == "retired":
+        return AliveResult(
+            model=model,
+            alive=False,
+            status="retired",
+            provider=entry.get("provider"),
+            deprecated_at=entry.get("deprecated_at"),
+            retired_at=retired_at,
+            replacement=entry.get("replacement"),
+            breaking_changes=list(entry.get("breaking_changes") or []),
+            migrate_url=entry.get("migrate_url"),
+            days_until_retirement=days_left,
+            message=_retired_message(model, entry),
+            registry_version=version,
+        )
+
+    if status == "deprecated":
+        return AliveResult(
+            model=model,
+            alive=True,
+            status="deprecated",
+            provider=entry.get("provider"),
+            deprecated_at=entry.get("deprecated_at"),
+            retired_at=retired_at,
+            replacement=entry.get("replacement"),
+            breaking_changes=list(entry.get("breaking_changes") or []),
+            migrate_url=entry.get("migrate_url"),
+            days_until_retirement=days_left,
+            message=_deprecated_message(model, entry, days_left),
+            registry_version=version,
+        )
+
+    return AliveResult(
+        model=model,
+        alive=True,
+        status="active",
+        provider=entry.get("provider"),
+        replacement=entry.get("replacement"),
+        breaking_changes=list(entry.get("breaking_changes") or []),
+        migrate_url=entry.get("migrate_url"),
+        registry_version=version,
+    )
+
+
+def check(
+    model: str,
+    *,
+    warn_deprecated: bool = False,
+    registry_path: str | Path | None = None,
+    today: date | None = None,
+) -> AliveResult:
+    """Check model lifecycle; raise on retired (and optionally deprecated)."""
+    result = alive(model, registry_path=registry_path, today=today)
+
+    if result.status == "retired":
+        raise ModelRetiredError(result)
+    if warn_deprecated and result.status == "deprecated":
+        raise ModelDeprecatedError(result)
+    return result
+
+
+def resolve(
+    model: str,
+    *,
+    registry_path: str | Path | None = None,
+    today: date | None = None,
+) -> str:
+    """Return replacement model ID if retired/deprecated, else the original."""
+    result = alive(model, registry_path=registry_path, today=today)
+    if result.replacement:
+        return result.replacement
+    return model
+
+
+def _retired_message(model: str, entry: dict) -> str:
+    replacement = entry.get("replacement")
+    if replacement:
+        return f"Model '{model}' was retired. Use '{replacement}' instead."
+    return f"Model '{model}' was retired."
+
+
+def _deprecated_message(model: str, entry: dict, days_left: int | None) -> str:
+    replacement = entry.get("replacement")
+    retired_at = entry.get("retired_at")
+    parts = [f"Model '{model}' is deprecated."]
+    if retired_at:
+        parts.append(f"Retires on {retired_at}.")
+    if days_left is not None and days_left >= 0:
+        parts.append(f"{days_left} day(s) remaining.")
+    if replacement:
+        parts.append(f"Migrate to '{replacement}'.")
+    return " ".join(parts)

modelalive/cli.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from modelalive.check import alive, check, resolve
+from modelalive.exceptions import ModelDeprecatedError, ModelRetiredError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="modelalive",
+        description="Pre-flight check: is this LLM model ID still alive?",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check_cmd = sub.add_parser("check", help="Check a model ID")
+    check_cmd.add_argument("model", help="Model ID to check")
+    check_cmd.add_argument(
+        "--warn-deprecated",
+        action="store_true",
+        help="Exit non-zero if model is deprecated",
+    )
+    check_cmd.add_argument("--json", action="store_true", help="Output JSON")
+
+    resolve_cmd = sub.add_parser("resolve", help="Return best model ID to use")
+    resolve_cmd.add_argument("model", help="Model ID to resolve")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        try:
+            result = check(args.model, warn_deprecated=args.warn_deprecated)
+        except (ModelRetiredError, ModelDeprecatedError) as exc:
+            result = exc.result
+            if args.json:
+                print(json.dumps(result.to_dict(), indent=2))
+            else:
+                print(result.message or result.model, file=sys.stderr)
+            return 1
+
+        if args.json:
+            print(json.dumps(result.to_dict(), indent=2))
+        else:
+            status = "ALIVE" if result.alive else "DEAD"
+            print(f"{status}: {result.model} ({result.status})")
+            if result.replacement:
+                print(f"  replacement: {result.replacement}")
+            if result.breaking_changes:
+                print("  breaking_changes:")
+                for change in result.breaking_changes:
+                    print(f"    - {change}")
+        return 0
+
+    if args.command == "resolve":
+        print(resolve(args.model))
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

modelalive/data/models.json

@@ -0,0 +1,128 @@
+{
+  "version": "2026-06-28",
+  "models": {
+    "claude-sonnet-4-20250514": {
+      "provider": "anthropic",
+      "status": "retired",
+      "deprecated_at": "2026-04-14",
+      "retired_at": "2026-06-15",
+      "replacement": "claude-sonnet-4-6",
+      "breaking_changes": [],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-opus-4-20250514": {
+      "provider": "anthropic",
+      "status": "retired",
+      "deprecated_at": "2026-04-14",
+      "retired_at": "2026-06-15",
+      "replacement": "claude-opus-4-8",
+      "breaking_changes": [
+        "temperature, top_p, and top_k are rejected on Claude Opus 4.7+ — remove these parameters"
+      ],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-opus-4-1-20250805": {
+      "provider": "anthropic",
+      "status": "deprecated",
+      "deprecated_at": "2026-06-05",
+      "retired_at": "2026-08-05",
+      "replacement": "claude-opus-4-8",
+      "breaking_changes": [
+        "temperature, top_p, and top_k are rejected on Claude Opus 4.7+ — remove these parameters"
+      ],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-mythos-preview": {
+      "provider": "anthropic",
+      "status": "deprecated",
+      "deprecated_at": "2026-06-01",
+      "retired_at": "2026-06-30",
+      "replacement": "claude-mythos-5",
+      "breaking_changes": [],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-3-7-sonnet-20250219": {
+      "provider": "anthropic",
+      "status": "retired",
+      "deprecated_at": "2025-10-28",
+      "retired_at": "2026-02-19",
+      "replacement": "claude-sonnet-4-6",
+      "breaking_changes": [],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-3-5-haiku-20241022": {
+      "provider": "anthropic",
+      "status": "retired",
+      "deprecated_at": "2025-12-19",
+      "retired_at": "2026-02-19",
+      "replacement": "claude-haiku-4-5-20251001",
+      "breaking_changes": [],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-3-haiku-20240307": {
+      "provider": "anthropic",
+      "status": "retired",
+      "deprecated_at": "2026-02-19",
+      "retired_at": "2026-04-20",
+      "replacement": "claude-haiku-4-5-20251001",
+      "breaking_changes": [],
+      "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+    },
+    "claude-sonnet-4-6": {
+      "provider": "anthropic",
+      "status": "active",
+      "replacement": null,
+      "breaking_changes": []
+    },
+    "claude-opus-4-8": {
+      "provider": "anthropic",
+      "status": "active",
+      "replacement": null,
+      "breaking_changes": [
+        "temperature, top_p, and top_k are rejected — omit these parameters"
+      ]
+    },
+    "claude-haiku-4-5-20251001": {
+      "provider": "anthropic",
+      "status": "active",
+      "replacement": null,
+      "breaking_changes": []
+    },
+    "gpt-4-0314": {
+      "provider": "openai",
+      "status": "retired",
+      "retired_at": "2024-06-06",
+      "replacement": "gpt-4o",
+      "breaking_changes": [],
+      "migrate_url": "https://developers.openai.com/api/docs/deprecations"
+    },
+    "gpt-4-32k": {
+      "provider": "openai",
+      "status": "retired",
+      "retired_at": "2024-06-06",
+      "replacement": "gpt-4o",
+      "breaking_changes": [],
+      "migrate_url": "https://developers.openai.com/api/docs/deprecations"
+    },
+    "gpt-3.5-turbo-0301": {
+      "provider": "openai",
+      "status": "retired",
+      "retired_at": "2024-09-13",
+      "replacement": "gpt-3.5-turbo",
+      "breaking_changes": [],
+      "migrate_url": "https://developers.openai.com/api/docs/deprecations"
+    },
+    "gpt-4o": {
+      "provider": "openai",
+      "status": "active",
+      "replacement": null,
+      "breaking_changes": []
+    },
+    "gpt-4o-mini": {
+      "provider": "openai",
+      "status": "active",
+      "replacement": null,
+      "breaking_changes": []
+    }
+  }
+}

modelalive/exceptions.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from modelalive.types import AliveResult
+
+
+class ModelLifecycleError(Exception):
+    """Base error for model lifecycle issues."""
+
+    def __init__(self, result: AliveResult) -> None:
+        self.result = result
+        super().__init__(result.message or result.model)
+
+
+class ModelRetiredError(ModelLifecycleError):
+    """Raised when a model is retired and API calls will fail."""
+
+
+class ModelDeprecatedError(ModelLifecycleError):
+    """Raised when a model is deprecated but not yet retired."""

modelalive/registry.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+from datetime import date, datetime
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+_REGISTRY_FILENAME = "models.json"
+
+
+def _bundled_registry_text() -> str:
+    return resources.files("modelalive.data").joinpath(_REGISTRY_FILENAME).read_text(encoding="utf-8")
+
+
+def _dev_registry_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "registry" / _REGISTRY_FILENAME
+
+
+@lru_cache(maxsize=1)
+def load_registry(path: str | Path | None = None) -> dict[str, Any]:
+    if path is not None:
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+    try:
+        return json.loads(_bundled_registry_text())
+    except (FileNotFoundError, OSError, TypeError):
+        return json.loads(_dev_registry_path().read_text(encoding="utf-8"))
+
+
+def get_model_entry(model: str, *, registry_path: str | Path | None = None) -> dict[str, Any] | None:
+    registry = load_registry(registry_path)
+    return registry.get("models", {}).get(model)
+
+
+def registry_version(*, registry_path: str | Path | None = None) -> str | None:
+    return load_registry(registry_path).get("version")
+
+
+def _parse_date(value: str | None) -> date | None:
+    if not value:
+        return None
+    return datetime.strptime(value, "%Y-%m-%d").date()
+
+
+def days_until(value: str | None, *, today: date | None = None) -> int | None:
+    target = _parse_date(value)
+    if target is None:
+        return None
+    current = today or date.today()
+    return (target - current).days

modelalive/types.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AliveResult:
+    model: str
+    alive: bool
+    status: str  # active | deprecated | retired | unknown
+    provider: str | None = None
+    deprecated_at: str | None = None
+    retired_at: str | None = None
+    replacement: str | None = None
+    breaking_changes: list[str] = field(default_factory=list)
+    migrate_url: str | None = None
+    days_until_retirement: int | None = None
+    message: str | None = None
+    registry_version: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

modelalive-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: modelalive
+Version: 0.1.0
+Summary: Pre-flight check: is this LLM model ID still alive?
+Project-URL: Homepage, https://github.com/modelalive/modelalive
+Author: ModelAlive
+License-Expression: MIT
+Keywords: anthropic,deprecation,llm,model-id,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115.0; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: httpx>=0.27.0; extra == 'http'
+Description-Content-Type: text/markdown
+
+# Model Alive
+
+Pre-flight check before every LLM API call: **is this model ID still alive?**
+
+Hardcoded model IDs break silently until production fails. Anthropic retired Claude Sonnet 4 and Opus 4 on **June 15, 2026**. Mythos Preview retires **June 30, 2026**. Model Alive answers in one call.
+
+## Quick start
+
+```bash
+pip install -e ".[dev]"
+modelalive check claude-sonnet-4-20250514
+```
+
+```
+DEAD: claude-sonnet-4-20250514 (retired)
+  replacement: claude-sonnet-4-6
+```
+
+## Python SDK
+
+```python
+import modelalive
+
+# Raises ModelRetiredError if dead
+modelalive.check("claude-sonnet-4-20250514")
+
+# Non-throwing status
+result = modelalive.alive("claude-mythos-preview")
+print(result.days_until_retirement)  # 2 (as of 2026-06-28)
+
+# Auto-replace before calling your provider
+model_id = modelalive.resolve("claude-sonnet-4-20250514")
+# → "claude-sonnet-4-6"
+```
+
+## HTTP API
+
+```bash
+uvicorn api.main:app --reload --port 8787
+```
+
+```bash
+curl "http://localhost:8787/v1/alive?model=claude-sonnet-4-20250514"
+```
+
+```json
+{
+  "model": "claude-sonnet-4-20250514",
+  "alive": false,
+  "status": "retired",
+  "provider": "anthropic",
+  "retired_at": "2026-06-15",
+  "replacement": "claude-sonnet-4-6",
+  "breaking_changes": [],
+  "migrate_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+}
+```
+
+Retired models return **HTTP 410**.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/v1/alive?model=` | Lifecycle check |
+| GET | `/v1/resolve?model=` | Best model ID to use |
+| GET | `/v1/registry` | Full registry (optional `?status=retired`) |
+| GET | `/v1/health` | Health + registry version |
+
+## Registry
+
+Curated deprecation data lives in `registry/models.json`. Update when providers announce retirements.
+
+## License
+
+MIT

modelalive-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+modelalive/__init__.py,sha256=OYp5mLHET38U5SaBZTweV2mv0xr93Ridor7rjx6HsNw,375
+modelalive/check.py,sha256=hHeiHt0aV8CvLpOCEP89dDkY-JOUHejBn7tX8b01Yp4,4133
+modelalive/cli.py,sha256=E1R_k_iV5_55zE_IB7W7ZT5NO_p-BAt_xy8k_UXlP38,2087
+modelalive/exceptions.py,sha256=lF9gitdXb-T5YkEK8TxmLCIp6hb8s1jLHoOPzGQr1Io,536
+modelalive/registry.py,sha256=2OpMXTVLY5FVroZHRMKnqkrAIr5NPhPWjz6dePTj4d0,1574
+modelalive/types.py,sha256=HLDaz5y7GnUiz2hIoyXeXMaKfsksri01odRfGMywd7w,664
+modelalive/data/models.json,sha256=yhRUqHq6bBKREzCDYrBLw--mYaj40JKjOoqL7bXBKL8,4182
+modelalive-0.1.0.dist-info/METADATA,sha256=Xhh-QPJ1-3rhBTW0c-7Ow3CHoeZU4hMxkSbPXj8X_8I,2776
+modelalive-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modelalive-0.1.0.dist-info/entry_points.txt,sha256=k6-jjSdowRF-uGoWdhypSyii9WSFjNhQVlPfUrLikzk,51
+modelalive-0.1.0.dist-info/RECORD,,

modelalive-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

modelalive-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modelalive = modelalive.cli:main