# 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:

```bash
python run_pipeline.py --strategy hybrid
```

Legacy single-hop:

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

## Standalone Usage

```bash
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`