algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/url_scheme.py

@@ -0,0 +1,174 @@
+"""URL scheme handler for Algo CLI.
+
+Handles algo-cli:// deep links, inspired by Ollama's ollama:// URL scheme.
+
+Supported routes:
+  algo-cli://skill/<name>           — load and display a skill
+  algo-cli://memory/recall?q=<query> — trigger a memory recall search
+  algo-cli://session/new             — start a new session
+  algo-cli://session/load?name=<n>   — load a saved session
+  algo-cli://plugin/<name>           — show plugin status
+  algo-cli://version                 — show full version manifest
+  algo-cli://credential/<helper>     — show credential helper status
+
+The handler parses the URL and returns a ParsedDeepLink describing the
+action to take. The caller (CLI entry point or GUI companion) is responsible
+for executing the action.
+"""
+from __future__ import annotations
+
+import logging
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+URL_SCHEME = "algo-cli"
+
+
+@dataclass(frozen=True)
+class ParsedDeepLink:
+    """A parsed algo-cli:// deep link."""
+    route: str
+    path: str
+    query: dict[str, str] = field(default_factory=dict)
+    raw_url: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "route": self.route,
+            "path": self.path,
+            "query": self.query,
+            "raw_url": self.raw_url,
+        }
+
+
+# Supported routes and their expected path/query parameters
+KNOWN_ROUTES: dict[str, dict[str, Any]] = {
+    "skill": {"path_required": True, "description": "Load and display a skill by name"},
+    "memory": {"path_required": True, "description": "Memory operations (recall, list)"},
+    "session": {"path_required": True, "description": "Session operations (new, load)"},
+    "plugin": {"path_required": True, "description": "Show plugin status by name"},
+    "version": {"path_required": False, "description": "Show full version manifest"},
+    "credential": {"path_required": True, "description": "Show credential helper status"},
+}
+
+
+def parse_deep_link(url: str) -> ParsedDeepLink | None:
+    """Parse an algo-cli:// URL into a ParsedDeepLink.
+
+    Returns None if the URL is not a valid algo-cli:// link.
+    """
+    if not url:
+        return None
+
+    # Accept both algo-cli:// and algo-cli: for flexibility
+    if url.startswith(f"{URL_SCHEME}://"):
+        remainder = url[len(f"{URL_SCHEME}://"):]
+    elif url.startswith(f"{URL_SCHEME}:"):
+        remainder = url[len(f"{URL_SCHEME}:"):]
+    else:
+        return None
+
+    # Strip leading slashes
+    remainder = remainder.lstrip("/")
+
+    # Parse query string if present
+    if "?" in remainder:
+        path_part, query_part = remainder.split("?", 1)
+        query = dict(urllib.parse.parse_qsl(query_part))
+    else:
+        path_part = remainder
+        query = {}
+
+    path_part = path_part.rstrip("/")
+    if not path_part:
+        return ParsedDeepLink(route="", path="", query=query, raw_url=url)
+
+    # Split into route and sub-path
+    parts = path_part.split("/", 1)
+    route = parts[0].lower()
+    sub_path = parts[1] if len(parts) > 1 else ""
+
+    return ParsedDeepLink(
+        route=route,
+        path=sub_path,
+        query=query,
+        raw_url=url,
+    )
+
+
+def validate_deep_link(link: ParsedDeepLink) -> tuple[bool, str]:
+    """Validate a parsed deep link. Returns (is_valid, error_message)."""
+    if not link.route:
+        return False, "Empty route"
+
+    if link.route not in KNOWN_ROUTES:
+        known = ", ".join(sorted(KNOWN_ROUTES.keys()))
+        return False, f"Unknown route '{link.route}'. Known routes: {known}"
+
+    route_info = KNOWN_ROUTES[link.route]
+    if route_info["path_required"] and not link.path:
+        return False, f"Route '{link.route}' requires a path component"
+
+    return True, ""
+
+
+def handle_deep_link(url: str) -> dict[str, Any]:
+    """Parse and validate a deep link URL, returning an action descriptor.
+
+    This is the main entry point. It returns a dict with:
+      - valid: bool
+      - error: str (if invalid)
+      - action: str (the route name)
+      - target: str (the path component)
+      - query: dict (query parameters)
+      - raw_url: str
+
+    The caller is responsible for executing the action.
+    """
+    parsed = parse_deep_link(url)
+    if parsed is None:
+        return {
+            "valid": False,
+            "error": f"URL does not start with {URL_SCHEME}://",
+            "raw_url": url,
+        }
+
+    is_valid, error = validate_deep_link(parsed)
+    if not is_valid:
+        return {
+            "valid": False,
+            "error": error,
+            "raw_url": url,
+            **parsed.as_dict(),
+        }
+
+    return {
+        "valid": True,
+        "error": "",
+        "action": parsed.route,
+        "target": parsed.path,
+        "query": parsed.query,
+        "raw_url": url,
+    }
+
+
+def format_help() -> str:
+    """Return a help string listing all supported deep link routes."""
+    lines = [f"Algo CLI URL scheme: {URL_SCHEME}://<route>/<path>?<query>"]
+    lines.append("")
+    lines.append("Supported routes:")
+    for route, info in sorted(KNOWN_ROUTES.items()):
+        path_req = " <path>" if info["path_required"] else ""
+        lines.append(f"  {URL_SCHEME}://{route}{path_req}")
+        lines.append(f"    {info['description']}")
+    lines.append("")
+    lines.append("Examples:")
+    lines.append(f"  {URL_SCHEME}://skill/echo-veil-integration")
+    lines.append(f"  {URL_SCHEME}://memory/recall?q=rebrand")
+    lines.append(f"  {URL_SCHEME}://session/new")
+    lines.append(f"  {URL_SCHEME}://session/load?name=my-session")
+    lines.append(f"  {URL_SCHEME}://version")
+    return "\n".join(lines)

