Add Search/RAG integration for grounded verification (Issue #2)

- Add PerplexityAdapter for RAG-native models (sonar, sonar-pro, etc.)
  with built-in web search and citations support
- Add SearchBackend interface with implementations:
  - BraveSearchBackend (Brave Search API)
  - SerpAPIBackend (Google Search via SerpAPI)
  - TavilySearchBackend (AI-optimized search)
- Add SearchRegistry for managing multiple search backends
- Add verify_claim_with_search() for RAG-grounded verification
- Add verify_claim_grounded() to AICP protocol
- Add citations field to Response schema
- Add source_citations and retrieved_sources to VerificationResult
- Add Perplexity model capabilities to router (4 models)
- Add 40 new tests (Perplexity adapter + search backends)
- Update README with Perplexity and RAG verification documentation

Author: lancejames221b

README.md

@@ -268,6 +268,52 @@ LITELLM_API_KEY=sk-1234
 LITELLM_MODELS=gpt-4o,claude-3-opus,llama3.1
 ```
 
+### Perplexity (RAG-Native)
+
+i2i integrates with [Perplexity](https://perplexity.ai) for RAG-native models with built-in web search and citations:
+
+```env
+PERPLEXITY_API_KEY=pplx-...
+```
+
+Perplexity models automatically search the web and return citations:
+
+```python
+# Query with automatic web search
+result = await protocol.query(
+    "What is the current stock price of Apple?",
+    model="perplexity/sonar-pro"
+)
+print(result.content)
+print(result.citations)  # ['https://finance.yahoo.com/...', ...]
+```
+
+Available models: `sonar`, `sonar-pro`, `sonar-deep-research`, `sonar-reasoning-pro`
+
+### Search-Grounded Verification (RAG)
+
+i2i provides RAG-grounded verification that retrieves external sources before verifying claims:
+
+```python
+# Verify a claim with search grounding
+result = await protocol.verify_claim_grounded(
+    "The Eiffel Tower is 330 meters tall",
+    search_backend="brave"  # or "serpapi", "tavily"
+)
+print(f"Verified: {result.verified}")
+print(f"Confidence: {result.confidence}")
+print(f"Sources: {result.source_citations}")
+print(f"Retrieved: {result.retrieved_sources}")
+```
+
+Configure search backends:
+```env
+# Choose one or more (first configured is used as fallback)
+BRAVE_API_KEY=BSA...     # https://brave.com/search/api/
+SERPAPI_API_KEY=...      # https://serpapi.com/
+TAVILY_API_KEY=tvly-...  # https://tavily.com/
+```
+
 ### Configuring Default Models
 
 Models are **not hardcoded**. Configure via `config.json`, environment variables, or CLI:
@@ -759,6 +805,7 @@ protocol = AICP()
 | **Cohere** | Command A, Command A Reasoning | ✅ Supported |
 | **Ollama** | Llama 3.2, Mistral, CodeLlama, Phi-3, Gemma 2, etc. | ✅ Supported (Local) |
 | **LiteLLM** | 100+ models via unified proxy | ✅ Supported |
+| **Perplexity** | Sonar, Sonar Pro, Deep Research, Reasoning Pro | ✅ Supported (RAG) |
 
 ---
 
@@ -798,9 +845,9 @@ The RFC defines:
 │  ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌───────────┐   │
 │  │ OpenAI │ │Anthropic │ │ Google │ │Mistral │ │Groq/Llama │   │
 │  └────────┘ └──────────┘ └────────┘ └────────┘ └───────────┘   │
-│  ┌────────┐ ┌──────────┐                                        │
-│  │ Ollama │ │ LiteLLM  │  ← Local & Proxy providers             │
-│  └────────┘ └──────────┘                                        │
+│  ┌────────┐ ┌──────────┐ ┌────────────┐                         │
+│  │ Ollama │ │ LiteLLM  │ │ Perplexity │ ← Local/Proxy/RAG       │
+│  └────────┘ └──────────┘ └────────────┘                         │
 └─────────────────────────────────────────────────────────────────┘
 ```
 

i2i/__init__.py

@@ -37,6 +37,14 @@
     get_epistemic_models,
     DEFAULTS,
 )
+from .search import (
+    SearchBackend,
+    SearchResult,
+    SearchRegistry,
+    BraveSearchBackend,
+    SerpAPIBackend,
+    TavilySearchBackend,
+)
 
 __version__ = "0.1.0"
 __all__ = [
@@ -71,4 +79,11 @@
     "get_synthesis_models",
     "get_verification_models",
     "get_epistemic_models",
+    # Search/RAG
+    "SearchBackend",
+    "SearchResult",
+    "SearchRegistry",
+    "BraveSearchBackend",
+    "SerpAPIBackend",
+    "TavilySearchBackend",
 ]

