compresr 2.7.9__tar.gz → 2.8.2__tar.gz

{compresr-2.7.9 → compresr-2.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compresr
-Version: 2.7.9
+Version: 2.8.2
 Summary: Python SDK for Compresr - Intelligent prompt compression service
 Author-email: Compresr Team <founders@compresr.ai>
 License-Expression: Apache-2.0
@@ -47,10 +47,15 @@ Provides-Extra: llamaindex
 Requires-Dist: llama-index-core>=0.11; extra == "llamaindex"
 Provides-Extra: litellm
 Requires-Dist: litellm[proxy]>=1.79; extra == "litellm"
+Provides-Extra: agentcore
+Requires-Dist: mcp>=1.0; extra == "agentcore"
+Requires-Dist: nest-asyncio>=1.6; extra == "agentcore"
 Provides-Extra: all
 Requires-Dist: langgraph>=0.2; extra == "all"
 Requires-Dist: llama-index-core>=0.11; extra == "all"
 Requires-Dist: litellm[proxy]>=1.79; extra == "all"
+Requires-Dist: mcp>=1.0; extra == "all"
+Requires-Dist: nest-asyncio>=1.6; extra == "all"
 Provides-Extra: langchain
 Provides-Extra: agents
 Provides-Extra: agents-anthropic
@@ -92,7 +97,7 @@ print(f"Saved:      {result.data.tokens_saved} tokens")
 print(result.data.compressed_context)
 ```
 
-The default model is `latte_v1` (query-aware). Pass any other model name your
+The default model is `latte_v2` (query-aware). Pass any other model name your
 account has access to via `compression_model_name="..."` — the backend
 validates.
 
@@ -180,7 +185,7 @@ client.messages.create(model="claude-haiku-4-5", max_tokens=512,
                        messages=[...], tools=[...])
 
 # OpenAI shape
-client.chat.completions.create(model="gpt-4o-mini", messages=[...], tools=[...])
+client.chat.completions.create(model="gpt-5-mini", messages=[...], tools=[...])
 
 # Native — returns a NormalizedResult
 client.run(prompt="...", model="claude-haiku-4-5", tools=[...], max_tokens=512)
@@ -200,6 +205,46 @@ search = WebSearchTool.tavily(
 # Brave: WebSearchTool.brave(api_key=..., max_results=5)
 ```
 
+#### Amazon Bedrock AgentCore
+
+`WebSearchTool.agentcore(...)` reaches Amazon Bedrock AgentCore web search via a
+Cognito OAuth handshake + an MCP streamable-HTTP session. Its runtime deps are
+optional:
+
+```bash
+pip install compresr[agentcore]
+```
+
+Config resolves from explicit args first, then env vars (the
+`AGENTCORE_`-prefixed name takes precedence, with the bare name as fallback):
+
+| Field | Env var (fallback) |
+|---|---|
+| `gateway_url` | `AGENTCORE_GATEWAY_MCP_URL` (`GATEWAY_MCP_URL`) |
+| `cognito_token_url` | `AGENTCORE_COGNITO_TOKEN_URL` (`COGNITO_TOKEN_URL`) |
+| `client_id` | `AGENTCORE_COGNITO_CLIENT_ID` (`COGNITO_CLIENT_ID`) |
+| `client_secret` | `AGENTCORE_COGNITO_CLIENT_SECRET` (`COGNITO_CLIENT_SECRET`) |
+| `scope` | `AGENTCORE_COGNITO_SCOPE` (`COGNITO_SCOPE`) |
+
+```python
+# All five values from env vars:
+search = WebSearchTool.agentcore(max_results=5)
+
+# Or pass them explicitly:
+search = WebSearchTool.agentcore(
+    gateway_url="https://...gateway.../mcp",
+    cognito_token_url="https://...oauth2/token",
+    client_id="...",
+    client_secret="...",          # never logged
+    scope="gateway/invoke",
+    max_results=5,                # clamped to 1–25
+)
+```
+
+The tool emitted to the LLM is named `agentcore_web_search` and returns
+plaintext. Domain filters (`allowed_domains` / `blocked_domains`) are not
+supported by AgentCore — use Tavily for domain filtering.
+
 ### Bring your own tool
 
 Any `@tool`-decorated function works — its string output is compressed for you:
@@ -286,7 +331,7 @@ Tavily / Brave keys are read from `TAVILY_API_KEY` / `BRAVE_SEARCH_API_KEY`
 
 | Param | Purpose |
 |---|---|
-| `query` | Question the LLM is trying to answer — drives `latte_v1` compression |
+| `query` | Question the LLM is trying to answer — drives `latte_v2` compression |
 | `target_compression_ratio` | `0-1` strength (e.g. `0.5` = remove 50%) or `>1` for Nx factor (`4` = 4x). Backend max: 200 |
 | `coarse` | `True` for paragraph-level (default, faster), `False` for token-level (fine-grained) |
 | `heuristic_chunking` | Structure-preserving chunking |
@@ -325,6 +370,7 @@ Genuinely optional integrations beyond the agents layer:
 | `compresr[langgraph]` | `langgraph` (LangGraph checkpoint serializer, store, handoff tool) |
 | `compresr[llamaindex]` | `llama-index-core` (node postprocessor, memory block, tool wrapper) |
 | `compresr[litellm]` | `litellm[proxy]` (LiteLLM proxy guardrail) |
+| `compresr[agentcore]` | `mcp`, `nest-asyncio` (Amazon Bedrock AgentCore web search) |
 | `compresr[all]` | all three above |
 
 ```bash
@@ -407,9 +453,9 @@ Minimal `proxy_config.yaml`:
 
 ```yaml
 model_list:
-  - model_name: gpt-4o-mini
+  - model_name: gpt-5-mini
     litellm_params:
-      model: openai/gpt-4o-mini
+      model: openai/gpt-5-mini
       api_key: os.environ/OPENAI_API_KEY
 
 guardrails:
@@ -437,7 +483,7 @@ Per-request override (no restart, no YAML edit):
 
 ```json
 {
-  "model": "gpt-4o-mini",
+  "model": "gpt-5-mini",
   "messages": [...],
   "metadata": {
     "guardrail_config": {

{compresr-2.7.9 → compresr-2.8.2}/README.md

@@ -29,7 +29,7 @@ print(f"Saved:      {result.data.tokens_saved} tokens")
 print(result.data.compressed_context)
 ```
 
-The default model is `latte_v1` (query-aware). Pass any other model name your
+The default model is `latte_v2` (query-aware). Pass any other model name your
 account has access to via `compression_model_name="..."` — the backend
 validates.
 
@@ -117,7 +117,7 @@ client.messages.create(model="claude-haiku-4-5", max_tokens=512,
                        messages=[...], tools=[...])
 
 # OpenAI shape
-client.chat.completions.create(model="gpt-4o-mini", messages=[...], tools=[...])
+client.chat.completions.create(model="gpt-5-mini", messages=[...], tools=[...])
 
 # Native — returns a NormalizedResult
 client.run(prompt="...", model="claude-haiku-4-5", tools=[...], max_tokens=512)
@@ -137,6 +137,46 @@ search = WebSearchTool.tavily(
 # Brave: WebSearchTool.brave(api_key=..., max_results=5)
 ```
 
+#### Amazon Bedrock AgentCore
+
+`WebSearchTool.agentcore(...)` reaches Amazon Bedrock AgentCore web search via a
+Cognito OAuth handshake + an MCP streamable-HTTP session. Its runtime deps are
+optional:
+
+```bash
+pip install compresr[agentcore]
+```
+
+Config resolves from explicit args first, then env vars (the
+`AGENTCORE_`-prefixed name takes precedence, with the bare name as fallback):
+
+| Field | Env var (fallback) |
+|---|---|
+| `gateway_url` | `AGENTCORE_GATEWAY_MCP_URL` (`GATEWAY_MCP_URL`) |
+| `cognito_token_url` | `AGENTCORE_COGNITO_TOKEN_URL` (`COGNITO_TOKEN_URL`) |
+| `client_id` | `AGENTCORE_COGNITO_CLIENT_ID` (`COGNITO_CLIENT_ID`) |
+| `client_secret` | `AGENTCORE_COGNITO_CLIENT_SECRET` (`COGNITO_CLIENT_SECRET`) |
+| `scope` | `AGENTCORE_COGNITO_SCOPE` (`COGNITO_SCOPE`) |
+
+```python
+# All five values from env vars:
+search = WebSearchTool.agentcore(max_results=5)
+
+# Or pass them explicitly:
+search = WebSearchTool.agentcore(
+    gateway_url="https://...gateway.../mcp",
+    cognito_token_url="https://...oauth2/token",
+    client_id="...",
+    client_secret="...",          # never logged
+    scope="gateway/invoke",
+    max_results=5,                # clamped to 1–25
+)
+```
+
+The tool emitted to the LLM is named `agentcore_web_search` and returns
+plaintext. Domain filters (`allowed_domains` / `blocked_domains`) are not
+supported by AgentCore — use Tavily for domain filtering.
+
 ### Bring your own tool
 
 Any `@tool`-decorated function works — its string output is compressed for you:
@@ -223,7 +263,7 @@ Tavily / Brave keys are read from `TAVILY_API_KEY` / `BRAVE_SEARCH_API_KEY`
 
 | Param | Purpose |
 |---|---|
-| `query` | Question the LLM is trying to answer — drives `latte_v1` compression |
+| `query` | Question the LLM is trying to answer — drives `latte_v2` compression |
 | `target_compression_ratio` | `0-1` strength (e.g. `0.5` = remove 50%) or `>1` for Nx factor (`4` = 4x). Backend max: 200 |
 | `coarse` | `True` for paragraph-level (default, faster), `False` for token-level (fine-grained) |
 | `heuristic_chunking` | Structure-preserving chunking |
@@ -262,6 +302,7 @@ Genuinely optional integrations beyond the agents layer:
 | `compresr[langgraph]` | `langgraph` (LangGraph checkpoint serializer, store, handoff tool) |
 | `compresr[llamaindex]` | `llama-index-core` (node postprocessor, memory block, tool wrapper) |
 | `compresr[litellm]` | `litellm[proxy]` (LiteLLM proxy guardrail) |
+| `compresr[agentcore]` | `mcp`, `nest-asyncio` (Amazon Bedrock AgentCore web search) |
 | `compresr[all]` | all three above |
 
 ```bash
@@ -344,9 +385,9 @@ Minimal `proxy_config.yaml`:
 
 ```yaml
 model_list:
-  - model_name: gpt-4o-mini
+  - model_name: gpt-5-mini
     litellm_params:
-      model: openai/gpt-4o-mini
+      model: openai/gpt-5-mini
       api_key: os.environ/OPENAI_API_KEY
 
 guardrails:
@@ -374,7 +415,7 @@ Per-request override (no restart, no YAML edit):
 
 ```json
 {
-  "model": "gpt-4o-mini",
+  "model": "gpt-5-mini",
   "messages": [...],
   "metadata": {
     "guardrail_config": {

{compresr-2.7.9 → compresr-2.8.2}/compresr/__init__.py

@@ -42,6 +42,7 @@ Quick Start - Agents (opt-in provider-shape facades):
 from importlib.metadata import PackageNotFoundError, version
 from typing import Any
 
+from .auth import login, logout
 from .clients import CompressionClient
 from .config import MODELS
 from .retry import RetryConfig
@@ -56,6 +57,8 @@ __all__ = [
     "CompressionClient",
     "MODELS",
     "RetryConfig",
+    "login",
+    "logout",
     "WebSearchTool",
     "CompressionPolicy",
     "ResearchResult",

compresr-2.8.2/compresr/__main__.py

@@ -0,0 +1,150 @@
+"""``compresr-sdk`` CLI: login, logout, whoami, status."""
+
+from __future__ import annotations
+
+import argparse
+import configparser
+import sys
+from typing import Optional
+
+from . import __version__
+from .auth import login as _login
+from .auth import logout as _logout
+from .credentials import (
+    DEFAULT_PROFILE,
+    LockAcquisitionError,
+    credentials_path,
+    load,
+)
+
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _cmd_login(args: argparse.Namespace) -> int:
+    try:
+        _login(
+            app_url=args.app_url,
+            base_url=args.base_url,
+            profile=args.profile,
+            timeout=args.timeout,
+            open_browser=not args.no_browser,
+        )
+        return 0
+    except (RuntimeError, TimeoutError, ValueError) as e:
+        _err(f"error: {e}")
+        return 1
+    except PermissionError as e:
+        _err(f"error: {e}")
+        _err("hint: run `chmod 600 ~/.compresr/credentials` and retry.")
+        return 1
+
+
+def _cmd_logout(args: argparse.Namespace) -> int:
+    try:
+        removed = _logout(
+            args.profile,
+            revoke_server_key=not args.no_server_revoke,
+            base_url=args.base_url,
+        )
+    except LockAcquisitionError as e:
+        _err(f"error: {e}")
+        return 1
+    except PermissionError as e:
+        _err(f"error: {e}")
+        _err("hint: run `chmod 600 ~/.compresr/credentials` and retry.")
+        return 1
+    if removed:
+        print(f"Removed credentials for profile '{args.profile}'.")
+        return 0
+    print(f"No credentials found for profile '{args.profile}'.")
+    return 0
+
+
+def _cmd_whoami(args: argparse.Namespace) -> int:
+    try:
+        key = load(args.profile)
+    except PermissionError as e:
+        _err(f"error: {e}")
+        return 1
+    if not key:
+        _err(f"Not logged in (profile '{args.profile}'). Run `compresr-sdk login`.")
+        return 1
+    print(f"profile:  {args.profile}")
+    print(f"file:     {credentials_path()}")
+    print(f"api_key:  {key[:8]}…{key[-4:]}")
+    return 0
+
+
+def _cmd_status(_args: argparse.Namespace) -> int:
+    from .credentials import _read_file
+
+    path = credentials_path()
+    print(f"credentials file: {path}")
+    print(f"exists:           {path.exists()}")
+    if not path.exists():
+        return 0
+    try:
+        parser = _read_file()
+    except PermissionError as e:
+        _err(f"error: {e}")
+        return 1
+    except configparser.Error as e:
+        _err(f"warning: file is corrupt ({e})")
+        return 0
+    profiles = parser.sections()
+    print(f"profiles:         {', '.join(profiles) if profiles else '(none)'}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="compresr-sdk", description="Compresr SDK CLI")
+    p.add_argument("--version", action="version", version=f"compresr-sdk {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    login_p = sub.add_parser("login", help="Log in via browser and store credentials")
+    login_p.add_argument("--profile", default=DEFAULT_PROFILE)
+    login_p.add_argument("--app-url", default=None, help="Override web app URL")
+    login_p.add_argument("--base-url", default=None, help="Override API base URL")
+    login_p.add_argument("--timeout", type=float, default=120.0)
+    login_p.add_argument(
+        "--no-browser", action="store_true", help="Print the URL instead of opening it"
+    )
+    login_p.set_defaults(func=_cmd_login)
+
+    logout_p = sub.add_parser(
+        "logout",
+        help="Revoke the server-side CLI key and remove stored credentials",
+    )
+    logout_p.add_argument("--profile", default=DEFAULT_PROFILE)
+    logout_p.add_argument("--base-url", default=None, help="Override API base URL")
+    logout_p.add_argument(
+        "--no-server-revoke",
+        action="store_true",
+        help="Skip the server-side key revoke and only delete local credentials.",
+    )
+    logout_p.set_defaults(func=_cmd_logout)
+
+    whoami_p = sub.add_parser("whoami", help="Show the stored API key preview")
+    whoami_p.add_argument("--profile", default=DEFAULT_PROFILE)
+    whoami_p.set_defaults(func=_cmd_whoami)
+
+    status_p = sub.add_parser("status", help="Show credentials file location and profiles")
+    status_p.set_defaults(func=_cmd_status)
+
+    return p
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except KeyboardInterrupt:
+        _err("\nAborted.")
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

compresr-2.8.2/compresr/agents/tools/_agentcore.py

@@ -0,0 +1,247 @@
+"""AgentCore Web Search client (Amazon Bedrock AgentCore over MCP).
+
+Ported from the standalone ``websearch_client.py`` reference. Wraps the
+Cognito client-credentials OAuth handshake plus an MCP streamable-HTTP session
+into a synchronous :meth:`AgentCoreClient.search` call that works in plain
+scripts and in Jupyter (handles the already-running event-loop case).
+
+The runtime dependencies (``mcp``, ``nest-asyncio``) are **optional** — they are
+imported lazily inside the call so a bare ``pip install compresr`` still imports
+fine. The error only surfaces when ``WebSearchTool.agentcore(...)`` is actually
+invoked without the extra installed::
+
+    pip install compresr[agentcore]
+
+Never logs the Cognito client secret or the bearer token.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+# Guard against an unbounded/misbehaving gateway response before buffering it
+# in memory and parsing as JSON.
+MAX_RESPONSE_BYTES = 1_000_000
+
+# The gateway also exposes this built-in *tool*-search (semantic search over the
+# gateway's own tools). It is NOT web search and must be ignored.
+TOOL_SEARCH_META = "x_amz_bedrock_agentcore_search"
+
+TOKEN_TIMEOUT_SECONDS = 30
+
+# AgentCore web search accepts maxResults in the inclusive range 1..25.
+MIN_RESULTS = 1
+MAX_RESULTS = 25
+
+_MISSING_DEP_MSG = (
+    "WebSearchTool.agentcore requires the 'agentcore' extra. "
+    "Install: pip install compresr[agentcore]"
+)
+
+
+@dataclass(frozen=True)
+class AgentCoreConfig:
+    """Immutable connection config for the AgentCore web-search gateway."""
+
+    gateway_url: str
+    cognito_token_url: str
+    client_id: str
+    client_secret: str
+    scope: str
+    max_results: int = 5
+
+
+def _clamp_results(value: int) -> int:
+    """Clamp a requested result count to AgentCore's inclusive 1..25 range."""
+    return max(MIN_RESULTS, min(MAX_RESULTS, value))
+
+
+def _run(coro: Any) -> Any:
+    """Run a coroutine whether or not an event loop is already running (Jupyter)."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    # Inside a running loop (e.g. Jupyter): allow nested execution.
+    try:
+        import nest_asyncio
+    except ImportError as exc:  # pragma: no cover - exercised via search()
+        raise ImportError(_MISSING_DEP_MSG) from exc
+
+    nest_asyncio.apply()
+    return loop.run_until_complete(coro)
+
+
+class AgentCoreClient:
+    """Synchronous client for AgentCore web search over MCP.
+
+    Mints (and caches) a Cognito bearer token, then opens an MCP
+    streamable-HTTP session to call the gateway's web-search tool. A single
+    instance is shared by the built tool so the token is reused across calls.
+    """
+
+    def __init__(self, config: AgentCoreConfig) -> None:
+        self._config = config
+        self._token: Optional[str] = None
+        self._token_lock = threading.Lock()
+
+    # --- auth ----------------------------------------------------------------
+
+    def token(self, refresh: bool = False) -> str:
+        """Return a cached bearer token, minting a fresh one when needed.
+
+        Guarded by a lock (double-checked locking) so concurrent first-use
+        calls from multiple threads only mint one token. The client secret
+        and the resulting token are never logged.
+        """
+        if self._token and not refresh:
+            return self._token
+        with self._token_lock:
+            # Re-check after acquiring the lock: another thread may have
+            # already minted/refreshed the token while we were waiting.
+            if self._token and not refresh:
+                return self._token
+            try:
+                resp = httpx.post(
+                    self._config.cognito_token_url,
+                    data={
+                        "grant_type": "client_credentials",
+                        "client_id": self._config.client_id,
+                        "client_secret": self._config.client_secret,
+                        "scope": self._config.scope,
+                    },
+                    headers={"Content-Type": "application/x-www-form-urlencoded"},
+                    timeout=TOKEN_TIMEOUT_SECONDS,
+                )
+                resp.raise_for_status()
+                self._token = resp.json()["access_token"]
+            except httpx.HTTPError as exc:
+                # Re-raise sanitized: the original exception's .request (and
+                # this frame's locals) carry the client_secret, which we do
+                # not want chained into error-monitoring tools (e.g. Sentry).
+                status = getattr(getattr(exc, "response", None), "status_code", None)
+                detail = f" (HTTP {status})" if status is not None else ""
+                raise RuntimeError(f"AgentCore Cognito token request failed{detail}.") from None
+            return self._token
+
+    # --- tool selection ------------------------------------------------------
+
+    @staticmethod
+    def _pick_web_search_tool(names: list[str]) -> str:
+        """Pick the web-search tool, ignoring the semantic tool-search meta tool."""
+        candidates = [n for n in names if n != TOOL_SEARCH_META]
+        for name in candidates:
+            if "websearch" in name.lower().replace("-", "").replace("_", ""):
+                return name
+        if not candidates:
+            raise RuntimeError(f"No web-search tool found among {names}")
+        return candidates[0]
+
+    # --- search --------------------------------------------------------------
+
+    async def _search_async(self, query: str, max_results: int, *, refresh: bool) -> dict:
+        # Lazy import so a bare install imports fine; only fails on actual use.
+        try:
+            from mcp import ClientSession
+            from mcp.client.streamable_http import streamablehttp_client
+        except ImportError as exc:
+            raise ImportError(_MISSING_DEP_MSG) from exc
+
+        headers = {"Authorization": f"Bearer {self.token(refresh=refresh)}"}
+        async with streamablehttp_client(self._config.gateway_url, headers=headers) as (
+            read,
+            write,
+            _,
+        ):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                names = [t.name for t in (await session.list_tools()).tools]
+                tool = self._pick_web_search_tool(names)
+                result = await session.call_tool(tool, {"query": query, "maxResults": max_results})
+                return _parse_tool_result(result)
+
+    def search(self, query: str, max_results: Optional[int] = None) -> list[dict]:
+        """Run a web search and return normalized result dicts.
+
+        Each result is ``{"title", "url", "content", "published_date"}`` — the
+        ``content`` key matches the SDK's ``_flatten_search_results`` flattener.
+        Re-mints the bearer token once on an MCP 401 and retries.
+        """
+        count = _clamp_results(self._config.max_results if max_results is None else max_results)
+        try:
+            payload = _run(self._search_async(query, count, refresh=False))
+        except Exception as exc:  # noqa: BLE001 - inspect for a 401 to retry once
+            if _is_unauthorized(exc):
+                payload = _run(self._search_async(query, count, refresh=True))
+            else:
+                raise
+        results = payload.get("results", [])
+        if not isinstance(results, list):
+            raise RuntimeError(
+                "AgentCore web-search returned an unexpected 'results' shape "
+                f"(expected a list, got {type(results).__name__})."
+            )
+        out: list[dict] = []
+        for item in results:
+            if not isinstance(item, dict):
+                continue
+            out.append(
+                {
+                    "title": item.get("title"),
+                    "url": item.get("url"),
+                    "content": item.get("text", "") or "",
+                    "published_date": item.get("publishedDate"),
+                }
+            )
+        return out
+
+
+def _parse_tool_result(result: Any) -> dict:
+    """Validate and parse an MCP ``CallToolResult`` into a JSON dict.
+
+    Defensive against everything a misbehaving/compromised gateway could
+    return: a tool-level error (``isError=True`` with plain-text content,
+    NOT JSON), an oversized body, malformed JSON, or a JSON value that isn't
+    an object. Raises ``RuntimeError`` with a clear, secret-free message in
+    every case instead of letting a bare ``JSONDecodeError``/``AttributeError``
+    propagate.
+    """
+    text = "".join(getattr(b, "text", "") for b in result.content)
+    if getattr(result, "isError", False):
+        # Gateway tool-level errors (bad query, throttling, auth/scope error)
+        # come back as plain text, NOT JSON. Surface them directly instead of
+        # failing on json.loads with a confusing JSONDecodeError. The text may
+        # itself contain "401" — keep it intact so the unauthorized-retry
+        # heuristic in _is_unauthorized still matches.
+        raise RuntimeError(f"AgentCore web-search tool error: {text}")
+    if len(text.encode("utf-8", errors="ignore")) > MAX_RESPONSE_BYTES:
+        raise RuntimeError(
+            f"AgentCore web-search response exceeded the {MAX_RESPONSE_BYTES} byte size guard."
+        )
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"AgentCore web-search returned malformed JSON: {exc}") from None
+    if not isinstance(payload, dict):
+        raise RuntimeError(
+            "AgentCore web-search returned an unexpected JSON shape "
+            f"(expected an object, got {type(payload).__name__})."
+        )
+    return payload
+
+
+def _is_unauthorized(exc: BaseException) -> bool:
+    """Best-effort detection of an MCP/HTTP 401 to trigger a single token re-mint."""
+    status = getattr(getattr(exc, "response", None), "status_code", None)
+    if status == 401:
+        return True
+    return "401" in str(exc)
+
+
+__all__ = ["AgentCoreConfig", "AgentCoreClient"]