compresr 2.7.2__tar.gz → 2.7.5__tar.gz

{compresr-2.7.2 → compresr-2.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compresr
-Version: 2.7.2
+Version: 2.7.5
 Summary: Python SDK for Compresr - Intelligent prompt compression service
 Author-email: Compresr Team <founders@compresr.ai>
 License-Expression: Apache-2.0

{compresr-2.7.2 → compresr-2.7.5}/compresr/agents/engine.py

@@ -23,11 +23,6 @@ from .normalized import Citation, CompresrStats, NormalizedResult
 logger = logging.getLogger(__name__)
 
 
-# ---------------------------------------------------------------------------
-# Lazy imports — keep `import compresr.agents` cheap.
-# ---------------------------------------------------------------------------
-
-
 def _import_lc() -> tuple[Any, Any, Any]:
     """Resolve ``init_chat_model``, ``create_agent``, and middleware lazily."""
     try:
@@ -56,28 +51,9 @@ def _CompresrToolMiddleware(*args: Any, **kwargs: Any) -> Any:
     return _mw(*args, **kwargs)
 
 
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
 _KNOWN_PROVIDERS = {"anthropic", "openai", "google_genai"}
 
 
-# ---------------------------------------------------------------------------
-# Solo-WebSearchTool auto-route
-# ---------------------------------------------------------------------------
-#
-# When a generic-agent facade (``client.messages.create`` / ``client.chat
-# .completions.create`` / ``client.run``) is invoked with exactly the
-# Compresr ``WebSearchTool`` and nothing else, the engine silently routes the
-# call through the deep-research loop instead of the standard ``create_agent``
-# middleware path. The caller still gets back their facade's expected shape
-# (Anthropic ``Message`` / OpenAI ``ChatCompletion`` / ``NormalizedResult``),
-# but the loop semantics are research-agent: ``tool_choice="none"`` on the
-# final step, per-snippet compression against the live query, 10-step cap,
-# manual Anthropic ``cache_control`` stamping.
-#
 # Detection is by tool name because ``WebSearchTool.__new__`` returns a
 # ``StructuredTool`` (not a ``WebSearchTool`` instance), so ``isinstance``
 # would always be False.
@@ -163,6 +139,13 @@ _LLM_BIND_KWARGS = frozenset(
     }
 )
 
+# Constructor-only kwargs — transport, not per-call LLM knobs. Baked into the
+# chat model at build time so a custom httpx client (corporate proxy / custom
+# CA bundle / verify=False) reaches the provider SDK. Requires langchain-anthropic
+# >= the release that adds ``http_client``/``http_async_client`` to ChatAnthropic;
+# langchain-openai already supports both.
+_LLM_CONSTRUCTOR_KWARGS = frozenset({"http_client", "http_async_client"})
+
 
 def _parse_llm(llm: str) -> tuple[str, Optional[str]]:
     """Split ``"provider[:model]"`` (or ``"provider[/model]"``) into
@@ -259,7 +242,6 @@ def _extract_citations(msg: Any) -> list:
     for block in blocks:
         if not isinstance(block, dict):
             continue
-        # Anthropic: text block with `citations` list
         for cit in block.get("citations", []) or []:
             if not isinstance(cit, dict):
                 continue
@@ -275,7 +257,6 @@ def _extract_citations(msg: Any) -> list:
                         provider_metadata=dict(cit),
                     )
                 )
-        # OpenAI Responses: annotations[] with type="url_citation"
         for ann in block.get("annotations", []) or []:
             if not isinstance(ann, dict):
                 continue
@@ -291,7 +272,6 @@ def _extract_citations(msg: Any) -> list:
                         provider_metadata=dict(ann),
                     )
                 )
-    # Gemini: grounding_metadata on response_metadata
     response_metadata = getattr(msg, "response_metadata", None) or {}
     grounding = response_metadata.get("grounding_metadata") or {}
     for chunk in grounding.get("grounding_chunks", []) or []:
@@ -446,11 +426,6 @@ def _last_ai_message(messages: list) -> Any:
     return messages[-1] if messages else None
 
 
-# ---------------------------------------------------------------------------
-# _Engine
-# ---------------------------------------------------------------------------
-
-
 class _Engine:
     """Private engine shared by the provider-shape facades.
 
@@ -478,6 +453,8 @@ class _Engine:
         prompt_cache_ttl: str = "5m",
         prompt_cache_min_messages: int = 2,
         openai_prompt_cache_key: Optional[str] = None,
