split-stack 0.2.0__py3-none-any.whl

split_stack/setup_wizard.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from split_stack.discovery import discover_models
+from split_stack.model_registry import normalize_deployment_profile
+from split_stack.presets import RECOMMENDED_STACKS, assign_recommended_tiers, list_recommended_stacks, recommended_models
+from split_stack.tiering import describe_tiers
+
+
+@dataclass(frozen=True)
+class SetupPlan:
+    profile: str
+    description: str
+    models: tuple[str, ...]
+    installed: tuple[str, ...]
+    missing: tuple[str, ...]
+    config_path: Path
+
+
+@dataclass(frozen=True)
+class SetupResult:
+    profile: str
+    config_path: Path
+    pulled: tuple[str, ...]
+    skipped: tuple[str, ...]
+    already_present: tuple[str, ...]
+    tiers: dict[str, str | None]
+    cancelled: bool = False
+    dry_run: bool = False
+    error: str | None = None
+
+    @property
+    def ready(self) -> bool:
+        return self.error is None and not self.cancelled
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def default_config_path() -> Path:
+    return Path.cwd() / "split-stack.models.json"
+
+
+def model_is_installed(tag: str, installed: list[str]) -> bool:
+    wanted = tag.lower()
+    for name in installed:
+        lowered = name.lower()
+        if lowered == wanted or lowered.startswith(f"{wanted}:"):
+            return True
+        if wanted in lowered and ":" in wanted:
+            return True
+    return False
+
+
+def plan_setup(
+    profile: str,
+    *,
+    base_url: str = "http://127.0.0.1:11434",
+    config_path: Path | None = None,
+) -> SetupPlan:
+    profile_name = normalize_deployment_profile(profile)
+    stack = RECOMMENDED_STACKS[profile_name]
+    installed = discover_models(base_url=base_url)
+    missing = [tag for tag in stack.models if not model_is_installed(tag, installed)]
+    present = [tag for tag in stack.models if model_is_installed(tag, installed)]
+    return SetupPlan(
+        profile=profile_name,
+        description=stack.description,
+        models=stack.models,
+        installed=tuple(present),
+        missing=tuple(missing),
+        config_path=config_path or default_config_path(),
+    )
+
+
+def pull_model(
+    tag: str,
+    *,
+    base_url: str = "http://127.0.0.1:11434",
+    timeout_seconds: int = 3600,
+) -> None:
+    try:
+        import requests
+    except ImportError as exc:
+        raise RuntimeError(
+            "pull_model requires optional dependency: pip install split-stack[ollama]"
+        ) from exc
+
+    response = requests.post(
+        f"{base_url.rstrip('/')}/api/pull",
+        json={"name": tag, "stream": False},
+        timeout=timeout_seconds,
+    )
+    response.raise_for_status()
+
+
+def write_setup_config(profile: str, config_path: Path) -> None:
+    profile_name = normalize_deployment_profile(profile)
+    template_path = _repo_root() / "config" / "models.example.json"
+    if template_path.is_file():
+        payload = json.loads(template_path.read_text(encoding="utf-8"))
+    else:
+        payload = {"models": []}
+    payload["deployment_profile"] = profile_name
+    payload["comment"] = f"Generated by stack setup ({profile_name}). Edit models[] if your tags differ."
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def prompt_profile_choice() -> str:
+    stacks = list_recommended_stacks()
+    print("Choose your GPU preset:")
+    for index, stack in enumerate(stacks, start=1):
+        print(f"  {index}. {stack.profile} — {stack.description}")
+    print("")
+    while True:
+        raw = input(f"Preset [1-{len(stacks)}] (default 2 = workstation_12gb): ").strip()
+        if not raw:
+            return "workstation_12gb"
+        if raw.isdigit():
+            choice = int(raw)
+            if 1 <= choice <= len(stacks):
+                return stacks[choice - 1].profile
+        lowered = raw.lower()
+        try:
+            return normalize_deployment_profile(lowered)
+        except ValueError:
+            print("Enter a preset number or name like workstation_12gb / 12gb.")
+
+
+def prompt_download_consent(*, missing: tuple[str, ...]) -> bool:
+    if not missing:
+        return True
+    print("")
+    print(f"Ollama will download {len(missing)} model(s) (large files, one-time):")
+    for tag in missing:
+        print(f"  - {tag}")
+    print("")
+    answer = input("Proceed with download? [y/N]: ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+def run_setup(
+    profile: str | None = None,
+    *,
+    base_url: str = "http://127.0.0.1:11434",
+    config_path: Path | None = None,
+    assume_yes: bool = False,
+    dry_run: bool = False,
+    interactive: bool = True,
+) -> SetupResult:
+    chosen = profile
+    if not chosen and interactive:
+        chosen = prompt_profile_choice()
+    if not chosen:
+        chosen = "workstation_12gb"
+
+    path = config_path or default_config_path()
+    try:
+        plan = plan_setup(chosen, base_url=base_url, config_path=path)
+    except Exception as exc:
+        return SetupResult(
+            profile=chosen,
+            config_path=path,
+            pulled=(),
+            skipped=(),
+            already_present=(),
+            tiers={},
+            error=str(exc),
+        )
+
+    if dry_run:
+        tiers = describe_tiers(assign_recommended_tiers(plan.profile))
+        return SetupResult(
+            profile=plan.profile,
+            config_path=plan.config_path,
+            pulled=(),
+            skipped=plan.missing,
+            already_present=plan.installed,
+            tiers=tiers,
+            dry_run=True,
+        )
+
+    if plan.missing and not assume_yes and interactive:
+        if not prompt_download_consent(missing=plan.missing):
+            return SetupResult(
+                profile=plan.profile,
+                config_path=plan.config_path,
+                pulled=(),
+                skipped=plan.missing,
+                already_present=plan.installed,
+                tiers={},
+                cancelled=True,
+            )
+
+    pulled: list[str] = []
+    errors: list[str] = []
+    for tag in plan.missing:
+        try:
+            print(f"Pulling {tag}...", flush=True)
+            pull_model(tag, base_url=base_url)
+            pulled.append(tag)
+        except Exception as exc:
+            errors.append(f"{tag}: {exc}")
+
+    try:
+        write_setup_config(plan.profile, plan.config_path)
+        tiers = describe_tiers(assign_recommended_tiers(plan.profile))
+    except Exception as exc:
+        errors.append(str(exc))
+        tiers = {}
+
+    if errors:
+        return SetupResult(
+            profile=plan.profile,
+            config_path=plan.config_path,
+            pulled=tuple(pulled),
+            skipped=tuple([tag for tag in plan.missing if tag not in pulled]),
+            already_present=plan.installed,
+            tiers=tiers,
+            error="; ".join(errors),
+        )
+
+    return SetupResult(
+        profile=plan.profile,
+        config_path=plan.config_path,
+        pulled=tuple(pulled),
+        skipped=(),
+        already_present=plan.installed,
+        tiers=tiers,
+    )
+
+
+def format_setup_summary(result: SetupResult) -> str:
+    lines = [
+        f"profile={result.profile}",
+        f"config={result.config_path}",
+    ]
+    if result.already_present:
+        lines.append(f"already_present={','.join(result.already_present)}")
+    if result.pulled:
+        lines.append(f"pulled={','.join(result.pulled)}")
+    if result.skipped:
+        lines.append(f"not_installed={','.join(result.skipped)}")
+    if result.tiers:
+        lines.append("tiers:")
+        for key, value in result.tiers.items():
+            lines.append(f"  {key}: {value or '-'}")
+    if result.cancelled:
+        lines.append("status=cancelled (no downloads)")
+    if result.dry_run:
+        lines.append("status=dry-run")
+    if result.error:
+        lines.append(f"error={result.error}")
+    return "\n".join(lines)

