split-stack 0.2.0__py3-none-any.whl

split_stack/requirements.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable
+
+
+class UsageProfile(str, Enum):
+    """Supported ways to use split-stack."""
+
+    CORE = "core"
+    OLLAMA_DISCOVERY = "ollama_discovery"
+    LOCAL_ASSISTANT = "local_assistant"
+    CLI_DOCTOR = "cli_doctor"
+
+
+@dataclass(frozen=True)
+class Prerequisite:
+    id: str
+    description: str
+    kind: str
+    required: bool
+    install_command: str | None = None
+    verify_hint: str | None = None
+    satisfied: bool | None = None
+
+
+@dataclass(frozen=True)
+class ProfileRequirements:
+    profile: UsageProfile
+    title: str
+    summary: str
+    prerequisites: tuple[Prerequisite, ...]
+
+    @property
+    def ready(self) -> bool:
+        return all(item.satisfied is not False for item in self.prerequisites if item.required)
+
+
+def _python_ok() -> bool:
+    return sys.version_info >= (3, 10)
+
+
+def _requests_ok() -> bool:
+    try:
+        import requests  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def _ollama_ok(base_url: str = "http://127.0.0.1:11434") -> bool:
+    if not _requests_ok():
+        return False
+    try:
+        import requests
+
+        response = requests.get(f"{base_url.rstrip('/')}/api/tags", timeout=2)
+        response.raise_for_status()
+        payload = response.json() or {}
+        return bool(payload.get("models"))
+    except Exception:
+        return False
+
+
+def _catalog() -> dict[UsageProfile, tuple[Prerequisite, ...]]:
+    return {
+        UsageProfile.CORE: (
+            Prerequisite(
+                id="python",
+                description="Python 3.10 or newer",
+                kind="runtime",
+                required=True,
+                install_command="https://www.python.org/downloads/",
+                verify_hint="python --version",
+            ),
+            Prerequisite(
+                id="split_stack",
+                description="split-stack package installed",
+                kind="package",
+                required=True,
+                install_command="python -m pip install split-stack",
+                verify_hint="python -c \"import split_stack\"",
+            ),
+            Prerequisite(
+                id="model_names",
+                description="A list of model names for assign_tiers() (from config or your provider)",
+                kind="input",
+                required=True,
+                verify_hint='assign_tiers(["qwen3:4b", "qwen3:8b"])',
+            ),
+        ),
+        UsageProfile.OLLAMA_DISCOVERY: (
+            Prerequisite(
+                id="python",
+                description="Python 3.10 or newer",
+                kind="runtime",
+                required=True,
+                install_command="https://www.python.org/downloads/",
+                verify_hint="python --version",
+            ),
+            Prerequisite(
+                id="split_stack",
+                description="split-stack package installed",
+                kind="package",
+                required=True,
+                install_command="python -m pip install split-stack",
+                verify_hint="python -c \"import split_stack\"",
+            ),
+            Prerequisite(
+                id="requests",
+                description="requests library (optional extra)",
+                kind="package",
+                required=True,
+                install_command="python -m pip install split-stack[ollama]",
+                verify_hint="python -c \"import requests\"",
+            ),
+            Prerequisite(
+                id="ollama",
+                description="Ollama installed and running on localhost:11434",
+                kind="service",
+                required=True,
+                install_command="https://ollama.com/download",
+                verify_hint="ollama list",
+            ),
+            Prerequisite(
+                id="ollama_models",
+                description="At least one model pulled in Ollama (e.g. ollama pull qwen3:8b)",
+                kind="input",
+                required=True,
+                verify_hint="ollama list",
+            ),
+        ),
+        UsageProfile.LOCAL_ASSISTANT: (
+            Prerequisite(
+                id="python",
+                description="Python 3.10 or newer",
+                kind="runtime",
+                required=True,
+                install_command="https://www.python.org/downloads/",
+                verify_hint="python --version",
+            ),
+            Prerequisite(
+                id="split_stack",
+                description="split-stack installed in editable mode from repo checkout",
+                kind="package",
+                required=True,
+                install_command="python -m pip install -e .",
+                verify_hint="python -c \"import split_stack\"",
+            ),
+            Prerequisite(
+                id="requests",
+                description="requests library for Ollama HTTP calls",
+                kind="package",
+                required=True,
+                install_command="python -m pip install split-stack[ollama]",
+                verify_hint="python -c \"import requests\"",
+            ),
+            Prerequisite(
+                id="ollama",
+                description="Ollama installed and running on localhost:11434",
+                kind="service",
+                required=True,
+                install_command="https://ollama.com/download",
+                verify_hint="ollama serve",
+            ),
+            Prerequisite(
+                id="ollama_models",
+                description="Two or more models recommended so tiers differ (small + large)",
+                kind="input",
+                required=True,
+                verify_hint="ollama pull qwen3:4b && ollama pull qwen3:14b",
+            ),
+            Prerequisite(
+                id="gpu_ram",
+                description="Enough VRAM/RAM to run your largest pulled model",
+                kind="hardware",
+                required=True,
+                verify_hint="Start with smaller models if inference is slow or fails",
+            ),
+        ),
+        UsageProfile.CLI_DOCTOR: (
+            Prerequisite(
+                id="python",
+                description="Python 3.10 or newer",
+                kind="runtime",
+                required=True,
+                install_command="https://www.python.org/downloads/",
+                verify_hint="python --version",
+            ),
+            Prerequisite(
+                id="split_stack",
+                description="split-stack package installed (includes stack CLI)",
+                kind="package",
+                required=True,
+                install_command="python -m pip install split-stack",
+                verify_hint="stack doctor",
+            ),
+            Prerequisite(
+                id="requests",
+                description="requests library for Ollama tier detection",
+                kind="package",
+                required=False,
+                install_command="python -m pip install split-stack[ollama]",
+                verify_hint="python -c \"import requests\"",
+            ),
+            Prerequisite(
+                id="ollama",
+                description="Ollama running locally (optional; doctor skips if unavailable)",
+                kind="service",
+                required=False,
+                install_command="https://ollama.com/download",
+                verify_hint="ollama list",
+            ),
+        ),
+    }
+
+
+_PROFILE_META: dict[UsageProfile, tuple[str, str]] = {
+    UsageProfile.CORE: (
+        "Core library",
+        "Use score_prompt(), assign_tiers(), and route_prompt() with your own model list.",
+    ),
+    UsageProfile.OLLAMA_DISCOVERY: (
+        "Ollama discovery",
+        "Call discover_models() to read model tags from a local Ollama instance.",
+    ),
+    UsageProfile.LOCAL_ASSISTANT: (
+        "Local work assistant example",
+        "Run examples/local_work_assistant/app.py for auto-tiered local Q&A.",
+    ),
+    UsageProfile.CLI_DOCTOR: (
+        "CLI doctor",
+        "Run stack doctor for split-stack guidance and optional Ollama tier output.",
+    ),
+}
+
+
+def list_usage_profiles() -> list[UsageProfile]:
+    return list(UsageProfile)
+
+
+_CHECKERS: dict[str, Callable[[], bool]] = {
+    "python": _python_ok,
+    "split_stack": lambda: True,
+    "requests": _requests_ok,
+    "ollama": _ollama_ok,
+    "ollama_models": _ollama_ok,
+}
+
+
+def usage_requirements(
+    profile: UsageProfile = UsageProfile.CORE,
+    *,
+    check: bool = False,
+) -> ProfileRequirements:
+    """Return prerequisites for a usage profile.
+
+    Set check=True to probe the local machine (Python version, requests, Ollama).
+    """
+    title, summary = _PROFILE_META[profile]
+    catalog = _catalog()[profile]
+    prerequisites: list[Prerequisite] = []
+
+    for item in catalog:
+        satisfied = None
+        if check and item.id in _CHECKERS:
+            satisfied = _CHECKERS[item.id]()
+        prerequisites.append(
+            Prerequisite(
+                id=item.id,
+                description=item.description,
+                kind=item.kind,
+                required=item.required,
+                install_command=item.install_command,
+                verify_hint=item.verify_hint,
+                satisfied=satisfied,
+            )
+        )
+
+    return ProfileRequirements(
+        profile=profile,
+        title=title,
+        summary=summary,
+        prerequisites=tuple(prerequisites),
+    )