+        llm_http_client: Any = None,
+        llm_http_async_client: Any = None,
     ) -> None:
         self._compresr_client = compresr_client
         self._provider, self._default_model_name = _parse_llm(llm)
@@ -487,6 +464,11 @@ class _Engine:
         self._prompt_cache_ttl = prompt_cache_ttl
         self._prompt_cache_min_messages = int(prompt_cache_min_messages)
         self._openai_prompt_cache_key = openai_prompt_cache_key
+        # Custom httpx clients for the LLM provider transport (corporate proxy /
+        # custom CA / verify settings). Baked into every chat-model build; a
+        # per-call http_client passed to run() overrides these.
+        self._llm_http_client = llm_http_client
+        self._llm_http_async_client = llm_http_async_client
         # Chat-model cache keyed by effective model name. Construction is
         # deferred to the first ``run()`` so a provider-only client
         # (``llm="anthropic"``) doesn't try to resolve a model at init time.
@@ -494,10 +476,6 @@ class _Engine:
         # combinations get their own cached chat model.
         self._chat_models: dict[tuple[str, tuple], Any] = {}
 
-    # ------------------------------------------------------------------
-    # Public, read-only accessors
-    # ------------------------------------------------------------------
-
     @property
     def provider(self) -> str:
         return self._provider
@@ -516,10 +494,6 @@ class _Engine:
         """
         return self._default_model_name
 
-    # ------------------------------------------------------------------
-    # Build helpers
-    # ------------------------------------------------------------------
-
     def _get_or_build_chat(self, model_name: str, extra_kwargs: Optional[dict] = None) -> Any:
         """Return a cached chat model for ``model_name`` + ``extra_kwargs``,
         building on miss.
@@ -544,6 +518,14 @@ class _Engine:
         kwargs: dict = dict(extra_kwargs)
         if self._llm_api_key is not None:
             kwargs.setdefault("api_key", self._llm_api_key)
+        # Client-level custom httpx clients. setdefault so a per-call override
+        # from run(http_client=...) wins. Only Anthropic and OpenAI chat models
+        # accept these kwargs; google_genai uses a different transport.
+        if self._provider in ("anthropic", "openai"):
+            if self._llm_http_client is not None:
+                kwargs.setdefault("http_client", self._llm_http_client)
+            if self._llm_http_async_client is not None:
+                kwargs.setdefault("http_async_client", self._llm_http_async_client)
         # OpenAI caching is server-side; we only pass ``prompt_cache_key``
         # and ``prompt_cache_retention`` via ``model_kwargs`` so they survive
         # ``bind_tools``.
@@ -564,8 +546,50 @@ class _Engine:
                 )
             except TypeError:  # pragma: no cover - older langchain-openai
                 logger.debug("init_chat_model rejected output_version; falling back without it")
+        if self._provider == "anthropic":
+            return self._build_anthropic_chat(model_name, kwargs)
         return init_chat_model(f"{self._provider}:{model_name}", **kwargs)
 
+    def _build_anthropic_chat(self, model_name: str, kwargs: dict) -> Any:
+        """Build an Anthropic chat model, shimming ``http_client`` support on
+        versions of langchain-anthropic that predate the native field.
+
+        Native field present (PR merged / future release) → pass through. Absent
+        (current PyPI) → strip the unknown kwargs so the constructor doesn't drop
+        them silently, then swap the cached anthropic SDK client for one built
+        with the caller's httpx client. The shim is a no-op once native support
+        ships, so it can be removed then. See langchain issue #36056."""
+        from langchain_anthropic import ChatAnthropic
+
+        native = "http_client" in ChatAnthropic.model_fields
+        sync_client = kwargs.get("http_client")
+        async_client = kwargs.get("http_async_client")
+        if not native:
+            kwargs.pop("http_client", None)
+            kwargs.pop("http_async_client", None)
+
+        chat = init_chat_model(f"anthropic:{model_name}", **kwargs)
+
+        if not native and (sync_client is not None or async_client is not None):
+            self._inject_anthropic_http_client(chat, sync_client, async_client)
+        return chat
+
+    @staticmethod
+    def _inject_anthropic_http_client(chat: Any, sync_client: Any, async_client: Any) -> None:
+        """Replace ChatAnthropic's cached SDK clients with ones built around the
+        caller's httpx client, reusing langchain's own ``_client_params`` so
+        api_key / base_url / retries / headers stay correct. Writes through
+        ``__dict__`` to seed the ``cached_property`` before first access."""
+        import anthropic
+
+        params = dict(chat._client_params)
+        if sync_client is not None:
+            chat.__dict__["_client"] = anthropic.Anthropic(**{**params, "http_client": sync_client})
+        if async_client is not None:
+            chat.__dict__["_async_client"] = anthropic.AsyncClient(
+                **{**params, "http_client": async_client}
+            )
+
     def _openai_cache_model_kwargs(self) -> dict:
         """Build the OpenAI-specific cache controls. ``prompt_cache_retention``
         is only set for ``ttl="1h"`` so older langchain-openai doesn't reject
@@ -669,7 +693,7 @@ class _Engine:
         """
         bind_kwargs: dict = {}
         for key in list(kw):
