chakpy 0.3.2__tar.gz → 0.3.4__tar.gz

{chakpy-0.3.2/chakpy.egg-info → chakpy-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chakpy
-Version: 0.3.2
+Version: 0.3.4
 Summary: A simple, yet elegant, LLM API routing library
 Author: Chak Contributors
 License: MIT
@@ -25,9 +25,6 @@ Requires-Dist: anthropic>=0.40.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: dashscope>=1.20.0
 Requires-Dist: httpx>=0.24.0
-Requires-Dist: pymupdf4llm>=0.0.17
-Requires-Dist: pymupdf-layout>=1.27.0
-Requires-Dist: markdown>=3.4.0
 Requires-Dist: boto3>=1.26.0
 Requires-Dist: tiktoken>=0.5.0
 Requires-Dist: loguru>=0.7.0
@@ -51,6 +48,16 @@ Requires-Dist: readability-lxml>=0.8.1; extra == "web"
 Requires-Dist: firecrawl-py>=1.0.0; extra == "web"
 Requires-Dist: tavily-python>=0.3.0; extra == "web"
 Requires-Dist: ddgs>=0.1.0; extra == "web"
+Provides-Extra: tools
+Requires-Dist: pymupdf4llm>=0.0.17; extra == "tools"
+Requires-Dist: pymupdf-layout>=1.27.0; extra == "tools"
+Requires-Dist: markdown>=3.4.0; extra == "tools"
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "tools"
+Requires-Dist: readability-lxml>=0.8.1; extra == "tools"
+Requires-Dist: firecrawl-py>=1.0.0; extra == "tools"
+Requires-Dist: tavily-python>=0.3.0; extra == "tools"
+Requires-Dist: ddgs>=0.1.0; extra == "tools"
+Requires-Dist: e2b>=2.0.0; extra == "tools"
 Provides-Extra: all
 Requires-Dist: fastapi>=0.104.0; extra == "all"
 Requires-Dist: uvicorn>=0.24.0; extra == "all"
@@ -70,6 +77,7 @@ Requires-Dist: ddgs>=0.1.0; extra == "all"
 Requires-Dist: pymupdf4llm>=0.0.17; extra == "all"
 Requires-Dist: pymupdf-layout>=1.27.0; extra == "all"
 Requires-Dist: markdown>=3.4.0; extra == "all"
+Requires-Dist: e2b>=2.0.0; extra == "all"
 Dynamic: license-file
 
 <div align="center">
@@ -98,6 +106,8 @@ chak is not another liteLLM, one-api, or OpenRouter, but a client library that a
 
 ## 🌵 What's New
 
+- **2026-04-27 | v0.3.4** - e2b Sandbox:
+  - **Sandbox tool**: New `Sandbox` built-in tool — run code in an isolated e2b cloud VM. See [Built-in Standard Tools](#built-in-standard-tools).
 - **2026-04-22 | v0.3.2** - Built-in standard tools:
   - **Built-in standard tools**: 7 atomic-level tools now ship with chak — `Bash`, `Python`, `FileSystem`, `Web`, `Search`, `Http`, `Pdf`. Drop them directly into `tools=[]` to give any agent baseline capabilities. See [Built-in Standard Tools](#built-in-standard-tools).
 - **2026-04-08 | v0.3.1** - Human-in-the-Loop upgrade & built-in execution tools:
@@ -342,6 +352,9 @@ OpenAI, Google Gemini, Azure OpenAI, Anthropic Claude, Alibaba Bailian, Baidu We
 # Basic installation (SDK only)
 pip install chakpy
 
+# With built-in standard tools (Pdf, Web, Search, Sandbox)
+pip install chakpy[tools]
+
 # With server support
 pip install chakpy[server]
 
@@ -349,6 +362,13 @@ pip install chakpy[server]
 pip install chakpy[all]
 ```
 
+| Extra | What it installs |
+|-------|------------------|
+| `tools` | pymupdf4llm, beautifulsoup4, readability-lxml, ddgs, e2b (and optional API clients for Firecrawl/Tavily) |
+| `server` | fastapi, uvicorn, websockets, pyyaml |
+| `web` | beautifulsoup4, readability-lxml, firecrawl-py, tavily-python, ddgs |
+| `all` | everything above |
+
 ### Chat with global models in a few lines
 
 ```python
@@ -615,10 +635,12 @@ See full example: [examples/tool_calling_claude_skill.py](examples/tool_calling_
 
 ### Built-in Standard Tools
 
-chak ships 7 atomic tools that cover the most common agent needs out of the box. Import and pass them directly — no wrapping, no configuration required.
+chak ships 8 atomic tools that cover the most common agent needs out of the box. Import and pass them directly — no wrapping, no configuration required.
+
+> Tools with optional dependencies require `pip install chakpy[tools]` (or install individual packages as needed — each tool prints an actionable `pip install` message if a dependency is missing).
 
 ```python
-from chak.tools.std import Bash, Python, FileSystem, Web, Search, Http, Pdf
+from chak.tools.std import Bash, Python, FileSystem, Web, Search, Http, Pdf, Sandbox
 
 conv = chak.Conversation(
     "openai/gpt-4o",
@@ -629,18 +651,21 @@ conv = chak.Conversation(
 response = await conv.asend("Search for the latest Python release, then save a summary to ./notes.txt")
 ```
 
-| Tool | Class | What it does |
-|------|-------|--------------|
-| Shell | `Bash` | Run any shell command. Cross-platform (PowerShell on Windows, bash on Unix). |
-| Code Interpreter | `Python` | Write and run Python code snippets in the active venv. |
-| File System | `FileSystem` | Read, write, edit, list, search, and delete files and directories. |
-| Web | `Web` | Fetch and parse web pages into clean text (Firecrawl → Jina → httpx fallback). |
-| Search | `Search` | Search the web and return structured results (Tavily → Brave → DuckDuckGo fallback). |
-| HTTP Client | `Http` | Full HTTP client — GET, POST, PUT, PATCH, DELETE with headers and body. |
-| PDF | `Pdf` | Extract text and tables from PDF files (local path or URL). |
+| Tool | Class | What it does | Optional deps |
+|------|-------|--------------|---------------|
+| Shell | `Bash` | Run any shell command. Cross-platform (PowerShell on Windows, bash on Unix). | — |
+| Code Interpreter | `Python` | Write and run Python code snippets in the active venv. | — |
+| File System | `FileSystem` | Read, write, edit, list, search, and delete files and directories. | — |
+| HTTP Client | `Http` | Full HTTP client — GET, POST, PUT, PATCH, DELETE with headers and body. | — |
+| Web | `Web` | Fetch and parse web pages into clean text (Firecrawl → Jina → httpx fallback). | `firecrawl-py` (Layer 1, needs API key), `beautifulsoup4`, `readability-lxml` |
+| Search | `Search` | Search the web and return structured results (Tavily → Brave → DuckDuckGo fallback). | `ddgs`, `tavily-python` |
+| PDF | `Pdf` | Extract text and tables from PDF files (local path or URL). | `pymupdf4llm` |
+| Sandbox | `Sandbox` | Run multi-file code projects in an isolated e2b cloud sandbox. Supports any language reachable from bash. | `e2b`, `E2B_API_KEY` |
 
 These tools are intentionally minimal and composable. Combine them freely or mix with your own custom tools.
 
+See [`examples/tool_calling_std.py`](examples/tool_calling_std.py) for a runnable demo of every tool, including an `all` mode that runs them all in sequence.
+
 > ⚠️ **Security**: `Bash` and `Python` execute with host-process permissions. For production deployments, use `hitl_handler` for human approval, or run inside a sandboxed environment. `Bash` supports `deny_patterns`, `sensitive_files`, and `working_dir` parameters for fine-grained access control.
 
 ### Pass Functions

{chakpy-0.3.2 → chakpy-0.3.4}/README.md

@@ -24,6 +24,8 @@ chak is not another liteLLM, one-api, or OpenRouter, but a client library that a
 
 ## 🌵 What's New
 
+- **2026-04-27 | v0.3.4** - e2b Sandbox:
+  - **Sandbox tool**: New `Sandbox` built-in tool — run code in an isolated e2b cloud VM. See [Built-in Standard Tools](#built-in-standard-tools).
 - **2026-04-22 | v0.3.2** - Built-in standard tools:
   - **Built-in standard tools**: 7 atomic-level tools now ship with chak — `Bash`, `Python`, `FileSystem`, `Web`, `Search`, `Http`, `Pdf`. Drop them directly into `tools=[]` to give any agent baseline capabilities. See [Built-in Standard Tools](#built-in-standard-tools).
 - **2026-04-08 | v0.3.1** - Human-in-the-Loop upgrade & built-in execution tools:
@@ -268,6 +270,9 @@ OpenAI, Google Gemini, Azure OpenAI, Anthropic Claude, Alibaba Bailian, Baidu We
 # Basic installation (SDK only)
 pip install chakpy
 
+# With built-in standard tools (Pdf, Web, Search, Sandbox)
+pip install chakpy[tools]
+
 # With server support
 pip install chakpy[server]
 
@@ -275,6 +280,13 @@ pip install chakpy[server]
 pip install chakpy[all]
 ```
 
+| Extra | What it installs |
+|-------|------------------|
+| `tools` | pymupdf4llm, beautifulsoup4, readability-lxml, ddgs, e2b (and optional API clients for Firecrawl/Tavily) |
+| `server` | fastapi, uvicorn, websockets, pyyaml |
+| `web` | beautifulsoup4, readability-lxml, firecrawl-py, tavily-python, ddgs |
+| `all` | everything above |
+
 ### Chat with global models in a few lines
 
 ```python
@@ -541,10 +553,12 @@ See full example: [examples/tool_calling_claude_skill.py](examples/tool_calling_
 
 ### Built-in Standard Tools
 
-chak ships 7 atomic tools that cover the most common agent needs out of the box. Import and pass them directly — no wrapping, no configuration required.
+chak ships 8 atomic tools that cover the most common agent needs out of the box. Import and pass them directly — no wrapping, no configuration required.
+
+> Tools with optional dependencies require `pip install chakpy[tools]` (or install individual packages as needed — each tool prints an actionable `pip install` message if a dependency is missing).
 
 ```python
-from chak.tools.std import Bash, Python, FileSystem, Web, Search, Http, Pdf
+from chak.tools.std import Bash, Python, FileSystem, Web, Search, Http, Pdf, Sandbox
 
 conv = chak.Conversation(
     "openai/gpt-4o",
@@ -555,18 +569,21 @@ conv = chak.Conversation(
 response = await conv.asend("Search for the latest Python release, then save a summary to ./notes.txt")
 ```
 
-| Tool | Class | What it does |
-|------|-------|--------------|
-| Shell | `Bash` | Run any shell command. Cross-platform (PowerShell on Windows, bash on Unix). |
-| Code Interpreter | `Python` | Write and run Python code snippets in the active venv. |
-| File System | `FileSystem` | Read, write, edit, list, search, and delete files and directories. |
-| Web | `Web` | Fetch and parse web pages into clean text (Firecrawl → Jina → httpx fallback). |
-| Search | `Search` | Search the web and return structured results (Tavily → Brave → DuckDuckGo fallback). |
-| HTTP Client | `Http` | Full HTTP client — GET, POST, PUT, PATCH, DELETE with headers and body. |
-| PDF | `Pdf` | Extract text and tables from PDF files (local path or URL). |
+| Tool | Class | What it does | Optional deps |
+|------|-------|--------------|---------------|
+| Shell | `Bash` | Run any shell command. Cross-platform (PowerShell on Windows, bash on Unix). | — |
+| Code Interpreter | `Python` | Write and run Python code snippets in the active venv. | — |
+| File System | `FileSystem` | Read, write, edit, list, search, and delete files and directories. | — |
+| HTTP Client | `Http` | Full HTTP client — GET, POST, PUT, PATCH, DELETE with headers and body. | — |
+| Web | `Web` | Fetch and parse web pages into clean text (Firecrawl → Jina → httpx fallback). | `firecrawl-py` (Layer 1, needs API key), `beautifulsoup4`, `readability-lxml` |
+| Search | `Search` | Search the web and return structured results (Tavily → Brave → DuckDuckGo fallback). | `ddgs`, `tavily-python` |
+| PDF | `Pdf` | Extract text and tables from PDF files (local path or URL). | `pymupdf4llm` |
+| Sandbox | `Sandbox` | Run multi-file code projects in an isolated e2b cloud sandbox. Supports any language reachable from bash. | `e2b`, `E2B_API_KEY` |
 
 These tools are intentionally minimal and composable. Combine them freely or mix with your own custom tools.
 
+See [`examples/tool_calling_std.py`](examples/tool_calling_std.py) for a runnable demo of every tool, including an `all` mode that runs them all in sequence.
+
 > ⚠️ **Security**: `Bash` and `Python` execute with host-process permissions. For production deployments, use `hitl_handler` for human approval, or run inside a sandboxed environment. `Bash` supports `deny_patterns`, `sensitive_files`, and `working_dir` parameters for fine-grained access control.
 
 ### Pass Functions

{chakpy-0.3.2 → chakpy-0.3.4}/chak/__init__.py

@@ -16,7 +16,11 @@ Example:
 >>> conv = chak.Conversation('deepseek@https://custom.api.com:deepseek-chat', api_key='xxx')
 """
 
-__version__ = "0.3.2"
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    __version__ = version("chakpy")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"
 
 # Context handlers
 from .context.handlers import (

{chakpy-0.3.2 → chakpy-0.3.4}/chak/tools/__init__.py

@@ -59,6 +59,24 @@ __all__ = [
 ]
 
 
+def _is_duck_tool(obj) -> bool:
+    """Return True if obj implements the chak duck-typed tool interface.
+
+    A duck-typed tool must have:
+    - ``name``: a str property or attribute
+    - ``to_openai_tool``: a callable that returns the OpenAI schema dict
+    - ``call``: an async callable that executes the tool
+    """
+    name_ok = isinstance(getattr(obj, 'name', None), str) or isinstance(
+        getattr(type(obj), 'name', None), property
+    )
+    return (
+        name_ok
+        and callable(getattr(obj, 'to_openai_tool', None))
+        and callable(getattr(obj, 'call', None))
+    )
+
+
 def wrap_tools(tools: List[ToolLike]) -> List:
     """
     自动包装工具列表
@@ -116,8 +134,12 @@ def wrap_tools(tools: List[ToolLike]) -> List:
     """
     wrapped = []
     for tool in tools:
-        if isinstance(tool, (MCPTool, NativeFunctionTool, NativeObjectTool, SkillObjectTool, ClaudeSkill, Bash, Python)):
-            # 已经是工具对象，直接使用
+        if isinstance(tool, (MCPTool, NativeFunctionTool, NativeObjectTool, SkillObjectTool, ClaudeSkill)):
+            # Already a fully-wrapped tool object, use as-is
+            wrapped.append(tool)
+        elif _is_duck_tool(tool):
+            # Duck-typed tool: has name/to_openai_tool/call — treat as direct tool
+            # (e.g. Bash, Python, Sandbox, or any custom std tool)
             wrapped.append(tool)
         elif isinstance(tool, SkillBase):
             # 是 Skill 实例，包装成 SkillObjectTool

{chakpy-0.3.2 → chakpy-0.3.4}/chak/tools/manager.py

@@ -967,7 +967,8 @@ class ToolManager:
                 # Construct final AIMessage from accumulated content, preserving LLM usage metadata
                 final_message = AIMessage(
                     content=accumulated_content,
-                    metadata=_dict_to_metadata(last_metadata)
+                    metadata=_dict_to_metadata(last_metadata),
+                    attachments=all_attachments,
                 )
                 new_messages.append(final_message)
                 

{chakpy-0.3.2 → chakpy-0.3.4}/chak/tools/std/__init__.py

@@ -10,6 +10,7 @@ All first-party atomic tools that ship with chak live here:
   - Search:     search the web (Tavily → Brave → DuckDuckGo fallback)
   - Http:       full HTTP client (GET/POST/PUT/PATCH/DELETE)
   - Pdf:        extract text/tables from PDF files (local path or URL)
+  - Sandbox:    execute multi-file code projects in an isolated e2b cloud sandbox
 """
 
 from .bash import Bash
@@ -19,5 +20,6 @@ from .web import Web
 from .search import Search
 from .http import Http
 from .pdf import Pdf
+from .sandbox import Sandbox
 
-__all__ = ["Bash", "Python", "FileSystem", "Web", "Search", "Http", "Pdf"]
+__all__ = ["Bash", "Python", "FileSystem", "Web", "Search", "Http", "Pdf", "Sandbox"]

chakpy-0.3.4/chak/tools/std/sandbox.py

@@ -0,0 +1,190 @@
+"""
+Sandbox: Built-in e2b cloud sandbox execution tool for chak
+
+Executes code in an isolated e2b cloud sandbox (pure shell mode via e2b.Sandbox).
+One-shot design: spin up → write files → run shell script → return output → destroy.
+
+Usage:
+    from chak.tools.std import Sandbox
+
+    sb = Sandbox()
+    conv = Conversation(model, tools=[sb])
+
+Requires:
+    e2b package (pip install e2b)
+    E2B_API_KEY environment variable (or api_key passed to constructor)
+"""
+
+import asyncio
+import os
+from typing import Any, Dict, List, Optional
+
+
+class Sandbox:
+    """Built-in e2b cloud sandbox execution tool.
+
+    Writes source files into an isolated cloud sandbox, then runs a bash
+    shell script that controls the full execution sequence (install packages,
+    run code, etc.).  The sandbox is created fresh for each call and
+    destroyed afterwards.
+
+    Example::
+
+        sb = Sandbox()
+        result = await sb.call({
+            "shell_script": "pip install httpx -q\\npython /project/main.py",
+            "files": [{"path": "/project/main.py", "content": "import httpx; print(httpx.get('https://example.com').status_code)"}]
+        })
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        timeout: int = 120,
+    ):
+        """
+        Args:
+            api_key: E2B API key.  Falls back to the ``E2B_API_KEY``
+                     environment variable when not provided.
+            timeout: Maximum seconds to wait for the shell script to finish.
+                     Defaults to 120.
+        """
+        self._api_key = api_key or os.getenv("E2B_API_KEY")
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Duck-typing interface required by ToolManager
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        """Tool name exposed to the LLM."""
+        return "sandbox"
+
+    @property
+    def description(self) -> str:
+        """Short description shown to the LLM."""
+        return (
+            "Execute code in an isolated cloud sandbox and return its output. "
+            "IMPORTANT: Call this tool EXACTLY ONCE per task — never in parallel or sequentially. "
+            "Each call creates a completely fresh environment; files do NOT persist between calls. "
+            "The entire pipeline (install packages, write files, run code) must be done in a single call. "
+            "Write all source files via 'files', then run a bash shell script via 'shell_script'. "
+            "Supports any language reachable from bash (Python, Node, Ruby, etc.)."
+        )
+
+    def to_openai_tool(self) -> Dict[str, Any]:
+        """Return the OpenAI function-calling schema for this tool."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "shell_script": {
+                            "type": "string",
+                            "description": (
+                                "Bash shell script to execute inside the sandbox. "
+                                "Each line is a shell command — install packages, "
+                                "create directories, run code, etc. "
+                                "All lines share the same bash session. "
+                                "Example: \"pip install httpx -q\\npython /project/main.py\""
+                            ),
+                        },
+                        "files": {
+                            "type": "array",
+                            "description": (
+                                "Source files to write into the sandbox before "
+                                "the shell script runs. "
+                                "Provide the full content of each file here — "
+                                "do NOT use heredocs in shell_script for large files."
+                            ),
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "path": {
+                                        "type": "string",
+                                        "description": "Absolute path inside the sandbox, e.g. /project/main.py",
+                                    },
+                                    "content": {
+                                        "type": "string",
+                                        "description": "Full source code content of the file.",
+                                    },
+                                },
+                                "required": ["path", "content"],
+                            },
+                        },
+                    },
+                    "required": ["shell_script"],
+                },
+            },
+        }
+
+    async def call(self, arguments: Dict[str, Any], **kwargs) -> str:
+        """Execute the sandbox task asynchronously.
+
+        Args:
+            arguments: Dict with ``shell_script`` (required) and optionally
+                       ``files`` (list of ``{path, content}`` dicts).
+            **kwargs: Ignored (present for interface compatibility).
+
+        Returns:
+            Combined stdout + stderr output, or an error string on failure.
+        """
+        shell_script: str = arguments.get("shell_script", "").strip()
+        files: List[Dict[str, str]] = arguments.get("files") or []
+
+        return await asyncio.to_thread(self._run, shell_script, files)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _run(self, shell_script: str, files: List[Dict[str, str]]) -> str:
+        """Spin up sandbox, write files, run shell script.
+
+        Called from a worker thread via :func:`asyncio.to_thread`.
+        """
+        try:
+            from e2b import Sandbox as E2BSandbox  # pyright: ignore[reportMissingTypeStubs]
+        except ImportError:
+            return "Error: 'e2b' package is not installed. Run: pip install e2b"
+
+        if not self._api_key:
+            return (
+                "Error: E2B API key not found. "
+                "Set E2B_API_KEY environment variable or pass api_key to Sandbox()."
+            )
+
+        try:
+            with E2BSandbox.create(api_key=self._api_key) as sbx:
+                # 1. Write source files
+                for f in files:
+                    path = f.get("path", "")
+                    content = f.get("content", "")
+                    if path:
+                        sbx.files.write(path, content)  # pyright: ignore[reportUnknownMemberType]
+
+                # 2. Write the shell script to a file and execute via bash
+                sbx.files.write(  # pyright: ignore[reportUnknownMemberType]
+                    "/tmp/_chak_script.sh",
+                    "#!/bin/bash\nset -e\n" + shell_script,
+                )
+                result = sbx.commands.run(
+                    "bash /tmp/_chak_script.sh",
+                    timeout=self._timeout,
+                )
+
+                output = result.stdout or ""
+                if result.stderr:
+                    output += "\n[stderr]\n" + result.stderr
+                return output.strip() or "(no output)"
+
+        except Exception as exc:
+            return f"Error running sandbox: {exc}"
+
+    def __repr__(self) -> str:
+        key = "set" if self._api_key else "missing"
+        return f"<Sandbox api_key={key} timeout={self._timeout}>"