split_stack/routing.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from split_stack.complexity import (
+    looks_like_code,
+    resolve_tier,
+    score_prompt,
+)
+from split_stack.hints import normalize_step_kind, prefer_code_model
+from split_stack.models import ComplexityTier, RouteDecision, StepKind, TierMap
+from split_stack.tiering import describe_tiers
+
+
+def route_prompt(
+    prompt: str,
+    tiers: TierMap,
+    *,
+    hint: str | StepKind | None = None,
+) -> tuple[ComplexityTier, str]:
+    """Return complexity tier and selected model for a prompt."""
+    return explain_route(prompt, tiers, hint=hint).as_tuple()
+
+
+def explain_route(
+    prompt: str,
+    tiers: TierMap,
+    *,
+    hint: str | StepKind | None = None,
+) -> RouteDecision:
+    """Return tier, model, and a trace of why routing chose them."""
+    raw_hint = hint.value if isinstance(hint, StepKind) else hint
+    step_kind: StepKind | None = None
+    tier_source = "heuristic"
+    reasons: list[str] = []
+
+    if hint is not None:
+        step_kind = normalize_step_kind(hint)
+        tier = resolve_tier(prompt, hint=step_kind)
+        tier_source = "hint"
+        reasons.append(f"hint={step_kind.value} maps to tier {tier.value}")
+    else:
+        tier = score_prompt(prompt)
+        reasons.append(f"no hint — keyword/heuristic scoring → tier {tier.value}")
+        if len((prompt or "").split()) > 80:
+            reasons.append("prompt length > 80 tokens influenced complex tier")
+
+    use_code = _should_use_code_model(prompt, tier, hint, step_kind, tiers)
+    if use_code and tiers.code:
+        model = tiers.code
+        model_source = "code_slot"
+        if prefer_code_model(hint) or step_kind == StepKind.CODE:
+            reasons.append(f"code specialist {model} (hint={step_kind.value if step_kind else hint})")
+        else:
+            reasons.append(f"code specialist {model} (prompt looks like code)")
+    elif use_code and not tiers.code:
+        model = tiers.for_tier(tier)
+        model_source = "tier_slot"
+        reasons.append(
+            f"code-like prompt but no code slot — using {tier.value} model {model}"
+        )
+    else:
+        model = tiers.for_tier(tier)
+        model_source = "tier_slot"
+        slot_name = tier.value
+        if tier == ComplexityTier.REASONING and tiers.reasoning == tiers.complex:
+            reasons.append(
+                f"reasoning tier → {model} (no separate reasoning model; complex fallback)"
+            )
+        else:
+            reasons.append(f"{slot_name} slot → {model}")
+
+    return RouteDecision(
+        tier=tier,
+        model=model,
+        hint=raw_hint,
+        step_kind=step_kind.value if step_kind else None,
+        tier_source=tier_source,
+        model_source=model_source,
+        reasons=tuple(reasons),
+        tiers=describe_tiers(tiers),
+    )
+
+
+def _should_use_code_model(
+    prompt: str,
+    tier: ComplexityTier,
+    hint: str | StepKind | None,
+    step_kind: StepKind | None,
+    tiers: TierMap,
+) -> bool:
+    if prefer_code_model(hint) or step_kind == StepKind.CODE:
+        return True
+    if tiers.code is None:
+        return False
+    if tier not in (ComplexityTier.COMPLEX, ComplexityTier.MEDIUM):
+        return False
+    return looks_like_code(prompt)

