specsmith 0.6.0.dev231__tar.gz → 0.6.0.dev233__tar.gz

{specsmith-0.6.0.dev231/src/specsmith.egg-info → specsmith-0.6.0.dev233}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.6.0.dev231
+Version: 0.6.0.dev233
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT
@@ -53,6 +53,11 @@ Provides-Extra: gui
 Requires-Dist: PySide6>=6.6; extra == "gui"
 Provides-Extra: ag2
 Requires-Dist: ag2[ollama]; extra == "ag2"
+Provides-Extra: history-semantic
+Requires-Dist: sentence-transformers>=2.2; extra == "history-semantic"
+Requires-Dist: numpy>=1.24; extra == "history-semantic"
+Provides-Extra: voice
+Requires-Dist: whisper-cpp-python>=0.2; extra == "voice"
 Provides-Extra: agent
 Requires-Dist: anthropic>=0.56; extra == "agent"
 Requires-Dist: openai>=1.0; extra == "agent"

{specsmith-0.6.0.dev231 → specsmith-0.6.0.dev233}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.6.0.dev231"
+version = "0.6.0.dev233"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"
@@ -67,6 +67,11 @@ mistral = ["openai>=1.0"]  # Mistral uses the openai SDK pointed at api.mistral.
 gui = ["PySide6>=6.6"]
 # AG2 agent shell (Planner/Builder/Verifier over Ollama)
 ag2 = ["ag2[ollama]"]
+# Optional semantic backend for `specsmith history search --semantic` (REQ-135).
+# Falls back gracefully to keyword matching if these are not installed.
+history-semantic = ["sentence-transformers>=2.2", "numpy>=1.24"]
+# Optional whisper-cpp wrapper for the voice agent input (REQ-141).
+voice = ["whisper-cpp-python>=0.2"]
 # Install all optional LLM providers
 agent = ["anthropic>=0.56", "openai>=1.0"]
 # Convenience bundle: everything
@@ -138,6 +143,12 @@ module = [
     "yaml.*",
     "keyring",   # optional OS credential store; stubs not published
     "keyring.*",
+    "numpy",     # optional [history-semantic] extra (REQ-135)
+    "numpy.*",
+    "sentence_transformers",  # optional [history-semantic] extra (REQ-135)
+    "sentence_transformers.*",
+    "whisper_cpp_python",  # optional [voice] extra (REQ-141)
+    "whisper_cpp_python.*",
 ]
 ignore_missing_imports = true
 

