[NVIDIA #4] Integrate NVIDIA AI-Q Blueprint as AHE deep-research analysis backend

[AugustChaoTW]

Summary

NVIDIA's AI-Q Blueprint is a multi-agent deep-research framework with retrieval, planning, and synthesis agents. Integrating it as an optional backend for ahe/analyze_failures.py enables richer failure analysis: instead of just classifying failure types, AI-Q can synthesize cross-run patterns, query external documentation, and generate hypothesis proposals informed by web research.

What is AI-Q Blueprint

• Multi-agent system: planner → retriever → synthesizer → critic agents
• Supports local model backends (compatible with vLLM local endpoint)
• REST API: /health, /chat, async job endpoints with polling
• The aiq-research NVIDIA skill (installed in issue [NVIDIA #1] Install NVIDIA Skills into opencode-owl skill registry (P0) #49) already documents how to call it

Integration Architecture

ahe/analyze_failures.py
  ├── (existing) local failure classification (log_classifier.py)
  ├── (existing) diff quality scoring
  └── (NEW) AI-Q deep analysis [optional, --aiq flag]
       └── POST http://localhost:8000/chat
           payload: failure summary + context
           response: root cause hypothesis + remediation suggestions

Changes

1. ahe/analyze_failures.py — add --aiq flag

parser.add_argument("--aiq", action="store_true",
                    help="Use NVIDIA AI-Q Blueprint for deep failure analysis")
parser.add_argument("--aiq-url", default=os.environ.get("AIQ_SERVER_URL", "http://localhost:8000"),
                    help="AI-Q Blueprint server URL")

2. ahe/aiq_client.py — new module (mirrors aiq-research SKILL.md)

"""Thin client for NVIDIA AI-Q Blueprint /chat endpoint."""

import requests, time, json
from pathlib import Path

def aiq_research(query: str, server_url: str = "http://localhost:8000",
                 timeout: int = 120) -> dict:
    """Submit a research query to AI-Q and poll until done."""
    health = requests.get(f"{server_url}/health", timeout=5)
    if not health.ok:
        raise RuntimeError(f"AI-Q server not reachable at {server_url}")

    resp = requests.post(f"{server_url}/chat",
                         json={"query": query}, timeout=10)
    resp.raise_for_status()
    body = resp.json()

    # Async job: poll until complete
    if job_id := body.get("job_id"):
        for _ in range(timeout // 2):
            poll = requests.get(f"{server_url}/jobs/{job_id}", timeout=5).json()
            if poll.get("status") == "completed":
                return poll.get("result", {})
            if poll.get("status") == "failed":
                raise RuntimeError(f"AI-Q job failed: {poll.get('error')}")
            time.sleep(2)
        raise TimeoutError(f"AI-Q job {job_id} timed out after {timeout}s")

    return body

3. Failure analysis enrichment

# In analyze_failures.py, after local classification:
if args.aiq:
    failure_summary = build_failure_summary(traces)  # existing
    query = f"""
    Analyze these AHE eval failures and suggest harness patches:
    {failure_summary}

    Focus on: root cause patterns, which harness component to patch,
    and predicted improvement in pass@1.
    """
    aiq_result = aiq_research(query, server_url=args.aiq_url)
    report["aiq_analysis"] = aiq_result

4. propose_patch.py — use AI-Q analysis in proposal generation

If AI-Q analysis is available in the failure report, embed it under aiq_insights: in the proposal YAML:

change_id: h-0005
component: harness/prompts/system.md
hypothesis: AI-Q suggests the system prompt lacks explicit tool-use ordering rules.
aiq_insights:
  root_cause: "Agent repeatedly selects Edit before reading target file"
  suggested_fix: "Add rule: always Read before Edit"
  confidence: 0.87

Prerequisites

• NVIDIA AI-Q Blueprint server running (see NVIDIA skill aiq-deploy)
• OR use local vLLM backend via AI-Q's self-hosted mode
• AIQ_SERVER_URL env var set, or default http://localhost:8000

Acceptance Criteria

• python ahe/analyze_failures.py --run traces/runs/latest --aiq runs without error
• --aiq-url flag overrides default endpoint
• Graceful degradation if AI-Q server not reachable (warning, not failure)
• AI-Q analysis embedded in report.json under aiq_analysis key
• propose_patch.py picks up aiq_insights from report if present
• New ahe/aiq_client.py has unit tests with mocked HTTP

Effort: 3 days | Priority: P2