specsmith 0.6.0.dev232__tar.gz → 0.6.0.dev233__tar.gz

{specsmith-0.6.0.dev232/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.dev232
+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.dev232 → specsmith-0.6.0.dev233}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.6.0.dev232"
+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/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.dev232 → specsmith-0.6.0.dev233}/src/specsmith/cli.py

@@ -4440,6 +4440,129 @@ 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)
 # ---------------------------------------------------------------------------

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

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Reference cloud-agent receiver for `specsmith cloud spawn` (REQ-136).
+
+A minimal stdlib HTTP server that accepts manifest-only POSTs at ``/spawn``
+and acks them. The full streaming-back-of-results contract is documented
+but kept narrow (and intentionally local-only) so we ship a working
+endpoint without baking in vendor coupling.
+
+Auth model: optional ``Authorization: Bearer <token>``. When the server
+is started with ``--token``, every request must present it.
+Defense-in-depth: the server refuses to bind to any address other than
+``127.0.0.1`` unless explicitly given ``--host`` AND ``--allow-cidr``.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import threading
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class CloudReceiverConfig:
+    host: str = "127.0.0.1"
+    port: int = 9000
+    token: str = ""
+    allow_cidr: str = ""
+    storage_dir: Path = field(default_factory=lambda: Path.home() / ".specsmith" / "cloud-runs")
+
+
+class _Handler(BaseHTTPRequestHandler):
+    config: CloudReceiverConfig = CloudReceiverConfig()
+
+    # noqa: N802 -- BaseHTTPRequestHandler API.
+    def do_POST(self) -> None:  # noqa: N802
+        if not self._authorize():
+            self._respond(401, {"error": "unauthorized"})
+            return
+        if self.path != "/spawn":
+            self._respond(404, {"error": f"unknown path {self.path}"})
+            return
+        length = int(self.headers.get("Content-Length", "0") or "0")
+        body = self.rfile.read(length) if length else b""
+        try:
+            payload = json.loads(body.decode("utf-8") or "{}")
+        except ValueError:
+            self._respond(400, {"error": "invalid json"})
+            return
+        run_id = str(payload.get("run_id", "")).strip() or _new_run_id()
+        target = self.config.storage_dir / run_id
+        try:
+            target.mkdir(parents=True, exist_ok=True)
+            (target / "manifest.json").write_text(
+                json.dumps(payload, indent=2),
+                encoding="utf-8",
+            )
+        except OSError as exc:
+            self._respond(500, {"error": f"storage failed: {exc}"})
+            return
+        self._respond(
+            202,
+            {
+                "run_id": run_id,
+                "status": "accepted",
+                "stream_url": f"/runs/{run_id}/events",
+            },
+        )
+
+    def do_GET(self) -> None:  # noqa: N802
+        if not self._authorize():
+            self._respond(401, {"error": "unauthorized"})
+            return
+        if self.path == "/health":
+            self._respond(200, {"ok": True})
+            return
+        self._respond(404, {"error": f"unknown path {self.path}"})
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+        # Quiet by default — caller sees JSON responses.
+        return
+
+    # ── helpers ───────────────────────────────────────────────────────────
+
+    def _authorize(self) -> bool:
+        if self.config.token:
+            header = self.headers.get("Authorization", "")
+            if header != f"Bearer {self.config.token}":
+                return False
+        if self.config.allow_cidr:
+            try:
+                net = ipaddress.ip_network(self.config.allow_cidr, strict=False)
+                client = ipaddress.ip_address(self.client_address[0])
+                if client not in net:
+                    return False
+            except (ValueError, TypeError):
+                return False
+        return True
+
+    def _respond(self, status: int, payload: dict[str, Any]) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+def _new_run_id() -> str:
+    import uuid
+
+    return f"cloud_{uuid.uuid4().hex[:12]}"
+
+
+def _validate_host(config: CloudReceiverConfig) -> None:
+    if config.host not in {"127.0.0.1", "::1", "localhost"} and not config.allow_cidr:
+        raise RuntimeError(
+            "specsmith cloud serve refuses to bind to a non-loopback address "
+            "unless --allow-cidr is also set. This is a security guardrail."
+        )
+
+
+def make_server(config: CloudReceiverConfig) -> HTTPServer:
+    _validate_host(config)
+    config.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    class _Bound(_Handler):
+        pass
+
+    _Bound.config = config
+    return HTTPServer((config.host, config.port), _Bound)
+
+
+def run_in_thread(config: CloudReceiverConfig) -> tuple[HTTPServer, threading.Thread]:
+    """Start the server in a background thread; useful for tests."""
+    server = make_server(config)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server, thread
+
+
+__all__ = [
+    "CloudReceiverConfig",
+    "make_server",
+    "run_in_thread",
+]

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

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Specsmith Drive (REQ-133) — sync rules/workflows/notebooks across machines.
+
+Backend agnostic: the default backend is a local filesystem mirror under
+``~/.specsmith/drive/`` which the user can ``git push`` themselves. An
+HTTP backend is documented but not bundled (see ``examples/drive_http_server.py``
+once it exists).
+
+Supported artifact kinds:
+* ``rules`` — files under ``docs/governance/*_RULES.md``
+* ``workflows`` — files under ``.specsmith/workflows/*.yml``
+* ``notebooks`` — files under ``docs/notebooks/*.md``
+
+Each project's artifacts go into ``<drive>/<project_name>/<kind>/<file>``.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+KINDS = ("rules", "workflows", "notebooks")
+
+
+def default_drive_dir() -> Path:
+    return Path.home() / ".specsmith" / "drive"
+
+
+def _kind_sources(project_dir: Path) -> dict[str, list[Path]]:
+    return {
+        "rules": sorted((project_dir / "docs" / "governance").glob("*_RULES.md"))
+        if (project_dir / "docs" / "governance").is_dir()
+        else [],
+        "workflows": sorted((project_dir / ".specsmith" / "workflows").glob("*.yml"))
+        if (project_dir / ".specsmith" / "workflows").is_dir()
+        else [],
+        "notebooks": sorted((project_dir / "docs" / "notebooks").glob("*.md"))
+        if (project_dir / "docs" / "notebooks").is_dir()
+        else [],
+    }
+
+
+def _kind_dest(drive_dir: Path, project_name: str, kind: str) -> Path:
+    return drive_dir / project_name / kind
+
+
+@dataclass
+class DriveResult:
+    pushed: list[str]
+    pulled: list[str]
+    skipped: list[str]
+    errors: list[str]
+
+
+def push(project_dir: Path, drive_dir: Path | None = None) -> DriveResult:
+    """Mirror project artifacts into the drive directory."""
+    drive_dir = drive_dir or default_drive_dir()
+    project_name = project_dir.name
+    pushed: list[str] = []
+    skipped: list[str] = []
+    errors: list[str] = []
+    for kind, files in _kind_sources(project_dir).items():
+        dest = _kind_dest(drive_dir, project_name, kind)
+        dest.mkdir(parents=True, exist_ok=True)
+        for src in files:
+            try:
+                shutil.copy2(src, dest / src.name)
+                pushed.append(f"{kind}/{src.name}")
+            except OSError as exc:
+                errors.append(f"{kind}/{src.name}: {exc}")
+        if not files:
+            skipped.append(f"{kind} (no source files)")
+    return DriveResult(pushed=pushed, pulled=[], skipped=skipped, errors=errors)
+
+
+def pull(project_dir: Path, drive_dir: Path | None = None) -> DriveResult:
+    """Mirror drive artifacts back into the project."""
+    drive_dir = drive_dir or default_drive_dir()
+    project_name = project_dir.name
+    pulled: list[str] = []
+    skipped: list[str] = []
+    errors: list[str] = []
+    project_targets = {
+        "rules": project_dir / "docs" / "governance",
+        "workflows": project_dir / ".specsmith" / "workflows",
+        "notebooks": project_dir / "docs" / "notebooks",
+    }
+    for kind, target in project_targets.items():
+        src_dir = _kind_dest(drive_dir, project_name, kind)
+        if not src_dir.is_dir():
+            skipped.append(f"{kind} (no drive entry)")
+            continue
+        target.mkdir(parents=True, exist_ok=True)
+        for src in sorted(src_dir.iterdir()):
+            if not src.is_file():
+                continue
+            try:
+                shutil.copy2(src, target / src.name)
+                pulled.append(f"{kind}/{src.name}")
+            except OSError as exc:
+                errors.append(f"{kind}/{src.name}: {exc}")
+    return DriveResult(pushed=[], pulled=pulled, skipped=skipped, errors=errors)
+
+
+def listing(drive_dir: Path | None = None) -> dict[str, dict[str, list[str]]]:
+    """Return ``{project: {kind: [filenames]}}`` for everything in the drive."""
+    drive_dir = drive_dir or default_drive_dir()
+    out: dict[str, dict[str, list[str]]] = {}
+    if not drive_dir.is_dir():
+        return out
+    for project_path in sorted(drive_dir.iterdir()):
+        if not project_path.is_dir():
+            continue
+        kinds: dict[str, list[str]] = {}
+        for kind in KINDS:
+            d = project_path / kind
+            if d.is_dir():
+                kinds[kind] = sorted(p.name for p in d.iterdir() if p.is_file())
+        if kinds:
+            out[project_path.name] = kinds
+    return out
+
+
+__all__ = ["DriveResult", "KINDS", "default_drive_dir", "listing", "pull", "push"]