specsmith 0.6.0.dev233__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.6.0.dev233
+Version: 0.7.0
 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.6.0.dev233 → specsmith-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.6.0.dev233"
+version = "0.7.0"
 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.7.0/src/specsmith/agent/voice.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Voice transcription wrapper (REQ-141).
+
+Wraps the optional ``whisper_cpp_python`` library so the rest of specsmith
+can call ``transcribe(path)`` without caring whether the extra is
+installed. When the library is missing, ``transcribe`` raises
+``VoiceUnavailableError`` with a friendly install hint so the caller can
+surface it to the user.
+
+The wrapper supports three modes:
+
+* **real** -- ``whisper_cpp_python`` is installed and a model file is
+  available (auto-located under ``~/.specsmith/voice/`` or pointed to via
+  ``SPECSMITH_VOICE_MODEL``). Real audio decoding.
+* **stub** -- ``SPECSMITH_VOICE_STUB=<text>`` is set. Returns the literal
+  text without touching the audio file. Used by tests and CI so we don't
+  need to ship a 500MB model file.
+* **unavailable** -- neither of the above. ``transcribe`` raises.
+
+The CLI exposes this as ``specsmith voice transcribe <wav>``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class VoiceUnavailableError(RuntimeError):
+    """Raised when whisper-cpp is not installed and no stub is set."""
+
+
+@dataclass
+class TranscribeResult:
+    text: str
+    backend: str  # 'whisper-cpp', 'stub', 'unavailable'
+    model: str = ""
+    duration_s: float = 0.0
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "text": self.text,
+            "backend": self.backend,
+            "model": self.model,
+            "duration_s": round(self.duration_s, 3),
+        }
+
+
+def default_model_dir() -> Path:
+    return Path.home() / ".specsmith" / "voice"
+
+
+def _resolve_model_path() -> Path | None:
+    """Return the on-disk model path, or None if no model is configured."""
+    env = os.environ.get("SPECSMITH_VOICE_MODEL", "").strip()
+    if env:
+        p = Path(env)
+        if p.is_file():
+            return p
+    # Auto-locate the smallest .bin under ~/.specsmith/voice/
+    voice_dir = default_model_dir()
+    if voice_dir.is_dir():
+        candidates = sorted(voice_dir.glob("*.bin"), key=lambda x: x.stat().st_size)
+        if candidates:
+            return candidates[0]
+    return None
+
+
+def is_available() -> bool:
+    """Cheap probe: True iff transcription would succeed without raising."""
+    if os.environ.get("SPECSMITH_VOICE_STUB", "").strip():
+        return True
+    try:
+        import whisper_cpp_python  # noqa: F401  (presence-only check)
+    except Exception:  # noqa: BLE001
+        return False
+    return _resolve_model_path() is not None
+
+
+def transcribe(path: Path) -> TranscribeResult:
+    """Transcribe a wav/flac/mp3 file to text.
+
+    Order of resolution:
+    1. If ``SPECSMITH_VOICE_STUB`` is set, return its value verbatim. This
+       lets tests run without a model file.
+    2. Otherwise import ``whisper_cpp_python`` and run a real transcription.
+    3. If neither is available, raise :class:`VoiceUnavailableError` with
+       an actionable message.
+    """
+    import time as _time
+
+    if not path.exists():
+        raise FileNotFoundError(f"audio file not found: {path}")
+
+    stub = os.environ.get("SPECSMITH_VOICE_STUB", "").strip()
+    if stub:
+        return TranscribeResult(text=stub, backend="stub")
+
+    try:
+        import whisper_cpp_python
+    except Exception as exc:  # noqa: BLE001
+        raise VoiceUnavailableError(
+            "whisper-cpp-python is not installed. Run "
+            "`pipx inject specsmith whisper-cpp-python` "
+            "(or `pip install specsmith[voice]`)."
+        ) from exc
+
+    model_path = _resolve_model_path()
+    if model_path is None:
+        raise VoiceUnavailableError(
+            "No whisper model found. Set SPECSMITH_VOICE_MODEL or place a "
+            f".bin model under {default_model_dir()}."
+        )
+
+    start = _time.perf_counter()
+    whisper = whisper_cpp_python.Whisper(model_path=str(model_path))
+    out = whisper.transcribe(str(path))
+    text = out.get("text") if isinstance(out, dict) else str(out)
+    return TranscribeResult(
+        text=str(text or "").strip(),
+        backend="whisper-cpp",
+        model=model_path.name,
+        duration_s=_time.perf_counter() - start,
+    )
+
+
+__all__ = [
+    "TranscribeResult",
+    "VoiceUnavailableError",
+    "default_model_dir",
+    "is_available",
+    "transcribe",
+]

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