specsmith-0.6.0.dev233/src/specsmith/agent/suggester.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Lightweight NL-to-command suggester for `specsmith suggest-command` (REQ-131).
+
+Given a partial natural-language fragment, return a structured suggestion
+that the VS Code extension renders as inline ghost-text in the chat input.
+Three classification buckets:
+
+* ``command`` -- the input is shell-y (starts with an imperative verb that
+  maps to a known CLI). Suggest a concrete shell command.
+* ``utterance`` -- the input is plain English meant for the agent. Suggest
+  a refined utterance that names a likely component (best-effort).
+* ``passthrough`` -- input is too short or ambiguous; echo it back so the
+  ghost-text matches what the user typed (no-op suggestion).
+
+The suggester is **deterministic and LLM-free**. The IDE may layer an LLM
+predictor on top, but the CLI baseline must always succeed quickly. If the
+extension wants a richer suggestion, it can call `specsmith preflight
+--predict-only` separately for utterances.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# Common imperative verbs that map to shell-y intents.
+_SHELL_VERBS = {
+    "run",
+    "exec",
+    "execute",
+    "kill",
+    "stop",
+    "start",
+    "restart",
+    "build",
+    "test",
+    "lint",
+    "format",
+    "git",
+    "cd",
+    "ls",
+    "cat",
+    "rm",
+    "mv",
+    "cp",
+    "find",
+    "grep",
+    "ps",
+    "top",
+    "open",
+    "edit",
+    "tail",
+    "head",
+    "make",
+    "npm",
+    "pnpm",
+    "yarn",
+    "pip",
+    "pipx",
+    "uv",
+    "pytest",
+    "ruff",
+    "mypy",
+    "cargo",
+    "go",
+    "docker",
+    "kubectl",
+    "terraform",
+}
+
+# Map verb -> default refined command.
+_VERB_TEMPLATES: dict[str, str] = {
+    "run tests": "pytest -q",
+    "run lint": "ruff check .",
+    "run mypy": "mypy src/",
+    "format": "ruff format .",
+    "lint": "ruff check .",
+    "test": "pytest -q",
+    "build": "python -m build",
+    "git status": "git --no-pager status",
+    "git log": "git --no-pager log --oneline -20",
+    "git diff": "git --no-pager diff",
+}
+
+
+@dataclass
+class CommandSuggestion:
+    """Output payload of :func:`suggest_command`."""
+
+    kind: str  # "command" | "utterance" | "passthrough"
+    suggestion: str
+    confidence: float = 0.5
+    reasoning: str = ""
+    candidates: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "suggestion": self.suggestion,
+            "confidence": round(self.confidence, 3),
+            "reasoning": self.reasoning,
+            "candidates": list(self.candidates),
+        }
+
+
+def classify(text: str) -> str:
+    """Return ``command``, ``utterance``, or ``passthrough``."""
+    stripped = text.strip()
+    if len(stripped) < 2:
+        return "passthrough"
+    first = stripped.split()[0].lower()
+    if first in _SHELL_VERBS:
+        return "command"
+    return "utterance"
+
+
+def suggest_command(text: str, *, project_dir: Path | None = None) -> CommandSuggestion:
+    """Return a structured suggestion for ``text``.
+
+    The suggester is deterministic. It looks for verb prefixes and a short
+    catalogue of common templates; if nothing matches, it returns the input
+    unchanged with kind=``passthrough``.
+    """
+    stripped = text.strip()
+    kind = classify(stripped)
+    if kind == "passthrough":
+        return CommandSuggestion(
+            kind="passthrough",
+            suggestion=text,
+            confidence=0.0,
+            reasoning="input too short to suggest",
+        )
+    if kind == "utterance":
+        return _suggest_utterance(stripped, project_dir=project_dir)
+    return _suggest_shell(stripped)
+
+
+def _suggest_shell(text: str) -> CommandSuggestion:
+    lower = text.lower()
+    # Direct multi-word template match (e.g. "run tests").
+    for phrase, command in _VERB_TEMPLATES.items():
+        if lower.startswith(phrase):
+            return CommandSuggestion(
+                kind="command",
+                suggestion=command,
+                confidence=0.85,
+                reasoning=f"matched template '{phrase}'",
+            )
+    # Single-verb fallback: if the user typed "git" alone, propose
+    # `git status`. If "test", propose pytest -q.
+    first = lower.split()[0]
+    fallback = {
+        "git": "git --no-pager status",
+        "ls": "ls -la",
+        "test": "pytest -q",
+        "lint": "ruff check .",
+        "format": "ruff format .",
+        "build": "python -m build",
+        "find": "find . -name '*.py'",
+    }.get(first)
+    if fallback and lower.strip() == first:
+        return CommandSuggestion(
+            kind="command",
+            suggestion=fallback,
+            confidence=0.7,
+            reasoning=f"single verb '{first}' resolved to default command",
+        )
+    # Pass through what the user typed; mark as command anyway so the IDE
+    # knows it's shell-y rather than NL.
+    return CommandSuggestion(
+        kind="command",
+        suggestion=text,
+        confidence=0.3,
+        reasoning="recognised as shell command but no template applied",
+    )
+
+
+_REQ_REGEX = re.compile(r"REQ-[A-Z0-9-]+", re.IGNORECASE)
+_KNOWN_VERBS = ("add", "fix", "refactor", "remove", "rename", "document", "test")
+
+
+def _suggest_utterance(text: str, *, project_dir: Path | None) -> CommandSuggestion:
+    lower = text.lower()
+    candidates: list[str] = []
+
+    # If the text already names a REQ, surface it verbatim with a higher
+    # confidence — the user is already specific.
+    matched = _REQ_REGEX.findall(text)
+    if matched:
+        return CommandSuggestion(
+            kind="utterance",
+            suggestion=text,
+            confidence=0.9,
+            reasoning=f"references {matched[0]} explicitly",
+            candidates=matched,
+        )
+
+    # If the text starts with a change verb but doesn't name a component,
+    # suggest a refined version that asks the user to add a target.
+    first = lower.split()[0] if lower.split() else ""
+    if first in _KNOWN_VERBS and len(lower.split()) <= 3:
+        return CommandSuggestion(
+            kind="utterance",
+            suggestion=f"{text.rstrip()} (please name the component or file)",
+            confidence=0.6,
+            reasoning=f"verb '{first}' lacks an explicit target",
+        )
+
+    # Project-aware refinement: scan REQUIREMENTS.md for keywords that match
+    # the input and propose the first hit. Best-effort; never blocks.
+    if project_dir is not None:
+        candidates = _scan_requirements(text, project_dir)
+        if candidates:
+            return CommandSuggestion(
+                kind="utterance",
+                suggestion=f"{text.rstrip()} ({candidates[0]})",
+                confidence=0.65,
+                reasoning=f"matched {candidates[0]} from REQUIREMENTS.md",
+                candidates=candidates,
+            )
+
+    # Default: echo back unchanged.
+    return CommandSuggestion(
+        kind="utterance",
+        suggestion=text,
+        confidence=0.4,
+        reasoning="no project-specific refinement available",
+    )
+
+
+def _scan_requirements(text: str, project_dir: Path) -> list[str]:
+    """Return up to 5 REQ ids whose description shares words with ``text``."""
+    candidates: list[tuple[int, str]] = []
+    for path in (
+        project_dir / "REQUIREMENTS.md",
+        project_dir / "docs" / "REQUIREMENTS.md",
+    ):
+        if not path.is_file():
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        words = {w.lower() for w in re.findall(r"[A-Za-z]{4,}", text)}
+        if not words:
+            return []
+        for match in re.finditer(
+            r"^###?\s+(REQ-[A-Z0-9-]+)\s*(.*?)(?=^###?\s+REQ|^##\s|\Z)",
+            content,
+            re.MULTILINE | re.DOTALL,
+        ):
+            req_id, body = match.group(1), match.group(2)
+            body_words = {w.lower() for w in re.findall(r"[A-Za-z]{4,}", body)}
+            score = len(words & body_words)
+            if score > 0:
+                candidates.append((score, req_id))
+    candidates.sort(key=lambda x: (-x[0], x[1]))
+    return [req for _, req in candidates[:5]]
+
+
+__all__ = ["CommandSuggestion", "classify", "suggest_command"]