split_stack/startup_tips.py

@@ -0,0 +1,169 @@
+"""Import-time and CLI tips: scan local models and surface community recommendations."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+logger = logging.getLogger("split_stack")
+
+_emitted = False
+
+
+def _import_tips_mode() -> str:
+    return os.environ.get("SPLIT_STACK_IMPORT_TIPS", "off").strip().lower()
+
+
+def _is_disabled(mode: str) -> bool:
+    return mode in {"0", "false", "no", "off", "quiet"}
+
+
+def _should_echo_stderr(mode: str) -> bool:
+    if mode in {"1", "true", "yes", "stderr", "on"}:
+        return True
+    if mode != "auto":
+        return False
+    if not sys.stderr.isatty():
+        return False
+    if logger.handlers:
+        return False
+    root = logging.getLogger()
+    return not root.handlers
+
+
+def _default_report_profile() -> str:
+    from split_stack.session import default_profile_from_env
+
+    return default_profile_from_env()
+
+
+def model_recommendation_report(
+    *,
+    profile: str | None = None,
+    include_api: bool = False,
+    base_url: str = "http://127.0.0.1:11434",
+) -> list[str]:
+    """Build human-readable lines about installed vs recommended models."""
+    from split_stack.community_picks import (
+        focus_stack,
+        recommended_models_for_tier,
+        vram_tier_for_profile,
+    )
+    from split_stack.discovery import audit_model_folders, discover_models_from_disk, list_model_inventory
+    from split_stack.model_registry import normalize_deployment_profile
+
+    profile_name = normalize_deployment_profile(profile or _default_report_profile())
+    vram_tier = vram_tier_for_profile(profile)
+
+    if include_api:
+        inventory = list_model_inventory(base_url=base_url)
+        installed = sorted(set(inventory.api_models) | set(inventory.disk_models))
+        primary = inventory.manifest_roots[0] if inventory.manifest_roots else None
+    else:
+        installed = discover_models_from_disk()
+        audit = audit_model_folders()
+        primary = audit.get("primary_root")
+
+    lines: list[str] = []
+    if not installed:
+        lines.append("split-stack: no local Ollama models found on disk.")
+        lines.append(
+            "  Starter agent stack: ollama pull gemma4:e4b && "
+            "ollama pull qwen3:8b && ollama pull qwen3:14b"
+        )
+        lines.append("  Then: stack models --include-disk")
+        return lines
+
+    header = f"split-stack: {len(installed)} local model(s)"
+    if primary:
+        header += f" under {primary}"
+    lines.append(f"{header} (profile {profile_name}, tier {vram_tier}).")
+
+    stack = focus_stack("agentic", vram_tier=vram_tier)
+    if stack and stack.models:
+        have = [name for name in stack.models if name in installed]
+        missing_stack = [name for name in stack.models if name not in installed]
+        lines.append(f"  Reddit agent stack: {', '.join(stack.models)}")
+        if have:
+            lines.append(f"  Installed from stack: {', '.join(have)}")
+        if missing_stack:
+            lines.append(f"  Pull for routing spread: {', '.join(missing_stack)}")
+
+    installed_lower = {name.lower() for name in installed}
+    recommended = recommended_models_for_tier(vram_tier=vram_tier)
+    missing_picks: list[str] = []
+    for model_name in recommended:
+        lowered = model_name.lower()
+        if lowered in installed_lower:
+            continue
+        if any(lowered in name or name.startswith(lowered) for name in installed_lower):
+            continue
+        missing_picks.append(model_name)
+
+    if missing_picks:
+        preview = ", ".join(missing_picks[:6])
+        if len(missing_picks) > 6:
+            preview += ", ..."
+        lines.append(f"  Community picks to explore: {preview}")
+
+    extras = sorted(
+        name
+        for name in installed
+        if stack and name not in stack.models and name not in recommended
+    )
+    if extras:
+        preview = ", ".join(extras[:6])
+        if len(extras) > 6:
+            preview += ", ..."
+        lines.append(f"  Also on disk (not in default stack): {preview}")
+
+    audit = audit_model_folders()
+    duplicate_tags = audit.get("duplicate_tags") or []
+    if duplicate_tags:
+        lines.append(
+            "  Duplicate tags across folders: "
+            f"{', '.join(duplicate_tags)} — keep one Ollama models directory."
+        )
+
+    lines.append("  Commands: stack models --include-disk  |  stack tips  |  stack stacks")
+    return lines
+
+
+def emit_import_tips(
+    *,
+    profile: str | None = None,
+    include_api: bool = False,
+    base_url: str = "http://127.0.0.1:11434",
+) -> None:
+    """Log model recommendations once per process (controlled by SPLIT_STACK_IMPORT_TIPS)."""
+    global _emitted
+    if _emitted:
+        return
+
+    mode = _import_tips_mode()
+    if _is_disabled(mode):
+        return
+
+    _emitted = True
+    try:
+        lines = model_recommendation_report(
+            profile=profile or _default_report_profile(),
+            include_api=include_api,
+            base_url=base_url,
+        )
+    except Exception as exc:
+        logger.debug("split-stack import tips skipped: %s", exc)
+        return
+
+    for line in lines:
+        logger.info(line)
+
+    if _should_echo_stderr(mode):
+        print("\n".join(lines), file=sys.stderr)
+
+
+def reset_import_tips_for_tests() -> None:
+    """Allow tests to re-run emit_import_tips."""
+    global _emitted
+    _emitted = False

split_stack/tiering.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from split_stack.model_registry import ModelRegistry, load_registry, model_weight
+from split_stack.models import TierMap
+
+
+def _is_code_specialist(name: str) -> bool:
+    lowered = name.lower()
+    if "reasoning" in lowered:
+        return False
+    tokens = ("codellama", "deepseek-coder", "starcoder", "codegemma", "coder")
+    return any(token in lowered for token in tokens)
+
+
+def _is_reasoning_specialist(name: str) -> bool:
+    lowered = name.lower()
+    return "deepseek-r1" in lowered or "reasoning" in lowered or ":r1" in lowered
+
+
+def assign_tiers(model_names: list[str], registry: ModelRegistry | None = None) -> TierMap:
+    if not model_names:
+        raise ValueError("model_names must contain at least one model")
+
+    reg = registry or load_registry()
+    code_models = [name for name in model_names if _is_code_specialist(name)]
+    general_models = [name for name in model_names if name not in code_models]
+    if not general_models:
+        general_models = list(model_names)
+        code_models = []
+
+    reasoning_models = [name for name in general_models if _is_reasoning_specialist(name)]
+    core_models = [name for name in general_models if name not in reasoning_models]
+    if not core_models:
+        core_models = list(general_models)
+
+    ranked = sorted(core_models, key=lambda name: model_weight(name, reg))
+    simple = ranked[0]
+    complex_model = ranked[-1]
+    medium = ranked[1] if len(ranked) > 1 else ranked[0]
+
+    if reasoning_models:
+        reasoning = sorted(reasoning_models, key=lambda name: model_weight(name, reg))[-1]
+    else:
+        reasoning = complex_model
+
+    code = None
+    if code_models:
+        code = sorted(code_models, key=lambda name: model_weight(name, reg))[-1]
+
+    return TierMap(
+        simple=simple,
+        medium=medium,
+        complex=complex_model,
+        reasoning=reasoning,
+        code=code,
+    )
+
+
+def describe_tiers(tiers: TierMap) -> dict[str, str | None]:
+    return {
+        "simple": tiers.simple,
+        "medium": tiers.medium,
+        "complex": tiers.complex,
+        "reasoning": tiers.reasoning,
+        "code": tiers.code,
+    }

split_stack/validation.py

@@ -0,0 +1,85 @@
+"""Session and tier-map validation — warnings, not hard failures."""
+
+from __future__ import annotations
+
+from split_stack.model_registry import load_registry, model_weight
+from split_stack.models import TierMap
+from split_stack.tiering import describe_tiers
+
+
+def _is_reasoning_specialist(name: str) -> bool:
+    lowered = name.lower()
+    return "deepseek-r1" in lowered or "reasoning" in lowered or ":r1" in lowered
+
+
+def _is_code_specialist(name: str) -> bool:
+    lowered = name.lower()
+    if "reasoning" in lowered:
+        return False
+    tokens = ("codellama", "deepseek-coder", "starcoder", "codegemma", "coder")
+    return any(token in lowered for token in tokens)
+
+
+def validate_tier_map(
+    tiers: TierMap,
+    models: list[str] | tuple[str, ...],
+    *,
+    profile: str | None = None,
+) -> list[str]:
+    """Return human-readable warnings about a tier ladder."""
+    warnings: list[str] = []
+    model_list = list(models)
+    registry = load_registry(profile=profile)
+
+    if len(model_list) < 2:
+        warnings.append("Fewer than two models — routing cannot spread across tiers.")
+
+    slot_models = {
+        tiers.simple,
+        tiers.medium,
+        tiers.complex,
+        tiers.reasoning,
+    }
+    if tiers.code:
+        slot_models.add(tiers.code)
+    unique_slots = len(slot_models)
+    if unique_slots < min(3, len(model_list)):
+        warnings.append(
+            "Multiple tier slots map to the same model — spread is mostly cosmetic."
+        )
+
+    reasoning_specialists = [name for name in model_list if _is_reasoning_specialist(name)]
+    if not reasoning_specialists and tiers.reasoning == tiers.complex:
+        warnings.append(
+            "No reasoning specialist in models= — hint='reason' uses the complex model "
+            f"({tiers.complex}), not a dedicated reasoner."
+        )
+
+    code_specialists = [name for name in model_list if _is_code_specialist(name)]
+    if not code_specialists:
+        warnings.append(
+            "No code specialist in models= — hint='code' uses the complex tier "
+            f"({tiers.complex}) unless the prompt looks like code."
+        )
+
+    try:
+        simple_w = model_weight(tiers.simple, registry)
+        medium_w = model_weight(tiers.medium, registry)
+        if simple_w > medium_w:
+            warnings.append(
+                f"Simple slot ({tiers.simple}, weight {simple_w}) is heavier than "
+                f"medium ({tiers.medium}, weight {medium_w}) — check registry rows for "
+                "unknown tags (heuristic weight 1000)."
+            )
+    except Exception:
+        pass
+
+    described = describe_tiers(tiers)
+    if tiers.simple != model_list[0] and len(model_list) >= 2:
+        ranked = sorted(model_list, key=lambda name: model_weight(name, registry))
+        if tiers.simple != ranked[0]:
+            warnings.append(
+                f"Simple slot is {tiers.simple}; lightest installed tag is {ranked[0]}."
+            )
+
+    return warnings