{chakpy-0.3.2 → chakpy-0.3.4}/chak/tools/std/search.py

@@ -128,25 +128,40 @@ class Search:
                 return "Error: query must not be empty"
 
             n = int(max_results) if max_results is not None else self._max_results
+            failures: list[str] = []
 
             # Layer 1: Tavily (AI-optimized, best for agent use)
             if self._tavily_key:
                 results = await asyncio.to_thread(self._search_tavily, query, n)
                 if results:
                     return self._format(results)
+                failures.append("Tavily: failed (check API key or network)")
+            else:
+                failures.append("Tavily: skipped (no tavily_key provided)")
 
             # Layer 2: Brave Search (paid, high quality)
             if self._brave_key:
                 results = await self._search_brave(query, n)
                 if results:
                     return self._format(results)
+                failures.append("Brave: failed (check API key or network)")
+            else:
+                failures.append("Brave: skipped (no brave_key provided)")
 
             # Layer 3: DuckDuckGo (free, no key)
-            results = await self._search_ddgs(query, n)
+            results, ddgs_err = await self._search_ddgs(query, n)
             if results:
                 return self._format(results)
+            failures.append(f"DuckDuckGo: {ddgs_err}")
 
-            return f"Error: all search backends failed for query: {query!r}"
+            detail = "; ".join(failures)
+            return (
+                f"Error: all search backends failed for query: {query!r}. "
+                f"Reasons: {detail}. "
+                f"To fix: install at least one backend — "
+                f"`pip install ddgs` (free, no key needed) or "
+                f"`pip install tavily-python` (requires TAVILY_API_KEY)."
+            )
 
         except Exception as e:
             return f"Error searching for {query!r}: {e}"