@@ -2796,12 +2796,23 @@ def run_cmd(
 @click.option("--model", default="", help="Model name (blank = provider default).")
 @click.option("--port", type=int, default=8421, help="HTTP port to listen on.")
 @click.option("--host", default="127.0.0.1", help="Bind address (use 0.0.0.0 for network access).")
+@click.option(
+    "--auth-token",
+    "auth_token",
+    default="",
+    help=(
+        "Optional bearer token (REQ-137). When set, every /api/* request must "
+        "present `Authorization: Bearer <token>`. /api/health stays open so "
+        "liveness probes still work."
+    ),
+)
 def serve_cmd(
     project_dir: str,
     provider: str,
     model: str,
     port: int,
     host: str,
+    auth_token: str,
 ) -> None:
     """Start a persistent HTTP server for agent sessions.
 
@@ -2810,7 +2821,8 @@ def serve_cmd(
     POST /api/send.
 
     Example:
-      specsmith serve --port 8421 --provider ollama --model qwen2.5:14b
+      specsmith serve --port 8421 --provider ollama --model qwen2.5:14b \
+        --auth-token $(specsmith auth get serve)
     """
     from specsmith.serve import run_server
 
@@ -2820,6 +2832,7 @@ def serve_cmd(
         model=model,
         port=port,
         host=host,
+        auth_token=auth_token,
     )
 
 
@@ -4444,9 +4457,28 @@ 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.
+# Top-level alias kept for back-compat with v0.6.x which only exposed
+# ``specsmith chat-export-block``. The canonical 1.0 spelling is
+# ``specsmith chat export-block`` under the chat group below.
+
+
+def _do_chat_export_block(project_dir: str, session_id: str, block_id: str, fmt: str) -> None:
+    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)
 
 
 @main.command(name="chat-export-block")
@@ -4460,23 +4492,156 @@ def info_cmd(as_json: bool, section: str) -> None:
     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
+    """Export one chat block as a self-contained snippet (REQ-134, top-level alias)."""
+    _do_chat_export_block(project_dir, session_id, block_id, fmt)
+
+
+# ---------------------------------------------------------------------------
+# specsmith voice transcribe — wav/flac transcription via whisper-cpp (REQ-141)
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="voice")
+def voice_group() -> None:
+    """Voice agent input (REQ-141). Requires the ``[voice]`` extra."""
+
+
+@voice_group.command(name="transcribe")
+@click.argument("audio_path", type=click.Path(exists=True))
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit the full transcription record as JSON.",
+)
+def voice_transcribe_cmd(audio_path: str, as_json: bool) -> None:
+    """Transcribe AUDIO_PATH to text using whisper-cpp.
+
+    Three resolution modes:
+
+    \b
+    * SPECSMITH_VOICE_STUB=<text> — returns the literal text (used by tests)
+    * whisper-cpp installed + model present — real transcription
+    * neither — exits 2 with an actionable install hint
+    """
+    import json as _json
+
+    from specsmith.agent.voice import VoiceUnavailableError, transcribe
 
     try:
-        out = export_block(
-            Path(project_dir).resolve(),
-            session_id,
-            block_id,
-            fmt=fmt,
-        )
+        result = transcribe(Path(audio_path))
     except FileNotFoundError as exc:
         console.print(f"[red]{exc}[/red]")
         raise SystemExit(1) from exc
-    except KeyError as exc:
+    except VoiceUnavailableError as exc:
         console.print(f"[red]{exc}[/red]")
