@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/http_client.py

@@ -1,160 +0,0 @@
-"""Typed HTTP client for the MCP Router.
-
-Protocol (empirically verified):
-  - HTTP POST to /mcp with JSON-RPC 2.0 body
-  - Accept: text/event-stream  (required; router returns HTTP 406 without it)
-  - Response is SSE-formatted: exactly 3 lines
-      event: message               ← always "message", semantically inert
-      data: <complete JSON-RPC>    ← one-shot, full response in one JSON blob
-      <blank line>                 ← SSE terminator; stop reading after this
-  - MCP Router is synchronous (one-shot request/response); no progressive streaming.
-  - Uses httpx.stream() to avoid hanging on keep-alive connections.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-import httpx
-
-from vds_research_orchestrator.config import ResearchSettings
-from vds_research_orchestrator.exceptions import (
-    McpRouterAuthError,
-    McpRouterError,
-    McpRouterNoEventsError,
-    McpRouterProtocolError,
-    McpRouterServerError,
-    McpRouterTimeout,
-)
-
-
-class MCPClient:
-    """Synchronous HTTP client for the MCP Router JSON-RPC API."""
-
-    def __init__(self, settings: ResearchSettings | None = None) -> None:
-        self.settings = settings or ResearchSettings()
-        self._client: httpx.Client | None = None
-
-    # ── lifecycle ──────────────────────────────────────────────────────────────
-
-    def _ensure_client(self, timeout: int | None = None) -> httpx.Client:
-        if self._client is None:
-            effective_timeout = timeout or self.settings.default_tool_timeout
-            self._client = httpx.Client(
-                base_url=self.settings.mcpr_url,
-                http2=False,
-                timeout=httpx.Timeout(
-                    timeout=effective_timeout,
-                    connect=10.0,
-                ),
-            )
-        return self._client
-
-    def close(self) -> None:
-        if self._client:
-            self._client.close()
-            self._client = None
-
-    def __enter__(self) -> MCPClient:
-        return self
-
-    def __exit__(self, *args: object) -> None:
-        self.close()
-
-    # ── SSE parsing ────────────────────────────────────────────────────────────
-
-    def _read_sse_events(self, response: httpx.Response) -> list[str]:
-        """Parse SSE events from httpx streaming response.
-
-        Reads lines until blank-line terminator.
-        """
-        events: list[str] = []
-        for raw_line in response.iter_lines():
-            line = raw_line.rstrip("\r\n")
-            if not line:
-                break  # blank = terminator
-            if line.startswith("event: "):
-                continue
-            if not line.startswith("data: "):
-                continue
-            events.append(line[6:])
-        if not events:
-            raise McpRouterNoEventsError(
-                f"No SSE events from {self.settings.mcpr_url}. "
-                "MCP Router may be unreachable or returned an empty response.",
-            )
-        return events
-
-    # ── HTTP ───────────────────────────────────────────────────────────────────
-
-    def _rpc(self, method: str, params: dict[str, Any], timeout: int) -> dict[str, Any]:
-        """Fire a JSON-RPC request via streaming and return parsed result."""
-        payload = {"jsonrpc": "2.0", "method": method, "id": 1, "params": params}
-        try:
-            with self._ensure_client(timeout).stream(
-                "POST",
-                "/mcp",
-                json=payload,
-                headers={
-                    "Content-Type": "application/json",
-                    "Accept": "application/json, text/event-stream",
-                    "Authorization": f"Bearer {self.settings.mcpr_token}",
-                },
-            ) as response:
-                self._check_status(response)
-                events = self._read_sse_events(response)
-        except httpx.TimeoutException as exc:
-            raise McpRouterTimeout(str(exc)) from exc
-        except httpx.RequestError as exc:
-            raise McpRouterError(
-                f"Connection failed to {self.settings.mcpr_url}: {exc}",
-            ) from exc
-        try:
-            parsed = json.loads(events[0])
-        except json.JSONDecodeError as exc:
-            raise McpRouterProtocolError(
-                f"Invalid JSON in SSE event: {exc}",
-            ) from exc
-        return parsed
-
-    def _check_status(self, response: httpx.Response) -> None:
-        if response.status_code in (401, 403):
-            raise McpRouterAuthError(
-                f"Authentication failed: HTTP {response.status_code}. "
-                "Verify MCPR_TOKEN is present in ~/.vds/.env.",
-            )
-        if response.status_code >= 500:
-            raise McpRouterServerError(
-                f"MCP Router returned HTTP {response.status_code}",
-            )
-        if response.status_code == 406:
-            try:
-                body = response.json()
-                msg = body.get("error", {}).get("message", str(response.text))
-            except Exception:
-                msg = str(response.text)
-            raise McpRouterProtocolError(
-                f"Accept: text/event-stream required. HTTP 406: {msg}",
-            )
-        response.raise_for_status()
-
-    # ── public API ─────────────────────────────────────────────────────────────
-
-    def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any],
-        timeout: int | None = None,
-    ) -> dict[str, Any]:
-        """Call an MCP tool and return the parsed result dictionary."""
-        return self._rpc(
-            "tools/call",
-            {"name": name, "arguments": arguments},
-            timeout=timeout or self.settings.default_tool_timeout,
-        )
-
-    def list_tools(self) -> list[dict[str, Any]]:
-        """List all available MCP tools."""
-        result = self._rpc("tools/list", {}, timeout=15)
-        return result.get("result", {}).get("tools", [])

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/logging.py

@@ -1,49 +0,0 @@
-"""Structured logging setup for vds-research CLI.
-
-Uses structlog for structured output; Rich for console rendering.
-"""
-
-from __future__ import annotations
-
-import sys
-
-import structlog
-
-
-def configure(verbose: bool = False) -> None:
-    """Configure structlog for the vds-research CLI.
-
-    Args:
-        verbose: If True, log at DEBUG level; otherwise INFO.
-    """
-    log_level = "DEBUG" if verbose else "INFO"
-
-    structlog.configure(
-        processors=[
-            structlog.stdlib.filter_by_level,
-            structlog.stdlib.add_logger_name,
-            structlog.stdlib.add_log_level,
-            structlog.stdlib.PositionalArgumentsFormatter(),
-            structlog.processors.TimeStamper(fmt="iso"),
-            structlog.processors.StackInfoRenderer(),
-            structlog.processors.format_exc_info,
-            structlog.processors.UnicodeDecoder(),
-            structlog.processors.JSONRenderer()
-            if not sys.stdout.isatty()
-            else structlog.dev.ConsoleRenderer(colors=True),
-        ],
-        wrapper_class=structlog.stdlib.BoundLogger,
-        context_class=dict,
-        logger_factory=structlog.stdlib.LoggerFactory(),
-        cache_logger_on_first_use=True,
-    )
-
-    # Set global log level via environment variable for structlog stdlib bridge
-    import os
-
-    os.environ["LOG_LEVEL"] = log_level
-
-
-def get_logger(name: str) -> structlog.stdlib.BoundLogger:
-    """Return a bound structlog logger for the given module name."""
-    return structlog.get_logger(name)

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/output/formatters.py

@@ -1,93 +0,0 @@
-"""JSON and markdown output formatters for CLI commands."""
-
-from __future__ import annotations
-
-import json
-import sys
-from typing import Any
-
-from rich.console import Console
-from rich.table import Table
-
-console = Console()
-
-
-# ── JSON output ───────────────────────────────────────────────────────────────
-
-JSON_INDENT = 2
-
-
-def emit_json(data: dict[str, Any]) -> None:
-    """Write a Python object as JSON to stdout."""
-    sys.stdout.write(json.dumps(data, indent=JSON_INDENT, ensure_ascii=False))
-    sys.stdout.write("\n")
-
-
-def format_json_success(command: str, data: dict[str, Any]) -> dict[str, Any]:
-    return {"ok": True, "command": command, "data": data}
-
-
-def format_json_error(command: str, error: str, error_type: str) -> dict[str, Any]:
-    return {"ok": False, "command": command, "error": error, "error_type": error_type}
-
-
-# ── Human-readable tables ─────────────────────────────────────────────────────
-
-
-def print_search_table(query: str, tool: str, results: list[dict[str, Any]]) -> None:
-    console.print(f"[cyan]🔍 {query}[/cyan] via [bold]{tool}[/bold]")
-    if not results:
-        console.print("[dim]No results found.[/dim]")
-        return
-    for r in results:
-        title = r.get("title") or "(no title)"
-        url = r.get("url") or ""
-        snippet = r.get("snippet") or ""
-        score = r.get("score", 0.0)
-        console.print(f"  [bold cyan]{title}[/bold cyan]")
-        if url:
-            console.print(f"  [dim]{url}[/dim]")
-        if snippet:
-            console.print(f"  {snippet[:120]}")
-        if score:
-            console.print(f"  [dim]score: {score:.3f}[/dim]")
-        console.print()
-
-
-def print_health_table(checks: dict[str, Any]) -> None:
-    table = Table(title="Research Environment Health", header_style="bold cyan")
-    table.add_column("Check", style="cyan")
-    table.add_column("Status", style="magenta")
-    table.add_column("Detail", style="dim")
-    for name, check in checks.items():
-        ok = check.get("ok", False)
-        status = "[green]✅[/green]" if ok else "[red]❌[/red]"
-        detail_parts = []
-        if name == "mcp_router":
-            if ok:
-                detail_parts.append(f"{check.get('tools', 0)} tools")
-            else:
-                detail_parts.append(check.get("error", "unreachable")[:60])
-        elif name == "mcp_token":
-            if ok:
-                detail_parts.append(f"token ({check.get('length', 0)} chars)")
-            else:
-                detail_parts.append("missing MCPR_TOKEN")
-        elif ok:
-            path = check.get("found") or ""
-            if path:
-                detail_parts.append(path.split("/")[-1])
-        else:
-            detail_parts.append("not found")
-        table.add_row(name, status, " | ".join(detail_parts))
-    console.print(table)
-
-
-def print_score_table(score_value: int, confidence: str, ready: bool, blockers: list[str]) -> None:
-    icon = "[green]✅[/green]" if ready else "[red]❌[/red]"
-    console.print(f"  Score   : [bold]{score_value}[/bold] / 100  ({confidence})")
-    console.print(f"  Decision: {icon} {'ready' if ready else 'blocked'}")
-    if blockers:
-        console.print("  [yellow]Blockers:[/yellow]")
-        for b in blockers:
-            console.print(f"    - {b}")

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/py.typed

@@ -1 +0,0 @@
-

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/report/build.py

@@ -1,156 +0,0 @@
-"""Report builder — SOURCED from: .agent/skills/research-skill/scripts/generate-research-report.py:build_decision_packet()"""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any
-
-
-def build_decision_packet(
-    *,
-    title: str,
-    question: str,
-    recommendation: str,
-    decision: str,
-    confidence: str,
-    local_evidence: list[dict[str, Any]],
-    internet_evidence: list[dict[str, Any]],
-    gaps: list[str],
-    next_checks: list[str],
-    scoring: dict[str, Any] | None,
-) -> dict[str, Any]:
-    """Build a decision packet from research results.
-
-    SOURCED from: .agent/skills/research-skill/scripts/generate-research-report.py:build_decision_packet()
-    VERSION: matches 2026-04-18 version
-    SYNC RULE (AC-3.4): update this copy when source script changes; run test_parity.py after update
-    """
-    generated_at = datetime.now(UTC).isoformat(timespec="seconds")
-    local_norm = _normalize_evidence(local_evidence, "local")
-    internet_norm = _normalize_evidence(internet_evidence, "internet")
-    readiness = _derive_readiness(confidence=confidence, gaps=gaps, scoring=scoring)
-    most_relevant = _pick_most_relevant_source(local_norm, internet_norm)
-    mcp_summary = _build_mcp_tool_summary(local_norm, internet_norm)
-    packet: dict[str, Any] = {
-        "schema_version": "1.2.0",
-        "generated_at": generated_at,
-        "title": title.strip(),
-        "question": question.strip(),
-        "recommendation": {
-            "decision": decision,
-            "summary": recommendation.strip() or "(not provided)",
-        },
-        "readiness": readiness,
-        "evidence": {
-            "local": local_norm,
-            "internet": internet_norm,
-        },
-        "most_relevant_source": most_relevant,
-        "mcp_tools_used": mcp_summary,
-        "gaps": gaps,
-        "next_checks": next_checks,
-        "scoring": scoring,
-    }
-    return packet
-
-
-def _normalize_evidence(evidence: list[dict[str, Any]], source_type: str) -> list[dict[str, Any]]:
-    """Normalize evidence items to standard format, including graph evidence."""
-    results: list[dict[str, Any]] = []
-    for item in evidence:
-        if not isinstance(item, dict):
-            continue
-        norm = _normalize_single_item(item, source_type)
-        results.append(norm)
-    return results
-
-
-def _normalize_single_item(item: dict[str, Any], source_type: str) -> dict[str, Any]:
-    """Normalize a single evidence item with graph awareness."""
-    # Graph evidence reliability mapping
-    reliability = item.get("reliability", "secondary")
-    edge_type = item.get("edge_type")
-    if edge_type == "EXTRACTED":
-        reliability = "primary"
-    elif edge_type == "INFERRED":
-        reliability = "secondary"
-    elif edge_type == "AMBIGUOUS":
-        reliability = "low"
-
-    return {
-        "summary": item.get("summary", ""),
-        "source": item.get("source", ""),
-        "link": item.get("link", ""),
-        "site": item.get("site", ""),
-        "mcp_tool": item.get("mcp_tool", ""),
-        "reliability": reliability,
-        "relevance_score": item.get("relevance_score", 0.5),
-        "source_type": source_type,
-        "graph_tool": item.get("graph_tool"),
-        "edge_type": edge_type,
-    }
-
-
-def _load_evidence_file(path: str | Path) -> list[dict[str, Any]]:
-    """Load evidence from a JSON or markdown file.
-
-    - JSON files: parsed as list of evidence dicts.
-    - Markdown files: wrapped as a single evidence item with source="graphify".
-    """
-    import json
-
-    p = Path(path)
-    text = p.read_text(encoding="utf-8")
-    if p.suffix.lower() == ".json":
-        data = json.loads(text)
-        if isinstance(data, list):
-            return data
-        if isinstance(data, dict):
-            return [data]
-        return []
-    # Markdown: wrap as single item
-    return [
-        {
-            "id": f"md-{p.stem}",
-            "summary": text[:2000],
-            "source": str(p),
-            "reliability": "secondary",
-            "relevance_score": 0.7,
-            "graph_tool": "graphify",
-        }
-    ]
-
-
-def _derive_readiness(confidence: str, gaps: list[str], scoring: dict[str, Any] | None) -> dict[str, Any]:
-    """Derive readiness assessment."""
-    readiness = {"confidence": confidence, "gaps_count": len(gaps)}
-    if scoring:
-        readiness["score"] = scoring.get("score")
-        readiness["ready_for_decision"] = scoring.get("decision_gate", {}).get("ready_for_decision", False)
-        readiness["blockers"] = scoring.get("decision_gate", {}).get("blockers", [])
-    else:
-        readiness["ready_for_decision"] = False
-        readiness["blockers"] = []
-    return readiness
-
-
-def _pick_most_relevant_source(local: list[dict[str, Any]], internet: list[dict[str, Any]]) -> dict[str, Any] | None:
-    """Pick the most relevant source from local and internet evidence."""
-    all_evidence = local + internet
-    if not all_evidence:
-        return None
-    scored = sorted(all_evidence, key=lambda x: x.get("relevance_score", 0), reverse=True)
-    return scored[0] if scored else None
-
-
-def _build_mcp_tool_summary(local: list[dict[str, Any]], internet: list[dict[str, Any]]) -> dict[str, int]:
-    """Build summary of MCP tools used."""
-    summary: dict[str, int] = {}
-    for item in local + internet:
-        tool = item.get("mcp_tool", "unknown")
-        summary[tool] = summary.get(tool, 0) + 1
-    return summary
-
-
-__all__ = ["_load_evidence_file", "build_decision_packet"]

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/report/format.py

@@ -1,147 +0,0 @@
-"""Markdown renderer for decision packets.
-
-SOURCED from: .agent/skills/research-skill/scripts/generate-research-report.py:render_markdown()
-VERSION: 2026-04-18
-SYNC RULE (AC-3.4): update this copy when source script changes.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-
-def _render_evidence_section(title: str, rows: list[dict[str, Any]]) -> str:
-    lines = [f"## {title}", ""]
-    if not rows:
-        lines.append("- (none provided)")
-        lines.append("")
-        return "\n".join(lines)
-
-    for row in rows:
-        summary = str(row.get("summary", "(missing summary)"))
-        source = str(row.get("source", "(missing source)"))
-        link = row.get("link")
-        freshness = row.get("freshness")
-        meta_bits = [f"source: {source}"]
-        tool = row.get("mcp_tool")
-        site = row.get("site")
-        if tool:
-            meta_bits.append(f"mcp_tool: {tool}")
-        if site:
-            meta_bits.append(f"site: {site}")
-        if "mcp_call_success" in row:
-            meta_bits.append(f"mcp_call_success: {row.get('mcp_call_success')}")
-        if "useful_info" in row:
-            meta_bits.append(f"useful_info: {row.get('useful_info')}")
-        if freshness:
-            meta_bits.append(f"freshness: {freshness}")
-        if link:
-            meta_bits.append(f"link: {link}")
-        lines.append(f"- {summary} ({'; '.join(meta_bits)})")
-
-    lines.append("")
-    return "\n".join(lines)
-
-
-def render_markdown(packet: dict[str, Any]) -> str:
-    """Render a decision packet as a markdown document.
-
-    Verbatim copy of render_markdown() from generate-research-report.py.
-    """
-    recommendation = packet.get("recommendation", {})
-    readiness = packet.get("readiness") or packet.get("decision_readiness", {})
-    if not isinstance(readiness, dict):
-        readiness = {}
-    evidence = packet.get("evidence", {})
-    if not isinstance(evidence, dict):
-        evidence = {}
-    confidence = packet.get("confidence") or readiness.get("confidence", "unknown")
-    ready_for_decision = readiness.get("ready_for_decision")
-    if ready_for_decision is None:
-        ready_for_decision = readiness.get("ready")
-
-    lines = [
-        f"# {packet['title']}",
-        "",
-        f"- Generated: {packet.get('generated_at', '(unknown)')}",
-        f"- Confidence: {confidence}",
-        f"- Decision: {recommendation.get('decision', '(unknown)')}",
-        f"- Ready for decision: {ready_for_decision}",
-        "",
-        "## Research Question",
-        "",
-        str(packet.get("question", "")),
-        "",
-        "## Recommendation",
-        "",
-        str(recommendation.get("summary", "(not provided)")),
-        "",
-    ]
-
-    most_relevant = packet.get("most_relevant_source")
-    if isinstance(most_relevant, dict):
-        lines.extend(
-            [
-                "## Most Relevant Source",
-                "",
-                f"- Summary: {most_relevant.get('summary')}",
-                f"- MCP Tool: {most_relevant.get('mcp_tool')}",
-                f"- Site: {most_relevant.get('site')}",
-                f"- MCP Call Success: {most_relevant.get('mcp_call_success')}",
-                f"- Useful Info: {most_relevant.get('useful_info')}",
-                f"- Source: {most_relevant.get('source')}",
-                f"- Link: {most_relevant.get('link')}",
-                "",
-            ]
-        )
-
-    mcp_summary = packet.get("mcp_tools_used") or packet.get("mcp_tool_summary")
-    if isinstance(mcp_summary, dict) and mcp_summary:
-        lines.extend(["## MCP Tool Summary", ""])
-        overall = mcp_summary.get("overall")
-        if isinstance(overall, dict):
-            lines.extend(
-                [
-                    f"- Calls Total: {overall.get('calls_total')}",
-                    f"- Calls Success: {overall.get('calls_success')}",
-                    f"- Useful Results: {overall.get('useful_results')}",
-                    f"- Success Rate: {overall.get('success_rate')}",
-                    f"- Usefulness Rate: {overall.get('usefulness_rate')}",
-                    "",
-                ]
-            )
-        else:
-            for tool_name, count in sorted(mcp_summary.items()):
-                lines.append(f"- {tool_name}: {count}")
-            lines.append("")
-
-    lines.append(_render_evidence_section("Local Evidence", evidence.get("local", [])))
-    lines.append(_render_evidence_section("Internet Evidence", evidence.get("internet", [])))
-
-    lines.extend(["## Open Gaps", ""])
-    gaps = packet.get("gaps") or packet.get("open_gaps", [])
-    if gaps:
-        lines.extend([f"- {gap}" for gap in gaps])
-    else:
-        lines.append("- (none)")
-    lines.append("")
-
-    lines.extend(["## Next Checks", ""])
-    for item in packet.get("next_checks", []):
-        lines.append(f"- {item}")
-    lines.append("")
-
-    if packet.get("scoring"):
-        scoring = packet["scoring"]
-        lines.extend(
-            [
-                "## Scoring",
-                "",
-                f"- Score: {scoring.get('score')}",
-                f"- Conflict Severity: {scoring.get('conflict_severity')}",
-                f"- Next Action: {scoring.get('next_action')}",
-                "",
-            ]
-        )
-
-    return "\n".join(lines)

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/tools/health.py

