scootcli 0.2.0__tar.gz → 0.3.0__tar.gz

{scootcli-0.2.0/src/scootcli.egg-info → scootcli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scootcli
-Version: 0.2.0
+Version: 0.3.0
 Summary: A tiny coding agent that goes where you point it
 Author: Sergey Nes
 License-Expression: MIT
@@ -36,7 +36,7 @@ Dynamic: license-file
 ```
        ╭───╮      scoot: a tiny coding agent that goes where you point it.
        │o o│
-    T──┤───┤      pipx install scootcli
+    T──┤───┤      pipx install scootcli   (or: curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash)
     │  ╰┬─┬╯      scoot
   (o)═══╧═╧═(o)
 ```
@@ -106,6 +106,36 @@ scoot --model auto "..."             # pick a model per prompt from the live lis
 ```
 
 Inside the REPL, `/model <provider/model>` switches and is remembered for the next launch; `/model default` goes back to the provider's preferred model.
+
+### Routing
+
+`auto` is opt-in (`--model auto`, `SCOOT_MODEL=auto`, or `/model auto`) because choosing costs a decision per turn.
+Without any configuration it uses a built-in heuristic over the models your providers actually list: a strong coding model for multi-step or editing prompts, a cheaper one for short questions, never a dated snapshot.
+A turn is routed once, at its first model call, and stays on that model.
+
+Write your own rules in `~/.config/scoot/router.json` (or the file named by `SCOOT_ROUTER`); first match wins, and a rule whose provider has no key is skipped:
+
+```json
+{
+  "rules": [
+    {"when": {"has_images": true},        "use": "anthropic/claude-opus-5"},
+    {"when": {"complex": true},           "use": "openai/gpt-5.3-codex"},
+    {"when": {"est_tokens_over": 60000},  "use": "anthropic/claude-sonnet-5"},
+    {"when": {"prompt_matches": "(?i)translate|summari[sz]e"}, "use": "ollama/qwen3"}
+  ],
+  "default": "ollama/llama3.2",
+  "classifier": {
+    "model": "ollama/llama3.2",
+    "tiers": {"simple": "ollama/llama3.2", "coding": "openai/gpt-5.3-codex", "hard": "anthropic/claude-opus-5"}
+  }
+}
+```
+
+Conditions: `complex`, `has_images`, `needs_tools`, `est_tokens_over`, `prompt_matches`.
+The optional `classifier` asks a small model one question per turn ("simple, coding, or hard?") and maps the answer to a tier; it adds a short call, and any failure falls through to the rules.
+Expect it to be rough with a 3B local model: on a hand-labelled set of seven prompts, `llama3.2` and `qwen2.5` each got four right, mostly confusing "coding" with "hard".
+The rules are deterministic, so put the decisions you care about there, and if you want a better judge, name a cheap hosted model as the classifier (`openai/gpt-5-mini`), which costs a few hundred tokens per turn.
+`/route` shows the rules in force and why the current model was picked; `/status` shows tokens per model.
 `SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it, on both OpenAI and Anthropic.
 On Claude Opus 5 the server-side refusal fallback is requested by default, so a declined request is retried on another Claude model inside the same call; `SCOOT_ANTHROPIC_FALLBACKS=0` turns that off.
 
@@ -205,11 +235,14 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 
 ```bash
 pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
 git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e .                       # from source
 ```
 
+The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.
 

{scootcli-0.2.0 → scootcli-0.3.0}/README.md

@@ -11,7 +11,7 @@
 ```
        ╭───╮      scoot: a tiny coding agent that goes where you point it.
        │o o│
-    T──┤───┤      pipx install scootcli
+    T──┤───┤      pipx install scootcli   (or: curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash)
     │  ╰┬─┬╯      scoot
   (o)═══╧═╧═(o)
 ```
@@ -81,6 +81,36 @@ scoot --model auto "..."             # pick a model per prompt from the live lis
 ```
 
 Inside the REPL, `/model <provider/model>` switches and is remembered for the next launch; `/model default` goes back to the provider's preferred model.
+
+### Routing
+
+`auto` is opt-in (`--model auto`, `SCOOT_MODEL=auto`, or `/model auto`) because choosing costs a decision per turn.
+Without any configuration it uses a built-in heuristic over the models your providers actually list: a strong coding model for multi-step or editing prompts, a cheaper one for short questions, never a dated snapshot.
+A turn is routed once, at its first model call, and stays on that model.
+
+Write your own rules in `~/.config/scoot/router.json` (or the file named by `SCOOT_ROUTER`); first match wins, and a rule whose provider has no key is skipped:
+
+```json
+{
+  "rules": [
+    {"when": {"has_images": true},        "use": "anthropic/claude-opus-5"},
+    {"when": {"complex": true},           "use": "openai/gpt-5.3-codex"},
+    {"when": {"est_tokens_over": 60000},  "use": "anthropic/claude-sonnet-5"},
+    {"when": {"prompt_matches": "(?i)translate|summari[sz]e"}, "use": "ollama/qwen3"}
+  ],
+  "default": "ollama/llama3.2",
+  "classifier": {
+    "model": "ollama/llama3.2",
+    "tiers": {"simple": "ollama/llama3.2", "coding": "openai/gpt-5.3-codex", "hard": "anthropic/claude-opus-5"}
+  }
+}
+```
+
+Conditions: `complex`, `has_images`, `needs_tools`, `est_tokens_over`, `prompt_matches`.
+The optional `classifier` asks a small model one question per turn ("simple, coding, or hard?") and maps the answer to a tier; it adds a short call, and any failure falls through to the rules.
+Expect it to be rough with a 3B local model: on a hand-labelled set of seven prompts, `llama3.2` and `qwen2.5` each got four right, mostly confusing "coding" with "hard".
+The rules are deterministic, so put the decisions you care about there, and if you want a better judge, name a cheap hosted model as the classifier (`openai/gpt-5-mini`), which costs a few hundred tokens per turn.
+`/route` shows the rules in force and why the current model was picked; `/status` shows tokens per model.
 `SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it, on both OpenAI and Anthropic.
 On Claude Opus 5 the server-side refusal fallback is requested by default, so a declined request is retried on another Claude model inside the same call; `SCOOT_ANTHROPIC_FALLBACKS=0` turns that off.
 
@@ -180,11 +210,14 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 
 ```bash
 pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
 git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e .                       # from source
 ```
 
+The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.
 

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/__init__.py

@@ -1,4 +1,4 @@
 """scoot: a tiny coding agent that goes where you point it."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/agent.py

@@ -129,7 +129,10 @@ class Agent:
             except ScootError as exc:
                 return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
 
-            session.account(result.usage)
+            try:
+                session.account(result.usage, model=result.model or session.active_model)
+            except TypeError:  # older/fake sessions with a one-argument account()
+                session.account(result.usage)
             session.messages.append(self._assistant_message(result))
 
             if result.tool_calls:
@@ -187,19 +190,33 @@ class Agent:
 
     # ── message construction ─────────────────────────────────────────────────────
     def _pick_model(self, session) -> str:
-        """Resolve the model for this turn. For ``auto``, use the heuristic over live models."""
+        """Resolve the model for this turn. ``auto`` routes once per turn (see ``providers.router``)."""
         if session.model.lower() != "auto":
             return session.resolved_model()
-        from .models import resolve_auto
+        from .providers.router import Router, compute_hints
 
-        last_user = self._last_user_text(session)
+        router = getattr(session, "router", None)
+        if router is None:
+            router = Router()
+            try:
+                session.router = router
+            except Exception:
+                pass
         try:
             available = session.available_models()
         except Exception:
             available = []
         bad = getattr(session, "bad_models", None) or set()
         available = [m for m in available if m not in bad] or available
-        return resolve_auto(last_user, available, fallback=session.resolved_model())
+        hints = compute_hints(session)
+        return router.choose(session, hints, available, session.resolved_model(),
+                             classify=self._classify_with_provider).model
+
+    def _classify_with_provider(self, model: str, prompt: str) -> str:
+        """One small, non-streaming call used by a configured router classifier."""
+        result = self.provider.chat([{"role": "user", "content": prompt}], model=model, max_tokens=5,
+                                    temperature=0, hints={"purpose": "route"})
+        return result.content or ""
 
     def _fallback_model(self, session) -> bool:
         """After a model-unavailable error, blacklist it and switch models. Returns False if stuck."""

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/auth.py

@@ -43,14 +43,19 @@ def status_rows(config) -> List[dict]:
     default = registry.default_provider_name(config)
     rows = []
     for spec in registry.all_specs():
-        rows.append({
+        url = registry.base_url_for(spec)
+        row = {
             "name": spec.name,
             "source": key_source(spec),
             "required": spec.key_required,
             "configured": is_configured(spec),
             "default": spec.name == default,
-            "base_url": registry.base_url_for(spec),
-        })
+            "base_url": url,
+            "reachable": None,  # only probed for keyless local servers
+        }
+        if not spec.key_required and registry.is_local_url(url):
+            row["reachable"] = registry.reachable(url)
+        rows.append(row)
     return rows
 
 

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/cli.py

@@ -141,6 +141,16 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
     from .agent import Agent
     from .repl import ReplSession, ReplUI
 
+    from .providers.registry import readiness
+
+    ready, message = readiness(config)
+    if not ready:  # fail fast with guidance instead of a connection error after retries
+        if as_json:
+            print(_json.dumps({"status": "error", "model": "", "steps": 0, "content": "",
+                               "error": message, "usage": {}}, indent=2))
+        else:
+            eprint(color(message, "yellow"))
+        return 1
     session = ReplSession(config, pool)
     if resume is not None:
         session.apply_record(resume)
@@ -194,7 +204,6 @@ def _cmd_auth(config: Config, pool: ProviderPool, words: List[str]) -> int:
 
 def _interactive(pool: ProviderPool, resume=None) -> int:
     """Launch the persistent REPL (banner, live status, ESC-interrupt, slash-commands)."""
-    from .auth import is_configured, missing_key_hint
     from .repl import Repl
 
     config = pool.config
@@ -206,9 +215,11 @@ def _interactive(pool: ProviderPool, resume=None) -> int:
         resume = sessions.latest_for_root(str(config.root))
 
     try:
-        spec = pool.spec
-        if not is_configured(spec):  # first-run onboarding: guide, but still open the REPL
-            eprint(color(f"No API key for {spec.name}: {missing_key_hint(spec)}", "yellow"))
+        from .providers.registry import readiness
+
+        ready, message = readiness(config)
+        if not ready:  # first-run onboarding: guide, but still open the REPL so /auth is usable
+            eprint(color(message, "yellow"))
     except ScootError as exc:
         eprint(color(f"⚠ {redact(str(exc))}", "yellow"))
     return Repl(config, pool, resume=resume).run()

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/commands/__init__.py

@@ -51,6 +51,7 @@ def load_builtins() -> None:
     from . import verbosity as _verbosity  # noqa: F401
     from . import copy as _copy  # noqa: F401
     from . import logo as _logo  # noqa: F401
+    from . import route as _route  # noqa: F401
 
     _loaded = True
 

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/commands/auth.py

@@ -24,8 +24,10 @@ def _show(session) -> None:
     print(color("providers:", "bold"))
     for row in rows:
         name = row["name"] + ("  (default)" if row["default"] else "")
-        if not row["required"]:
-            state = color("no key needed", "gray")
+        if not row["required"] and row.get("reachable") is False:
+            state = color("not running (ollama serve; install from https://ollama.com)", "yellow")
+        elif not row["required"]:
+            state = color("no key needed" + (", running" if row.get("reachable") else ""), "gray")
         elif row["source"]:
             state = color(f"key from {row['source']}", "green")
         else:

scootcli-0.3.0/src/scootcli/commands/route.py

@@ -0,0 +1,21 @@
+"""/route — show how the ``auto`` model alias routes: rule source, rules, classifier, last decision."""
+
+from __future__ import annotations
+
+from ..providers.router import Router, config_path, describe
+from ..rendering import color
+from . import register
+from .base import SlashCommand
+
+
+def _run(session, args: str):
+    router = getattr(session, "router", None) or Router()
+    print(color("routing (for /model auto):", "bold"))
+    for line in describe(router):
+        print("  " + line)
+    if session.model.lower() != "auto":
+        print(color(f"  auto is off; the preference is '{session.model}'. Turn it on with /model auto.", "gray"))
+    print(color(f"  edit rules in {config_path()} (see README: Routing)", "gray"))
+
+
+register(SlashCommand("route", "show how 'auto' picks a model", _run))

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/commands/status.py

@@ -42,6 +42,13 @@ def _run(session, args: str):
     print(color("status:", "bold"))
     for label, value in rows:
         print(f"  {color(label + ':', 'gray'):<28} {value}")
+    by_model = getattr(session, "usage_by_model", None) or {}
+    if len(by_model) > 1 or (by_model and session.model.lower() == "auto"):
+        print(f"  {color('tokens by model:', 'gray')}")
+        for name, u in sorted(by_model.items(), key=lambda kv: -(kv[1]['prompt'] + kv[1]['completion'])):
+            print(f"    {color(name, 'cyan'):<40} prompt={u['prompt']} completion={u['completion']} calls={u['calls']}")
+    if session.model.lower() == "auto" and getattr(session, "route_reason", ""):
+        print(f"  {color('routed by:', 'gray'):<28} {session.route_reason}")
     trusted = getattr(session, "trusted_tools", None)
     if trusted:
         print(f"  {color('trusted tools:', 'gray'):<28} {', '.join(sorted(trusted))}")

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/providers/base.py

@@ -21,6 +21,7 @@ from ..errors import (
     ContextLengthError,
     Interrupted,
     ModelUnavailableError,
+    NetworkError,
     QuotaError,
     RETRIABLE,
     RateLimitError,
@@ -321,12 +322,27 @@ class BaseProvider:
 
     # ── retry policy ─────────────────────────────────────────────────────────────
     def _with_retry(self, fn: Callable[[], ChatResult], cancel_event, emitted=None) -> ChatResult:
-        """Retry transient failures with capped, jittered backoff; never after tokens were printed."""
+        """Retry transient failures with capped, jittered backoff; never after tokens were printed.
+
+        A connection failure to a *local* server is not transient (nothing is listening), so it fails
+        at once with a hint about starting the server instead of burning the retry budget.
+        """
+        from .registry import is_local_url
+
         attempt = 0
         while True:
             attempt += 1
             try:
                 return fn()
+            except NetworkError as exc:
+                if is_local_url(self.spec.base_url):
+                    exc.hint = (f"{self.name} is not running at {self.spec.base_url}: start it "
+                                f"(`ollama serve`; install from https://ollama.com) or use another "
+                                f"provider (`scoot auth set openai`)")
+                    raise
+                if attempt >= _RETRY_ATTEMPTS or (emitted is not None and emitted[0]):
+                    raise
+                self._backoff(attempt, cancel_event)
             except RETRIABLE:
                 if attempt >= _RETRY_ATTEMPTS or (emitted is not None and emitted[0]):
                     raise

{scootcli-0.2.0 → scootcli-0.3.0}/src/scootcli/providers/registry.py

@@ -7,8 +7,10 @@ selected by ``spec.wire``. Base URLs can be overridden per provider with ``SCOOT
 from __future__ import annotations
 
 import os
+import socket
 from dataclasses import replace
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Tuple
+from urllib.parse import urlsplit
 
 from ..errors import ConfigError, ScootError
 from .base import BaseProvider, ChatResult, ModelInfo, ProviderSpec, qualify, split_model_id
@@ -89,6 +91,56 @@ def base_url_for(spec: ProviderSpec) -> str:
     return override or spec.base_url
 
 
+def is_local_url(url: str) -> bool:
+    host = (urlsplit(url).hostname or "").lower()
+    return host in ("localhost", "127.0.0.1", "::1", "0.0.0.0") or host.endswith(".localhost")
+
+
+def reachable(url: str, timeout: float = 0.3) -> bool:
+    """One TCP connect to the URL's host and port. Cheap enough to run at startup for a local server."""
+    parts = urlsplit(url)
+    host = parts.hostname or ""
+    port = parts.port or (443 if parts.scheme == "https" else 80)
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+SETUP_HELP = (
+    "No model provider is ready yet. Set one up:\n"
+    "  scoot auth set openai        hosted, needs an OpenAI API key\n"
+    "  scoot auth set anthropic     hosted, needs an Anthropic API key\n"
+    "  ollama pull llama3.2         local and free (install from https://ollama.com), then run scoot again"
+)
+
+
+def readiness(config) -> Tuple[bool, str]:
+    """Whether the default provider can take a request now, and a message when it cannot.
+
+    Hosted providers are ready when a key is present (no network call). A keyless local provider is
+    ready when its server answers a TCP connect; when nothing is configured at all, the message lists
+    every way to get started.
+    """
+    from ..auth import is_configured
+
+    name = default_provider_name(config)
+    spec = get(name)
+    if spec is None:
+        return False, SETUP_HELP
+    if spec.key_required:
+        if is_configured(spec):
+            return True, ""
+        return False, SETUP_HELP
+    url = base_url_for(spec)
+    if reachable(url):
+        return True, ""
+    if any(s.key_required and is_configured(s) for s in all_specs()):
+        return False, f"{name} is not running at {url} (start it with `ollama serve`, or pick another provider with --provider)"
+    return False, SETUP_HELP
+
+
 def make_provider(name: str, config, transport=None) -> BaseProvider:
     """Instantiate the adapter for ``name`` with any base-URL override applied."""
     spec = get(name)
@@ -178,8 +230,12 @@ class ProviderPool:
         for spec in all_specs():
             if not is_configured(spec):
                 continue
+            url = base_url_for(spec)
+            if not spec.key_required and is_local_url(url) and not reachable(url):
+                self.list_errors[spec.name] = f"not running at {url} (start it with `ollama serve`)"
+                continue
             try:
                 out.extend(self.provider(spec.name).list_models(cancel_event=cancel_event))
             except ScootError as exc:
-                self.list_errors[spec.name] = str(exc)
+                self.list_errors[spec.name] = str(exc) + (f" ({exc.hint})" if getattr(exc, "hint", "") else "")
         return out