+        raise SystemExit(2) from exc
+
+    if as_json:
+        click.echo(_json.dumps(result.to_dict(), indent=2))
+    else:
+        click.echo(result.text)
+
+
+@voice_group.command(name="status")
+def voice_status_cmd() -> None:
+    """Report whether voice transcription is available right now."""
+    from specsmith.agent.voice import default_model_dir, is_available
+
+    if is_available():
+        console.print("[green]\u2713[/green] voice available")
+        console.print(f"  model dir: {default_model_dir()}")
+    else:
+        console.print("[yellow]\u2014[/yellow] voice unavailable")
+        console.print(
+            "  Install: [bold]pipx inject specsmith whisper-cpp-python[/bold] "
+            "and place a model under ~/.specsmith/voice/."
+        )
+        raise SystemExit(2)
+
+
+# ---------------------------------------------------------------------------
+# specsmith cloud spawn — client side of the receiver (REQ-136)
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="cloud")
+def cloud_group() -> None:
+    """Cloud-agent receiver client (REQ-136)."""
+
+
+@cloud_group.command(name="spawn")
+@click.argument("manifest_path", type=click.Path(exists=True))
+@click.option(
+    "--endpoint",
+    default="http://127.0.0.1:9000",
+    help="Cloud-serve base URL (default: http://127.0.0.1:9000).",
+)
+@click.option("--token", default="", help="Bearer token for the receiver.")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Validate the manifest locally and print what would be posted.",
+)
+def cloud_spawn_cmd(manifest_path: str, endpoint: str, token: str, dry_run: bool) -> None:
+    """Post a manifest to a `specsmith cloud-serve` endpoint (REQ-136).
+
+    The MANIFEST_PATH is a YAML or JSON file describing the run. The CLI
+    reads it, posts it to ``<endpoint>/spawn`` with optional bearer auth,
+    and prints the response as JSON.
+    """
+    import json as _json
+    import urllib.error
+    import urllib.request
+
+    raw = Path(manifest_path).read_text(encoding="utf-8")
+    payload: dict[str, object]
+    if manifest_path.endswith((".yml", ".yaml")):
+        try:
+            import yaml as _yaml
+
+            payload = _yaml.safe_load(raw) or {}
+        except Exception as exc:  # noqa: BLE001
+            console.print(f"[red]Invalid YAML manifest: {exc}[/red]")
+            raise SystemExit(2) from exc
+    else:
+        try:
+            payload = _json.loads(raw)
+        except ValueError as exc:
+            console.print(f"[red]Invalid JSON manifest: {exc}[/red]")
+            raise SystemExit(2) from exc
+
+    if not isinstance(payload, dict):
+        console.print("[red]Manifest must be a mapping (YAML/JSON object).[/red]")
+        raise SystemExit(2)
+
+    if dry_run:
+        click.echo(_json.dumps({"endpoint": endpoint, "manifest": payload}, indent=2))
+        return
+
+    body = _json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(  # noqa: S310 - user-supplied endpoint
+        endpoint.rstrip("/") + "/spawn",
+        data=body,
+        method="POST",
+        headers={"Content-Type": "application/json"},
+    )
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310
+            response = _json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body_text = exc.read().decode("utf-8") or "{}"
+        console.print(f"[red]HTTP {exc.code}[/red]: {body_text}")
+        raise SystemExit(1) from exc
+    except urllib.error.URLError as exc:
+        console.print(f"[red]Network error[/red]: {exc.reason}")
         raise SystemExit(1) from exc
-    click.echo(out)
+
+    click.echo(_json.dumps(response, indent=2))
 
 
 # ---------------------------------------------------------------------------
@@ -5808,93 +5973,13 @@ main.add_command(notebook_group)
 
 
 # ---------------------------------------------------------------------------
-# Cloud — spawn an off-machine agent (REQ-126)
+# Cloud — REQ-126 placeholder (cloud spawn lives above under REQ-136).
 # ---------------------------------------------------------------------------
