specsmith 0.8.0.dev237__tar.gz → 0.10.0.dev238__tar.gz

{specsmith-0.8.0.dev237/src/specsmith.egg-info → specsmith-0.10.0.dev238}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.8.0.dev237
+Version: 0.10.0.dev238
 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.8.0.dev237 → specsmith-0.10.0.dev238}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.8.0.dev237"
+version = "0.10.0.dev238"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"
@@ -171,6 +171,9 @@ module = [
     "specsmith.importer",
     "specsmith.agent.providers.gemini",
     "specsmith.agent.runner",
+    "specsmith.agent.profiles",
+    "specsmith.agent.fallback",
+    "specsmith.agent.core",
     "specsmith.agent.cleanup",
     "specsmith.agent.orchestrator",
     "specsmith.agent.repl",

{specsmith-0.8.0.dev237 → specsmith-0.10.0.dev238}/src/specsmith/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import version as _pkg_version
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.3.6"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.10.0"  # fallback: keep in sync with pyproject.toml

specsmith-0.10.0.dev238/src/specsmith/agent/core.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Shared agent runtime primitives (REQ-145).
+
+Hosts low-level enums and dataclasses that span :mod:`specsmith.agent.runner`,
+:mod:`specsmith.serve`, :mod:`specsmith.agent.profiles`, and
+:mod:`specsmith.agent.fallback` without forcing them to import each other.
+
+The historical ``cli.py`` referenced ``ModelTier`` from this module before
+it existed in the source tree (the file was lost in an earlier refactor),
+which produced an ``ImportError`` the moment ``specsmith run`` was
+invoked. Restoring the symbol here is the prerequisite for the bridge
+``ready`` event handshake to land before the VS Code extension's 20 s
+startup timeout fires.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class ModelTier(str, enum.Enum):
+    """Capability tier for an LLM call.
+
+    Ordered cheapest → most capable so that a fallback chain can iterate
+    in declaration order without external metadata.
+    """
+
+    FAST = "fast"
+    BALANCED = "balanced"
+    POWERFUL = "powerful"
+
+    @classmethod
+    def parse(
+        cls,
+        value: str | ModelTier | None,
+        default: ModelTier | None = None,
+    ) -> ModelTier:
+        """Tolerant parser used by CLI option handlers."""
+        if value is None or value == "":
+            return default or cls.BALANCED
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(str(value).strip().lower())
+        except ValueError:
+            return default or cls.BALANCED
+
+
+@dataclass
+class AgentState:
+    """Mutable per-session metrics surfaced via ``specsmith serve``'s
+    ``GET /api/status`` endpoint and the VS Code TokenMeter chip.
+
+    Field names mirror what :class:`specsmith.serve._AgentThread` reads off
+    ``runner._state``; do not rename without updating that consumer.
+    """
+
+    provider_name: str = ""
+    model_name: str = ""
+    profile_id: str = ""
+    session_tokens: int = 0
+    tokens_in: int = 0
+    tokens_out: int = 0
+    total_cost_usd: float = 0.0
+    tool_calls_made: int = 0
+    elapsed_minutes: float = 0.0
+    by_profile: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def credit(
+        self,
+        *,
+        profile_id: str,
+        tokens_in: int = 0,
+        tokens_out: int = 0,
+        cost_usd: float = 0.0,
+        tool_calls: int = 0,
+    ) -> None:
+        """Aggregate one turn's metrics into the running totals."""
+        self.tokens_in += int(tokens_in)
+        self.tokens_out += int(tokens_out)
+        self.session_tokens = self.tokens_in + self.tokens_out
+        self.total_cost_usd += float(cost_usd)
+        self.tool_calls_made += int(tool_calls)
+        bucket = self.by_profile.setdefault(
+            profile_id or "(default)",
+            {"tokens_in": 0, "tokens_out": 0, "cost_usd": 0.0, "tool_calls": 0, "turns": 0},
+        )
+        bucket["tokens_in"] += int(tokens_in)
+        bucket["tokens_out"] += int(tokens_out)
+        bucket["cost_usd"] = round(bucket["cost_usd"] + float(cost_usd), 6)
+        bucket["tool_calls"] += int(tool_calls)
+        bucket["turns"] += 1
+
+
+__all__ = ["AgentState", "ModelTier"]

{specsmith-0.8.0.dev237 → specsmith-0.10.0.dev238}/src/specsmith/agent/events.py

@@ -19,6 +19,9 @@ Event kinds
 * ``plan_step``        - status transition for a step in the active plan
                          block (REQ-114).
 * ``task_complete``    - final block; carries final summary + profile.
+* ``ready``            - emitted exactly once at process start (REQ-145);
+                         the VS Code bridge waits up to 20 s for this
+                         frame before declaring the agent unresponsive.
 """
 
 from __future__ import annotations
@@ -58,6 +61,61 @@ class EventEmitter:
         with contextlib.suppress(Exception):
             self.stream.flush()
 
+    # ── Lifecycle helpers ────────────────────────────────────────────────
+
+    def ready(
+        self,
+        *,
+        agent: str = "nexus",
+        version: str = "",
+        project_dir: str = "",
+        provider: str = "",
+        model: str = "",
+        profile_id: str = "",
+        capabilities: list[str] | None = None,
+        **extra: Any,
+    ) -> None:
+        """Emit the bridge handshake frame (REQ-145).
+
+        The VS Code extension's :class:`SpecsmithBridge` keys off this
+        single event to flip from ``starting`` → ``waiting`` and to start
+        flushing the queued user prompts. Schema is intentionally flat so
+        a ``JSON.parse`` line check is enough on the consumer side.
+        """
+        payload: dict[str, Any] = {
+            "type": "ready",
+            "timestamp": _now_iso(),
+            "agent": agent,
+            "version": version,
+            "project_dir": project_dir,
+            "provider": provider,
+            "model": model,
+            "profile_id": profile_id,
+            "capabilities": list(capabilities or []),
+        }
+        payload.update(extra)
+        self.emit(payload)
+
+    def system(self, message: str, **extra: Any) -> None:
+        """Emit a free-form system note (matches bridge.ts handler)."""
+        self.emit({"type": "system", "message": message, **extra})
+
+    def turn_done(self, **extra: Any) -> None:
+        """Emit the per-turn terminator the bridge uses to clear timers."""
+        self.emit({"type": "turn_done", "timestamp": _now_iso(), **extra})
+
+    def error(self, message: str, *, recoverable: bool = False, **extra: Any) -> None:
+        """Emit an error frame (recoverable = retry will be offered)."""
+        self.emit(
+            {
+                "type": "error",
+                "timestamp": _now_iso(),
+                "message": message,
+                "recoverable": bool(recoverable),
+                **extra,
+            }
+        )
+
     # ── Block helpers ────────────────────────────────────────────────────
 
     def block_start(self, kind: str, *, agent: str = "nexus", **payload: Any) -> str:

specsmith-0.10.0.dev238/src/specsmith/agent/fallback.py

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Resilient fallback-chain executor for agent profiles (REQ-146).
+
+Profiles in :mod:`specsmith.agent.profiles` carry a ``fallback_chain``
+list of ``"<provider>/<model>"`` or ``"endpoint:<id>"`` strings. When the
+primary call raises a transient error (timeout / connection refused /
+HTTP 429 / HTTP 5xx), this module walks the chain in order until one
+returns successfully or the chain is exhausted.
+
+The chain is **resilience**, not **routing** — picking the right primary
+is the routing table's job. The chain only kicks in when the chosen
+primary fails.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import socket
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError, URLError
+
+# (ruff I001 sentinel: imports above are intentionally grouped stdlib + typing)
+
+
+# Errors we treat as worth falling through. Anything else is a programmer
+# bug and should bubble up so we don't paper over correctness issues.
+TRANSIENT_EXCEPTIONS: tuple[type[BaseException], ...] = (
+    TimeoutError,
+    socket.timeout,
+    URLError,
+    ConnectionError,
+    OSError,
+)
+
+
+@dataclass
+class FallbackAttempt:
+    """One step of an executed chain."""
+
+    target: str
+    ok: bool
+    error: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"target": self.target, "ok": self.ok, "error": self.error}
+
+
+@dataclass
+class FallbackResult:
+    """Outcome of :func:`run_with_fallback`."""
+
+    value: Any
+    used: str = ""
+    attempts: list[FallbackAttempt] = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self.attempts is None:
+            self.attempts = []
+
+
+def _is_transient(exc: BaseException) -> bool:
+    if isinstance(exc, HTTPError):
+        return 500 <= int(getattr(exc, "code", 0) or 0) < 600 or exc.code in {408, 429}
+    return isinstance(exc, TRANSIENT_EXCEPTIONS)
+
+
+def parse_target(target: str) -> tuple[str, str, str]:
+    """Decompose a chain entry into ``(kind, provider_or_id, model)``.
+
+    Examples::
+
+        parse_target("anthropic/claude-haiku-4-5")
+            # -> ("provider", "anthropic", "claude-haiku-4-5")
+        parse_target("ollama/qwen2.5:7b")
+            # -> ("provider", "ollama", "qwen2.5:7b")
+        parse_target("endpoint:home-vllm")
+            # -> ("endpoint", "home-vllm", "")
+    """
+    cleaned = (target or "").strip()
+    if not cleaned:
+        return ("provider", "", "")
+    if cleaned.startswith("endpoint:"):
+        return ("endpoint", cleaned[len("endpoint:") :], "")
+    if "/" not in cleaned:
+        return ("provider", cleaned, "")
+    provider, _, model = cleaned.partition("/")
+    return ("provider", provider.strip(), model.strip())
+
+
+def run_with_fallback(
+    primary_target: str,
+    fallback_chain: Iterable[str],
+    invoke: Callable[[str, str, str], Any],
+    *,
+    on_attempt: Callable[[FallbackAttempt], None] | None = None,
+) -> FallbackResult:
+    """Try the primary target; on transient failure walk the chain.
+
+    ``invoke`` is called as ``invoke(kind, provider_or_id, model)`` and
+    must raise on failure. Any non-transient exception aborts the chain
+    immediately (we don't want to mask a programmer bug as an outage).
+    """
+    targets = [primary_target] + [t for t in fallback_chain if t]
+    result = FallbackResult(value=None, attempts=[])
+    for target in targets:
+        kind, ident, model = parse_target(target)
+        if not ident:
+            continue
+        try:
+            value = invoke(kind, ident, model)
+        except Exception as exc:  # noqa: BLE001
+            attempt = FallbackAttempt(target=target, ok=False, error=str(exc))
+            result.attempts.append(attempt)
+            if on_attempt:
+                with contextlib.suppress(Exception):
+                    on_attempt(attempt)
+            if not _is_transient(exc):
+                # Programmer error / auth failure — bubble up immediately
+                # so the caller sees the real cause.
+                raise
+            continue
+        attempt = FallbackAttempt(target=target, ok=True)
+        result.attempts.append(attempt)
+        if on_attempt:
+            with contextlib.suppress(Exception):
+                on_attempt(attempt)
+        result.value = value
+        result.used = target
+        return result
+    return result  # exhausted, value=None
+
+
+__all__ = [
+    "FallbackAttempt",
+    "FallbackResult",
+    "TRANSIENT_EXCEPTIONS",
+    "parse_target",
+    "run_with_fallback",
+]