-            if key in _LLM_BIND_KWARGS:
+            if key in _LLM_BIND_KWARGS or key in _LLM_CONSTRUCTOR_KWARGS:
                 bind_kwargs[key] = kw.pop(key)
         if max_tokens is not None:
             # Explicit signature param always reflects customer intent.
@@ -720,10 +744,6 @@ class _Engine:
         # facades layer; for now just keep the original messages.
         return list(messages)
 
-    # ------------------------------------------------------------------
-    # run / arun
-    # ------------------------------------------------------------------
-
     def run(
         self,
         *,
@@ -840,10 +860,6 @@ class _Engine:
         )
         return self._normalize({"messages": state.messages})
 
-    # ------------------------------------------------------------------
-    # Normalization
-    # ------------------------------------------------------------------
-
     def _normalize(self, agent_result: Any) -> NormalizedResult:
         """Reshape ``{"messages": [...]}`` into a :class:`NormalizedResult`.
 

compresr-2.7.5/compresr/agents/research/__init__.py

@@ -0,0 +1,24 @@
+"""Compresr research agent — multi-step web search with per-snippet compression.
+
+Public entry: ``client.research.run(question)`` / ``client.research.search(question)``.
+Loop structure adapted from Perplexity ``search_evals`` (MIT,
+https://github.com/perplexityai/search_evals).
+"""
+
+from .agent import ResearchAgent
+from .facade import ResearchFacade
+from .parser import parse_research_output
+from .prompts import DEFAULT_RESEARCH_SYSTEM_PROMPT
+from .types import Citation, ResearchResult, ResearchUsage, Step, StepKind
+
+__all__ = [
+    "Citation",
+    "DEFAULT_RESEARCH_SYSTEM_PROMPT",
+    "ResearchAgent",
+    "ResearchFacade",
+    "ResearchResult",
+    "ResearchUsage",
+    "Step",
+    "StepKind",
+    "parse_research_output",
+]

compresr-2.7.5/compresr/agents/research/agent.py

@@ -0,0 +1,334 @@
+"""``ResearchAgent`` — strict-output ReAct loop with per-snippet compression.
+
+Bypasses ``_Engine.run`` so we can control ``tool_choice`` per step (forces
+the model to commit on the final step) and compress each tool result against
+the live query before it enters the conversation. Cache control is stamped
+manually for Anthropic since ``create_agent`` is not in the call path.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional, Sequence
+
+from .parser import parse_research_output
+from .prompts import DEFAULT_RESEARCH_SYSTEM_PROMPT
+from .types import Citation, ResearchResult, ResearchUsage, Step
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MAX_CONTEXT_TOKENS = 120_000
+_DEFAULT_MAX_STEPS = 10
+_DEFAULT_MIN_COMPRESS_TOKENS = 100
+
+
+def _estimate_tokens(text: str) -> int:
+    return max(1, len(text) // 4)
+
+
+@dataclass
+class _LoopState:
+    """Internal result of :meth:`ResearchAgent._run_loop`.
+
+    Exposed to the engine's solo-WebSearchTool fast-path so it can feed the
+    raw message chain to :meth:`_Engine._normalize` while the public
+    :meth:`run` keeps producing a typed :class:`ResearchResult`.
+    """
+
+    messages: list
+    ai_history: list = field(default_factory=list)
+    trajectory: list = field(default_factory=list)
+    last_ai: Optional[Any] = None
+
+
+class ResearchAgent:
+    """Multi-step web-research agent with on-the-fly compression.
+
+    Args:
+        engine: A live :class:`compresr.agents.engine._Engine`.
+        search_tool: LangChain ``BaseTool`` taking ``query: str``.
+        max_steps: Hard cap on LLM turns. On the final turn ``tool_choice``
+            is set to ``"none"`` so the model has to commit.
+        system_prompt: Override the default research prompt.
+        compress_snippets: Compress each tool result via
+            ``client.compress(query=live_query)`` before appending.
+        compression_model: Compresr model name (default ``"latte_v1"``).
+        min_compress_tokens: Skip compression for tool results below this size.
+        max_context_tokens: Drop the oldest tool-result pair when context
+            exceeds this cap.
+    """
+
+    def __init__(
+        self,
+        *,
+        engine: Any,
+        search_tool: Any,
+        max_steps: int = _DEFAULT_MAX_STEPS,
+        system_prompt: Optional[str] = None,
+        compress_snippets: bool = True,
+        compression_model: str = "latte_v1",
+        min_compress_tokens: int = _DEFAULT_MIN_COMPRESS_TOKENS,
+        max_context_tokens: int = _DEFAULT_MAX_CONTEXT_TOKENS,
+    ) -> None:
+        self._engine = engine
+        self._search_tool = search_tool
+        self._max_steps = max(1, int(max_steps))
+        self._system_prompt = system_prompt or DEFAULT_RESEARCH_SYSTEM_PROMPT
+        self._compress_snippets = bool(compress_snippets)
+        self._compression_model = compression_model
+        self._min_compress_tokens = int(min_compress_tokens)
+        self._max_context_tokens = int(max_context_tokens)
+
+    def run(self, question: str, *, model: Optional[str] = None) -> ResearchResult:
+        state = self._run_loop(question, model=model)
+        usage = self._aggregate_usage(
+            state.ai_history,
+            search_calls=sum(1 for s in state.trajectory if s.type == "search"),
+        )
+        final_text = self._stringify(state.last_ai.content) if state.last_ai is not None else ""
+        parsed = parse_research_output(final_text)
+        citations = self._collect_citations(parsed.citation_urls, state.trajectory)
+
+        return ResearchResult(
+            answer=parsed.answer,
+            explanation=parsed.explanation,
+            confidence=parsed.confidence,
+            text=final_text,
+            citations=citations,
+            trajectory=state.trajectory,
+            usage=usage,
+            raw=state.last_ai,
+        )
+
+    def _run_loop(
+        self,
+        question: str,
+        *,
+        model: Optional[str] = None,
+        extra_chat_kwargs: Optional[dict] = None,
+    ) -> _LoopState:
+        """Execute the strict-output ReAct loop and return raw state.
+
+        Shared by :meth:`run` (which parses ``ResearchResult``) and the
+        engine's solo-WebSearchTool fast-path (which feeds ``state.messages``
+        into :meth:`_Engine._normalize`).
+
+        ``extra_chat_kwargs`` lets the engine path bake per-call LLM knobs
+        (``max_tokens``, ``temperature``…) into the cached chat model so
+        they survive ``bind_tools``.
+        """
+        from langchain_core.messages import (  # type: ignore[import-not-found]
+            HumanMessage,
+            SystemMessage,
+            ToolMessage,
+        )
+
+        effective_model = self._engine._resolve_model(model)
+        chat = self._engine._get_or_build_chat(effective_model, extra_kwargs=extra_chat_kwargs)
+
+        messages: list = [
+            SystemMessage(content=self._system_prompt),
+            HumanMessage(content=question),
+        ]
+        ai_history: list = []
+        trajectory: list[Step] = []
+        last_ai: Optional[Any] = None
+
+        for step_idx in range(self._max_steps):
+            self._maybe_truncate(messages)
+
+            tool_choice = "none" if step_idx == self._max_steps - 1 else "auto"
+            bound = chat.bind_tools([self._search_tool], tool_choice=tool_choice)
+            invoke_messages = self._apply_cache_control(messages)
+
+            t0 = time.time()
+            try:
+                response = bound.invoke(invoke_messages)
+            except Exception as exc:  # noqa: BLE001
+                trajectory.append(
+                    Step(type="error", text=str(exc), latency_s=round(time.time() - t0, 3))
+                )
+                break
+            step_latency = round(time.time() - t0, 3)
+
+            ai_history.append(response)
+            last_ai = response
+            messages.append(response)
+
+            tool_calls = getattr(response, "tool_calls", None) or []
+            if not tool_calls:
+                trajectory.append(
+                    Step(
+                        type="answer",
+                        text=self._stringify(response.content),
+                        latency_s=step_latency,
+                    )
+                )
+                break
+
+            for tc in tool_calls:
+                args = tc.get("args") if isinstance(tc, dict) else {}
+                args = args if isinstance(args, dict) else {}
+                query = args.get("query")
+                trajectory.append(Step(type="search", query=query, latency_s=step_latency))
+
+                raw_result = self._invoke_search(args)
+                final_result = (
+                    self._compress(raw_result, query or question)
+                    if self._compress_snippets
+                    else raw_result
+                )
+                trajectory.append(
+                    Step(
+                        type="tool_result",
+                        chars=len(final_result),
+                        text=final_result,
+                    )
+                )
+
+                tool_call_id = tc.get("id") if isinstance(tc, dict) else None
+                messages.append(
+                    ToolMessage(
+                        content=final_result,
+                        tool_call_id=tool_call_id or "",
+                        name=getattr(self._search_tool, "name", "search_web"),
+                    )
+                )
+
+        return _LoopState(
+            messages=messages,
+            ai_history=ai_history,
+            trajectory=trajectory,
+            last_ai=last_ai,
+        )
+
+    def _apply_cache_control(self, messages: list) -> list:
+        """Stamp Anthropic ephemeral cache_control on the last message.
+
+        Mirrors ``AnthropicPromptCachingMiddleware`` for the bypass path —
+        the research agent does not go through ``create_agent`` so the
+        engine's middleware never runs. No-op for non-Anthropic providers.
+        """
+        provider = getattr(self._engine, "_provider", None)
+        if provider != "anthropic":
+            return messages
+        if not getattr(self._engine, "_enable_prompt_cache", False):
+            return messages
+        min_msgs = getattr(self._engine, "_prompt_cache_min_messages", 2)
+        if len(messages) < min_msgs:
+            return messages
+
+        ttl = getattr(self._engine, "_prompt_cache_ttl", "5m")
+        marker = {"type": "ephemeral", "ttl": ttl}
+        last = messages[-1]
+        content = getattr(last, "content", None)
+        if isinstance(content, str):
+            new_content: list = [{"type": "text", "text": content, "cache_control": marker}]
+        elif isinstance(content, list) and content:
+            new_content = list(content)
+            tail = new_content[-1]
+            if isinstance(tail, dict):
+                tail = dict(tail)
+                tail["cache_control"] = marker
+                new_content[-1] = tail
+            else:
+                new_content.append({"type": "text", "text": str(tail), "cache_control": marker})
+        else:
+            return messages
+
+        try:
+            patched = last.model_copy(update={"content": new_content})
+        except Exception:  # noqa: BLE001
+            patched = type(last)(content=new_content)
+        return [*messages[:-1], patched]
+
+    def _invoke_search(self, args: dict) -> str:
+        try:
+            out = self._search_tool.invoke(args)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("research: search tool raised %s; agent will continue", exc)
+            return f"Search error: {exc}"
+        return self._stringify(out)
+
+    def _compress(self, text: str, query: str) -> str:
+        if not text or _estimate_tokens(text) < self._min_compress_tokens:
+            return text
+        client = self._engine._compresr_client
+        try:
+            resp = client.compress(
+                context=text,
+                query=query,
+                compression_model_name=self._compression_model,
+            )
+            data = getattr(resp, "data", None)
+            compressed = getattr(data, "compressed_context", None) if data is not None else None
+            return compressed if isinstance(compressed, str) and compressed else text
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("research: compression failed (%s); using raw snippet", exc)
+            return text
+
+    def _maybe_truncate(self, messages: list) -> None:
+        if not self._max_context_tokens:
+            return
+        total = sum(_estimate_tokens(self._stringify(getattr(m, "content", ""))) for m in messages)
+        if total <= self._max_context_tokens:
+            return
+        guard = 0
+        while total > self._max_context_tokens and len(messages) >= 4 and guard < 4:
+            del messages[2:4]
+            total = sum(
+                _estimate_tokens(self._stringify(getattr(m, "content", ""))) for m in messages
+            )
+            guard += 1
+
+    def _aggregate_usage(
+        self,
+        ai_messages: Sequence[Any],
+        *,
+        search_calls: int = 0,
+    ) -> ResearchUsage:
+        from compresr.agents.engine import _aggregate_usage
+
+        agg = _aggregate_usage(list(ai_messages))
+        return ResearchUsage(
+            input_tokens=int(agg.get("input_tokens", 0) or 0),
+            output_tokens=int(agg.get("output_tokens", 0) or 0),
+            cache_read_tokens=int(agg.get("cache_read_input_tokens", 0) or 0),
+            cache_creation_tokens=int(agg.get("cache_creation_input_tokens", 0) or 0),
+            calls=len(ai_messages),
+            search_calls=int(search_calls or 0),
+        )
+
+    def _collect_citations(
+        self, parsed_urls: Sequence[str], trajectory: Sequence[Step]
+    ) -> list[Citation]:
+        urls: list[str] = []
+        for u in parsed_urls:
+            if u not in urls:
+                urls.append(u)
+        for step in trajectory:
+            if step.type != "tool_result" or not step.text:
+                continue
+            for url in re.findall(r"https?://[^\s,;<>\"')]+", step.text):
+                if url not in urls:
+                    urls.append(url)
+        return [Citation(url=u) for u in urls]
+
+    @staticmethod
+    def _stringify(content: Any) -> str:
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts = []
+            for block in content:
+                if isinstance(block, dict):
+                    text = block.get("text")
+                    if isinstance(text, str):
+                        parts.append(text)
+                elif isinstance(block, str):
+                    parts.append(block)
+            return "".join(parts)
+        return str(content) if content is not None else ""

compresr-2.7.5/compresr/agents/research/facade.py

@@ -0,0 +1,94 @@
+"""``client.research`` facade — thin wrapper over :class:`ResearchAgent`."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from .agent import ResearchAgent
+from .types import ResearchResult
+
+_SEARCH_PROVIDER_ENV = {
+    "tavily": ("TAVILY_API_KEY",),
+    "brave": ("BRAVE_SEARCH_API_KEY", "BRAVE_API_KEY"),
+}
+
+
+class ResearchFacade:
+    def __init__(self, engine: Any) -> None:
+        self._engine = engine
+
+    def run(
+        self,
+        question: str,
+        *,
+        search: Any = "tavily",
+        max_steps: int = 10,
+        model: Optional[str] = None,
+        compress_snippets: bool = True,
+        compression_model: str = "latte_v1",
+        min_compress_tokens: int = 100,
+        max_context_tokens: int = 120_000,
+        system_prompt: Optional[str] = None,
+    ) -> ResearchResult:
+        """Multi-step research loop.
+
+        ``search`` is either a provider name (``"tavily"`` | ``"brave"``)
+        or a ready-made LangChain ``BaseTool``.
+        """
+        tool = self._resolve_search_tool(search)
+        agent = ResearchAgent(
+            engine=self._engine,
+            search_tool=tool,
+            max_steps=max_steps,
+            system_prompt=system_prompt,
+            compress_snippets=compress_snippets,
+            compression_model=compression_model,
+            min_compress_tokens=min_compress_tokens,
+            max_context_tokens=max_context_tokens,
+        )
+        return agent.run(question, model=model)
+
+    def search(
+        self,
+        question: str,
+        *,
+        search: Any = "tavily",
+        model: Optional[str] = None,
+        compress_snippets: bool = True,
+        compression_model: str = "latte_v1",
+        min_compress_tokens: int = 100,
+        max_context_tokens: int = 120_000,
+        system_prompt: Optional[str] = None,
+    ) -> ResearchResult:
+        """Single-shot: one search + forced answer (``max_steps=2``)."""
+        return self.run(
+            question,
+            search=search,
+            max_steps=2,
+            model=model,
+            compress_snippets=compress_snippets,
+            compression_model=compression_model,
+            min_compress_tokens=min_compress_tokens,
+            max_context_tokens=max_context_tokens,
+            system_prompt=system_prompt,
+        )
+
+    def _resolve_search_tool(self, search: Any) -> Any:
+        if not isinstance(search, str):
+            return search
+        provider = search.lower()
+        if provider not in _SEARCH_PROVIDER_ENV:
+            raise ValueError(
+                f"unsupported search provider {search!r}; expected one of "
+                f"{sorted(_SEARCH_PROVIDER_ENV)} or a LangChain BaseTool"
+            )
+        from ..tools.web_search import WebSearchTool
+
+        api_key: Optional[str] = None
+        for env_var in _SEARCH_PROVIDER_ENV[provider]:
+            v = os.environ.get(env_var)
+            if v:
+                api_key = v
+                break
+        return WebSearchTool(provider=provider, api_key=api_key)