Multi-Hop Agent

This module adds a multi-hop retrieval agent to CognitiveRAG. The agent:

• Decomposes complex queries into focused sub-questions
• Retrieves evidence iteratively across multiple hops
• Accumulates provenance-rich evidence with deduplication
• Validates evidence sufficiency and terminates explicitly
• Produces a grounded answer with citations
• Logs full traces for LangSmith and RAGAS analysis

Where It Lives

• Agent code: 03_embedding/multihop_agent.py
• Standalone CLI: 03_embedding/run_multihop_agent.py
• Pipeline integration: run_pipeline.py
• Traces: 03_embedding/output/multihop_traces/
• Test artifacts: 03_embedding/output/multihop_artifacts/

How It Runs In The Pipeline

run_pipeline.py now runs the multi-hop agent by default. To run the legacy single-hop flow, use --single-hop.

Example:

python run_pipeline.py --strategy hybrid

Legacy single-hop:

python run_pipeline.py --strategy dense --single-hop

Standalone Usage

python 03_embedding/run_multihop_agent.py \
  --query "What written claims made by Theranos executives were later contradicted by courtroom testimony?" \
  --strategy hybrid \
  --max-hops 3 \
  --per-hop-top-k 8 \
  --total-doc-budget 24 \
  --sufficiency-threshold 0.75 \
  --time-limit-sec 60

Required Environment

The agent uses the same backends as the rest of the pipeline:

• NVIDIA NIM embeddings: NVIDIA_API_KEY
• Pinecone (for retrieval)
• AWS Bedrock (Claude) for decomposition, validation, synthesis
• LangSmith (optional) for tracing

If you already run run_pipeline.py, your env is already set up.

Outputs

Each run produces a trace JSON:

• 03_embedding/output/multihop_traces/multihop_trace_YYYYMMDD_HHMMSS_<id>.json

The trace includes:

• Hop-by-hop sub-questions
• Retrieval metadata
• Evidence pool with provenance
• Validation scores
• Termination reason
• Final answer and citations

Configuration

The agent is configured via MultiHopConfig:

• max_hops: Maximum hops
• per_hop_top_k: Documents per hop
• total_doc_budget: Overall retrieval budget
• sufficiency_threshold: Combined sufficiency threshold
• time_limit_sec: Hard time limit per query
• strategy: dense, sparse, or hybrid

Test Artifacts

Example inputs and trace samples are stored here:

• 03_embedding/output/multihop_artifacts/sample_queries.json
• 03_embedding/output/multihop_artifacts/trace_example.json
• 03_embedding/output/multihop_artifacts/early_termination_example.json
• 03_embedding/output/multihop_artifacts/failure_example.json