@@ -213,8 +228,15 @@ class Search:
             ))
         return results or None
 
-    async def _search_ddgs(self, query: str, n: int) -> Optional[List[SearchResult]]:
-        """Query DuckDuckGo via duckduckgo-search (ddgs) library."""
+    async def _search_ddgs(
+        self, query: str, n: int
+    ) -> tuple[Optional[List[SearchResult]], str]:
+        """Query DuckDuckGo via duckduckgo-search (ddgs) library.
+
+        Returns:
+            (results, error_msg) — results is None on failure;
+            error_msg describes the failure reason.
+        """
         try:
             from ddgs import DDGS
 
@@ -230,9 +252,9 @@ class Search:
 
             items = await asyncio.to_thread(_run)
         except ImportError:
-            return None  # duckduckgo-search not installed
-        except Exception:
-            return None
+            return None, "package not installed — run `pip install ddgs`"
+        except Exception as e:
+            return None, f"runtime error: {e}"
 
         results = []
         for item in items[:n]:
@@ -241,7 +263,7 @@ class Search:
                 url=item.get("href", item.get("url", "")),
                 snippet=item.get("body", ""),
             ))
-        return results or None
+        return (results or None), "no results returned"
 
     def __repr__(self) -> str:
         tv = "yes" if self._tavily_key else "no"