i2i/protocol.py

@@ -215,6 +215,42 @@ async def verify_claim(
             context=context,
         )
 
+    async def verify_claim_grounded(
+        self,
+        claim: str,
+        verifiers: Optional[List[str]] = None,
+        search_backend: Optional[str] = None,
+        num_sources: int = 5,
+        original_source: Optional[str] = None,
+    ) -> VerificationResult:
+        """
+        Verify a claim with search-grounded evidence (RAG verification).
+
+        This method retrieves relevant sources from the web before
+        asking verification models to evaluate the claim. The result
+        includes source citations for transparency.
+
+        Args:
+            claim: The claim/statement to verify
+            verifiers: Models to use for verification
+            search_backend: Search backend to use (brave, serpapi, tavily)
+            num_sources: Number of sources to retrieve (default: 5)
+            original_source: Model that originally made the claim
+
+        Returns:
+            VerificationResult with source_citations and retrieved_sources
+        """
+        if verifiers is None:
+            verifiers = self._get_default_models()[:2]
+
+        return await self.verification_engine.verify_claim_with_search(
+            claim=claim,
+            verifier_models=verifiers,
+            search_backend=search_backend,
+            num_sources=num_sources,
+            original_source=original_source,
+        )
+
     async def challenge_response(
         self,
         response: Response,

i2i/providers.py

@@ -656,6 +656,93 @@ def _extract_confidence(self, content: str) -> ConfidenceLevel:
         return ConfidenceLevel.MEDIUM
 
 
+class PerplexityAdapter(ProviderAdapter):
+    """
+    Adapter for Perplexity AI.
+
+    Perplexity provides RAG-native models with built-in web search and citations.
+    Uses OpenAI-compatible API at https://api.perplexity.ai
+    """
+
+    MODELS = ["sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro"]
+
+    def __init__(self):
+        self.api_key = os.getenv("PERPLEXITY_API_KEY")
+        self._client = None
+
+    @property
+    def provider_name(self) -> str:
+        return "perplexity"
+
+    @property
+    def available_models(self) -> List[str]:
+        return self.MODELS
+
+    def is_configured(self) -> bool:
+        return bool(self.api_key)
+
+    @property
+    def client(self):
+        if self._client is None:
+            from openai import AsyncOpenAI
+            self._client = AsyncOpenAI(
+                api_key=self.api_key,
+                base_url="https://api.perplexity.ai"
+            )
+        return self._client
+
+    async def query(self, message: Message, model: str) -> Response:
+        start_time = time.time()
+
+        # Build messages
+        messages = []
+        if message.context:
+            for ctx_msg in message.context:
+                role = "assistant" if ctx_msg.sender else "user"
+                messages.append({"role": role, "content": ctx_msg.content})
+        messages.append({"role": "user", "content": message.content})
+
+        response = await self.client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=0.2,  # Lower for factual queries
+        )
+
+        latency = (time.time() - start_time) * 1000
+        content = response.choices[0].message.content
+
+        # Extract citations from response (Perplexity includes search_results)
+        citations = None
+        if hasattr(response, 'search_results') and response.search_results:
+            citations = [r.get('url') for r in response.search_results if r.get('url')]
+
+        return Response(
+            message_id=message.id,
+            model=f"perplexity/{model}",
+            content=content,
+            confidence=self._extract_confidence(content),
+            citations=citations,
+            input_tokens=response.usage.prompt_tokens if response.usage else None,
+            output_tokens=response.usage.completion_tokens if response.usage else None,
+            latency_ms=latency,
+        )
+
+    def _extract_confidence(self, content: str) -> ConfidenceLevel:
+        """Heuristically extract confidence from response content."""
+        content_lower = content.lower()
+        if any(phrase in content_lower for phrase in ["i'm certain", "definitely", "absolutely", "i'm confident"]):
+            return ConfidenceLevel.VERY_HIGH
+        elif any(phrase in content_lower for phrase in ["i believe", "likely", "probably"]):
+            return ConfidenceLevel.HIGH
+        elif any(phrase in content_lower for phrase in ["i think", "possibly", "might"]):
+            return ConfidenceLevel.MEDIUM
+        elif any(phrase in content_lower for phrase in ["i'm not sure", "uncertain", "hard to say"]):
+            return ConfidenceLevel.LOW
+        elif any(phrase in content_lower for phrase in ["i don't know", "impossible to determine"]):
+            return ConfidenceLevel.VERY_LOW
+        return ConfidenceLevel.MEDIUM
+
+
 class ProviderRegistry:
     """
     Registry of all available AI providers.
@@ -677,6 +764,7 @@ def __init__(self):
         self._register_adapter(CohereAdapter())
         self._register_adapter(OllamaAdapter())
         self._register_adapter(LiteLLMAdapter())
+        self._register_adapter(PerplexityAdapter())
 
     def _register_adapter(self, adapter: ProviderAdapter):
         """Register a provider adapter."""

i2i/router.py

@@ -953,6 +953,94 @@ class RoutingResult(BaseModel):
         instruction_following=79,
         factual_accuracy=73,
     ),
+
+    # ==================== Perplexity (RAG-native) ====================
+    # Sonar - Lightweight search model
+    "perplexity/sonar": ModelCapability(
+        model_id="perplexity/sonar",
+        provider="perplexity",
+        task_scores={
+            TaskType.FACTUAL_QA: 90,
+            TaskType.RESEARCH: 92,
+            TaskType.SUMMARIZATION: 85,
+            TaskType.CHAT: 80,
+        },
+        avg_latency_ms=800,
+        cost_per_1k_tokens=0.001,
+        context_window=127000,
+        max_output_tokens=4096,
+        supports_function_calling=False,
+        supports_json_mode=False,
+        reasoning_depth=75,
+        creativity_score=60,
+        instruction_following=80,
+        factual_accuracy=92,
+    ),
+    # Sonar Pro - Advanced search with citations
+    "perplexity/sonar-pro": ModelCapability(
+        model_id="perplexity/sonar-pro",
+        provider="perplexity",
+        task_scores={
+            TaskType.FACTUAL_QA: 95,
+            TaskType.RESEARCH: 97,
+            TaskType.SUMMARIZATION: 90,
+            TaskType.ANALYTICAL: 88,
+            TaskType.CHAT: 85,
+        },
+        avg_latency_ms=1500,
+        cost_per_1k_tokens=0.005,
+        context_window=200000,
+        max_output_tokens=8192,
+        supports_function_calling=False,
+        supports_json_mode=False,
+        reasoning_depth=85,
+        creativity_score=65,
+        instruction_following=85,
+        factual_accuracy=96,
+    ),
+    # Sonar Deep Research - Exhaustive multi-step research
+    "perplexity/sonar-deep-research": ModelCapability(
+        model_id="perplexity/sonar-deep-research",
+        provider="perplexity",
+        task_scores={
+            TaskType.RESEARCH: 99,
+            TaskType.FACTUAL_QA: 97,
+            TaskType.ANALYTICAL: 95,
+            TaskType.SUMMARIZATION: 92,
+        },
+        avg_latency_ms=5000,
+        cost_per_1k_tokens=0.02,
+        context_window=200000,
+        max_output_tokens=16384,
+        supports_function_calling=False,
+        supports_json_mode=False,
+        reasoning_depth=95,
+        creativity_score=60,
+        instruction_following=88,
+        factual_accuracy=98,
+    ),
+    # Sonar Reasoning Pro - Premier reasoning with search
+    "perplexity/sonar-reasoning-pro": ModelCapability(
+        model_id="perplexity/sonar-reasoning-pro",
+        provider="perplexity",
+        task_scores={
+            TaskType.LOGICAL_REASONING: 94,
+            TaskType.RESEARCH: 95,
+            TaskType.FACTUAL_QA: 93,
+            TaskType.ANALYTICAL: 94,
+            TaskType.SCIENTIFIC: 90,
+        },
+        avg_latency_ms=3000,
+        cost_per_1k_tokens=0.01,
+        context_window=200000,
+        max_output_tokens=16384,
+        supports_function_calling=False,
+        supports_json_mode=False,
+        reasoning_depth=94,
+        creativity_score=65,
+        instruction_following=88,
+        factual_accuracy=95,
+    ),
 }
 
 

i2i/schema.py

@@ -93,6 +93,9 @@ class Response(BaseModel):
     output_tokens: Optional[int] = None
     latency_ms: Optional[float] = None
 
+    # RAG/Search citations
+    citations: Optional[List[str]] = None  # Source URLs from RAG providers
+
 
 class ConsensusResult(BaseModel):
     """
@@ -132,6 +135,10 @@ class VerificationResult(BaseModel):
     issues_found: List[str] = Field(default_factory=list)
     corrections: Optional[str] = None  # Suggested corrections if not verified
 
+    # RAG/Search grounding
+    source_citations: List[str] = Field(default_factory=list)  # Source URLs used
+    retrieved_sources: List[Dict[str, Any]] = Field(default_factory=list)  # Full source info
+
     metadata: Dict[str, Any] = Field(default_factory=dict)