@@ -1,66 +0,0 @@
-"""Health check utilities for the research orchestrator environment."""
-
-from __future__ import annotations
-
-import os
-import shutil
-from typing import Any
-
-from vds_research_orchestrator.http_client import MCPClient
-from vds_research_orchestrator.tools.health_graph import (
-    check_code_review_graph,
-    check_gitnexus,
-    check_graphify,
-)
-
-
-def run_health_checks() -> dict[str, Any]:
-    """Run all health checks for the research orchestrator environment.
-
-    Returns:
-        Dict mapping check names to status dicts with "ok" and other metadata.
-    """
-    checks: dict[str, Any] = {}
-    checks["ripgrep"] = _check_ripgrep()
-    checks["ast_grep"] = {
-        "ok": shutil.which("sg") is not None,
-        "found": bool(shutil.which("sg")),
-    }
-    checks["grepai"] = {"ok": False, "found": False}
-    if gi := shutil.which("grepai"):
-        checks["grepai"] = {"ok": True, "found": True}
-    checks["vds_skills_sync"] = _check_vds_skills_sync()
-    checks["mcp_token"] = _check_mcp_token()
-    checks["mcp_router"] = _check_mcp_router()
-    checks["code_review_graph"] = check_code_review_graph()
-    checks["graphify"] = check_graphify()
-    checks["gitnexus"] = check_gitnexus()
-    return checks
-
-
-def _check_ripgrep() -> dict[str, Any]:
-    found = shutil.which("rg")
-    return {"ok": found is not None, "found": found is not None}
-
-
-def _check_vds_skills_sync() -> dict[str, Any]:
-    found = shutil.which("vds-skills-sync") is not None or shutil.which("python3") is not None
-    return {"ok": found, "found": found}
-
-
-def _check_mcp_token() -> dict[str, Any]:
-    token = os.environ.get("MCPR_TOKEN", "")
-    return {"ok": bool(token), "present": bool(token)}
-
-
-def _check_mcp_router() -> dict[str, Any]:
-    try:
-        client = MCPClient()
-        tools = client.list_tools()
-        client.close()
-        return {"ok": True, "reachable": True, "tools": len(tools)}
-    except Exception as exc:
-        return {"ok": False, "reachable": False, "error": str(exc)}
-
-
-__all__ = ["run_health_checks"]