@ngocsangairvds/vsaf 3.2.14 → 3.2.15

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

@@ -1,335 +0,0 @@
-"""VDS Research Orchestrator CLI — search, health, score, report commands."""
-
-from __future__ import annotations
-
-import json
-import sys
-from pathlib import Path
-
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from .config import ResearchSettings
-from .evidence.scoring import EvidenceMetrics, score
-from .exceptions import ResearchError
-from .logging import configure
-from .report.build import build_decision_packet
-from .report.format import render_markdown
-from .tools.health import run_health_checks
-from .tools.search import search
-
-app = typer.Typer(help="VDS Research Orchestrator — evidence-first research CLI")
-
-console = Console()
-
-
-def _emit_error(exc: ResearchError) -> None:
-    console.print(f"[red]❌ {exc}[/red]")
-    if exc.hint:
-        console.print(f"[dim]Hint: {exc.hint}[/dim]")
-
-
-def _score_band_gate(score_value: int) -> str:
-    if score_value >= 80:
-        return "ready"
-    if score_value >= 60:
-        return "investigate"
-    return "blocked"
-
-
-def _score_adjustments(metrics: dict[str, int | bool]) -> dict[str, int]:
-    primary_sources = int(metrics.get("primary_sources", 0))
-    independent_sources = int(metrics.get("independent_sources", 0))
-    local_validation = bool(metrics.get("local_validation", False))
-    conflict_count = int(metrics.get("conflict_count", 0))
-    stale_source_count = int(metrics.get("stale_source_count", 0))
-
-    return {
-        "primary_sources_bonus": 20 if primary_sources >= 2 else 10 if primary_sources == 1 else 0,
-        "independent_sources_bonus": 15 if independent_sources >= 2 else 5 if independent_sources == 1 else 0,
-        "local_validation_bonus": 10 if local_validation else 0,
-        "conflict_penalty": -10 * conflict_count,
-        "stale_source_penalty": -7 * stale_source_count,
-    }
-
-
-def _normalize_scoring_payload(payload: dict[str, object] | None) -> dict[str, object] | None:
-    """Accept score payloads from CLI output and map to report builder schema."""
-    if payload is None:
-        return None
-
-    normalized = payload
-    data = normalized.get("data")
-    if isinstance(data, dict):
-        normalized = data
-
-    if "score" in normalized and isinstance(normalized.get("decision_gate"), dict):
-        return normalized
-
-    score_value = normalized.get("score_value")
-    ready_for_decision = normalized.get("ready_for_decision")
-    blockers = normalized.get("blockers")
-    if score_value is None or ready_for_decision is None:
-        return normalized
-
-    return {
-        "score": score_value,
-        "confidence": normalized.get("confidence"),
-        "decision_gate": {
-            "ready_for_decision": ready_for_decision,
-            "blockers": blockers if isinstance(blockers, list) else [],
-        },
-        "conflict_severity": normalized.get("conflict_severity"),
-        "next_action": normalized.get("next_action"),
-    }
-
-
-# ------------------------------------------------------------------
-# search
-# ------------------------------------------------------------------
-
-
-@app.command("search")
-def search_cmd(
-    query: str = typer.Argument(..., help="Search query string"),
-    tool: str = typer.Option("tavily", "--tool", "-t", help="MCP tool to use"),
-    max_results: int | None = typer.Option(None, "--max-results", help="Max results"),
-    library: str | None = typer.Option(None, "--library", help="Library name for docs tool"),
-    library_id: str | None = typer.Option(None, "--library-id", help="Context7 library ID"),
-    repo: str | None = typer.Option(None, "--repo", help="Repository (owner/repo) for deepwiki tool"),
-    url: list[str] | None = typer.Option(None, "--url", help="URL input for URL-based tools (repeatable)"),
-    language: list[str] | None = typer.Option(
-        None,
-        "--language",
-        help="Language filter for github search (repeatable)",
-    ),
-    engine: str | None = typer.Option(None, "--engine", help="Search engine for brightdata search"),
-    timeout: int = typer.Option(120, "--timeout", min=10, max=300),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON output"),
-    verbose: bool = typer.Option(False, "--verbose", "-v"),
-) -> None:
-    """Search for evidence using an MCP tool (default: tavily)."""
-    configure(verbose=verbose)
-    settings = ResearchSettings()
-    extra: dict[str, object] = {}
-    if max_results is not None:
-        if tool == "exa":
-            extra["numResults"] = max_results
-        elif tool == "brave":
-            extra["count"] = max_results
-        else:
-            extra["max_results"] = max_results
-    if library:
-        extra["library"] = library
-    if library_id:
-        extra["libraryId"] = library_id
-    if repo:
-        extra["repoName"] = repo
-    if language:
-        extra["language"] = language
-    if engine:
-        extra["engine"] = engine
-
-    if tool == "tavily-extract":
-        urls = list(url) if url else [query]
-        extra["urls"] = urls
-    elif tool == "brightdata-scrape":
-        if url and len(url) > 0:
-            extra["url"] = url[0]
-        else:
-            extra["url"] = query
-    elif tool == "deep" and not repo:
-        # Convenience: allow query to carry owner/repo when --repo is omitted.
-        if "/" in query and " " not in query:
-            extra["repoName"] = query
-
-    extra_args = extra if extra else None
-    try:
-        result = search(query, tool_name=tool, timeout=timeout, extra_args=extra_args, settings=settings)
-    except ResearchError as exc:
-        _emit_error(exc)
-        raise typer.Exit(getattr(exc, "exit_code", 2)) from exc
-    if json_output:
-        sys.stdout.write(json.dumps({"ok": True, "command": "search", "data": result}, indent=2))
-    else:
-        console.print(f"[cyan]🔍 {query}[/cyan] via [{tool}]")
-        for r in result.get("results", []):
-            console.print(f"  [bold]{r['title']}[/bold]")
-            console.print(f"  [dim]{r['url']}[/dim]")
-            if r["snippet"]:
-                console.print(f"  {r['snippet'][:120]}")
-
-
-# ------------------------------------------------------------------
-# health
-# ------------------------------------------------------------------
-
-
-@app.command("health")
-def health_cmd(
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON output"),
-    verbose: bool = typer.Option(False, "--verbose", "-v"),
-) -> None:
-    """Check research environment health (MCP router, tools, token)."""
-    configure(verbose=verbose)
-    report = run_health_checks()
-    ok = all(v.get("ok", False) for v in report.values())
-    if json_output:
-        sys.stdout.write(json.dumps({"ok": ok, "command": "health", "data": {"checks": report}}, indent=2))
-    else:
-        table = Table(title="Research Environment Health")
-        table.add_column("Check", style="cyan")
-        table.add_column("Status", style="magenta")
-        for name, check in report.items():
-            status = "✅" if check.get("ok") else "❌"
-            detail = f" (v{check.get('version', '')}" if check.get("version") else ""
-            table.add_row(name, f"{status}{detail}")
-        console.print(table)
-    raise typer.Exit(0 if ok else 1)
-
-
-# ------------------------------------------------------------------
-# score
-# ------------------------------------------------------------------
-
-
-@app.command("score")
-def score_cmd(
-    primary: int = typer.Option(0, "--primary-sources", help="Number of primary sources"),
-    independent: int = typer.Option(0, "--independent-sources", help="Number of independent sources"),
-    local_validation: bool = typer.Option(False, "--local-validation", help="Local code validated"),
-    conflicts: int = typer.Option(0, "--conflicts", help="Number of conflicting sources"),
-    stale: int = typer.Option(0, "--stale-sources", help="Number of stale sources"),
-    metrics_json: Path | None = typer.Option(None, "--metrics-json", help="JSON file with metrics"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON output"),
-    verbose: bool = typer.Option(False, "--verbose", "-v"),
-) -> None:
-    """Score evidence quality based on metrics.
-
-    Scoring: primary>=2 (+20), independent>=2 (+15), local_validation (+10),
-    each conflict (-10), each stale (-7). Gate is "ready" when score >= 60.
-    """
-    configure(verbose=verbose)
-    import json as _json
-
-    if metrics_json:
-        data = _json.loads(metrics_json.read_text())
-        m = EvidenceMetrics(**data)
-    else:
-        m = EvidenceMetrics(
-            primary_sources=primary,
-            independent_sources=independent,
-            local_validation=local_validation,
-            conflict_count=conflicts,
-            stale_source_count=stale,
-        )
-    result = score(m)
-    if json_output:
-        metrics_input = result["metrics"]
-        blockers = result["decision_gate"]["blockers"]
-        score_value = int(result["score"])
-        sys.stdout.write(
-            _json.dumps(
-                {
-                    "ok": True,
-                    "command": "score",
-                    "data": {
-                        "score_value": score_value,
-                        "confidence": result["confidence"],
-                        "ready_for_decision": result["decision_gate"]["ready_for_decision"],
-                        "decision_gate": _score_band_gate(score_value),
-                        "blockers": blockers,
-                        "blocker_codes": list(blockers),
-                        "conflict_severity": result["conflict_severity"],
-                        "next_action": result["next_action"],
-                        "adjustments": _score_adjustments(metrics_input),
-                        "metrics_input": metrics_input,
-                    },
-                },
-                indent=2,
-            )
-        )
-    else:
-        console.print(f"[cyan]Score:[/cyan] {result['score']} ({result['confidence']})")
-        gate = "✅ ready" if result["decision_gate"]["ready_for_decision"] else "❌ blocked"
-        console.print(f"[cyan]Decision:[/cyan] {gate}")
-        if result["decision_gate"]["blockers"]:
-            console.print("[yellow]Blockers:[/yellow]")
-            for b in result["decision_gate"]["blockers"]:
-                console.print(f"  - {b}")
-
-
-# ------------------------------------------------------------------
-# report
-# ------------------------------------------------------------------
-
-
-@app.command("report")
-def report_cmd(
-    title: str = typer.Option("", "--title", "-t", help="Report title"),
-    question: str = typer.Option("", "--question", "-q", help="Research question"),
-    recommendation: str = typer.Option("", "--recommendation", "-r", help="Recommendation summary"),
-    decision: str = typer.Option("investigate", "--decision", help="accept|reject|defer|investigate"),
-    confidence: str = typer.Option("medium", "--confidence", help="high|medium|low"),
-    local_evidence: Path | None = typer.Option(
-        None, "--local-evidence", help="JSON file with local evidence (supports .json and .md from graph tools)"
-    ),
-    internet_evidence: Path | None = typer.Option(None, "--internet-evidence", help="JSON file with internet evidence"),
-    relevance_override: float | None = typer.Option(
-        None, "--relevance-override", min=0.0, max=1.0, help="Override relevance_score for graph structural evidence"
-    ),
-    score_json: Path | None = typer.Option(None, "--score-json", help="JSON file with scoring result"),
-    gaps: str = typer.Option("", "--gaps", help="Semicolon-separated open gaps"),
-    next_checks: str = typer.Option("", "--next-checks", help="Semicolon-separated next checks"),
-    json_output: Path | None = typer.Option(None, "--json-output", help="JSON output path"),
-    output: Path | None = typer.Option(None, "--output", "-o", help="Markdown output path"),
-    json_out_flag: bool = typer.Option(False, "--json", help="Emit JSON to stdout"),
-    verbose: bool = typer.Option(False, "--verbose", "-v"),
-) -> None:
-    """Build a decision report from evidence and scoring results."""
-    configure(verbose=verbose)
-    import json as _json
-
-    if not title or not question:
-        raise typer.BadParameter("--title and --question are required for a decision report")
-    local_rows: list[dict[str, object]] = []
-    if local_evidence:
-        from .report.build import _load_evidence_file
-
-        local_rows = _load_evidence_file(local_evidence)
-    internet_rows = _json.loads(internet_evidence.read_text()) if internet_evidence else []
-
-    # Apply relevance override to graph structural evidence
-    if relevance_override is not None:
-        for row in local_rows:
-            if row.get("graph_tool") in ("code-review-graph", "graphify", "gitnexus"):
-                row["relevance_score"] = relevance_override
-    scoring = _json.loads(score_json.read_text()) if score_json else None
-    scoring = _normalize_scoring_payload(scoring if isinstance(scoring, dict) else None)
-    gap_list = [g.strip() for g in gaps.split(";") if g.strip()]
-    checks_list = [c.strip() for c in next_checks.split(";") if c.strip()]
-    packet = build_decision_packet(
-        title=title,
-        question=question,
-        recommendation=recommendation,
-        decision=decision,
-        confidence=confidence,
-        local_evidence=local_rows,
-        internet_evidence=internet_rows,
-        gaps=gap_list,
-        next_checks=checks_list,
-        scoring=scoring,
-    )
-    if json_output or json_out_flag:
-        out_path = json_output or Path("/tmp/decision-packet.json")
-        out_path.parent.mkdir(parents=True, exist_ok=True)
-        out_path.write_text(_json.dumps(packet, ensure_ascii=False, indent=2))
-        console.print(f"[green]✅[/green] Decision packet → {out_path}")
-    if output:
-        output.parent.mkdir(parents=True, exist_ok=True)
-        output.write_text(render_markdown(packet))
-        console.print(f"[green]✅[/green] Markdown → {output}")
-
-
-__all__ = ["app"]

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

@@ -1,43 +0,0 @@
-"""Pydantic settings for research orchestrator.
-
-MCPR_TOKEN is loaded from ~/.vds/.env before pydantic-settings reads os.environ.
-The import-time call to load_shared_env() ensures the token is in os.environ
-before the first ResearchSettings() instantiation.
-"""
-
-from __future__ import annotations
-
-from pydantic import Field
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-# CRITICAL: load ~/.vds/.env into os.environ BEFORE pydantic-settings reads it.
-# This must happen at import time (module-level), not lazily.
-from vds_cli_common.env import load_shared_env
-
-load_shared_env()
-
-
-class ResearchSettings(BaseSettings):
-    """Runtime settings sourced from environment variables.
-
-    Token resolution order:
-    1. VDS_RESEARCH_MCPR_TOKEN  (env var, highest priority)
-    2. MCPR_TOKEN               (from ~/.vds/.env via load_shared_env())
-    """
-
-    mcpr_url: str = Field(
-        default="http://localhost:3282",
-        description="MCP Router base URL (e.g. http://localhost:3282). The /mcp path is appended by the client.",
-    )
-    mcpr_token: str = Field(
-        default="",
-        description="Bearer token for the MCP Router. Read from MCPR_TOKEN in ~/.vds/.env",
-    )
-    default_tool_timeout: int = Field(
-        default=120,
-        ge=10,
-        le=300,
-        description="Default timeout in seconds for MCP tool calls",
-    )
-
-    model_config = SettingsConfigDict(extra="ignore")

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/evidence/models.py

@@ -1,89 +0,0 @@
-"""Pydantic v2 evidence models for the research orchestrator."""
-
-from __future__ import annotations
-
-from typing import Literal
-
-from pydantic import BaseModel, Field
-
-
-class EvidenceItem(BaseModel):
-    """A single piece of evidence gathered from an MCP tool or graph skill."""
-
-    id: str = Field(min_length=1, description="Unique evidence identifier")
-    evidence_type: Literal["local", "internet"] | None = Field(
-        default=None,
-        description="Source category",
-    )
-    source_type: Literal["primary", "secondary", "low"] = Field(
-        default="secondary",
-        description="Reliability classification",
-    )
-    summary: str = Field(min_length=1, description="Plain-text summary of the evidence")
-    source: str | None = Field(default=None, description="URL or file path")
-    mcp_tool: str | None = Field(default=None, description="MCP tool that produced this")
-    site: str | None = Field(default=None, description="Domain name")
-    mcp_call_success: bool = Field(default=True, description="Whether the MCP call succeeded")
-    useful_info: bool = Field(default=True, description="Whether the content was useful")
-    link: str | None = Field(default=None, description="Direct link to the source")
-    freshness: str | None = Field(default=None, description="Date string or 'fresh'/'stale'")
-    reliability: Literal["primary", "secondary", "low"] = Field(
-        default="secondary",
-        description="Reliability classification",
-    )
-    relevance_score: float = Field(
-        default=0.5,
-        ge=0.0,
-        le=1.0,
-        description="0.0–1.0 relevance to the research question",
-    )
-    tags: list[str] = Field(default_factory=list, description="Arbitrary tags")
-    graph_tool: Literal["code-review-graph", "graphify", "gitnexus", None] = Field(
-        default=None,
-        description="Graph skill that produced this evidence, if any",
-    )
-    edge_type: Literal["EXTRACTED", "INFERRED", "AMBIGUOUS", None] = Field(
-        default=None,
-        description="Graph edge provenance: EXTRACTED=AST (primary), INFERRED=heuristic (secondary), AMBIGUOUS=needs review",
-    )
-    graph_confidence: Literal["high", "medium", "low"] | None = Field(
-        default=None,
-        description="Confidence level for graph structural evidence",
-    )
-
-
-class EvidenceMetrics(BaseModel):
-    """Input metrics for the scoring function.
-
-    These values are derived from EvidenceItems by the CLI layer.
-    """
-
-    primary_sources: int = Field(ge=0, description="Number of primary (official) sources")
-    independent_sources: int = Field(ge=0, description="Number of independent (non-copied) sources")
-    local_validation: bool = Field(
-        default=False,
-        description="Whether local code was checked to confirm claims",
-    )
-    conflict_count: int = Field(ge=0, default=0, description="Number of sources with conflicting information")
-    stale_source_count: int = Field(ge=0, default=0, description="Number of sources with outdated information")
-
-
-class ScoreResult(BaseModel):
-    """Structured output of the score command."""
-
-    ok: bool = Field(default=True)
-    command: Literal["score"] = Field(default="score")
-    data: ScoreData
-
-
-class ScoreData(BaseModel):
-    score_value: int = Field(ge=0, le=100, description="0–100 reliability score")
-    confidence: Literal["high", "medium", "low"]
-    ready_for_decision: bool
-    decision_gate: Literal["ready", "investigate", "blocked"]
-    blockers: list[str] = Field(default_factory=list)
-    blocker_codes: list[str] = Field(default_factory=list)
-    conflict_severity: Literal["none", "low", "medium", "high"] = "none"
-    next_action: str
-    adjustments: dict[str, int] = Field(default_factory=dict)
-    metrics_input: dict[str, int]

package/tools/vds-scripts/research_orchestrator/src/vds_research_orchestrator/evidence/scoring.py

@@ -1,102 +0,0 @@
-"""Evidence scoring — verbatim copy from research-skill scripts.
-
-SOURCED from: .agent/skills/research-skill/scripts/score-research-evidence.py:score()
-VERSION: 2026-04-18
-SYNC RULE (AC-2.5): update this copy when source script changes; run test_parity.py
-after every update to verify output parity.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-# Re-export EvidenceMetrics for consumers
-from vds_research_orchestrator.evidence.models import EvidenceMetrics
-
-
-def _clamp(value: int, low: int = 0, high: int = 100) -> int:
-    return max(low, min(high, value))
-
-
-def _derive_blockers(metrics: EvidenceMetrics) -> list[str]:
-    blockers: list[str] = []
-    if metrics.primary_sources < 2:
-        blockers.append("insufficient_primary_sources")
-    if metrics.independent_sources < 2:
-        blockers.append("insufficient_independent_sources")
-    if not metrics.local_validation:
-        blockers.append("missing_local_validation")
-    if metrics.conflict_count > 0:
-        blockers.append("unresolved_conflicts")
-    if metrics.stale_source_count > 0:
-        blockers.append("contains_stale_sources")
-    return blockers
-
-
-def score(metrics: EvidenceMetrics) -> dict[str, Any]:
-    """Compute evidence reliability score from metrics.
-
-    Verbatim copy of score() from research-skill score-research-evidence.py.
-    Do not reimplement — maintain parity via the parity test.
-    """
-    score_value = 50
-    if metrics.primary_sources >= 2:
-        score_value += 20
-    elif metrics.primary_sources == 1:
-        score_value += 10
-    if metrics.independent_sources >= 2:
-        score_value += 15
-    elif metrics.independent_sources == 1:
-        score_value += 5
-    if metrics.local_validation:
-        score_value += 10
-    score_value -= metrics.conflict_count * 10
-    score_value -= metrics.stale_source_count * 7
-    score_value = _clamp(score_value)
-
-    if score_value >= 80:
-        confidence = "high"
-    elif score_value >= 60:
-        confidence = "medium"
-    else:
-        confidence = "low"
-
-    if metrics.conflict_count == 0:
-        conflict_severity = "none"
-    elif metrics.conflict_count == 1:
-        conflict_severity = "low"
-    elif metrics.conflict_count == 2:
-        conflict_severity = "medium"
-    else:
-        conflict_severity = "high"
-
-    blockers = _derive_blockers(metrics)
-    ready_for_decision = score_value >= 80 and conflict_severity in {"none", "low"} and len(blockers) == 0
-
-    if confidence == "medium":
-        next_action = "collect-one-more-primary-source"
-    elif confidence == "low":
-        next_action = "insufficient-evidence-research-more"
-    elif metrics.conflict_count > 0:
-        next_action = "resolve-source-conflicts"
-    else:
-        next_action = "ready-for-decision"
-
-    return {
-        "schema_version": "1.0.0",
-        "score": score_value,
-        "confidence": confidence,
-        "conflict_severity": conflict_severity,
-        "next_action": next_action,
-        "decision_gate": {
-            "ready_for_decision": ready_for_decision,
-            "blockers": blockers,
-        },
-        "metrics": {
-            "primary_sources": metrics.primary_sources,
-            "independent_sources": metrics.independent_sources,
-            "local_validation": metrics.local_validation,
-            "conflict_count": metrics.conflict_count,
-            "stale_source_count": metrics.stale_source_count,
-        },
-    }

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

@@ -1,78 +0,0 @@
-"""Research orchestrator exception hierarchy."""
-
-from __future__ import annotations
-
-
-class ResearchError(Exception):
-    """Base exception for all research orchestrator errors.
-
-    Every subclass carries a numeric exit_code used by the CLI to produce
-    the correct process exit status.
-    """
-
-    exit_code: int = 2
-
-    def __init__(self, message: str, *, hint: str | None = None) -> None:
-        super().__init__(message)
-        self.hint = hint
-
-
-# ── MCP Router errors ──────────────────────────────────────────────────────────
-
-
-class McpRouterError(ResearchError):
-    """Base for MCP Router communication failures."""
-
-
-class McpRouterAuthError(McpRouterError):
-    """Authentication with the MCP Router failed (HTTP 401/403)."""
-
-    exit_code = 2
-
-    def __init__(self, message: str, *, hint: str | None = None) -> None:
-        super().__init__(message, hint=hint)
-
-
-class McpRouterServerError(McpRouterError):
-    """MCP Router returned a 5xx HTTP status."""
-
-    exit_code = 2
-
-
-class McpRouterTimeout(McpRouterError):
-    """Request to the MCP Router exceeded the configured timeout."""
-
-    exit_code = 2
-
-
-class McpRouterNoEventsError(McpRouterError):
-    """SSE response from the MCP Router contained zero events."""
-
-    exit_code = 2
-
-
-class McpRouterProtocolError(McpRouterError):
-    """MCP Router returned a response that failed to parse as JSON-RPC."""
-
-    exit_code = 2
-
-
-# ── Tool & file errors ────────────────────────────────────────────────────────
-
-
-class ToolValidationError(ResearchError):
-    """Unknown tool name or invalid argument for the selected tool."""
-
-    exit_code = 1
-
-
-class EvidenceFileNotFoundError(ResearchError):
-    """A --*-evidence path was provided but the file does not exist."""
-
-    exit_code = 1
-
-
-class ScriptExecutionError(ResearchError):
-    """A shell or Python script invocation failed (non-zero exit)."""
-
-    exit_code = 3