specsmith-0.6.0.dev233/src/specsmith/block_export.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Per-block share/export for `specsmith chat` (REQ-134).
+
+Reads ``.specsmith/sessions/<session_id>/events.jsonl`` (the chat replay log
+or, fallback, ``turns.jsonl``) and slices a single block out as a
+self-contained Markdown / JSON / HTML snippet.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _events_path(project_dir: Path, session_id: str) -> Path | None:
+    base = project_dir / ".specsmith" / "sessions" / session_id
+    candidates = [
+        base / "events.jsonl",
+        base / "turns.jsonl",
+    ]
+    for c in candidates:
+        if c.is_file():
+            return c
+    return None
+
+
+def _read_events(events_path: Path) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for line in events_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(obj, dict):
+            out.append(obj)
+    return out
+
+
+def slice_block(events: list[dict[str, Any]], block_id: str) -> list[dict[str, Any]]:
+    """Return all events tagged with ``block_id``, plus the bracketing
+    block_start/block_complete events that defined it.
+    """
+    out: list[dict[str, Any]] = []
+    for evt in events:
+        if evt.get("block_id") == block_id or evt.get("id") == block_id:
+            out.append(evt)
+    return out
+
+
+def export_block(
+    project_dir: Path,
+    session_id: str,
+    block_id: str,
+    *,
+    fmt: str = "md",
+) -> str:
+    """Export the events for ``block_id`` as a string in ``fmt``.
+
+    Raises FileNotFoundError if no session log exists.
+    Raises KeyError if the block is not found.
+    """
+    events_path = _events_path(project_dir, session_id)
+    if events_path is None:
+        raise FileNotFoundError(f"No session log for {session_id} in {project_dir}")
+    events = _read_events(events_path)
+    matching = slice_block(events, block_id)
+    if not matching:
+        raise KeyError(f"block_id {block_id} not found in session {session_id}")
+    if fmt == "json":
+        return json.dumps(matching, indent=2)
+    if fmt == "html":
+        rows = "".join(
+            f"<li><pre>{html.escape(json.dumps(evt, indent=2))}</pre></li>" for evt in matching
+        )
+        return (
+            f"<!DOCTYPE html><html><head><meta charset='utf-8'>"
+            f"<title>specsmith block {html.escape(block_id)}</title></head>"
+            f"<body><h1>Block {html.escape(block_id)}</h1>"
+            f"<p>session {html.escape(session_id)}</p><ol>{rows}</ol></body></html>"
+        )
+    # default: markdown
+    lines: list[str] = [
+        f"# Block `{block_id}`",
+        f"_session_: `{session_id}`",
+        "",
+    ]
+    for evt in matching:
+        kind = str(evt.get("type", "event"))
+        lines.append(f"## {kind}")
+        if "text" in evt:
+            lines.append(str(evt["text"]))
+        else:
+            lines.append("```json")
+            lines.append(json.dumps(evt, indent=2))
+            lines.append("```")
+        lines.append("")
+    return "\n".join(lines)
+
+
+__all__ = ["export_block", "slice_block"]

{specsmith-0.6.0.dev231 → specsmith-0.6.0.dev233}/src/specsmith/cli.py

@@ -4440,6 +4440,159 @@ def info_cmd(as_json: bool, section: str) -> None:
 # ---------------------------------------------------------------------------
 
 