algo_cli/verify.py

@@ -0,0 +1,154 @@
+"""Hallucination-prevention layer for small models.
+
+Three components wired together:
+  1. parameter_size_billions()  — parse model size string to float (lives in model_info)
+  2. extract_claims()           — maintenance-model pass decomposing a response into
+                                  individual verifiable factual claims
+  3. ground_claim()             — each claim is checked against the harness index;
+                                  ungrounded claims are returned for user visibility
+  4. verify_response()          — orchestrates 2+3 and returns a structured report
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Callable
+
+from . import harness
+
+LLMFn = Callable[[str, str], str]
+
+_MIN_CLAIM_CHARS = 12
+
+_EXTRACT_SYSTEM = (
+    "You are a factual claim extractor. Given text, list every verifiable factual claim "
+    "as a JSON array under the key 'claims'. A claim is a specific, checkable assertion: "
+    "a file path, function name, version number, shell command, URL, configuration key, "
+    "or named technical concept. Omit vague statements and subjective opinions. "
+    'Output only valid JSON: {"claims": ["claim1", "claim2", ...]}'
+)
+
+_WORD_RE = re.compile(r"[a-zA-Z0-9_\-\.]+")
+_COMMON_WORDS = frozenset(
+    {
+        "the", "and", "for", "that", "this", "with", "from", "file", "uses",
+        "use", "has", "have", "will", "into", "json", "text", "data", "code",
+        "line", "lines", "path",
+    }
+)
+
+
+def extract_claims(text: str, llm_fn: LLMFn) -> list[str]:
+    """Use a maintenance LLM pass to extract factual claims from model output.
+
+    Returns an empty list on any failure — never raises.
+    """
+    if not text or not text.strip():
+        return []
+    try:
+        raw = llm_fn(_EXTRACT_SYSTEM, text)
+        data = json.loads(raw)
+        claims = data.get("claims", [])
+        if not isinstance(claims, list):
+            return []
+        return [
+            str(c).strip()
+            for c in claims
+            if str(c).strip() and len(str(c).strip()) >= _MIN_CLAIM_CHARS
+        ]
+    except Exception:
+        return []
+
+
+def ground_claim(claim: str, *, limit: int = 3) -> dict[str, Any]:
+    """Check whether a claim has supporting evidence in the harness index.
+
+    Returns:
+        {"claim": str, "grounded": bool, "sources": list[str]}
+    """
+    if not claim or not claim.strip():
+        return {"claim": claim, "grounded": False, "sources": []}
+    words = _WORD_RE.findall(claim)
+    keywords = [w for w in words if len(w) >= 4 and w.lower() not in _COMMON_WORDS][:8]
+    query = " ".join(keywords)
+    if not query:
+        return {"claim": claim, "grounded": False, "sources": []}
+    try:
+        results = harness.search_index(query, limit=limit)
+    except Exception:
+        results = []
+    claim_tokens = {w.lower() for w in keywords}
+    sources: list[str] = []
+    for result in results:
+        haystack = " ".join(
+            str(result.get(key, ""))
+            for key in ("id", "title", "path", "relative_path", "description", "summary", "search_text")
+        ).lower()
+        if any(token in haystack for token in claim_tokens):
+            if result.get("id"):
+                sources.append(str(result["id"]))
+    if sources:
+        return {
+            "claim": claim,
+            "grounded": True,
+            "sources": sources[:limit],
+        }
+    return {"claim": claim, "grounded": False, "sources": []}
+
+
+def verify_response(text: str, llm_fn: LLMFn) -> dict[str, Any]:
+    """Full claim-extraction + harness-grounding pipeline.
+
+    Returns:
+        {
+            "total_claims": int,
+            "grounded_count": int,
+            "ungrounded_count": int,
+            "grounded": [...],
+            "ungrounded": [...],
+            "confidence": float,   # fraction of claims grounded (1.0 if no claims)
+        }
+    """
+    claims = extract_claims(text, llm_fn)
+    if not claims:
+        return {
+            "total_claims": 0,
+            "grounded_count": 0,
+            "ungrounded_count": 0,
+            "grounded": [],
+            "ungrounded": [],
+            "confidence": 1.0,
+        }
+    results = [ground_claim(c) for c in claims]
+    grounded = [r for r in results if r["grounded"]]
+    ungrounded = [r for r in results if not r["grounded"]]
+    confidence = len(grounded) / len(results) if results else 1.0
+    return {
+        "total_claims": len(claims),
+        "grounded_count": len(grounded),
+        "ungrounded_count": len(ungrounded),
+        "grounded": grounded,
+        "ungrounded": ungrounded,
+        "confidence": round(confidence, 3),
+    }
+
+
+def format_verification_report(result: dict[str, Any]) -> str:
+    """Human-readable summary of a verify_response result."""
+    total = result.get("total_claims", 0)
+    if total == 0:
+        return ""
+    grounded_count = result["grounded_count"]
+    confidence = result["confidence"]
+    lines = [
+        f"[Verify] {grounded_count}/{total} claims grounded in harness  "
+        f"(confidence {confidence:.0%})"
+    ]
+    ungrounded = result.get("ungrounded", [])
+    if ungrounded:
+        lines.append("Unverified claims (not found in harness index):")
+        for item in ungrounded[:5]:
+            lines.append(f"  · {item['claim']}")
+        if len(ungrounded) > 5:
+            lines.append(f"  · …and {len(ungrounded) - 5} more")
+    return "\n".join(lines)

algo_cli/version_manifest.py

@@ -0,0 +1,178 @@
+"""Version manifest for Algo CLI.
+
+Tracks the full system state — not just the CLI binary version, but the
+harness index version, embedding model, knowledge graph version, and any
+loaded plugin versions. Inspired by Docker's componentsVersion.json.
+
+The manifest may be written to ~/.algo_cli/versions.json. `algo-cli --version`
+only reads state that already exists; it never builds an index or scaffolds files.
+"""
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .config import CONFIG_DIR
+from . import __version__ as _cli_version
+
+VERSIONS_FILE = CONFIG_DIR / "versions.json"
+EXTENSIONS_VERSION_FILE = CONFIG_DIR / "extensions_version.json"
+
+
+@dataclass
+class VersionManifest:
+    """Full system version state."""
+    cli_version: str = _cli_version
+    python_version: str = ""
+    platform: str = ""
+    harness_index_version: str = ""
+    harness_record_count: int = 0
+    harness_embed_model: str = ""
+    knowledge_graph_version: str = ""
+    knowledge_graph_node_count: int = 0
+    plugins: dict[str, str] = field(default_factory=dict)
+    config_dir: str = ""
+    updated_at: float = 0.0
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.as_dict(), indent=2)
+
+
+def _safe_get_harness_info() -> dict[str, Any]:
+    """Read an existing harness index without building or refreshing it."""
+    try:
+        from . import harness
+        if not harness.INDEX_PATH.is_file():
+            return {}
+        index = json.loads(harness.INDEX_PATH.read_text(encoding="utf-8"))
+        record_count = len(index.get("records", []))
+        embed_model = index.get("embed_model", "")
+        index_version = index.get("version", "")
+        return {
+            "harness_index_version": index_version,
+            "harness_record_count": record_count,
+            "harness_embed_model": embed_model,
+        }
+    except Exception:
+        return {}
+
+
+def _safe_get_kg_info() -> dict[str, Any]:
+    """Read existing knowledge-graph metadata without running the graph."""
+    try:
+        from . import index_compute_lab
+        assets = index_compute_lab.lab_assets()
+        if assets is not None:
+            _root, graph_path, _aliases = assets
+            data = json.loads(graph_path.read_text(encoding="utf-8"))
+            nodes = data.get("nodes")
+            index = data.get("index")
+            node_count = len(nodes) if isinstance(nodes, list) else len(index) if isinstance(index, dict) else 0
+            version = data.get("version") or data.get("schema_version") or ""
+            return {
+                "knowledge_graph_version": version,
+                "knowledge_graph_node_count": node_count,
+            }
+    except Exception:
+        pass
+    return {}
+
+
+def _safe_get_plugin_versions() -> dict[str, str]:
+    """Safely query loaded plugins for their versions."""
+    try:
+        from . import plugins as plugins_module
+        manifests = plugins_module.discover_plugins()
+        return {m.name: m.version for m in manifests}
+    except Exception:
+        return {}
+
+
+def build_manifest() -> VersionManifest:
+    """Build a version manifest from the current system state."""
+    import platform as _platform
+    import sys
+
+    harness_info = _safe_get_harness_info()
+    kg_info = _safe_get_knowledge_graph_info()
+    plugin_versions = _safe_get_plugin_versions()
+
+    return VersionManifest(
+        cli_version=_cli_version,
+        python_version=sys.version.split()[0] if sys.version else "",
+        platform=f"{_platform.system()} {_platform.machine()}",
+        harness_index_version=harness_info.get("harness_index_version", ""),
+        harness_record_count=harness_info.get("harness_record_count", 0),
+        harness_embed_model=harness_info.get("harness_embed_model", ""),
+        knowledge_graph_version=kg_info.get("knowledge_graph_version", ""),
+        knowledge_graph_node_count=kg_info.get("knowledge_graph_node_count", 0),
+        plugins=plugin_versions,
+        config_dir="~/.algo_cli (or ALGO_CLI_CONFIG_DIR)",
+        updated_at=time.time(),
+    )
+
+
+def _safe_get_knowledge_graph_info() -> dict[str, Any]:
+    """Alias for _safe_get_kg_info to avoid name collision."""
+    return _safe_get_kg_info()
+
+
+def save_manifest() -> VersionManifest:
+    """Build and persist the version manifest to disk."""
+    manifest = build_manifest()
+    try:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        VERSIONS_FILE.write_text(manifest.to_json(), encoding="utf-8")
+    except OSError as exc:
+        # Don't crash if we can't write — just log
+        import logging
+        logging.getLogger(__name__).warning("Could not save version manifest: %s", exc)
+    return manifest
+
+
+def load_manifest() -> VersionManifest | None:
+    """Load a previously saved version manifest from disk."""
+    try:
+        data = json.loads(VERSIONS_FILE.read_text(encoding="utf-8"))
+        return VersionManifest(**data)
+    except (FileNotFoundError, json.JSONDecodeError, TypeError):
+        return None
+
+
+def format_version_string(manifest: VersionManifest | None = None) -> str:
+    """Format a human-readable version string showing full system state."""
+    if manifest is None:
+        manifest = build_manifest()
+
+    lines = [
+        f"Algo CLI v{manifest.cli_version}",
+        f"  Python:      {manifest.python_version}",
+        f"  Platform:    {manifest.platform}",
+        f"  Config dir:   {manifest.config_dir}",
+    ]
+
+    if manifest.harness_record_count > 0:
+        lines.append(
+            f"  Harness:     {manifest.harness_record_count} records"
+            f" (index v{manifest.harness_index_version or 'unknown'})"
+        )
+        if manifest.harness_embed_model:
+            lines.append(f"  Embed model: {manifest.harness_embed_model}")
+
+    if manifest.knowledge_graph_node_count > 0:
+        lines.append(
+            f"  KG:          {manifest.knowledge_graph_node_count} nodes"
+            f" (v{manifest.knowledge_graph_version or 'unknown'})"
+        )
+
+    if manifest.plugins:
+        lines.append("  Plugins:")
+        for name, version in sorted(manifest.plugins.items()):
+            lines.append(f"    {name} v{version}")
+
+    return "\n".join(lines)

algo_cli/vision_screenshot_verify.py

@@ -0,0 +1,76 @@
+"""Screenshot-as-verification helpers (I6).
+
+These helpers do not call a vision model themselves. They validate the textual
+result returned by ``vision_describe`` against expected/forbidden UI evidence,
+so screenshots become structured test artifacts instead of informal notes.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ScreenshotVerification:
+    """Structured result for screenshot description verification."""
+
+    passed: bool
+    expected_terms: tuple[str, ...]
+    missing_terms: tuple[str, ...]
+    forbidden_terms: tuple[str, ...]
+    forbidden_hits: tuple[str, ...]
+    coverage: float
+    summary: str
+
+    def to_dict(self) -> dict:
+        return {
+            "passed": self.passed,
+            "expected_terms": list(self.expected_terms),
+            "missing_terms": list(self.missing_terms),
+            "forbidden_terms": list(self.forbidden_terms),
+            "forbidden_hits": list(self.forbidden_hits),
+            "coverage": round(self.coverage, 3),
+            "summary": self.summary,
+        }
+
+
+def _contains_term(text: str, term: str) -> bool:
+    return term.strip().lower() in text.lower()
+
+
+def verify_screenshot_description(
+    description: str,
+    expected_terms: list[str] | tuple[str, ...] = (),
+    forbidden_terms: list[str] | tuple[str, ...] = (),
+) -> ScreenshotVerification:
+    """Verify a screenshot description against expected and forbidden evidence.
+
+    Args:
+        description: Text returned by a vision/OCR model.
+        expected_terms: Terms that should appear in the description.
+        forbidden_terms: Terms that must not appear (for example, "error").
+
+    Returns:
+        A structured verification result suitable for tests or reports.
+    """
+    expected = tuple(term.strip() for term in expected_terms if term and term.strip())
+    forbidden = tuple(term.strip() for term in forbidden_terms if term and term.strip())
+    missing = tuple(term for term in expected if not _contains_term(description or "", term))
+    hits = tuple(term for term in forbidden if _contains_term(description or "", term))
+    coverage = 1.0 if not expected else (len(expected) - len(missing)) / len(expected)
+    passed = not missing and not hits
+    summary = (
+        f"screenshot verification {'passed' if passed else 'failed'}: "
+        f"coverage={coverage:.2f}, missing={len(missing)}, forbidden_hits={len(hits)}"
+    )
+    return ScreenshotVerification(
+        passed=passed,
+        expected_terms=expected,
+        missing_terms=missing,
+        forbidden_terms=forbidden,
+        forbidden_hits=hits,
+        coverage=coverage,
+        summary=summary,
+    )
+
+
+__all__ = ["ScreenshotVerification", "verify_screenshot_description"]