-
-
-@main.group(name="cloud")
-def cloud_group() -> None:
-    """Spawn cloud agents (stub for now — packages and posts work)."""
-
-
-@cloud_group.command(name="spawn")
-@click.argument("utterance")
-@click.option("--project-dir", type=click.Path(exists=True), default=".")
-@click.option(
-    "--endpoint",
-    default="",
-    help="Cloud endpoint URL (default: SPECSMITH_CLOUD_ENDPOINT env var).",
-)
-@click.option(
-    "--dry-run",
-    is_flag=True,
-    default=False,
-    help="Build the tarball + manifest but do not POST.",
-)
-def cloud_spawn(utterance: str, project_dir: str, endpoint: str, dry_run: bool) -> None:
-    """Tarball the working tree and POST to a cloud agent endpoint (REQ-126).
-
-    Always emits a manifest at `.specsmith/cloud/<run_id>/manifest.json`
-    so the operation is auditable. When the endpoint is reachable the
-    response stream is tailed to stdout as JSONL events. Without an
-    endpoint, the command stays local: the manifest is recorded and a
-    helpful error is printed.
-    """
-    import json as _json
-    import os
-    import tarfile
-    import uuid as _uuid
-    from urllib import error as _urlerror
-    from urllib import request as _urlreq
-
-    root = Path(project_dir).resolve()
-    run_id = f"cloud_{_uuid.uuid4().hex[:12]}"
-    run_dir = root / ".specsmith" / "cloud" / run_id
-    run_dir.mkdir(parents=True, exist_ok=True)
-
-    tar_path = run_dir / "workspace.tar.gz"
-    skip = {".git", ".venv", "__pycache__", ".specsmith", "node_modules", "dist", "build"}
-    with tarfile.open(tar_path, "w:gz") as tar:
-        for item in sorted(root.iterdir()):
-            if item.name in skip:
-                continue
-            tar.add(item, arcname=item.name)
-
-    manifest = {
-        "run_id": run_id,
-        "utterance": utterance,
-        "workspace": str(tar_path.relative_to(root)),
-        "endpoint": endpoint or os.environ.get("SPECSMITH_CLOUD_ENDPOINT", ""),
-        "dry_run": dry_run,
-    }
-    (run_dir / "manifest.json").write_text(_json.dumps(manifest, indent=2), encoding="utf-8")
-
-    if dry_run or not manifest["endpoint"]:
-        console.print(
-            f"[yellow]Cloud endpoint not configured.[/yellow] Manifest written to {run_dir}."
-        )
-        console.print(
-            "  Set [bold]SPECSMITH_CLOUD_ENDPOINT[/bold] or pass [bold]--endpoint[/bold] to POST."
-        )
-        return
-
-    body = _json.dumps(manifest).encode("utf-8")
-    req = _urlreq.Request(
-        manifest["endpoint"],
-        data=body,
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
-    try:
-        with _urlreq.urlopen(req, timeout=30) as resp:  # noqa: S310 - user-configured
-            for line in resp:
-                click.echo(line.decode("utf-8", errors="replace").rstrip())
-    except (_urlerror.URLError, OSError) as exc:
-        console.print(f"[red]Cloud spawn failed:[/red] {exc}")
-        raise SystemExit(1) from None
-
-
-main.add_command(cloud_group)
+# The original REQ-126 stub built a workspace tarball and posted to a free-
+# form endpoint with no auth. REQ-136 supersedes it with a manifest-based
+# command that posts to ``<endpoint>/spawn`` with optional bearer auth.
+# Keeping a single ``cloud spawn`` avoids surface drift; see
+# tests/test_warp_parity_followup.py for coverage.
 
 
 # ---------------------------------------------------------------------------

{specsmith-0.6.0.dev233 → specsmith-0.7.0}/src/specsmith/serve.py

@@ -153,11 +153,29 @@ class _Handler(BaseHTTPRequestHandler):
 
     bus: _EventBus
     agent: _AgentThread
+    auth_token: str = ""  # populated by run_server / make_server when set
 
     def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
         """Suppress default stderr logging."""
 
+    # ── Auth ─────────────────────────────────────────────────────────
+    # REQ-137: when run_server is started with --auth-token, every
+    # request must present `Authorization: Bearer <token>`. /api/health
+    # is the only unauthenticated endpoint so liveness probes still
+    # work behind a load balancer that strips Authorization.
+    def _authorize(self) -> bool:
+        token = type(self).auth_token
+        if not token:
+            return True
+        if self.path == "/api/health":
+            return True
+        header = self.headers.get("Authorization", "")
+        return header == f"Bearer {token}"
+
     def do_GET(self) -> None:  # noqa: N802
+        if not self._authorize():
+            self._json_response({"error": "unauthorized"}, code=401)
+            return
         if self.path == "/api/events":
             self._sse()
         elif self.path == "/api/status":
@@ -168,6 +186,9 @@ class _Handler(BaseHTTPRequestHandler):
             self.send_error(404)
 
     def do_POST(self) -> None:  # noqa: N802
+        if not self._authorize():
+            self._json_response({"error": "unauthorized"}, code=401)
+            return
         if self.path == "/api/send":
             body = self._read_json()
             text = body.get("text", "").strip() if body else ""
@@ -183,6 +204,9 @@ class _Handler(BaseHTTPRequestHandler):
             self.send_error(404)
 
     def do_DELETE(self) -> None:  # noqa: N802
+        if not self._authorize():
+            self._json_response({"error": "unauthorized"}, code=401)
+            return
         if self.path == "/api/session":
             self.agent.send(None)  # type: ignore[arg-type]
             self._json_response({"ok": True, "message": "session ending"})
@@ -246,38 +270,68 @@ class _Handler(BaseHTTPRequestHandler):
         self.wfile.write(body)
 
 
-def run_server(
+def make_server(
     *,
     project_dir: str = ".",
     provider: str = "ollama",
     model: str = "",
     port: int = 8421,
     host: str = "127.0.0.1",
-) -> None:
-    """Start the specsmith HTTP server."""
+    auth_token: str = "",
+) -> tuple[_ThreadedHTTPServer, _AgentThread]:
+    """Build the HTTP server + agent thread without serving yet.
+
+    Used by tests so they can drive a fresh server inside the same
+    process. Production callers go through ``run_server`` which adds
+    the banner + serve_forever loop.
+    """
     project_dir = str(Path(project_dir).resolve())
     bus = _EventBus()
     agent = _AgentThread(project_dir, provider, model, bus)
 
-    # Subclass to carry shared state into the handler
     class Handler(_Handler):
         pass
 
     Handler.bus = bus
     Handler.agent = agent
+    Handler.auth_token = auth_token
 
     server = _ThreadedHTTPServer((host, port), Handler)
+    return server, agent
+
+
+def run_server(
+    *,
+    project_dir: str = ".",
+    provider: str = "ollama",
+    model: str = "",
+    port: int = 8421,
+    host: str = "127.0.0.1",
+    auth_token: str = "",
+) -> None:
+    """Start the specsmith HTTP server."""
+    server, agent = make_server(
+        project_dir=project_dir,
+        provider=provider,
+        model=model,
+        port=port,
+        host=host,
+        auth_token=auth_token,
+    )
     agent.start()
 
+    auth_note = "  Auth:     bearer-token required\n" if auth_token else ""
     print(  # noqa: T201
         f"specsmith serve — http://{host}:{port}\n"
         f"  Project:  {project_dir}\n"
         f"  Provider: {provider}/{model or '(default)'}\n"
+        f"{auth_note}"
         f"  Endpoints:\n"
         f"    GET  /api/events  — SSE event stream\n"
         f"    POST /api/send    — send a message\n"
         f"    GET  /api/status  — session status\n"
         f"    POST /api/stop    — stop current turn\n"
+        f"    GET  /api/health  — unauthenticated liveness\n"
         f"  Press Ctrl+C to stop.\n",
         file=sys.stderr,
     )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.6.0.dev233
+Version: 0.7.0
 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.6.0.dev233 → specsmith-0.7.0}/src/specsmith.egg-info/SOURCES.txt

@@ -77,6 +77,7 @@ src/specsmith/agent/safety.py
 src/specsmith/agent/suggester.py
 src/specsmith/agent/tools.py
 src/specsmith/agent/verifier.py
+src/specsmith/agent/voice.py
 src/specsmith/commands/__init__.py
 src/specsmith/epistemic/__init__.py
 src/specsmith/epistemic/belief.py
@@ -179,4 +180,5 @@ tests/test_suggester.py
 tests/test_tools.py
 tests/test_validator.py
 tests/test_vcs.py
-tests/test_warp_parity.py
+tests/test_warp_parity.py
+tests/test_warp_parity_followup.py