+# ---------------------------------------------------------------------------
+# specsmith chat-export-block — self-contained block share (REQ-134)
+# ---------------------------------------------------------------------------
+#
+# This is exposed at the top level (rather than under ``chat``) because the
+# existing ``specsmith chat <utterance>`` command takes a positional argument
+# and cannot simultaneously act as a Click group.
+
+
+@main.command(name="chat-export-block")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--session-id", "session_id", required=True)
+@click.option("--block-id", "block_id", required=True)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["md", "json", "html"]),
+    default="md",
+)
+def chat_export_block_cmd(project_dir: str, session_id: str, block_id: str, fmt: str) -> None:
+    """Export one chat block as a self-contained snippet (REQ-134)."""
+    from specsmith.block_export import export_block
+
+    try:
+        out = export_block(
+            Path(project_dir).resolve(),
+            session_id,
+            block_id,
+            fmt=fmt,
+        )
+    except FileNotFoundError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise SystemExit(1) from exc
+    except KeyError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise SystemExit(1) from exc
+    click.echo(out)
+
+
+# ---------------------------------------------------------------------------
+# specsmith cloud serve — reference cloud-agent receiver (REQ-136)
+# ---------------------------------------------------------------------------
+
+
+@main.command(name="cloud-serve")
+@click.option("--host", default="127.0.0.1")
+@click.option("--port", type=int, default=9000)
+@click.option("--token", default="", help="Optional bearer token.")
+@click.option("--allow-cidr", default="", help="CIDR range required to bind non-loopback.")
+def cloud_serve_cmd(host: str, port: int, token: str, allow_cidr: str) -> None:
+    """Run the reference cloud-agent receiver (REQ-136).
+
+    Accepts POST /spawn with a JSON manifest, persists it under
+    ~/.specsmith/cloud-runs/<run_id>/manifest.json, and returns 202 with
+    a stream_url placeholder.
+    """
+    from specsmith.cloud_serve import CloudReceiverConfig, make_server
+
+    config = CloudReceiverConfig(host=host, port=port, token=token, allow_cidr=allow_cidr)
+    try:
+        server = make_server(config)
+    except RuntimeError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise SystemExit(2) from exc
+    console.print(
+        f"[bold]specsmith cloud serve[/bold] on http://{config.host}:{config.port}\n"
+        f"  storage: {config.storage_dir}\n"
+        f"  token:   {'(set)' if token else '(none)'}\n"
+        "  Press Ctrl+C to stop."
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        console.print("\n[dim]cloud serve stopped.[/dim]")
+        server.server_close()
+
+
+# ---------------------------------------------------------------------------
+# specsmith api-surface — 1.0 stability snapshot (REQ-140)
+# ---------------------------------------------------------------------------
+
+
+@main.command(name="api-surface")
+@click.option(
+    "--snapshot",
+    type=click.Path(),
+    default="",
+    help="Write the current public surface to this JSON file.",
+)
+def api_surface_cmd(snapshot: str) -> None:
+    """Print the frozen public CLI/API surface as JSON (REQ-140)."""
+    import json as _json
+
+    surface = {
+        "cli_commands": sorted(
+            cmd_name for cmd_name in main.commands if not cmd_name.startswith("_")
+        ),
+        "exit_codes": {
+            "preflight_accepted": 0,
+            "preflight_needs_clarification": 2,
+            "preflight_blocked": 3,
+            "verify_ok": 0,
+            "verify_retry": 2,
+            "verify_stop": 3,
+        },
+        "event_types": [
+            "block_start",
+            "block_complete",
+            "token",
+            "plan_step",
+            "tool_call",
+            "tool_request",
+            "tool_result",
+            "diff",
+            "task_complete",
+        ],
+    }
+    payload = _json.dumps(surface, indent=2, sort_keys=True)
+    if snapshot:
+        Path(snapshot).write_text(payload, encoding="utf-8")
+    click.echo(payload)
+
+
+# ---------------------------------------------------------------------------
+# specsmith suggest-command — NL-to-command suggester (REQ-131)
+# ---------------------------------------------------------------------------
+
+
+@main.command(name="suggest-command")
+@click.argument("text")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=True,
+    help="Emit suggestion as JSON (default; only mode for now).",
+)
+def suggest_command_cmd(text: str, project_dir: str, as_json: bool) -> None:
+    """Suggest a refined command or utterance for a partial input (REQ-131).
+
+    Returns a JSON object: ``{kind, suggestion, confidence, reasoning, candidates}``.
+    ``kind`` is one of ``command``, ``utterance``, ``passthrough``. The
+    extension renders the suggestion as inline ghost-text.
+    """
+    import json as _json
+
+    from specsmith.agent.suggester import suggest_command
+
+    result = suggest_command(text, project_dir=Path(project_dir).resolve())
+    click.echo(_json.dumps(result.to_dict(), indent=2))
+
+
 @main.command(name="scan")
 @click.option("--project-dir", type=click.Path(exists=True), default=".")
 @click.option("--json", "as_json", is_flag=True, default=False, help="Output as JSON.")