specsmith 0.11.5.dev452__tar.gz → 0.11.5.dev453__tar.gz

{specsmith-0.11.5.dev452/src/specsmith.egg-info → specsmith-0.11.5.dev453}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.11.5.dev452
+Version: 0.11.5.dev453
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.11.5.dev452"
+version = "0.11.5.dev453"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453}/src/specsmith/agent/chat_runner.py

@@ -34,6 +34,24 @@ from specsmith.agent.verifier import (
 
 DEFAULT_OLLAMA_HOST = "http://127.0.0.1:11434"
 DEFAULT_OLLAMA_MODEL = os.environ.get("SPECSMITH_OLLAMA_MODEL", "qwen2.5:7b")
+
+# Ordered preference list used by _pick_ollama_model() when the default
+# model is not installed.  Lighter / faster models first so the REPL
+# stays responsive on developer hardware.
+_OLLAMA_MODEL_PREFERENCE = [
+    "qwen2.5:7b",
+    "qwen2.5-coder:7b-instruct",
+    "qwen3:8b",
+    "mistral:7b-instruct-q4_0",
+    "llama3:8b-instruct-q4_K_M",
+    "qwen2.5:14b",
+    "qwen2.5-coder:14b",
+    "qwen3:14b",
+    "mistral-nemo:12b",
+    "phi4:14b-q4_K_M",
+    "deepseek-r1:14b",
+    "qwen3:30b-a3b",
+]
 SYSTEM_PROMPT = (
     "You are Nexus, the local-first agentic developer assistant inside "
     "Specsmith. Always end your response with the canonical contract:\n"
@@ -239,6 +257,40 @@ def run_single_prompt(prompt: str, *, max_tokens: int = 500) -> str | None:  # n
 # ---------------------------------------------------------------------------
 
 
+def _ollama_alive(host: str) -> bool:
+    try:
+        with urlopen(f"{host}/api/tags", timeout=2):  # noqa: S310
+            return True
+    except (URLError, TimeoutError, OSError):
+        return False
+
+
+def _pick_ollama_model(host: str) -> str:
+    """Return the best available Ollama model for this machine.
+
+    Checks the installed model list from ``/api/tags`` and walks
+    ``_OLLAMA_MODEL_PREFERENCE`` to find the first match.  Falls back
+    to ``DEFAULT_OLLAMA_MODEL`` when the API is unreachable or the list
+    is empty.  An explicit ``SPECSMITH_OLLAMA_MODEL`` env var always wins.
+    """
+    env_override = os.environ.get("SPECSMITH_OLLAMA_MODEL", "").strip()
+    if env_override:
+        return env_override
+    try:
+        with urlopen(f"{host}/api/tags", timeout=2) as resp:  # noqa: S310
+            data = json.loads(resp.read())
+        installed = {m["name"] for m in data.get("models", []) if m.get("name")}
+        for candidate in _OLLAMA_MODEL_PREFERENCE:
+            if candidate in installed:
+                return candidate
+        # None of the preferred models found — use whatever is first
+        if installed:
+            return sorted(installed)[0]
+    except Exception:  # noqa: BLE001 — best-effort; fall through to default
+        pass
+    return DEFAULT_OLLAMA_MODEL
+
+
 def _run_ollama(
     messages: list[dict[str, str]],
     emitter: EventEmitter,
@@ -246,12 +298,13 @@ def _run_ollama(
 ) -> tuple[str | None, _UsageDelta]:
     """Stream from a local Ollama daemon using only stdlib."""
     host = os.environ.get("OLLAMA_HOST", DEFAULT_OLLAMA_HOST).rstrip("/")
-    model = os.environ.get("SPECSMITH_OLLAMA_MODEL", DEFAULT_OLLAMA_MODEL)
     usage = _UsageDelta()
 
     if not _ollama_alive(host):
         return None, usage
 
+    model = _pick_ollama_model(host)
+
     payload = json.dumps({"model": model, "messages": messages, "stream": True}).encode("utf-8")
     req = Request(  # noqa: S310 - URL is a hardcoded localhost default
         f"{host}/api/chat",
@@ -284,14 +337,6 @@ def _run_ollama(
     return ("".join(pieces) if pieces else None), usage
 
 
-def _ollama_alive(host: str) -> bool:
-    try:
-        with urlopen(f"{host}/api/tags", timeout=2):  # noqa: S310
-            return True
-    except (URLError, TimeoutError, OSError):
-        return False
-
-
 def _run_anthropic(
     messages: list[dict[str, str]],
     emitter: EventEmitter,

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453}/src/specsmith/agent/events.py

@@ -231,4 +231,24 @@ class EventEmitter:
         )
 
 
-__all__ = ["EventEmitter"]
+class PlainTextEmitter(EventEmitter):
+    """Human-readable variant of EventEmitter for interactive terminal sessions.
+
+    Writes LLM token chunks directly to the stream (no JSON wrapping) so
+    ``specsmith run`` without ``--json-events`` produces readable output.
+    All non-token protocol events are silently dropped — system messages
+    are handled separately by ``AgentRunner._default_emit_event``.
+    """
+
+    def token(self, block_id: str, text: str) -> None:  # noqa: ARG002
+        self.stream.write(text)
+        with contextlib.suppress(Exception):
+            self.stream.flush()
+
+    def emit(self, event: dict[str, Any]) -> None:
+        # Drop JSONL protocol frames in plain-text mode; token() handles
+        # the only output that matters for interactive sessions.
+        pass
+
+
+__all__ = ["EventEmitter", "PlainTextEmitter"]

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453}/src/specsmith/agent/runner.py

@@ -27,13 +27,160 @@ from pathlib import Path
 from typing import Any
 
 from specsmith.agent.core import AgentState, ModelTier
-from specsmith.agent.events import EventEmitter
+from specsmith.agent.events import EventEmitter, PlainTextEmitter
 
 # These imports are kept lazy in the public API so that a busted optional
 # dependency (e.g. ``ag2``) doesn't keep the bridge from emitting ``ready``.
 # The import itself happens on the first call that actually needs the
 # orchestrator group chat.
-__all__ = ["AgentRunner", "_capabilities"]
+__all__ = ["AgentRunner", "ProviderStatus", "check_providers", "_capabilities"]
+
+
+# ---------------------------------------------------------------------------
+# Provider health check
+# ---------------------------------------------------------------------------
+
+
+from dataclasses import dataclass  # noqa: E402 — after __all__
+
+
+@dataclass
+class ProviderStatus:
+    """Health snapshot for a single LLM provider."""
+
+    name: str
+    available: bool
+    model: str = ""  # resolved model name (empty when unavailable)
+    note: str = ""  # human-readable reason (error or extra context)
+    model_count: int = 0  # number of installed models (Ollama only)
+
+    @property
+    def icon(self) -> str:
+        return "\u2713" if self.available else "\u2717"
+
+
+def check_providers() -> list[ProviderStatus]:
+    """Probe every supported LLM provider and return a status list.
+
+    Safe to call at any time — never raises, never blocks for more than
+    a couple of seconds.  Used by ``_print_banner`` and ``specsmith run
+    --check``.
+    """
+    import importlib
+    import os
+
+    from specsmith.agent.chat_runner import (
+        _OLLAMA_MODEL_PREFERENCE,
+        DEFAULT_OLLAMA_HOST,
+        DEFAULT_OLLAMA_MODEL,
+        _ollama_alive,
+    )
+
+    results: list[ProviderStatus] = []
+
+    # ── Ollama ───────────────────────────────────────────────────────────
+    host = os.environ.get("OLLAMA_HOST", DEFAULT_OLLAMA_HOST).rstrip("/")
+    if _ollama_alive(host):
+        try:
+            import json
+            from urllib.request import urlopen
+
+            with urlopen(f"{host}/api/tags", timeout=2) as resp:  # noqa: S310
+                data = json.loads(resp.read())
+            installed = [m["name"] for m in data.get("models", []) if m.get("name")]
+            installed_set = set(installed)
+            model = os.environ.get("SPECSMITH_OLLAMA_MODEL", "").strip()
+            source = "env"
+            if not model:
+                source = "auto"
+                for candidate in _OLLAMA_MODEL_PREFERENCE:
+                    if candidate in installed_set:
+                        model = candidate
+                        break
+                if not model and installed:
+                    model = sorted(installed_set)[0]
+                if not model:
+                    model = DEFAULT_OLLAMA_MODEL
+            note = f"{source}, {len(installed)} installed"
+            results.append(
+                ProviderStatus(
+                    name="ollama",
+                    available=True,
+                    model=model,
+                    note=note,
+                    model_count=len(installed),
+                )
+            )
+        except Exception as exc:  # noqa: BLE001
+            results.append(
+                ProviderStatus(name="ollama", available=False, note=f"error reading tags: {exc}")
+            )
+    else:
+        results.append(
+            ProviderStatus(
+                name="ollama",
+                available=False,
+                note=f"not running at {host} — start with: ollama serve",
+            )
+        )
+
+    # ── Anthropic ────────────────────────────────────────────────────────
+    key = os.environ.get("ANTHROPIC_API_KEY", "")
+    if not key:
+        results.append(
+            ProviderStatus(name="anthropic", available=False, note="no ANTHROPIC_API_KEY")
+        )
+    elif importlib.util.find_spec("anthropic") is None:
+        results.append(
+            ProviderStatus(
+                name="anthropic",
+                available=False,
+                note="key set but SDK missing — run: pipx inject specsmith anthropic",
+            )
+        )
+    else:
+        model = os.environ.get("ANTHROPIC_MODEL", "claude-haiku-4-5")
+        results.append(
+            ProviderStatus(name="anthropic", available=True, model=model, note="key configured")
+        )
+
+    # ── OpenAI ───────────────────────────────────────────────────────────
+    key = os.environ.get("OPENAI_API_KEY", "")
+    if not key:
+        results.append(ProviderStatus(name="openai", available=False, note="no OPENAI_API_KEY"))
+    elif importlib.util.find_spec("openai") is None:
+        results.append(
+            ProviderStatus(
+                name="openai",
+                available=False,
+                note="key set but SDK missing — run: pipx inject specsmith openai",
+            )
+        )
+    else:
+        model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+        results.append(
+            ProviderStatus(name="openai", available=True, model=model, note="key configured")
+        )
+
+    # ── Gemini ───────────────────────────────────────────────────────────
+    key = os.environ.get("GOOGLE_API_KEY", "")
+    if not key:
+        results.append(ProviderStatus(name="gemini", available=False, note="no GOOGLE_API_KEY"))
+    elif importlib.util.find_spec("google.genai") is None:
+        results.append(
+            ProviderStatus(
+                name="gemini",
+                available=False,
+                note="key set but SDK missing — run: pipx inject specsmith google-genai",
+            )
+        )
+    else:
+        model = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash")
+        results.append(
+            ProviderStatus(name="gemini", available=True, model=model, note="key configured")
+        )
+
+    return results
 
 
 # ---------------------------------------------------------------------------
@@ -156,7 +303,14 @@ class AgentRunner:
         self.endpoint_id = (endpoint_id or "").strip() or None
         self.profile_id = (profile_id or "").strip() or None
 
-        self._emitter = emitter or EventEmitter(stream=sys.stdout)
+        # Use a plain-text emitter in interactive mode so LLM tokens render
+        # as readable prose instead of raw JSONL frames on the terminal.
+        if emitter is not None:
+            self._emitter = emitter
+        elif json_events:
+            self._emitter = EventEmitter(stream=sys.stdout)
+        else:
+            self._emitter = PlainTextEmitter(stream=sys.stdout)
         self._state = AgentState(
             provider_name=self.provider_name,
             model_name=self.model,
@@ -187,37 +341,58 @@ class AgentRunner:
     # ── Public lifecycle ───────────────────────────────────────────────
 
     def _print_banner(self) -> None:
-        """Emit the ``ready`` handshake (or print a plain banner).
+        """Emit the ``ready`` handshake (or print a plain banner.
 
         Called exactly once at process start. The bridge waits up to 20 s
-        for this frame; when ``json_events`` is False we still emit a
-        terminal-friendly banner so interactive ``specsmith run`` users
-        see the same boot text they used to.
+        for this frame; when ``json_events`` is False we print a human-
+        readable provider status table so the user knows exactly what will
+        respond to their commands before they type anything.
         """
         version = self._package_version()
         if self.json_events:
+            # When a model/provider was explicitly set (e.g. via CLI flag or test),
+            # use those.  Only probe check_providers() when no model was pinned.
+            if self.model:
+                provider_for_ready = self.provider_name
+                model_for_ready = self.model
+            else:
+                statuses = check_providers()
+                active = next((s for s in statuses if s.available), None)
+                provider_for_ready = active.name if active else self.provider_name
+                model_for_ready = active.model if active else ""
             self._emitter.ready(
                 agent="nexus",
                 version=version,
                 project_dir=self.project_dir,
-                provider=self.provider_name,
-                model=self.model,
+                provider=provider_for_ready,
+                model=model_for_ready,
                 profile_id=self.profile_id or "",
                 capabilities=_capabilities(),
                 endpoint_id=self.endpoint_id or "",
             )
         else:
-            print(
-                f"Nexus {version} — Local-first Agentic Development Environment "
-                f"(Specsmith-governed)\n"
-                f"  project: {self.project_dir}\n"
-                f"  provider: {self.provider_name}\n"
-                f"  model: {self.model or '(default)'}\n"
-                f"  profile: {self.profile_id or '(default)'}\n"
-                "Type plain English, or use slash commands "
-                "(/plan, /ask, /fix, /test, /commit, /pr, /why, /exit).",
-                flush=True,
-            )
+            statuses = check_providers()
+            active_count = sum(1 for s in statuses if s.available)
+            lines = [
+                f"Nexus {version} — specsmith run",
+                f"  project : {self.project_dir}",
+                f"  profile : {self.profile_id or '(default)'}",
+                "",
+                "  LLM providers:",
+            ]
+            for s in statuses:
+                if s.available:
+                    lines.append(
+                        f"    {s.icon} {s.name:<10} ✓ ready   model: {s.model}  ({s.note})"
+                    )
+                else:
+                    lines.append(f"    {s.icon} {s.name:<10} ✗ {s.note}")
+            lines.append("")
+            if active_count == 0:
+                lines.append("  ⚠  No provider available — commands will return no response.")
+            else:
+                lines.append("  Type plain English, or use /plan /ask /fix /test /commit /pr /exit")
+            print("\n".join(lines), flush=True)
 
     def run_interactive(self) -> None:
         """Read stdin lines and dispatch each to :meth:`_handle_command`."""
@@ -230,6 +405,10 @@ class AgentRunner:
                 if line.strip().lower() in {"/exit", "/quit"}:
                     break
                 self._handle_command(line)
+                # Ensure streamed tokens are followed by a newline so the
+                # next input prompt doesn't bleed onto the response line.
+                if not self.json_events:
+                    print(flush=True)
                 if self.json_events:
                     self._emit_event(type="turn_done")
                 if self._hard_stop:
@@ -316,7 +495,12 @@ class AgentRunner:
 
         block_id = self._next_block_id()
         try:
-            from specsmith.agent.chat_runner import run_chat
+            from specsmith.agent.chat_runner import (
+                DEFAULT_OLLAMA_HOST,
+                _ollama_alive,
+                _pick_ollama_model,
+                run_chat,
+            )
 
             result = run_chat(
                 full_prompt,
@@ -336,6 +520,28 @@ class AgentRunner:
             )
             return None
 
+        if result is None:
+            # All providers failed — give the user an actionable explanation
+            # rather than silent emptiness.
+            import os as _os
+
+            host = _os.environ.get("OLLAMA_HOST", DEFAULT_OLLAMA_HOST).rstrip("/")
+            if _ollama_alive(host):
+                model = _pick_ollama_model(host)
+                hint = (
+                    f"Ollama is running but returned no response "
+                    f"(model: {model}). "
+                    "Try: ollama run " + model
+                )
+            else:
+                hint = (
+                    "No LLM provider available. Options:\n"
+                    "  • Start Ollama: ollama serve\n"
+                    "  • Set ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY"
+                )
+            self._emit_event(type="system", message=hint)
+            return None
+
         # Aggregate metrics into the session state (C1).
         # ``run_chat`` now reports tokens_in / tokens_out / cost_usd off the
         # provider response (Ollama prompt_eval_count + eval_count, OpenAI

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453}/src/specsmith/cli.py

@@ -3661,6 +3661,13 @@ def abort_cmd(pid: int | None, abort_all_flag: bool, project_dir: str) -> None:
 
 @main.command(name="run")
 @click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option(
+    "--check",
+    "check_only",
+    is_flag=True,
+    default=False,
+    help="Check provider availability and exit (no REPL started).",
+)
 @click.option(
     "--task",
     "task",
@@ -3718,6 +3725,7 @@ def abort_cmd(pid: int | None, abort_all_flag: bool, project_dir: str) -> None:
 )
 def run_cmd(
     project_dir: str,
+    check_only: bool,
     task: str,
     provider_name: str | None,
     model: str | None,
@@ -3737,10 +3745,39 @@ def run_cmd(
       Ollama running    → local LLMs (zero config)
       SPECSMITH_PROVIDER=<name> → explicit override
 
+    Use --check to validate provider configuration without starting a session.
+
     Install a provider:
       pipx inject specsmith anthropic             # Claude
       pipx inject specsmith openai               # GPT/O-series
     """
+    from specsmith.agent.runner import check_providers
+
+    if check_only:
+        statuses = check_providers()
+        any_ok = any(s.available for s in statuses)
+        console.print("[bold]specsmith run --check[/bold]\n")
+        for s in statuses:
+            if s.available:
+                console.print(
+                    f"  [green]\u2713[/green] {s.name:<10} "
+                    f"model: [bold]{s.model}[/bold]  ({s.note})"
+                )
+            else:
+                console.print(f"  [red]\u2717[/red] {s.name:<10} {s.note}")
+        console.print()
+        if any_ok:
+            active = next(s for s in statuses if s.available)
+            console.print(
+                f"[bold green]Ready.[/bold green] Primary provider: {active.name} / {active.model}"
+            )
+        else:
+            console.print(
+                "[bold red]No provider available.[/bold red] Start Ollama or set an API key."
+            )
+            raise SystemExit(1)
+        return
+
     from specsmith.agent.core import ModelTier
     from specsmith.agent.runner import AgentRunner
 

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.11.5.dev452
+Version: 0.11.5.dev453
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.11.5.dev452 → specsmith-0.11.5.dev453}/src/specsmith.egg-info/SOURCES.txt

@@ -239,6 +239,7 @@ src/specsmith/vcs/github.py
 src/specsmith/vcs/gitlab.py
 tests/test_CMD_001.py
 tests/test_agent_profiles.py
+tests/test_agent_run_feedback.py
 tests/test_agent_runner_ready.py
 tests/test_ai_client.py
 tests/test_ai_intelligence.py