split_stack/session.py

@@ -0,0 +1,259 @@
+"""Minimal session: set VRAM once, route every call."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from split_stack.model_registry import normalize_deployment_profile
+from split_stack.models import ComplexityTier, RouteDecision, TierMap
+from split_stack.presets import recommended_models
+from split_stack.routing import explain_route, route_prompt
+from split_stack.tiering import assign_tiers, describe_tiers
+from split_stack.validation import validate_tier_map
+
+
+@dataclass(frozen=True)
+class Session:
+    profile: str
+    vram_gb: int | None
+    quant: str
+    models: tuple[str, ...]
+    tiers: TierMap
+    warnings: tuple[str, ...] = ()
+    note: str | None = None
+
+
+_session: Session | None = None
+
+
+def profile_for_vram_gb(vram_gb: int) -> str:
+    """Map discrete GPU VRAM to a workstation deployment profile."""
+    if vram_gb <= 8:
+        return "workstation_8gb"
+    if vram_gb <= 12:
+        return "workstation_12gb"
+    if vram_gb <= 16:
+        return "workstation_16gb"
+    if vram_gb <= 24:
+        return "workstation_24gb"
+    if vram_gb <= 32:
+        return "workstation_32gb"
+    return "datacenter"
+
+
+def _vram_from_env() -> int | None:
+    raw = os.environ.get("SPLIT_STACK_VRAM_GB", "").strip()
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        return None
+    return value if value > 0 else None
+
+
+def _profile_from_env() -> str | None:
+    raw = os.environ.get("SPLIT_STACK_PROFILE", "").strip()
+    return raw or None
+
+
+def default_profile_from_env(*, fallback: str = "workstation_12gb") -> str:
+    """Profile from SPLIT_STACK_PROFILE or SPLIT_STACK_VRAM_GB, else fallback."""
+    profile = _profile_from_env()
+    if profile:
+        return normalize_deployment_profile(profile)
+    vram = _vram_from_env()
+    if vram is not None:
+        return profile_for_vram_gb(vram)
+    return fallback
+
+
+def _quant_from_env() -> str | None:
+    from split_stack.quantization import quant_from_env
+
+    return quant_from_env()
+
+
+def _resolve_models(
+    profile: str,
+    models: list[str] | None,
+    *,
+    quant: str | None = None,
+) -> tuple[list[str], str | None]:
+    if models:
+        return models, None
+
+    from split_stack.quantization import normalize_quant_mode
+
+    desired = recommended_models(profile, quant=quant)
+    note: str | None = None
+    mode = normalize_quant_mode(quant)
+    if mode == "qat" and len(desired) > len(recommended_models(profile)):
+        note = "QAT stack: added Gemma 4 models that fit at int4 runtime sizes."
+    try:
+        from split_stack.discovery import discover_models_from_disk
+
+        disk = discover_models_from_disk()
+    except Exception:
+        disk = []
+
+    if disk:
+        matched = [name for name in desired if name in disk]
+        if len(matched) >= 2:
+            return matched, None
+        if len(disk) >= 2:
+            from split_stack.model_registry import load_registry, model_weight
+
+            registry = load_registry(profile=profile)
+            ranked = sorted(disk, key=lambda name: model_weight(name, registry))
+            note = (
+                f"Recommended stack not fully installed ({', '.join(desired)}). "
+                f"Using: {', '.join(ranked[:3])}"
+            )
+            return ranked[:3], note
+        note = f"Using installed models only: {', '.join(disk)}"
+        return disk, note
+
+    return desired, "Using recommended stack (not verified against disk)."
+
+
+def configure(
+    *,
+    vram_gb: int | None = None,
+    profile: str | None = None,
+    models: list[str] | None = None,
+    tiers: TierMap | None = None,
+    quant: str | None = None,
+) -> Session:
+    """Set the default profile and tier map for ``route()`` and ``explain()``.
+
+    Progressive control:
+    - ``configure(vram_gb=16)`` — preset profile and recommended models
+    - ``configure(..., models=[...])`` — explicit model list, auto tier ladder
+    - ``configure(..., models=[...], tiers=...)`` — explicit ladder (power users)
+    """
+    global _session
+    from split_stack.quantization import normalize_quant_mode
+
+    if quant is None:
+        quant = _quant_from_env()
+    quant_mode = normalize_quant_mode(quant)
+
+    if profile is None:
+        profile = _profile_from_env()
+    if profile is None:
+        if vram_gb is None:
+            vram_gb = _vram_from_env()
+        if vram_gb is None:
+            raise ValueError(
+                "Pass vram_gb=16 (or profile='workstation_16gb'), "
+                "or set SPLIT_STACK_VRAM_GB / SPLIT_STACK_PROFILE."
+            )
+        profile = profile_for_vram_gb(vram_gb)
+    else:
+        profile = normalize_deployment_profile(profile)
+        if vram_gb is None:
+            vram_gb = _vram_from_env()
+
+    resolved_models, note = _resolve_models(profile, models, quant=quant_mode)
+    if not resolved_models:
+        raise ValueError(f"No models for profile {profile}")
+
+    if tiers is not None:
+        tier_map = tiers
+        if models is not None:
+            unknown = [
+                name
+                for name in (
+                    tier_map.simple,
+                    tier_map.medium,
+                    tier_map.complex,
+                    tier_map.reasoning,
+                    tier_map.code,
+                )
+                if name and name not in resolved_models
+            ]
+            if unknown:
+                raise ValueError(
+                    f"tiers= references models not in models=: {', '.join(sorted(set(unknown)))}"
+                )
+    else:
+        tier_map = assign_tiers(resolved_models)
+    warnings = tuple(validate_tier_map(tier_map, resolved_models, profile=profile))
+    _session = Session(
+        profile=profile,
+        vram_gb=vram_gb,
+        quant=quant_mode,
+        models=tuple(resolved_models),
+        tiers=tier_map,
+        warnings=warnings,
+        note=note,
+    )
+    return _session
+
+
+def get_session() -> Session | None:
+    return _session
+
+
+def session_warnings() -> tuple[str, ...]:
+    """Warnings from the last ``configure()`` (empty if none)."""
+    session = _session
+    return session.warnings if session else ()
+
+
+def _ensure_session() -> Session:
+    session = _session
+    if session is None:
+        if _vram_from_env() is not None or _profile_from_env() is not None:
+            configure()
+            session = _session
+        else:
+            raise RuntimeError(
+                "split_stack.configure(vram_gb=16) first, or set SPLIT_STACK_VRAM_GB."
+            )
+    assert session is not None
+    return session
+
+
+def route(
+    prompt: str,
+    *,
+    hint: str | None = None,
+) -> tuple[ComplexityTier, str]:
+    """Route one prompt using the configured session. Call ``configure()`` first."""
+    session = _ensure_session()
+    return route_prompt(prompt, session.tiers, hint=hint)
+
+
+def explain(
+    prompt: str,
+    *,
+    hint: str | None = None,
+) -> RouteDecision:
+    """Route with a full decision trace (logging, CLI, tests)."""
+    session = _ensure_session()
+    return explain_route(prompt, session.tiers, hint=hint)
+
+
+def describe_session() -> dict[str, object]:
+    """Snapshot of the active session for logs and ``stack explain`` without a prompt."""
+    session = get_session()
+    if session is None:
+        return {"configured": False}
+    return {
+        "configured": True,
+        "profile": session.profile,
+        "vram_gb": session.vram_gb,
+        "quant": session.quant,
+        "models": list(session.models),
+        "tiers": describe_tiers(session.tiers),
+        "warnings": list(session.warnings),
+        "note": session.note,
+    }
+
+
+def reset_session_for_tests() -> None:
+    global _session
+    _session = None