algo_cli/workspace_resolver.py

@@ -0,0 +1,68 @@
+"""Resolve an agent session cwd from generic project hints."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from pathlib import Path
+from typing import Any
+
+
+_WIN_DRIVE_ABS = re.compile(r"^(?:\\\\\?\\)?[A-Za-z]:[\\/]")
+
+
+def parse_path_arg(arg: str) -> str:
+    """Parse a single path from a slash-command argument (handles quoted Windows paths)."""
+    text = (arg or "").strip()
+    if not text:
+        return ""
+    # shlex treats backslash as escape (POSIX rules), so a Windows absolute path loses separators.
+    if _WIN_DRIVE_ABS.match(text) or (len(text) >= 2 and text[1] == ":" and text[0].isalpha()):
+        return text.strip('"').strip("'")
+    if text[0] in "\"'":
+        try:
+            parts = shlex.split(text)
+            return parts[0] if parts else ""
+        except ValueError:
+            return text.strip('"').strip("'")
+    try:
+        parts = shlex.split(text)
+    except ValueError:
+        parts = [text.strip('"').strip("'")]
+    return parts[0] if parts else ""
+
+_ALGO_CLI_PATH = re.compile(r"\balgo_cli/", re.IGNORECASE)
+_ALGO_CLI_NAME = re.compile(r"\b(?:ollama-cli|algo-cli)\b", re.IGNORECASE)
+
+
+def candidate_workspaces(task: str) -> list[Path]:
+    text = task or ""
+    candidates: list[Path] = []
+    if _ALGO_CLI_PATH.search(text) or _ALGO_CLI_NAME.search(text):
+        candidates.append(Path.home() / "algo-cli")
+        legacy = Path.home() / "ollama-cli"
+        if legacy.is_dir() and legacy != candidates[-1]:
+            candidates.append(legacy)
+    return candidates
+
+
+def _is_valid_workspace(root: Path) -> bool:
+    if not root.is_dir():
+        return False
+    return (root / "algo_cli").is_dir()
+
+
+def resolve_agent_workspace(task: str, cfg: Any) -> bool:
+    """Point cfg.cwd at a known project root inferred from the task. Returns True if updated."""
+    seen: set[str] = set()
+    for root in candidate_workspaces(task):
+        key = str(root)
+        if key in seen:
+            continue
+        seen.add(key)
+        if _is_valid_workspace(root):
+            cfg.cwd = str(root.resolve())
+            if hasattr(cfg, "save"):
+                cfg.save()
+            return True
+    return False