Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1,35 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Modules/AI_Web_Search.py

@@ -0,0 +1,158 @@
+"""
+AI Web Search Module.
+
+AI-powered web search using Pollinations API with Perplexity and Gemini models.
+Query optimization is ALWAYS enabled for best results.
+
+Depth levels:
+- fast: Gemini with Google Search - Quick, reliable answers
+- normal: Perplexity Sonar - Balanced speed and quality
+- deep: Perplexity Sonar Reasoning - Deep analysis with reasoning chain
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+import gradio as gr
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+from ._pollinations_client import PollinationsClient
+from ._query_optimizer import get_optimizer
+
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "AI-powered web search using Perplexity or Gemini with built-in web search. "
+    "Returns synthesized answers with source citations. "
+    "Use for complex questions requiring current information and analysis. "
+    "Query optimization is automatically applied for best results."
+)
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def AI_Web_Search(
+    query: Annotated[str, "The search query or question."],
+    depth: Annotated[
+        Literal["fast", "normal", "deep"],
+        "Search depth: 'fast' (Gemini + Google Search), 'normal' (Perplexity Sonar), 'deep' (Perplexity Sonar Reasoning).",
+    ] = "normal",
+    detailed: Annotated[bool, "Request a comprehensive answer with more detail."] = False,
+) -> str:
+    """
+    AI-powered web search with automatic query optimization.
+
+    Uses Pollinations API to access AI search models with built-in web search:
+    - fast: Gemini with Google Search - Best for quick facts
+    - normal: Perplexity Sonar - Balanced for general research
+    - deep: Perplexity Sonar Reasoning - Best for complex analysis
+
+    Query optimization is ALWAYS ON - queries are automatically optimized
+    for AI search using SC-CoT (Mistral → HF fallback chain).
+
+    Returns a synthesized answer with numbered citations and source URLs.
+    """
+    _log_call_start("AI_Web_Search", query=query, depth=depth, detailed=detailed)
+
+    if not query or not query.strip():
+        result = "No search query provided. Please enter a question or search term."
+        _log_call_end("AI_Web_Search", _truncate_for_log(result))
+        return result
+
+    # ALWAYS optimize the query for AI search
+    original_query = query
+    optimization_metadata = None
+    try:
+        optimizer = get_optimizer()
+        query, optimization_metadata = optimizer.optimize_for_ai_search(query)
+    except Exception as exc:
+        print(f"[AI_Web_Search] Query optimization failed: {exc}", flush=True)
+        # Continue with original query
+
+    try:
+        client = PollinationsClient()
+        result_data = client.web_search_sync(query, depth, detailed)
+
+        # Build output
+        lines = []
+
+        # Add optimization info if available
+        if optimization_metadata and optimization_metadata.get("original_query") != optimization_metadata.get("optimized_query"):
+            lines.append(f"Optimized query: {query}")
+            lines.append(f"Original query: {original_query}")
+            lines.append(f"Optimizer: {optimization_metadata.get('provider', 'unknown')}")
+            lines.append("")
+
+        lines.append(f"Query: {result_data['query']}")
+        lines.append(f"Model: {result_data['model']}")
+        lines.append(f"Depth: {depth}")
+        lines.append("")
+        lines.append("Answer:")
+        lines.append(result_data["answer"] or "No answer generated.")
+
+        if result_data["sources"]:
+            lines.append("")
+            lines.append("Sources:")
+            for i, source in enumerate(result_data["sources"], 1):
+                lines.append(f"  {i}. {source}")
+        else:
+            lines.append("")
+            lines.append("(No sources provided)")
+
+        result = "\n".join(lines)
+        _log_call_end("AI_Web_Search", _truncate_for_log(result))
+        return result
+
+    except Exception as exc:
+        error_msg = f"Search failed: {exc}"
+        _log_call_end("AI_Web_Search", error_msg)
+        return error_msg
+
+
+def build_interface() -> gr.Interface:
+    """Build the Gradio interface for AI Web Search."""
+    return gr.Interface(
+        fn=AI_Web_Search,
+        inputs=[
+            gr.Textbox(
+                label="Query",
+                placeholder="Ask a question or enter a search topic...",
+                max_lines=3,
+                info="Your question or search query (will be optimized automatically)",
+            ),
+            gr.Radio(
+                label="Search Depth",
+                choices=["fast", "normal", "deep"],
+                value="normal",
+                info="fast: Gemini + Google Search | normal: Perplexity Sonar | deep: Perplexity Reasoning",
+            ),
+            gr.Checkbox(
+                label="Detailed Answer",
+                value=False,
+                info="Request a comprehensive answer with more detail",
+            ),
+        ],
+        outputs=gr.Textbox(
+            label="AI Search Results",
+            interactive=False,
+            lines=20,
+            max_lines=30,
+        ),
+        title="AI Web Search",
+        description=(
+            "<div style='text-align:center'>"
+            "AI-powered web search with automatic query optimization. "
+            "Uses Perplexity Sonar or Gemini with built-in web search to provide "
+            "direct answers with source citations. Query optimization is always enabled."
+            "</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Search",
+    )
+
+
+__all__ = ["AI_Web_Search", "build_interface"]

Modules/Agent_Skills.py

@@ -1,788 +1,788 @@
-from __future__ import annotations
-
-"""
-Agent Skills Module for Nymbo-Tools MCP Server.
-
-Provides structured skill discovery, activation, validation, and resource access
-following the Agent Skills specification (https://agentskills.io).
-
-Skills are directories containing a SKILL.md file with YAML frontmatter (name, description)
-and Markdown instructions. This tool enables agents to efficiently discover and use skills
-through progressive disclosure: low-token metadata discovery, on-demand full activation,
-and targeted resource access.
-"""
-
-import json
-import os
-import re
-import unicodedata
-from pathlib import Path
-from typing import Annotated, Optional
-
-import gradio as gr
-
-from app import _log_call_end, _log_call_start, _truncate_for_log
-from ._docstrings import autodoc
-from .File_System import ROOT_DIR, _display_path
-
-
-# ---------------------------------------------------------------------------
-# Constants
-# ---------------------------------------------------------------------------
-
-SKILLS_SUBDIR = "Skills"  # Subdirectory under ROOT_DIR containing skills
-MAX_SKILL_NAME_LENGTH = 64
-MAX_DESCRIPTION_LENGTH = 1024
-MAX_COMPATIBILITY_LENGTH = 500
-
-ALLOWED_FRONTMATTER_FIELDS = {
-    "name",
-    "description",
-    "license",
-    "allowed-tools",
-    "metadata",
-    "compatibility",
-}
-
-TOOL_SUMMARY = (
-    "Discover, inspect, validate, and access Agent Skills. "
-    "Actions: discover (list all skills), info (get SKILL.md contents), "
-    "resources (list/read bundled files), validate (check format), search (find by keyword). "
-    "Skills provide structured instructions for specialized tasks. "
-    "Use in combination with the `Shell_Command` and `File_System` tools."
-)
-
-HELP_TEXT = """\
-Agent Skills — actions and usage
-
-Skills are directories containing a SKILL.md file with YAML frontmatter (name, description)
-and Markdown instructions. They live under /Skills/ in the filesystem root.
-
-Actions:
-- discover: List all available skills with their metadata (name, description, location)
-- info: Get the full contents of a specific skill's SKILL.md file
-- resources: List or read files within a skill's bundled directories (scripts/, references/, assets/)
-- validate: Check if a skill conforms to the Agent Skills specification
-- search: Find skills by keyword in name or description
-- help: Show this guide
-
-Examples:
-- Discover all skills: action="discover"
-- Get skill info: action="info", skill_name="pdf"
-- List skill resources: action="resources", skill_name="mcp-builder"
-- Read a resource: action="resources", skill_name="pdf", resource_path="references/forms.md"
-- Validate a skill: action="validate", skill_name="pdf"
-- Search for skills: action="search", query="MCP"
-"""
-
-
-# ---------------------------------------------------------------------------
-# Skills Root Resolution
-# ---------------------------------------------------------------------------
-
-def _get_skills_root() -> Path:
-    """Get the absolute path to the skills directory."""
-    skills_root = os.getenv("NYMBO_SKILLS_ROOT")
-    if skills_root and skills_root.strip():
-        return Path(skills_root.strip()).resolve()
-    return Path(ROOT_DIR) / SKILLS_SUBDIR
-
-# Import _fmt_size from shared utility instead of duplicating
-from ._core import _fmt_size
-
-
-# ---------------------------------------------------------------------------
-# YAML Frontmatter Parsing (adapted from skills_ref/parser.py)
-# ---------------------------------------------------------------------------
-
-class ParseError(Exception):
-    """Raised when SKILL.md parsing fails."""
-    pass
-
-
-class ValidationError(Exception):
-    """Raised when skill validation fails."""
-    def __init__(self, message: str, errors: list[str] | None = None):
-        super().__init__(message)
-        self.errors = errors if errors is not None else [message]
-
-
-def _parse_frontmatter(content: str) -> tuple[dict, str]:
-    """
-    Parse YAML frontmatter from SKILL.md content.
-    
-    Returns (metadata dict, markdown body).
-    Raises ParseError if frontmatter is missing or invalid.
-    """
-    if not content.startswith("---"):
-        raise ParseError("SKILL.md must start with YAML frontmatter (---)")
-    
-    parts = content.split("---", 2)
-    if len(parts) < 3:
-        raise ParseError("SKILL.md frontmatter not properly closed with ---")
-    
-    frontmatter_str = parts[1]
-    body = parts[2].strip()
-    
-    # Simple YAML parsing without external dependency
-    metadata: dict = {}
-    in_metadata_block = False
-    metadata_dict: dict = {}
-    
-    for line in frontmatter_str.strip().split("\n"):
-        if not line.strip():
-            continue
-        
-        if line.strip() == "metadata:":
-            in_metadata_block = True
-            continue
-        
-        if in_metadata_block:
-            if line.startswith("  "):
-                match = re.match(r"^\s+(\w+):\s*(.*)$", line)
-                if match:
-                    key = match.group(1).strip()
-                    value = match.group(2).strip().strip('"').strip("'")
-                    metadata_dict[key] = value
-                continue
-            else:
-                in_metadata_block = False
-                if metadata_dict:
-                    metadata["metadata"] = metadata_dict
-                    metadata_dict = {}
-        
-        match = re.match(r"^(\S+):\s*(.*)$", line)
-        if match:
-            key = match.group(1).strip()
-            value = match.group(2).strip()
-            if (value.startswith('"') and value.endswith('"')) or \
-               (value.startswith("'") and value.endswith("'")):
-                value = value[1:-1]
-            metadata[key] = value if value else ""
-    
-    if in_metadata_block and metadata_dict:
-        metadata["metadata"] = metadata_dict
-    
-    return metadata, body
-
-
-def _find_skill_md(skill_dir: Path) -> Optional[Path]:
-    """Find the SKILL.md file in a skill directory (prefers uppercase)."""
-    for name in ("SKILL.md", "skill.md"):
-        path = skill_dir / name
-        if path.exists():
-            return path
-    return None
-
-
-# ---------------------------------------------------------------------------
-# Skill Validation (adapted from skills_ref/validator.py)
-# ---------------------------------------------------------------------------
-
-def _validate_name(name: str, skill_dir: Path) -> list[str]:
-    """Validate skill name format and directory match."""
-    errors = []
-    
-    if not name or not isinstance(name, str) or not name.strip():
-        errors.append("Field 'name' must be a non-empty string")
-        return errors
-    
-    name = unicodedata.normalize("NFKC", name.strip())
-    
-    if len(name) > MAX_SKILL_NAME_LENGTH:
-        errors.append(f"Skill name '{name}' exceeds {MAX_SKILL_NAME_LENGTH} character limit ({len(name)} chars)")
-    
-    if name != name.lower():
-        errors.append(f"Skill name '{name}' must be lowercase")
-    
-    if name.startswith("-") or name.endswith("-"):
-        errors.append("Skill name cannot start or end with a hyphen")
-    
-    if "--" in name:
-        errors.append("Skill name cannot contain consecutive hyphens")
-    
-    if not all(c.isalnum() or c == "-" for c in name):
-        errors.append(f"Skill name '{name}' contains invalid characters. Only letters, digits, and hyphens allowed.")
-    
-    if skill_dir:
-        dir_name = unicodedata.normalize("NFKC", skill_dir.name)
-        if dir_name != name:
-            errors.append(f"Directory name '{skill_dir.name}' must match skill name '{name}'")
-    
-    return errors
-
-
-def _validate_description(description: str) -> list[str]:
-    """Validate description format."""
-    errors = []
-    
-    if not description or not isinstance(description, str) or not description.strip():
-        errors.append("Field 'description' must be a non-empty string")
-        return errors
-    
-    if len(description) > MAX_DESCRIPTION_LENGTH:
-        errors.append(f"Description exceeds {MAX_DESCRIPTION_LENGTH} character limit ({len(description)} chars)")
-    
-    return errors
-
-
-def _validate_compatibility(compatibility: str) -> list[str]:
-    """Validate compatibility format."""
-    errors = []
-    
-    if not isinstance(compatibility, str):
-        errors.append("Field 'compatibility' must be a string")
-        return errors
-    
-    if len(compatibility) > MAX_COMPATIBILITY_LENGTH:
-        errors.append(f"Compatibility exceeds {MAX_COMPATIBILITY_LENGTH} character limit ({len(compatibility)} chars)")
-    
-    return errors
-
-
-def _validate_skill(skill_dir: Path) -> list[str]:
-    """Validate a skill directory. Returns list of error messages (empty = valid)."""
-    if not skill_dir.exists():
-        return [f"Path does not exist: {skill_dir}"]
-    
-    if not skill_dir.is_dir():
-        return [f"Not a directory: {skill_dir}"]
-    
-    skill_md = _find_skill_md(skill_dir)
-    if skill_md is None:
-        return ["Missing required file: SKILL.md"]
-    
-    try:
-        content = skill_md.read_text(encoding="utf-8")
-        metadata, _ = _parse_frontmatter(content)
-    except ParseError as e:
-        return [str(e)]
-    except Exception as e:
-        return [f"Failed to read SKILL.md: {e}"]
-    
-    errors = []
-    
-    extra_fields = set(metadata.keys()) - ALLOWED_FRONTMATTER_FIELDS
-    if extra_fields:
-        errors.append(f"Unexpected fields in frontmatter: {', '.join(sorted(extra_fields))}")
-    
-    if "name" not in metadata:
-        errors.append("Missing required field: name")
-    else:
-        errors.extend(_validate_name(metadata["name"], skill_dir))
-    
-    if "description" not in metadata:
-        errors.append("Missing required field: description")
-    else:
-        errors.extend(_validate_description(metadata["description"]))
-    
-    if "compatibility" in metadata:
-        errors.extend(_validate_compatibility(metadata["compatibility"]))
-    
-    return errors
-
-
-# ---------------------------------------------------------------------------
-# Skill Discovery and Info
-# ---------------------------------------------------------------------------
-
-def _read_skill_properties(skill_dir: Path) -> dict:
-    """Read skill properties from SKILL.md frontmatter. Returns dict with metadata."""
-    skill_md = _find_skill_md(skill_dir)
-    if skill_md is None:
-        raise ParseError(f"SKILL.md not found in {skill_dir}")
-    
-    content = skill_md.read_text(encoding="utf-8")
-    metadata, body = _parse_frontmatter(content)
-    
-    if "name" not in metadata:
-        raise ValidationError("Missing required field: name")
-    if "description" not in metadata:
-        raise ValidationError("Missing required field: description")
-    
-    return {
-        "name": metadata.get("name", "").strip(),
-        "description": metadata.get("description", "").strip(),
-        "license": metadata.get("license"),
-        "compatibility": metadata.get("compatibility"),
-        "allowed_tools": metadata.get("allowed-tools"),
-        "metadata": metadata.get("metadata", {}),
-        "location": str(skill_md),
-        "body": body,
-    }
-
-
-def _discover_skills() -> list[dict]:
-    """Discover all valid skills in the skills directory."""
-    skills_root = _get_skills_root()
-    
-    if not skills_root.exists():
-        return []
-    
-    skills = []
-    for item in sorted(skills_root.iterdir()):
-        if not item.is_dir():
-            continue
-        
-        skill_md = _find_skill_md(item)
-        if skill_md is None:
-            continue
-        
-        try:
-            props = _read_skill_properties(item)
-            skills.append({
-                "name": props["name"],
-                "description": props["description"],
-                "location": _display_path(str(skill_md)),
-            })
-        except Exception:
-            continue
-    
-    return skills
-
-
-def _get_skill_info(skill_name: str, offset: int = 0, max_chars: int = 0) -> dict:
-    """Get full information for a specific skill."""
-    skills_root = _get_skills_root()
-    skill_dir = skills_root / skill_name
-    
-    if not skill_dir.exists():
-        raise FileNotFoundError(f"Skill not found: {skill_name}")
-    
-    skill_md = _find_skill_md(skill_dir)
-    if skill_md is None:
-        raise FileNotFoundError(f"SKILL.md not found in skill: {skill_name}")
-    
-    content = skill_md.read_text(encoding="utf-8")
-    metadata, body = _parse_frontmatter(content)
-    
-    total_chars = len(body)
-    start = max(0, min(offset, total_chars))
-    if max_chars > 0:
-        end = min(total_chars, start + max_chars)
-    else:
-        end = total_chars
-    
-    body_chunk = body[start:end]
-    truncated = end < total_chars
-    next_cursor = end if truncated else None
-    
-    return {
-        "name": metadata.get("name", "").strip(),
-        "description": metadata.get("description", "").strip(),
-        "license": metadata.get("license"),
-        "compatibility": metadata.get("compatibility"),
-        "allowed_tools": metadata.get("allowed-tools"),
-        "metadata": metadata.get("metadata", {}),
-        "location": _display_path(str(skill_md)),
-        "body": body_chunk,
-        "offset": start,
-        "total_chars": total_chars,
-        "truncated": truncated,
-        "next_cursor": next_cursor,
-    }
-
-
-def _list_skill_resources(skill_name: str) -> dict:
-    """List all resources within a skill directory.
-    
-    Dynamically discovers all subdirectories, not just predefined ones.
-    """
-    skills_root = _get_skills_root()
-    skill_dir = skills_root / skill_name
-    
-    if not skill_dir.exists():
-        raise FileNotFoundError(f"Skill not found: {skill_name}")
-    
-    resources = {
-        "skill": skill_name,
-        "directories": {},  # Dynamic: dirname -> file list
-        "other_files": [],
-    }
-    
-    for item in sorted(skill_dir.iterdir()):
-        if item.name.lower() in ("skill.md",):
-            continue
-        
-        if item.is_dir():
-            files = []
-            for f in sorted(item.rglob("*")):
-                if f.is_file():
-                    files.append({
-                        "path": f.relative_to(item).as_posix(),
-                        "size": f.stat().st_size,
-                    })
-            resources["directories"][item.name] = files
-        elif item.is_file():
-            resources["other_files"].append({
-                "path": item.name,
-                "size": item.stat().st_size,
-            })
-    
-    return resources
-
-
-def _read_skill_resource(skill_name: str, resource_path: str, offset: int = 0, max_chars: int = 3000) -> dict:
-    """Read a specific resource file from a skill."""
-    skills_root = _get_skills_root()
-    skill_dir = skills_root / skill_name
-    
-    if not skill_dir.exists():
-        raise FileNotFoundError(f"Skill not found: {skill_name}")
-    
-    resource_file = skill_dir / resource_path
-    
-    try:
-        resource_file.resolve().relative_to(skill_dir.resolve())
-    except ValueError:
-        raise PermissionError(f"Resource path escapes skill directory: {resource_path}")
-    
-    if not resource_file.exists():
-        raise FileNotFoundError(f"Resource not found: {resource_path}")
-    
-    if resource_file.is_dir():
-        raise IsADirectoryError(f"Path is a directory: {resource_path}")
-    
-    content = resource_file.read_text(encoding="utf-8", errors="replace")
-    total_chars = len(content)
-    
-    start = max(0, min(offset, total_chars))
-    if max_chars > 0:
-        end = min(total_chars, start + max_chars)
-    else:
-        end = total_chars
-        
-    chunk = content[start:end]
-    truncated = end < total_chars
-    next_cursor = end if truncated else None
-    
-    return {
-        "skill": skill_name,
-        "resource": resource_path,
-        "content": chunk,
-        "size": resource_file.stat().st_size,
-        "offset": start,
-        "total_chars": total_chars,
-        "truncated": truncated,
-        "next_cursor": next_cursor,
-    }
-
-
-def _search_skills(query: str) -> list[dict]:
-    """Search for skills by keyword in name or description."""
-    query_lower = query.lower()
-    all_skills = _discover_skills()
-    
-    matches = []
-    for skill in all_skills:
-        name_match = query_lower in skill["name"].lower()
-        desc_match = query_lower in skill["description"].lower()
-        
-        if name_match or desc_match:
-            matches.append({
-                **skill,
-                "match_in": "name" if name_match else "description",
-            })
-    
-    return matches
-
-
-# ---------------------------------------------------------------------------
-# Human-Readable Output Formatters
-# ---------------------------------------------------------------------------
-
-def _format_discover(skills: list[dict]) -> str:
-    """Format skill discovery results as human-readable text."""
-    skills_root = _display_path(str(_get_skills_root()))
-    lines = [
-        f"Available Skills",
-        f"Root: {skills_root}",
-        f"Total: {len(skills)} skills",
-        "",
-    ]
-    
-    if not skills:
-        lines.append("No skills found.")
-    else:
-        for i, skill in enumerate(skills, 1):
-            name = skill["name"]
-            desc = skill["description"]
-            # Truncate long descriptions
-            if len(desc) > 100:
-                desc = desc[:97] + "..."
-            lines.append(f"{i}. {name}")
-            lines.append(f"   {desc}")
-            lines.append("")
-    
-    return "\n".join(lines).strip()
-
-
-def _format_skill_info(info: dict) -> str:
-    """Format skill info as human-readable text."""
-    lines = [
-        f"Skill: {info['name']}",
-        f"Location: {info['location']}",
-        "",
-        f"Description: {info['description']}",
-    ]
-    
-    if info.get("license"):
-        lines.append(f"License: {info['license']}")
-    if info.get("compatibility"):
-        lines.append(f"Compatibility: {info['compatibility']}")
-    if info.get("allowed_tools"):
-        lines.append(f"Allowed Tools: {info['allowed_tools']}")
-    if info.get("metadata"):
-        meta_str = ", ".join(f"{k}={v}" for k, v in info["metadata"].items())
-        lines.append(f"Metadata: {meta_str}")
-    
-    lines.append("")
-    lines.append("--- SKILL.md Body ---")
-    if info.get("offset", 0) > 0:
-        lines.append(f"(Showing content from offset {info['offset']})")
-    lines.append("")
-    lines.append(info["body"])
-    
-    if info.get("truncated"):
-        lines.append("")
-        lines.append(f"… Truncated. Showing {len(info['body'])} chars (offset {info['offset']}). Total: {info['total_chars']}.")
-        lines.append(f"Next cursor: {info['next_cursor']}")
-    
-    return "\n".join(lines)
-
-
-def _format_resources_list(resources: dict) -> str:
-    """Format resource listing as a visual filesystem tree with line connectors."""
-    from ._core import build_tree, render_tree
-    
-    skill = resources["skill"]
-    lines = [
-        f"Resources for skill: {skill}",
-        "",
-    ]
-    
-    # Build entries list for the tree
-    entries: list[tuple[str, dict]] = []
-    
-    # Add all discovered directories and their files
-    directories = resources.get("directories", {})
-    for dirname, files in directories.items():
-        for f in files:
-            path = f"{dirname}/{f['path']}"
-            entries.append((path, {"size": f["size"]}))
-    
-    # Add root files
-    other = resources.get("other_files", [])
-    for f in other:
-        entries.append((f["path"], {"size": f["size"]}))
-    
-    # Build and render the unified tree
-    tree = build_tree(entries)
-    
-    # Count files
-    total_files = len(entries)
-    
-    # Render with skill as root
-    lines.append(f"└── {skill}/")
-    lines.extend(render_tree(tree, "    "))
-    
-    lines.append("")
-    if total_files == 0:
-        lines.append("No resource files found.")
-    else:
-        lines.append(f"Total: {total_files} files")
-    
-    return "\n".join(lines).strip()
-
-
-def _format_resource_content(data: dict) -> str:
-    """Format resource file content as human-readable text."""
-    lines = [
-        f"Resource: {data['resource']}",
-        f"Skill: {data['skill']}",
-        f"Size: {_fmt_size(data['size'])}",
-    ]
-    
-    offset = data.get("offset", 0)
-    lines.append(f"Showing: {len(data['content'])} of {data['total_chars']} chars (offset {offset})")
-    
-    lines.append("")
-    lines.append("--- Content ---")
-    lines.append("")
-    lines.append(data["content"])
-    
-    if data.get("truncated"):
-        lines.append("")
-        lines.append(f"… Truncated. Next cursor: {data['next_cursor']}")
-    
-    return "\n".join(lines)
-
-
-def _format_validation(skill_name: str, errors: list[str]) -> str:
-    """Format validation results as human-readable text."""
-    if not errors:
-        return f"✓ Skill '{skill_name}' is valid."
-    
-    lines = [
-        f"✗ Validation failed for skill '{skill_name}'",
-        f"Errors: {len(errors)}",
-        "",
-    ]
-    
-    for i, err in enumerate(errors, 1):
-        lines.append(f"  {i}. {err}")
-    
-    return "\n".join(lines)
-
-
-def _format_search(query: str, matches: list[dict]) -> str:
-    """Format search results as human-readable text."""
-    lines = [
-        f"Search results for: {query}",
-        f"Matches: {len(matches)}",
-        "",
-    ]
-    
-    if not matches:
-        lines.append("No matching skills found.")
-    else:
-        for i, m in enumerate(matches, 1):
-            name = m["name"]
-            desc = m["description"]
-            match_in = m.get("match_in", "")
-            if len(desc) > 80:
-                desc = desc[:77] + "..."
-            lines.append(f"{i}. {name}  (matched in {match_in})")
-            lines.append(f"   {desc}")
-            lines.append("")
-    
-    return "\n".join(lines).strip()
-
-
-def _format_error(message: str, hint: str = "") -> str:
-    """Format error as human-readable text."""
-    lines = [f"Error: {message}"]
-    if hint:
-        lines.append(f"Hint: {hint}")
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# Main Tool Function
-# ---------------------------------------------------------------------------
-
-@autodoc(summary=TOOL_SUMMARY)
-def Agent_Skills(
-    action: Annotated[str, "Operation: 'discover', 'info', 'resources', 'validate', 'search', 'help'."],
-    skill_name: Annotated[Optional[str], "Name of skill (required for info/resources/validate)."] = None,
-    resource_path: Annotated[Optional[str], "Path to resource file within skill (for resources action)."] = None,
-    query: Annotated[Optional[str], "Search query (for search action)."] = None,
-    max_chars: Annotated[int, "Max characters to return for skill body or resource content (0 = no limit)."] = 3000,
-    offset: Annotated[int, "Start offset for reading content (for info/resources)."] = 0,
-) -> str:
-    _log_call_start("Agent_Skills", action=action, skill_name=skill_name, resource_path=resource_path, query=query, max_chars=max_chars, offset=offset)
-    
-    action = (action or "").strip().lower()
-    
-    if action not in {"discover", "info", "resources", "validate", "search", "help"}:
-        result = _format_error(
-            f"Invalid action: {action}",
-            "Choose from: discover, info, resources, validate, search, help."
-        )
-        _log_call_end("Agent_Skills", _truncate_for_log(result))
-        return result
-    
-    try:
-        if action == "help":
-            result = HELP_TEXT
-        
-        elif action == "discover":
-            skills = _discover_skills()
-            result = _format_discover(skills)
-        
-        elif action == "info":
-            if not skill_name:
-                result = _format_error("skill_name is required for 'info' action.")
-            else:
-                info = _get_skill_info(skill_name.strip(), offset=offset, max_chars=max_chars)
-                result = _format_skill_info(info)
-        
-        elif action == "resources":
-            if not skill_name:
-                result = _format_error("skill_name is required for 'resources' action.")
-            elif resource_path:
-                resource_data = _read_skill_resource(skill_name.strip(), resource_path.strip(), offset=offset, max_chars=max_chars)
-                result = _format_resource_content(resource_data)
-            else:
-                resources = _list_skill_resources(skill_name.strip())
-                result = _format_resources_list(resources)
-        
-        elif action == "validate":
-            if not skill_name:
-                result = _format_error("skill_name is required for 'validate' action.")
-            else:
-                skills_root = _get_skills_root()
-                skill_dir = skills_root / skill_name.strip()
-                errors = _validate_skill(skill_dir)
-                result = _format_validation(skill_name, errors)
-        
-        elif action == "search":
-            if not query:
-                result = _format_error("query is required for 'search' action.")
-            else:
-                matches = _search_skills(query.strip())
-                result = _format_search(query, matches)
-        
-        else:
-            result = _format_error(f"Action '{action}' not implemented.")
-    
-    except FileNotFoundError as e:
-        result = _format_error(str(e))
-    except PermissionError as e:
-        result = _format_error(str(e))
-    except ParseError as e:
-        result = _format_error(str(e))
-    except ValidationError as e:
-        result = _format_error(str(e))
-    except Exception as e:
-        result = _format_error(f"Unexpected error: {e}")
-    
-    _log_call_end("Agent_Skills", _truncate_for_log(result))
-    return result
-
-
-# ---------------------------------------------------------------------------
-# Gradio Interface
-# ---------------------------------------------------------------------------
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Agent_Skills,
-        inputs=[
-            gr.Radio(
-                label="Action",
-                choices=["discover", "info", "resources", "validate", "search", "help"],
-                value="help",
-                info="Operation to perform",
-            ),
-            gr.Textbox(label="Skill Name", placeholder="pdf", max_lines=1, info="Name of the skill"),
-            gr.Textbox(label="Resource Path", placeholder="references/forms.md", max_lines=1, info="Path to resource within skill"),
-            gr.Textbox(label="Search Query", placeholder="MCP", max_lines=1, info="Keyword to search for"),
-            gr.Slider(minimum=0, maximum=100000, step=500, value=3000, label="Max Chars", info="Max characters for content (0 = no limit)"),
-            gr.Slider(minimum=0, maximum=1_000_000, step=100, value=0, label="Offset", info="Start offset (Info/Resources)"),
-        ],
-        outputs=gr.Textbox(label="Result", lines=20),
-        title="Agent Skills",
-        description=(
-            "<div style=\"text-align:center; overflow:hidden;\">"
-            "Discover, inspect, and access Agent Skills. "
-            "Skills provide structured instructions and resources for specialized tasks."
-            "</div>"
-        ),
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-        submit_btn="Run",
-    )
-
-
-__all__ = ["Agent_Skills", "build_interface"]
+from __future__ import annotations
+
+"""
+Agent Skills Module for Nymbo-Tools MCP Server.
+
+Provides structured skill discovery, activation, validation, and resource access
+following the Agent Skills specification (https://agentskills.io).
+
+Skills are directories containing a SKILL.md file with YAML frontmatter (name, description)
+and Markdown instructions. This tool enables agents to efficiently discover and use skills
+through progressive disclosure: low-token metadata discovery, on-demand full activation,
+and targeted resource access.
+"""
+
+import json
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import Annotated, Optional
+
+import gradio as gr
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+from .File_System import ROOT_DIR, _display_path
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SKILLS_SUBDIR = "Skills"  # Subdirectory under ROOT_DIR containing skills
+MAX_SKILL_NAME_LENGTH = 64
+MAX_DESCRIPTION_LENGTH = 1024
+MAX_COMPATIBILITY_LENGTH = 500
+
+ALLOWED_FRONTMATTER_FIELDS = {
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+}
+
+TOOL_SUMMARY = (
+    "Discover, inspect, validate, and access Agent Skills. "
+    "Actions: discover (list all skills), info (get SKILL.md contents), "
+    "resources (list/read bundled files), validate (check format), search (find by keyword). "
+    "Skills provide structured instructions for specialized tasks. "
+    "Use in combination with the `Shell_Command` and `File_System` tools."
+)
+
+HELP_TEXT = """\
+Agent Skills — actions and usage
+
+Skills are directories containing a SKILL.md file with YAML frontmatter (name, description)
+and Markdown instructions. They live under /Skills/ in the filesystem root.
+
+Actions:
+- discover: List all available skills with their metadata (name, description, location)
+- info: Get the full contents of a specific skill's SKILL.md file
+- resources: List or read files within a skill's bundled directories (scripts/, references/, assets/)
+- validate: Check if a skill conforms to the Agent Skills specification
+- search: Find skills by keyword in name or description
+- help: Show this guide
+
+Examples:
+- Discover all skills: action="discover"
+- Get skill info: action="info", skill_name="pdf"
+- List skill resources: action="resources", skill_name="mcp-builder"
+- Read a resource: action="resources", skill_name="pdf", resource_path="references/forms.md"
+- Validate a skill: action="validate", skill_name="pdf"
+- Search for skills: action="search", query="MCP"
+"""
+
+
+# ---------------------------------------------------------------------------
+# Skills Root Resolution
+# ---------------------------------------------------------------------------
+
+def _get_skills_root() -> Path:
+    """Get the absolute path to the skills directory."""
+    skills_root = os.getenv("NYMBO_SKILLS_ROOT")
+    if skills_root and skills_root.strip():
+        return Path(skills_root.strip()).resolve()
+    return Path(ROOT_DIR) / SKILLS_SUBDIR
+
+# Import _fmt_size from shared utility instead of duplicating
+from ._core import _fmt_size
+
+
+# ---------------------------------------------------------------------------
+# YAML Frontmatter Parsing (adapted from skills_ref/parser.py)
+# ---------------------------------------------------------------------------
+
+class ParseError(Exception):
+    """Raised when SKILL.md parsing fails."""
+    pass
+
+
+class ValidationError(Exception):
+    """Raised when skill validation fails."""
+    def __init__(self, message: str, errors: list[str] | None = None):
+        super().__init__(message)
+        self.errors = errors if errors is not None else [message]
+
+
+def _parse_frontmatter(content: str) -> tuple[dict, str]:
+    """
+    Parse YAML frontmatter from SKILL.md content.
+    
+    Returns (metadata dict, markdown body).
+    Raises ParseError if frontmatter is missing or invalid.
+    """
+    if not content.startswith("---"):
+        raise ParseError("SKILL.md must start with YAML frontmatter (---)")
+    
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        raise ParseError("SKILL.md frontmatter not properly closed with ---")
+    
+    frontmatter_str = parts[1]
+    body = parts[2].strip()
+    
+    # Simple YAML parsing without external dependency
+    metadata: dict = {}
+    in_metadata_block = False
+    metadata_dict: dict = {}
+    
+    for line in frontmatter_str.strip().split("\n"):
+        if not line.strip():
+            continue
+        
+        if line.strip() == "metadata:":
+            in_metadata_block = True
+            continue
+        
+        if in_metadata_block:
+            if line.startswith("  "):
+                match = re.match(r"^\s+(\w+):\s*(.*)$", line)
+                if match:
+                    key = match.group(1).strip()
+                    value = match.group(2).strip().strip('"').strip("'")
+                    metadata_dict[key] = value
+                continue
+            else:
+                in_metadata_block = False
+                if metadata_dict:
+                    metadata["metadata"] = metadata_dict
+                    metadata_dict = {}
+        
+        match = re.match(r"^(\S+):\s*(.*)$", line)
+        if match:
+            key = match.group(1).strip()
+            value = match.group(2).strip()
+            if (value.startswith('"') and value.endswith('"')) or \
+               (value.startswith("'") and value.endswith("'")):
+                value = value[1:-1]
+            metadata[key] = value if value else ""
+    
+    if in_metadata_block and metadata_dict:
+        metadata["metadata"] = metadata_dict
+    
+    return metadata, body
+
+
+def _find_skill_md(skill_dir: Path) -> Optional[Path]:
+    """Find the SKILL.md file in a skill directory (prefers uppercase)."""
+    for name in ("SKILL.md", "skill.md"):
+        path = skill_dir / name
+        if path.exists():
+            return path
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Skill Validation (adapted from skills_ref/validator.py)
+# ---------------------------------------------------------------------------
+
+def _validate_name(name: str, skill_dir: Path) -> list[str]:
+    """Validate skill name format and directory match."""
+    errors = []
+    
+    if not name or not isinstance(name, str) or not name.strip():
+        errors.append("Field 'name' must be a non-empty string")
+        return errors
+    
+    name = unicodedata.normalize("NFKC", name.strip())
+    
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        errors.append(f"Skill name '{name}' exceeds {MAX_SKILL_NAME_LENGTH} character limit ({len(name)} chars)")
+    
+    if name != name.lower():
+        errors.append(f"Skill name '{name}' must be lowercase")
+    
+    if name.startswith("-") or name.endswith("-"):
+        errors.append("Skill name cannot start or end with a hyphen")
+    
+    if "--" in name:
+        errors.append("Skill name cannot contain consecutive hyphens")
+    
+    if not all(c.isalnum() or c == "-" for c in name):
+        errors.append(f"Skill name '{name}' contains invalid characters. Only letters, digits, and hyphens allowed.")
+    
+    if skill_dir:
+        dir_name = unicodedata.normalize("NFKC", skill_dir.name)
+        if dir_name != name:
+            errors.append(f"Directory name '{skill_dir.name}' must match skill name '{name}'")
+    
+    return errors
+
+
+def _validate_description(description: str) -> list[str]:
+    """Validate description format."""
+    errors = []
+    
+    if not description or not isinstance(description, str) or not description.strip():
+        errors.append("Field 'description' must be a non-empty string")
+        return errors
+    
+    if len(description) > MAX_DESCRIPTION_LENGTH:
+        errors.append(f"Description exceeds {MAX_DESCRIPTION_LENGTH} character limit ({len(description)} chars)")
+    
+    return errors
+
+
+def _validate_compatibility(compatibility: str) -> list[str]:
+    """Validate compatibility format."""
+    errors = []
+    
+    if not isinstance(compatibility, str):
+        errors.append("Field 'compatibility' must be a string")
+        return errors
+    
+    if len(compatibility) > MAX_COMPATIBILITY_LENGTH:
+        errors.append(f"Compatibility exceeds {MAX_COMPATIBILITY_LENGTH} character limit ({len(compatibility)} chars)")
+    
+    return errors
+
+
+def _validate_skill(skill_dir: Path) -> list[str]:
+    """Validate a skill directory. Returns list of error messages (empty = valid)."""
+    if not skill_dir.exists():
+        return [f"Path does not exist: {skill_dir}"]
+    
+    if not skill_dir.is_dir():
+        return [f"Not a directory: {skill_dir}"]
+    
+    skill_md = _find_skill_md(skill_dir)
+    if skill_md is None:
+        return ["Missing required file: SKILL.md"]
+    
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+        metadata, _ = _parse_frontmatter(content)
+    except ParseError as e:
+        return [str(e)]
+    except Exception as e:
+        return [f"Failed to read SKILL.md: {e}"]
+    
+    errors = []
+    
+    extra_fields = set(metadata.keys()) - ALLOWED_FRONTMATTER_FIELDS
+    if extra_fields:
+        errors.append(f"Unexpected fields in frontmatter: {', '.join(sorted(extra_fields))}")
+    
+    if "name" not in metadata:
+        errors.append("Missing required field: name")
+    else:
+        errors.extend(_validate_name(metadata["name"], skill_dir))
+    
+    if "description" not in metadata:
+        errors.append("Missing required field: description")
+    else:
+        errors.extend(_validate_description(metadata["description"]))
+    
+    if "compatibility" in metadata:
+        errors.extend(_validate_compatibility(metadata["compatibility"]))
+    
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# Skill Discovery and Info
+# ---------------------------------------------------------------------------
+
+def _read_skill_properties(skill_dir: Path) -> dict:
+    """Read skill properties from SKILL.md frontmatter. Returns dict with metadata."""
+    skill_md = _find_skill_md(skill_dir)
+    if skill_md is None:
+        raise ParseError(f"SKILL.md not found in {skill_dir}")
+    
+    content = skill_md.read_text(encoding="utf-8")
+    metadata, body = _parse_frontmatter(content)
+    
+    if "name" not in metadata:
+        raise ValidationError("Missing required field: name")
+    if "description" not in metadata:
+        raise ValidationError("Missing required field: description")
+    
+    return {
+        "name": metadata.get("name", "").strip(),
+        "description": metadata.get("description", "").strip(),
+        "license": metadata.get("license"),
+        "compatibility": metadata.get("compatibility"),
+        "allowed_tools": metadata.get("allowed-tools"),
+        "metadata": metadata.get("metadata", {}),
+        "location": str(skill_md),
+        "body": body,
+    }
+
+
+def _discover_skills() -> list[dict]:
+    """Discover all valid skills in the skills directory."""
+    skills_root = _get_skills_root()
+    
+    if not skills_root.exists():
+        return []
+    
+    skills = []
+    for item in sorted(skills_root.iterdir()):
+        if not item.is_dir():
+            continue
+        
+        skill_md = _find_skill_md(item)
+        if skill_md is None:
+            continue
+        
+        try:
+            props = _read_skill_properties(item)
+            skills.append({
+                "name": props["name"],
+                "description": props["description"],
+                "location": _display_path(str(skill_md)),
+            })
+        except Exception:
+            continue
+    
+    return skills
+
+
+def _get_skill_info(skill_name: str, offset: int = 0, max_chars: int = 0) -> dict:
+    """Get full information for a specific skill."""
+    skills_root = _get_skills_root()
+    skill_dir = skills_root / skill_name
+    
+    if not skill_dir.exists():
+        raise FileNotFoundError(f"Skill not found: {skill_name}")
+    
+    skill_md = _find_skill_md(skill_dir)
+    if skill_md is None:
+        raise FileNotFoundError(f"SKILL.md not found in skill: {skill_name}")
+    
+    content = skill_md.read_text(encoding="utf-8")
+    metadata, body = _parse_frontmatter(content)
+    
+    total_chars = len(body)
+    start = max(0, min(offset, total_chars))
+    if max_chars > 0:
+        end = min(total_chars, start + max_chars)
+    else:
+        end = total_chars
+    
+    body_chunk = body[start:end]
+    truncated = end < total_chars
+    next_cursor = end if truncated else None
+    
+    return {
+        "name": metadata.get("name", "").strip(),
+        "description": metadata.get("description", "").strip(),
+        "license": metadata.get("license"),
+        "compatibility": metadata.get("compatibility"),
+        "allowed_tools": metadata.get("allowed-tools"),
+        "metadata": metadata.get("metadata", {}),
+        "location": _display_path(str(skill_md)),
+        "body": body_chunk,
+        "offset": start,
+        "total_chars": total_chars,
+        "truncated": truncated,
+        "next_cursor": next_cursor,
+    }
+
+
+def _list_skill_resources(skill_name: str) -> dict:
+    """List all resources within a skill directory.
+    
+    Dynamically discovers all subdirectories, not just predefined ones.
+    """
+    skills_root = _get_skills_root()
+    skill_dir = skills_root / skill_name
+    
+    if not skill_dir.exists():
+        raise FileNotFoundError(f"Skill not found: {skill_name}")
+    
+    resources = {
+        "skill": skill_name,
+        "directories": {},  # Dynamic: dirname -> file list
+        "other_files": [],
+    }
+    
+    for item in sorted(skill_dir.iterdir()):
+        if item.name.lower() in ("skill.md",):
+            continue
+        
+        if item.is_dir():
+            files = []
+            for f in sorted(item.rglob("*")):
+                if f.is_file():
+                    files.append({
+                        "path": f.relative_to(item).as_posix(),
+                        "size": f.stat().st_size,
+                    })
+            resources["directories"][item.name] = files
+        elif item.is_file():
+            resources["other_files"].append({
+                "path": item.name,
+                "size": item.stat().st_size,
+            })
+    
+    return resources
+
+
+def _read_skill_resource(skill_name: str, resource_path: str, offset: int = 0, max_chars: int = 3000) -> dict:
+    """Read a specific resource file from a skill."""
+    skills_root = _get_skills_root()
+    skill_dir = skills_root / skill_name
+    
+    if not skill_dir.exists():
+        raise FileNotFoundError(f"Skill not found: {skill_name}")
+    
+    resource_file = skill_dir / resource_path
+    
+    try:
+        resource_file.resolve().relative_to(skill_dir.resolve())
+    except ValueError:
+        raise PermissionError(f"Resource path escapes skill directory: {resource_path}")
+    
+    if not resource_file.exists():
+        raise FileNotFoundError(f"Resource not found: {resource_path}")
+    
+    if resource_file.is_dir():
+        raise IsADirectoryError(f"Path is a directory: {resource_path}")
+    
+    content = resource_file.read_text(encoding="utf-8", errors="replace")
+    total_chars = len(content)
+    
+    start = max(0, min(offset, total_chars))
+    if max_chars > 0:
+        end = min(total_chars, start + max_chars)
+    else:
+        end = total_chars
+        
+    chunk = content[start:end]
+    truncated = end < total_chars
+    next_cursor = end if truncated else None
+    
+    return {
+        "skill": skill_name,
+        "resource": resource_path,
+        "content": chunk,
+        "size": resource_file.stat().st_size,
+        "offset": start,
+        "total_chars": total_chars,
+        "truncated": truncated,
+        "next_cursor": next_cursor,
+    }
+
+
+def _search_skills(query: str) -> list[dict]:
+    """Search for skills by keyword in name or description."""
+    query_lower = query.lower()
+    all_skills = _discover_skills()
+    
+    matches = []
+    for skill in all_skills:
+        name_match = query_lower in skill["name"].lower()
+        desc_match = query_lower in skill["description"].lower()
+        
+        if name_match or desc_match:
+            matches.append({
+                **skill,
+                "match_in": "name" if name_match else "description",
+            })
+    
+    return matches
+
+
+# ---------------------------------------------------------------------------
+# Human-Readable Output Formatters
+# ---------------------------------------------------------------------------
+
+def _format_discover(skills: list[dict]) -> str:
+    """Format skill discovery results as human-readable text."""
+    skills_root = _display_path(str(_get_skills_root()))
+    lines = [
+        f"Available Skills",
+        f"Root: {skills_root}",
+        f"Total: {len(skills)} skills",
+        "",
+    ]
+    
+    if not skills:
+        lines.append("No skills found.")
+    else:
+        for i, skill in enumerate(skills, 1):
+            name = skill["name"]
+            desc = skill["description"]
+            # Truncate long descriptions
+            if len(desc) > 100:
+                desc = desc[:97] + "..."
+            lines.append(f"{i}. {name}")
+            lines.append(f"   {desc}")
+            lines.append("")
+    
+    return "\n".join(lines).strip()
+
+
+def _format_skill_info(info: dict) -> str:
+    """Format skill info as human-readable text."""
+    lines = [
+        f"Skill: {info['name']}",
+        f"Location: {info['location']}",
+        "",
+        f"Description: {info['description']}",
+    ]
+    
+    if info.get("license"):
+        lines.append(f"License: {info['license']}")
+    if info.get("compatibility"):
+        lines.append(f"Compatibility: {info['compatibility']}")
+    if info.get("allowed_tools"):
+        lines.append(f"Allowed Tools: {info['allowed_tools']}")
+    if info.get("metadata"):
+        meta_str = ", ".join(f"{k}={v}" for k, v in info["metadata"].items())
+        lines.append(f"Metadata: {meta_str}")
+    
+    lines.append("")
+    lines.append("--- SKILL.md Body ---")
+    if info.get("offset", 0) > 0:
+        lines.append(f"(Showing content from offset {info['offset']})")
+    lines.append("")
+    lines.append(info["body"])
+    
+    if info.get("truncated"):
+        lines.append("")
+        lines.append(f"… Truncated. Showing {len(info['body'])} chars (offset {info['offset']}). Total: {info['total_chars']}.")
+        lines.append(f"Next cursor: {info['next_cursor']}")
+    
+    return "\n".join(lines)
+
+
+def _format_resources_list(resources: dict) -> str:
+    """Format resource listing as a visual filesystem tree with line connectors."""
+    from ._core import build_tree, render_tree
+    
+    skill = resources["skill"]
+    lines = [
+        f"Resources for skill: {skill}",
+        "",
+    ]
+    
+    # Build entries list for the tree
+    entries: list[tuple[str, dict]] = []
+    
+    # Add all discovered directories and their files
+    directories = resources.get("directories", {})
+    for dirname, files in directories.items():
+        for f in files:
+            path = f"{dirname}/{f['path']}"
+            entries.append((path, {"size": f["size"]}))
+    
+    # Add root files
+    other = resources.get("other_files", [])
+    for f in other:
+        entries.append((f["path"], {"size": f["size"]}))
+    
+    # Build and render the unified tree
+    tree = build_tree(entries)
+    
+    # Count files
+    total_files = len(entries)
+    
+    # Render with skill as root
+    lines.append(f"└── {skill}/")
+    lines.extend(render_tree(tree, "    "))
+    
+    lines.append("")
+    if total_files == 0:
+        lines.append("No resource files found.")
+    else:
+        lines.append(f"Total: {total_files} files")
+    
+    return "\n".join(lines).strip()
+
+
+def _format_resource_content(data: dict) -> str:
+    """Format resource file content as human-readable text."""
+    lines = [
+        f"Resource: {data['resource']}",
+        f"Skill: {data['skill']}",
+        f"Size: {_fmt_size(data['size'])}",
+    ]
+    
+    offset = data.get("offset", 0)
+    lines.append(f"Showing: {len(data['content'])} of {data['total_chars']} chars (offset {offset})")
+    
+    lines.append("")
+    lines.append("--- Content ---")
+    lines.append("")
+    lines.append(data["content"])
+    
+    if data.get("truncated"):
+        lines.append("")
+        lines.append(f"… Truncated. Next cursor: {data['next_cursor']}")
+    
+    return "\n".join(lines)
+
+
+def _format_validation(skill_name: str, errors: list[str]) -> str:
+    """Format validation results as human-readable text."""
+    if not errors:
+        return f"✓ Skill '{skill_name}' is valid."
+    
+    lines = [
+        f"✗ Validation failed for skill '{skill_name}'",
+        f"Errors: {len(errors)}",
+        "",
+    ]
+    
+    for i, err in enumerate(errors, 1):
+        lines.append(f"  {i}. {err}")
+    
+    return "\n".join(lines)
+
+
+def _format_search(query: str, matches: list[dict]) -> str:
+    """Format search results as human-readable text."""
+    lines = [
+        f"Search results for: {query}",
+        f"Matches: {len(matches)}",
+        "",
+    ]
+    
+    if not matches:
+        lines.append("No matching skills found.")
+    else:
+        for i, m in enumerate(matches, 1):
+            name = m["name"]
+            desc = m["description"]
+            match_in = m.get("match_in", "")
+            if len(desc) > 80:
+                desc = desc[:77] + "..."
+            lines.append(f"{i}. {name}  (matched in {match_in})")
+            lines.append(f"   {desc}")
+            lines.append("")
+    
+    return "\n".join(lines).strip()
+
+
+def _format_error(message: str, hint: str = "") -> str:
+    """Format error as human-readable text."""
+    lines = [f"Error: {message}"]
+    if hint:
+        lines.append(f"Hint: {hint}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Main Tool Function
+# ---------------------------------------------------------------------------
+
+@autodoc(summary=TOOL_SUMMARY)
+def Agent_Skills(
+    action: Annotated[str, "Operation: 'discover', 'info', 'resources', 'validate', 'search', 'help'."],
+    skill_name: Annotated[Optional[str], "Name of skill (required for info/resources/validate)."] = None,
+    resource_path: Annotated[Optional[str], "Path to resource file within skill (for resources action)."] = None,
+    query: Annotated[Optional[str], "Search query (for search action)."] = None,
+    max_chars: Annotated[int, "Max characters to return for skill body or resource content (0 = no limit)."] = 3000,
+    offset: Annotated[int, "Start offset for reading content (for info/resources)."] = 0,
+) -> str:
+    _log_call_start("Agent_Skills", action=action, skill_name=skill_name, resource_path=resource_path, query=query, max_chars=max_chars, offset=offset)
+    
+    action = (action or "").strip().lower()
+    
+    if action not in {"discover", "info", "resources", "validate", "search", "help"}:
+        result = _format_error(
+            f"Invalid action: {action}",
+            "Choose from: discover, info, resources, validate, search, help."
+        )
+        _log_call_end("Agent_Skills", _truncate_for_log(result))
+        return result
+    
+    try:
+        if action == "help":
+            result = HELP_TEXT
+        
+        elif action == "discover":
+            skills = _discover_skills()
+            result = _format_discover(skills)
+        
+        elif action == "info":
+            if not skill_name:
+                result = _format_error("skill_name is required for 'info' action.")
+            else:
+                info = _get_skill_info(skill_name.strip(), offset=offset, max_chars=max_chars)
+                result = _format_skill_info(info)
+        
+        elif action == "resources":
+            if not skill_name:
+                result = _format_error("skill_name is required for 'resources' action.")
+            elif resource_path:
+                resource_data = _read_skill_resource(skill_name.strip(), resource_path.strip(), offset=offset, max_chars=max_chars)
+                result = _format_resource_content(resource_data)
+            else:
+                resources = _list_skill_resources(skill_name.strip())
+                result = _format_resources_list(resources)
+        
+        elif action == "validate":
+            if not skill_name:
+                result = _format_error("skill_name is required for 'validate' action.")
+            else:
+                skills_root = _get_skills_root()
+                skill_dir = skills_root / skill_name.strip()
+                errors = _validate_skill(skill_dir)
+                result = _format_validation(skill_name, errors)
+        
+        elif action == "search":
+            if not query:
+                result = _format_error("query is required for 'search' action.")
+            else:
+                matches = _search_skills(query.strip())
+                result = _format_search(query, matches)
+        
+        else:
+            result = _format_error(f"Action '{action}' not implemented.")
+    
+    except FileNotFoundError as e:
+        result = _format_error(str(e))
+    except PermissionError as e:
+        result = _format_error(str(e))
+    except ParseError as e:
+        result = _format_error(str(e))
+    except ValidationError as e:
+        result = _format_error(str(e))
+    except Exception as e:
+        result = _format_error(f"Unexpected error: {e}")
+    
+    _log_call_end("Agent_Skills", _truncate_for_log(result))
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Gradio Interface
+# ---------------------------------------------------------------------------
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Agent_Skills,
+        inputs=[
+            gr.Radio(
+                label="Action",
+                choices=["discover", "info", "resources", "validate", "search", "help"],
+                value="help",
+                info="Operation to perform",
+            ),
+            gr.Textbox(label="Skill Name", placeholder="pdf", max_lines=1, info="Name of the skill"),
+            gr.Textbox(label="Resource Path", placeholder="references/forms.md", max_lines=1, info="Path to resource within skill"),
+            gr.Textbox(label="Search Query", placeholder="MCP", max_lines=1, info="Keyword to search for"),
+            gr.Slider(minimum=0, maximum=100000, step=500, value=3000, label="Max Chars", info="Max characters for content (0 = no limit)"),
+            gr.Slider(minimum=0, maximum=1_000_000, step=100, value=0, label="Offset", info="Start offset (Info/Resources)"),
+        ],
+        outputs=gr.Textbox(label="Result", lines=20),
+        title="Agent Skills",
+        description=(
+            "<div style=\"text-align:center; overflow:hidden;\">"
+            "Discover, inspect, and access Agent Skills. "
+            "Skills provide structured instructions and resources for specialized tasks."
+            "</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Run",
+    )
+
+
+__all__ = ["Agent_Skills", "build_interface"]

Modules/Agent_Terminal.py

@@ -1,159 +1,135 @@
-from __future__ import annotations
-
+from __future__ import annotations
+
 import sys
 import types
 import inspect
 import functools
 from typing import Annotated, get_type_hints, get_origin, get_args
-
-import gradio as gr
-from ._docstrings import autodoc
-from ._core import sandboxed_exec
-
-from app import _log_call_end, _log_call_start, _truncate_for_log
-
+
+import gradio as gr
+from ._docstrings import autodoc
+from ._core import sandboxed_exec
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+
 # NOTE: Tool imports are deferred to _get_tools_map() to avoid circular imports
-# (app.py imports Agent_Terminal, which would import File_System before it's fully loaded)
-
-
-# Example usages for each tool - simple and advanced
+# during app startup.
+
+
+# Example usages for each tool - simple and advanced
 _TOOL_EXAMPLES = {
-    "Web_Fetch": (
-        'Web_Fetch(url="https://example.com")',
-        'Web_Fetch(url="https://example.com", max_chars=5000, mode="url_scraper")',
-    ),
     "Web_Search": (
         'Web_Search(query="Python tutorials")',
         'Web_Search(query="AI news", max_results=10, search_type="news", date_filter="week")',
     ),
+    "ScrapeGraphAI": (
+        'ScrapeGraphAI(action="extract", url="https://example.com", prompt="Extract the main offer")',
+        'ScrapeGraphAI(action="multi_extract", urls=["https://example.com/a", "https://example.com/b"], prompt="Compare pricing", schema_json={"type":"object","properties":{"plans":{"type":"array","items":{"type":"string"}}}})',
+    ),
     "Code_Interpreter": (
         'Code_Interpreter(code="print(2 + 2)")',
         'Code_Interpreter(code="import math; print(math.pi)", timeout=60)',
-    ),
+    ),
     "Shell_Command": (
         'Shell_Command(command="echo Hello")',
         'Shell_Command(command="ls -la", timeout=30)',
     ),
-    "File_System": (
-        'File_System(action="list", path="/")',
-        'File_System(action="edit", path="/script.py", content="<<<<<<< SEARCH\\nold_text\\n=======\\nnew_text\\n>>>>>>> REPLACE")',
-    ),
-    "Obsidian_Vault": (
-        'Obsidian_Vault(action="list", path="/")',
-        'Obsidian_Vault(action="search", query="meeting notes", recursive=True)',
-    ),
     "Memory_Manager": (
         'Memory_Manager(action="list")',
         'Memory_Manager(action="save", text="Remember this fact", tags="important, facts")',
     ),
-    "Generate_Speech": (
-        'Generate_Speech(text="Hello, world!")',
-        'Generate_Speech(text="Welcome to the demo", voice="af_heart", speed=1.2)',
-    ),
     "Generate_Image": (
         'Generate_Image(prompt="A sunset over mountains")',
         'Generate_Image(prompt="A cyberpunk city", steps=50, cfg_scale=9.0, width=1024, height=768)',
     ),
-    "Generate_Video": (
-        'Generate_Video(prompt="A cat playing piano")',
-        'Generate_Video(prompt="Ocean waves", duration=5, aspect_ratio="16:9")',
-    ),
-    "Deep_Research": (
-        'Deep_Research(query="Climate change effects")',
-        'Deep_Research(query="Quantum computing advances", max_sources=10, search_type="news")',
-    ),
-    "Agent_Skills": (
-        'Agent_Skills(action="discover")',
-        'Agent_Skills(action="info", skill_name="pdf")',
-    ),
 }
-
-
-def _format_tool_usage(func) -> str:
-    """Generate detailed usage information for a tool function."""
-    name = func.__name__
-    doc = func.__doc__ or "No description available."
-    
-    # Extract just the summary (first paragraph) - skip Args/Returns sections
-    # since we generate our own detailed parameter list
-    doc_lines = doc.strip().split('\n')
-    summary_lines = []
-    for line in doc_lines:
-        stripped = line.strip().lower()
-        # Stop at Args:, Returns:, Parameters:, etc.
-        if stripped.startswith(('args:', 'returns:', 'parameters:', 'raises:', 'example:', 'note:', 'notes:')):
-            break
-        summary_lines.append(line)
-    summary = '\n'.join(summary_lines).strip()
-    
-    # Get the signature
-    sig = inspect.signature(func)
-    
-    # Try to get type hints
-    try:
-        hints = get_type_hints(func, include_extras=True)
-    except Exception:
-        hints = {}
-    
-    lines = [f"=== {name} ===", "", summary, "", "Parameters:"]
-    
-    for param_name, param in sig.parameters.items():
-        if param_name in ("self", "cls"):
-            continue
-            
-        # Get type and description from Annotated if available
-        hint = hints.get(param_name)
-        type_str = "any"
-        desc = ""
-        
-        if hint is not None:
-            if get_origin(hint) is Annotated:
-                args = get_args(hint)
-                if args:
-                    type_str = getattr(args[0], "__name__", str(args[0]))
-                    if len(args) > 1 and isinstance(args[1], str):
-                        desc = args[1]
-            else:
-                type_str = getattr(hint, "__name__", str(hint))
-        
-        # Check for default
-        if param.default is not inspect.Parameter.empty:
-            default_repr = repr(param.default)
-            if len(default_repr) > 50:
-                default_repr = default_repr[:47] + "..."
-            default_str = f" = {default_repr}"
-        else:
-            default_str = " (required)"
-        
-        lines.append(f"  - {param_name}: {type_str}{default_str}")
-        if desc:
-            lines.append(f"      {desc}")
-    
-    # Add examples
-    lines.append("")
-    lines.append("Examples:")
-    if name in _TOOL_EXAMPLES:
-        simple, advanced = _TOOL_EXAMPLES[name]
-        lines.append(f"  {simple}")
-        lines.append(f"  {advanced}")
-    else:
-        lines.append(f"  {name}(...)")
-    
-    return "\n".join(lines)
-
-
+
+
+def _format_tool_usage(func) -> str:
+    """Generate detailed usage information for a tool function."""
+    name = func.__name__
+    doc = func.__doc__ or "No description available."
+    
+    # Extract just the summary (first paragraph) - skip Args/Returns sections
+    # since we generate our own detailed parameter list
+    doc_lines = doc.strip().split('\n')
+    summary_lines = []
+    for line in doc_lines:
+        stripped = line.strip().lower()
+        # Stop at Args:, Returns:, Parameters:, etc.
+        if stripped.startswith(('args:', 'returns:', 'parameters:', 'raises:', 'example:', 'note:', 'notes:')):
+            break
+        summary_lines.append(line)
+    summary = '\n'.join(summary_lines).strip()
+    
+    # Get the signature
+    sig = inspect.signature(func)
+    
+    # Try to get type hints
+    try:
+        hints = get_type_hints(func, include_extras=True)
+    except Exception:
+        hints = {}
+    
+    lines = [f"=== {name} ===", "", summary, "", "Parameters:"]
+    
+    for param_name, param in sig.parameters.items():
+        if param_name in ("self", "cls"):
+            continue
+            
+        # Get type and description from Annotated if available
+        hint = hints.get(param_name)
+        type_str = "any"
+        desc = ""
+        
+        if hint is not None:
+            if get_origin(hint) is Annotated:
+                args = get_args(hint)
+                if args:
+                    type_str = getattr(args[0], "__name__", str(args[0]))
+                    if len(args) > 1 and isinstance(args[1], str):
+                        desc = args[1]
+            else:
+                type_str = getattr(hint, "__name__", str(hint))
+        
+        # Check for default
+        if param.default is not inspect.Parameter.empty:
+            default_repr = repr(param.default)
+            if len(default_repr) > 50:
+                default_repr = default_repr[:47] + "..."
+            default_str = f" = {default_repr}"
+        else:
+            default_str = " (required)"
+        
+        lines.append(f"  - {param_name}: {type_str}{default_str}")
+        if desc:
+            lines.append(f"      {desc}")
+    
+    # Add examples
+    lines.append("")
+    lines.append("Examples:")
+    if name in _TOOL_EXAMPLES:
+        simple, advanced = _TOOL_EXAMPLES[name]
+        lines.append(f"  {simple}")
+        lines.append(f"  {advanced}")
+    else:
+        lines.append(f"  {name}(...)")
+    
+    return "\n".join(lines)
+
+
 def _wrap_tool_for_no_arg_usage(func):
-    """
-    Wrap a tool function so that calling it with no arguments 
-    returns usage information instead of raising an error.
-    """
-    @functools.wraps(func)
-    def wrapper(*args, **kwargs):
-        # If called with no arguments, return usage info
-        if not args and not kwargs:
-            return _format_tool_usage(func)
-        return func(*args, **kwargs)
-    
+    """
+    Wrap a tool function so that calling it with no arguments 
+    returns usage information instead of raising an error.
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # If called with no arguments, return usage info
+        if not args and not kwargs:
+            return _format_tool_usage(func)
+        return func(*args, **kwargs)
+    
     # Preserve the original function for introspection
     wrapper._original_func = func
     return wrapper
@@ -164,140 +140,126 @@ def _get_tools_map():
     Imports are done here (lazily) to avoid circular imports when app.py loads Agent_Terminal.
     """
     # Lazy imports to avoid circular import during app startup
-    from .File_System import File_System
-    from .Web_Fetch import Web_Fetch
     from .Web_Search import Web_Search
+    from .ScrapeGraphAI import ScrapeGraphAI
     from .Memory_Manager import Memory_Manager
-    from .Generate_Speech import Generate_Speech, List_Kokoro_Voices
     from .Generate_Image import Generate_Image
-    from .Generate_Video import Generate_Video
-    from .Deep_Research import Deep_Research
-    from .Obsidian_Vault import Obsidian_Vault
     from .Shell_Command import Shell_Command
     from .Code_Interpreter import Code_Interpreter
-    from .Agent_Skills import Agent_Skills
-    
     raw_tools = {
-        "Web_Fetch": Web_Fetch,
         "Web_Search": Web_Search,
+        "ScrapeGraphAI": ScrapeGraphAI,
         "Memory_Manager": Memory_Manager,
-        "Generate_Speech": Generate_Speech,
-        "List_Kokoro_Voices": List_Kokoro_Voices,
         "Generate_Image": Generate_Image,
-        "Generate_Video": Generate_Video,
-        "Deep_Research": Deep_Research,
-        "File_System": File_System,
-        "Obsidian_Vault": Obsidian_Vault,
         "Shell_Command": Shell_Command,
         "Code_Interpreter": Code_Interpreter,
-        "Agent_Skills": Agent_Skills,
     }
     return {name: _wrap_tool_for_no_arg_usage(func) for name, func in raw_tools.items()}
-
-
-
-def search_tools(query: str) -> str:
-    """Search for tools by name or description. Returns usage info for matches."""
-    query = query.lower()
-    matches = []
-    tools = _get_tools_map()
-    for name, func in tools.items():
-        # Get original function for docstring if wrapped
-        original = getattr(func, '_original_func', func)
-        doc = (original.__doc__ or "").lower()
-        if query in name.lower() or query in doc:
-            matches.append((name, func))
-    
-    if not matches:
-        return f"No tools found matching '{query}'."
-    
-    output = []
-    for name, func in matches:
-        output.append(_format_tool_usage(getattr(func, '_original_func', func)))
-        output.append("")
-    return "\n".join(output)
-
-def _initialize_mock_modules():
-    """
-    Registers a mock 'functions' module in sys.modules so that LLMs
-    can do 'from functions import ...' without error.
-    Uses wrapped tools that return usage info when called with no args.
-    """
-    mock_module = types.ModuleType("functions")
-    
-    # Add wrapped tools (return usage when called with no args)
-    for name, tool in _get_tools_map().items():
-        setattr(mock_module, name, tool)
-        
-    # Add helpers
-    helpers = {
-        "search_tools": search_tools,
-    }
-    for name, func in helpers.items():
-        setattr(mock_module, name, func)
-        
-    sys.modules["functions"] = mock_module
-
-# Defer initialization until first use to avoid circular imports during app startup
-_mock_modules_initialized = False
-
-def _ensure_mock_modules():
-    """Initialize mock modules on first use (deferred to avoid circular imports)."""
-    global _mock_modules_initialized
-    if not _mock_modules_initialized:
-        _initialize_mock_modules()
-        _mock_modules_initialized = True
-
+
+
+
+def search_tools(query: str) -> str:
+    """Search for tools by name or description. Returns usage info for matches."""
+    query = query.lower()
+    matches = []
+    tools = _get_tools_map()
+    for name, func in tools.items():
+        # Get original function for docstring if wrapped
+        original = getattr(func, '_original_func', func)
+        doc = (original.__doc__ or "").lower()
+        if query in name.lower() or query in doc:
+            matches.append((name, func))
+    
+    if not matches:
+        return f"No tools found matching '{query}'."
+    
+    output = []
+    for name, func in matches:
+        output.append(_format_tool_usage(getattr(func, '_original_func', func)))
+        output.append("")
+    return "\n".join(output)
+
+def _initialize_mock_modules():
+    """
+    Registers a mock 'functions' module in sys.modules so that LLMs
+    can do 'from functions import ...' without error.
+    Uses wrapped tools that return usage info when called with no args.
+    """
+    mock_module = types.ModuleType("functions")
+    
+    # Add wrapped tools (return usage when called with no args)
+    for name, tool in _get_tools_map().items():
+        setattr(mock_module, name, tool)
+        
+    # Add helpers
+    helpers = {
+        "search_tools": search_tools,
+    }
+    for name, func in helpers.items():
+        setattr(mock_module, name, func)
+        
+    sys.modules["functions"] = mock_module
+
+# Defer initialization until first use to avoid circular imports during app startup
+_mock_modules_initialized = False
+
+def _ensure_mock_modules():
+    """Initialize mock modules on first use (deferred to avoid circular imports)."""
+    global _mock_modules_initialized
+    if not _mock_modules_initialized:
+        _initialize_mock_modules()
+        _mock_modules_initialized = True
+
 TOOL_SUMMARY = (
     "Executes Python code as the unified interface for the entire tools ecosystem. "
     "Use Agent Terminal repeatedly whenever you need to chain or combine tool operations. Input must be JSON that will be executed in Python. "
-    "Available tools: `Web_Fetch`, `Web_Search`, `Code_Interpreter`, `Shell_Command`, `File_System`, `Obsidian_Vault`, `Memory_Manager`, `Generate_Speech`, `Generate_Image`, `Generate_Video`, `Deep_Research`, `Agent_Skills`."
+    "Available tools: `Web_Search`, `ScrapeGraphAI`, `Code_Interpreter`, `Shell_Command`, `Memory_Manager`, `Generate_Image`."
 )
-
-
-
-@autodoc(
-    summary=TOOL_SUMMARY,
-)
-def Agent_Terminal(input: Annotated[str, (
-    "Python source code to run; stdout is captured and returned. "
-    "Use `search_tools(`query`)` to search tools by name or capability, returns tool definitions and examples. "
-    "Call any tool with no arguments to get its full usage info (e.g., `Generate_Image()`)."
-)]) -> str:
-    # Initialize mock modules on first call (deferred to avoid circular imports)
-    _ensure_mock_modules()
-    
-    _log_call_start("Agent_Terminal", input=_truncate_for_log(input or "", 300))
-    if input is None:
-        result = "No code provided."
-        _log_call_end("Agent_Terminal", result)
-        return result
-    
-    # Get wrapped tools that return usage info when called with no args
-    wrapped_tools = _get_tools_map()
-    
-    # Build tools environment to inject
-    tools_env = {
-        **wrapped_tools,
-        "search_tools": search_tools,
-    }
-    
-    # Execute with AST mode to print all expression results
-    result = sandboxed_exec(input, extra_globals=tools_env, ast_mode=True)
-    _log_call_end("Agent_Terminal", _truncate_for_log(result))
-    return result
-
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Agent_Terminal,
-        inputs=gr.Code(label="Python Code", language="python"),
-        outputs=gr.Textbox(label="Output", lines=5, max_lines=20),
-        title="Agent Terminal",
-        description="<div style=\"text-align:center\">Interact with all other tools via a Python API. Reduces token usage by 90%.</div>",
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-    )
-
-
-__all__ = ["Agent_Terminal", "build_interface"]
+
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Agent_Terminal(input: Annotated[str, (
+    "Python source code to run; stdout is captured and returned. "
+    "Use `search_tools(`query`)` to search tools by name or capability, returns tool definitions and examples. "
+    "Call any tool with no arguments to get its full usage info (e.g., `Generate_Image()`)."
+)]) -> str:
+    # Initialize mock modules on first call (deferred to avoid circular imports)
+    _ensure_mock_modules()
+    
+    _log_call_start("Agent_Terminal", input=_truncate_for_log(input or "", 300))
+    if input is None:
+        result = "No code provided."
+        _log_call_end("Agent_Terminal", result)
+        return result
+    
+    # Get wrapped tools that return usage info when called with no args
+    wrapped_tools = _get_tools_map()
+    
+    # Build tools environment to inject
+    tools_env = {
+        **wrapped_tools,
+        "search_tools": search_tools,
+    }
+    
+    # Execute with AST mode to print all expression results
+    result = sandboxed_exec(input, extra_globals=tools_env, ast_mode=True)
+    _log_call_end("Agent_Terminal", _truncate_for_log(result))
+    return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Agent_Terminal,
+        inputs=gr.Code(label="Python Code", language="python"),
+        outputs=gr.Textbox(label="Output", lines=5, max_lines=20),
+        title="Agent Terminal",
+        description="<div style=\"text-align:center\">Interact with all other tools via a Python API. Reduces token usage by 90%.</div>",
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Agent_Terminal", "build_interface"]

Modules/Code_Interpreter.py

@@ -1,40 +1,40 @@
-from __future__ import annotations
-
-from typing import Annotated
-
-import gradio as gr
-from ._docstrings import autodoc
-from ._core import sandboxed_exec
-
-from app import _log_call_end, _log_call_start, _truncate_for_log
-
-
-# Single source of truth for the LLM-facing tool description
-TOOL_SUMMARY = (
-    "Execute Python code from the tool root; returns captured stdout or the exception text."
-)
-
-
-@autodoc(
-    summary=TOOL_SUMMARY,
-)
-def Code_Interpreter(code: Annotated[str, "Python source code to run; stdout is captured and returned."]) -> str:
-    _log_call_start("Code_Interpreter", code=_truncate_for_log(code or "", 300))
-    result = sandboxed_exec(code, ast_mode=False)
-    _log_call_end("Code_Interpreter", _truncate_for_log(result))
-    return result
-
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Code_Interpreter,
-        inputs=gr.Code(label="Python Code", language="python"),
-        outputs=gr.Textbox(label="Output", lines=5, max_lines=20),
-        title="Code Interpreter",
-        description="<div style=\"text-align:center\">Execute Python code and see the output.</div>",
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-    )
-
-
+from __future__ import annotations
+
+from typing import Annotated
+
+import gradio as gr
+from ._docstrings import autodoc
+from ._core import sandboxed_exec
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Execute Python code from the tool root; returns captured stdout or the exception text."
+)
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Code_Interpreter(code: Annotated[str, "Python source code to run; stdout is captured and returned."]) -> str:
+    _log_call_start("Code_Interpreter", code=_truncate_for_log(code or "", 300))
+    result = sandboxed_exec(code, ast_mode=False)
+    _log_call_end("Code_Interpreter", _truncate_for_log(result))
+    return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Code_Interpreter,
+        inputs=gr.Code(label="Python Code", language="python"),
+        outputs=gr.Textbox(label="Output", lines=5, max_lines=20),
+        title="Code Interpreter",
+        description="<div style=\"text-align:center\">Execute Python code and see the output.</div>",
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
 __all__ = ["Code_Interpreter", "build_interface"]

Modules/Deep_Research.py

@@ -1,596 +1,596 @@
-from __future__ import annotations
-
-import os
-import re
-import tempfile
-import time
-import uuid
-from collections import OrderedDict, deque
-from concurrent.futures import Future, ThreadPoolExecutor, as_completed
-from datetime import datetime
-from typing import Annotated, Callable, Dict, List, Tuple
-from urllib.parse import urlparse
-
-import gradio as gr
-import requests
-from bs4 import BeautifulSoup
-from ddgs import DDGS
-from huggingface_hub import InferenceClient
-
-from .Web_Fetch import _fullpage_markdown_from_soup, _http_get_enhanced
-from app import _log_call_end, _log_call_start, _search_rate_limiter, _truncate_for_log
-from ._docstrings import autodoc
-from .File_System import ROOT_DIR
-from ._core import get_hf_token
-
-HF_TEXTGEN_TOKEN = get_hf_token()
-
-
-# Single source of truth for the LLM-facing tool description
-TOOL_SUMMARY = (
-    "Write a summary of what the user wants to research, and "
-    "run multiple DuckDuckGo searches (up to 50 max results between all queries), fetch pages, and a Research agent will produce a comprehensive research report with sources; "
-    "returns (Markdown report, newline-separated source links, downloadable report path). "
-    "Provide the user with one-paragraph summary of the research report and the txt file in this format `![research_report](URL)`."
-)
-
-RESEARCHER_SYSTEM_PROMPT = (
-    "You are Nymbot, a helpful deep research assistant. You will be asked a Query from a user and you will create a long, comprehensive, well-structured research report in response to the user's Query.\n\n"
-    "You will receive a summary of the user question, the search queries used, and the fetched webpages. Follow the guidance below when writing the report.\n\n"
-    "<report_format>\n"
-    "Write a well-formatted report in the structure of a scientific report to a broad audience. The report must be readable and have a nice flow of Markdown headers and paragraphs of text. Do NOT use bullet points or lists which break up the natural flow. The report must be exhaustive for comprehensive topics.\n"
-    "For any given user query, first determine the major themes or areas that need investigation, then structure these as main sections, and develop detailed subsections that explore various facets of each theme. Each section and subsection requires paragraphs of texts that need to all connect into one narrative flow.\n"
-    "</report_format>\n\n"
-    "<document_structure>\n"
-    "- Always begin with a clear title using a single # header\n"
-    "- Organize content into major sections using ## headers\n"
-    "- Further divide into subsections using ### headers\n"
-    "- Use #### headers sparingly for special subsections\n"
-    "- Never skip header levels\n"
-    "- Write multiple paragraphs per section or subsection\n"
-    "- Each paragraph must contain at least 4-5 sentences, present novel insights and analysis grounded in source material, connect ideas to original query, and build upon previous paragraphs to create a narrative flow\n"
-    "- Never use lists, instead always use text or tables\n\n"
-    "Mandatory Section Flow:\n"
-    "1. Title (# level)\n   - Before writing the main report, start with one detailed paragraph summarizing key findings\n"
-    "2. Main Body Sections (## level)\n   - Each major topic gets its own section (## level). There MUST BE at least 5 sections.\n   - Use ### subsections for detailed analysis\n   - Every section or subsection needs at least one paragraph of narrative before moving to the next section\n   - Do NOT have a section titled \"Main Body Sections\" and instead pick informative section names that convey the theme of the section\n"
-    "3. Conclusion (## level)\n   - Synthesis of findings\n   - Potential recommendations or next steps\n"
-    "</document_structure>\n\n"
-    "<planning_rules>\n"
-    "- Always break it down into multiple steps\n"
-    "- Assess the different sources and whether they are useful for any steps needed to answer the query\n"
-    "- Create the best report that weighs all the evidence from the sources\n"
-    "- Use the current date supplied in the first user message to contextualize findings\n"
-    "- Make sure that your final report addresses all parts of the query\n"
-    "- Communicate a brief high-level plan in the introduction; do not reveal chain-of-thought.\n"
-    "- When referencing sources during analysis, you should still refer to them by index with brackets and follow <citations>\n"
-    "- As a final step, review your planned report structure and ensure it completely answers the query.\n"
-    "</planning_rules>\n\n"
-)
-
-FILTERER_SYSTEM_PROMPT = (
-    "You are Nymbot Filterer, an analyst who selects the most relevant sources for a research task. "
-    "You will be given a summary of the research topic (and optional search queries) followed by multiple fetched documents. "
-    "Each document includes its URL and a truncated excerpt. Evaluate how well each source helps answer the research topic. "
-    "Return only the URLs that should be used for the final research step. Output plain text with exactly one URL per line and no additional commentary, bullets, numbering, or explanations. "
-    "If no sources are relevant, return an empty string."
-)
-
-
-class SlowHost(Exception):
-    pass
-
-
-def _normalize_query(q: str) -> str:
-    if not q:
-        return ""
-    repl = {"“": '"', "”": '"', "‘": "'", "’": "'", "`": "'"}
-    for key, value in repl.items():
-        q = q.replace(key, value)
-    q = re.sub(r"\s+", " ", q)
-    q = re.sub(r'"\s+"', " ", q)
-    q = q.strip().strip('"').strip()
-    return q
-
-
-def _search_urls_only(query: str, max_results: int) -> list[str]:
-    if not query or not query.strip() or max_results <= 0:
-        return []
-    urls: list[str] = []
-    try:
-        _search_rate_limiter.acquire()
-        with DDGS() as ddgs:
-            for item in ddgs.text(query, region="wt-wt", safesearch="moderate", max_results=max_results):
-                url = (item.get("href") or item.get("url") or "").strip()
-                if url:
-                    urls.append(url)
-    except Exception:
-        pass
-    seen = set()
-    deduped = []
-    for url in urls:
-        if url not in seen:
-            seen.add(url)
-            deduped.append(url)
-    return deduped
-
-
-def _fetch_page_markdown_fast(url: str, max_chars: int = 3000, timeout: float = 10.0) -> str:
-    try:
-        resp = _http_get_enhanced(url, timeout=timeout, skip_rate_limit=True)
-        resp.raise_for_status()
-    except requests.exceptions.RequestException as exc:
-        msg = str(exc)
-        if "timed out" in msg.lower():
-            raise SlowHost(msg) from exc
-        return ""
-    final_url = str(resp.url)
-    ctype = resp.headers.get("Content-Type", "")
-    if "html" not in ctype.lower():
-        return ""
-    resp.encoding = resp.encoding or resp.apparent_encoding
-    html = resp.text
-    soup = BeautifulSoup(html, "lxml")
-    md_text = _fullpage_markdown_from_soup(soup, final_url, "")
-    if max_chars > 0 and len(md_text) > max_chars:
-        md_text = md_text[:max_chars]
-    return md_text
-
-
-def _truncate_join(parts: List[str], max_chars: int) -> Tuple[str, bool]:
-    out = []
-    total = 0
-    truncated = False
-    for part in parts:
-        if not part:
-            continue
-        if total + len(part) > max_chars:
-            out.append(part[: max(0, max_chars - total)])
-            truncated = True
-            break
-        out.append(part)
-        total += len(part)
-    return ("\n\n".join(out), truncated)
-
-
-def _build_research_prompt(summary: str, queries: List[str], url_list: List[str], pages_map: Dict[str, str]) -> str:
-    sources_blocks: List[str] = []
-    indexed_urls: List[str] = []
-    for idx, url in enumerate(url_list, start=1):
-        text = pages_map.get(url, "").strip()
-        if not text:
-            continue
-        indexed_urls.append(f"[{idx}] {url}")
-        sources_blocks.append(f"[Source {idx}] URL: {url}\n\n{text}")
-    sources_joined, truncated = _truncate_join(sources_blocks, max_chars=100_000)
-    prompt_parts: List[str] = []
-    prompt_parts.append("<user_query_summary>\n" + (summary or "") + "\n</user_query_summary>\n")
-    populated = [q for q in queries if q and q.strip()]
-    if populated:
-        prompt_parts.append("<search_queries>\n" + "\n".join(f"- {q.strip()}" for q in populated) + "\n</search_queries>\n")
-    if indexed_urls:
-        prompt_parts.append("<sources_list>\n" + "\n".join(indexed_urls) + "\n</sources_list>\n")
-    prompt_parts.append("<fetched_documents>\n" + sources_joined + ("\n\n[NOTE] Sources truncated due to context limits." if truncated else "") + "\n</fetched_documents>")
-    return "\n\n".join(prompt_parts)
-
-
-def _build_filter_prompt(summary: str, queries: List[str], pages_map: Dict[str, str]) -> str:
-    populated = [q for q in queries if q and q.strip()]
-    summary_text = summary or ""
-    prompt_sections: List[str] = []
-    prompt_sections.append("<research_topic_summary>\n" + summary_text + "\n</research_topic_summary>")
-    if populated:
-        prompt_sections.append("<search_queries>\n" + "\n".join(populated) + "\n</search_queries>")
-    sources: List[str] = []
-    for idx, (url, text) in enumerate(pages_map.items(), start=1):
-        content = text.strip()
-        if not content:
-            continue
-        sources.append(f"[Source {idx}] URL: {url}\n\n{content}")
-    sources_joined, truncated = _truncate_join(sources, max_chars=60_000)
-    prompt_sections.append("<candidate_sources>\n" + sources_joined + ("\n\n[NOTE] Sources truncated due to context limits." if truncated else "") + "\n</candidate_sources>")
-    prompt_sections.append(
-        "<task>\nIdentify which of the provided URLs should be retained for the final research synthesis. "
-        "Consider coverage, credibility, and relevance to the research topic. "
-        "Return ONLY the URLs you choose, with one URL per line and no additional text.\n</task>"
-    )
-    return "\n\n".join(prompt_sections)
-
-
-def _parse_filterer_output(raw: str, allowed_urls: List[str]) -> List[str]:
-    if not raw:
-        return []
-    allowed_set = {url.strip(): idx for idx, url in enumerate(allowed_urls)}
-    found_indices: set[int] = set()
-    for line in raw.splitlines():
-        candidate = line.strip()
-        if not candidate:
-            continue
-        if candidate in allowed_set:
-            found_indices.add(allowed_set[candidate])
-            continue
-        match = re.search(r"https?://[^\s]+", candidate)
-        if not match:
-            continue
-        url = match.group(0).rstrip(".,);]")
-        if url in allowed_set:
-            found_indices.add(allowed_set[url])
-    selected = [allowed_urls[idx] for idx in sorted(found_indices)]
-    return selected
-
-
-def _write_report_tmp(text: str) -> str:
-    filename = f"research_report_{uuid.uuid4().hex}.txt"
-    path = os.path.join(ROOT_DIR, filename)
-    with open(path, "w", encoding="utf-8") as file:
-        file.write(text)
-    return path
-
-
-def _fetch_pages_within_budget(urls: List[str], char_limit: int, time_left_fn: Callable[[], float]) -> OrderedDict:
-    pages: dict[str, str] = {}
-    if not urls:
-        return OrderedDict()
-    queue = deque(urls)
-    attempts: dict[str, int] = {url: 0 for url in urls}
-    max_attempts = 2
-    max_workers = min(12, max(4, len(urls)))
-    in_flight: dict[Future, str] = {}
-    delayed: list[tuple[float, str]] = []
-
-    def schedule_next(executor: ThreadPoolExecutor) -> None:
-        while queue and len(in_flight) < max_workers:
-            url = queue.popleft()
-            if url in pages:
-                continue
-            attempts.setdefault(url, 0)
-            if attempts[url] >= max_attempts:
-                continue
-            attempts[url] += 1
-            tl = time_left_fn()
-            if tl <= 0.1:
-                return
-            per_timeout = 10.0 if tl > 15 else (5.0 if tl > 8 else 2.0)
-            future = executor.submit(_fetch_page_markdown_fast, url, char_limit, per_timeout)
-            in_flight[future] = url
-
-    with ThreadPoolExecutor(max_workers=max_workers) as executor:
-        schedule_next(executor)
-        while (in_flight or queue or delayed) and time_left_fn() > 0.2:
-            now = time.time()
-            if delayed:
-                ready: list[tuple[float, str]] = []
-                not_ready: list[tuple[float, str]] = []
-                for ready_time, delayed_url in delayed:
-                    (ready if ready_time <= now else not_ready).append((ready_time, delayed_url))
-                delayed = not_ready
-                for _, delayed_url in ready:
-                    queue.append(delayed_url)
-                if ready:
-                    schedule_next(executor)
-            done = [future for future in list(in_flight.keys()) if future.done()]
-            if not done:
-                if not queue and delayed:
-                    next_ready = min((t for t, _ in delayed), default=time.time())
-                    sleep_for = max(0.0, next_ready - time.time())
-                    time.sleep(max(0.02, min(0.25, sleep_for)))
-                else:
-                    time.sleep(0.05)
-                continue
-            for future in done:
-                url = in_flight.pop(future)
-                try:
-                    md = future.result()
-                    if md and not md.startswith("Unsupported content type") and not md.startswith("An error occurred"):
-                        pages[url] = md
-                        try:
-                            print(f"[FETCH OK] {url} (chars={len(md)})", flush=True)
-                        except Exception:
-                            pass
-                except SlowHost:
-                    if time_left_fn() > 5.0:
-                        delayed.append((time.time() + 3.0, url))
-                except Exception:
-                    pass
-            schedule_next(executor)
-    ordered = OrderedDict((url, pages[url]) for url in urls if url in pages)
-    return ordered
-
-
-@autodoc(
-    summary=TOOL_SUMMARY,
-)
-def Deep_Research(
-    summary: Annotated[str, "Summarization of research topic (one or more sentences)."],
-    query1: Annotated[str, "DDG Search Query 1"],
-    max1: Annotated[int, "Max results for Query 1 (1-50)"] = 10,
-    query2: Annotated[str, "DDG Search Query 2"] = "",
-    max2: Annotated[int, "Max results for Query 2 (1-50)"] = 10,
-    query3: Annotated[str, "DDG Search Query 3"] = "",
-    max3: Annotated[int, "Max results for Query 3 (1-50)"] = 10,
-    query4: Annotated[str, "DDG Search Query 4"] = "",
-    max4: Annotated[int, "Max results for Query 4 (1-50)"] = 10,
-    query5: Annotated[str, "DDG Search Query 5"] = "",
-    max5: Annotated[int, "Max results for Query 5 (1-50)"] = 10,
-) -> tuple[str, str, str]:
-    _log_call_start(
-        "Deep_Research",
-        summary=_truncate_for_log(summary or "", 200),
-        queries=[q for q in [query1, query2, query3, query4, query5] if q],
-    )
-    if not HF_TEXTGEN_TOKEN:
-        _log_call_end("Deep_Research", "error=missing HF token")
-        raise gr.Error("Please provide a `HF_READ_TOKEN` to enable Deep Research.")
-    queries = [
-        _normalize_query(query1 or ""),
-        _normalize_query(query2 or ""),
-        _normalize_query(query3 or ""),
-        _normalize_query(query4 or ""),
-        _normalize_query(query5 or ""),
-    ]
-    reqs = [
-        max(1, min(50, int(max1))),
-        max(1, min(50, int(max2))),
-        max(1, min(50, int(max3))),
-        max(1, min(50, int(max4))),
-        max(1, min(50, int(max5))),
-    ]
-    total_requested = sum(reqs)
-    if total_requested > 50:
-        reqs = [10, 10, 10, 10, 10]
-    start_ts = time.time()
-    budget_seconds = 55.0
-    deadline = start_ts + budget_seconds
-
-    def time_left() -> float:
-        return max(0.0, deadline - time.time())
-
-    now_dt = datetime.now().astimezone()
-    date_str = now_dt.strftime("%A, %B %d, %Y %I:%M %p %Z").strip()
-    if not date_str:
-        date_str = now_dt.isoformat()
-
-    all_urls: list[str] = []
-    tasks = []
-    with ThreadPoolExecutor(max_workers=min(5, sum(1 for q in queries if q.strip())) or 1) as executor:
-        for query, count in zip(queries, reqs):
-            if not query.strip():
-                continue
-            tasks.append(executor.submit(_search_urls_only, query.strip(), count))
-        for future in as_completed(tasks):
-            try:
-                urls = future.result() or []
-            except Exception:
-                urls = []
-            for url in urls:
-                if url not in all_urls:
-                    all_urls.append(url)
-            if len(all_urls) >= 50:
-                break
-            if time_left() <= 0.5:
-                break
-    if len(all_urls) > 50:
-        all_urls = all_urls[:50]
-    blacklist = {
-        "homedepot.com",
-        "tractorsupply.com",
-        "mcmaster.com",
-        "mrchain.com",
-        "answers.com",
-        "city-data.com",
-        "dictionary.cambridge.org",
-    }
-
-    def _domain(url: str) -> str:
-        try:
-            return urlparse(url).netloc.lower()
-        except Exception:
-            return ""
-
-    all_urls = [url for url in all_urls if _domain(url) not in blacklist]
-    skip_exts = (
-        ".pdf",
-        ".ppt",
-        ".pptx",
-        ".doc",
-        ".docx",
-        ".xls",
-        ".xlsx",
-        ".zip",
-        ".gz",
-        ".tgz",
-        ".bz2",
-        ".7z",
-        ".rar",
-    )
-
-    def _skip_url(url: str) -> bool:
-        try:
-            path = urlparse(url).path.lower()
-        except Exception:
-            return False
-        return any(path.endswith(ext) for ext in skip_exts)
-
-    all_urls = [url for url in all_urls if not _skip_url(url)]
-    truncated_pages = OrderedDict()
-    if all_urls and time_left() > 0.2:
-        truncated_pages = _fetch_pages_within_budget(all_urls, 3000, time_left)
-    print(
-        f"[PIPELINE] Initial fetch complete: candidates={len(all_urls)}, truncated_documents={len(truncated_pages)}, time_left={time_left():.2f}s",
-        flush=True,
-    )
-
-    def _invoke_chat(messages, provider: str, max_tokens: int, temp: float, top_p: float):
-        client = InferenceClient(provider=provider, api_key=HF_TEXTGEN_TOKEN)
-        return client.chat.completions.create(
-            model="zai-org/GLM-4.7",
-            messages=messages,
-            max_tokens=max_tokens,
-            temperature=temp,
-            top_p=top_p,
-        )
-
-    filtered_urls: List[str] = list(truncated_pages.keys())
-    filter_output = ""
-    filter_used_fallback = False
-    filter_success = False
-    if truncated_pages and time_left() > 3.0:
-        filter_prompt = _build_filter_prompt(summary or "", [q for q in queries if q.strip()], truncated_pages)
-        filter_messages = [
-            {"role": "system", "content": FILTERER_SYSTEM_PROMPT},
-            {"role": "user", "content": f"The current date is {date_str}. Consider how recent each source is when deciding relevance."},
-            {"role": "user", "content": filter_prompt},
-        ]
-        filter_completion = None
-        try:
-            print("[FILTER] Attempt 1: provider=cerebras, max_tokens=2048", flush=True)
-            filter_completion = _invoke_chat(filter_messages, "cerebras", 2048, 0.2, 0.9)
-        except Exception as exc1:
-            print(f"[FILTER] Attempt 1 failed: {str(exc1)[:200]}", flush=True)
-            try:
-                print("[FILTER] Attempt 2: provider=auto, max_tokens=2048", flush=True)
-                filter_completion = _invoke_chat(filter_messages, "auto", 2048, 0.2, 0.9)
-            except Exception as exc2:
-                print(f"[FILTER] Attempt 2 failed: {str(exc2)[:200]}", flush=True)
-        if filter_completion and filter_completion.choices:
-            filter_output = filter_completion.choices[0].message.content or ""
-            filtered_urls = _parse_filterer_output(filter_output, list(truncated_pages.keys()))
-            filter_success = bool(filter_output.strip()) and bool(filtered_urls)
-    if not filtered_urls:
-        filter_used_fallback = True
-        fallback_count = min(8, len(truncated_pages))
-        filtered_urls = list(truncated_pages.keys())[:fallback_count]
-    max_final_urls = 20
-    if len(filtered_urls) > max_final_urls:
-        filter_used_fallback = True
-        filtered_urls = filtered_urls[:max_final_urls]
-    if not filter_success:
-        filter_used_fallback = True
-    print(
-        f"[FILTER] Selected URLs={len(filtered_urls)}, fallback={filter_used_fallback}, time_left={time_left():.2f}s",
-        flush=True,
-    )
-
-    final_pages_fetched = OrderedDict()
-    if filtered_urls and time_left() > 0.2:
-        final_pages_fetched = _fetch_pages_within_budget(filtered_urls, 8000, time_left)
-    merged_pages = OrderedDict()
-    for url in filtered_urls:
-        content = final_pages_fetched.get(url) or truncated_pages.get(url) or ""
-        if content:
-            merged_pages[url] = content
-    pages = merged_pages
-    print(
-        f"[PIPELINE] Final fetch complete: retained_documents={len(pages)}, time_left={time_left():.2f}s",
-        flush=True,
-    )
-    prompt = _build_research_prompt(summary=summary or "", queries=[q for q in queries if q.strip()], url_list=list(pages.keys()), pages_map=pages)
-    system_message = {"role": "system", "content": RESEARCHER_SYSTEM_PROMPT}
-    date_message = {"role": "user", "content": f"The current date is {date_str}. Return only the research report."}
-    messages = [
-        system_message,
-        date_message,
-        {"role": "user", "content": prompt},
-    ]
-    try:
-        prompt_chars = len(prompt)
-    except Exception:
-        prompt_chars = -1
-    print(f"[PIPELINE] Fetch complete: pages={len(pages)}, unique_urls={len(pages.keys())}, prompt_chars={prompt_chars}", flush=True)
-    print("[PIPELINE] Starting inference (provider=cerebras, model=zai-org/GLM-4.7)", flush=True)
-
-    try:
-        print("[LLM] Attempt 1: provider=cerebras, max_tokens=32768", flush=True)
-        completion = _invoke_chat(messages, "cerebras", max_tokens=32768, temp=0.3, top_p=0.95)
-    except Exception as exc1:
-        print(f"[LLM] Attempt 1 failed: {str(exc1)[:200]}", flush=True)
-        try:
-            prompt2 = _build_research_prompt(
-                summary=summary or "",
-                queries=[q for q in queries if q.strip()],
-                url_list=list(pages.keys())[:30],
-                pages_map={key: pages[key] for key in list(pages.keys())[:30]},
-            )
-            messages = [
-                system_message,
-                date_message,
-                {"role": "user", "content": prompt2},
-            ]
-            print("[LLM] Attempt 2: provider=cerebras (trimmed), max_tokens=16384", flush=True)
-            completion = _invoke_chat(messages, "cerebras", max_tokens=16384, temp=0.7, top_p=0.95)
-        except Exception as exc2:
-            print(f"[LLM] Attempt 2 failed: {str(exc2)[:200]}", flush=True)
-            try:
-                print("[LLM] Attempt 3: provider=auto, max_tokens=8192", flush=True)
-                completion = _invoke_chat(messages, "auto", max_tokens=8192, temp=0.7, top_p=0.95)
-            except Exception as exc3:
-                _log_call_end("Deep_Research", f"error={_truncate_for_log(str(exc3), 260)}")
-                raise gr.Error(f"Researcher model call failed: {exc3}")
-    raw = completion.choices[0].message.content or ""
-    try:
-        no_think = re.sub(r"<think>[\s\S]*?<\\/think>", "", raw, flags=re.IGNORECASE)
-        no_think = re.sub(r"<\\/?think>", "", no_think, flags=re.IGNORECASE)
-    except Exception:
-        no_think = raw
-    try:
-        paragraphs = [p for p in re.split(r"\n\s*\n", no_think) if p.strip()]
-        keep: List[str] = []
-        removed = 0
-        planning_re = re.compile(r"\b(let me|now i(?:'ll| will)?|first,|i will now|i will|i'll|let's|now let me|i need to|now i'll|now i will)\b", re.IGNORECASE)
-        for paragraph in paragraphs:
-            if planning_re.search(paragraph):
-                removed += 1
-                continue
-            keep.append(paragraph)
-        report = "\n\n".join(keep).strip()
-        if not report:
-            report = no_think.strip()
-    except Exception:
-        report = no_think
-        removed = 0
-    report = re.sub(r"\n\s*\n\s*\n+", "\n\n", report)
-    try:
-        print(f"[POSTPROCESS] removed_planning_paragraphs={removed}, raw_chars={len(raw)}, final_chars={len(report)}", flush=True)
-    except Exception:
-        pass
-    links_text = "\n".join([f"[{i+1}] {url}" for i, url in enumerate(pages.keys())])
-    if links_text:
-        sources_section = "\n\n## Sources\n" + "\n".join([f"[{i+1}] {url}" for i, url in enumerate(pages.keys())])
-        report = report.rstrip() + sources_section
-    file_path = _write_report_tmp(report)
-    elapsed = time.time() - start_ts
-    print(f"[TIMING] Deep_Research elapsed: {elapsed:.2f}s", flush=True)
-    _log_call_end("Deep_Research", f"urls={len(pages)} file={os.path.basename(file_path)} duration={elapsed:.2f}s")
-    return report, links_text, file_path
-
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Deep_Research,
-        inputs=[
-            gr.Textbox(label="Summarization of research topic", lines=3, placeholder="Briefly summarize the research topic or user question", info="Summarization of research topic (one or more sentences)"),
-            gr.Textbox(label="DDG Search Query 1", max_lines=1, info="DDG Search Query 1"),
-            gr.Slider(1, 50, value=10, step=1, label="Max results (Q1)", info="Max results for Query 1 (1-50)"),
-            gr.Textbox(label="DDG Search Query 2", value="", max_lines=1, info="DDG Search Query 2"),
-            gr.Slider(1, 50, value=10, step=1, label="Max results (Q2)", info="Max results for Query 2 (1-50)"),
-            gr.Textbox(label="DDG Search Query 3", value="", max_lines=1, info="DDG Search Query 3"),
-            gr.Slider(1, 50, value=10, step=1, label="Max results (Q3)", info="Max results for Query 3 (1-50)"),
-            gr.Textbox(label="DDG Search Query 4", value="", max_lines=1, info="DDG Search Query 4"),
-            gr.Slider(1, 50, value=10, step=1, label="Max results (Q4)", info="Max results for Query 4 (1-50)"),
-            gr.Textbox(label="DDG Search Query 5", value="", max_lines=1, info="DDG Search Query 5"),
-            gr.Slider(1, 50, value=10, step=1, label="Max results (Q5)", info="Max results for Query 5 (1-50)"),
-        ],
-        outputs=[
-            gr.Markdown(label="Research Report"),
-            gr.Textbox(label="Fetched Links", lines=8),
-            gr.File(label="Download Research Report", file_count="single"),
-        ],
-        title="Deep Research",
-        description=(
-            "<div style=\"text-align:center\">Generate a research report based on dozens of sources. Default model is GLM-4.7</div>"
-        ),
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-    )
-
-
-__all__ = ["Deep_Research", "build_interface"]
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+import time
+import uuid
+from collections import OrderedDict, deque
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from datetime import datetime
+from typing import Annotated, Callable, Dict, List, Tuple
+from urllib.parse import urlparse
+
+import gradio as gr
+import requests
+from bs4 import BeautifulSoup
+from ddgs import DDGS
+from huggingface_hub import InferenceClient
+
+from .Web_Fetch import _fullpage_markdown_from_soup, _http_get_enhanced
+from app import _log_call_end, _log_call_start, _search_rate_limiter, _truncate_for_log
+from ._docstrings import autodoc
+from .File_System import ROOT_DIR
+from ._core import get_hf_token
+
+HF_TEXTGEN_TOKEN = get_hf_token()
+
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Write a summary of what the user wants to research, and "
+    "run multiple DuckDuckGo searches (up to 50 max results between all queries), fetch pages, and a Research agent will produce a comprehensive research report with sources; "
+    "returns (Markdown report, newline-separated source links, downloadable report path). "
+    "Provide the user with one-paragraph summary of the research report and the txt file in this format `![research_report](URL)`."
+)
+
+RESEARCHER_SYSTEM_PROMPT = (
+    "You are Nymbot, a helpful deep research assistant. You will be asked a Query from a user and you will create a long, comprehensive, well-structured research report in response to the user's Query.\n\n"
+    "You will receive a summary of the user question, the search queries used, and the fetched webpages. Follow the guidance below when writing the report.\n\n"
+    "<report_format>\n"
+    "Write a well-formatted report in the structure of a scientific report to a broad audience. The report must be readable and have a nice flow of Markdown headers and paragraphs of text. Do NOT use bullet points or lists which break up the natural flow. The report must be exhaustive for comprehensive topics.\n"
+    "For any given user query, first determine the major themes or areas that need investigation, then structure these as main sections, and develop detailed subsections that explore various facets of each theme. Each section and subsection requires paragraphs of texts that need to all connect into one narrative flow.\n"
+    "</report_format>\n\n"
+    "<document_structure>\n"
+    "- Always begin with a clear title using a single # header\n"
+    "- Organize content into major sections using ## headers\n"
+    "- Further divide into subsections using ### headers\n"
+    "- Use #### headers sparingly for special subsections\n"
+    "- Never skip header levels\n"
+    "- Write multiple paragraphs per section or subsection\n"
+    "- Each paragraph must contain at least 4-5 sentences, present novel insights and analysis grounded in source material, connect ideas to original query, and build upon previous paragraphs to create a narrative flow\n"
+    "- Never use lists, instead always use text or tables\n\n"
+    "Mandatory Section Flow:\n"
+    "1. Title (# level)\n   - Before writing the main report, start with one detailed paragraph summarizing key findings\n"
+    "2. Main Body Sections (## level)\n   - Each major topic gets its own section (## level). There MUST BE at least 5 sections.\n   - Use ### subsections for detailed analysis\n   - Every section or subsection needs at least one paragraph of narrative before moving to the next section\n   - Do NOT have a section titled \"Main Body Sections\" and instead pick informative section names that convey the theme of the section\n"
+    "3. Conclusion (## level)\n   - Synthesis of findings\n   - Potential recommendations or next steps\n"
+    "</document_structure>\n\n"
+    "<planning_rules>\n"
+    "- Always break it down into multiple steps\n"
+    "- Assess the different sources and whether they are useful for any steps needed to answer the query\n"
+    "- Create the best report that weighs all the evidence from the sources\n"
+    "- Use the current date supplied in the first user message to contextualize findings\n"
+    "- Make sure that your final report addresses all parts of the query\n"
+    "- Communicate a brief high-level plan in the introduction; do not reveal chain-of-thought.\n"
+    "- When referencing sources during analysis, you should still refer to them by index with brackets and follow <citations>\n"
+    "- As a final step, review your planned report structure and ensure it completely answers the query.\n"
+    "</planning_rules>\n\n"
+)
+
+FILTERER_SYSTEM_PROMPT = (
+    "You are Nymbot Filterer, an analyst who selects the most relevant sources for a research task. "
+    "You will be given a summary of the research topic (and optional search queries) followed by multiple fetched documents. "
+    "Each document includes its URL and a truncated excerpt. Evaluate how well each source helps answer the research topic. "
+    "Return only the URLs that should be used for the final research step. Output plain text with exactly one URL per line and no additional commentary, bullets, numbering, or explanations. "
+    "If no sources are relevant, return an empty string."
+)
+
+
+class SlowHost(Exception):
+    pass
+
+
+def _normalize_query(q: str) -> str:
+    if not q:
+        return ""
+    repl = {"“": '"', "”": '"', "‘": "'", "’": "'", "`": "'"}
+    for key, value in repl.items():
+        q = q.replace(key, value)
+    q = re.sub(r"\s+", " ", q)
+    q = re.sub(r'"\s+"', " ", q)
+    q = q.strip().strip('"').strip()
+    return q
+
+
+def _search_urls_only(query: str, max_results: int) -> list[str]:
+    if not query or not query.strip() or max_results <= 0:
+        return []
+    urls: list[str] = []
+    try:
+        _search_rate_limiter.acquire()
+        with DDGS() as ddgs:
+            for item in ddgs.text(query, region="wt-wt", safesearch="moderate", max_results=max_results):
+                url = (item.get("href") or item.get("url") or "").strip()
+                if url:
+                    urls.append(url)
+    except Exception:
+        pass
+    seen = set()
+    deduped = []
+    for url in urls:
+        if url not in seen:
+            seen.add(url)
+            deduped.append(url)
+    return deduped
+
+
+def _fetch_page_markdown_fast(url: str, max_chars: int = 3000, timeout: float = 10.0) -> str:
+    try:
+        resp = _http_get_enhanced(url, timeout=timeout, skip_rate_limit=True)
+        resp.raise_for_status()
+    except requests.exceptions.RequestException as exc:
+        msg = str(exc)
+        if "timed out" in msg.lower():
+            raise SlowHost(msg) from exc
+        return ""
+    final_url = str(resp.url)
+    ctype = resp.headers.get("Content-Type", "")
+    if "html" not in ctype.lower():
+        return ""
+    resp.encoding = resp.encoding or resp.apparent_encoding
+    html = resp.text
+    soup = BeautifulSoup(html, "lxml")
+    md_text = _fullpage_markdown_from_soup(soup, final_url, "")
+    if max_chars > 0 and len(md_text) > max_chars:
+        md_text = md_text[:max_chars]
+    return md_text
+
+
+def _truncate_join(parts: List[str], max_chars: int) -> Tuple[str, bool]:
+    out = []
+    total = 0
+    truncated = False
+    for part in parts:
+        if not part:
+            continue
+        if total + len(part) > max_chars:
+            out.append(part[: max(0, max_chars - total)])
+            truncated = True
+            break
+        out.append(part)
+        total += len(part)
+    return ("\n\n".join(out), truncated)
+
+
+def _build_research_prompt(summary: str, queries: List[str], url_list: List[str], pages_map: Dict[str, str]) -> str:
+    sources_blocks: List[str] = []
+    indexed_urls: List[str] = []
+    for idx, url in enumerate(url_list, start=1):
+        text = pages_map.get(url, "").strip()
+        if not text:
+            continue
+        indexed_urls.append(f"[{idx}] {url}")
+        sources_blocks.append(f"[Source {idx}] URL: {url}\n\n{text}")
+    sources_joined, truncated = _truncate_join(sources_blocks, max_chars=100_000)
+    prompt_parts: List[str] = []
+    prompt_parts.append("<user_query_summary>\n" + (summary or "") + "\n</user_query_summary>\n")
+    populated = [q for q in queries if q and q.strip()]
+    if populated:
+        prompt_parts.append("<search_queries>\n" + "\n".join(f"- {q.strip()}" for q in populated) + "\n</search_queries>\n")
+    if indexed_urls:
+        prompt_parts.append("<sources_list>\n" + "\n".join(indexed_urls) + "\n</sources_list>\n")
+    prompt_parts.append("<fetched_documents>\n" + sources_joined + ("\n\n[NOTE] Sources truncated due to context limits." if truncated else "") + "\n</fetched_documents>")
+    return "\n\n".join(prompt_parts)
+
+
+def _build_filter_prompt(summary: str, queries: List[str], pages_map: Dict[str, str]) -> str:
+    populated = [q for q in queries if q and q.strip()]
+    summary_text = summary or ""
+    prompt_sections: List[str] = []
+    prompt_sections.append("<research_topic_summary>\n" + summary_text + "\n</research_topic_summary>")
+    if populated:
+        prompt_sections.append("<search_queries>\n" + "\n".join(populated) + "\n</search_queries>")
+    sources: List[str] = []
+    for idx, (url, text) in enumerate(pages_map.items(), start=1):
+        content = text.strip()
+        if not content:
+            continue
+        sources.append(f"[Source {idx}] URL: {url}\n\n{content}")
+    sources_joined, truncated = _truncate_join(sources, max_chars=60_000)
+    prompt_sections.append("<candidate_sources>\n" + sources_joined + ("\n\n[NOTE] Sources truncated due to context limits." if truncated else "") + "\n</candidate_sources>")
+    prompt_sections.append(
+        "<task>\nIdentify which of the provided URLs should be retained for the final research synthesis. "
+        "Consider coverage, credibility, and relevance to the research topic. "
+        "Return ONLY the URLs you choose, with one URL per line and no additional text.\n</task>"
+    )
+    return "\n\n".join(prompt_sections)
+
+
+def _parse_filterer_output(raw: str, allowed_urls: List[str]) -> List[str]:
+    if not raw:
+        return []
+    allowed_set = {url.strip(): idx for idx, url in enumerate(allowed_urls)}
+    found_indices: set[int] = set()
+    for line in raw.splitlines():
+        candidate = line.strip()
+        if not candidate:
+            continue
+        if candidate in allowed_set:
+            found_indices.add(allowed_set[candidate])
+            continue
+        match = re.search(r"https?://[^\s]+", candidate)
+        if not match:
+            continue
+        url = match.group(0).rstrip(".,);]")
+        if url in allowed_set:
+            found_indices.add(allowed_set[url])
+    selected = [allowed_urls[idx] for idx in sorted(found_indices)]
+    return selected
+
+
+def _write_report_tmp(text: str) -> str:
+    filename = f"research_report_{uuid.uuid4().hex}.txt"
+    path = os.path.join(ROOT_DIR, filename)
+    with open(path, "w", encoding="utf-8") as file:
+        file.write(text)
+    return path
+
+
+def _fetch_pages_within_budget(urls: List[str], char_limit: int, time_left_fn: Callable[[], float]) -> OrderedDict:
+    pages: dict[str, str] = {}
+    if not urls:
+        return OrderedDict()
+    queue = deque(urls)
+    attempts: dict[str, int] = {url: 0 for url in urls}
+    max_attempts = 2
+    max_workers = min(12, max(4, len(urls)))
+    in_flight: dict[Future, str] = {}
+    delayed: list[tuple[float, str]] = []
+
+    def schedule_next(executor: ThreadPoolExecutor) -> None:
+        while queue and len(in_flight) < max_workers:
+            url = queue.popleft()
+            if url in pages:
+                continue
+            attempts.setdefault(url, 0)
+            if attempts[url] >= max_attempts:
+                continue
+            attempts[url] += 1
+            tl = time_left_fn()
+            if tl <= 0.1:
+                return
+            per_timeout = 10.0 if tl > 15 else (5.0 if tl > 8 else 2.0)
+            future = executor.submit(_fetch_page_markdown_fast, url, char_limit, per_timeout)
+            in_flight[future] = url
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        schedule_next(executor)
+        while (in_flight or queue or delayed) and time_left_fn() > 0.2:
+            now = time.time()
+            if delayed:
+                ready: list[tuple[float, str]] = []
+                not_ready: list[tuple[float, str]] = []
+                for ready_time, delayed_url in delayed:
+                    (ready if ready_time <= now else not_ready).append((ready_time, delayed_url))
+                delayed = not_ready
+                for _, delayed_url in ready:
+                    queue.append(delayed_url)
+                if ready:
+                    schedule_next(executor)
+            done = [future for future in list(in_flight.keys()) if future.done()]
+            if not done:
+                if not queue and delayed:
+                    next_ready = min((t for t, _ in delayed), default=time.time())
+                    sleep_for = max(0.0, next_ready - time.time())
+                    time.sleep(max(0.02, min(0.25, sleep_for)))
+                else:
+                    time.sleep(0.05)
+                continue
+            for future in done:
+                url = in_flight.pop(future)
+                try:
+                    md = future.result()
+                    if md and not md.startswith("Unsupported content type") and not md.startswith("An error occurred"):
+                        pages[url] = md
+                        try:
+                            print(f"[FETCH OK] {url} (chars={len(md)})", flush=True)
+                        except Exception:
+                            pass
+                except SlowHost:
+                    if time_left_fn() > 5.0:
+                        delayed.append((time.time() + 3.0, url))
+                except Exception:
+                    pass
+            schedule_next(executor)
+    ordered = OrderedDict((url, pages[url]) for url in urls if url in pages)
+    return ordered
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Deep_Research(
+    summary: Annotated[str, "Summarization of research topic (one or more sentences)."],
+    query1: Annotated[str, "DDG Search Query 1"],
+    max1: Annotated[int, "Max results for Query 1 (1-50)"] = 10,
+    query2: Annotated[str, "DDG Search Query 2"] = "",
+    max2: Annotated[int, "Max results for Query 2 (1-50)"] = 10,
+    query3: Annotated[str, "DDG Search Query 3"] = "",
+    max3: Annotated[int, "Max results for Query 3 (1-50)"] = 10,
+    query4: Annotated[str, "DDG Search Query 4"] = "",
+    max4: Annotated[int, "Max results for Query 4 (1-50)"] = 10,
+    query5: Annotated[str, "DDG Search Query 5"] = "",
+    max5: Annotated[int, "Max results for Query 5 (1-50)"] = 10,
+) -> tuple[str, str, str]:
+    _log_call_start(
+        "Deep_Research",
+        summary=_truncate_for_log(summary or "", 200),
+        queries=[q for q in [query1, query2, query3, query4, query5] if q],
+    )
+    if not HF_TEXTGEN_TOKEN:
+        _log_call_end("Deep_Research", "error=missing HF token")
+        raise gr.Error("Please provide a `HF_READ_TOKEN` to enable Deep Research.")
+    queries = [
+        _normalize_query(query1 or ""),
+        _normalize_query(query2 or ""),
+        _normalize_query(query3 or ""),
+        _normalize_query(query4 or ""),
+        _normalize_query(query5 or ""),
+    ]
+    reqs = [
+        max(1, min(50, int(max1))),
+        max(1, min(50, int(max2))),
+        max(1, min(50, int(max3))),
+        max(1, min(50, int(max4))),
+        max(1, min(50, int(max5))),
+    ]
+    total_requested = sum(reqs)
+    if total_requested > 50:
+        reqs = [10, 10, 10, 10, 10]
+    start_ts = time.time()
+    budget_seconds = 55.0
+    deadline = start_ts + budget_seconds
+
+    def time_left() -> float:
+        return max(0.0, deadline - time.time())
+
+    now_dt = datetime.now().astimezone()
+    date_str = now_dt.strftime("%A, %B %d, %Y %I:%M %p %Z").strip()
+    if not date_str:
+        date_str = now_dt.isoformat()
+
+    all_urls: list[str] = []
+    tasks = []
+    with ThreadPoolExecutor(max_workers=min(5, sum(1 for q in queries if q.strip())) or 1) as executor:
+        for query, count in zip(queries, reqs):
+            if not query.strip():
+                continue
+            tasks.append(executor.submit(_search_urls_only, query.strip(), count))
+        for future in as_completed(tasks):
+            try:
+                urls = future.result() or []
+            except Exception:
+                urls = []
+            for url in urls:
+                if url not in all_urls:
+                    all_urls.append(url)
+            if len(all_urls) >= 50:
+                break
+            if time_left() <= 0.5:
+                break
+    if len(all_urls) > 50:
+        all_urls = all_urls[:50]
+    blacklist = {
+        "homedepot.com",
+        "tractorsupply.com",
+        "mcmaster.com",
+        "mrchain.com",
+        "answers.com",
+        "city-data.com",
+        "dictionary.cambridge.org",
+    }
+
+    def _domain(url: str) -> str:
+        try:
+            return urlparse(url).netloc.lower()
+        except Exception:
+            return ""
+
+    all_urls = [url for url in all_urls if _domain(url) not in blacklist]
+    skip_exts = (
+        ".pdf",
+        ".ppt",
+        ".pptx",
+        ".doc",
+        ".docx",
+        ".xls",
+        ".xlsx",
+        ".zip",
+        ".gz",
+        ".tgz",
+        ".bz2",
+        ".7z",
+        ".rar",
+    )
+
+    def _skip_url(url: str) -> bool:
+        try:
+            path = urlparse(url).path.lower()
+        except Exception:
+            return False
+        return any(path.endswith(ext) for ext in skip_exts)
+
+    all_urls = [url for url in all_urls if not _skip_url(url)]
+    truncated_pages = OrderedDict()
+    if all_urls and time_left() > 0.2:
+        truncated_pages = _fetch_pages_within_budget(all_urls, 3000, time_left)
+    print(
+        f"[PIPELINE] Initial fetch complete: candidates={len(all_urls)}, truncated_documents={len(truncated_pages)}, time_left={time_left():.2f}s",
+        flush=True,
+    )
+
+    def _invoke_chat(messages, provider: str, max_tokens: int, temp: float, top_p: float):
+        client = InferenceClient(provider=provider, api_key=HF_TEXTGEN_TOKEN)
+        return client.chat.completions.create(
+            model="zai-org/GLM-4.7",
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temp,
+            top_p=top_p,
+        )
+
+    filtered_urls: List[str] = list(truncated_pages.keys())
+    filter_output = ""
+    filter_used_fallback = False
+    filter_success = False
+    if truncated_pages and time_left() > 3.0:
+        filter_prompt = _build_filter_prompt(summary or "", [q for q in queries if q.strip()], truncated_pages)
+        filter_messages = [
+            {"role": "system", "content": FILTERER_SYSTEM_PROMPT},
+            {"role": "user", "content": f"The current date is {date_str}. Consider how recent each source is when deciding relevance."},
+            {"role": "user", "content": filter_prompt},
+        ]
+        filter_completion = None
+        try:
+            print("[FILTER] Attempt 1: provider=cerebras, max_tokens=2048", flush=True)
+            filter_completion = _invoke_chat(filter_messages, "cerebras", 2048, 0.2, 0.9)
+        except Exception as exc1:
+            print(f"[FILTER] Attempt 1 failed: {str(exc1)[:200]}", flush=True)
+            try:
+                print("[FILTER] Attempt 2: provider=auto, max_tokens=2048", flush=True)
+                filter_completion = _invoke_chat(filter_messages, "auto", 2048, 0.2, 0.9)
+            except Exception as exc2:
+                print(f"[FILTER] Attempt 2 failed: {str(exc2)[:200]}", flush=True)
+        if filter_completion and filter_completion.choices:
+            filter_output = filter_completion.choices[0].message.content or ""
+            filtered_urls = _parse_filterer_output(filter_output, list(truncated_pages.keys()))
+            filter_success = bool(filter_output.strip()) and bool(filtered_urls)
+    if not filtered_urls:
+        filter_used_fallback = True
+        fallback_count = min(8, len(truncated_pages))
+        filtered_urls = list(truncated_pages.keys())[:fallback_count]
+    max_final_urls = 20
+    if len(filtered_urls) > max_final_urls:
+        filter_used_fallback = True
+        filtered_urls = filtered_urls[:max_final_urls]
+    if not filter_success:
+        filter_used_fallback = True
+    print(
+        f"[FILTER] Selected URLs={len(filtered_urls)}, fallback={filter_used_fallback}, time_left={time_left():.2f}s",
+        flush=True,
+    )
+
+    final_pages_fetched = OrderedDict()
+    if filtered_urls and time_left() > 0.2:
+        final_pages_fetched = _fetch_pages_within_budget(filtered_urls, 8000, time_left)
+    merged_pages = OrderedDict()
+    for url in filtered_urls:
+        content = final_pages_fetched.get(url) or truncated_pages.get(url) or ""
+        if content:
+            merged_pages[url] = content
+    pages = merged_pages
+    print(
+        f"[PIPELINE] Final fetch complete: retained_documents={len(pages)}, time_left={time_left():.2f}s",
+        flush=True,
+    )
+    prompt = _build_research_prompt(summary=summary or "", queries=[q for q in queries if q.strip()], url_list=list(pages.keys()), pages_map=pages)
+    system_message = {"role": "system", "content": RESEARCHER_SYSTEM_PROMPT}
+    date_message = {"role": "user", "content": f"The current date is {date_str}. Return only the research report."}
+    messages = [
+        system_message,
+        date_message,
+        {"role": "user", "content": prompt},
+    ]
+    try:
+        prompt_chars = len(prompt)
+    except Exception:
+        prompt_chars = -1
+    print(f"[PIPELINE] Fetch complete: pages={len(pages)}, unique_urls={len(pages.keys())}, prompt_chars={prompt_chars}", flush=True)
+    print("[PIPELINE] Starting inference (provider=cerebras, model=zai-org/GLM-4.7)", flush=True)
+
+    try:
+        print("[LLM] Attempt 1: provider=cerebras, max_tokens=32768", flush=True)
+        completion = _invoke_chat(messages, "cerebras", max_tokens=32768, temp=0.3, top_p=0.95)
+    except Exception as exc1:
+        print(f"[LLM] Attempt 1 failed: {str(exc1)[:200]}", flush=True)
+        try:
+            prompt2 = _build_research_prompt(
+                summary=summary or "",
+                queries=[q for q in queries if q.strip()],
+                url_list=list(pages.keys())[:30],
+                pages_map={key: pages[key] for key in list(pages.keys())[:30]},
+            )
+            messages = [
+                system_message,
+                date_message,
+                {"role": "user", "content": prompt2},
+            ]
+            print("[LLM] Attempt 2: provider=cerebras (trimmed), max_tokens=16384", flush=True)
+            completion = _invoke_chat(messages, "cerebras", max_tokens=16384, temp=0.7, top_p=0.95)
+        except Exception as exc2:
+            print(f"[LLM] Attempt 2 failed: {str(exc2)[:200]}", flush=True)
+            try:
+                print("[LLM] Attempt 3: provider=auto, max_tokens=8192", flush=True)
+                completion = _invoke_chat(messages, "auto", max_tokens=8192, temp=0.7, top_p=0.95)
+            except Exception as exc3:
+                _log_call_end("Deep_Research", f"error={_truncate_for_log(str(exc3), 260)}")
+                raise gr.Error(f"Researcher model call failed: {exc3}")
+    raw = completion.choices[0].message.content or ""
+    try:
+        no_think = re.sub(r"<think>[\s\S]*?<\\/think>", "", raw, flags=re.IGNORECASE)
+        no_think = re.sub(r"<\\/?think>", "", no_think, flags=re.IGNORECASE)
+    except Exception:
+        no_think = raw
+    try:
+        paragraphs = [p for p in re.split(r"\n\s*\n", no_think) if p.strip()]
+        keep: List[str] = []
+        removed = 0
+        planning_re = re.compile(r"\b(let me|now i(?:'ll| will)?|first,|i will now|i will|i'll|let's|now let me|i need to|now i'll|now i will)\b", re.IGNORECASE)
+        for paragraph in paragraphs:
+            if planning_re.search(paragraph):
+                removed += 1
+                continue
+            keep.append(paragraph)
+        report = "\n\n".join(keep).strip()
+        if not report:
+            report = no_think.strip()
+    except Exception:
+        report = no_think
+        removed = 0
+    report = re.sub(r"\n\s*\n\s*\n+", "\n\n", report)
+    try:
+        print(f"[POSTPROCESS] removed_planning_paragraphs={removed}, raw_chars={len(raw)}, final_chars={len(report)}", flush=True)
+    except Exception:
+        pass
+    links_text = "\n".join([f"[{i+1}] {url}" for i, url in enumerate(pages.keys())])
+    if links_text:
+        sources_section = "\n\n## Sources\n" + "\n".join([f"[{i+1}] {url}" for i, url in enumerate(pages.keys())])
+        report = report.rstrip() + sources_section
+    file_path = _write_report_tmp(report)
+    elapsed = time.time() - start_ts
+    print(f"[TIMING] Deep_Research elapsed: {elapsed:.2f}s", flush=True)
+    _log_call_end("Deep_Research", f"urls={len(pages)} file={os.path.basename(file_path)} duration={elapsed:.2f}s")
+    return report, links_text, file_path
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Deep_Research,
+        inputs=[
+            gr.Textbox(label="Summarization of research topic", lines=3, placeholder="Briefly summarize the research topic or user question", info="Summarization of research topic (one or more sentences)"),
+            gr.Textbox(label="DDG Search Query 1", max_lines=1, info="DDG Search Query 1"),
+            gr.Slider(1, 50, value=10, step=1, label="Max results (Q1)", info="Max results for Query 1 (1-50)"),
+            gr.Textbox(label="DDG Search Query 2", value="", max_lines=1, info="DDG Search Query 2"),
+            gr.Slider(1, 50, value=10, step=1, label="Max results (Q2)", info="Max results for Query 2 (1-50)"),
+            gr.Textbox(label="DDG Search Query 3", value="", max_lines=1, info="DDG Search Query 3"),
+            gr.Slider(1, 50, value=10, step=1, label="Max results (Q3)", info="Max results for Query 3 (1-50)"),
+            gr.Textbox(label="DDG Search Query 4", value="", max_lines=1, info="DDG Search Query 4"),
+            gr.Slider(1, 50, value=10, step=1, label="Max results (Q4)", info="Max results for Query 4 (1-50)"),
+            gr.Textbox(label="DDG Search Query 5", value="", max_lines=1, info="DDG Search Query 5"),
+            gr.Slider(1, 50, value=10, step=1, label="Max results (Q5)", info="Max results for Query 5 (1-50)"),
+        ],
+        outputs=[
+            gr.Markdown(label="Research Report"),
+            gr.Textbox(label="Fetched Links", lines=8),
+            gr.File(label="Download Research Report", file_count="single"),
+        ],
+        title="Deep Research",
+        description=(
+            "<div style=\"text-align:center\">Generate a research report based on dozens of sources. Default model is GLM-4.7</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Deep_Research", "build_interface"]

Modules/Generate_Image.py

@@ -1,132 +1,132 @@
-from __future__ import annotations
-
-import os
-import uuid
-import random
-from typing import Annotated
-
-import gradio as gr
-from PIL import Image
-from huggingface_hub import InferenceClient
-from ._core import ROOT_DIR, get_hf_token, DEFAULT_PROVIDERS, handle_hf_error
-
-from app import _log_call_end, _log_call_start, _truncate_for_log
-from ._docstrings import autodoc
-
-HF_API_TOKEN = get_hf_token()
-
-# Single source of truth for the LLM-facing tool description
-TOOL_SUMMARY = (
-    "Generate an image from a text prompt via Hugging Face serverless inference; "
-    "tunable model/steps/guidance/size, supports negative prompt and seed; returns a PIL.Image. "
-    "Return the generated media to the user in this format `![Alt text](URL)`."
-)
-
-
-@autodoc(
-    summary=TOOL_SUMMARY,
-)
-def Generate_Image(
-    prompt: Annotated[str, "Text description of the image to generate."],
-    model_id: Annotated[str, "Hugging Face model id in the form 'creator/model-name' (e.g., Tongyi-MAI/Z-Image-Turbo)."] = "Tongyi-MAI/Z-Image-Turbo",
-    negative_prompt: Annotated[str, "What should NOT appear in the image."] = (
-        "(deformed, distorted, disfigured), poorly drawn, bad anatomy, wrong anatomy, extra limb, "
-        "missing limb, floating limbs, (mutated hands and fingers), disconnected limbs, mutation, "
-        "mutated, ugly, disgusting, blurry, amputation, misspellings, typos"
-    ),
-    steps: Annotated[int, "Number of denoising steps (1–100). Higher = slower, potentially higher quality."] = 35,
-    cfg_scale: Annotated[float, "Classifier-free guidance scale (1–20). Higher = follow the prompt more closely."] = 7.0,
-    seed: Annotated[int, "Random seed for reproducibility. Use -1 for a random seed per call."] = -1,
-    width: Annotated[int, "Output width in pixels (64–1216, multiple of 32 recommended)."] = 1024,
-    height: Annotated[int, "Output height in pixels (64–1216, multiple of 32 recommended)."] = 1024,
-    sampler: Annotated[str, "Sampling method label (UI only). Common options: 'DPM++ 2M Karras', 'DPM++ SDE Karras', 'Euler', 'Euler a', 'Heun', 'DDIM'."] = "DPM++ 2M Karras",
-) -> str:
-    _log_call_start(
-        "Generate_Image",
-        prompt=_truncate_for_log(prompt, 200),
-        model_id=model_id,
-        steps=steps,
-        cfg_scale=cfg_scale,
-        seed=seed,
-        size=f"{width}x{height}",
-    )
-    if not prompt or not prompt.strip():
-        _log_call_end("Generate_Image", "error=empty prompt")
-        raise gr.Error("Please provide a non-empty prompt.")
-    enhanced_prompt = f"{prompt} | ultra detail, ultra elaboration, ultra quality, perfect."
-    last_error: Exception | None = None
-    for provider in DEFAULT_PROVIDERS:
-        try:
-            client = InferenceClient(api_key=HF_API_TOKEN, provider=provider)
-            image = client.text_to_image(
-                prompt=enhanced_prompt,
-                negative_prompt=negative_prompt,
-                model=model_id,
-                width=width,
-                height=height,
-                num_inference_steps=steps,
-                guidance_scale=cfg_scale,
-                seed=seed if seed != -1 else random.randint(1, 1_000_000_000),
-            )
-            
-            filename = f"image_{uuid.uuid4().hex[:8]}.png"
-            output_path = os.path.join(ROOT_DIR, filename)
-            image.save(output_path)
-            
-            _log_call_end("Generate_Image", f"provider={provider} size={image.size} saved_to={filename}")
-            return output_path
-        except Exception as exc:
-            last_error = exc
-            continue
-    
-    msg = str(last_error) if last_error else "Unknown error"
-    _log_call_end("Generate_Image", f"error={_truncate_for_log(msg, 200)}")
-    handle_hf_error(msg, model_id, context="Image generation")
-
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Generate_Image,
-        inputs=[
-            gr.Textbox(label="Prompt", placeholder="Enter a prompt", lines=2, info="Text description of the image to generate"),
-            gr.Textbox(
-                label="Model",
-                value="Tongyi-MAI/Z-Image-Turbo",
-                placeholder="creator/model-name",
-                max_lines=1,
-                info="<a href=\"https://huggingface.co/models?pipeline_tag=text-to-image&inference_provider=nebius,cerebras,novita,fireworks-ai,together,fal-ai,groq,featherless-ai,nscale,hyperbolic,sambanova,cohere,replicate,scaleway,publicai,hf-inference&sort=trending\" target=\"_blank\" rel=\"noopener noreferrer\">Browse models</a>",
-            ),
-            gr.Textbox(
-                label="Negative Prompt",
-                value=(
-                    "(deformed, distorted, disfigured), poorly drawn, bad anatomy, wrong anatomy, extra limb, "
-                    "missing limb, floating limbs, (mutated hands and fingers), disconnected limbs, mutation, "
-                    "mutated, ugly, disgusting, blurry, amputation, misspellings, typos"
-                ),
-                lines=2,
-                info="What should NOT appear in the image",
-            ),
-            gr.Slider(minimum=1, maximum=100, value=35, step=1, label="Steps", info="Number of denoising steps (1–100)"),
-            gr.Slider(minimum=1.0, maximum=20.0, value=7.0, step=0.1, label="CFG Scale", info="Classifier-free guidance scale (1–20)"),
-            gr.Slider(minimum=-1, maximum=1_000_000_000, value=-1, step=1, label="Seed (-1 = random)", info="Random seed for reproducibility"),
-            gr.Slider(minimum=64, maximum=1216, value=1024, step=32, label="Width", info="Output width in pixels"),
-            gr.Slider(minimum=64, maximum=1216, value=1024, step=32, label="Height", info="Output height in pixels"),
-            gr.Radio(
-                label="Sampler",
-                value="DPM++ 2M Karras",
-                choices=["DPM++ 2M Karras", "DPM++ SDE Karras", "Euler", "Euler a", "Heun", "DDIM"],
-                info="Sampling method",
-            ),
-        ],
-        outputs=gr.Image(label="Generated Image"),
-        title="Generate Image",
-        description=(
-            "<div style=\"text-align:center\">Generate images via Hugging Face serverless inference. "
-            "Default model is Z-Image-Turbo.</div>"
-        ),
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-    )
-
-
-__all__ = ["Generate_Image", "build_interface"]
+from __future__ import annotations
+
+import os
+import uuid
+import random
+from typing import Annotated
+
+import gradio as gr
+from PIL import Image
+from huggingface_hub import InferenceClient
+from ._core import ROOT_DIR, get_hf_token, DEFAULT_PROVIDERS, handle_hf_error
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+HF_API_TOKEN = get_hf_token()
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Generate an image from a text prompt via Hugging Face serverless inference; "
+    "tunable model/steps/guidance/size, supports negative prompt and seed; returns a PIL.Image. "
+    "Return the generated media to the user in this format `![Alt text](URL)`."
+)
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Generate_Image(
+    prompt: Annotated[str, "Text description of the image to generate."],
+    model_id: Annotated[str, "Hugging Face model id in the form 'creator/model-name' (e.g., Tongyi-MAI/Z-Image-Turbo)."] = "Tongyi-MAI/Z-Image-Turbo",
+    negative_prompt: Annotated[str, "What should NOT appear in the image."] = (
+        "(deformed, distorted, disfigured), poorly drawn, bad anatomy, wrong anatomy, extra limb, "
+        "missing limb, floating limbs, (mutated hands and fingers), disconnected limbs, mutation, "
+        "mutated, ugly, disgusting, blurry, amputation, misspellings, typos"
+    ),
+    steps: Annotated[int, "Number of denoising steps (1–100). Higher = slower, potentially higher quality."] = 35,
+    cfg_scale: Annotated[float, "Classifier-free guidance scale (1–20). Higher = follow the prompt more closely."] = 7.0,
+    seed: Annotated[int, "Random seed for reproducibility. Use -1 for a random seed per call."] = -1,
+    width: Annotated[int, "Output width in pixels (64–1216, multiple of 32 recommended)."] = 1024,
+    height: Annotated[int, "Output height in pixels (64–1216, multiple of 32 recommended)."] = 1024,
+    sampler: Annotated[str, "Sampling method label (UI only). Common options: 'DPM++ 2M Karras', 'DPM++ SDE Karras', 'Euler', 'Euler a', 'Heun', 'DDIM'."] = "DPM++ 2M Karras",
+) -> str:
+    _log_call_start(
+        "Generate_Image",
+        prompt=_truncate_for_log(prompt, 200),
+        model_id=model_id,
+        steps=steps,
+        cfg_scale=cfg_scale,
+        seed=seed,
+        size=f"{width}x{height}",
+    )
+    if not prompt or not prompt.strip():
+        _log_call_end("Generate_Image", "error=empty prompt")
+        raise gr.Error("Please provide a non-empty prompt.")
+    enhanced_prompt = f"{prompt} | ultra detail, ultra elaboration, ultra quality, perfect."
+    last_error: Exception | None = None
+    for provider in DEFAULT_PROVIDERS:
+        try:
+            client = InferenceClient(api_key=HF_API_TOKEN, provider=provider)
+            image = client.text_to_image(
+                prompt=enhanced_prompt,
+                negative_prompt=negative_prompt,
+                model=model_id,
+                width=width,
+                height=height,
+                num_inference_steps=steps,
+                guidance_scale=cfg_scale,
+                seed=seed if seed != -1 else random.randint(1, 1_000_000_000),
+            )
+            
+            filename = f"image_{uuid.uuid4().hex[:8]}.png"
+            output_path = os.path.join(ROOT_DIR, filename)
+            image.save(output_path)
+            
+            _log_call_end("Generate_Image", f"provider={provider} size={image.size} saved_to={filename}")
+            return output_path
+        except Exception as exc:
+            last_error = exc
+            continue
+    
+    msg = str(last_error) if last_error else "Unknown error"
+    _log_call_end("Generate_Image", f"error={_truncate_for_log(msg, 200)}")
+    handle_hf_error(msg, model_id, context="Image generation")
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Generate_Image,
+        inputs=[
+            gr.Textbox(label="Prompt", placeholder="Enter a prompt", lines=2, info="Text description of the image to generate"),
+            gr.Textbox(
+                label="Model",
+                value="Tongyi-MAI/Z-Image-Turbo",
+                placeholder="creator/model-name",
+                max_lines=1,
+                info="<a href=\"https://huggingface.co/models?pipeline_tag=text-to-image&inference_provider=nebius,cerebras,novita,fireworks-ai,together,fal-ai,groq,featherless-ai,nscale,hyperbolic,sambanova,cohere,replicate,scaleway,publicai,hf-inference&sort=trending\" target=\"_blank\" rel=\"noopener noreferrer\">Browse models</a>",
+            ),
+            gr.Textbox(
+                label="Negative Prompt",
+                value=(
+                    "(deformed, distorted, disfigured), poorly drawn, bad anatomy, wrong anatomy, extra limb, "
+                    "missing limb, floating limbs, (mutated hands and fingers), disconnected limbs, mutation, "
+                    "mutated, ugly, disgusting, blurry, amputation, misspellings, typos"
+                ),
+                lines=2,
+                info="What should NOT appear in the image",
+            ),
+            gr.Slider(minimum=1, maximum=100, value=35, step=1, label="Steps", info="Number of denoising steps (1–100)"),
+            gr.Slider(minimum=1.0, maximum=20.0, value=7.0, step=0.1, label="CFG Scale", info="Classifier-free guidance scale (1–20)"),
+            gr.Slider(minimum=-1, maximum=1_000_000_000, value=-1, step=1, label="Seed (-1 = random)", info="Random seed for reproducibility"),
+            gr.Slider(minimum=64, maximum=1216, value=1024, step=32, label="Width", info="Output width in pixels"),
+            gr.Slider(minimum=64, maximum=1216, value=1024, step=32, label="Height", info="Output height in pixels"),
+            gr.Radio(
+                label="Sampler",
+                value="DPM++ 2M Karras",
+                choices=["DPM++ 2M Karras", "DPM++ SDE Karras", "Euler", "Euler a", "Heun", "DDIM"],
+                info="Sampling method",
+            ),
+        ],
+        outputs=gr.Image(label="Generated Image"),
+        title="Generate Image",
+        description=(
+            "<div style=\"text-align:center\">Generate images via Hugging Face serverless inference. "
+            "Default model is Z-Image-Turbo.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Generate_Image", "build_interface"]

Modules/Memory_Manager.py

@@ -1,253 +1,316 @@
+"""
+Memory Manager - Graphiti Knowledge Graph Interface.
+
+Provides unified memory operations using the same Graphiti instance
+configured for Claude Code's Graphiti MCP server.
+
+Configuration (must match Graphiti MCP):
+- FALKORDB_URI: redis://localhost:6379 (default)
+- FALKORDB_DATABASE: graphiti (default)
+- MISTRAL_API_KEY: Required for entity extraction
+- GRAPHITI_GROUP_ID: main (default)
+"""
+
 from __future__ import annotations
 
-import json
 import os
-import threading
-import uuid
-from datetime import datetime
-from typing import Annotated, Dict, List, Literal, Optional
+from datetime import datetime, timezone
+from typing import Annotated, Literal, Optional
 
 import gradio as gr
 from ._docstrings import autodoc
 
-_MODULE_DIR = os.path.dirname(os.path.abspath(__file__))
-MEMORY_FILE = os.path.join(os.path.dirname(_MODULE_DIR), "memories.json")
-_MEMORY_LOCK = threading.RLock()
-_MAX_MEMORIES = 10_000
+# Graphiti configuration - matches Graphiti MCP server
+FALKORDB_URI = os.getenv("FALKORDB_URI", "redis://localhost:6379")
+FALKORDB_DATABASE = os.getenv("FALKORDB_DATABASE", "graphiti")
+MISTRAL_API_KEY = os.getenv("MISTRAL_API_KEY", "")
+GRAPHITI_GROUP_ID = os.getenv("GRAPHITI_GROUP_ID", "main")
 
+# Check if Graphiti is available
+GRAPHITI_AVAILABLE = bool(MISTRAL_API_KEY)
 
-def _now_iso() -> str:
-    return datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S")
+# Lazy-loaded Graphiti client
+_graphiti_client = None
 
 
-def _load_memories() -> List[Dict[str, str]]:
-    if not os.path.exists(MEMORY_FILE):
-        return []
-    try:
-        with open(MEMORY_FILE, "r", encoding="utf-8") as file:
-            data = json.load(file)
-        if isinstance(data, list):
-            cleaned: List[Dict[str, str]] = []
-            for item in data:
-                if isinstance(item, dict) and "id" in item and "text" in item:
-                    cleaned.append(item)
-            return cleaned
-        return []
-    except Exception:
+def _get_graphiti_client():
+    """Get or create the Graphiti client (lazy load to avoid import errors)."""
+    global _graphiti_client
+    if _graphiti_client is None and GRAPHITI_AVAILABLE:
         try:
-            backup = MEMORY_FILE + ".corrupt"
-            if not os.path.exists(backup):
-                os.replace(MEMORY_FILE, backup)
-        except Exception:
-            pass
-        return []
-
-
-def _save_memories(memories: List[Dict[str, str]]) -> None:
-    tmp_path = MEMORY_FILE + ".tmp"
-    with open(tmp_path, "w", encoding="utf-8") as file:
-        json.dump(memories, file, ensure_ascii=False, indent=2)
-    os.replace(tmp_path, MEMORY_FILE)
-
-
-def _mem_save(text: str, tags: str) -> str:
-    text_clean = (text or "").strip()
-    if not text_clean:
-        return "Error: memory text is empty."
-    with _MEMORY_LOCK:
-        memories = _load_memories()
-        if memories and memories[-1].get("text") == text_clean:
-            return "Skipped: identical to last stored memory."
-        mem_id = str(uuid.uuid4())
-        entry = {
-            "id": mem_id,
-            "text": text_clean,
-            "timestamp": _now_iso(),
-            "tags": tags.strip(),
-        }
-        memories.append(entry)
-        if len(memories) > _MAX_MEMORIES:
-            overflow = len(memories) - _MAX_MEMORIES
-            memories = memories[overflow:]
-        _save_memories(memories)
-    return f"Memory saved: {mem_id}"
-
-
-def _mem_list(limit: int, include_tags: bool) -> str:
-    limit = max(1, min(200, limit))
-    with _MEMORY_LOCK:
-        memories = _load_memories()
-    if not memories:
-        return "No memories stored yet."
-    chosen = memories[-limit:][::-1]
-    lines: List[str] = []
-    for memory in chosen:
-        base = f"{memory['id'][:8]} [{memory.get('timestamp','?')}] {memory.get('text','')}"
-        if include_tags and memory.get("tags"):
-            base += f" | tags: {memory['tags']}"
-        lines.append(base)
-    omitted = len(memories) - len(chosen)
-    if omitted > 0:
-        lines.append(f"… ({omitted} older memorie{'s' if omitted!=1 else ''} omitted; total={len(memories)})")
-    return "\n".join(lines)
-
-
-def _parse_search_query(query: str) -> Dict[str, List[str]]:
-    import re
-
-    result = {"tag_terms": [], "text_terms": [], "operator": "and"}
-    if not query or not query.strip():
-        return result
-    query = re.sub(r"\s+", " ", query.strip())
-    if re.search(r"\bOR\b", query, re.IGNORECASE):
-        result["operator"] = "or"
-        parts = re.split(r"\s+OR\s+", query, flags=re.IGNORECASE)
-    else:
-        parts = re.split(r"\s+(?:AND\s+)?", query, flags=re.IGNORECASE)
-        parts = [p for p in parts if p.strip() and p.strip().upper() != "AND"]
-    for part in parts:
-        part = part.strip()
-        if not part:
-            continue
-        tag_match = re.match(r"^tag:(.+)$", part, re.IGNORECASE)
-        if tag_match:
-            tag_name = tag_match.group(1).strip()
-            if tag_name:
-                result["tag_terms"].append(tag_name.lower())
-        else:
-            result["text_terms"].append(part.lower())
-    return result
-
-
-def _match_memory_with_query(memory: Dict[str, str], parsed_query: Dict[str, List[str]]) -> bool:
-    tag_terms = parsed_query["tag_terms"]
-    text_terms = parsed_query["text_terms"]
-    operator = parsed_query["operator"]
-    if not tag_terms and not text_terms:
-        return False
-    memory_text = memory.get("text", "").lower()
-    memory_tags = memory.get("tags", "").lower()
-    memory_tag_list = [tag.strip() for tag in memory_tags.split(",") if tag.strip()]
-    tag_matches = [any(tag_term in tag for tag in memory_tag_list) for tag_term in tag_terms]
-    combined_text = memory_text + " " + memory_tags
-    text_matches = [text_term in combined_text for text_term in text_terms]
-    all_matches = tag_matches + text_matches
-    if not all_matches:
-        return False
-    if operator == "or":
-        return any(all_matches)
-    return all(all_matches)
-
-
-def _mem_search(query: str, limit: int) -> str:
-    q = (query or "").strip()
-    if not q:
-        return "Error: empty query."
-    parsed_query = _parse_search_query(q)
-    if not parsed_query["tag_terms"] and not parsed_query["text_terms"]:
-        return "Error: no valid search terms found."
-    limit = max(1, min(200, limit))
-    with _MEMORY_LOCK:
-        memories = _load_memories()
-    matches: List[Dict[str, str]] = []
-    total_matches = 0
-    for memory in reversed(memories):
-        if _match_memory_with_query(memory, parsed_query):
-            total_matches += 1
-            if len(matches) < limit:
-                matches.append(memory)
-    if not matches:
-        return f"No matches for: {query}"
-    lines = [
-        f"{memory['id'][:8]} [{memory.get('timestamp','?')}] {memory.get('text','')}" + (f" | tags: {memory['tags']}" if memory.get('tags') else "")
-        for memory in matches
-    ]
-    omitted = total_matches - len(matches)
-    if omitted > 0:
-        lines.append(f"… ({omitted} additional match{'es' if omitted!=1 else ''} omitted; total_matches={total_matches})")
-    return "\n".join(lines)
-
-
-def _mem_delete(memory_id: str) -> str:
-    key = (memory_id or "").strip().lower()
-    if len(key) < 4:
-        return "Error: supply at least 4 characters of the id."
-    with _MEMORY_LOCK:
-        memories = _load_memories()
-        matched = [memory for memory in memories if memory["id"].lower().startswith(key)]
-        if not matched:
-            return "Memory not found."
-        if len(matched) > 1 and key != matched[0]["id"].lower():
-            sample = ", ".join(memory["id"][:8] for memory in matched[:5])
-            more = "…" if len(matched) > 5 else ""
-            return f"Ambiguous prefix (matches {len(matched)} ids: {sample}{more}). Provide more characters."
-        target_id = matched[0]["id"]
-        memories = [memory for memory in memories if memory["id"] != target_id]
-        _save_memories(memories)
-    return f"Deleted memory: {target_id}"
-
-
-# Single source of truth for the LLM-facing tool description
+            from graphiti_core import Graphiti
+            from graphiti_core.llm_client import OpenAIClient
+            from graphiti_core.driver.falkordb_driver import FalkorDriver
+
+            # Create FalkorDB driver
+            driver = FalkorDriver(
+                uri=FALKORDB_URI,
+                database=FALKORDB_DATABASE,
+            )
+
+            # Create Mistral LLM client (OpenAI-compatible API)
+            llm_client = OpenAIClient(
+                api_key=MISTRAL_API_KEY,
+                base_url="https://api.mistral.ai/v1",
+                model="mistral-large-2411",
+            )
+
+            # Create Graphiti client
+            _graphiti_client = Graphiti(
+                uri=FALKORDB_URI,
+                driver=driver,
+                llm_client=llm_client,
+            )
+        except ImportError as e:
+            print(f"[Memory_Manager] Graphiti not available: {e}")
+            return None
+        except Exception as e:
+            print(f"[Memory_Manager] Failed to initialize Graphiti: {e}")
+            return None
+    return _graphiti_client
+
+
+def _format_timestamp() -> str:
+    """Return current UTC timestamp in ISO format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+# ============================================================================
+# Graphiti Memory Operations
+# ============================================================================
+
+
+def _graphiti_save(text: str, tags: str) -> str:
+    """Save memory to Graphiti knowledge graph."""
+    if not GRAPHITI_AVAILABLE:
+        return "Error: MISTRAL_API_KEY not set. Cannot save to Graphiti."
+
+    client = _get_graphiti_client()
+    if not client:
+        return "Error: Failed to initialize Graphiti client."
+
+    try:
+        # Build episode body with tags
+        episode_body = text.strip()
+        if tags and tags.strip():
+            episode_body = f"{text.strip()}\n\nTags: {tags.strip()}"
+
+        # Add episode to Graphiti
+        import asyncio
+
+        async def _save():
+            return await client.add_episode(
+                name=f"Memory {_format_timestamp()}",
+                episode_body=episode_body,
+                source_description="Memory_Manager tool",
+                group_id=GRAPHITI_GROUP_ID,
+            )
+
+        result = asyncio.run(_save())
+        return f"Memory saved to Graphiti knowledge graph (group: {GRAPHITI_GROUP_ID})"
+    except Exception as e:
+        return f"Error saving to Graphiti: {e}"
+
+
+def _graphiti_list(limit: int, include_tags: bool) -> str:
+    """List recent memories from Graphiti."""
+    if not GRAPHITI_AVAILABLE:
+        return "Error: MISTRAL_API_KEY not set. Cannot access Graphiti."
+
+    client = _get_graphiti_client()
+    if not client:
+        return "Error: Failed to initialize Graphiti client."
+
+    try:
+        import asyncio
+
+        async def _list():
+            # Get episodes from Graphiti
+            return await client.get_episodes(
+                group_ids=[GRAPHITI_GROUP_ID],
+                limit=limit,
+            )
+
+        episodes = asyncio.run(_list())
+
+        if not episodes:
+            return f"No memories found in Graphiti (group: {GRAPHITI_GROUP_ID})"
+
+        lines = [f"Graphiti Memories (group: {GRAPHITI_GROUP_ID})", "-" * 50]
+        for ep in episodes:
+            name = ep.name if hasattr(ep, "name") else "?"
+            created = ep.created_at if hasattr(ep, "created_at") else "?"
+            content = ep.content if hasattr(ep, "content") else str(ep)
+
+            # Extract tags from content if present
+            tags_str = ""
+            if include_tags and "Tags:" in content:
+                parts = content.split("Tags:")
+                if len(parts) > 1:
+                    tags_str = f" | tags: {parts[1].strip()}"
+                    content = parts[0].strip()
+
+            lines.append(f"[{created}] {content[:100]}{'...' if len(content) > 100 else ''}{tags_str}")
+
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error listing from Graphiti: {e}"
+
+
+def _graphiti_search(query: str, limit: int) -> str:
+    """Search memories in Graphiti knowledge graph."""
+    if not GRAPHITI_AVAILABLE:
+        return "Error: MISTRAL_API_KEY not set. Cannot search Graphiti."
+
+    client = _get_graphiti_client()
+    if not client:
+        return "Error: Failed to initialize Graphiti client."
+
+    try:
+        import asyncio
+
+        async def _search():
+            # Use Graphiti's hybrid search
+            return await client.search(
+                query=query,
+                group_ids=[GRAPHITI_GROUP_ID],
+                num_results=limit,
+            )
+
+        results = asyncio.run(_search())
+
+        if not results:
+            return f"No matches found for: {query}"
+
+        lines = [f"Graphiti Search Results for: {query}", "-" * 50]
+
+        for i, result in enumerate(results, 1):
+            if hasattr(result, "fact"):
+                # Edge/fact result
+                source = getattr(result, "source_node", "?")
+                target = getattr(result, "target_node", "?")
+                fact = result.fact
+                lines.append(f"{i}. {source} -> {target}: {fact}")
+            elif hasattr(result, "name"):
+                # Node result
+                name = result.name
+                summary = getattr(result, "summary", "")
+                lines.append(f"{i}. [{name}] {summary[:150]}{'...' if len(summary) > 150 else ''}")
+            else:
+                lines.append(f"{i}. {str(result)[:150]}")
+
+        return "\n".join(lines)
+    except Exception as e:
+        return f"Error searching Graphiti: {e}"
+
+
+def _graphiti_delete(memory_id: str) -> str:
+    """Delete memory from Graphiti (requires episode UUID)."""
+    if not GRAPHITI_AVAILABLE:
+        return "Error: MISTRAL_API_KEY not set. Cannot access Graphiti."
+
+    # Note: Graphiti deletion requires the full episode UUID
+    # This is a simplified implementation
+    return f"Note: To delete from Graphiti, use the Graphiti MCP directly with the episode UUID. Memory deletion is not fully implemented in this interface."
+
+
+# ============================================================================
+# Status Check
+# ============================================================================
+
+
+def _get_status() -> str:
+    """Get Graphiti connection status."""
+    if not GRAPHITI_AVAILABLE:
+        return "Status: MISTRAL_API_KEY not configured"
+
+    client = _get_graphiti_client()
+    if client:
+        return f"Status: Connected to Graphiti\nDatabase: {FALKORDB_DATABASE}\nGroup: {GRAPHITI_GROUP_ID}"
+    return "Status: Failed to initialize Graphiti client"
+
+
+# ============================================================================
+# Main Tool Function
+# ============================================================================
+
+
 TOOL_SUMMARY = (
-    "Manage short text memories (save, list, search, delete) in a local JSON store with tags and simple query language; "
-    "returns a result string (confirmation, listing, matches, or error)."
+    "Manage memories in Graphiti knowledge graph (save, list, search, status). "
+    "Connects to the same Graphiti instance as the Graphiti MCP server. "
+    "Requires MISTRAL_API_KEY for entity extraction and knowledge graph operations."
 )
 
 
-@autodoc(
-    summary=TOOL_SUMMARY,
-)
+@autodoc(summary=TOOL_SUMMARY)
 def Memory_Manager(
-    action: Annotated[Literal["save", "list", "search", "delete"], "Action to perform: save | list | search | delete"],
-    text: Annotated[Optional[str], "Text content (Save only)"] = None,
+    action: Annotated[Literal["save", "list", "search", "status"], "Action: save | list | search | status"] = "list",
+    text: Annotated[Optional[str], "Memory text (Save only)"] = None,
     tags: Annotated[Optional[str], "Comma-separated tags (Save only)"] = None,
-    query: Annotated[Optional[str], "Enhanced search with tag:name syntax, AND/OR operators (Search only)"] = None,
+    query: Annotated[Optional[str], "Search query (Search only)"] = None,
     limit: Annotated[int, "Max results (List/Search only)"] = 20,
-    memory_id: Annotated[Optional[str], "Full UUID or unique prefix (Delete only)"] = None,
-    include_tags: Annotated[bool, "Include tags (List/Search only)"] = True,
+    include_tags: Annotated[bool, "Include tags in output"] = True,
 ) -> str:
-    act = (action or "").lower().strip()
-    text = text or ""
-    tags = tags or ""
-    query = query or ""
-    memory_id = memory_id or ""
+    """
+    Memory Manager - Graphiti Knowledge Graph Interface.
+
+    Connects to the same Graphiti instance used by Claude Code's Graphiti MCP.
+    All memories are stored in the knowledge graph with automatic entity extraction
+    and relationship detection.
+    """
+    act = (action or "list").lower().strip()
+
+    if act == "status":
+        return _get_status()
+
     if act == "save":
-        if not text.strip():
+        text = (text or "").strip()
+        if not text:
             return "Error: 'text' is required when action=save."
-        return _mem_save(text=text, tags=tags)
+        return _graphiti_save(text=text, tags=tags or "")
+
     if act == "list":
-        return _mem_list(limit=limit, include_tags=include_tags)
+        return _graphiti_list(limit=max(1, min(200, limit)), include_tags=include_tags)
+
     if act == "search":
-        if not query.strip():
+        query = (query or "").strip()
+        if not query:
             return "Error: 'query' is required when action=search."
-        return _mem_search(query=query, limit=limit)
-    if act == "delete":
-        if not memory_id.strip():
-            return "Error: 'memory_id' is required when action=delete."
-        return _mem_delete(memory_id=memory_id)
-    return "Error: invalid action (use save|list|search|delete)."
+        return _graphiti_search(query=query, limit=max(1, min(200, limit)))
+
+    return "Error: invalid action (use save|list|search|status)."
 
 
 def build_interface() -> gr.Interface:
+    """Build Gradio interface for Memory Manager."""
+    status_info = _get_status()
+
     return gr.Interface(
         fn=Memory_Manager,
         inputs=[
-            gr.Radio(label="Action", choices=["save", "list", "search", "delete"], value="list", info="Action to perform"),
+            gr.Radio(
+                label="Action",
+                choices=["save", "list", "search", "status"],
+                value="status",
+                info="Action to perform",
+            ),
             gr.Textbox(label="Text", lines=3, info="Memory text (Save only)"),
             gr.Textbox(label="Tags", placeholder="tag1, tag2", max_lines=1, info="Comma-separated tags (Save only)"),
-            gr.Textbox(label="Query", placeholder="tag:work AND tag:project OR meeting", max_lines=1, info="Search query (Search only)"),
+            gr.Textbox(label="Query", placeholder="search terms...", max_lines=1, info="Search query (Search only)"),
             gr.Slider(1, 200, value=20, step=1, label="Limit", info="Max results (List/Search only)"),
-            gr.Textbox(label="Memory ID / Prefix", max_lines=1, info="UUID or prefix (Delete only)"),
-            gr.Checkbox(value=True, label="Include Tags", info="Include tags in output (List/Search only)"),
+            gr.Checkbox(value=True, label="Include Tags", info="Include tags in output"),
         ],
         outputs=gr.Textbox(label="Result", lines=14),
-        title="Memory Manager",
-        description=(
-            "<div style=\"text-align:center\">Lightweight local JSON memory store (no external DB). Choose an Action, fill only the relevant fields, and run.</div>"
-        ),
+        title="Memory Manager - Graphiti",
+        description=f"<div style='text-align:center'><strong>{status_info}</strong><br/>Knowledge graph memory with entity extraction</div>",
         api_description=TOOL_SUMMARY,
         flagging_mode="never",
     )
 
 
-__all__ = ["Memory_Manager", "build_interface", "_load_memories", "_save_memories"]
+__all__ = [
+    "Memory_Manager",
+    "build_interface",
+    "GRAPHITI_AVAILABLE",
+    "GRAPHITI_GROUP_ID",
+]

Modules/ScrapeGraphAI.py

@@ -0,0 +1,779 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Annotated, Any, Literal
+
+import gradio as gr
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._core import _resolve_path
+from ._docstrings import autodoc
+
+TOOL_SUMMARY = (
+    "Scrape and extract structured data from known URLs using ScrapeGraphAI with "
+    "Mistral-only models. Supports single-page extraction, bounded crawl extraction, "
+    "multi-URL extraction, rendered markdown, and image-aware extraction."
+)
+
+ACTION_CHOICES = [
+    "extract",
+    "crawl_extract",
+    "multi_extract",
+    "render_markdown",
+    "vision_extract",
+]
+
+RENDER_CHOICES = ["auto", "browser", "http"]
+
+TEXT_MODEL_ENV = "SCRAPEGRAPH_TEXT_MODEL"
+VISION_MODEL_ENV = "SCRAPEGRAPH_VISION_MODEL"
+DEFAULT_TEXT_MODEL = "mistral-small-latest"
+DEFAULT_VISION_MODEL = "pixtral-12b-latest"
+
+_IMPORT_ERROR: Exception | None = None
+
+try:
+    from langchain.chat_models import init_chat_model
+    from pydantic import BaseModel, Field, create_model
+    from scrapegraphai.graphs import SmartScraperGraph, SmartScraperMultiGraph
+    from scrapegraphai.graphs.abstract_graph import AbstractGraph
+    from scrapegraphai.graphs.base_graph import BaseGraph
+    from scrapegraphai.nodes import (
+        DescriptionNode,
+        FetchNode,
+        FetchNodeLevelK,
+        GenerateAnswerNodeKLevel,
+        GenerateAnswerOmniNode,
+        ImageToTextNode,
+        ParseNode,
+        ParseNodeDepthK,
+        RAGNode,
+    )
+    from scrapegraphai.utils.convert_to_md import convert_to_md
+except Exception as exc:  # pragma: no cover - import error path is runtime-only
+    _IMPORT_ERROR = exc
+    init_chat_model = None
+    BaseModel = None
+    Field = None
+    create_model = None
+    SmartScraperGraph = None
+    SmartScraperMultiGraph = None
+    AbstractGraph = None
+    BaseGraph = None
+    DescriptionNode = None
+    FetchNode = None
+    FetchNodeLevelK = None
+    GenerateAnswerNodeKLevel = None
+    GenerateAnswerOmniNode = None
+    ImageToTextNode = None
+    ParseNode = None
+    ParseNodeDepthK = None
+    RAGNode = None
+    convert_to_md = None
+else:
+    class _LimitedFetchNodeLevelK(FetchNodeLevelK):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+            self.max_pages = None if self.node_config is None else self.node_config.get("max_pages")
+
+        def obtain_content(self, documents, loader_kwargs):
+            documents = super().obtain_content(documents, loader_kwargs)
+            if self.max_pages and len(documents) > self.max_pages:
+                return documents[: self.max_pages]
+            return documents
+
+    class _BoundedDepthSearchGraph(AbstractGraph):
+        def __init__(self, prompt: str, source: str, config: dict, schema: type[BaseModel] | None = None):
+            super().__init__(prompt, config, source, schema)
+            self.input_key = "url" if source.startswith("http") else "local_dir"
+
+        def _create_graph(self):
+            fetch_node_k = _LimitedFetchNodeLevelK(
+                input="url| local_dir",
+                output=["docs"],
+                node_config={
+                    "loader_kwargs": self.config.get("loader_kwargs", {}),
+                    "force": self.config.get("force", False),
+                    "cut": self.config.get("cut", True),
+                    "browser_base": self.config.get("browser_base"),
+                    "storage_state": self.config.get("storage_state"),
+                    "depth": self.config.get("depth", 1),
+                    "only_inside_links": self.config.get("only_inside_links", False),
+                    "max_pages": self.config.get("max_pages"),
+                },
+            )
+            parse_node_k = ParseNodeDepthK(
+                input="docs",
+                output=["docs"],
+                node_config={"verbose": self.config.get("verbose", False)},
+            )
+            description_node = DescriptionNode(
+                input="docs",
+                output=["docs"],
+                node_config={
+                    "llm_model": self.llm_model,
+                    "verbose": self.config.get("verbose", False),
+                    "cache_path": self.config.get("cache_path", False),
+                },
+            )
+            rag_node = RAGNode(
+                input="docs",
+                output=["vectorial_db"],
+                node_config={
+                    "llm_model": self.llm_model,
+                    "embedder_model": self.config.get("embedder_model", False),
+                    "verbose": self.config.get("verbose", False),
+                },
+            )
+            generate_answer_k = GenerateAnswerNodeKLevel(
+                input="vectorial_db",
+                output=["answer"],
+                node_config={
+                    "llm_model": self.llm_model,
+                    "embedder_model": self.config.get("embedder_model", False),
+                    "verbose": self.config.get("verbose", False),
+                    "schema": self.schema,
+                },
+            )
+            return BaseGraph(
+                nodes=[fetch_node_k, parse_node_k, description_node, rag_node, generate_answer_k],
+                edges=[
+                    (fetch_node_k, parse_node_k),
+                    (parse_node_k, description_node),
+                    (description_node, rag_node),
+                    (rag_node, generate_answer_k),
+                ],
+                entry_point=fetch_node_k,
+                graph_name=self.__class__.__name__,
+            )
+
+        def run(self):
+            inputs = {"user_prompt": self.prompt, self.input_key: self.source}
+            self.final_state, self.execution_info = self.graph.execute(inputs)
+            return self.final_state.get("answer", "No answer found.")
+
+    class _MistralOmniScraperGraph(AbstractGraph):
+        def __init__(self, prompt: str, source: str, config: dict, schema: type[BaseModel] | None = None):
+            self.max_images = config.get("max_images", 5)
+            super().__init__(prompt, config, source, schema)
+            self.input_key = "url" if source.startswith("http") else "local_dir"
+
+        def _create_graph(self):
+            vision_model = init_chat_model(
+                model=self.config.get("vision_model", DEFAULT_VISION_MODEL),
+                model_provider="mistralai",
+                api_key=self.config["llm"]["api_key"],
+                temperature=0,
+            )
+            fetch_node = FetchNode(
+                input="url | local_dir",
+                output=["doc"],
+                node_config={
+                    "loader_kwargs": self.config.get("loader_kwargs", {}),
+                    "storage_state": self.config.get("storage_state"),
+                    "use_soup": self.config.get("use_soup", False),
+                    "timeout": self.config.get("timeout", 30),
+                },
+            )
+            parse_node = ParseNode(
+                input="doc & (url | local_dir)",
+                output=["parsed_doc", "link_urls", "img_urls"],
+                node_config={
+                    "chunk_size": self.model_token,
+                    "parse_urls": True,
+                    "llm_model": self.llm_model,
+                },
+            )
+            image_to_text_node = ImageToTextNode(
+                input="img_urls",
+                output=["img_desc"],
+                node_config={
+                    "llm_model": vision_model,
+                    "max_images": self.max_images,
+                },
+            )
+            generate_answer_omni_node = GenerateAnswerOmniNode(
+                input="user_prompt & (relevant_chunks | parsed_doc | doc) & img_desc",
+                output=["answer"],
+                node_config={
+                    "llm_model": self.llm_model,
+                    "additional_info": self.config.get("additional_info"),
+                    "schema": self.schema,
+                },
+            )
+            return BaseGraph(
+                nodes=[fetch_node, parse_node, image_to_text_node, generate_answer_omni_node],
+                edges=[
+                    (fetch_node, parse_node),
+                    (parse_node, image_to_text_node),
+                    (image_to_text_node, generate_answer_omni_node),
+                ],
+                entry_point=fetch_node,
+                graph_name=self.__class__.__name__,
+            )
+
+        def run(self):
+            inputs = {"user_prompt": self.prompt, self.input_key: self.source}
+            self.final_state, self.execution_info = self.graph.execute(inputs)
+            return self.final_state.get("answer", "No answer found.")
+
+
+class ScrapeGraphToolError(RuntimeError):
+    def __init__(self, code: str, message: str, hint: str | None = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+
+
+def _json_response(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2, default=str)
+
+
+def _error_response(action: str, code: str, message: str, hint: str | None = None) -> str:
+    return _json_response(
+        {
+            "action": action,
+            "error": {"code": code, "message": message, **({"hint": hint} if hint else {})},
+        }
+    )
+
+
+def _require_scrapegraph() -> None:
+    if _IMPORT_ERROR is not None:
+        raise ScrapeGraphToolError(
+            "missing_scrapegraph_dependencies",
+            f"ScrapeGraphAI dependencies are unavailable: {_IMPORT_ERROR}",
+            "Install `scrapegraphai>=1.75.1` and its runtime dependencies.",
+        )
+
+
+def _require_mistral_key() -> str:
+    api_key = os.getenv("MISTRAL_API_KEY", "").strip()
+    if not api_key:
+        raise ScrapeGraphToolError(
+            "missing_mistral_api_key",
+            "MISTRAL_API_KEY is not configured.",
+            "Set MISTRAL_API_KEY in the environment before using ScrapeGraphAI extraction actions.",
+        )
+    return api_key
+
+
+def _coerce_urls(urls: Any) -> list[str]:
+    if urls is None or urls == "":
+        return []
+    if isinstance(urls, list):
+        return [str(url).strip() for url in urls if str(url).strip()]
+    if isinstance(urls, str):
+        text = urls.strip()
+        if not text:
+            return []
+        if text.startswith("["):
+            parsed = json.loads(text)
+            if not isinstance(parsed, list):
+                raise ScrapeGraphToolError("invalid_urls", "urls must be a JSON array of URL strings.")
+            return [str(url).strip() for url in parsed if str(url).strip()]
+        return [part.strip() for part in text.replace("\r", "\n").replace(",", "\n").split("\n") if part.strip()]
+    raise ScrapeGraphToolError("invalid_urls", "urls must be provided as a list or JSON array string.")
+
+
+def _coerce_schema(schema_json: Any) -> dict[str, Any] | None:
+    if schema_json in (None, "", {}):
+        return None
+    if isinstance(schema_json, dict):
+        return schema_json
+    if isinstance(schema_json, str):
+        try:
+            parsed = json.loads(schema_json)
+        except json.JSONDecodeError as exc:
+            raise ScrapeGraphToolError("invalid_schema_json", f"schema_json is not valid JSON: {exc}") from exc
+        if not isinstance(parsed, dict):
+            raise ScrapeGraphToolError("invalid_schema_json", "schema_json must decode to a JSON object.")
+        return parsed
+    raise ScrapeGraphToolError("invalid_schema_json", "schema_json must be a JSON object or JSON string.")
+
+
+def _schema_to_type(name: str, schema: dict[str, Any]) -> Any:
+    schema_type = schema.get("type")
+    if schema_type == "string":
+        return str
+    if schema_type == "integer":
+        return int
+    if schema_type == "number":
+        return float
+    if schema_type == "boolean":
+        return bool
+    if schema_type == "array":
+        item_schema = schema.get("items", {})
+        return list[_schema_to_type(f"{name}Item", item_schema)]
+    if schema_type == "object" or "properties" in schema:
+        properties = schema.get("properties", {})
+        required = set(schema.get("required", []))
+        fields: dict[str, tuple[Any, Any]] = {}
+        for prop_name, prop_schema in properties.items():
+            prop_type = _schema_to_type(f"{name}{prop_name.title()}", prop_schema)
+            description = prop_schema.get("description")
+            is_required = prop_name in required
+            annotation = prop_type if is_required else (prop_type | None)
+            default = Field(... if is_required else None, description=description)
+            fields[prop_name] = (annotation, default)
+        return create_model(name, **fields)
+    return Any
+
+
+def _schema_to_model(schema: dict[str, Any] | None) -> type[BaseModel] | None:
+    if not schema:
+        return None
+    if schema.get("type") not in (None, "object") and "properties" not in schema:
+        raise ScrapeGraphToolError(
+            "invalid_schema_json",
+            "Only object-shaped JSON schemas are supported for schema_json.",
+        )
+    model_type = _schema_to_type("ScrapeGraphResult", schema)
+    if not isinstance(model_type, type) or not issubclass(model_type, BaseModel):
+        raise ScrapeGraphToolError(
+            "invalid_schema_json",
+            "schema_json must define an object with properties for structured extraction.",
+        )
+    return model_type
+
+
+def _resolve_storage_state(storage_state_path: str | None) -> str | None:
+    if not storage_state_path:
+        return None
+    candidate = storage_state_path.strip()
+    if not candidate:
+        return None
+    if os.path.isabs(candidate):
+        resolved = candidate
+    else:
+        resolved, _ = _resolve_path(candidate)
+    if not os.path.exists(resolved):
+        raise ScrapeGraphToolError(
+            "invalid_storage_state_path",
+            f"Storage state file not found: {candidate}",
+        )
+    return resolved
+
+
+def _build_config(
+    *,
+    api_key: str | None,
+    text_model: str | None = None,
+    render_mode: str = "auto",
+    timeout_s: int = 30,
+    storage_state_path: str | None = None,
+    depth: int | None = None,
+    max_pages: int | None = None,
+    same_domain_only: bool | None = None,
+    max_images: int | None = None,
+    vision_model: str | None = None,
+) -> dict[str, Any]:
+    if render_mode not in RENDER_CHOICES:
+        raise ScrapeGraphToolError("invalid_render_mode", f"Unsupported render_mode: {render_mode}")
+    config: dict[str, Any] = {
+        "headless": True,
+        "verbose": False,
+        "timeout": max(5, int(timeout_s)),
+        "use_soup": render_mode == "http",
+    }
+    if api_key:
+        config["llm"] = {
+            "api_key": api_key,
+            "model": f"mistralai/{text_model or os.getenv(TEXT_MODEL_ENV, DEFAULT_TEXT_MODEL)}",
+            "temperature": 0,
+        }
+    if storage_state_path:
+        config["storage_state"] = storage_state_path
+    if depth is not None:
+        config["depth"] = max(1, int(depth))
+    if max_pages is not None:
+        config["max_pages"] = max(1, int(max_pages))
+    if same_domain_only is not None:
+        config["only_inside_links"] = bool(same_domain_only)
+    if max_images is not None:
+        config["max_images"] = max(1, int(max_images))
+    if vision_model:
+        config["vision_model"] = vision_model
+    return config
+
+
+def _json_safe(value: Any) -> Any:
+    if BaseModel is not None and isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, dict):
+        return {key: _json_safe(val) for key, val in value.items()}
+    if isinstance(value, list):
+        return [_json_safe(item) for item in value]
+    if isinstance(value, tuple):
+        return [_json_safe(item) for item in value]
+    if hasattr(value, "metadata") and hasattr(value, "page_content"):
+        return {
+            "page_content": getattr(value, "page_content", ""),
+            "metadata": _json_safe(getattr(value, "metadata", {})),
+        }
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.startswith("{") or stripped.startswith("["):
+            try:
+                return json.loads(stripped)
+            except Exception:
+                return value
+    return value
+
+
+def _extract_sources(state: dict[str, Any], fallback: list[str] | None = None) -> list[str]:
+    sources: list[str] = []
+    for item in state.get("docs", []) or []:
+        source = item.get("source") if isinstance(item, dict) else None
+        if source and source not in sources:
+            sources.append(source)
+    for doc in state.get("doc", []) or []:
+        metadata = getattr(doc, "metadata", {}) or {}
+        source = metadata.get("source")
+        if source and source not in sources:
+            sources.append(source)
+    if not sources and fallback:
+        sources.extend([source for source in fallback if source])
+    return sources
+
+
+def _extract_links_and_images(doc_state: dict[str, Any], url: str) -> tuple[list[str], list[str]]:
+    parse_node = ParseNode(
+        input="doc & url",
+        output=["parsed_doc", "link_urls", "img_urls"],
+        node_config={
+            "parse_urls": True,
+            "parse_html": True,
+            "chunk_size": 8192,
+            "llm_model": None,
+        },
+    )
+    docs = doc_state.get("doc")
+    if not docs:
+        docs = doc_state.get("html_content", [])
+    if not docs:
+        return [], []
+    state = {"doc": docs, "url": url}
+    parse_node.execute(state)
+    return state.get("link_urls", []) or [], state.get("img_urls", []) or []
+
+
+def _render_markdown_with_fetch(url: str, config: dict[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    fetch_node = FetchNode(
+        input="url",
+        output=["doc"],
+        node_config=config,
+    )
+    state = {"url": url}
+    state = fetch_node.execute(state)
+    docs = state.get("doc", []) or []
+    if not docs:
+        raise ScrapeGraphToolError("fetch_failed", "ScrapeGraph fetch returned no documents for render_markdown.")
+    html = getattr(docs[0], "page_content", None) or ""
+    if not html.strip():
+        raise ScrapeGraphToolError("fetch_failed", "Fetched document for render_markdown had empty content.")
+    state["markdown"] = convert_to_md(html)
+    return state, []
+
+
+@autodoc(summary=TOOL_SUMMARY)
+def ScrapeGraphAI(
+    action: Annotated[
+        Literal["extract", "crawl_extract", "multi_extract", "render_markdown", "vision_extract"],
+        "Action to run: extract, crawl_extract, multi_extract, render_markdown, or vision_extract.",
+    ] = "extract",
+    url: Annotated[str, "Single URL for extract, crawl_extract, render_markdown, or vision_extract."] = "",
+    urls: Annotated[list[str] | str | None, "Explicit list of URLs for multi_extract. Accepts a list or JSON array string."] = None,
+    prompt: Annotated[str, "Natural-language extraction prompt. Required for extraction actions."] = "",
+    schema_json: Annotated[dict[str, Any] | str | None, "Optional object-shaped JSON schema for structured extraction."] = None,
+    render_mode: Annotated[Literal["auto", "browser", "http"], "Fetch mode. `browser` uses ScrapeGraph browser loading, `http` uses requests + soup, `auto` currently follows ScrapeGraph's browser-first path."] = "auto",
+    include_images: Annotated[bool, "For `extract`, include page images in the extraction context."] = False,
+    depth: Annotated[int, "For `crawl_extract`, crawl depth from the starting URL."] = 1,
+    max_pages: Annotated[int, "For `crawl_extract`, soft cap on fetched pages."] = 4,
+    same_domain_only: Annotated[bool, "For `crawl_extract`, stay within the starting site's links only."] = True,
+    max_urls: Annotated[int, "For `multi_extract`, maximum URLs allowed in one call."] = 8,
+    max_images: Annotated[int, "For `vision_extract` and image-aware extraction, maximum images to describe."] = 5,
+    max_chars: Annotated[int, "For `render_markdown`, trim returned markdown to this many characters."] = 12000,
+    include_links: Annotated[bool, "For `render_markdown`, include discovered page links."] = True,
+    timeout_s: Annotated[int, "Timeout in seconds passed to ScrapeGraph fetch and generation nodes."] = 30,
+    storage_state_path: Annotated[str, "Optional Playwright storage state JSON path for authenticated pages."] = "",
+    return_debug: Annotated[bool, "Include execution metadata and graph execution info in the response."] = False,
+) -> str:
+    _log_call_start(
+        "ScrapeGraphAI",
+        action=action,
+        url=url,
+        urls=urls,
+        prompt=_truncate_for_log(prompt or "", 180),
+        render_mode=render_mode,
+        include_images=include_images,
+        depth=depth,
+        max_pages=max_pages,
+        max_urls=max_urls,
+        max_images=max_images,
+        timeout_s=timeout_s,
+        storage_state_path=storage_state_path,
+        return_debug=return_debug,
+    )
+
+    try:
+        _require_scrapegraph()
+        storage_state = _resolve_storage_state(storage_state_path)
+        schema = _coerce_schema(schema_json)
+        schema_model = _schema_to_model(schema)
+        text_model_name = os.getenv(TEXT_MODEL_ENV, DEFAULT_TEXT_MODEL)
+        vision_model_name = os.getenv(VISION_MODEL_ENV, DEFAULT_VISION_MODEL)
+
+        if action == "render_markdown":
+            if not url.strip():
+                raise ScrapeGraphToolError("missing_url", "url is required for render_markdown.")
+            final_state, exec_info = _render_markdown_with_fetch(
+                url.strip(),
+                _build_config(
+                    api_key=None,
+                    render_mode=render_mode,
+                    timeout_s=timeout_s,
+                    storage_state_path=storage_state,
+                ),
+            )
+            markdown = (final_state.get("markdown") or "")[: max(1000, int(max_chars))]
+            links, images = _extract_links_and_images(final_state, url.strip())
+            response = {
+                "action": action,
+                "result": {"markdown": markdown},
+                "sources": [url.strip()],
+                "artifacts": {
+                    "markdown": markdown,
+                    "links": links if include_links else [],
+                    "images": images if include_images else [],
+                    "per_url_results": [],
+                },
+                "meta": {
+                    "render_mode_used": render_mode,
+                    "text_model": None,
+                    "vision_model": None,
+                },
+                "warnings": [],
+            }
+            if return_debug:
+                response["debug"] = {"final_state": _json_safe(final_state), "execution_info": _json_safe(exec_info)}
+            result = _json_response(response)
+            _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+            return result
+
+        api_key = _require_mistral_key()
+        if action == "extract":
+            if not url.strip() or not prompt.strip():
+                raise ScrapeGraphToolError("missing_arguments", "url and prompt are required for extract.")
+            config = _build_config(
+                api_key=api_key,
+                text_model=text_model_name,
+                render_mode=render_mode,
+                timeout_s=timeout_s,
+                storage_state_path=storage_state,
+                max_images=max_images,
+                vision_model=vision_model_name,
+            )
+            graph_cls = _MistralOmniScraperGraph if include_images else SmartScraperGraph
+            graph = graph_cls(prompt=prompt.strip(), source=url.strip(), config=config, schema=schema_model)
+            result_data = _json_safe(graph.run())
+            final_state = graph.get_state()
+            response = {
+                "action": action,
+                "result": result_data,
+                "sources": _extract_sources(final_state, [url.strip()]),
+                "artifacts": {
+                    "markdown": None,
+                    "links": final_state.get("link_urls", []) or [],
+                    "images": final_state.get("img_urls", []) or [],
+                    "per_url_results": [],
+                },
+                "meta": {
+                    "render_mode_used": render_mode,
+                    "text_model": text_model_name,
+                    "vision_model": vision_model_name if include_images else None,
+                },
+                "warnings": [],
+            }
+            if return_debug:
+                response["debug"] = {"final_state": _json_safe(final_state), "execution_info": _json_safe(graph.get_execution_info())}
+            result = _json_response(response)
+            _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+            return result
+
+        if action == "vision_extract":
+            if not url.strip() or not prompt.strip():
+                raise ScrapeGraphToolError("missing_arguments", "url and prompt are required for vision_extract.")
+            graph = _MistralOmniScraperGraph(
+                prompt=prompt.strip(),
+                source=url.strip(),
+                config=_build_config(
+                    api_key=api_key,
+                    text_model=text_model_name,
+                    render_mode=render_mode,
+                    timeout_s=timeout_s,
+                    storage_state_path=storage_state,
+                    max_images=max_images,
+                    vision_model=vision_model_name,
+                ),
+                schema=schema_model,
+            )
+            result_data = _json_safe(graph.run())
+            final_state = graph.get_state()
+            img_urls = final_state.get("img_urls", []) or []
+            if not img_urls:
+                raise ScrapeGraphToolError("no_images_found", "No images were found on the page for vision_extract.")
+            response = {
+                "action": action,
+                "result": result_data,
+                "sources": _extract_sources(final_state, [url.strip()]),
+                "artifacts": {
+                    "markdown": None,
+                    "links": final_state.get("link_urls", []) or [],
+                    "images": img_urls,
+                    "per_url_results": [],
+                },
+                "meta": {
+                    "render_mode_used": render_mode,
+                    "text_model": text_model_name,
+                    "vision_model": vision_model_name,
+                },
+                "warnings": [],
+            }
+            if return_debug:
+                response["debug"] = {"final_state": _json_safe(final_state), "execution_info": _json_safe(graph.get_execution_info())}
+            result = _json_response(response)
+            _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+            return result
+
+        if action == "multi_extract":
+            normalized_urls = _coerce_urls(urls)
+            if not normalized_urls or not prompt.strip():
+                raise ScrapeGraphToolError("missing_arguments", "urls and prompt are required for multi_extract.")
+            if len(normalized_urls) > max(1, int(max_urls)):
+                raise ScrapeGraphToolError("too_many_urls", f"multi_extract supports at most {max_urls} URLs per call.")
+            graph = SmartScraperMultiGraph(
+                prompt=prompt.strip(),
+                source=normalized_urls,
+                config=_build_config(
+                    api_key=api_key,
+                    text_model=text_model_name,
+                    render_mode=render_mode,
+                    timeout_s=timeout_s,
+                    storage_state_path=storage_state,
+                ),
+                schema=schema_model,
+            )
+            result_data = _json_safe(graph.run())
+            final_state = graph.get_state()
+            response = {
+                "action": action,
+                "result": result_data,
+                "sources": normalized_urls,
+                "artifacts": {
+                    "markdown": None,
+                    "links": [],
+                    "images": [],
+                    "per_url_results": _json_safe(final_state.get("results", [])),
+                },
+                "meta": {
+                    "render_mode_used": render_mode,
+                    "text_model": text_model_name,
+                    "vision_model": None,
+                },
+                "warnings": [],
+            }
+            if return_debug:
+                response["debug"] = {"final_state": _json_safe(final_state), "execution_info": _json_safe(graph.get_execution_info())}
+            result = _json_response(response)
+            _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+            return result
+
+        if action == "crawl_extract":
+            if not url.strip() or not prompt.strip():
+                raise ScrapeGraphToolError("missing_arguments", "url and prompt are required for crawl_extract.")
+            graph = _BoundedDepthSearchGraph(
+                prompt=prompt.strip(),
+                source=url.strip(),
+                config=_build_config(
+                    api_key=api_key,
+                    text_model=text_model_name,
+                    render_mode=render_mode,
+                    timeout_s=timeout_s,
+                    storage_state_path=storage_state,
+                    depth=depth,
+                    max_pages=max_pages,
+                    same_domain_only=same_domain_only,
+                ),
+                schema=schema_model,
+            )
+            result_data = _json_safe(graph.run())
+            final_state = graph.get_state()
+            response = {
+                "action": action,
+                "result": result_data,
+                "sources": _extract_sources(final_state, [url.strip()]),
+                "artifacts": {
+                    "markdown": None,
+                    "links": [],
+                    "images": [],
+                    "per_url_results": [],
+                },
+                "meta": {
+                    "render_mode_used": render_mode,
+                    "text_model": text_model_name,
+                    "vision_model": None,
+                },
+                "warnings": [],
+            }
+            if return_debug:
+                response["debug"] = {"final_state": _json_safe(final_state), "execution_info": _json_safe(graph.get_execution_info())}
+            result = _json_response(response)
+            _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+            return result
+
+        raise ScrapeGraphToolError("unsupported_action", f"Unsupported action: {action}")
+    except ScrapeGraphToolError as exc:
+        result = _error_response(action, exc.code, exc.message, exc.hint)
+        _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+        return result
+    except Exception as exc:  # pragma: no cover - runtime integration path
+        code = "browser_unavailable" if "playwright" in str(exc).lower() or "chromium" in str(exc).lower() else "fetch_failed"
+        result = _error_response(action, code, f"ScrapeGraphAI action failed: {exc}")
+        _log_call_end("ScrapeGraphAI", _truncate_for_log(result))
+        return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=ScrapeGraphAI,
+        inputs=[
+            gr.Dropdown(choices=ACTION_CHOICES, value="extract", label="Action"),
+            gr.Textbox(label="URL", placeholder="https://example.com"),
+            gr.JSON(label="URLs", value=[]),
+            gr.Textbox(label="Prompt", lines=4, placeholder="Extract pricing tiers and main limits."),
+            gr.JSON(label="Schema JSON", value={}),
+            gr.Dropdown(choices=RENDER_CHOICES, value="auto", label="Render Mode"),
+            gr.Checkbox(label="Include Images", value=False),
+            gr.Number(label="Depth", value=1, precision=0),
+            gr.Number(label="Max Pages", value=4, precision=0),
+            gr.Checkbox(label="Same Domain Only", value=True),
+            gr.Number(label="Max URLs", value=8, precision=0),
+            gr.Number(label="Max Images", value=5, precision=0),
+            gr.Number(label="Max Chars", value=12000, precision=0),
+            gr.Checkbox(label="Include Links", value=True),
+            gr.Number(label="Timeout (seconds)", value=30, precision=0),
+            gr.Textbox(label="Storage State Path", placeholder="Optional Playwright storage_state JSON path"),
+            gr.Checkbox(label="Return Debug", value=False),
+        ],
+        outputs=gr.Textbox(label="Result", lines=20, max_lines=40),
+        title="ScrapeGraphAI",
+        description="<div style=\"text-align:center\">Mistral-only structured scraping using ScrapeGraphAI graphs.</div>",
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["ScrapeGraphAI", "build_interface"]

Modules/Shell_Command.py

@@ -1,194 +1,194 @@
-from __future__ import annotations
-
-import os
-import platform
-import shlex
-import subprocess
-from typing import Annotated
-
-import gradio as gr
-
-from app import _log_call_end, _log_call_start, _truncate_for_log
-from ._docstrings import autodoc
-from ._core import _resolve_path, ROOT_DIR, _display_path, ALLOW_ABS
-import shutil
-
-
-
-def _detect_shell(prefer_powershell: bool = True) -> tuple[list[str], str]:
-    """
-    Pick an appropriate shell for the host OS.
-    - Windows: use PowerShell by default, fall back to cmd.exe.
-    - POSIX: use /bin/bash if available, else /bin/sh.
-    Returns (shell_cmd_prefix, shell_name) where shell_cmd_prefix is the command list to launch the shell.
-    """
-    system = platform.system().lower()
-    if system == "windows":
-        if prefer_powershell:
-            pwsh = shutil.which("pwsh")
-            candidates = [pwsh, shutil.which("powershell"), shutil.which("powershell.exe")]
-            for cand in candidates:
-                if cand:
-                    return [cand, "-NoLogo", "-NoProfile", "-Command"], "powershell"
-            # Fallback to cmd
-        comspec = os.environ.get("ComSpec", r"C:\\Windows\\System32\\cmd.exe")
-        return [comspec, "/C"], "cmd"
-    # POSIX
-    bash = shutil.which("bash")
-    if bash:
-        return [bash, "-lc"], "bash"
-    sh = os.environ.get("SHELL", "/bin/sh")
-    return [sh, "-lc"], "sh"
-
-
-# Detect shell at import time for docs/UI purposes
-_DETECTED_SHELL_PREFIX, _DETECTED_SHELL_NAME = _detect_shell()
-
-
-# Clarify path semantics and expose detected shell in summary
-TOOL_SUMMARY = (
-    "Execute a shell command within a safe working directory under the tool root ('/'). "
-    "Paths must be relative to '/'. "
-    "Set workdir to '.' to use the root. "
-    "Absolute paths are disabled."
-    f"Detected shell: {_DETECTED_SHELL_NAME}."
-)
-
-
-def _run_command(command: str, cwd: str, timeout: int) -> tuple[str, str, int]:
-    shell_prefix, shell_name = _detect_shell()
-    full_cmd = shell_prefix + [command]
-    try:
-        proc = subprocess.run(
-            full_cmd,
-            cwd=cwd,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            timeout=timeout if timeout and timeout > 0 else None,
-        )
-        return proc.stdout, proc.stderr, proc.returncode
-    except subprocess.TimeoutExpired as exc:
-        return exc.stdout or "", (exc.stderr or "") + "\n[timeout]", 124
-    except Exception as exc:
-        return "", f"Execution failed: {exc}", 1
-
-
-@autodoc(summary=TOOL_SUMMARY)
-def Shell_Command(
-    command: Annotated[str, "Shell command to execute. Accepts multi-part pipelines as a single string."],
-    workdir: Annotated[str, "Working directory (relative to root unless UNSAFE_ALLOW_ABS_PATHS=1)."] = ".",
-    timeout: Annotated[int, "Timeout in seconds (0 = no timeout, be careful on public hosting)."] = 60,
-) -> str:
-    _log_call_start("Shell_Command", command=command, workdir=workdir, timeout=timeout)
-    if not command or not command.strip():
-        result = "No command provided."
-        _log_call_end("Shell_Command", _truncate_for_log(result))
-        return result
-
-    abs_cwd, err = _resolve_path(workdir)
-    if err:
-        _log_call_end("Shell_Command", _truncate_for_log(err))
-        return err
-    if not os.path.exists(abs_cwd):
-        result = f"Working directory not found: {abs_cwd}"
-        _log_call_end("Shell_Command", _truncate_for_log(result))
-        return result
-
-    # Heuristic check for absolute paths in arguments if sandboxing is strictly enforced
-    # We look for typical absolute path patterns: "/..." or "C:\..."
-    # This is not perfect (e.g., inside strings) but helps enforce "Impossible" rule.
-    import re
-    if not ALLOW_ABS:
-
-        # Regex for Unix-style absolute path (start with /)
-        # or Windows-style absolute path (start with drive letter)
-        # We look for these patterns preceded by space or start of string
-        # to avoid matching arguments like --flag=/value (though those might be paths too!)
-        # Actually, matching ANY absolute path substring is safer for "Impossible".
-        # Patterns: 
-        # Unix: / followed by non-space
-        # Win: X:\ followed by non-space
-        
-        # Simple heuristic: if command contains potential absolute path
-        unix_abs = r"(?:\s|^)/[a-zA-Z0-9_.]"
-        win_abs = r"(?:\s|^)[a-zA-Z]:\\"
-        
-        if re.search(unix_abs, command) or re.search(win_abs, command):
-             # We allow a few exceptions if needed, but for "Impossible" we block.
-             # Note: This might block flags like /C, but we run powershell/cmd separately.
-             # Wait, Windows flags start with /. 'dir /s'. This heuristic is dangerous for Windows flags.
-             # We should refine it.
-             pass 
-
-        # Refined check:
-        # On Windows, flags start with /, so checking for / is bad.
-        # But paths in Windows usually use \ or /.
-        # Let's focus on Unix roots and Windows Drive roots.
-        
-        has_abs_path = False
-        if platform.system().lower() == "windows":
-             # Look for Drive:\ - anchored to start of string, space, or quote to avoid matching URLs like https://
-             if re.search(r"(?:\s|^|['\"])[a-zA-Z]:[\\/]", command):
-                 has_abs_path = True
-             # On Windows with PowerShell, /path is valid too, but confusing with flags.
-             # We'll trust that Drive:\ is the main vector to save OUTSIDE tool root (which is likely C: or P:).
-             # If tool root is P:/Code..., writing to C:/... requires Drive arg.
-        else:
-             # Unix: Look for / at start of token, but exclude common flags?
-             # Actually, just looking for " /" or start "/" is decent.
-             # But flags like /dev/null are common.
-             # Maybe we just warn or block known dangerous patterns?
-             # User said "Make it impossible". a broad block is better than a leak.
-             if re.search(r"(?:\s|^)/", command):
-                  # This blocks flags like /bin/bash or paths.
-                  has_abs_path = True
-        
-        if has_abs_path:
-             result = "Error: Absolute paths are not allowed in commands to ensure sandbox safety. Use relative paths."
-             _log_call_end("Shell_Command", _truncate_for_log(result))
-             return result
-
-    # Capture shell used for transparency
-    _, shell_name = _detect_shell()
-    stdout, stderr, code = _run_command(command, cwd=abs_cwd, timeout=timeout)
-    display_cwd = _display_path(abs_cwd)
-    header = (
-        f"Command: {command}\n"
-        f"CWD: {display_cwd}\n"
-        f"Root: /\n"
-        f"Shell: {shell_name}\n"
-        f"Exit code: {code}\n"
-        f"--- STDOUT ---\n"
-    )
-    output = header + (stdout or "<empty>") + "\n--- STDERR ---\n" + (stderr or "<empty>")
-    _log_call_end("Shell_Command", _truncate_for_log(f"exit={code} stdout={len(stdout)} stderr={len(stderr)}"))
-    return output
-
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Shell_Command,
-        inputs=[
-            gr.Textbox(label="Command", placeholder="echo hello || dir", lines=2, info="Shell command to execute"),
-            gr.Textbox(label="Workdir", value=".", max_lines=1, info="Working directory (relative to root)"),
-            gr.Slider(minimum=0, maximum=600, step=5, value=60, label="Timeout (seconds)", info="Timeout in seconds (0 = no timeout)"),
-        ],
-        outputs=gr.Textbox(label="Output", lines=20),
-        title="Shell Command",
-        description=(
-            "<div style=\"text-align:center; overflow:hidden;\">"
-            "Run a shell command under the same safe root as File System. "
-            "Absolute paths are disabled, use relative paths. "
-            f"Detected shell: {_DETECTED_SHELL_NAME}. "
-            "</div>"
-        ),
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-        submit_btn="Run",
-    )
-
-
-__all__ = ["Shell_Command", "build_interface"]
+from __future__ import annotations
+
+import os
+import platform
+import shlex
+import subprocess
+from typing import Annotated
+
+import gradio as gr
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+from ._core import _resolve_path, ROOT_DIR, _display_path, ALLOW_ABS
+import shutil
+
+
+
+def _detect_shell(prefer_powershell: bool = True) -> tuple[list[str], str]:
+    """
+    Pick an appropriate shell for the host OS.
+    - Windows: use PowerShell by default, fall back to cmd.exe.
+    - POSIX: use /bin/bash if available, else /bin/sh.
+    Returns (shell_cmd_prefix, shell_name) where shell_cmd_prefix is the command list to launch the shell.
+    """
+    system = platform.system().lower()
+    if system == "windows":
+        if prefer_powershell:
+            pwsh = shutil.which("pwsh")
+            candidates = [pwsh, shutil.which("powershell"), shutil.which("powershell.exe")]
+            for cand in candidates:
+                if cand:
+                    return [cand, "-NoLogo", "-NoProfile", "-Command"], "powershell"
+            # Fallback to cmd
+        comspec = os.environ.get("ComSpec", r"C:\\Windows\\System32\\cmd.exe")
+        return [comspec, "/C"], "cmd"
+    # POSIX
+    bash = shutil.which("bash")
+    if bash:
+        return [bash, "-lc"], "bash"
+    sh = os.environ.get("SHELL", "/bin/sh")
+    return [sh, "-lc"], "sh"
+
+
+# Detect shell at import time for docs/UI purposes
+_DETECTED_SHELL_PREFIX, _DETECTED_SHELL_NAME = _detect_shell()
+
+
+# Clarify path semantics and expose detected shell in summary
+TOOL_SUMMARY = (
+    "Execute a shell command within a safe working directory under the tool root ('/'). "
+    "Paths must be relative to '/'. "
+    "Set workdir to '.' to use the root. "
+    "Absolute paths are disabled."
+    f"Detected shell: {_DETECTED_SHELL_NAME}."
+)
+
+
+def _run_command(command: str, cwd: str, timeout: int) -> tuple[str, str, int]:
+    shell_prefix, shell_name = _detect_shell()
+    full_cmd = shell_prefix + [command]
+    try:
+        proc = subprocess.run(
+            full_cmd,
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout if timeout and timeout > 0 else None,
+        )
+        return proc.stdout, proc.stderr, proc.returncode
+    except subprocess.TimeoutExpired as exc:
+        return exc.stdout or "", (exc.stderr or "") + "\n[timeout]", 124
+    except Exception as exc:
+        return "", f"Execution failed: {exc}", 1
+
+
+@autodoc(summary=TOOL_SUMMARY)
+def Shell_Command(
+    command: Annotated[str, "Shell command to execute. Accepts multi-part pipelines as a single string."],
+    workdir: Annotated[str, "Working directory (relative to root unless UNSAFE_ALLOW_ABS_PATHS=1)."] = ".",
+    timeout: Annotated[int, "Timeout in seconds (0 = no timeout, be careful on public hosting)."] = 60,
+) -> str:
+    _log_call_start("Shell_Command", command=command, workdir=workdir, timeout=timeout)
+    if not command or not command.strip():
+        result = "No command provided."
+        _log_call_end("Shell_Command", _truncate_for_log(result))
+        return result
+
+    abs_cwd, err = _resolve_path(workdir)
+    if err:
+        _log_call_end("Shell_Command", _truncate_for_log(err))
+        return err
+    if not os.path.exists(abs_cwd):
+        result = f"Working directory not found: {abs_cwd}"
+        _log_call_end("Shell_Command", _truncate_for_log(result))
+        return result
+
+    # Heuristic check for absolute paths in arguments if sandboxing is strictly enforced
+    # We look for typical absolute path patterns: "/..." or "C:\..."
+    # This is not perfect (e.g., inside strings) but helps enforce "Impossible" rule.
+    import re
+    if not ALLOW_ABS:
+
+        # Regex for Unix-style absolute path (start with /)
+        # or Windows-style absolute path (start with drive letter)
+        # We look for these patterns preceded by space or start of string
+        # to avoid matching arguments like --flag=/value (though those might be paths too!)
+        # Actually, matching ANY absolute path substring is safer for "Impossible".
+        # Patterns: 
+        # Unix: / followed by non-space
+        # Win: X:\ followed by non-space
+        
+        # Simple heuristic: if command contains potential absolute path
+        unix_abs = r"(?:\s|^)/[a-zA-Z0-9_.]"
+        win_abs = r"(?:\s|^)[a-zA-Z]:\\"
+        
+        if re.search(unix_abs, command) or re.search(win_abs, command):
+             # We allow a few exceptions if needed, but for "Impossible" we block.
+             # Note: This might block flags like /C, but we run powershell/cmd separately.
+             # Wait, Windows flags start with /. 'dir /s'. This heuristic is dangerous for Windows flags.
+             # We should refine it.
+             pass 
+
+        # Refined check:
+        # On Windows, flags start with /, so checking for / is bad.
+        # But paths in Windows usually use \ or /.
+        # Let's focus on Unix roots and Windows Drive roots.
+        
+        has_abs_path = False
+        if platform.system().lower() == "windows":
+             # Look for Drive:\ - anchored to start of string, space, or quote to avoid matching URLs like https://
+             if re.search(r"(?:\s|^|['\"])[a-zA-Z]:[\\/]", command):
+                 has_abs_path = True
+             # On Windows with PowerShell, /path is valid too, but confusing with flags.
+             # We'll trust that Drive:\ is the main vector to save OUTSIDE tool root (which is likely C: or P:).
+             # If tool root is P:/Code..., writing to C:/... requires Drive arg.
+        else:
+             # Unix: Look for / at start of token, but exclude common flags?
+             # Actually, just looking for " /" or start "/" is decent.
+             # But flags like /dev/null are common.
+             # Maybe we just warn or block known dangerous patterns?
+             # User said "Make it impossible". a broad block is better than a leak.
+             if re.search(r"(?:\s|^)/", command):
+                  # This blocks flags like /bin/bash or paths.
+                  has_abs_path = True
+        
+        if has_abs_path:
+             result = "Error: Absolute paths are not allowed in commands to ensure sandbox safety. Use relative paths."
+             _log_call_end("Shell_Command", _truncate_for_log(result))
+             return result
+
+    # Capture shell used for transparency
+    _, shell_name = _detect_shell()
+    stdout, stderr, code = _run_command(command, cwd=abs_cwd, timeout=timeout)
+    display_cwd = _display_path(abs_cwd)
+    header = (
+        f"Command: {command}\n"
+        f"CWD: {display_cwd}\n"
+        f"Root: /\n"
+        f"Shell: {shell_name}\n"
+        f"Exit code: {code}\n"
+        f"--- STDOUT ---\n"
+    )
+    output = header + (stdout or "<empty>") + "\n--- STDERR ---\n" + (stderr or "<empty>")
+    _log_call_end("Shell_Command", _truncate_for_log(f"exit={code} stdout={len(stdout)} stderr={len(stderr)}"))
+    return output
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Shell_Command,
+        inputs=[
+            gr.Textbox(label="Command", placeholder="echo hello || dir", lines=2, info="Shell command to execute"),
+            gr.Textbox(label="Workdir", value=".", max_lines=1, info="Working directory (relative to root)"),
+            gr.Slider(minimum=0, maximum=600, step=5, value=60, label="Timeout (seconds)", info="Timeout in seconds (0 = no timeout)"),
+        ],
+        outputs=gr.Textbox(label="Output", lines=20),
+        title="Shell Command",
+        description=(
+            "<div style=\"text-align:center; overflow:hidden;\">"
+            "Run a shell command under the same safe root as File System. "
+            "Absolute paths are disabled, use relative paths. "
+            f"Detected shell: {_DETECTED_SHELL_NAME}. "
+            "</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Run",
+    )
+
+
+__all__ = ["Shell_Command", "build_interface"]

Modules/Web_Search.py

@@ -1,499 +1,517 @@
-from __future__ import annotations
-
-from typing import Annotated, List
-from datetime import datetime
-
-import gradio as gr
-from ddgs import DDGS
-
-from app import _log_call_end, _log_call_start, _search_rate_limiter, _truncate_for_log
-from ._docstrings import autodoc
-
-
-# Single source of truth for the LLM-facing tool description
-TOOL_SUMMARY = (
-    "Run a DuckDuckGo-backed search across text, news, images, videos, or books. "
-    "Readable results include pagination hints and next_offset when more results are available; "
-    "Use in combination with `Web_Fetch` to navigate the web."
-)
-
-
-_SAFESEARCH_LEVEL = "off"
-
-# Defaults and choices for newly added parameters
-BACKEND_CHOICES = [
-    "auto",
-    "duckduckgo",
-    "bing",
-    "brave",
-    "yahoo",
-    "wikipedia",
-]
-
-# Allowed backends per type (explicit selection set)
-_ALLOWED_BACKENDS = {
-    "text": ["duckduckgo", "bing", "brave", "yahoo", "wikipedia"],
-    "news": ["duckduckgo", "bing", "yahoo"],
-    "images": ["duckduckgo"],
-    "videos": ["duckduckgo"],
-    "books": ["annasarchive"],
-}
-
-# Auto order per type (used when backend == "auto"); wikipedia excluded for text
-_AUTO_ORDER = {
-    "text": ["duckduckgo", "bing", "brave", "yahoo"],
-    "news": ["duckduckgo", "bing", "yahoo"],
-    "images": ["duckduckgo"],
-    "videos": ["duckduckgo"],
-    "books": ["annasarchive"],
-}
-
-# Date filter choices: canonical values used by resolver
-DATE_FILTER_CHOICES = ["any", "day", "week", "month", "year"]
-
-
-def _resolve_backend(search_type: str, backend_choice: str) -> str:
-    """Resolve backend string for DDGS based on search type and user choice.
-
-    - If backend_choice is "auto", return a comma-separated fallback order for that type.
-    - If backend_choice is not supported by the type, fall back to the first allowed backend.
-    - Books endpoint uses only 'annasarchive'.
-    """
-    stype = search_type if search_type in _ALLOWED_BACKENDS else "text"
-    allowed = _ALLOWED_BACKENDS[stype]
-    if backend_choice == "auto":
-        return ", ".join(_AUTO_ORDER[stype])
-    if stype == "books":
-        return "annasarchive"
-    # Validate backend against allowed set for this type
-    if backend_choice in allowed:
-        return backend_choice
-    # Fallback to first allowed backend
-    return allowed[0]
-
-
-def _resolve_timelimit(date_filter: str, search_type: str) -> str | None:
-    """Map UI date filter to DDGS timelimit code per endpoint.
-
-    Returns one of: None, 'd', 'w', 'm', 'y'. For news/videos (which support d/w/m),
-    selecting 'year' will coerce to 'm' to stay within supported range.
-    """
-    normalized = (date_filter or "any").strip().lower()
-    if normalized in ("any", "none", ""):
-        return None
-    mapping = {
-        "day": "d",
-        "week": "w",
-        "month": "m",
-        "year": "y",
-    }
-    code = mapping.get(normalized)
-    if not code:
-        return None
-    if search_type in ("news", "videos") and code == "y":
-        return "m"
-    return code
-
-
-def _extract_date_from_snippet(snippet: str) -> str:
-    if not snippet:
-        return ""
-    import re
-
-    date_patterns = [
-        r"\b(\d{4}[-/]\d{1,2}[-/]\d{1,2})\b",
-        r"\b([A-Za-z]{3,9}\s+\d{1,2},?\s+\d{4})\b",
-        r"\b(\d{1,2}\s+[A-Za-z]{3,9}\s+\d{4})\b",
-        r"\b(\d+\s+(?:day|week|month|year)s?\s+ago)\b",
-        r"(?:Published|Updated|Posted):\s*([^,\n]+?)(?:[,\n]|$)",
-    ]
-    for pattern in date_patterns:
-        matches = re.findall(pattern, snippet, re.IGNORECASE)
-        if matches:
-            return matches[0].strip()
-    return ""
-
-
-def _format_search_result(result: dict, search_type: str, index: int) -> List[str]:
-    lines: List[str] = []
-    if search_type == "text":
-        title = result.get("title", "").strip()
-        url = result.get("href", "").strip()
-        snippet = result.get("body", "").strip()
-        date = _extract_date_from_snippet(snippet)
-        lines.append(f"{index}. {title}")
-        lines.append(f"   URL: {url}")
-        if snippet:
-            lines.append(f"   Summary: {snippet}")
-        if date:
-            lines.append(f"   Date: {date}")
-    elif search_type == "news":
-        title = result.get("title", "").strip()
-        url = result.get("url", "").strip()
-        body = result.get("body", "").strip()
-        date = result.get("date", "").strip()
-        source = result.get("source", "").strip()
-        lines.append(f"{index}. {title}")
-        lines.append(f"   URL: {url}")
-        if source:
-            lines.append(f"   Source: {source}")
-        if date:
-            lines.append(f"   Date: {date}")
-        if body:
-            lines.append(f"   Summary: {body}")
-    elif search_type == "images":
-        title = result.get("title", "").strip()
-        image_url = result.get("image", "").strip()
-        source_url = result.get("url", "").strip()
-        source = result.get("source", "").strip()
-        width = result.get("width", "")
-        height = result.get("height", "")
-        lines.append(f"{index}. {title}")
-        lines.append(f"   Image: {image_url}")
-        lines.append(f"   Source: {source_url}")
-        if source:
-            lines.append(f"   Publisher: {source}")
-        if width and height:
-            lines.append(f"   Dimensions: {width}x{height}")
-    elif search_type == "videos":
-        title = result.get("title", "").strip()
-        description = result.get("description", "").strip()
-        duration = result.get("duration", "").strip()
-        published = result.get("published", "").strip()
-        uploader = result.get("uploader", "").strip()
-        embed_url = result.get("embed_url", "").strip()
-        lines.append(f"{index}. {title}")
-        if embed_url:
-            lines.append(f"   Video: {embed_url}")
-        if uploader:
-            lines.append(f"   Uploader: {uploader}")
-        if duration:
-            lines.append(f"   Duration: {duration}")
-        if published:
-            lines.append(f"   Published: {published}")
-        if description:
-            lines.append(f"   Description: {description}")
-    elif search_type == "books":
-        title = result.get("title", "").strip()
-        url = result.get("url", "").strip()
-        body = result.get("body", "").strip()
-        lines.append(f"{index}. {title}")
-        lines.append(f"   URL: {url}")
-        if body:
-            lines.append(f"   Description: {body}")
-    return lines
-
-
-@autodoc(
-    summary=TOOL_SUMMARY,
-)
-def Web_Search(
-    query: Annotated[str, "The search query (supports operators like site:, quotes, OR)."],
-    max_results: Annotated[int, "Number of results to return (1–20)."] = 5,
-    page: Annotated[int, "Page number for pagination (1-based, each page contains max_results items)."] = 1,
-    offset: Annotated[int, "Result offset to start from (overrides page if > 0, for precise continuation)."] = 0,
-    search_type: Annotated[str, "Type of search: 'text' (web pages), 'news', 'images', 'videos', or 'books'."] = "text",
-    backend: Annotated[str, "Search backend or ordered fallbacks. Use 'auto' for recommended order."] = "auto",
-    date_filter: Annotated[str, "Time filter: any, day, week, month, year."] = "any",
-) -> str:
-    _log_call_start(
-        "Web_Search",
-        query=query,
-        max_results=max_results,
-        page=page,
-        search_type=search_type,
-        offset=offset,
-        backend=backend,
-        date_filter=date_filter,
-    )
-    if not query or not query.strip():
-        result = "No search query provided. Please enter a search term."
-        _log_call_end("Web_Search", _truncate_for_log(result))
-        return result
-    max_results = max(1, min(20, max_results))
-    page = max(1, page)
-    offset = max(0, offset)
-    valid_types = ["text", "news", "images", "videos", "books"]
-    if search_type not in valid_types:
-        search_type = "text"
-    if offset > 0:
-        actual_offset = offset
-        calculated_page = (offset // max_results) + 1
-    else:
-        actual_offset = (page - 1) * max_results
-        calculated_page = page
-    total_needed = actual_offset + max_results
-    used_fallback = False
-    original_search_type = search_type
-    # Prepare cross-cutting parameters
-    resolved_backend = _resolve_backend(search_type, (backend or "auto").lower())
-    timelimit = _resolve_timelimit(date_filter, search_type)
-
-    def _perform_search(stype: str) -> list[dict]:
-        try:
-            _search_rate_limiter.acquire()
-            with DDGS() as ddgs:
-                if stype == "text":
-                    user_backend_choice = (backend or "auto").lower()
-                    if user_backend_choice == "auto":
-                        # Custom auto: DDG first, then append other engines
-                        results: list[dict] = []
-                        seen: set[str] = set()
-
-                        def add_unique(items: list[dict], key_field: str) -> None:
-                            for it in items or []:
-                                url = (it.get(key_field, "") or "").strip()
-                                if url and url not in seen:
-                                    seen.add(url)
-                                    results.append(it)
-
-                        # First: duckduckgo
-                        try:
-                            ddg_items = list(
-                                ddgs.text(
-                                    query,
-                                    max_results=total_needed + 10,
-                                    safesearch=_SAFESEARCH_LEVEL,
-                                    timelimit=timelimit,
-                                    backend="duckduckgo",
-                                )
-                            )
-                        except Exception:
-                            ddg_items = []
-                        add_unique(ddg_items, "href")
-
-                        # Then: other engines appended (excluding duckduckgo)
-                        for eng in [b for b in _AUTO_ORDER["text"] if b != "duckduckgo"]:
-                            try:
-                                extra = list(
-                                    ddgs.text(
-                                        query,
-                                        max_results=total_needed + 10,
-                                        safesearch=_SAFESEARCH_LEVEL,
-                                        timelimit=timelimit,
-                                        backend=eng,
-                                    )
-                                )
-                            except Exception:
-                                extra = []
-                            add_unique(extra, "href")
-
-                        return results
-                    else:
-                        raw_gen = ddgs.text(
-                            query,
-                            max_results=total_needed + 10,
-                            safesearch=_SAFESEARCH_LEVEL,
-                            timelimit=timelimit,
-                            backend=resolved_backend,
-                        )
-                elif stype == "news":
-                    user_backend_choice = (backend or "auto").lower()
-                    if user_backend_choice == "auto":
-                        # Custom auto: DDG first, then append other engines
-                        results: list[dict] = []
-                        seen: set[str] = set()
-
-                        def add_unique(items: list[dict], key_field: str) -> None:
-                            for it in items or []:
-                                url = (it.get(key_field, "") or "").strip()
-                                if url and url not in seen:
-                                    seen.add(url)
-                                    results.append(it)
-
-                        # First: duckduckgo news
-                        try:
-                            ddg_news = list(
-                                ddgs.news(
-                                    query,
-                                    max_results=total_needed + 10,
-                                    safesearch=_SAFESEARCH_LEVEL,
-                                    timelimit=timelimit,
-                                    backend="duckduckgo",
-                                )
-                            )
-                        except Exception:
-                            ddg_news = []
-                        add_unique(ddg_news, "url")
-
-                        # Then: other news engines appended
-                        for eng in [b for b in _AUTO_ORDER["news"] if b != "duckduckgo"]:
-                            try:
-                                extra = list(
-                                    ddgs.news(
-                                        query,
-                                        max_results=total_needed + 10,
-                                        safesearch=_SAFESEARCH_LEVEL,
-                                        timelimit=timelimit,
-                                        backend=eng,
-                                    )
-                                )
-                            except Exception:
-                                extra = []
-                            add_unique(extra, "url")
-
-                        return results
-                    else:
-                        raw_gen = ddgs.news(
-                            query,
-                            max_results=total_needed + 10,
-                            safesearch=_SAFESEARCH_LEVEL,
-                            timelimit=timelimit,
-                            backend=_resolve_backend("news", (backend or "auto").lower()),
-                        )
-                elif stype == "images":
-                    raw_gen = ddgs.images(
-                        query,
-                        max_results=total_needed + 10,
-                        safesearch=_SAFESEARCH_LEVEL,
-                        timelimit=timelimit,
-                        backend=_resolve_backend("images", (backend or "auto").lower()),
-                    )
-                elif stype == "videos":
-                    raw_gen = ddgs.videos(
-                        query,
-                        max_results=total_needed + 10,
-                        safesearch=_SAFESEARCH_LEVEL,
-                        timelimit=timelimit,
-                        backend=_resolve_backend("videos", (backend or "auto").lower()),
-                    )
-                else:
-                    raw_gen = ddgs.books(
-                        query,
-                        max_results=total_needed + 10,
-                        backend=_resolve_backend("books", (backend or "auto").lower()),
-                    )
-                try:
-                    return list(raw_gen)
-                except Exception as inner_exc:
-                    if "no results" in str(inner_exc).lower() or "not found" in str(inner_exc).lower():
-                        return []
-                    raise inner_exc
-        except Exception as exc:
-            error_msg = f"Search failed: {str(exc)[:200]}"
-            lowered = str(exc).lower()
-            if "blocked" in lowered or "rate" in lowered:
-                error_msg = "Search temporarily blocked due to rate limiting. Please try again in a few minutes."
-            elif "timeout" in lowered:
-                error_msg = "Search timed out. Please try again with a simpler query."
-            elif "network" in lowered or "connection" in lowered:
-                error_msg = "Network connection error. Please check your internet connection and try again."
-            elif "no results" in lowered or "not found" in lowered:
-                return []
-            raise Exception(error_msg)
-
-    try:
-        raw = _perform_search(search_type)
-    except Exception as exc:
-        result = f"Error: {exc}"
-        _log_call_end("Web_Search", _truncate_for_log(result))
-        return result
-
-    if not raw and search_type == "news":
-        try:
-            raw = _perform_search("text")
-            if raw:
-                used_fallback = True
-                search_type = "text"
-        except Exception:
-            pass
-
-    if not raw:
-        fallback_note = " (also tried 'text' search as fallback)" if original_search_type == "news" and used_fallback else ""
-        result = f"No {original_search_type} results found for query: {query}{fallback_note}"
-        _log_call_end("Web_Search", _truncate_for_log(result))
-        return result
-
-    paginated_results = raw[actual_offset: actual_offset + max_results]
-    if not paginated_results:
-        if actual_offset >= len(raw):
-            result = f"Offset {actual_offset} exceeds available results ({len(raw)} total). Try offset=0 to start from beginning."
-        else:
-            result = f"No {original_search_type} results found on page {calculated_page} for query: {query}. Try page 1 or reduce page number."
-        _log_call_end("Web_Search", _truncate_for_log(result))
-        return result
-
-    total_available = len(raw)
-    start_num = actual_offset + 1
-    end_num = actual_offset + len(paginated_results)
-    next_offset = actual_offset + len(paginated_results)
-    search_label = original_search_type.title()
-    if used_fallback:
-        search_label += " → Text (Smart Fallback)"
-
-    now_dt = datetime.now().astimezone()
-    date_str = now_dt.strftime("%A, %B %d, %Y %I:%M %p %Z").strip()
-    if not date_str:
-        date_str = now_dt.isoformat()
-
-    pagination_info = f"Page {calculated_page}"
-    if offset > 0:
-        pagination_info = f"Offset {actual_offset} (≈ {pagination_info})"
-    lines = [f"Current Date: {date_str}", f"{search_label} search results for: {query}"]
-    if used_fallback:
-        lines.append("📍 Note: News search returned no results, automatically searched general web content instead")
-    lines.append(f"{pagination_info} (results {start_num}-{end_num} of ~{total_available}+ available)\n")
-    for i, result in enumerate(paginated_results, start_num):
-        result_lines = _format_search_result(result, search_type, i)
-        lines.extend(result_lines)
-        lines.append("")
-    if total_available > end_num:
-        lines.append("💡 More results available:")
-        lines.append(f"   • Next page: page={calculated_page + 1}")
-        lines.append(f"   • Next offset: offset={next_offset}")
-        lines.append(f"   • Use offset={next_offset} to continue exactly from result {next_offset + 1}")
-    result = "\n".join(lines)
-    search_info = f"type={original_search_type}"
-    if used_fallback:
-        search_info += "→text"
-    _log_call_end("Web_Search", f"{search_info} page={calculated_page} offset={actual_offset} results={len(paginated_results)} chars={len(result)}")
-    return result
-
-
-def build_interface() -> gr.Interface:
-    return gr.Interface(
-        fn=Web_Search,
-        inputs=[
-            gr.Textbox(label="Query", placeholder="topic OR site:example.com", max_lines=1, info="The search query"),
-            gr.Slider(minimum=1, maximum=20, value=5, step=1, label="Max results", info="Number of results to return (1–20)"),
-            gr.Slider(minimum=1, maximum=10, value=1, step=1, label="Page", info="Page number for pagination (ignored if offset > 0)"),
-            gr.Slider(
-                minimum=0,
-                maximum=1000,
-                value=0,
-                step=1,
-                label="Offset",
-                info="Result offset to start from (overrides page if > 0, use next_offset from previous search)",
-            ),
-            gr.Radio(
-                label="Search Type",
-                choices=["text", "news", "images", "videos", "books"],
-                value="text",
-                info="Type of content to search for",
-            ),
-            gr.Radio(
-                label="Backend",
-                choices=BACKEND_CHOICES,
-                value="auto",
-                info="Search engine backend or fallback order (auto applies recommended order)",
-            ),
-            gr.Radio(
-                label="Date filter",
-                choices=DATE_FILTER_CHOICES,
-                value="any",
-                info="Limit results to: day, week, month, or year (varies by type)",
-            ),
-        ],
-        outputs=gr.Textbox(label="Search Results", interactive=False, lines=20, max_lines=20),
-        title="Web Search",
-        description=(
-            "<div style=\"text-align:center\">Multi-type web search with readable output format, date detection, and flexible pagination. "
-            "Supports text, news, images, videos, and books. Features smart fallback for news searches and precise offset control.</div>"
-        ),
-        api_description=TOOL_SUMMARY,
-        flagging_mode="never",
-        submit_btn="Search",
-    )
-
-
-__all__ = ["Web_Search", "build_interface"]
+from __future__ import annotations
+
+from typing import Annotated, List, Literal
+from datetime import datetime
+
+import gradio as gr
+from ddgs import DDGS
+
+from app import _log_call_end, _log_call_start, _search_rate_limiter, _truncate_for_log
+from ._docstrings import autodoc
+from ._searxng_client import SearXNGClient, TimeRange
+from ._query_optimizer import get_optimizer
+
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Run a web search across text, news, images, videos, or books. "
+    "Supports multiple backends (DuckDuckGo, SearXNG) with optional AI query optimization. "
+    "Readable results include pagination hints and next_offset when more results are available."
+)
+
+
+_SAFESEARCH_LEVEL = "off"
+
+# Defaults and choices for newly added parameters
+BACKEND_CHOICES = [
+    "auto",
+    "duckduckgo",
+    "searxng",
+    "bing",
+    "brave",
+    "yahoo",
+    "wikipedia",
+]
+
+# Allowed backends per type (explicit selection set)
+_ALLOWED_BACKENDS = {
+    "text": ["duckduckgo", "searxng", "bing", "brave", "yahoo", "wikipedia"],
+    "news": ["duckduckgo", "searxng", "bing", "yahoo"],
+    "images": ["duckduckgo", "searxng"],
+    "videos": ["duckduckgo"],
+    "books": ["annasarchive"],
+}
+
+# Auto order per type (used when backend == "auto"); wikipedia excluded for text
+_AUTO_ORDER = {
+    "text": ["searxng", "duckduckgo", "bing", "brave", "yahoo"],
+    "news": ["searxng", "duckduckgo", "bing", "yahoo"],
+    "images": ["searxng", "duckduckgo"],
+    "videos": ["duckduckgo"],
+    "books": ["annasarchive"],
+}
+
+# Date filter choices: canonical values used by resolver
+DATE_FILTER_CHOICES = ["any", "day", "week", "month", "year"]
+
+
+def _resolve_backend(search_type: str, backend_choice: str) -> str:
+    """Resolve backend string for DDGS based on search type and user choice.
+
+    - If backend_choice is "auto", return a comma-separated fallback order for that type.
+    - If backend_choice is not supported by the type, fall back to the first allowed backend.
+    - Books endpoint uses only 'annasarchive'.
+    """
+    stype = search_type if search_type in _ALLOWED_BACKENDS else "text"
+    allowed = _ALLOWED_BACKENDS[stype]
+    if backend_choice == "auto":
+        return ", ".join(_AUTO_ORDER[stype])
+    if stype == "books":
+        return "annasarchive"
+    # Validate backend against allowed set for this type
+    if backend_choice in allowed:
+        return backend_choice
+    # Fallback to first allowed backend
+    return allowed[0]
+
+
+def _resolve_timelimit(date_filter: str, search_type: str) -> str | None:
+    """Map UI date filter to DDGS timelimit code per endpoint.
+
+    Returns one of: None, 'd', 'w', 'm', 'y'. For news/videos (which support d/w/m),
+    selecting 'year' will coerce to 'm' to stay within supported range.
+    """
+    normalized = (date_filter or "any").strip().lower()
+    if normalized in ("any", "none", ""):
+        return None
+    mapping = {
+        "day": "d",
+        "week": "w",
+        "month": "m",
+        "year": "y",
+    }
+    code = mapping.get(normalized)
+    if not code:
+        return None
+    if search_type in ("news", "videos") and code == "y":
+        return "m"
+    return code
+
+
+def _extract_date_from_snippet(snippet: str) -> str:
+    if not snippet:
+        return ""
+    import re
+
+    date_patterns = [
+        r"\b(\d{4}[-/]\d{1,2}[-/]\d{1,2})\b",
+        r"\b([A-Za-z]{3,9}\s+\d{1,2},?\s+\d{4})\b",
+        r"\b(\d{1,2}\s+[A-Za-z]{3,9}\s+\d{4})\b",
+        r"\b(\d+\s+(?:day|week|month|year)s?\s+ago)\b",
+        r"(?:Published|Updated|Posted):\s*([^,\n]+?)(?:[,\n]|$)",
+    ]
+    for pattern in date_patterns:
+        matches = re.findall(pattern, snippet, re.IGNORECASE)
+        if matches:
+            return matches[0].strip()
+    return ""
+
+
+def _format_search_result(result: dict, search_type: str, index: int) -> List[str]:
+    lines: List[str] = []
+    if search_type == "text":
+        title = result.get("title", "").strip()
+        url = result.get("href", "").strip()
+        snippet = result.get("body", "").strip()
+        date = _extract_date_from_snippet(snippet)
+        lines.append(f"{index}. {title}")
+        lines.append(f"   URL: {url}")
+        if snippet:
+            lines.append(f"   Summary: {snippet}")
+        if date:
+            lines.append(f"   Date: {date}")
+    elif search_type == "news":
+        title = result.get("title", "").strip()
+        url = result.get("url", "").strip()
+        body = result.get("body", "").strip()
+        date = result.get("date", "").strip()
+        source = result.get("source", "").strip()
+        lines.append(f"{index}. {title}")
+        lines.append(f"   URL: {url}")
+        if source:
+            lines.append(f"   Source: {source}")
+        if date:
+            lines.append(f"   Date: {date}")
+        if body:
+            lines.append(f"   Summary: {body}")
+    elif search_type == "images":
+        title = result.get("title", "").strip()
+        image_url = result.get("image", "").strip()
+        source_url = result.get("url", "").strip()
+        source = result.get("source", "").strip()
+        width = result.get("width", "")
+        height = result.get("height", "")
+        lines.append(f"{index}. {title}")
+        lines.append(f"   Image: {image_url}")
+        lines.append(f"   Source: {source_url}")
+        if source:
+            lines.append(f"   Publisher: {source}")
+        if width and height:
+            lines.append(f"   Dimensions: {width}x{height}")
+    elif search_type == "videos":
+        title = result.get("title", "").strip()
+        description = result.get("description", "").strip()
+        duration = result.get("duration", "").strip()
+        published = result.get("published", "").strip()
+        uploader = result.get("uploader", "").strip()
+        embed_url = result.get("embed_url", "").strip()
+        lines.append(f"{index}. {title}")
+        if embed_url:
+            lines.append(f"   Video: {embed_url}")
+        if uploader:
+            lines.append(f"   Uploader: {uploader}")
+        if duration:
+            lines.append(f"   Duration: {duration}")
+        if published:
+            lines.append(f"   Published: {published}")
+        if description:
+            lines.append(f"   Description: {description}")
+    elif search_type == "books":
+        title = result.get("title", "").strip()
+        url = result.get("url", "").strip()
+        body = result.get("body", "").strip()
+        lines.append(f"{index}. {title}")
+        lines.append(f"   URL: {url}")
+        if body:
+            lines.append(f"   Description: {body}")
+    return lines
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Web_Search(
+    query: Annotated[str, "The search query (supports operators like site:, quotes, OR)."],
+    max_results: Annotated[int, "Number of results to return (1–20)."] = 5,
+    page: Annotated[int, "Page number for pagination (1-based, each page contains max_results items)."] = 1,
+    offset: Annotated[int, "Result offset to start from (overrides page if > 0, for precise continuation)."] = 0,
+    search_type: Annotated[str, "Type of search: 'text' (web pages), 'news', 'images', 'videos', or 'books'."] = "text",
+    backend: Annotated[str, "Search backend: 'duckduckgo', 'searxng', or 'auto' (SearXNG first, then DDG)."] = "auto",
+    date_filter: Annotated[str, "Time filter: any, day, week, month, year."] = "any",
+    optimize_query: Annotated[bool, "Use AI to optimize the query for better results (adds ~2s latency)."] = False,
+) -> str:
+    _log_call_start(
+        "Web_Search",
+        query=query,
+        max_results=max_results,
+        page=page,
+        search_type=search_type,
+        offset=offset,
+        backend=backend,
+        date_filter=date_filter,
+        optimize_query=optimize_query,
+    )
+
+    # Query optimization (optional)
+    optimization_metadata = None
+    if optimize_query:
+        try:
+            optimizer = get_optimizer()
+            query, optimization_metadata = optimizer.optimize_for_search_engine(query)
+        except Exception as exc:
+            print(f"[Web_Search] Query optimization failed: {exc}", flush=True)
+            # Continue with original query
+
+    if not query or not query.strip():
+        result = "No search query provided. Please enter a search term."
+        _log_call_end("Web_Search", _truncate_for_log(result))
+        return result
+    max_results = max(1, min(20, max_results))
+    page = max(1, page)
+    offset = max(0, offset)
+    valid_types = ["text", "news", "images", "videos", "books"]
+    if search_type not in valid_types:
+        search_type = "text"
+    if offset > 0:
+        actual_offset = offset
+        calculated_page = (offset // max_results) + 1
+    else:
+        actual_offset = (page - 1) * max_results
+        calculated_page = page
+    total_needed = actual_offset + max_results
+    used_fallback = False
+    original_search_type = search_type
+    # Prepare cross-cutting parameters
+    resolved_backend = _resolve_backend(search_type, (backend or "auto").lower())
+    timelimit = _resolve_timelimit(date_filter, search_type)
+
+    # Map date_filter to SearXNG TimeRange
+    _TIME_RANGE_MAP = {
+        "day": TimeRange.DAY,
+        "week": TimeRange.WEEK,
+        "month": TimeRange.MONTH,
+        "year": TimeRange.YEAR,
+    }
+    searxng_time_range = _TIME_RANGE_MAP.get(date_filter.lower()) if date_filter else None
+
+    def _perform_searxng_search(stype: str) -> list[dict]:
+        """Perform search using SearXNG backend."""
+        try:
+            _search_rate_limiter.acquire()
+            with SearXNGClient() as client:
+                if stype == "text":
+                    results = client.text(query, max_results=total_needed, time_range=searxng_time_range)
+                    return [
+                        {
+                            "title": r.title,
+                            "href": r.url,
+                            "body": r.content,
+                            "engine": r.engine,
+                        }
+                        for r in results
+                    ]
+                elif stype == "news":
+                    results = client.news(query, max_results=total_needed, time_range=searxng_time_range)
+                    return [
+                        {
+                            "title": r.title,
+                            "url": r.url,
+                            "body": r.content,
+                            "date": r.published_date or "",
+                            "source": r.engine or "",
+                        }
+                        for r in results
+                    ]
+                elif stype == "images":
+                    results = client.images(query, max_results=total_needed)
+                    return [
+                        {
+                            "title": r.title,
+                            "image": r.img_src,
+                            "url": r.url,
+                            "source": r.source or r.engine or "",
+                            "thumbnail": r.thumbnail_src,
+                        }
+                        for r in results
+                    ]
+                return []
+        except Exception as exc:
+            print(f"[Web_Search] SearXNG error: {exc}", flush=True)
+            return []
+
+    def _perform_search(stype: str) -> list[dict]:
+        user_backend_choice = (backend or "auto").lower()
+
+        # Handle SearXNG backend explicitly
+        if user_backend_choice == "searxng":
+            return _perform_searxng_search(stype)
+
+        # Handle auto: SearXNG first, then DDG fallback
+        if user_backend_choice == "auto":
+            # Try SearXNG first
+            searxng_results = _perform_searxng_search(stype)
+            if searxng_results:
+                return searxng_results
+            # Fallback to DDG
+            print(f"[Web_Search] SearXNG returned no results, falling back to DuckDuckGo", flush=True)
+
+        try:
+            _search_rate_limiter.acquire()
+            with DDGS() as ddgs:
+                if stype == "text":
+                    if user_backend_choice == "auto":
+                        # Auto fallback to DDG after SearXNG failed
+                        raw_gen = ddgs.text(
+                            query,
+                            max_results=total_needed + 10,
+                            safesearch=_SAFESEARCH_LEVEL,
+                            timelimit=timelimit,
+                            backend="duckduckgo",
+                        )
+                    else:
+                        raw_gen = ddgs.text(
+                            query,
+                            max_results=total_needed + 10,
+                            safesearch=_SAFESEARCH_LEVEL,
+                            timelimit=timelimit,
+                            backend=resolved_backend,
+                        )
+                elif stype == "news":
+                    if user_backend_choice == "auto":
+                        # Auto fallback to DDG after SearXNG failed
+                        raw_gen = ddgs.news(
+                            query,
+                            max_results=total_needed + 10,
+                            safesearch=_SAFESEARCH_LEVEL,
+                            timelimit=timelimit,
+                            backend="duckduckgo",
+                        )
+                    else:
+                        raw_gen = ddgs.news(
+                            query,
+                            max_results=total_needed + 10,
+                            safesearch=_SAFESEARCH_LEVEL,
+                            timelimit=timelimit,
+                            backend=_resolve_backend("news", user_backend_choice),
+                        )
+                elif stype == "images":
+                    raw_gen = ddgs.images(
+                        query,
+                        max_results=total_needed + 10,
+                        safesearch=_SAFESEARCH_LEVEL,
+                        timelimit=timelimit,
+                        backend=_resolve_backend("images", (backend or "auto").lower()),
+                    )
+                elif stype == "videos":
+                    raw_gen = ddgs.videos(
+                        query,
+                        max_results=total_needed + 10,
+                        safesearch=_SAFESEARCH_LEVEL,
+                        timelimit=timelimit,
+                        backend=_resolve_backend("videos", (backend or "auto").lower()),
+                    )
+                else:
+                    raw_gen = ddgs.books(
+                        query,
+                        max_results=total_needed + 10,
+                        backend=_resolve_backend("books", (backend or "auto").lower()),
+                    )
+                try:
+                    return list(raw_gen)
+                except Exception as inner_exc:
+                    if "no results" in str(inner_exc).lower() or "not found" in str(inner_exc).lower():
+                        return []
+                    raise inner_exc
+        except Exception as exc:
+            error_msg = f"Search failed: {str(exc)[:200]}"
+            lowered = str(exc).lower()
+            if "blocked" in lowered or "rate" in lowered:
+                error_msg = "Search temporarily blocked due to rate limiting. Please try again in a few minutes."
+            elif "timeout" in lowered:
+                error_msg = "Search timed out. Please try again with a simpler query."
+            elif "network" in lowered or "connection" in lowered:
+                error_msg = "Network connection error. Please check your internet connection and try again."
+            elif "no results" in lowered or "not found" in lowered:
+                return []
+            raise Exception(error_msg)
+
+    try:
+        raw = _perform_search(search_type)
+    except Exception as exc:
+        result = f"Error: {exc}"
+        _log_call_end("Web_Search", _truncate_for_log(result))
+        return result
+
+    if not raw and search_type == "news":
+        try:
+            raw = _perform_search("text")
+            if raw:
+                used_fallback = True
+                search_type = "text"
+        except Exception:
+            pass
+
+    if not raw:
+        fallback_note = " (also tried 'text' search as fallback)" if original_search_type == "news" and used_fallback else ""
+        result = f"No {original_search_type} results found for query: {query}{fallback_note}"
+        _log_call_end("Web_Search", _truncate_for_log(result))
+        return result
+
+    paginated_results = raw[actual_offset: actual_offset + max_results]
+    if not paginated_results:
+        if actual_offset >= len(raw):
+            result = f"Offset {actual_offset} exceeds available results ({len(raw)} total). Try offset=0 to start from beginning."
+        else:
+            result = f"No {original_search_type} results found on page {calculated_page} for query: {query}. Try page 1 or reduce page number."
+        _log_call_end("Web_Search", _truncate_for_log(result))
+        return result
+
+    total_available = len(raw)
+    start_num = actual_offset + 1
+    end_num = actual_offset + len(paginated_results)
+    next_offset = actual_offset + len(paginated_results)
+    search_label = original_search_type.title()
+    if used_fallback:
+        search_label += " → Text (Smart Fallback)"
+
+    now_dt = datetime.now().astimezone()
+    date_str = now_dt.strftime("%A, %B %d, %Y %I:%M %p %Z").strip()
+    if not date_str:
+        date_str = now_dt.isoformat()
+
+    pagination_info = f"Page {calculated_page}"
+    if offset > 0:
+        pagination_info = f"Offset {actual_offset} (≈ {pagination_info})"
+    lines = [f"Current Date: {date_str}", f"{search_label} search results for: {query}"]
+    if used_fallback:
+        lines.append("📍 Note: News search returned no results, automatically searched general web content instead")
+    lines.append(f"{pagination_info} (results {start_num}-{end_num} of ~{total_available}+ available)\n")
+    for i, result in enumerate(paginated_results, start_num):
+        result_lines = _format_search_result(result, search_type, i)
+        lines.extend(result_lines)
+        lines.append("")
+    if total_available > end_num:
+        lines.append("💡 More results available:")
+        lines.append(f"   • Next page: page={calculated_page + 1}")
+        lines.append(f"   • Next offset: offset={next_offset}")
+        lines.append(f"   • Use offset={next_offset} to continue exactly from result {next_offset + 1}")
+    result = "\n".join(lines)
+    search_info = f"type={original_search_type}"
+    if used_fallback:
+        search_info += "→text"
+    _log_call_end("Web_Search", f"{search_info} page={calculated_page} offset={actual_offset} results={len(paginated_results)} chars={len(result)}")
+    return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Web_Search,
+        inputs=[
+            gr.Textbox(label="Query", placeholder="topic OR site:example.com", max_lines=1, info="The search query"),
+            gr.Slider(minimum=1, maximum=20, value=5, step=1, label="Max results", info="Number of results to return (1–20)"),
+            gr.Slider(minimum=1, maximum=10, value=1, step=1, label="Page", info="Page number for pagination (ignored if offset > 0)"),
+            gr.Slider(
+                minimum=0,
+                maximum=1000,
+                value=0,
+                step=1,
+                label="Offset",
+                info="Result offset to start from (overrides page if > 0, use next_offset from previous search)",
+            ),
+            gr.Radio(
+                label="Search Type",
+                choices=["text", "news", "images", "videos", "books"],
+                value="text",
+                info="Type of content to search for",
+            ),
+            gr.Radio(
+                label="Backend",
+                choices=BACKEND_CHOICES,
+                value="auto",
+                info="Search backend: auto (SearXNG → DDG), searxng, or duckduckgo",
+            ),
+            gr.Radio(
+                label="Date filter",
+                choices=DATE_FILTER_CHOICES,
+                value="any",
+                info="Limit results to: day, week, month, or year",
+            ),
+            gr.Checkbox(
+                label="Optimize Query",
+                value=False,
+                info="Use AI to optimize the query for better results (adds ~2s latency)",
+            ),
+        ],
+        outputs=gr.Textbox(label="Search Results", interactive=False, lines=20, max_lines=20),
+        title="Web Search",
+        description=(
+            "<div style=\"text-align:center\">Multi-backend web search (SearXNG + DuckDuckGo) with optional AI query optimization. "
+            "Supports text, news, images, videos, and books. Auto backend tries SearXNG first, then DDG fallback.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Search",
+    )
+
+
+__all__ = ["Web_Search", "build_interface"]

Modules/_core.py

@@ -1,861 +1,861 @@
-"""
-Core shared utilities for the Nymbo-Tools MCP server.
-
-Consolidates three key areas:
-1. Sandboxed filesystem operations (path resolution, reading, writing, safe_open)
-2. Sandboxed Python execution (code interpreter, agent terminal)
-3. Hugging Face inference utilities (token, providers, error handling)
-"""
-
-from __future__ import annotations
-
-import ast
-import json
-import os
-import re
-import stat
-import sys
-from datetime import datetime
-from io import StringIO
-from typing import Any, Callable, Optional, TypeVar
-
-import gradio as gr
-
-
-# ===========================================================================
-# Part 0: Tree Rendering Utilities
-# ===========================================================================
-
-
-def _fmt_size(num_bytes: int) -> str:
-    """Format byte size as human-readable string."""
-    units = ["B", "KB", "MB", "GB"]
-    size = float(num_bytes)
-    for unit in units:
-        if size < 1024.0:
-            return f"{size:.1f} {unit}"
-        size /= 1024.0
-    return f"{size:.1f} TB"
-
-
-def build_tree(entries: list[tuple[str, dict]]) -> dict:
-    """
-    Build a nested tree structure from flat path entries.
-    
-    Args:
-        entries: List of (path, metadata) tuples where path uses forward slashes.
-                 Paths ending with '/' are treated as directories.
-    
-    Returns:
-        Nested dict with "__files__" key for files at each level.
-    """
-    root: dict = {"__files__": []}
-    
-    for path, metadata in entries:
-        parts = path.rstrip("/").split("/")
-        is_dir = path.endswith("/")
-        
-        node = root
-        for i, part in enumerate(parts[:-1]):
-            if part not in node:
-                node[part] = {"__files__": []}
-            node = node[part]
-        
-        final = parts[-1]
-        if is_dir:
-            if final not in node:
-                node[final] = {"__files__": []}
-            if metadata:
-                node[final]["__meta__"] = metadata
-        else:
-            node["__files__"].append((final, metadata))
-    
-    return root
-
-
-def render_tree(
-    node: dict,
-    prefix: str = "",
-    format_entry: Optional[Callable[[str, dict, bool], str]] = None,
-) -> list[str]:
-    """
-    Render a tree with line connectors.
-    
-    Args:
-        node: Nested dict from build_tree()
-        prefix: Current line prefix for indentation
-        format_entry: Optional callback to format each entry.
-    
-    Returns:
-        List of formatted lines.
-    """
-    result = []
-    
-    def default_format(name: str, meta: dict, is_dir: bool) -> str:
-        if is_dir:
-            return f"{name}/"
-        size = meta.get("size")
-        if size is not None:
-            return f"{name}  ({_fmt_size(size)})"
-        return name
-    
-    fmt = format_entry or default_format
-    
-    entries = []
-    subdirs = sorted(k for k in node.keys() if k not in ("__files__", "__meta__"))
-    files_here = sorted(node.get("__files__", []), key=lambda x: x[0])
-    
-    for dirname in subdirs:
-        dir_meta = node[dirname].get("__meta__", {})
-        entries.append(("dir", dirname, node[dirname], dir_meta))
-    for fname, fmeta in files_here:
-        entries.append(("file", fname, None, fmeta))
-    
-    for i, entry in enumerate(entries):
-        is_last = (i == len(entries) - 1)
-        connector = "└── " if is_last else "├── "
-        child_prefix = prefix + ("    " if is_last else "│   ")
-        
-        etype, name, subtree, meta = entry
-        
-        if etype == "dir":
-            result.append(f"{prefix}{connector}{fmt(name, meta, True)}")
-            result.extend(render_tree(subtree, child_prefix, format_entry))
-        else:
-            result.append(f"{prefix}{connector}{fmt(name, meta, False)}")
-    
-    return result
-
-
-def walk_and_build_tree(
-    abs_path: str,
-    *,
-    show_hidden: bool = False,
-    recursive: bool = False,
-    max_entries: int = 100,
-) -> tuple[dict, int, bool]:
-    """
-    Walk a directory and build a tree structure.
-    
-    Returns:
-        (tree, total_entries, truncated)
-    """
-    entries: list[tuple[str, dict]] = []
-    total = 0
-    truncated = False
-    
-    for root, dirs, files in os.walk(abs_path):
-        if not show_hidden:
-            dirs[:] = [d for d in dirs if not d.startswith('.')]
-            files = [f for f in files if not f.startswith('.')]
-        
-        dirs.sort()
-        files.sort()
-        
-        try:
-            rel_root = os.path.relpath(root, abs_path)
-        except Exception:
-            rel_root = ""
-        prefix = "" if rel_root == "." else rel_root.replace("\\", "/") + "/"
-        
-        for d in dirs:
-            p = os.path.join(root, d)
-            try:
-                mtime = datetime.fromtimestamp(os.path.getmtime(p)).strftime("%Y-%m-%d %H:%M")
-            except Exception:
-                mtime = "?"
-            entries.append((f"{prefix}{d}/", {"mtime": mtime}))
-            total += 1
-            if total >= max_entries:
-                truncated = True
-                break
-        
-        if truncated:
-            break
-        
-        for f in files:
-            p = os.path.join(root, f)
-            try:
-                size = os.path.getsize(p)
-                mtime = datetime.fromtimestamp(os.path.getmtime(p)).strftime("%Y-%m-%d %H:%M")
-            except Exception:
-                size, mtime = 0, "?"
-            entries.append((f"{prefix}{f}", {"size": size, "mtime": mtime}))
-            total += 1
-            if total >= max_entries:
-                truncated = True
-                break
-        
-        if truncated:
-            break
-        
-        if not recursive:
-            break
-    
-    return build_tree(entries), total, truncated
-
-
-def format_dir_listing(
-    abs_path: str,
-    display_path: str,
-    *,
-    show_hidden: bool = False,
-    recursive: bool = False,
-    max_entries: int = 100,
-    fmt_size_fn: Optional[Callable[[int], str]] = None,
-) -> str:
-    """Format a directory listing as a visual tree."""
-    fmt_size = fmt_size_fn or _fmt_size
-    
-    tree, total, truncated = walk_and_build_tree(
-        abs_path,
-        show_hidden=show_hidden,
-        recursive=recursive,
-        max_entries=max_entries,
-    )
-    
-    def format_entry(name: str, meta: dict, is_dir: bool) -> str:
-        mtime = meta.get("mtime", "")
-        if is_dir:
-            return f"{name}/  ({mtime})"
-        size = meta.get("size", 0)
-        return f"{name}  ({fmt_size(size)}, {mtime})"
-    
-    tree_lines = render_tree(tree, "    ", format_entry)
-    
-    header = f"Listing of {display_path}\nRoot: /\nEntries: {total}"
-    if truncated:
-        header += f"\n… Truncated at {max_entries} entries."
-    
-    lines = [header, "", "└── /"]
-    lines.extend(tree_lines)
-    
-    return "\n".join(lines).strip()
-
-
-# ===========================================================================
-# Part 1: Sandboxed Filesystem Operations
-# ===========================================================================
-
-
-class SandboxedRoot:
-    """
-    A configurable sandboxed root directory with path resolution and safety checks.
-    
-    Args:
-        root_dir: Absolute path to the sandbox root.
-        allow_abs: If True, allow absolute paths outside the sandbox.
-    """
-    
-    def __init__(self, root_dir: str, allow_abs: bool = False):
-        self.root_dir = os.path.abspath(root_dir)
-        self.allow_abs = allow_abs
-        # Ensure root exists
-        try:
-            os.makedirs(self.root_dir, exist_ok=True)
-        except Exception:
-            pass
-    
-    def safe_err(self, exc: Exception | str) -> str:
-        """Return an error string with any absolute root replaced by '/' and slashes normalized."""
-        s = str(exc)
-        s_norm = s.replace("\\", "/")
-        root_fwd = self.root_dir.replace("\\", "/")
-        root_variants = {self.root_dir, root_fwd, re.sub(r"/+", "/", root_fwd)}
-        for variant in root_variants:
-            if variant:
-                s_norm = s_norm.replace(variant, "/")
-        s_norm = re.sub(r"/+", "/", s_norm)
-        return s_norm
-
-    def err(
-        self,
-        code: str,
-        message: str,
-        *,
-        path: Optional[str] = None,
-        hint: Optional[str] = None,
-        data: Optional[dict] = None,
-    ) -> str:
-        """Return a structured error JSON string."""
-        payload = {
-            "status": "error",
-            "code": code,
-            "message": message,
-            "root": "/",
-        }
-        if path is not None and path != "":
-            payload["path"] = path
-        if hint:
-            payload["hint"] = hint
-        if data:
-            payload["data"] = data
-        return json.dumps(payload, ensure_ascii=False)
-
-    def display_path(self, abs_path: str) -> str:
-        """Return a user-friendly path relative to root using forward slashes."""
-        try:
-            norm_root = os.path.normpath(self.root_dir)
-            norm_abs = os.path.normpath(abs_path)
-            common = os.path.commonpath([norm_root, norm_abs])
-            if os.path.normcase(common) == os.path.normcase(norm_root):
-                rel = os.path.relpath(norm_abs, norm_root)
-                if rel == ".":
-                    return "/"
-                return "/" + rel.replace("\\", "/")
-        except Exception:
-            pass
-        return abs_path.replace("\\", "/")
-
-    def resolve_path(self, path: str) -> tuple[str, str]:
-        """
-        Resolve a user-provided path to an absolute, normalized path constrained to root.
-        Returns (abs_path, error_message). error_message is empty when ok.
-        """
-        try:
-            user_input = (path or "/").strip() or "/"
-            if user_input.startswith("/"):
-                rel_part = user_input.lstrip("/") or "."
-                raw = os.path.expanduser(rel_part)
-                treat_as_relative = True
-            else:
-                raw = os.path.expanduser(user_input)
-                treat_as_relative = False
-
-            if not treat_as_relative and os.path.isabs(raw):
-                if not self.allow_abs:
-                    return "", self.err(
-                        "absolute_path_disabled",
-                        "Absolute paths are disabled in safe mode.",
-                        path=raw.replace("\\", "/"),
-                        hint="Use a path relative to / (e.g., /notes/todo.txt).",
-                    )
-                abs_path = os.path.abspath(raw)
-            else:
-                abs_path = os.path.abspath(os.path.join(self.root_dir, raw))
-            
-            # Constrain to root when not allowing absolute paths
-            if not self.allow_abs:
-                try:
-                    common = os.path.commonpath(
-                        [os.path.normpath(self.root_dir), os.path.normpath(abs_path)]
-                    )
-                    if common != os.path.normpath(self.root_dir):
-                        return "", self.err(
-                            "path_outside_root",
-                            "Path is outside the sandbox root.",
-                            path=abs_path,
-                        )
-                except Exception:
-                    return "", self.err(
-                        "path_outside_root",
-                        "Path is outside the sandbox root.",
-                        path=abs_path,
-                    )
-
-            return abs_path, ""
-        except Exception as exc:
-            return "", self.err(
-                "resolve_path_failed",
-                "Failed to resolve path.",
-                path=(path or ""),
-                data={"error": self.safe_err(exc)},
-            )
-
-    def safe_open(self, file, *args, **kwargs):
-        """A drop-in replacement for open() that enforces sandbox constraints."""
-        if isinstance(file, int):
-            return open(file, *args, **kwargs)
-        
-        path_str = os.fspath(file)
-        abs_path, err = self.resolve_path(path_str)
-        if err:
-            try:
-                msg = json.loads(err)["message"]
-            except Exception:
-                msg = err
-            raise PermissionError(f"Sandboxed open() failed: {msg}")
-        
-        return open(abs_path, *args, **kwargs)
-
-    def list_dir(
-        self,
-        abs_path: str,
-        *,
-        show_hidden: bool = False,
-        recursive: bool = False,
-        max_entries: int = 100,
-    ) -> str:
-        """List directory contents as a visual tree."""
-        return format_dir_listing(
-            abs_path,
-            self.display_path(abs_path),
-            show_hidden=show_hidden,
-            recursive=recursive,
-            max_entries=max_entries,
-            fmt_size_fn=_fmt_size,
-        )
-
-    def search_text(
-        self,
-        abs_path: str,
-        query: str,
-        *,
-        recursive: bool = False,
-        show_hidden: bool = False,
-        max_results: int = 20,
-        case_sensitive: bool = False,
-        start_index: int = 0,
-    ) -> str:
-        """Search for text within files."""
-        if not os.path.exists(abs_path):
-            return self.err(
-                "path_not_found",
-                f"Path not found: {self.display_path(abs_path)}",
-                path=self.display_path(abs_path),
-            )
-
-        query = query or ""
-        normalized_query = query if case_sensitive else query.lower()
-        if normalized_query == "":
-            return self.err(
-                "missing_search_query",
-                "Search query is required for the search action.",
-                hint="Provide text in the Content field to search for.",
-            )
-
-        max_results = max(1, int(max_results) if max_results is not None else 20)
-        start_index = max(0, int(start_index) if start_index is not None else 0)
-        matches: list[tuple[str, int, str]] = []
-        errors: list[str] = []
-        files_scanned = 0
-        truncated = False
-        total_matches = 0
-
-        def _should_skip(name: str) -> bool:
-            return not show_hidden and name.startswith(".")
-
-        def _handle_match(file_path: str, line_no: int, line_text: str) -> bool:
-            nonlocal truncated, total_matches
-            total_matches += 1
-            if total_matches <= start_index:
-                return False
-            if len(matches) < max_results:
-                snippet = line_text.strip()
-                if len(snippet) > 200:
-                    snippet = snippet[:197] + "…"
-                matches.append((self.display_path(file_path), line_no, snippet))
-                return False
-            truncated = True
-            return True
-
-        def _search_file(file_path: str) -> bool:
-            nonlocal files_scanned
-            files_scanned += 1
-            try:
-                with open(file_path, "r", encoding="utf-8", errors="replace") as handle:
-                    for line_no, line in enumerate(handle, start=1):
-                        haystack = line if case_sensitive else line.lower()
-                        if normalized_query in haystack:
-                            if _handle_match(file_path, line_no, line):
-                                return True
-            except Exception as exc:
-                errors.append(f"{self.display_path(file_path)} ({self.safe_err(exc)})")
-            return truncated
-
-        if os.path.isfile(abs_path):
-            _search_file(abs_path)
-        else:
-            for root, dirs, files in os.walk(abs_path):
-                dirs[:] = [d for d in dirs if not _should_skip(d)]
-                visible_files = [f for f in files if show_hidden or not f.startswith(".")]
-                for name in visible_files:
-                    file_path = os.path.join(root, name)
-                    if _search_file(file_path):
-                        break
-                if truncated:
-                    break
-                if not recursive:
-                    break
-
-        header_lines = [
-            f"Search results for {query!r}",
-            f"Scope: {self.display_path(abs_path)}",
-            f"Recursive: {'yes' if recursive else 'no'}, Hidden: {'yes' if show_hidden else 'no'}, Case-sensitive: {'yes' if case_sensitive else 'no'}",
-            f"Start offset: {start_index}",
-            f"Matches returned: {len(matches)}" + (" (truncated)" if truncated else ""),
-            f"Files scanned: {files_scanned}",
-        ]
-
-        next_cursor = start_index + len(matches) if truncated else None
-
-        if truncated:
-            header_lines.append(f"Matches encountered before truncation: {total_matches}")
-            header_lines.append(f"Truncated: yes — re-run with offset={next_cursor} to continue.")
-            header_lines.append(f"Next cursor: {next_cursor}")
-        else:
-            header_lines.append(f"Total matches found: {total_matches}")
-            header_lines.append("Truncated: no — end of results.")
-            header_lines.append("Next cursor: None")
-
-        if not matches:
-            if total_matches > 0 and start_index >= total_matches:
-                hint_limit = max(total_matches - 1, 0)
-                body_lines = [
-                    f"No matches found at or after offset {start_index}. Total matches available: {total_matches}.",
-                    (f"Try a smaller offset (≤ {hint_limit})." if hint_limit >= 0 else ""),
-                ]
-                body_lines = [line for line in body_lines if line]
-            else:
-                body_lines = [
-                    "No matches found.",
-                    (f"Total matches encountered: {total_matches}." if total_matches else ""),
-                ]
-                body_lines = [line for line in body_lines if line]
-        else:
-            body_lines = [
-                f"{idx}. {path}:{line_no}: {text}"
-                for idx, (path, line_no, text) in enumerate(matches, start=1)
-            ]
-
-        if errors:
-            shown = errors[:5]
-            body_lines.extend(["", "Warnings:"])
-            body_lines.extend(shown)
-            if len(errors) > len(shown):
-                body_lines.append(f"… {len(errors) - len(shown)} additional files could not be read.")
-
-        return "\n".join(header_lines) + "\n\n" + "\n".join(body_lines)
-
-    def read_file(self, abs_path: str, *, offset: int = 0, max_chars: int = 4000) -> str:
-        """Read file contents with optional offset and character limit."""
-        if not os.path.exists(abs_path):
-            return self.err(
-                "file_not_found",
-                f"File not found: {self.display_path(abs_path)}",
-                path=self.display_path(abs_path),
-            )
-        if os.path.isdir(abs_path):
-            return self.err(
-                "is_directory",
-                f"Path is a directory, not a file: {self.display_path(abs_path)}",
-                path=self.display_path(abs_path),
-                hint="Provide a file path.",
-            )
-        try:
-            with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
-                data = f.read()
-        except Exception as exc:
-            return self.err(
-                "read_failed",
-                "Failed to read file.",
-                path=self.display_path(abs_path),
-                data={"error": self.safe_err(exc)},
-            )
-        total = len(data)
-        start = max(0, min(offset, total))
-        if max_chars > 0:
-            end = min(total, start + max_chars)
-        else:
-            end = total
-        chunk = data[start:end]
-        next_cursor = end if end < total else None
-        header = (
-            f"Reading {self.display_path(abs_path)}\n"
-            f"Offset {start}, returned {len(chunk)} of {total}."
-            + (f"\nNext cursor: {next_cursor}" if next_cursor is not None else "")
-        )
-        sep = "\n\n---\n\n"
-        return header + sep + chunk
-
-    def info(self, abs_path: str) -> str:
-        """Get file/directory metadata as JSON."""
-        try:
-            st = os.stat(abs_path)
-        except Exception as exc:
-            return self.err(
-                "stat_failed",
-                "Failed to stat path.",
-                path=self.display_path(abs_path),
-                data={"error": self.safe_err(exc)},
-            )
-        info_dict = {
-            "path": self.display_path(abs_path),
-            "type": "directory" if stat.S_ISDIR(st.st_mode) else "file",
-            "size": st.st_size,
-            "modified": datetime.fromtimestamp(st.st_mtime).isoformat(sep=" ", timespec="seconds"),
-            "created": datetime.fromtimestamp(st.st_ctime).isoformat(sep=" ", timespec="seconds"),
-            "mode": oct(st.st_mode),
-            "root": "/",
-        }
-        return json.dumps(info_dict, indent=2)
-
-
-# ---------------------------------------------------------------------------
-# Default roots (can be overridden by environment variables)
-# ---------------------------------------------------------------------------
-
-def _get_filesystem_root() -> str:
-    """Get the default filesystem root directory."""
-    root = os.getenv("NYMBO_TOOLS_ROOT")
-    if root and root.strip():
-        return os.path.abspath(os.path.expanduser(root.strip()))
-    try:
-        here = os.path.abspath(__file__)
-        tools_dir = os.path.dirname(os.path.dirname(here))
-        return os.path.abspath(os.path.join(tools_dir, "Filesystem"))
-    except Exception:
-        return os.path.abspath(os.getcwd())
-
-
-def _get_obsidian_root() -> str:
-    """Get the default Obsidian vault root directory."""
-    env_root = os.getenv("OBSIDIAN_VAULT_ROOT")
-    if env_root and env_root.strip():
-        return os.path.abspath(os.path.expanduser(env_root.strip()))
-    try:
-        here = os.path.abspath(__file__)
-        tools_dir = os.path.dirname(os.path.dirname(here))
-        return os.path.abspath(os.path.join(tools_dir, "Obsidian"))
-    except Exception:
-        return os.path.abspath(os.getcwd())
-
-
-# Pre-configured sandbox instances
-ALLOW_ABS = bool(int(os.getenv("UNSAFE_ALLOW_ABS_PATHS", "0")))
-
-FILESYSTEM_ROOT = _get_filesystem_root()
-OBSIDIAN_ROOT = _get_obsidian_root()
-
-# Default sandbox for /Filesystem (used by most tools)
-filesystem_sandbox = SandboxedRoot(FILESYSTEM_ROOT, allow_abs=ALLOW_ABS)
-
-# Sandbox for /Obsidian vault
-obsidian_sandbox = SandboxedRoot(OBSIDIAN_ROOT, allow_abs=ALLOW_ABS)
-
-
-# Convenience exports (for backward compatibility)
-ROOT_DIR = FILESYSTEM_ROOT
-
-def _resolve_path(path: str) -> tuple[str, str]:
-    """Resolve path using the default filesystem sandbox."""
-    return filesystem_sandbox.resolve_path(path)
-
-def _display_path(abs_path: str) -> str:
-    """Display path using the default filesystem sandbox."""
-    return filesystem_sandbox.display_path(abs_path)
-
-def safe_open(file, *args, **kwargs):
-    """Open file using the default filesystem sandbox."""
-    return filesystem_sandbox.safe_open(file, *args, **kwargs)
-
-
-# ===========================================================================
-# Part 2: Sandboxed Python Execution
-# ===========================================================================
-
-
-def create_safe_builtins() -> dict:
-    """Create a builtins dict with sandboxed open()."""
-    if isinstance(__builtins__, dict):
-        safe_builtins = __builtins__.copy()
-    else:
-        safe_builtins = vars(__builtins__).copy()
-    safe_builtins["open"] = safe_open
-    return safe_builtins
-
-
-def sandboxed_exec(
-    code: str,
-    *,
-    extra_globals: dict[str, Any] | None = None,
-    ast_mode: bool = False,
-) -> str:
-    """
-    Execute Python code in a sandboxed environment.
-    
-    Args:
-        code: Python source code to execute
-        extra_globals: Additional globals to inject (e.g., tools)
-        ast_mode: If True, parse and print results of all expression statements
-                  (like Agent_Terminal). If False, simple exec (like Code_Interpreter).
-    
-    Returns:
-        Captured stdout output, or exception text on error.
-    """
-    if not code:
-        return "No code provided."
-    
-    old_stdout = sys.stdout
-    old_cwd = os.getcwd()
-    redirected_output = sys.stdout = StringIO()
-    
-    # Build execution environment
-    safe_builtins = create_safe_builtins()
-    env: dict[str, Any] = {
-        "open": safe_open,
-        "__builtins__": safe_builtins,
-        "print": print,
-    }
-    if extra_globals:
-        env.update(extra_globals)
-    
-    try:
-        os.chdir(ROOT_DIR)
-        
-        if ast_mode:
-            # Parse and evaluate each statement, printing expression results
-            tree = ast.parse(code)
-            for node in tree.body:
-                if isinstance(node, ast.Expr):
-                    # Standalone expression - evaluate and print result
-                    expr = compile(ast.Expression(node.value), filename="<string>", mode="eval")
-                    result_val = eval(expr, env)
-                    if result_val is not None:
-                        print(result_val)
-                else:
-                    # Statement - execute it
-                    mod = ast.Module(body=[node], type_ignores=[])
-                    exec(compile(mod, filename="<string>", mode="exec"), env)
-        else:
-            # Simple exec mode
-            exec(code, env)
-        
-        result = redirected_output.getvalue()
-    except Exception as exc:
-        result = str(exc)
-    finally:
-        sys.stdout = old_stdout
-        try:
-            os.chdir(old_cwd)
-        except Exception:
-            pass
-    
-    return result
-
-
-# ===========================================================================
-# Part 3: Hugging Face Inference Utilities
-# ===========================================================================
-
-
-def get_hf_token() -> str | None:
-    """Get the HF API token from environment variables.
-    
-    Checks HF_READ_TOKEN first, then falls back to HF_TOKEN.
-    """
-    return os.getenv("HF_READ_TOKEN") or os.getenv("HF_TOKEN")
-
-
-# Pre-instantiated token for modules that prefer this pattern
-HF_TOKEN = get_hf_token()
-
-# Standard provider list for image/video generation
-DEFAULT_PROVIDERS = ["auto", "replicate", "fal-ai"]
-
-# Provider list for text generation (Deep Research)
-TEXTGEN_PROVIDERS = ["cerebras", "auto"]
-
-
-T = TypeVar("T")
-
-
-def handle_hf_error(msg: str, model_id: str, *, context: str = "generation") -> None:
-    """
-    Raise appropriate gr.Error for common HF API error codes.
-    
-    Args:
-        msg: Error message string to analyze
-        model_id: The model ID being used (for error messages)
-        context: Description of operation for error messages
-    
-    Raises:
-        gr.Error: With user-friendly message based on error type
-    """
-    lowered = msg.lower()
-    
-    if "404" in msg:
-        raise gr.Error(f"Model not found or unavailable: {model_id}. Check the id and your HF token access.")
-    
-    if "503" in msg:
-        raise gr.Error("The model is warming up. Please try again shortly.")
-    
-    if "401" in msg or "403" in msg:
-        raise gr.Error("Please duplicate the space and provide a `HF_READ_TOKEN` to enable Image and Video Generation.")
-    
-    if any(pattern in lowered for pattern in ("api_key", "hf auth login", "unauthorized", "forbidden")):
-        raise gr.Error("Please duplicate the space and provide a `HF_READ_TOKEN` to enable Image and Video Generation.")
-    
-    # If none of the known patterns match, raise generic error
-    raise gr.Error(f"{context.capitalize()} failed: {msg}")
-
-
-def invoke_with_fallback(
-    fn: Callable[[str], T],
-    providers: list[str] | None = None,
-) -> T:
-    """
-    Try calling fn(provider) for each provider until one succeeds.
-    
-    Args:
-        fn: Function that takes a provider string and returns a result.
-            Should raise an exception on failure.
-        providers: List of provider strings to try. Defaults to DEFAULT_PROVIDERS.
-    
-    Returns:
-        The result from the first successful fn() call.
-    
-    Raises:
-        The last exception if all providers fail.
-    """
-    if providers is None:
-        providers = DEFAULT_PROVIDERS
-    
-    last_error: Exception | None = None
-    
-    for provider in providers:
-        try:
-            return fn(provider)
-        except Exception as exc:
-            last_error = exc
-            continue
-    
-    # All providers failed
-    if last_error:
-        raise last_error
-    raise RuntimeError("No providers available")
-
-
-# ===========================================================================
-# Public API
-# ===========================================================================
-
-__all__ = [
-    # Tree Utils
-    "_fmt_size",
-    "build_tree",
-    "render_tree",
-    "walk_and_build_tree",
-    "format_dir_listing",
-    # Filesystem
-    "SandboxedRoot",
-    "filesystem_sandbox",
-    "obsidian_sandbox",
-    "ROOT_DIR",
-    "FILESYSTEM_ROOT",
-    "OBSIDIAN_ROOT",
-    "ALLOW_ABS",
-    "_resolve_path",
-    "_display_path",
-    "safe_open",
-    # Execution
-    "sandboxed_exec",
-    "create_safe_builtins",
-    # HF Inference
-    "get_hf_token",
-    "HF_TOKEN",
-    "DEFAULT_PROVIDERS",
-    "TEXTGEN_PROVIDERS",
-    "handle_hf_error",
-    "invoke_with_fallback",
-]
+"""
+Core shared utilities for the Nymbo-Tools MCP server.
+
+Consolidates three key areas:
+1. Sandboxed filesystem operations (path resolution, reading, writing, safe_open)
+2. Sandboxed Python execution (code interpreter, agent terminal)
+3. Hugging Face inference utilities (token, providers, error handling)
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+import re
+import stat
+import sys
+from datetime import datetime
+from io import StringIO
+from typing import Any, Callable, Optional, TypeVar
+
+import gradio as gr
+
+
+# ===========================================================================
+# Part 0: Tree Rendering Utilities
+# ===========================================================================
+
+
+def _fmt_size(num_bytes: int) -> str:
+    """Format byte size as human-readable string."""
+    units = ["B", "KB", "MB", "GB"]
+    size = float(num_bytes)
+    for unit in units:
+        if size < 1024.0:
+            return f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} TB"
+
+
+def build_tree(entries: list[tuple[str, dict]]) -> dict:
+    """
+    Build a nested tree structure from flat path entries.
+    
+    Args:
+        entries: List of (path, metadata) tuples where path uses forward slashes.
+                 Paths ending with '/' are treated as directories.
+    
+    Returns:
+        Nested dict with "__files__" key for files at each level.
+    """
+    root: dict = {"__files__": []}
+    
+    for path, metadata in entries:
+        parts = path.rstrip("/").split("/")
+        is_dir = path.endswith("/")
+        
+        node = root
+        for i, part in enumerate(parts[:-1]):
+            if part not in node:
+                node[part] = {"__files__": []}
+            node = node[part]
+        
+        final = parts[-1]
+        if is_dir:
+            if final not in node:
+                node[final] = {"__files__": []}
+            if metadata:
+                node[final]["__meta__"] = metadata
+        else:
+            node["__files__"].append((final, metadata))
+    
+    return root
+
+
+def render_tree(
+    node: dict,
+    prefix: str = "",
+    format_entry: Optional[Callable[[str, dict, bool], str]] = None,
+) -> list[str]:
+    """
+    Render a tree with line connectors.
+    
+    Args:
+        node: Nested dict from build_tree()
+        prefix: Current line prefix for indentation
+        format_entry: Optional callback to format each entry.
+    
+    Returns:
+        List of formatted lines.
+    """
+    result = []
+    
+    def default_format(name: str, meta: dict, is_dir: bool) -> str:
+        if is_dir:
+            return f"{name}/"
+        size = meta.get("size")
+        if size is not None:
+            return f"{name}  ({_fmt_size(size)})"
+        return name
+    
+    fmt = format_entry or default_format
+    
+    entries = []
+    subdirs = sorted(k for k in node.keys() if k not in ("__files__", "__meta__"))
+    files_here = sorted(node.get("__files__", []), key=lambda x: x[0])
+    
+    for dirname in subdirs:
+        dir_meta = node[dirname].get("__meta__", {})
+        entries.append(("dir", dirname, node[dirname], dir_meta))
+    for fname, fmeta in files_here:
+        entries.append(("file", fname, None, fmeta))
+    
+    for i, entry in enumerate(entries):
+        is_last = (i == len(entries) - 1)
+        connector = "└── " if is_last else "├── "
+        child_prefix = prefix + ("    " if is_last else "│   ")
+        
+        etype, name, subtree, meta = entry
+        
+        if etype == "dir":
+            result.append(f"{prefix}{connector}{fmt(name, meta, True)}")
+            result.extend(render_tree(subtree, child_prefix, format_entry))
+        else:
+            result.append(f"{prefix}{connector}{fmt(name, meta, False)}")
+    
+    return result
+
+
+def walk_and_build_tree(
+    abs_path: str,
+    *,
+    show_hidden: bool = False,
+    recursive: bool = False,
+    max_entries: int = 100,
+) -> tuple[dict, int, bool]:
+    """
+    Walk a directory and build a tree structure.
+    
+    Returns:
+        (tree, total_entries, truncated)
+    """
+    entries: list[tuple[str, dict]] = []
+    total = 0
+    truncated = False
+    
+    for root, dirs, files in os.walk(abs_path):
+        if not show_hidden:
+            dirs[:] = [d for d in dirs if not d.startswith('.')]
+            files = [f for f in files if not f.startswith('.')]
+        
+        dirs.sort()
+        files.sort()
+        
+        try:
+            rel_root = os.path.relpath(root, abs_path)
+        except Exception:
+            rel_root = ""
+        prefix = "" if rel_root == "." else rel_root.replace("\\", "/") + "/"
+        
+        for d in dirs:
+            p = os.path.join(root, d)
+            try:
+                mtime = datetime.fromtimestamp(os.path.getmtime(p)).strftime("%Y-%m-%d %H:%M")
+            except Exception:
+                mtime = "?"
+            entries.append((f"{prefix}{d}/", {"mtime": mtime}))
+            total += 1
+            if total >= max_entries:
+                truncated = True
+                break
+        
+        if truncated:
+            break
+        
+        for f in files:
+            p = os.path.join(root, f)
+            try:
+                size = os.path.getsize(p)
+                mtime = datetime.fromtimestamp(os.path.getmtime(p)).strftime("%Y-%m-%d %H:%M")
+            except Exception:
+                size, mtime = 0, "?"
+            entries.append((f"{prefix}{f}", {"size": size, "mtime": mtime}))
+            total += 1
+            if total >= max_entries:
+                truncated = True
+                break
+        
+        if truncated:
+            break
+        
+        if not recursive:
+            break
+    
+    return build_tree(entries), total, truncated
+
+
+def format_dir_listing(
+    abs_path: str,
+    display_path: str,
+    *,
+    show_hidden: bool = False,
+    recursive: bool = False,
+    max_entries: int = 100,
+    fmt_size_fn: Optional[Callable[[int], str]] = None,
+) -> str:
+    """Format a directory listing as a visual tree."""
+    fmt_size = fmt_size_fn or _fmt_size
+    
+    tree, total, truncated = walk_and_build_tree(
+        abs_path,
+        show_hidden=show_hidden,
+        recursive=recursive,
+        max_entries=max_entries,
+    )
+    
+    def format_entry(name: str, meta: dict, is_dir: bool) -> str:
+        mtime = meta.get("mtime", "")
+        if is_dir:
+            return f"{name}/  ({mtime})"
+        size = meta.get("size", 0)
+        return f"{name}  ({fmt_size(size)}, {mtime})"
+    
+    tree_lines = render_tree(tree, "    ", format_entry)
+    
+    header = f"Listing of {display_path}\nRoot: /\nEntries: {total}"
+    if truncated:
+        header += f"\n… Truncated at {max_entries} entries."
+    
+    lines = [header, "", "└── /"]
+    lines.extend(tree_lines)
+    
+    return "\n".join(lines).strip()
+
+
+# ===========================================================================
+# Part 1: Sandboxed Filesystem Operations
+# ===========================================================================
+
+
+class SandboxedRoot:
+    """
+    A configurable sandboxed root directory with path resolution and safety checks.
+    
+    Args:
+        root_dir: Absolute path to the sandbox root.
+        allow_abs: If True, allow absolute paths outside the sandbox.
+    """
+    
+    def __init__(self, root_dir: str, allow_abs: bool = False):
+        self.root_dir = os.path.abspath(root_dir)
+        self.allow_abs = allow_abs
+        # Ensure root exists
+        try:
+            os.makedirs(self.root_dir, exist_ok=True)
+        except Exception:
+            pass
+    
+    def safe_err(self, exc: Exception | str) -> str:
+        """Return an error string with any absolute root replaced by '/' and slashes normalized."""
+        s = str(exc)
+        s_norm = s.replace("\\", "/")
+        root_fwd = self.root_dir.replace("\\", "/")
+        root_variants = {self.root_dir, root_fwd, re.sub(r"/+", "/", root_fwd)}
+        for variant in root_variants:
+            if variant:
+                s_norm = s_norm.replace(variant, "/")
+        s_norm = re.sub(r"/+", "/", s_norm)
+        return s_norm
+
+    def err(
+        self,
+        code: str,
+        message: str,
+        *,
+        path: Optional[str] = None,
+        hint: Optional[str] = None,
+        data: Optional[dict] = None,
+    ) -> str:
+        """Return a structured error JSON string."""
+        payload = {
+            "status": "error",
+            "code": code,
+            "message": message,
+            "root": "/",
+        }
+        if path is not None and path != "":
+            payload["path"] = path
+        if hint:
+            payload["hint"] = hint
+        if data:
+            payload["data"] = data
+        return json.dumps(payload, ensure_ascii=False)
+
+    def display_path(self, abs_path: str) -> str:
+        """Return a user-friendly path relative to root using forward slashes."""
+        try:
+            norm_root = os.path.normpath(self.root_dir)
+            norm_abs = os.path.normpath(abs_path)
+            common = os.path.commonpath([norm_root, norm_abs])
+            if os.path.normcase(common) == os.path.normcase(norm_root):
+                rel = os.path.relpath(norm_abs, norm_root)
+                if rel == ".":
+                    return "/"
+                return "/" + rel.replace("\\", "/")
+        except Exception:
+            pass
+        return abs_path.replace("\\", "/")
+
+    def resolve_path(self, path: str) -> tuple[str, str]:
+        """
+        Resolve a user-provided path to an absolute, normalized path constrained to root.
+        Returns (abs_path, error_message). error_message is empty when ok.
+        """
+        try:
+            user_input = (path or "/").strip() or "/"
+            if user_input.startswith("/"):
+                rel_part = user_input.lstrip("/") or "."
+                raw = os.path.expanduser(rel_part)
+                treat_as_relative = True
+            else:
+                raw = os.path.expanduser(user_input)
+                treat_as_relative = False
+
+            if not treat_as_relative and os.path.isabs(raw):
+                if not self.allow_abs:
+                    return "", self.err(
+                        "absolute_path_disabled",
+                        "Absolute paths are disabled in safe mode.",
+                        path=raw.replace("\\", "/"),
+                        hint="Use a path relative to / (e.g., /notes/todo.txt).",
+                    )
+                abs_path = os.path.abspath(raw)
+            else:
+                abs_path = os.path.abspath(os.path.join(self.root_dir, raw))
+            
+            # Constrain to root when not allowing absolute paths
+            if not self.allow_abs:
+                try:
+                    common = os.path.commonpath(
+                        [os.path.normpath(self.root_dir), os.path.normpath(abs_path)]
+                    )
+                    if common != os.path.normpath(self.root_dir):
+                        return "", self.err(
+                            "path_outside_root",
+                            "Path is outside the sandbox root.",
+                            path=abs_path,
+                        )
+                except Exception:
+                    return "", self.err(
+                        "path_outside_root",
+                        "Path is outside the sandbox root.",
+                        path=abs_path,
+                    )
+
+            return abs_path, ""
+        except Exception as exc:
+            return "", self.err(
+                "resolve_path_failed",
+                "Failed to resolve path.",
+                path=(path or ""),
+                data={"error": self.safe_err(exc)},
+            )
+
+    def safe_open(self, file, *args, **kwargs):
+        """A drop-in replacement for open() that enforces sandbox constraints."""
+        if isinstance(file, int):
+            return open(file, *args, **kwargs)
+        
+        path_str = os.fspath(file)
+        abs_path, err = self.resolve_path(path_str)
+        if err:
+            try:
+                msg = json.loads(err)["message"]
+            except Exception:
+                msg = err
+            raise PermissionError(f"Sandboxed open() failed: {msg}")
+        
+        return open(abs_path, *args, **kwargs)
+
+    def list_dir(
+        self,
+        abs_path: str,
+        *,
+        show_hidden: bool = False,
+        recursive: bool = False,
+        max_entries: int = 100,
+    ) -> str:
+        """List directory contents as a visual tree."""
+        return format_dir_listing(
+            abs_path,
+            self.display_path(abs_path),
+            show_hidden=show_hidden,
+            recursive=recursive,
+            max_entries=max_entries,
+            fmt_size_fn=_fmt_size,
+        )
+
+    def search_text(
+        self,
+        abs_path: str,
+        query: str,
+        *,
+        recursive: bool = False,
+        show_hidden: bool = False,
+        max_results: int = 20,
+        case_sensitive: bool = False,
+        start_index: int = 0,
+    ) -> str:
+        """Search for text within files."""
+        if not os.path.exists(abs_path):
+            return self.err(
+                "path_not_found",
+                f"Path not found: {self.display_path(abs_path)}",
+                path=self.display_path(abs_path),
+            )
+
+        query = query or ""
+        normalized_query = query if case_sensitive else query.lower()
+        if normalized_query == "":
+            return self.err(
+                "missing_search_query",
+                "Search query is required for the search action.",
+                hint="Provide text in the Content field to search for.",
+            )
+
+        max_results = max(1, int(max_results) if max_results is not None else 20)
+        start_index = max(0, int(start_index) if start_index is not None else 0)
+        matches: list[tuple[str, int, str]] = []
+        errors: list[str] = []
+        files_scanned = 0
+        truncated = False
+        total_matches = 0
+
+        def _should_skip(name: str) -> bool:
+            return not show_hidden and name.startswith(".")
+
+        def _handle_match(file_path: str, line_no: int, line_text: str) -> bool:
+            nonlocal truncated, total_matches
+            total_matches += 1
+            if total_matches <= start_index:
+                return False
+            if len(matches) < max_results:
+                snippet = line_text.strip()
+                if len(snippet) > 200:
+                    snippet = snippet[:197] + "…"
+                matches.append((self.display_path(file_path), line_no, snippet))
+                return False
+            truncated = True
+            return True
+
+        def _search_file(file_path: str) -> bool:
+            nonlocal files_scanned
+            files_scanned += 1
+            try:
+                with open(file_path, "r", encoding="utf-8", errors="replace") as handle:
+                    for line_no, line in enumerate(handle, start=1):
+                        haystack = line if case_sensitive else line.lower()
+                        if normalized_query in haystack:
+                            if _handle_match(file_path, line_no, line):
+                                return True
+            except Exception as exc:
+                errors.append(f"{self.display_path(file_path)} ({self.safe_err(exc)})")
+            return truncated
+
+        if os.path.isfile(abs_path):
+            _search_file(abs_path)
+        else:
+            for root, dirs, files in os.walk(abs_path):
+                dirs[:] = [d for d in dirs if not _should_skip(d)]
+                visible_files = [f for f in files if show_hidden or not f.startswith(".")]
+                for name in visible_files:
+                    file_path = os.path.join(root, name)
+                    if _search_file(file_path):
+                        break
+                if truncated:
+                    break
+                if not recursive:
+                    break
+
+        header_lines = [
+            f"Search results for {query!r}",
+            f"Scope: {self.display_path(abs_path)}",
+            f"Recursive: {'yes' if recursive else 'no'}, Hidden: {'yes' if show_hidden else 'no'}, Case-sensitive: {'yes' if case_sensitive else 'no'}",
+            f"Start offset: {start_index}",
+            f"Matches returned: {len(matches)}" + (" (truncated)" if truncated else ""),
+            f"Files scanned: {files_scanned}",
+        ]
+
+        next_cursor = start_index + len(matches) if truncated else None
+
+        if truncated:
+            header_lines.append(f"Matches encountered before truncation: {total_matches}")
+            header_lines.append(f"Truncated: yes — re-run with offset={next_cursor} to continue.")
+            header_lines.append(f"Next cursor: {next_cursor}")
+        else:
+            header_lines.append(f"Total matches found: {total_matches}")
+            header_lines.append("Truncated: no — end of results.")
+            header_lines.append("Next cursor: None")
+
+        if not matches:
+            if total_matches > 0 and start_index >= total_matches:
+                hint_limit = max(total_matches - 1, 0)
+                body_lines = [
+                    f"No matches found at or after offset {start_index}. Total matches available: {total_matches}.",
+                    (f"Try a smaller offset (≤ {hint_limit})." if hint_limit >= 0 else ""),
+                ]
+                body_lines = [line for line in body_lines if line]
+            else:
+                body_lines = [
+                    "No matches found.",
+                    (f"Total matches encountered: {total_matches}." if total_matches else ""),
+                ]
+                body_lines = [line for line in body_lines if line]
+        else:
+            body_lines = [
+                f"{idx}. {path}:{line_no}: {text}"
+                for idx, (path, line_no, text) in enumerate(matches, start=1)
+            ]
+
+        if errors:
+            shown = errors[:5]
+            body_lines.extend(["", "Warnings:"])
+            body_lines.extend(shown)
+            if len(errors) > len(shown):
+                body_lines.append(f"… {len(errors) - len(shown)} additional files could not be read.")
+
+        return "\n".join(header_lines) + "\n\n" + "\n".join(body_lines)
+
+    def read_file(self, abs_path: str, *, offset: int = 0, max_chars: int = 4000) -> str:
+        """Read file contents with optional offset and character limit."""
+        if not os.path.exists(abs_path):
+            return self.err(
+                "file_not_found",
+                f"File not found: {self.display_path(abs_path)}",
+                path=self.display_path(abs_path),
+            )
+        if os.path.isdir(abs_path):
+            return self.err(
+                "is_directory",
+                f"Path is a directory, not a file: {self.display_path(abs_path)}",
+                path=self.display_path(abs_path),
+                hint="Provide a file path.",
+            )
+        try:
+            with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
+                data = f.read()
+        except Exception as exc:
+            return self.err(
+                "read_failed",
+                "Failed to read file.",
+                path=self.display_path(abs_path),
+                data={"error": self.safe_err(exc)},
+            )
+        total = len(data)
+        start = max(0, min(offset, total))
+        if max_chars > 0:
+            end = min(total, start + max_chars)
+        else:
+            end = total
+        chunk = data[start:end]
+        next_cursor = end if end < total else None
+        header = (
+            f"Reading {self.display_path(abs_path)}\n"
+            f"Offset {start}, returned {len(chunk)} of {total}."
+            + (f"\nNext cursor: {next_cursor}" if next_cursor is not None else "")
+        )
+        sep = "\n\n---\n\n"
+        return header + sep + chunk
+
+    def info(self, abs_path: str) -> str:
+        """Get file/directory metadata as JSON."""
+        try:
+            st = os.stat(abs_path)
+        except Exception as exc:
+            return self.err(
+                "stat_failed",
+                "Failed to stat path.",
+                path=self.display_path(abs_path),
+                data={"error": self.safe_err(exc)},
+            )
+        info_dict = {
+            "path": self.display_path(abs_path),
+            "type": "directory" if stat.S_ISDIR(st.st_mode) else "file",
+            "size": st.st_size,
+            "modified": datetime.fromtimestamp(st.st_mtime).isoformat(sep=" ", timespec="seconds"),
+            "created": datetime.fromtimestamp(st.st_ctime).isoformat(sep=" ", timespec="seconds"),
+            "mode": oct(st.st_mode),
+            "root": "/",
+        }
+        return json.dumps(info_dict, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Default roots (can be overridden by environment variables)
+# ---------------------------------------------------------------------------
+
+def _get_filesystem_root() -> str:
+    """Get the default filesystem root directory."""
+    root = os.getenv("NYMBO_TOOLS_ROOT")
+    if root and root.strip():
+        return os.path.abspath(os.path.expanduser(root.strip()))
+    try:
+        here = os.path.abspath(__file__)
+        tools_dir = os.path.dirname(os.path.dirname(here))
+        return os.path.abspath(os.path.join(tools_dir, "Filesystem"))
+    except Exception:
+        return os.path.abspath(os.getcwd())
+
+
+def _get_obsidian_root() -> str:
+    """Get the default Obsidian vault root directory."""
+    env_root = os.getenv("OBSIDIAN_VAULT_ROOT")
+    if env_root and env_root.strip():
+        return os.path.abspath(os.path.expanduser(env_root.strip()))
+    try:
+        here = os.path.abspath(__file__)
+        tools_dir = os.path.dirname(os.path.dirname(here))
+        return os.path.abspath(os.path.join(tools_dir, "Obsidian"))
+    except Exception:
+        return os.path.abspath(os.getcwd())
+
+
+# Pre-configured sandbox instances
+ALLOW_ABS = bool(int(os.getenv("UNSAFE_ALLOW_ABS_PATHS", "0")))
+
+FILESYSTEM_ROOT = _get_filesystem_root()
+OBSIDIAN_ROOT = _get_obsidian_root()
+
+# Default sandbox for /Filesystem (used by most tools)
+filesystem_sandbox = SandboxedRoot(FILESYSTEM_ROOT, allow_abs=ALLOW_ABS)
+
+# Sandbox for /Obsidian vault
+obsidian_sandbox = SandboxedRoot(OBSIDIAN_ROOT, allow_abs=ALLOW_ABS)
+
+
+# Convenience exports (for backward compatibility)
+ROOT_DIR = FILESYSTEM_ROOT
+
+def _resolve_path(path: str) -> tuple[str, str]:
+    """Resolve path using the default filesystem sandbox."""
+    return filesystem_sandbox.resolve_path(path)
+
+def _display_path(abs_path: str) -> str:
+    """Display path using the default filesystem sandbox."""
+    return filesystem_sandbox.display_path(abs_path)
+
+def safe_open(file, *args, **kwargs):
+    """Open file using the default filesystem sandbox."""
+    return filesystem_sandbox.safe_open(file, *args, **kwargs)
+
+
+# ===========================================================================
+# Part 2: Sandboxed Python Execution
+# ===========================================================================
+
+
+def create_safe_builtins() -> dict:
+    """Create a builtins dict with sandboxed open()."""
+    if isinstance(__builtins__, dict):
+        safe_builtins = __builtins__.copy()
+    else:
+        safe_builtins = vars(__builtins__).copy()
+    safe_builtins["open"] = safe_open
+    return safe_builtins
+
+
+def sandboxed_exec(
+    code: str,
+    *,
+    extra_globals: dict[str, Any] | None = None,
+    ast_mode: bool = False,
+) -> str:
+    """
+    Execute Python code in a sandboxed environment.
+    
+    Args:
+        code: Python source code to execute
+        extra_globals: Additional globals to inject (e.g., tools)
+        ast_mode: If True, parse and print results of all expression statements
+                  (like Agent_Terminal). If False, simple exec (like Code_Interpreter).
+    
+    Returns:
+        Captured stdout output, or exception text on error.
+    """
+    if not code:
+        return "No code provided."
+    
+    old_stdout = sys.stdout
+    old_cwd = os.getcwd()
+    redirected_output = sys.stdout = StringIO()
+    
+    # Build execution environment
+    safe_builtins = create_safe_builtins()
+    env: dict[str, Any] = {
+        "open": safe_open,
+        "__builtins__": safe_builtins,
+        "print": print,
+    }
+    if extra_globals:
+        env.update(extra_globals)
+    
+    try:
+        os.chdir(ROOT_DIR)
+        
+        if ast_mode:
+            # Parse and evaluate each statement, printing expression results
+            tree = ast.parse(code)
+            for node in tree.body:
+                if isinstance(node, ast.Expr):
+                    # Standalone expression - evaluate and print result
+                    expr = compile(ast.Expression(node.value), filename="<string>", mode="eval")
+                    result_val = eval(expr, env)
+                    if result_val is not None:
+                        print(result_val)
+                else:
+                    # Statement - execute it
+                    mod = ast.Module(body=[node], type_ignores=[])
+                    exec(compile(mod, filename="<string>", mode="exec"), env)
+        else:
+            # Simple exec mode
+            exec(code, env)
+        
+        result = redirected_output.getvalue()
+    except Exception as exc:
+        result = str(exc)
+    finally:
+        sys.stdout = old_stdout
+        try:
+            os.chdir(old_cwd)
+        except Exception:
+            pass
+    
+    return result
+
+
+# ===========================================================================
+# Part 3: Hugging Face Inference Utilities
+# ===========================================================================
+
+
+def get_hf_token() -> str | None:
+    """Get the HF API token from environment variables.
+    
+    Checks HF_READ_TOKEN first, then falls back to HF_TOKEN.
+    """
+    return os.getenv("HF_READ_TOKEN") or os.getenv("HF_TOKEN")
+
+
+# Pre-instantiated token for modules that prefer this pattern
+HF_TOKEN = get_hf_token()
+
+# Standard provider list for image/video generation
+DEFAULT_PROVIDERS = ["auto", "replicate", "fal-ai"]
+
+# Provider list for text generation (Deep Research)
+TEXTGEN_PROVIDERS = ["cerebras", "auto"]
+
+
+T = TypeVar("T")
+
+
+def handle_hf_error(msg: str, model_id: str, *, context: str = "generation") -> None:
+    """
+    Raise appropriate gr.Error for common HF API error codes.
+    
+    Args:
+        msg: Error message string to analyze
+        model_id: The model ID being used (for error messages)
+        context: Description of operation for error messages
+    
+    Raises:
+        gr.Error: With user-friendly message based on error type
+    """
+    lowered = msg.lower()
+    
+    if "404" in msg:
+        raise gr.Error(f"Model not found or unavailable: {model_id}. Check the id and your HF token access.")
+    
+    if "503" in msg:
+        raise gr.Error("The model is warming up. Please try again shortly.")
+    
+    if "401" in msg or "403" in msg:
+        raise gr.Error("Please duplicate the space and provide a `HF_READ_TOKEN` to enable Image and Video Generation.")
+    
+    if any(pattern in lowered for pattern in ("api_key", "hf auth login", "unauthorized", "forbidden")):
+        raise gr.Error("Please duplicate the space and provide a `HF_READ_TOKEN` to enable Image and Video Generation.")
+    
+    # If none of the known patterns match, raise generic error
+    raise gr.Error(f"{context.capitalize()} failed: {msg}")
+
+
+def invoke_with_fallback(
+    fn: Callable[[str], T],
+    providers: list[str] | None = None,
+) -> T:
+    """
+    Try calling fn(provider) for each provider until one succeeds.
+    
+    Args:
+        fn: Function that takes a provider string and returns a result.
+            Should raise an exception on failure.
+        providers: List of provider strings to try. Defaults to DEFAULT_PROVIDERS.
+    
+    Returns:
+        The result from the first successful fn() call.
+    
+    Raises:
+        The last exception if all providers fail.
+    """
+    if providers is None:
+        providers = DEFAULT_PROVIDERS
+    
+    last_error: Exception | None = None
+    
+    for provider in providers:
+        try:
+            return fn(provider)
+        except Exception as exc:
+            last_error = exc
+            continue
+    
+    # All providers failed
+    if last_error:
+        raise last_error
+    raise RuntimeError("No providers available")
+
+
+# ===========================================================================
+# Public API
+# ===========================================================================
+
+__all__ = [
+    # Tree Utils
+    "_fmt_size",
+    "build_tree",
+    "render_tree",
+    "walk_and_build_tree",
+    "format_dir_listing",
+    # Filesystem
+    "SandboxedRoot",
+    "filesystem_sandbox",
+    "obsidian_sandbox",
+    "ROOT_DIR",
+    "FILESYSTEM_ROOT",
+    "OBSIDIAN_ROOT",
+    "ALLOW_ABS",
+    "_resolve_path",
+    "_display_path",
+    "safe_open",
+    # Execution
+    "sandboxed_exec",
+    "create_safe_builtins",
+    # HF Inference
+    "get_hf_token",
+    "HF_TOKEN",
+    "DEFAULT_PROVIDERS",
+    "TEXTGEN_PROVIDERS",
+    "handle_hf_error",
+    "invoke_with_fallback",
+]

Modules/_docstrings.py

@@ -1,149 +1,149 @@
-from __future__ import annotations
-
-import inspect
-import re
-from typing import Any, Annotated, get_args, get_origin, get_type_hints
-
-
-def _typename(tp: Any) -> str:
-    """Return a readable type name from a type or annotation."""
-    try:
-        if hasattr(tp, "__name__"):
-            return tp.__name__  # e.g. int, str
-        if getattr(tp, "__module__", None) and getattr(tp, "__qualname__", None):
-            return f"{tp.__module__}.{tp.__qualname__}"
-        return str(tp).replace("typing.", "")
-    except Exception:
-        return str(tp)
-
-
-def _parse_string_annotation(annot_str: str) -> tuple[str | None, str | None]:
-    """
-    Parse a string annotation like "Annotated[Optional[str], 'description']"
-    and extract the base type name and the description metadata.
-    
-    Returns (base_type_name, description) or (None, None) if parsing fails.
-    """
-    if not isinstance(annot_str, str):
-        return None, None
-    
-    # Match Annotated[..., 'description'] or Annotated[..., "description"]
-    # Pattern: Annotated[<base_type>, '<description>'] or with double quotes
-    match = re.match(
-        r"^Annotated\[(.+?),\s*['\"](.+?)['\"]\s*\]$",
-        annot_str.strip(),
-        re.DOTALL,
-    )
-    if match:
-        base_type_str = match.group(1).strip()
-        description = match.group(2)
-        # Simplify Optional[X] -> just the base type for display
-        opt_match = re.match(r"^Optional\[(.+)\]$", base_type_str)
-        if opt_match:
-            base_type_str = opt_match.group(1).strip()
-        return base_type_str, description
-    
-    return None, None
-
-
-def _extract_base_and_meta(annotation: Any) -> tuple[Any, str | None]:
-    """Given an annotation, return (base_type, first string metadata) if Annotated, else (annotation, None)."""
-    try:
-        # Handle string annotations from PEP 563 (__future__.annotations)
-        if isinstance(annotation, str):
-            base_str, meta = _parse_string_annotation(annotation)
-            if meta:
-                return base_str or annotation, meta
-            return annotation, None
-        
-        if get_origin(annotation) is Annotated:
-            args = get_args(annotation)
-            base = args[0] if args else annotation
-            # Grab the first string metadata if present
-            for meta in args[1:]:
-                if isinstance(meta, str):
-                    return base, meta
-            return base, None
-        return annotation, None
-    except Exception:
-        return annotation, None
-
-
-def autodoc(summary: str | None = None, returns: str | None = None, *, force: bool = False):
-    """
-    Decorator that auto-generates a concise Google-style docstring from a function's
-    type hints and Annotated metadata. Useful for Gradio MCP where docstrings are
-    used for tool descriptions and parameter docs.
-
-    Args:
-        summary: Optional one-line summary for the function. If not provided,
-            will generate a simple sentence from the function name.
-        returns: Optional return value description. If not provided, only the
-            return type will be listed (if available).
-        force: When True, overwrite an existing docstring. Default False.
-
-    Returns:
-        The original function with its __doc__ populated (unless skipped).
-    """
-
-    def decorator(func):
-        # Skip if docstring already present and not forcing
-        if not force and func.__doc__ and func.__doc__.strip():
-            return func
-
-        try:
-            # include_extras=True to retain Annotated metadata
-            hints = get_type_hints(func, include_extras=True, globalns=getattr(func, "__globals__", None))
-        except Exception:
-            hints = {}
-
-        sig = inspect.signature(func)
-
-        lines: list[str] = []
-        # Summary line
-        if summary and summary.strip():
-            lines.append(summary.strip())
-        else:
-            pretty = func.__name__.replace("_", " ").strip().capitalize()
-            if not pretty.endswith("."):
-                pretty += "."
-            lines.append(pretty)
-
-        # Args section
-        if sig.parameters:
-            lines.append("")
-            lines.append("Args:")
-            for name, param in sig.parameters.items():
-                if name == "self":
-                    continue
-                annot = hints.get(name, param.annotation)
-                base, meta = _extract_base_and_meta(annot)
-                tname = _typename(base) if base is not inspect._empty else None
-                desc = meta or ""
-                if tname and tname != str(inspect._empty):
-                    lines.append(f"    {name} ({tname}): {desc}".rstrip())
-                else:
-                    lines.append(f"    {name}: {desc}".rstrip())
-
-        # Returns section
-        ret_hint = hints.get("return", sig.return_annotation)
-        if returns or (ret_hint and ret_hint is not inspect.Signature.empty):
-            lines.append("")
-            lines.append("Returns:")
-            if returns:
-                lines.append(f"    {returns}")
-            else:
-                base, meta = _extract_base_and_meta(ret_hint)
-                rtype = _typename(base)
-                if meta:
-                    lines.append(f"    {rtype}: {meta}")
-                else:
-                    lines.append(f"    {rtype}")
-
-        func.__doc__ = "\n".join(lines).strip() + "\n"
-        return func
-
-    return decorator
-
-
-__all__ = ["autodoc"]
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any, Annotated, get_args, get_origin, get_type_hints
+
+
+def _typename(tp: Any) -> str:
+    """Return a readable type name from a type or annotation."""
+    try:
+        if hasattr(tp, "__name__"):
+            return tp.__name__  # e.g. int, str
+        if getattr(tp, "__module__", None) and getattr(tp, "__qualname__", None):
+            return f"{tp.__module__}.{tp.__qualname__}"
+        return str(tp).replace("typing.", "")
+    except Exception:
+        return str(tp)
+
+
+def _parse_string_annotation(annot_str: str) -> tuple[str | None, str | None]:
+    """
+    Parse a string annotation like "Annotated[Optional[str], 'description']"
+    and extract the base type name and the description metadata.
+    
+    Returns (base_type_name, description) or (None, None) if parsing fails.
+    """
+    if not isinstance(annot_str, str):
+        return None, None
+    
+    # Match Annotated[..., 'description'] or Annotated[..., "description"]
+    # Pattern: Annotated[<base_type>, '<description>'] or with double quotes
+    match = re.match(
+        r"^Annotated\[(.+?),\s*['\"](.+?)['\"]\s*\]$",
+        annot_str.strip(),
+        re.DOTALL,
+    )
+    if match:
+        base_type_str = match.group(1).strip()
+        description = match.group(2)
+        # Simplify Optional[X] -> just the base type for display
+        opt_match = re.match(r"^Optional\[(.+)\]$", base_type_str)
+        if opt_match:
+            base_type_str = opt_match.group(1).strip()
+        return base_type_str, description
+    
+    return None, None
+
+
+def _extract_base_and_meta(annotation: Any) -> tuple[Any, str | None]:
+    """Given an annotation, return (base_type, first string metadata) if Annotated, else (annotation, None)."""
+    try:
+        # Handle string annotations from PEP 563 (__future__.annotations)
+        if isinstance(annotation, str):
+            base_str, meta = _parse_string_annotation(annotation)
+            if meta:
+                return base_str or annotation, meta
+            return annotation, None
+        
+        if get_origin(annotation) is Annotated:
+            args = get_args(annotation)
+            base = args[0] if args else annotation
+            # Grab the first string metadata if present
+            for meta in args[1:]:
+                if isinstance(meta, str):
+                    return base, meta
+            return base, None
+        return annotation, None
+    except Exception:
+        return annotation, None
+
+
+def autodoc(summary: str | None = None, returns: str | None = None, *, force: bool = False):
+    """
+    Decorator that auto-generates a concise Google-style docstring from a function's
+    type hints and Annotated metadata. Useful for Gradio MCP where docstrings are
+    used for tool descriptions and parameter docs.
+
+    Args:
+        summary: Optional one-line summary for the function. If not provided,
+            will generate a simple sentence from the function name.
+        returns: Optional return value description. If not provided, only the
+            return type will be listed (if available).
+        force: When True, overwrite an existing docstring. Default False.
+
+    Returns:
+        The original function with its __doc__ populated (unless skipped).
+    """
+
+    def decorator(func):
+        # Skip if docstring already present and not forcing
+        if not force and func.__doc__ and func.__doc__.strip():
+            return func
+
+        try:
+            # include_extras=True to retain Annotated metadata
+            hints = get_type_hints(func, include_extras=True, globalns=getattr(func, "__globals__", None))
+        except Exception:
+            hints = {}
+
+        sig = inspect.signature(func)
+
+        lines: list[str] = []
+        # Summary line
+        if summary and summary.strip():
+            lines.append(summary.strip())
+        else:
+            pretty = func.__name__.replace("_", " ").strip().capitalize()
+            if not pretty.endswith("."):
+                pretty += "."
+            lines.append(pretty)
+
+        # Args section
+        if sig.parameters:
+            lines.append("")
+            lines.append("Args:")
+            for name, param in sig.parameters.items():
+                if name == "self":
+                    continue
+                annot = hints.get(name, param.annotation)
+                base, meta = _extract_base_and_meta(annot)
+                tname = _typename(base) if base is not inspect._empty else None
+                desc = meta or ""
+                if tname and tname != str(inspect._empty):
+                    lines.append(f"    {name} ({tname}): {desc}".rstrip())
+                else:
+                    lines.append(f"    {name}: {desc}".rstrip())
+
+        # Returns section
+        ret_hint = hints.get("return", sig.return_annotation)
+        if returns or (ret_hint and ret_hint is not inspect.Signature.empty):
+            lines.append("")
+            lines.append("Returns:")
+            if returns:
+                lines.append(f"    {returns}")
+            else:
+                base, meta = _extract_base_and_meta(ret_hint)
+                rtype = _typename(base)
+                if meta:
+                    lines.append(f"    {rtype}: {meta}")
+                else:
+                    lines.append(f"    {rtype}")
+
+        func.__doc__ = "\n".join(lines).strip() + "\n"
+        return func
+
+    return decorator
+
+
+__all__ = ["autodoc"]

Modules/_pollinations_client.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import os
+from typing import Annotated, Any, Literal
+
+import httpx
+import gradio as gr
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+
+# ===========================================================================
+# Constants
+# ===========================================================================
+
+BASE_URL = "https://text.pollinations.ai"
+
+# Model mappings for different depth levels
+MODEL_MAPPING = {
+    "fast": "gemini-search",
+    "normal": "perplexity-fast",
+    "deep": "perplexity-reasoning",
+}
+
+# System prompts for different detail levels
+SYSTEM_PROMPTS = {
+    True: "Search the web and provide a comprehensive answer with sources. Include relevant details and cite your sources.",
+    False: "Search the web and provide a concise, accurate answer. Include source URLs.",
+}
+
+# Timeout settings (seconds)
+REQUEST_TIMEOUT = 30.0
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Search the web using AI-powered search models with source citations. "
+    "Supports different depth levels: fast (Gemini with Google Search), normal (Perplexity Sonar), "
+    "and deep (Perplexity Sonar Reasoning). Returns answers with source URLs."
+)
+
+
+# ===========================================================================
+# Core Client
+# ===========================================================================
+
+
+class PollinationsClient:
+    """
+    HTTP client for Pollinations AI web search API.
+
+    Provides web search functionality with different depth levels and citation support.
+    """
+
+    def __init__(
+        self,
+        base_url: str = BASE_URL,
+        timeout: float = REQUEST_TIMEOUT,
+        api_key: str | None = None,
+    ) -> None:
+        """
+        Initialize the Pollinations client.
+
+        Args:
+            base_url: Base URL for the Pollinations API (default: https://text.pollinations.ai)
+            timeout: Request timeout in seconds (default: 30)
+            api_key: Optional API key (reads from POLLINATIONS_API_KEY env var if not provided)
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.api_key = api_key or os.getenv("POLLINATIONS_API_KEY")
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get request headers including API key if available."""
+        headers = {
+            "Content-Type": "application/json",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _resolve_model(self, depth: str) -> str:
+        """
+        Resolve depth level to actual model name.
+
+        Args:
+            depth: Depth level ('fast', 'normal', or 'deep')
+
+        Returns:
+            The model identifier for the Pollinations API
+        """
+        return MODEL_MAPPING.get(depth, "perplexity-fast")
+
+    async def web_search(
+        self,
+        query: str,
+        depth: str = "normal",
+        detailed: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Perform web search using Pollinations AI.
+
+        Args:
+            query: The search query
+            depth: Search depth level ('fast', 'normal', or 'deep')
+            detailed: Whether to request a comprehensive answer
+
+        Returns:
+            Dictionary with keys:
+                - answer: The generated answer
+                - sources: List of source URLs (citations)
+                - model: The model used
+                - query: The original query
+
+        Raises:
+            httpx.HTTPError: For network/HTTP errors
+            ValueError: For invalid parameters
+        """
+        if not query or not query.strip():
+            raise ValueError("Query cannot be empty")
+
+        if depth not in MODEL_MAPPING:
+            raise ValueError(f"Invalid depth: {depth}. Must be one of {list(MODEL_MAPPING.keys())}")
+
+        model = self._resolve_model(depth)
+        system_prompt = SYSTEM_PROMPTS.get(detailed, SYSTEM_PROMPTS[False])
+
+        # Prepare OpenAI-compatible request
+        payload = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": query},
+            ],
+        }
+
+        url = f"{self.base_url}/v1/chat/completions"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            try:
+                response = await client.post(
+                    url,
+                    json=payload,
+                    headers=self._get_headers(),
+                )
+                response.raise_for_status()
+            except httpx.TimeoutException as exc:
+                raise httpx.HTTPError(f"Request timed out after {self.timeout}s") from exc
+            except httpx.HTTPStatusError as exc:
+                # Handle rate limiting specifically
+                if exc.response.status_code == 429:
+                    raise httpx.HTTPError("Rate limited. Please try again later.") from exc
+                raise
+
+        data = response.json()
+
+        # Extract answer and citations from response
+        answer = ""
+        sources = []
+
+        # OpenAI-compatible response format
+        if "choices" in data and data["choices"]:
+            answer = data["choices"][0].get("message", {}).get("content", "")
+
+        # Extract citations if present (Pollinations-specific extension)
+        if "citations" in data:
+            sources = data["citations"]
+
+        # Also check if citations are embedded in the message
+        if not sources and isinstance(answer, str):
+            # Try to extract URLs from the answer
+            import re
+            url_pattern = r'https?://[^\s<>"\'\)]+'
+            sources = list(dict.fromkeys(re.findall(url_pattern, answer)))  # Unique URLs
+
+        return {
+            "answer": answer,
+            "sources": sources,
+            "model": model,
+            "query": query,
+        }
+
+    def web_search_sync(
+        self,
+        query: str,
+        depth: str = "normal",
+        detailed: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Synchronous version of web_search.
+
+        Args:
+            query: The search query
+            depth: Search depth level ('fast', 'normal', or 'deep')
+            detailed: Whether to request a comprehensive answer
+
+        Returns:
+            Dictionary with answer, sources, model, and query
+        """
+        import asyncio
+
+        return asyncio.run(self.web_search(query, depth, detailed))
+
+
+# ===========================================================================
+# Gradio Tool Function
+# ===========================================================================
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Pollinations_Web_Search(
+    query: Annotated[str, "The search query string"],
+    depth: Annotated[
+        Literal["fast", "normal", "deep"],
+        "Search depth: 'fast' (Gemini with Google Search), 'normal' (Perplexity Sonar), or 'deep' (Perplexity Sonar Reasoning).",
+    ] = "normal",
+    detailed: Annotated[bool, "Request a comprehensive answer instead of concise summary"] = False,
+) -> str:
+    """
+    Search the web using Pollinations AI with source citations.
+
+    Uses AI-powered search models that provide direct answers with source citations.
+    Supports three depth levels for different search capabilities.
+    """
+    _log_call_start("Pollinations_Web_Search", query=query, depth=depth, detailed=detailed)
+
+    try:
+        client = PollinationsClient()
+        result = client.web_search_sync(query, depth, detailed)
+
+        # Format the result for display
+        lines = [
+            f"Query: {result['query']}",
+            f"Model: {result['model']}",
+            f"Depth: {depth}",
+            "",
+            "Answer:",
+            result["answer"] or "No answer generated.",
+        ]
+
+        if result["sources"]:
+            lines.append("")
+            lines.append("Sources:")
+            for i, source in enumerate(result["sources"], 1):
+                lines.append(f"  {i}. {source}")
+        else:
+            lines.append("")
+            lines.append("(No sources provided)")
+
+        formatted_result = "\n".join(lines)
+        _log_call_end("Pollinations_Web_Search", _truncate_for_log(formatted_result))
+        return formatted_result
+
+    except ValueError as exc:
+        error_msg = f"Invalid input: {exc}"
+        _log_call_end("Pollinations_Web_Search", error_msg)
+        return error_msg
+    except httpx.HTTPError as exc:
+        error_msg = f"Search failed: {exc}"
+        _log_call_end("Pollinations_Web_Search", error_msg)
+        return error_msg
+    except Exception as exc:
+        error_msg = f"Unexpected error: {exc}"
+        _log_call_end("Pollinations_Web_Search", error_msg)
+        return error_msg
+
+
+# ===========================================================================
+# Gradio Interface
+# ===========================================================================
+
+
+def build_interface() -> gr.Interface:
+    """Build the Gradio interface for Pollinations web search."""
+    return gr.Interface(
+        fn=Pollinations_Web_Search,
+        inputs=[
+            gr.Textbox(
+                label="Query",
+                placeholder="Enter your search query here...",
+                max_lines=2,
+                info="The search query",
+            ),
+            gr.Radio(
+                label="Search Depth",
+                choices=["fast", "normal", "deep"],
+                value="normal",
+                info="Search depth level: fast (Gemini), normal (Perplexity), deep (Reasoning)",
+            ),
+            gr.Checkbox(
+                label="Detailed Answer",
+                value=False,
+                info="Request a comprehensive answer instead of concise summary",
+            ),
+        ],
+        outputs=gr.Textbox(
+            label="Search Results",
+            interactive=False,
+            lines=15,
+            max_lines=20,
+        ),
+        title="Pollinations Web Search",
+        description=(
+            "<div style=\"text-align:center\">AI-powered web search with source citations. "
+            "Uses Google Search, Perplexity Sonar, and Perplexity Sonar Reasoning models "
+            "to provide direct answers with reliable source URLs.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Search",
+    )
+
+
+# ===========================================================================
+# Public API
+# ===========================================================================
+
+__all__ = [
+    "PollinationsClient",
+    "Pollinations_Web_Search",
+    "build_interface",
+]

Modules/_query_optimizer.py

@@ -0,0 +1,781 @@
+"""
+Query Optimizer Module with Self-Consistency Chain-of-Thought (SC-CoT).
+
+Optimizes search queries using AI-generated candidate scoring with a fallback chain:
+1. Mistral API (magistral-medium-2509) - Primary
+2. HuggingFace Inference (openai/gpt-oss-20b:cheapest) - Fallback
+3. Bypass (return raw query) - Final fallback
+
+Two optimization modes:
+- optimize_for_search_engine(): Boolean operators, site:, filetype:, exact phrases
+- optimize_for_ai_search(): Clear intent, context, specific questions
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Annotated, Any, Literal
+
+import gradio as gr
+from pydantic import BaseModel, Field
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+
+# ===========================================================================
+# Pydantic Schemas for Structured Output
+# ===========================================================================
+
+
+class OptimizedCandidate(BaseModel):
+    """A single optimized query candidate with reasoning."""
+
+    version: int = Field(description="Candidate version number (1-based)")
+    optimized_query: str = Field(description="The optimized query string")
+    reasoning: list[str] = Field(description="List of reasoning steps explaining optimizations")
+
+
+class GenerationOutput(BaseModel):
+    """Output from candidate generation phase."""
+
+    original_query: str = Field(description="The original user query")
+    candidates: list[OptimizedCandidate] = Field(description="List of generated candidates")
+
+
+class ScoringOutput(BaseModel):
+    """Output from candidate selection phase."""
+
+    selected_version: int = Field(description="Version number of the best candidate")
+
+
+# ===========================================================================
+# Core Query Optimizer Class
+# ===========================================================================
+
+
+class QueryOptimizer:
+    """
+    Self-Consistency Chain-of-Thought query optimizer.
+
+    Generates multiple optimized candidates and selects the best one through
+    self-consistency scoring. Implements a fallback chain for reliability.
+    """
+
+    # Few-shot examples for search engine optimization
+    _SEARCH_ENGINE_EXAMPLES = """
+Example 1:
+Input: python fastapi performance
+Candidates:
+1. ("python fastapi performance", "Direct query covers main concepts")
+2. ("fastapi performance optimization python", "Added 'optimization' for more specific results")
+3. ("site:stackoverflow.com fastapi performance python", "Targeted technical Q&A for performance issues")
+4. ("fastapi async performance benchmark", "Added 'async' and 'benchmark' for technical depth")
+5. "fastapi OR flask performance python", "Added comparison with Flask for broader context")
+
+Example 2:
+Input: climate change effects on agriculture
+Candidates:
+1. ("climate change effects on agriculture", "Clear and comprehensive query")
+2. ("site:nature.com OR site:science.org climate change agriculture", "Targeted reputable scientific sources")
+3. "\"climate change\" AND agriculture filetype:pdf", "Using exact phrase match and PDF filter for research papers")
+4. ("climate change impact crop yield 2023..2024", "Added temporal filter and specific terminology")
+5. ("agricultural adaptation climate change strategies", "Rephrased to focus on solutions")
+
+Example 3:
+Input: machine learning tutorial python
+Candidates:
+1. ("python machine learning tutorial", "Reordered for better SEO")
+2. ("site:youtube.com python machine learning tutorial", "Targeted video tutorials")
+3. ("python machine learning tutorial filetype:pdf", "Focus on PDF documentation")
+4. ("machine learning python sklearn tutorial", "Added popular library 'sklearn' for relevance")
+5. "\"machine learning\" AND python AND tutorial", "Using boolean operators for precision")
+
+Example 4:
+Input: react native vs flutter
+Candidates:
+1. ("react native vs flutter comparison", "Added 'comparison' for explicit intent")
+2. ("site:reddit.com \"react native\" flutter", "Targeted community discussions")
+3. "\"react native\" OR flutter mobile development", "Broader search for mobile frameworks")
+4. ("react native flutter performance benchmark", "Focus on technical comparison")
+5. ("flutter vs react native 2024", "Added year for current information")
+
+Example 5:
+Input: best restaurants in tokyo
+Candidates:
+1. ("best restaurants tokyo", "Simplified for broad search")
+2. ("site:michelin.com Tokyo restaurants", "Targeted Michelin guide sources")
+3. ("Tokyo restaurant guide 2024", "Added temporal context")
+4. "\"best restaurants\" AND tokyo AND review", "Boolean operators for precision")
+5. ("tokyo food guide michelin OR local", "Added 'local' for authentic recommendations")
+"""
+
+    # Few-shot examples for AI search optimization
+    _AI_SEARCH_EXAMPLES = """
+Example 1:
+Input: python fastapi performance
+Candidates:
+1. ("What are the performance characteristics of FastAPI in Python, and how does it compare to other web frameworks?", "Added comparison context and framework focus")
+2. ("Explain the key performance optimization techniques for FastAPI applications in Python.", "Focused on actionable optimization strategies")
+3. ("How does FastAPI's async/await model impact performance compared to synchronous frameworks?", "Targeted technical architectural question")
+4. ("What are the benchmarks and real-world performance metrics for FastAPI in production environments?", "Asked for empirical data")
+5. ("How can I identify and resolve performance bottlenecks in FastAPI applications?", "Problem-solving focused")
+
+Example 2:
+Input: climate change effects on agriculture
+Candidates:
+1. ("What are the primary impacts of climate change on global agricultural productivity and crop yields?", "Comprehensive question covering direct effects")
+2. ("How is climate change affecting different agricultural regions around the world?", "Geographic focus")
+3. ("What adaptation strategies are farmers using to cope with climate change impacts?", "Solution-oriented focus")
+4. ("What scientific evidence exists linking climate change to agricultural changes?", "Evidence-based inquiry")
+5. ("How will climate change affect food security and agricultural sustainability by 2050?", "Temporal and sustainability focus")
+
+Example 3:
+Input: react native vs flutter
+Candidates:
+1. ("What are the key differences between React Native and Flutter in terms of performance, development experience, and ecosystem?", "Comprehensive comparison framework")
+2. ("Which cross-platform mobile framework is better suited for startup applications: React Native or Flutter?", "Use-case specific question")
+3. ("How do React Native and Flutter compare in terms of learning curve, community support, and hiring availability?", "Practical development considerations")
+4. ("What are the long-term maintenance implications of choosing React Native vs Flutter?", "Strategic business question")
+5. ("Which framework provides better native performance and access to device features: React Native or Flutter?", "Technical performance focus")
+
+Example 4:
+Input: machine learning tutorial python
+Candidates:
+1. ("What is the best learning path for getting started with machine learning using Python?", "Learning path focused question")
+2. ("Can you recommend a comprehensive Python machine learning tutorial for beginners?", "Resource-seeking question")
+3. ("What are the essential Python libraries and tools for implementing machine learning algorithms?", "Tool ecosystem question")
+4. ("How can I build my first machine learning model in Python from scratch?", hands-on implementation focus")
+5. ("What are the common pitfalls and best practices for learning machine learning with Python?", "Learning guidance question")
+
+Example 5:
+Input: quantum computing explained
+Candidates:
+1. ("Can you explain quantum computing in simple terms for someone without a physics background?", "Accessible explanation request")
+2. ("What are the fundamental principles of quantum computing and how do they differ from classical computing?", "Conceptual comparison question")
+3. ("What are the practical applications of quantum computing and when might they become viable?", "Real-world impact question")
+4. ("How do qubits work and why do they enable quantum computational advantages?", "Technical explanation question")
+5. ("What are the current limitations and challenges in developing practical quantum computers?", "Critical analysis question")
+"""
+
+    _SELECTOR_PROMPT = """
+Given the original query and multiple optimized candidates, select the best one.
+
+Criteria for selection:
+- Relevance: Most accurately captures the user's intent
+- Precision: Will return the most relevant results
+- Completeness: Covers all important aspects of the query
+- Clarity: Easy to understand and well-structured
+
+Return only the version number of the best candidate (1-indexed).
+"""
+
+    def __init__(self) -> None:
+        """Initialize the query optimizer with API clients."""
+        self._mistral_api_key: str | None = os.getenv("MISTRAL_API_KEY")
+        self._hf_token: str | None = os.getenv("HF_TOKEN")
+        self._mistral_model: str = "magistral-medium-2509"
+        self._hf_model: str = "openai/gpt-oss-20b:cheapest"
+        self._hf_endpoint: str = "https://router.huggingface.co/v1"
+
+    def _mistral_generate(
+        self, prompt: str, response_format: dict[str, Any]
+    ) -> str:
+        """Generate structured output using Mistral API with response_format."""
+        if not self._mistral_api_key:
+            raise ValueError("MISTRAL_API_KEY not set")
+
+        import httpx
+
+        messages = [
+            {
+                "role": "user",
+                "content": prompt,
+            }
+        ]
+
+        payload = {
+            "model": self._mistral_model,
+            "messages": messages,
+            "response_format": response_format,
+            "max_tokens": 2000,
+            "temperature": 0.3,
+        }
+
+        headers = {
+            "Authorization": f"Bearer {self._mistral_api_key}",
+            "Content-Type": "application/json",
+        }
+
+        response = httpx.post(
+            "https://api.mistral.ai/v1/chat/completions",
+            json=payload,
+            headers=headers,
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        if "choices" not in result or not result["choices"]:
+            raise ValueError("Invalid Mistral API response: no choices")
+
+        return result["choices"][0]["message"]["content"]
+
+    def _hf_generate(self, prompt: str) -> str:
+        """Generate output using HuggingFace Inference API."""
+        if not self._hf_token:
+            raise ValueError("HF_TOKEN not set")
+
+        import httpx
+
+        payload = {
+            "model": self._hf_model,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": prompt,
+                }
+            ],
+            "max_tokens": 2000,
+            "temperature": 0.3,
+        }
+
+        headers = {
+            "Authorization": f"Bearer {self._hf_token}",
+            "Content-Type": "application/json",
+        }
+
+        response = httpx.post(
+            f"{self._hf_endpoint}/chat/completions",
+            json=payload,
+            headers=headers,
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        if "choices" not in result or not result["choices"]:
+            raise ValueError("Invalid HF API response: no choices")
+
+        return result["choices"][0]["message"]["content"]
+
+    def _extract_json_from_response(self, response: str) -> str:
+        """Extract JSON from a response that may have markdown formatting."""
+        # Try to find JSON between ```json and ``` or between ``` and ```
+        patterns = [
+            r"```json\s*([\s\S]*?)\s*```",
+            r"```\s*([\s\S]*?)\s*```",
+            r"(\{[\s\S]*\})",
+        ]
+
+        for pattern in patterns:
+            match = re.search(pattern, response.strip())
+            if match:
+                return match.group(1).strip()
+
+        return response.strip()
+
+    def _optimize_search_engine_mistral(self, query: str) -> str:
+        """Optimize for search engines using Mistral API."""
+        prompt = f"""Generate 5 optimized versions of the following search query for traditional search engines (DuckDuckGo, Google, etc.).
+
+Optimization techniques to use:
+- Add boolean operators (AND, OR, NOT)
+- Use site: to target specific domains
+- Use filetype: to filter by document type
+- Use exact phrases with quotes
+- Add relevant keywords for precision
+- Include temporal filters when appropriate
+- Target reputable sources (Wikipedia, StackOverflow, GitHub, etc.)
+
+{self._SEARCH_ENGINE_EXAMPLES}
+
+Original query: {query}
+
+Generate candidates in the following JSON format:
+{{
+  "original_query": "{query}",
+  "candidates": [
+    {{
+      "version": 1,
+      "optimized_query": "...",
+      "reasoning": ["...", "..."]
+    }},
+    ...
+  ]
+}}
+
+Return ONLY valid JSON, no markdown formatting."""
+
+        return self._mistral_generate(
+            prompt,
+            response_format={
+                "type": "json_schema",
+                "json_schema": GenerationOutput.model_json_schema(),
+            },
+        )
+
+    def _optimize_ai_search_mistral(self, query: str) -> str:
+        """Optimize for AI search using Mistral API."""
+        prompt = f"""Generate 5 optimized versions of the following query for AI-powered search engines (Perplexity, Gemini Search, etc.).
+
+Optimization techniques to use:
+- Reframe as clear, specific questions
+- Add context about what information is needed
+- Include comparative or evaluative language when relevant
+- Ask for explanations, examples, or step-by-step guides
+- Include temporal context (current state, recent developments)
+- Focus on actionable information or insights
+
+{self._AI_SEARCH_EXAMPLES}
+
+Original query: {query}
+
+Generate candidates in the following JSON format:
+{{
+  "original_query": "{query}",
+  "candidates": [
+    {{
+      "version": 1,
+      "optimized_query": "...",
+      "reasoning": ["...", "..."]
+    }},
+    ...
+  ]
+}}
+
+Return ONLY valid JSON, no markdown formatting."""
+
+        return self._mistral_generate(
+            prompt,
+            response_format={
+                "type": "json_schema",
+                "json_schema": GenerationOutput.model_json_schema(),
+            },
+        )
+
+    def _select_best_mistral(self, candidates_json: str) -> int:
+        """Select best candidate using Mistral API."""
+        prompt = f"""{self._SELECTOR_PROMPT}
+
+{candidates_json}
+
+Return the version number (1-5) of the best candidate."""
+
+        response = self._mistral_generate(
+            prompt,
+            response_format={
+                "type": "json_schema",
+                "json_schema": ScoringOutput.model_json_schema(),
+            },
+        )
+
+        # Parse JSON response
+        json_str = self._extract_json_from_response(response)
+        result = json.loads(json_str)
+        return result["selected_version"]
+
+    def _optimize_search_engine_hf(self, query: str) -> str:
+        """Optimize for search engines using HF Inference (fallback)."""
+        prompt = f"""Generate 5 optimized search query candidates. Return as JSON with format:
+{{
+  "original_query": "...",
+  "candidates": [
+    {{"version": 1, "optimized_query": "...", "reasoning": ["..."]}},
+    ...
+  ]
+}}
+
+Query: {query}
+
+Optimize with boolean operators, site:, filetype:, quotes for phrases, and relevant keywords."""
+
+        response = self._hf_generate(prompt)
+        return self._extract_json_from_response(response)
+
+    def _optimize_ai_search_hf(self, query: str) -> str:
+        """Optimize for AI search using HF Inference (fallback)."""
+        prompt = f"""Generate 5 optimized query candidates for AI search. Return as JSON with format:
+{{
+  "original_query": "...",
+  "candidates": [
+    {{"version": 1, "optimized_query": "...", "reasoning": ["..."]}},
+    ...
+  ]
+}}
+
+Query: {query}
+
+Optimize as clear, specific questions with context and intent."""
+
+        response = self._hf_generate(prompt)
+        return self._extract_json_from_response(response)
+
+    def _select_best_hf(self, candidates_json: str) -> int:
+        """Select best candidate using HF Inference (fallback)."""
+        prompt = f"""{self._SELECTOR_PROMPT}
+
+{candidates_json}
+
+Return only the number (1-5)."""
+
+        response = self._hf_generate(prompt)
+        # Try to extract number from response
+        match = re.search(r"\b([1-5])\b", response)
+        if match:
+            return int(match.group(1))
+        return 1  # Default to first candidate
+
+    def _parse_candidates(self, json_str: str, original_query: str) -> GenerationOutput:
+        """Parse candidate JSON with fallback."""
+        try:
+            json_clean = self._extract_json_from_response(json_str)
+            return GenerationOutput.model_validate_json(json_clean)
+        except Exception:
+            # Fallback: create minimal candidate with original query
+            return GenerationOutput(
+                original_query=original_query,
+                candidates=[
+                    OptimizedCandidate(
+                        version=1,
+                        optimized_query=original_query,
+                        reasoning=["Fallback: using original query"],
+                    )
+                ],
+            )
+
+    def _run_optimization_chain(
+        self,
+        query: str,
+        mode: Literal["search_engine", "ai_search"],
+    ) -> tuple[GenerationOutput, int, str]:
+        """
+        Run optimization with fallback chain.
+
+        Returns:
+            (candidates, best_version, provider_used)
+        """
+        provider = "bypass"
+
+        # Try Mistral API first
+        try:
+            if mode == "search_engine":
+                response = self._optimize_search_engine_mistral(query)
+            else:
+                response = self._optimize_ai_search_mistral(query)
+
+            candidates = self._parse_candidates(response, query)
+            best_version = self._select_best_mistral(response)
+            provider = "mistral"
+            return candidates, best_version, provider
+        except Exception as exc:
+            print(f"[QueryOptimizer] Mistral failed: {exc}", flush=True)
+
+        # Fallback to HF Inference
+        try:
+            if mode == "search_engine":
+                response = self._optimize_search_engine_hf(query)
+            else:
+                response = self._optimize_ai_search_hf(query)
+
+            candidates = self._parse_candidates(response, query)
+            best_version = self._select_best_hf(response)
+            provider = "hf"
+            return candidates, best_version, provider
+        except Exception as exc:
+            print(f"[QueryOptimizer] HF failed: {exc}", flush=True)
+
+        # Final bypass: return original query
+        candidates = GenerationOutput(
+            original_query=query,
+            candidates=[
+                OptimizedCandidate(
+                    version=1,
+                    optimized_query=query,
+                    reasoning=["Bypass: using original query due to optimization failure"],
+                )
+            ],
+        )
+        return candidates, 1, provider
+
+    def optimize_for_search_engine(self, query: str) -> tuple[str, dict[str, Any]]:
+        """
+        Optimize query for traditional search engines.
+
+        Optimizes with boolean operators, site:, filetype:, exact phrases.
+
+        Args:
+            query: The original search query
+
+        Returns:
+            (optimized_query, metadata) tuple with metadata including:
+            - original_query: The input query
+            - all_candidates: List of all generated candidates
+            - reasoning: Reasoning for selected candidate
+            - provider: Which provider was used (mistral/hf/bypass)
+        """
+        candidates, best_version, provider = self._run_optimization_chain(
+            query, "search_engine"
+        )
+
+        # Get selected candidate
+        selected = next(
+            (c for c in candidates.candidates if c.version == best_version),
+            candidates.candidates[0],
+        )
+
+        metadata = {
+            "original_query": candidates.original_query,
+            "all_candidates": [
+                {"version": c.version, "query": c.optimized_query}
+                for c in candidates.candidates
+            ],
+            "reasoning": selected.reasoning,
+            "provider": provider,
+        }
+
+        return selected.optimized_query, metadata
+
+    def optimize_for_ai_search(self, query: str) -> tuple[str, dict[str, Any]]:
+        """
+        Optimize query for AI-powered search engines.
+
+        Optimizes with clear intent, context, specific questions.
+
+        Args:
+            query: The original search query
+
+        Returns:
+            (optimized_query, metadata) tuple with metadata including:
+            - original_query: The input query
+            - all_candidates: List of all generated candidates
+            - reasoning: Reasoning for selected candidate
+            - provider: Which provider was used (mistral/hf/bypass)
+        """
+        candidates, best_version, provider = self._run_optimization_chain(query, "ai_search")
+
+        # Get selected candidate
+        selected = next(
+            (c for c in candidates.candidates if c.version == best_version),
+            candidates.candidates[0],
+        )
+
+        metadata = {
+            "original_query": candidates.original_query,
+            "all_candidates": [
+                {"version": c.version, "query": c.optimized_query}
+                for c in candidates.candidates
+            ],
+            "reasoning": selected.reasoning,
+            "provider": provider,
+        }
+
+        return selected.optimized_query, metadata
+
+
+# Singleton instance for module-level caching
+_optimizer_instance: QueryOptimizer | None = None
+
+
+def get_optimizer() -> QueryOptimizer:
+    """Get or create the singleton optimizer instance."""
+    global _optimizer_instance
+    if _optimizer_instance is None:
+        _optimizer_instance = QueryOptimizer()
+    return _optimizer_instance
+
+
+# ===========================================================================
+# Gradio Tool Functions
+# ===========================================================================
+
+
+@autodoc(
+    summary="Optimize a search query for traditional search engines using SC-CoT with fallback chain (Mistral → HF → bypass).",
+)
+def Optimize_for_Search_Engine(
+    query: Annotated[str, "The search query to optimize."],
+) -> str:
+    """
+    Optimize a query for traditional search engines (DuckDuckGo, Google, etc.).
+
+    Uses Self-Consistency Chain-of-Thought with fallback chain:
+    1. Mistral API (magistral-medium-2509) - Primary
+    2. HuggingFace Inference - Fallback
+    3. Bypass (return raw query) - Final fallback
+
+    Optimization techniques:
+    - Boolean operators (AND, OR, NOT)
+    - site: for domain targeting
+    - filetype: for document type filtering
+    - Exact phrases with quotes
+    - Relevant keywords for precision
+    - Temporal filters when appropriate
+    """
+    _log_call_start("Optimize_for_Search_Engine", query=query)
+
+    if not query or not query.strip():
+        result = "No query provided. Please enter a search query to optimize."
+        _log_call_end("Optimize_for_Search_Engine", _truncate_for_log(result))
+        return result
+
+    optimizer = get_optimizer()
+
+    try:
+        optimized, metadata = optimizer.optimize_for_search_engine(query)
+
+        lines = [
+            f"Original: {metadata['original_query']}",
+            f"Optimized: {optimized}",
+            f"Provider: {metadata['provider']}",
+            "",
+            "All candidates:",
+        ]
+
+        for i, candidate in enumerate(metadata["all_candidates"], 1):
+            prefix = "→" if i == 1 else "  "
+            lines.append(f"{prefix} {candidate['version']}. {candidate['query']}")
+
+        lines.append("")
+        lines.append("Reasoning:")
+        lines.extend(f"  • {step}" for step in metadata["reasoning"])
+
+        result = "\n".join(lines)
+        _log_call_end("Optimize_for_Search_Engine", _truncate_for_log(result))
+        return result
+    except Exception as exc:
+        result = f"Optimization failed: {exc}"
+        _log_call_end("Optimize_for_Search_Engine", _truncate_for_log(result))
+        return result
+
+
+@autodoc(
+    summary="Optimize a search query for AI-powered search engines using SC-CoT with fallback chain (Mistral → HF → bypass).",
+)
+def Optimize_for_AI_Search(
+    query: Annotated[str, "The search query to optimize."],
+) -> str:
+    """
+    Optimize a query for AI-powered search engines (Perplexity, Gemini, etc.).
+
+    Uses Self-Consistency Chain-of-Thought with fallback chain:
+    1. Mistral API (magistral-medium-2509) - Primary
+    2. HuggingFace Inference - Fallback
+    3. Bypass (return raw query) - Final fallback
+
+    Optimization techniques:
+    - Clear, specific questions
+    - Context about what information is needed
+    - Comparative or evaluative language
+    - Requests for explanations or examples
+    - Temporal context (current state, recent developments)
+    - Focus on actionable information
+    """
+    _log_call_start("Optimize_for_AI_Search", query=query)
+
+    if not query or not query.strip():
+        result = "No query provided. Please enter a search query to optimize."
+        _log_call_end("Optimize_for_AI_Search", _truncate_for_log(result))
+        return result
+
+    optimizer = get_optimizer()
+
+    try:
+        optimized, metadata = optimizer.optimize_for_ai_search(query)
+
+        lines = [
+            f"Original: {metadata['original_query']}",
+            f"Optimized: {optimized}",
+            f"Provider: {metadata['provider']}",
+            "",
+            "All candidates:",
+        ]
+
+        for i, candidate in enumerate(metadata["all_candidates"], 1):
+            prefix = "→" if i == 1 else "  "
+            lines.append(f"{prefix} {candidate['version']}. {candidate['query']}")
+
+        lines.append("")
+        lines.append("Reasoning:")
+        lines.extend(f"  • {step}" for step in metadata["reasoning"])
+
+        result = "\n".join(lines)
+        _log_call_end("Optimize_for_AI_Search", _truncate_for_log(result))
+        return result
+    except Exception as exc:
+        result = f"Optimization failed: {exc}"
+        _log_call_end("Optimize_for_AI_Search", _truncate_for_log(result))
+        return result
+
+
+def build_interfaces() -> list[gr.Interface]:
+    """Build Gradio interfaces for query optimizer tools."""
+    return [
+        gr.Interface(
+            fn=Optimize_for_Search_Engine,
+            inputs=[
+                gr.Textbox(
+                    label="Query",
+                    placeholder="Enter your search query",
+                    max_lines=1,
+                    info="The search query to optimize for traditional search engines",
+                ),
+            ],
+            outputs=gr.Textbox(
+                label="Optimization Results",
+                interactive=False,
+                lines=15,
+                max_lines=20,
+            ),
+            title="Query Optimizer (Search Engine)",
+            description=(
+                "<div style='text-align:center'>"
+                "Optimize queries for traditional search engines using AI. "
+                "Generates multiple candidates and selects the best one. "
+                "Optimizes with boolean operators, site:, filetype:, and precise keywords."
+                "</div>"
+            ),
+            api_name="optimize_for_search_engine",
+            flagging_mode="never",
+            submit_btn="Optimize",
+        ),
+        gr.Interface(
+            fn=Optimize_for_AI_Search,
+            inputs=[
+                gr.Textbox(
+                    label="Query",
+                    placeholder="Enter your search query",
+                    max_lines=1,
+                    info="The search query to optimize for AI-powered search engines",
+                ),
+            ],
+            outputs=gr.Textbox(
+                label="Optimization Results",
+                interactive=False,
+                lines=15,
+                max_lines=20,
+            ),
+            title="Query Optimizer (AI Search)",
+            description=(
+                "<div style='text-align:center'>"
+                "Optimize queries for AI-powered search engines using AI. "
+                "Generates multiple candidates and selects the best one. "
+                "Optimizes with clear questions, context, and specific intent."
+                "</div>"
+            ),
+            api_name="optimize_for_ai_search",
+            flagging_mode="never",
+            submit_btn="Optimize",
+        ),
+    ]
+
+
+__all__ = [
+    "QueryOptimizer",
+    "get_optimizer",
+    "Optimize_for_Search_Engine",
+    "Optimize_for_AI_Search",
+    "build_interfaces",
+]

Modules/_searxng_client.py

@@ -0,0 +1,460 @@
+"""
+SearXNG Client Module
+
+HTTP client for SearXNG metasearch engine with auto-fallback to multiple instances.
+Supports text, image, and news search with rate limiting and error handling.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Optional
+
+import httpx
+
+
+class TimeRange(str, Enum):
+    """Time range options for search results."""
+    DAY = "day"
+    WEEK = "week"
+    MONTH = "month"
+    YEAR = "year"
+
+
+@dataclass
+class TextResult:
+    """Represents a text/web search result."""
+    url: str
+    title: str
+    content: str
+    engine: Optional[str] = None
+    category: Optional[str] = None
+    score: float = 0.0
+
+
+@dataclass
+class ImageResult:
+    """Represents an image search result."""
+    url: str
+    title: str
+    img_src: str
+    thumbnail_src: str
+    engine: Optional[str] = None
+    source: Optional[str] = None
+    resolution: Optional[str] = None
+
+
+@dataclass
+class NewsResult:
+    """Represents a news search result."""
+    url: str
+    title: str
+    content: str
+    engine: Optional[str] = None
+    published_date: Optional[str] = None
+    score: float = 0.0
+
+
+class SearXNGError(Exception):
+    """Base exception for SearXNG client errors."""
+    pass
+
+
+class RateLimitError(SearXNGError):
+    """Raised when rate limit is exceeded."""
+    pass
+
+
+class InstanceUnavailableError(SearXNGError):
+    """Raised when a SearXNG instance is unavailable."""
+    pass
+
+
+class AllInstancesFailedError(SearXNGError):
+    """Raised when all SearXNG instances fail."""
+    pass
+
+
+class SearXNGClient:
+    """
+    HTTP client for SearXNG metasearch engine.
+
+    Features:
+    - Multiple instance support with auto-fallback
+    - Connection pooling for performance
+    - Automatic retries with exponential backoff
+    - Type-safe result parsing
+    - Configurable timeouts
+    """
+
+    def __init__(
+        self,
+        instances: Optional[list[str]] = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        pool_connections: int = 10,
+        pool_maxsize: int = 10,
+    ) -> None:
+        """
+        Initialize SearXNG client.
+
+        Args:
+            instances: List of SearXNG instance URLs (primary first)
+            timeout: Request timeout in seconds
+            max_retries: Maximum retry attempts per instance
+            retry_delay: Initial retry delay in seconds (exponential backoff)
+            pool_connections: Connection pool size
+            pool_maxsize: Maximum connections in pool
+        """
+        self.instances = instances or [
+            "https://searx.be",
+            "https://search.sapti.me",
+            "https://searx.fmac.xyz",
+        ]
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        # Configure httpx client with connection pooling
+        limits = httpx.Limits(
+            max_connections=pool_connections,
+            max_keepalive_connections=pool_maxsize,
+        )
+        self._client = httpx.Client(
+            timeout=timeout,
+            limits=limits,
+            follow_redirects=True,
+            verify=True,
+        )
+
+    def _build_params(
+        self,
+        query: str,
+        categories: Optional[list[str]] = None,
+        engines: Optional[list[str]] = None,
+        pageno: int = 1,
+        time_range: Optional[TimeRange] = None,
+    ) -> dict[str, str | int]:
+        """Build query parameters for SearXNG API."""
+        params: dict[str, str | int] = {
+            "q": query,
+            "format": "json",
+            "pageno": pageno,
+        }
+
+        if categories:
+            params["categories"] = ",".join(categories)
+        if engines:
+            params["engines"] = ",".join(engines)
+        if time_range:
+            params["time_range"] = time_range.value
+
+        return params
+
+    def _make_request(
+        self,
+        instance: str,
+        params: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Make HTTP request to SearXNG instance.
+
+        Args:
+            instance: SearXNG instance URL
+            params: Query parameters
+
+        Returns:
+            JSON response data
+
+        Raises:
+            InstanceUnavailableError: If instance is unreachable
+            RateLimitError: If rate limit is exceeded
+            SearXNGError: For other API errors
+        """
+        url = f"{instance.rstrip('/')}/search"
+
+        try:
+            response = self._client.get(url, params=params)
+
+            # Handle rate limiting
+            if response.status_code == 429:
+                raise RateLimitError(f"Rate limit exceeded for {instance}")
+
+            # Handle server errors
+            if response.status_code >= 500:
+                raise InstanceUnavailableError(
+                    f"Server error {response.status_code} for {instance}"
+                )
+
+            # Handle client errors
+            if response.status_code >= 400:
+                raise SearXNGError(
+                    f"Client error {response.status_code}: {response.text}"
+                )
+
+            return response.json()
+
+        except httpx.TimeoutException as e:
+            raise InstanceUnavailableError(f"Timeout for {instance}: {e}") from e
+        except httpx.ConnectError as e:
+            raise InstanceUnavailableError(f"Connection failed to {instance}: {e}") from e
+        except httpx.HTTPStatusError as e:
+            raise InstanceUnavailableError(f"HTTP error from {instance}: {e}") from e
+
+    def _search_with_retry(
+        self,
+        params: dict[str, Any],
+    ) -> tuple[list[dict[str, Any]], str]:
+        """
+        Search with automatic instance fallback and retry logic.
+
+        Args:
+            params: Query parameters
+
+        Returns:
+            Tuple of (results list, instance URL that succeeded)
+
+        Raises:
+            AllInstancesFailedError: If all instances fail
+        """
+        last_error: Optional[Exception] = None
+
+        for instance in self.instances:
+            for attempt in range(self.max_retries):
+                try:
+                    response = self._make_request(instance, params)
+
+                    if not response.get("results"):
+                        # No results but request succeeded
+                        return [], instance
+
+                    return response["results"], instance
+
+                except RateLimitError as e:
+                    last_error = e
+                    # Don't retry rate limit errors, move to next instance
+                    break
+
+                except InstanceUnavailableError as e:
+                    last_error = e
+                    if attempt < self.max_retries - 1:
+                        # Exponential backoff
+                        delay = self.retry_delay * (2**attempt)
+                        time.sleep(delay)
+                    continue
+
+                except SearXNGError as e:
+                    last_error = e
+                    # Non-retryable error, move to next instance
+                    break
+
+        # All instances failed
+        raise AllInstancesFailedError(
+            f"All SearXNG instances failed. Last error: {last_error}"
+        ) from last_error
+
+    def search(
+        self,
+        query: str,
+        categories: Optional[list[str]] = None,
+        engines: Optional[list[str]] = None,
+        pageno: int = 1,
+        time_range: Optional[TimeRange] = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Generic search method returning raw results.
+
+        Args:
+            query: Search query string
+            categories: List of result categories (e.g., ['general', 'images'])
+            engines: List of search engines to use
+            pageno: Page number (1-indexed)
+            time_range: Time filter for results
+
+        Returns:
+            List of raw result dictionaries
+
+        Raises:
+            AllInstancesFailedError: If all instances fail
+        """
+        params = self._build_params(
+            query=query,
+            categories=categories,
+            engines=engines,
+            pageno=pageno,
+            time_range=time_range,
+        )
+
+        results, _instance = self._search_with_retry(params)
+        return results
+
+    def text(
+        self,
+        query: str,
+        max_results: int = 10,
+        time_range: Optional[TimeRange] = None,
+    ) -> list[TextResult]:
+        """
+        Perform text/web search.
+
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+            time_range: Time filter for results
+
+        Returns:
+            List of TextResult objects
+
+        Raises:
+            AllInstancesFailedError: If all instances fail
+        """
+        params = self._build_params(
+            query=query,
+            categories=["general"],
+            pageno=1,
+            time_range=time_range,
+        )
+
+        raw_results, _instance = self._search_with_retry(params)
+
+        results = []
+        for item in raw_results[:max_results]:
+            if item.get("category") in ["general", ""]:
+                results.append(
+                    TextResult(
+                        url=item.get("url", ""),
+                        title=item.get("title", ""),
+                        content=item.get("content", ""),
+                        engine=item.get("engine"),
+                        category=item.get("category"),
+                        score=item.get("score", 0.0),
+                    )
+                )
+
+        return results
+
+    def images(
+        self,
+        query: str,
+        max_results: int = 10,
+    ) -> list[ImageResult]:
+        """
+        Perform image search.
+
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+
+        Returns:
+            List of ImageResult objects
+
+        Raises:
+            AllInstancesFailedError: If all instances fail
+        """
+        params = self._build_params(
+            query=query,
+            categories=["images"],
+            pageno=1,
+        )
+
+        raw_results, _instance = self._search_with_retry(params)
+
+        results = []
+        for item in raw_results[:max_results]:
+            if item.get("category") == "images":
+                results.append(
+                    ImageResult(
+                        url=item.get("url", ""),
+                        title=item.get("title", ""),
+                        img_src=item.get("img_src", ""),
+                        thumbnail_src=item.get("thumbnail_src", ""),
+                        engine=item.get("engine"),
+                        source=item.get("source"),
+                        resolution=item.get("resolution"),
+                    )
+                )
+
+        return results
+
+    def news(
+        self,
+        query: str,
+        max_results: int = 10,
+        time_range: Optional[TimeRange] = None,
+    ) -> list[NewsResult]:
+        """
+        Perform news search.
+
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+            time_range: Time filter for results
+
+        Returns:
+            List of NewsResult objects
+
+        Raises:
+            AllInstancesFailedError: If all instances fail
+        """
+        params = self._build_params(
+            query=query,
+            categories=["news"],
+            pageno=1,
+            time_range=time_range,
+        )
+
+        raw_results, _instance = self._search_with_retry(params)
+
+        results = []
+        for item in raw_results[:max_results]:
+            if item.get("category") == "news":
+                results.append(
+                    NewsResult(
+                        url=item.get("url", ""),
+                        title=item.get("title", ""),
+                        content=item.get("content", ""),
+                        engine=item.get("engine"),
+                        published_date=item.get("publishedDate"),
+                        score=item.get("score", 0.0),
+                    )
+                )
+
+        return results
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self._client.close()
+
+    def __enter__(self) -> "SearXNGClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, _exc_type: Any, _exc_val: Any, _exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+
+# Convenience function for quick searches
+def search_text(
+    query: str,
+    max_results: int = 10,
+    time_range: Optional[TimeRange] = None,
+    instances: Optional[list[str]] = None,
+) -> list[TextResult]:
+    """
+    Quick text search with default configuration.
+
+    Args:
+        query: Search query string
+        max_results: Maximum number of results to return
+        time_range: Time filter for results
+        instances: Optional custom instance list
+
+    Returns:
+        List of TextResult objects
+    """
+    with SearXNGClient(instances=instances) as client:
+        return client.text(query, max_results, time_range)

README.md

@@ -1,267 +1,267 @@
----
-title: Nymbo Tools MCP
-emoji: ⚙️
-colorFrom: green
-colorTo: gray
-sdk: gradio
-sdk_version: 6.2.0
-python_version: 3.12
-app_file: app.py
-pinned: true
-license: apache-2.0
-short_description: All-in-one hub of general purpose tools useful for any agent
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
-
-## Nymbo-Tools MCP Server
-
-All-in-one hub of general-purpose tools useful for any agent. Run it as a Gradio web app, or connect to it remotely as a Model Context Protocol (MCP) server to call its tools programmatically.
-
-Live Space: https://huggingface.co/spaces/Nymbo/Tools
-
-### What’s inside
-
-- Web Fetch: Turn any webpage into clean Markdown with optional link-only scraping, CSS selector stripping, length limits, and pagination via cursor offset.
-- Web Search: DuckDuckGo-backed search across text, news, images, videos, and books with readable, paginated output.
-- Code Interpreter: Execute small Python snippets and capture stdout.
-- Memory Manager: Lightweight JSON-based memory store with save/list/search/delete and tag filters.
-- Generate Speech: Kokoro‑82M TTS with 54 voices and adjustable speed (CPU or CUDA if available).
-- Generate Image: Text-to-image via Hugging Face serverless inference (choose model, steps, CFG, size, seed).
-- Generate Video: Text-to-video via Hugging Face serverless inference (model, steps, guidance, size, fps, duration, seed).
-- Deep Research: Multi-query web research pipeline (DDG search + parallel fetch + LLM report synthesis) with downloadable report.
-- Agent Skills: Discover, inspect, and access specialized agent skills and resources.
-- Agent Terminal: Execute Python code to chain multiple tools together (e.g., fetch -> summarize -> save) efficiently.
-- Obsidian Vault: Read-only access to an Obsidian vault (list, read, search notes) with safelisted paths.
-- File System: Safe, sandboxed filesystem operations under a tool root.
-- Shell Command: Run shell commands inside the same safe root as File System.
-
-## Quick start
-
-Run the following commands in sequence to run the server locally:
-
-```shell
-git clone https://huggingface.co/spaces/Nymbo/Tools
-cd Tools
-python -m venv env
-source env/bin/activate
-pip install -r requirements.txt
-python app.py
-```
-
-Defaults:
-- The Gradio UI typically serves on http://127.0.0.1:7860
-- The MCP endpoint is available at http://127.0.0.1:7860/gradio_api/mcp/
-
-## Using it as an MCP server
-
-Remote MCP (hosted):
-- Base URL: https://mcp.nymbo.net/gradio_api/mcp/
-- SSE endpoint (for clients that need it): https://mcp.nymbo.net/gradio_api/mcp/sse
-
-Local MCP (when you run app.py):
-- Base URL: http://127.0.0.1:7860/gradio_api/mcp/
-- SSE endpoint: http://127.0.0.1:7860/gradio_api/mcp/sse
-
-Example client config (JSON):
-
-```json
-{
-	"mcpServers": {
-		"nymbo-tools": {
-			"url": "https://mcp.nymbo.net/gradio_api/mcp/"
-		}
-	}
-}
-```
-
-## Environment variables (optional but recommended)
-
-- HF_READ_TOKEN: Enables Image Generation, Video Generation, and Deep Research (Hugging Face serverless inference). These tools stay visible to MCP clients but calls require a valid token to succeed.
-- HF_TOKEN: Alternative token fallback used by some providers (also enables Deep Research/Video).
-- NYMBO_TOOLS_ROOT: Overrides the File System/Shell working root. Defaults to Nymbo-Tools/Filesystem.
-- UNSAFE_ALLOW_ABS_PATHS=1: Allow absolute paths in File System and Shell Command (off by default for safety).
-
-Notes:
-- Without a HF API key, you can still use Web Fetch, Web Search, Code Interpreter, Memory Manager, File System, Shell Command, and Generate Speech.
-- Generate Speech requires the kokoro package and its dependencies; it works on CPU and uses CUDA if available. Doesn't require an API key because it's computed on the server itself.
-
-## Persistence and privacy
-
-- Memory Manager stores entries in `memories.json` at the Nymbo-Tools folder root when running locally.
-- File System defaults to the `Filesystem/` directory under Nymbo-Tools.
-- In the public demo Space, storage is ephemeral and visible to anyone using the Space; avoid personal or sensitive data.
-
-## Tool reference (signatures and behavior)
-
-Below are the MCP tool parameters summarized by inputs, outputs, and notable behaviors.
-
-### Web_Fetch (Webpages, converted to Markdown)
-Inputs:
-- url (str): Absolute URL to fetch (must return HTML).
-- max_chars (int, default 3000): 0 = full page; otherwise truncates with a next_cursor notice.
-- strip_selectors (str): Comma-separated CSS selectors to remove (e.g., .header, .footer, nav).
-- mode (str): "markdown" (default), "html", or "url_scraper" (returns list of links).
-- offset (int): Character offset for pagination; pass the previous next_cursor to continue.
-
-Output: Markdown string, raw HTML, or link list. If truncated, includes a next_cursor to continue.
-
-### Web_Search (DuckDuckGo backend)
-Inputs:
-- query (str): DuckDuckGo query (supports site:, quotes, OR).
-- max_results (int 1–20, default 5)
-- page (int, default 1) or offset (int) for precise continuation
-- search_type (str): "text" | "news" | "images" | "videos" | "books"
-
-Output: Readable text with pagination hints and next_offset.
-
-### Code_Interpreter (Python)
-Inputs:
-- code (str): Python source; stdout is captured.
-
-Output: Captured stdout or the exception text.
-
-### Memory_Manager (Simple JSON store)
-Inputs:
-- action: "save" | "list" | "search" | "delete"
-- text (save only), tags (save only)
-- query (search only): supports tag:name terms and AND/OR
-- limit (list/search): default 20
-- memory_id (delete): full UUID or unique prefix
-- include_tags (bool): include tags when listing/searching
-
-Output: Confirmation string, listing, search matches, or structured error text.
-
-### Generate_Speech (Kokoro-82M)
-Inputs:
-- text (str)
-- speed (float 0.5–2.0, default 1.25)
-- voice (str): One of 54 voices (e.g., af_heart, am_liam, bf_alice, zf_xiaoyi…)
-
-Output: (sample_rate:int, waveform:np.ndarray) – rendered as downloadable WAV in the UI.
-
-### Generate_Image (HF inference)
-Requires: HF_READ_TOKEN
-
-Inputs:
-- prompt (str)
-- model_id (str): e.g., black-forest-labs/FLUX.1-Krea-dev
-- negative_prompt (str)
-- steps (1–100), cfg_scale (1–20), sampler (UI label), seed (-1=random), width/height
-
-Output: PIL.Image. In UI, displayed and downloadable. Errors guide you to provide a token or fix model id.
-
-### Generate_Video (HF inference)
-Requires: HF_READ_TOKEN or HF_TOKEN
-
-Inputs:
-- prompt (str)
-- model_id (str): default Wan-AI/Wan2.2-T2V-A14B
-- negative_prompt (str)
-- steps (1–100), cfg_scale, seed, width/height, fps, duration (s)
-
-Output: Temporary MP4 file path; UI shows a playable/downloadable video.
-
-### Deep_Research (HF inference)
-Requires: HF_READ_TOKEN or HF_TOKEN
-
-Inputs:
-- summary (str): One or more sentences describing the research task.
-- query1..query5 (str) with max1..max5 (1–50). Total requested results across queries are capped at 50.
-
-Behavior:
-- Parallel DDG searches → fetch pages in budget → filter candidate sources with an LLM → synthesize a long, well-structured Markdown report and list of sources.
-
-Output: (report_md, fetched_links_text, report_file_path)
-
-### File_System (safe root)
-Root:
-- Defaults to `Nymbo-Tools/Filesystem` (or NYMBO_TOOLS_ROOT). Absolute paths disabled unless UNSAFE_ALLOW_ABS_PATHS=1.
-
-Actions:
-- list, read, write, append, edit, mkdir, move, copy, delete, info, help
-
-Key fields:
-- path, content (write/append/edit), dest_path (move/copy), recursive, show_hidden, max_entries, offset, max_chars, create_dirs, overwrite
-
-Edit format (SEARCH/REPLACE blocks):
-```
-<<<<<<< SEARCH
-[exact content to find]
-=======
-[new content to replace with]
->>>>>>> REPLACE
-```
-- Multiple blocks can be included; each is applied in order
-- Search text must match exactly (whitespace, indentation)
-- Only the first occurrence of each search text is replaced
-
-Output:
-- Human-readable listings or JSON-like error strings with code/message/hint.
-
-### Shell_Command (same safe root)
-Inputs:
-- command (str): Single-string shell command (pipelines supported by the host shell).
-- workdir (str): Relative to the root.
-- timeout (s)
-
-Output:
-- Combined header + STDOUT/STDERR. Absolute paths disabled by default. Shell is detected automatically (PowerShell on Windows when available; bash/sh on POSIX).
-
-### Agent_Skills (Skill Discovery)
-Inputs:
-- action: "discover" | "info" | "resources" | "validate" | "search" | "help"
-- skill_name (str): Required for info/resources/validate.
-- resource_path (str): Specific file to read within a skill.
-- query (str): Search term for "search" action.
-- max_chars (int), offset (int)
-
-Output:
-- Detailed skill metadata, SKILL.md content, resource file content, or validation reports.
-
-### Agent_Terminal (Tool Chaining)
-Inputs:
-- input (str): Python source code to execute.
-    - Can call any other tool (e.g., `Web_Fetch(...)`, `File_System(...)`).
-    - Use `search_tools("query")` to find tools.
-    - Call a tool with no args to get its usage guide.
-
-Output:
-- Captured STDOUT validation of the script.
-
-### Obsidian_Vault (Read-only Note Access)
-Root:
-- Defaults to `Tools/Obsidian` (or OBSIDIAN_VAULT_ROOT).
-
-Inputs:
-- action: "list" | "read" | "info" | "search" | "help"
-- path (str): Relative to vault root (start with /).
-- query (str): For search action.
-- recursive (bool), show_hidden (bool), max_entries (int)
-- offset (int), max_chars (int)
-
-Output:
-- File listings, note content, or search results (with context).
-
-## Running on Hugging Face Spaces
-
-1) Duplicate the Space at https://huggingface.co/spaces/Nymbo/Tools.
-2) In Space Settings → Secrets, add HF_READ_TOKEN (and/or HF_TOKEN) for model access.
-3) Both the UI and MCP clients will list every tool. Image/Video/Deep Research still need a valid token when invoked.
-
-## Troubleshooting
-
-- Image/Video/Deep Research calls fail immediately:
-	- Provide HF_READ_TOKEN (and optionally HF_TOKEN). Restart the app/Space.
-- 401/403 when calling generation tools:
-	- Token missing/insufficient permissions. Ensure your token can read the chosen model.
-- Kokoro not found:
-	- Install kokoro>=0.9.4. CPU works; CUDA used if available. Torch may be skipped on Apple Silicon by design.
-- Windows PowerShell activation policy blocks venv activation:
-	- Run PowerShell as Admin and set a suitable execution policy for the current user (e.g., RemoteSigned), or manually run `python app.py` after installing dependencies.
-- File System or Shell path errors:
-	- Paths are relative to the tool root. Set NYMBO_TOOLS_ROOT to customize. Set UNSAFE_ALLOW_ABS_PATHS=1 only if you fully trust the environment.
-
-## License
-
+---
+title: Nymbo Tools MCP
+emoji: ⚙️
+colorFrom: green
+colorTo: gray
+sdk: gradio
+sdk_version: 6.2.0
+python_version: 3.12
+app_file: app.py
+pinned: true
+license: apache-2.0
+short_description: All-in-one hub of general purpose tools useful for any agent
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Nymbo-Tools MCP Server
+
+All-in-one hub of general-purpose tools useful for any agent. Run it as a Gradio web app, or connect to it remotely as a Model Context Protocol (MCP) server to call its tools programmatically.
+
+Live Space: https://huggingface.co/spaces/Nymbo/Tools
+
+### What’s inside
+
+- Web Fetch: Turn any webpage into clean Markdown with optional link-only scraping, CSS selector stripping, length limits, and pagination via cursor offset.
+- Web Search: DuckDuckGo-backed search across text, news, images, videos, and books with readable, paginated output.
+- Code Interpreter: Execute small Python snippets and capture stdout.
+- Memory Manager: Lightweight JSON-based memory store with save/list/search/delete and tag filters.
+- Generate Speech: Kokoro‑82M TTS with 54 voices and adjustable speed (CPU or CUDA if available).
+- Generate Image: Text-to-image via Hugging Face serverless inference (choose model, steps, CFG, size, seed).
+- Generate Video: Text-to-video via Hugging Face serverless inference (model, steps, guidance, size, fps, duration, seed).
+- Deep Research: Multi-query web research pipeline (DDG search + parallel fetch + LLM report synthesis) with downloadable report.
+- Agent Skills: Discover, inspect, and access specialized agent skills and resources.
+- Agent Terminal: Execute Python code to chain multiple tools together (e.g., fetch -> summarize -> save) efficiently.
+- Obsidian Vault: Read-only access to an Obsidian vault (list, read, search notes) with safelisted paths.
+- File System: Safe, sandboxed filesystem operations under a tool root.
+- Shell Command: Run shell commands inside the same safe root as File System.
+
+## Quick start
+
+Run the following commands in sequence to run the server locally:
+
+```shell
+git clone https://huggingface.co/spaces/Nymbo/Tools
+cd Tools
+python -m venv env
+source env/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+Defaults:
+- The Gradio UI typically serves on http://127.0.0.1:7860
+- The MCP endpoint is available at http://127.0.0.1:7860/gradio_api/mcp/
+
+## Using it as an MCP server
+
+Remote MCP (hosted):
+- Base URL: https://mcp.nymbo.net/gradio_api/mcp/
+- SSE endpoint (for clients that need it): https://mcp.nymbo.net/gradio_api/mcp/sse
+
+Local MCP (when you run app.py):
+- Base URL: http://127.0.0.1:7860/gradio_api/mcp/
+- SSE endpoint: http://127.0.0.1:7860/gradio_api/mcp/sse
+
+Example client config (JSON):
+
+```json
+{
+	"mcpServers": {
+		"nymbo-tools": {
+			"url": "https://mcp.nymbo.net/gradio_api/mcp/"
+		}
+	}
+}
+```
+
+## Environment variables (optional but recommended)
+
+- HF_READ_TOKEN: Enables Image Generation, Video Generation, and Deep Research (Hugging Face serverless inference). These tools stay visible to MCP clients but calls require a valid token to succeed.
+- HF_TOKEN: Alternative token fallback used by some providers (also enables Deep Research/Video).
+- NYMBO_TOOLS_ROOT: Overrides the File System/Shell working root. Defaults to Nymbo-Tools/Filesystem.
+- UNSAFE_ALLOW_ABS_PATHS=1: Allow absolute paths in File System and Shell Command (off by default for safety).
+
+Notes:
+- Without a HF API key, you can still use Web Fetch, Web Search, Code Interpreter, Memory Manager, File System, Shell Command, and Generate Speech.
+- Generate Speech requires the kokoro package and its dependencies; it works on CPU and uses CUDA if available. Doesn't require an API key because it's computed on the server itself.
+
+## Persistence and privacy
+
+- Memory Manager stores entries in `memories.json` at the Nymbo-Tools folder root when running locally.
+- File System defaults to the `Filesystem/` directory under Nymbo-Tools.
+- In the public demo Space, storage is ephemeral and visible to anyone using the Space; avoid personal or sensitive data.
+
+## Tool reference (signatures and behavior)
+
+Below are the MCP tool parameters summarized by inputs, outputs, and notable behaviors.
+
+### Web_Fetch (Webpages, converted to Markdown)
+Inputs:
+- url (str): Absolute URL to fetch (must return HTML).
+- max_chars (int, default 3000): 0 = full page; otherwise truncates with a next_cursor notice.
+- strip_selectors (str): Comma-separated CSS selectors to remove (e.g., .header, .footer, nav).
+- mode (str): "markdown" (default), "html", or "url_scraper" (returns list of links).
+- offset (int): Character offset for pagination; pass the previous next_cursor to continue.
+
+Output: Markdown string, raw HTML, or link list. If truncated, includes a next_cursor to continue.
+
+### Web_Search (DuckDuckGo backend)
+Inputs:
+- query (str): DuckDuckGo query (supports site:, quotes, OR).
+- max_results (int 1–20, default 5)
+- page (int, default 1) or offset (int) for precise continuation
+- search_type (str): "text" | "news" | "images" | "videos" | "books"
+
+Output: Readable text with pagination hints and next_offset.
+
+### Code_Interpreter (Python)
+Inputs:
+- code (str): Python source; stdout is captured.
+
+Output: Captured stdout or the exception text.
+
+### Memory_Manager (Simple JSON store)
+Inputs:
+- action: "save" | "list" | "search" | "delete"
+- text (save only), tags (save only)
+- query (search only): supports tag:name terms and AND/OR
+- limit (list/search): default 20
+- memory_id (delete): full UUID or unique prefix
+- include_tags (bool): include tags when listing/searching
+
+Output: Confirmation string, listing, search matches, or structured error text.
+
+### Generate_Speech (Kokoro-82M)
+Inputs:
+- text (str)
+- speed (float 0.5–2.0, default 1.25)
+- voice (str): One of 54 voices (e.g., af_heart, am_liam, bf_alice, zf_xiaoyi…)
+
+Output: (sample_rate:int, waveform:np.ndarray) – rendered as downloadable WAV in the UI.
+
+### Generate_Image (HF inference)
+Requires: HF_READ_TOKEN
+
+Inputs:
+- prompt (str)
+- model_id (str): e.g., black-forest-labs/FLUX.1-Krea-dev
+- negative_prompt (str)
+- steps (1–100), cfg_scale (1–20), sampler (UI label), seed (-1=random), width/height
+
+Output: PIL.Image. In UI, displayed and downloadable. Errors guide you to provide a token or fix model id.
+
+### Generate_Video (HF inference)
+Requires: HF_READ_TOKEN or HF_TOKEN
+
+Inputs:
+- prompt (str)
+- model_id (str): default Wan-AI/Wan2.2-T2V-A14B
+- negative_prompt (str)
+- steps (1–100), cfg_scale, seed, width/height, fps, duration (s)
+
+Output: Temporary MP4 file path; UI shows a playable/downloadable video.
+
+### Deep_Research (HF inference)
+Requires: HF_READ_TOKEN or HF_TOKEN
+
+Inputs:
+- summary (str): One or more sentences describing the research task.
+- query1..query5 (str) with max1..max5 (1–50). Total requested results across queries are capped at 50.
+
+Behavior:
+- Parallel DDG searches → fetch pages in budget → filter candidate sources with an LLM → synthesize a long, well-structured Markdown report and list of sources.
+
+Output: (report_md, fetched_links_text, report_file_path)
+
+### File_System (safe root)
+Root:
+- Defaults to `Nymbo-Tools/Filesystem` (or NYMBO_TOOLS_ROOT). Absolute paths disabled unless UNSAFE_ALLOW_ABS_PATHS=1.
+
+Actions:
+- list, read, write, append, edit, mkdir, move, copy, delete, info, help
+
+Key fields:
+- path, content (write/append/edit), dest_path (move/copy), recursive, show_hidden, max_entries, offset, max_chars, create_dirs, overwrite
+
+Edit format (SEARCH/REPLACE blocks):
+```
+<<<<<<< SEARCH
+[exact content to find]
+=======
+[new content to replace with]
+>>>>>>> REPLACE
+```
+- Multiple blocks can be included; each is applied in order
+- Search text must match exactly (whitespace, indentation)
+- Only the first occurrence of each search text is replaced
+
+Output:
+- Human-readable listings or JSON-like error strings with code/message/hint.
+
+### Shell_Command (same safe root)
+Inputs:
+- command (str): Single-string shell command (pipelines supported by the host shell).
+- workdir (str): Relative to the root.
+- timeout (s)
+
+Output:
+- Combined header + STDOUT/STDERR. Absolute paths disabled by default. Shell is detected automatically (PowerShell on Windows when available; bash/sh on POSIX).
+
+### Agent_Skills (Skill Discovery)
+Inputs:
+- action: "discover" | "info" | "resources" | "validate" | "search" | "help"
+- skill_name (str): Required for info/resources/validate.
+- resource_path (str): Specific file to read within a skill.
+- query (str): Search term for "search" action.
+- max_chars (int), offset (int)
+
+Output:
+- Detailed skill metadata, SKILL.md content, resource file content, or validation reports.
+
+### Agent_Terminal (Tool Chaining)
+Inputs:
+- input (str): Python source code to execute.
+    - Can call any other tool (e.g., `Web_Fetch(...)`, `File_System(...)`).
+    - Use `search_tools("query")` to find tools.
+    - Call a tool with no args to get its usage guide.
+
+Output:
+- Captured STDOUT validation of the script.
+
+### Obsidian_Vault (Read-only Note Access)
+Root:
+- Defaults to `Tools/Obsidian` (or OBSIDIAN_VAULT_ROOT).
+
+Inputs:
+- action: "list" | "read" | "info" | "search" | "help"
+- path (str): Relative to vault root (start with /).
+- query (str): For search action.
+- recursive (bool), show_hidden (bool), max_entries (int)
+- offset (int), max_chars (int)
+
+Output:
+- File listings, note content, or search results (with context).
+
+## Running on Hugging Face Spaces
+
+1) Duplicate the Space at https://huggingface.co/spaces/Nymbo/Tools.
+2) In Space Settings → Secrets, add HF_READ_TOKEN (and/or HF_TOKEN) for model access.
+3) Both the UI and MCP clients will list every tool. Image/Video/Deep Research still need a valid token when invoked.
+
+## Troubleshooting
+
+- Image/Video/Deep Research calls fail immediately:
+	- Provide HF_READ_TOKEN (and optionally HF_TOKEN). Restart the app/Space.
+- 401/403 when calling generation tools:
+	- Token missing/insufficient permissions. Ensure your token can read the chosen model.
+- Kokoro not found:
+	- Install kokoro>=0.9.4. CPU works; CUDA used if available. Torch may be skipped on Apple Silicon by design.
+- Windows PowerShell activation policy blocks venv activation:
+	- Run PowerShell as Admin and set a suitable execution policy for the current user (e.g., RemoteSigned), or manually run `python app.py` after installing dependencies.
+- File System or Shell path errors:
+	- Paths are relative to the tool root. Set NYMBO_TOOLS_ROOT to customize. Set UNSAFE_ALLOW_ABS_PATHS=1 only if you fully trust the environment.
+
+## License
+
 Apache-2.0 (see Space metadata). If you duplicate the Space or use these tools, ensure your usage complies with the licenses and terms of the underlying models and providers.

app.py

@@ -1,124 +1,118 @@
-from __future__ import annotations
-
-# Project by Nymbo
-
+from __future__ import annotations
+
+# Project by Nymbo
+
 import json
 import os
 import sys
-import threading
-import time
-import warnings
-from datetime import datetime, timedelta
-from typing import Any
-
-# Suppress asyncio event loop cleanup errors (Python 3.10 issue on HF Spaces)
-# These occur when event loops are garbage collected after file descriptors close
-def _patch_asyncio_event_loop_del():
-    """Patch BaseEventLoop.__del__ to suppress 'Invalid file descriptor: -1' errors."""
-    try:
-        import asyncio.base_events as base_events
-        original_del = getattr(base_events.BaseEventLoop, "__del__", None)
-        if original_del is None:
-            return
-        def patched_del(self):
-            try:
-                original_del(self)
-            except ValueError as e:
-                if "Invalid file descriptor" not in str(e):
-                    raise
-        base_events.BaseEventLoop.__del__ = patched_del
-    except Exception:
-        pass
-
-_patch_asyncio_event_loop_del()
-
-import gradio as gr
-
-
-class RateLimiter:
-    """Best-effort in-process rate limiter for HTTP-heavy tools."""
-
-    def __init__(self, requests_per_minute: int = 30) -> None:
-        self.requests_per_minute = requests_per_minute
-        self._requests: list[datetime] = []
-        self._lock = threading.Lock()
-
-    def acquire(self) -> None:
-        now = datetime.now()
-        with self._lock:
-            self._requests = [req for req in self._requests if now - req < timedelta(minutes=1)]
-            if len(self._requests) >= self.requests_per_minute:
-                wait_time = 60 - (now - self._requests[0]).total_seconds()
-                if wait_time > 0:
-                    time.sleep(max(1, wait_time))
-            self._requests.append(now)
-
-
-_search_rate_limiter = RateLimiter(requests_per_minute=20)
-_fetch_rate_limiter = RateLimiter(requests_per_minute=25)
-
-
-def _truncate_for_log(value: Any, limit: int = 500) -> str:
-    if not isinstance(value, str):
-        value = str(value)
-    if len(value) <= limit:
-        return value
-    return value[: limit - 1] + "…"
-
-
-def _serialize_input(val: Any) -> Any:
-    try:
-        if isinstance(val, (str, int, float, bool)) or val is None:
-            return val
-        if isinstance(val, (list, tuple)):
-            return [_serialize_input(v) for v in list(val)[:10]] + (["…"] if len(val) > 10 else [])
-        if isinstance(val, dict):
-            out: dict[str, Any] = {}
-            for i, (k, v) in enumerate(val.items()):
-                if i >= 12:
-                    out["…"] = "…"
-                    break
-                out[str(k)] = _serialize_input(v)
-            return out
-        return repr(val)[:120]
-    except Exception:
-        return "<unserializable>"
-
-
-def _log_call_start(func_name: str, **kwargs: Any) -> None:
-    try:
-        compact = {k: _serialize_input(v) for k, v in kwargs.items()}
-        # Use sys.__stdout__ to avoid capturing logs in redirected output
-        print(f"[TOOL CALL] {func_name} inputs: {json.dumps(compact, ensure_ascii=False)[:800]}", flush=True, file=sys.__stdout__)
-    except Exception as exc:
-        print(f"[TOOL CALL] {func_name} (failed to log inputs: {exc})", flush=True, file=sys.__stdout__)
-
-
-def _log_call_end(func_name: str, output_desc: str) -> None:
-    try:
-        # Use sys.__stdout__ to avoid capturing logs in redirected output
-        print(f"[TOOL RESULT] {func_name} output: {output_desc}", flush=True, file=sys.__stdout__)
-    except Exception as exc:
-        print(f"[TOOL RESULT] {func_name} (failed to log output: {exc})", flush=True, file=sys.__stdout__)
-
-# Ensure Tools modules can import 'app' when this file is executed as a script
-# (their code does `from app import ...`).
-sys.modules.setdefault("app", sys.modules[__name__])
-
+import threading
+import time
+import warnings
+from datetime import datetime, timedelta
+from typing import Any
+
+# Suppress asyncio event loop cleanup errors (Python 3.10 issue on HF Spaces)
+# These occur when event loops are garbage collected after file descriptors close
+def _patch_asyncio_event_loop_del():
+    """Patch BaseEventLoop.__del__ to suppress 'Invalid file descriptor: -1' errors."""
+    try:
+        import asyncio.base_events as base_events
+        original_del = getattr(base_events.BaseEventLoop, "__del__", None)
+        if original_del is None:
+            return
+        def patched_del(self):
+            try:
+                original_del(self)
+            except ValueError as e:
+                if "Invalid file descriptor" not in str(e):
+                    raise
+        base_events.BaseEventLoop.__del__ = patched_del
+    except Exception:
+        pass
+
+_patch_asyncio_event_loop_del()
+
+import gradio as gr
+
+
+class RateLimiter:
+    """Best-effort in-process rate limiter for HTTP-heavy tools."""
+
+    def __init__(self, requests_per_minute: int = 30) -> None:
+        self.requests_per_minute = requests_per_minute
+        self._requests: list[datetime] = []
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        now = datetime.now()
+        with self._lock:
+            self._requests = [req for req in self._requests if now - req < timedelta(minutes=1)]
+            if len(self._requests) >= self.requests_per_minute:
+                wait_time = 60 - (now - self._requests[0]).total_seconds()
+                if wait_time > 0:
+                    time.sleep(max(1, wait_time))
+            self._requests.append(now)
+
+
+_search_rate_limiter = RateLimiter(requests_per_minute=20)
+_fetch_rate_limiter = RateLimiter(requests_per_minute=25)
+
+
+def _truncate_for_log(value: Any, limit: int = 500) -> str:
+    if not isinstance(value, str):
+        value = str(value)
+    if len(value) <= limit:
+        return value
+    return value[: limit - 1] + "…"
+
+
+def _serialize_input(val: Any) -> Any:
+    try:
+        if isinstance(val, (str, int, float, bool)) or val is None:
+            return val
+        if isinstance(val, (list, tuple)):
+            return [_serialize_input(v) for v in list(val)[:10]] + (["…"] if len(val) > 10 else [])
+        if isinstance(val, dict):
+            out: dict[str, Any] = {}
+            for i, (k, v) in enumerate(val.items()):
+                if i >= 12:
+                    out["…"] = "…"
+                    break
+                out[str(k)] = _serialize_input(v)
+            return out
+        return repr(val)[:120]
+    except Exception:
+        return "<unserializable>"
+
+
+def _log_call_start(func_name: str, **kwargs: Any) -> None:
+    try:
+        compact = {k: _serialize_input(v) for k, v in kwargs.items()}
+        # Use sys.__stdout__ to avoid capturing logs in redirected output
+        print(f"[TOOL CALL] {func_name} inputs: {json.dumps(compact, ensure_ascii=False)[:800]}", flush=True, file=sys.__stdout__)
+    except Exception as exc:
+        print(f"[TOOL CALL] {func_name} (failed to log inputs: {exc})", flush=True, file=sys.__stdout__)
+
+
+def _log_call_end(func_name: str, output_desc: str) -> None:
+    try:
+        # Use sys.__stdout__ to avoid capturing logs in redirected output
+        print(f"[TOOL RESULT] {func_name} output: {output_desc}", flush=True, file=sys.__stdout__)
+    except Exception as exc:
+        print(f"[TOOL RESULT] {func_name} (failed to log output: {exc})", flush=True, file=sys.__stdout__)
+
+# Ensure Tools modules can import 'app' when this file is executed as a script
+# (their code does `from app import ...`).
+sys.modules.setdefault("app", sys.modules[__name__])
+
 # Import per-tool interface builders from the Tools package
-from Modules.Web_Fetch import build_interface as build_fetch_interface
 from Modules.Web_Search import build_interface as build_search_interface
+from Modules.ScrapeGraphAI import build_interface as build_scrapegraph_interface
 from Modules.Agent_Terminal import build_interface as build_agent_terminal_interface
 from Modules.Code_Interpreter import build_interface as build_code_interface
 from Modules.Memory_Manager import build_interface as build_memory_interface
-from Modules.Generate_Speech import build_interface as build_speech_interface
 from Modules.Generate_Image import build_interface as build_image_interface
-from Modules.Generate_Video import build_interface as build_video_interface
-from Modules.Deep_Research import build_interface as build_research_interface
-from Modules.File_System import build_interface as build_fs_interface
-from Modules.Obsidian_Vault import build_interface as build_obsidian_interface
 from Modules.Shell_Command import build_interface as build_shell_interface
-from Modules.Agent_Skills import build_interface as build_skills_interface
 
 # Optional environment flags used to conditionally show API schemas (unchanged behavior)
 HF_IMAGE_TOKEN = bool(os.getenv("HF_READ_TOKEN"))
@@ -131,96 +125,78 @@ with open(_css_path, "r", encoding="utf-8") as _css_file:
     CSS_STYLES = _css_file.read()
 
 # Build each tab interface using modular builders
-fetch_interface = build_fetch_interface()
 web_search_interface = build_search_interface()
+scrapegraph_interface = build_scrapegraph_interface()
 agent_terminal_interface = build_agent_terminal_interface()
 code_interface = build_code_interface()
 memory_interface = build_memory_interface()
-kokoro_interface = build_speech_interface()
 image_generation_interface = build_image_interface()
-video_generation_interface = build_video_interface()
-deep_research_interface = build_research_interface()
-fs_interface = build_fs_interface()
 shell_interface = build_shell_interface()
-obsidian_interface = build_obsidian_interface()
-skills_interface = build_skills_interface()
 
 _interfaces = [
     agent_terminal_interface,
-    skills_interface,
-    fetch_interface,
     web_search_interface,
+    scrapegraph_interface,
     code_interface,
     shell_interface,
-    fs_interface,
-    obsidian_interface,
     memory_interface,
-    kokoro_interface,
     image_generation_interface,
-    video_generation_interface,
-    deep_research_interface,
 ]
 _tab_names = [
     "Agent Terminal",
-    "Agent Skills",
-    "Web Fetch",
     "Web Search",
+    "ScrapeGraphAI",
     "Code Interpreter",
     "Shell Command",
-    "File System",
-    "Obsidian Vault",
     "Memory Manager",
-    "Generate Speech",
     "Generate Image",
-    "Generate Video",
-    "Deep Research",
 ]
-
-with gr.Blocks(title="Nymbo/Tools MCP") as demo:
-
-    with gr.Sidebar(width=300, elem_classes="app-sidebar"):
-        gr.Markdown(
-            "## Nymbo/Tools MCP\n"
-            "<p style='font-size: 0.7rem; opacity: 0.85; margin-top: 2px; margin-bottom: 6px;'>General purpose tools useful for any agent.</p>\n"
-            "<a href='https://www.nymbo.net/nymbot' target='_blank' style='font-size: 0.7rem; display: block;'>Test with Nymbot</a>"
-        )
-        
-        with gr.Accordion("Information", open=False):
-            gr.HTML(
-                """
-                <div class="info-accordion">
-                    <div class="info-grid" style="grid-template-columns: 1fr;">
-                        <section class="info-card">
-                            <div class="info-card__body">
-                                <h3>Connecting from an MCP Client</h3>
-                                <p>
-                                    This Space also runs as a Model Context Protocol (MCP) server. Point your client to:
-                                    <br/>
-                                    <code>https://nymbo-tools.hf.space/gradio_api/mcp/</code>
-                                </p>
-                                <p>Example client configuration:</p>
-                                <pre><code class="language-json">{
-  "mcpServers": {
-    "nymbo-tools": {
-      "url": "https://nymbo-tools.hf.space/gradio_api/mcp/"
-    }
-  }
-}</code></pre>
-                                <p>Run the following commands in sequence to run the server locally:</p>
-                                <pre><code>git clone https://huggingface.co/spaces/Nymbo/Tools
-cd Tools
-python -m venv env
-source env/bin/activate
-pip install -r requirements.txt
-python app.py</code></pre>
-                            </div>
-                        </section>
-
+
+with gr.Blocks(title="Nymbo/Tools MCP") as demo:
+
+    with gr.Sidebar(width=300, elem_classes="app-sidebar"):
+        gr.Markdown(
+            "## Nymbo/Tools MCP\n"
+            "<p style='font-size: 0.7rem; opacity: 0.85; margin-top: 2px; margin-bottom: 6px;'>General purpose tools useful for any agent.</p>\n"
+            "<a href='https://www.nymbo.net/nymbot' target='_blank' style='font-size: 0.7rem; display: block;'>Test with Nymbot</a>"
+        )
+        
+        with gr.Accordion("Information", open=False):
+            gr.HTML(
+                """
+                <div class="info-accordion">
+                    <div class="info-grid" style="grid-template-columns: 1fr;">
+                        <section class="info-card">
+                            <div class="info-card__body">
+                                <h3>Connecting from an MCP Client</h3>
+                                <p>
+                                    This Space also runs as a Model Context Protocol (MCP) server. Point your client to:
+                                    <br/>
+                                    <code>https://nymbo-tools.hf.space/gradio_api/mcp/</code>
+                                </p>
+                                <p>Example client configuration:</p>
+                                <pre><code class="language-json">{
+  "mcpServers": {
+    "nymbo-tools": {
+      "url": "https://nymbo-tools.hf.space/gradio_api/mcp/"
+    }
+  }
+}</code></pre>
+                                <p>Run the following commands in sequence to run the server locally:</p>
+                                <pre><code>git clone https://huggingface.co/spaces/Nymbo/Tools
+cd Tools
+python -m venv env
+source env/bin/activate
+pip install -r requirements.txt
+python app.py</code></pre>
+                            </div>
+                        </section>
+
                         <section class="info-card">
                             <div class="info-card__body">
-                                <h3>Enable Image Gen, Video Gen, and Deep Research</h3>
+                                <h3>Enable Image Gen</h3>
                                 <p>
-                                    The <code>Generate_Image</code>, <code>Generate_Video</code>, and <code>Deep_Research</code> tools require a
+                                    The <code>Generate_Image</code> tool requires a
                                     <code>HF_READ_TOKEN</code> set as a secret or environment variable.
                                 </p>
                                 <ul class="info-list">
@@ -228,124 +204,66 @@ python app.py</code></pre>
                                     <li>Or run locally with <code>HF_READ_TOKEN</code> in your environment.</li>
                                 </ul>
                                 <div class="info-hint">
-                                    MCP clients can see these tools even without tokens, but calls will fail until a valid token is provided.
+                                    The <code>ScrapeGraphAI</code> tool also requires <code>MISTRAL_API_KEY</code> for extraction actions.
                                 </div>
                             </div>
                         </section>
-
+
                         <section class="info-card">
                             <div class="info-card__body">
-                                <h3>Persistent Memories and Files</h3>
+                                <h3>Persistent Memories</h3>
                                 <p>
-                                    In this public demo, memories and files created with the <code>Memory_Manager</code> and <code>File_System</code> are stored in the Space's running container and are cleared when the Space restarts. Content is visible to everyone—avoid personal data.
+                                    In this public demo, memories created with the <code>Memory_Manager</code> tool are stored in the Space's running container and are cleared when the Space restarts. Content is visible to everyone—avoid personal data.
                                 </p>
                                 <p>
-                                    When running locally, memories are saved to <code>memories.json</code> at the repo root for privacy, and files are saved to the <code>Tools/Filesystem</code> directory on disk.
+                                    When running locally, memories are saved to <code>memories.json</code> at the repo root for privacy.
                                 </p>
                             </div>
                         </section>
-
+
                         <section class="info-card">
                             <div class="info-card__body">
-                                <h3>Tool Notes &amp; Kokoro Voice Legend</h3>
+                                <h3>Tool Notes</h3>
                                 <p><strong>No authentication required for:</strong></p>
                                 <ul class="info-list">
-                                    <li><code>Web_Fetch</code></li>
                                     <li><code>Web_Search</code></li>
                                     <li><code>Agent_Terminal</code></li>
                                     <li><code>Code_Interpreter</code></li>
                                     <li><code>Memory_Manager</code></li>
-                                    <li><code>Generate_Speech</code></li>
-                                    <li><code>File_System</code></li>
                                     <li><code>Shell_Command</code></li>
-                                    <li><code>Agent_Skills</code></li>
                                 </ul>
-                                <p><strong>Kokoro voice prefixes</strong></p>
-                                <table style="width:100%; border-collapse:collapse; font-size:0.9em; margin-top:8px;">
-                                    <thead>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.15);">
-                                            <th style="padding:6px 8px; text-align:left;">Accent</th>
-                                            <th style="padding:6px 8px; text-align:center;">Female</th>
-                                            <th style="padding:6px 8px; text-align:center;">Male</th>
-                                        </tr>
-                                    </thead>
-                                    <tbody>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">American</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>af</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>am</code></td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">British</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>bf</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>bm</code></td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">European</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>ef</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>em</code></td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">French</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>ff</code></td>
-                                            <td style="padding:6px 8px; text-align:center;">—</td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">Hindi</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>hf</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>hm</code></td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">Italian</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>if</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>im</code></td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">Japanese</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>jf</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>jm</code></td>
-                                        </tr>
-                                        <tr style="border-bottom:1px solid rgba(255,255,255,0.08);">
-                                            <td style="padding:6px 8px; font-weight:600;">Portuguese</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>pf</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>pm</code></td>
-                                        </tr>
-                                        <tr>
-                                            <td style="padding:6px 8px; font-weight:600;">Chinese</td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>zf</code></td>
-                                            <td style="padding:6px 8px; text-align:center;"><code>zm</code></td>
-                                        </tr>
-                                    </tbody>
-                                </table>
+                                <p>
+                                    <code>ScrapeGraphAI</code> is available in this Space, but extraction actions require <code>MISTRAL_API_KEY</code>. The <code>render_markdown</code> action does not require Mistral.
+                                </p>
                             </div>
                         </section>
-                    </div>
-                </div>
-                """
-            )
-        
-        gr.Markdown("### Tools")
-        tool_selector = gr.Radio(
-            choices=_tab_names,
-            value=_tab_names[0],
-            label="Select Tool",
-            show_label=False,
-            container=False,
-            elem_classes="sidebar-nav"
-        )
-
-    with gr.Tabs(elem_classes="hidden-tabs", selected=_tab_names[0]) as tool_tabs:
-        for name, interface in zip(_tab_names, _interfaces):
-            with gr.TabItem(label=name, id=name, elem_id=f"tab-{name}"):
-                interface.render()
-
-    # Use JavaScript to click the hidden tab button when the radio selection changes
-    tool_selector.change(
-        fn=None,
-        inputs=tool_selector,
-        outputs=None,
-        js="(selected_tool) => { const buttons = document.querySelectorAll('.hidden-tabs button'); buttons.forEach(btn => { if (btn.innerText.trim() === selected_tool) { btn.click(); } }); }"
-    )
-
-if __name__ == "__main__":
-    demo.launch(mcp_server=True, theme="Nymbo/Nymbo_Theme", css=CSS_STYLES, ssr_mode=False)
+                    </div>
+                </div>
+                """
+            )
+        
+        gr.Markdown("### Tools")
+        tool_selector = gr.Radio(
+            choices=_tab_names,
+            value=_tab_names[0],
+            label="Select Tool",
+            show_label=False,
+            container=False,
+            elem_classes="sidebar-nav"
+        )
+
+    with gr.Tabs(elem_classes="hidden-tabs", selected=_tab_names[0]) as tool_tabs:
+        for name, interface in zip(_tab_names, _interfaces):
+            with gr.TabItem(label=name, id=name, elem_id=f"tab-{name}"):
+                interface.render()
+
+    # Use JavaScript to click the hidden tab button when the radio selection changes
+    tool_selector.change(
+        fn=None,
+        inputs=tool_selector,
+        outputs=None,
+        js="(selected_tool) => { const buttons = document.querySelectorAll('.hidden-tabs button'); buttons.forEach(btn => { if (btn.innerText.trim() === selected_tool) { btn.click(); } }); }"
+    )
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True, theme="Nymbo/Nymbo_Theme", css=CSS_STYLES, ssr_mode=False)

memories.json

@@ -1,20 +1,20 @@
-[
-  {
-    "id": "c8e3965d-270c-4baf-836f-33c6ed57f527",
-    "text": "The user's personal website is driven by Markdown and Vue, hosted on Vercel.",
-    "timestamp": "2025-09-06 02:21:17",
-    "tags": "website,markdown,vue,vercel"
-  },
-  {
-    "id": "17806073-cb86-472f-9b39-c1aaaf3ac058",
-    "text": "The user lives in New York City.",
-    "timestamp": "2025-09-06 17:07:27",
-    "tags": "location,address"
-  },
-  {
-    "id": "86e9f249-b43d-4aaa-bca0-b55fcb0c03be",
-    "text": "The user has a pet Russian tortoise who is 8 years old.",
-    "timestamp": "2025-09-06 02:20:59",
-    "tags": "pet,tortoise,animals"
-  }
+[
+  {
+    "id": "c8e3965d-270c-4baf-836f-33c6ed57f527",
+    "text": "The user's personal website is driven by Markdown and Vue, hosted on Vercel.",
+    "timestamp": "2025-09-06 02:21:17",
+    "tags": "website,markdown,vue,vercel"
+  },
+  {
+    "id": "17806073-cb86-472f-9b39-c1aaaf3ac058",
+    "text": "The user lives in New York City.",
+    "timestamp": "2025-09-06 17:07:27",
+    "tags": "location,address"
+  },
+  {
+    "id": "86e9f249-b43d-4aaa-bca0-b55fcb0c03be",
+    "text": "The user has a pet Russian tortoise who is 8 years old.",
+    "timestamp": "2025-09-06 02:20:59",
+    "tags": "pet,tortoise,animals"
+  }
 ]

requirements.txt

@@ -1,12 +1,14 @@
-gradio[mcp]==6.2.0
-requests
-beautifulsoup4
-lxml
-readability-lxml
-ddgs
-kokoro>=0.7.16
-numpy
-torch; platform_system != "Darwin" or platform_machine != "arm64"
-Pillow
-huggingface_hub>=0.30.0
-markdownify
+gradio[mcp]==6.2.0
+requests
+beautifulsoup4
+lxml
+readability-lxml
+ddgs
+kokoro>=0.7.16
+numpy
+torch; platform_system != "Darwin" or platform_machine != "arm64"
+Pillow
+huggingface_hub>=0.30.0
+markdownify
+langchain-mistralai>=1.1.1
+scrapegraphai>=1.75.1

styles.css

@@ -1,308 +1,308 @@
-/* Style only the top-level app title to avoid affecting headings elsewhere */
-.app-title {
-    text-align: center;
-    /* Ensure main title appears first, then our two subtitle lines */
-    display: grid;
-    justify-items: center;
-}
-.app-title::after {
-    grid-row: 2;
-    content: "General purpose tools useful for any agent.";
-    display: block;
-    font-size: 1rem;
-    font-weight: 400;
-    opacity: 0.9;
-    margin-top: 2px;
-    white-space: pre-wrap;
-}
-
-/* Sidebar Container */
-.app-sidebar {
-    background: var(--body-background-fill) !important;
-    border-right: 1px solid rgba(255, 255, 255, 0.08) !important;
-}
-@media (prefers-color-scheme: light) {
-    .app-sidebar {
-        border-right: 1px solid rgba(0, 0, 0, 0.08) !important;
-    }
-}
-
-/* Historical safeguard: if any h1 appears inside tabs, don't attach pseudo content */
-.gradio-container [role="tabpanel"] h1::before,
-.gradio-container [role="tabpanel"] h1::after {
-    content: none !important;
-}
-
-/* Information accordion - modern info cards */
-.info-accordion { 
-    margin: 8px 0 2px;
-}
-.info-grid {
-    display: grid;
-    gap: 12px;
-    /* Force a 2x2 layout on medium+ screens */
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-    align-items: stretch;
-}
-/* On narrow screens, stack into a single column */
-@media (max-width: 800px) {
-    .info-grid {
-        grid-template-columns: 1fr;
-    }
-}
-.info-card {
-    display: flex;
-    gap: 14px;
-    padding: 14px 16px;
-    border: 1px solid rgba(255, 255, 255, 0.08);
-    background: linear-gradient(180deg, rgba(255,255,255,0.05), rgba(255,255,255,0.03));
-    border-radius: 12px;
-    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
-    position: relative;
-    overflow: hidden;
-    -webkit-backdrop-filter: blur(2px);
-    backdrop-filter: blur(2px);
-}
-.info-card::before {
-    content: "";
-    position: absolute;
-    inset: 0;
-    border-radius: 12px;
-    pointer-events: none;
-    background: linear-gradient(90deg, rgba(99,102,241,0.06), rgba(59,130,246,0.05));
-}
-.info-card__icon {
-    font-size: 24px;
-    flex: 0 0 28px;
-    line-height: 1;
-    filter: saturate(1.1);
-}
-.info-card__body {
-    min-width: 0;
-}
-.info-card__body h3 {
-    margin: 0 0 6px;
-    font-size: 1.05rem;
-}
-.info-card__body p {
-    margin: 6px 0;
-    opacity: 0.95;
-}
-/* Readable code blocks inside info cards */
-.info-card pre {
-    margin: 8px 0;
-    padding: 10px 12px;
-    background: rgba(20, 20, 30, 0.55);
-    border: 1px solid rgba(255, 255, 255, 0.08);
-    border-radius: 10px;
-    overflow-x: auto;
-    white-space: pre;
-}
-.info-card code {
-    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
-    font-size: 0.95em;
-}
-.info-card pre code {
-    display: block;
-}
-.info-card p {
-    word-wrap: break-word;
-    overflow-wrap: break-word;
-}
-.info-card p code {
-    word-break: break-all;
-}
-.info-list {
-    margin: 6px 0 0 18px;
-    padding: 0;
-}
-.info-hint {
-    margin-top: 8px;
-    font-size: 0.9em;
-    opacity: 0.9;
-}
-
-/* Light theme adjustments */
-@media (prefers-color-scheme: light) {
-    .info-card {
-        border-color: rgba(0, 0, 0, 0.08);
-        background: linear-gradient(180deg, rgba(255,255,255,0.95), rgba(255,255,255,0.9));
-    }
-    .info-card::before {
-        background: linear-gradient(90deg, rgba(99,102,241,0.08), rgba(59,130,246,0.06));
-    }
-    .info-card pre {
-        background: rgba(245, 246, 250, 0.95);
-        border-color: rgba(0, 0, 0, 0.08);
-    }
-}
-
-/* Sidebar Navigation - styled like the previous tabs */
-.sidebar-nav {
-    background: transparent !important;
-    border: none !important;
-    padding: 0 !important;
-}
-.sidebar-nav .form {
-    gap: 8px !important;
-    display: flex !important;
-    flex-direction: column !important;
-    border: none !important;
-    background: transparent !important;
-}
-.sidebar-nav label {
-    display: flex !important;
-    align-items: center !important;
-    padding: 10px 12px !important;
-    border-radius: 10px !important;
-    border: 1px solid rgba(255, 255, 255, 0.08) !important;
-    background: linear-gradient(180deg, rgba(255,255,255,0.05), rgba(255,255,255,0.03)) !important;
-    transition: background .2s ease, border-color .2s ease, box-shadow .2s ease, transform .06s ease !important;
-    cursor: pointer !important;
-    margin-bottom: 0 !important;
-    width: 100% !important;
-    justify-content: flex-start !important;
-    text-align: left !important;
-}
-.sidebar-nav label:hover {
-    border-color: rgba(99,102,241,0.28) !important;
-    background: linear-gradient(180deg, rgba(99,102,241,0.10), rgba(59,130,246,0.08)) !important;
-}
-/* Selected state - Gradio adds 'selected' class to the label in some versions, or we check input:checked */
-.sidebar-nav label.selected {
-    border-color: rgba(99,102,241,0.35) !important;
-    box-shadow: inset 0 0 0 1px rgba(99,102,241,0.25), 0 1px 2px rgba(0,0,0,0.25) !important;
-    background: linear-gradient(180deg, rgba(99,102,241,0.18), rgba(59,130,246,0.14)) !important;
-    color: rgba(255, 255, 255, 0.95) !important;
-}
-
-/* Light theme adjustments for sidebar */
-@media (prefers-color-scheme: light) {
-    .sidebar-nav label {
-        border-color: rgba(0, 0, 0, 0.08) !important;
-        background: linear-gradient(180deg, rgba(255,255,255,0.95), rgba(255,255,255,0.90)) !important;
-        color: rgba(0, 0, 0, 0.85) !important;
-    }
-    .sidebar-nav label:hover {
-        border-color: rgba(99,102,241,0.25) !important;
-        background: linear-gradient(180deg, rgba(99,102,241,0.08), rgba(59,130,246,0.06)) !important;
-    }
-    .sidebar-nav label.selected {
-        border-color: rgba(99,102,241,0.35) !important;
-        background: linear-gradient(180deg, rgba(99,102,241,0.16), rgba(59,130,246,0.12)) !important;
-        color: rgba(0, 0, 0, 0.85) !important;
-    }
-}
-
-/* Hide scrollbars/arrows that can appear on the description block in some browsers */
-/* stylelint-disable compat-api/css */
-article.prose, .prose, .gr-prose {
-    overflow: visible !important;
-    max-height: none !important;
-    -ms-overflow-style: none !important; /* IE/Edge */
-    scrollbar-width: none !important; /* Firefox */
-}
-/* stylelint-enable compat-api/css */
-article.prose::-webkit-scrollbar,
-.prose::-webkit-scrollbar,
-.gr-prose::-webkit-scrollbar {
-    display: none !important;            /* Chrome/Safari */
-}
-
-/* Fix for white background on single-line inputs in dark mode */
-.gradio-container input[type="text"], 
-.gradio-container input[type="password"], 
-.gradio-container input[type="number"], 
-.gradio-container input[type="email"] {
-    background-color: var(--input-background-fill) !important;
-    color: var(--body-text-color) !important;
-}
-
-/* Custom glossy purple styling for primary action buttons */
-.gradio-container button.primary {
-    border: 1px solid rgba(99, 102, 241, 0.35) !important;
-    background: linear-gradient(180deg, rgba(99, 102, 241, 0.25), rgba(59, 130, 246, 0.20)) !important;
-    box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.12), 0 2px 4px rgba(0, 0, 0, 0.15) !important;
-    color: rgba(255, 255, 255, 0.95) !important;
-    transition: background .2s ease, border-color .2s ease, box-shadow .2s ease, transform .06s ease !important;
-}
-.gradio-container button.primary:hover {
-    border-color: rgba(99, 102, 241, 0.5) !important;
-    background: linear-gradient(180deg, rgba(99, 102, 241, 0.35), rgba(59, 130, 246, 0.28)) !important;
-    box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 3px 6px rgba(0, 0, 0, 0.2) !important;
-}
-.gradio-container button.primary:active {
-    transform: scale(0.98) !important;
-    box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.2), 0 1px 2px rgba(0, 0, 0, 0.1) !important;
-}
-@media (prefers-color-scheme: light) {
-    .gradio-container button.primary {
-        border-color: rgba(99, 102, 241, 0.4) !important;
-        background: linear-gradient(180deg, rgba(99, 102, 241, 0.85), rgba(79, 70, 229, 0.75)) !important;
-        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25), 0 2px 4px rgba(0, 0, 0, 0.12) !important;
-        color: rgba(255, 255, 255, 0.98) !important;
-    }
-    .gradio-container button.primary:hover {
-        background: linear-gradient(180deg, rgba(99, 102, 241, 0.95), rgba(79, 70, 229, 0.85)) !important;
-        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.3), 0 3px 6px rgba(0, 0, 0, 0.15) !important;
-    }
-}
-
-/* Hide the actual tabs since we use the sidebar to control them */
-.hidden-tabs .tab-nav,
-.hidden-tabs [role="tablist"] {
-    display: none !important;
-}
-/* Hide the entire first row of the tabs container (contains tab buttons + overflow) */
-.hidden-tabs > div:first-child {
-    display: none !important;
-}
-/* Ensure audio component buttons remain visible - they're inside tab panels, not the first row */
-.hidden-tabs [role="tabpanel"] button {
-    display: inline-flex !important;
-}
-
-/* Custom scrollbar styling - Progressive enhancement, falls back to default scrollbars */
-/* stylelint-disable compat-api/css */
-* {
-    scrollbar-width: thin;
-    scrollbar-color: rgba(61, 212, 159, 0.4) rgba(255, 255, 255, 0.05);
-}
-*::-webkit-scrollbar {
-    width: 8px;
-    height: 8px;
-}
-*::-webkit-scrollbar-track {
-    background: rgba(255, 255, 255, 0.05);
-    border-radius: 4px;
-}
-*::-webkit-scrollbar-thumb {
-    background: linear-gradient(180deg, rgba(61, 212, 159, 0.5), rgba(17, 186, 136, 0.4));
-    border-radius: 4px;
-    border: 1px solid rgba(119, 247, 209, 0.2);
-}
-*::-webkit-scrollbar-thumb:hover {
-    background: linear-gradient(180deg, rgba(85, 250, 192, 0.7), rgba(65, 184, 131, 0.6));
-}
-*::-webkit-scrollbar-corner {
-    background: rgba(255, 255, 255, 0.05);
-}
-@media (prefers-color-scheme: light) {
-    * {
-        scrollbar-color: rgba(61, 212, 159, 0.4) rgba(0, 0, 0, 0.05);
-    }
-    *::-webkit-scrollbar-track {
-        background: rgba(0, 0, 0, 0.05);
-    }
-    *::-webkit-scrollbar-thumb {
-        background: linear-gradient(180deg, rgba(61, 212, 159, 0.5), rgba(17, 186, 136, 0.4));
-        border-color: rgba(0, 0, 0, 0.1);
-    }
-    *::-webkit-scrollbar-thumb:hover {
-        background: linear-gradient(180deg, rgba(85, 250, 192, 0.7), rgba(65, 184, 131, 0.6));
-    }
-    *::-webkit-scrollbar-corner {
-        background: rgba(0, 0, 0, 0.05);
-    }
-}
+/* Style only the top-level app title to avoid affecting headings elsewhere */
+.app-title {
+    text-align: center;
+    /* Ensure main title appears first, then our two subtitle lines */
+    display: grid;
+    justify-items: center;
+}
+.app-title::after {
+    grid-row: 2;
+    content: "General purpose tools useful for any agent.";
+    display: block;
+    font-size: 1rem;
+    font-weight: 400;
+    opacity: 0.9;
+    margin-top: 2px;
+    white-space: pre-wrap;
+}
+
+/* Sidebar Container */
+.app-sidebar {
+    background: var(--body-background-fill) !important;
+    border-right: 1px solid rgba(255, 255, 255, 0.08) !important;
+}
+@media (prefers-color-scheme: light) {
+    .app-sidebar {
+        border-right: 1px solid rgba(0, 0, 0, 0.08) !important;
+    }
+}
+
+/* Historical safeguard: if any h1 appears inside tabs, don't attach pseudo content */
+.gradio-container [role="tabpanel"] h1::before,
+.gradio-container [role="tabpanel"] h1::after {
+    content: none !important;
+}
+
+/* Information accordion - modern info cards */
+.info-accordion { 
+    margin: 8px 0 2px;
+}
+.info-grid {
+    display: grid;
+    gap: 12px;
+    /* Force a 2x2 layout on medium+ screens */
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: stretch;
+}
+/* On narrow screens, stack into a single column */
+@media (max-width: 800px) {
+    .info-grid {
+        grid-template-columns: 1fr;
+    }
+}
+.info-card {
+    display: flex;
+    gap: 14px;
+    padding: 14px 16px;
+    border: 1px solid rgba(255, 255, 255, 0.08);
+    background: linear-gradient(180deg, rgba(255,255,255,0.05), rgba(255,255,255,0.03));
+    border-radius: 12px;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
+    position: relative;
+    overflow: hidden;
+    -webkit-backdrop-filter: blur(2px);
+    backdrop-filter: blur(2px);
+}
+.info-card::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    border-radius: 12px;
+    pointer-events: none;
+    background: linear-gradient(90deg, rgba(99,102,241,0.06), rgba(59,130,246,0.05));
+}
+.info-card__icon {
+    font-size: 24px;
+    flex: 0 0 28px;
+    line-height: 1;
+    filter: saturate(1.1);
+}
+.info-card__body {
+    min-width: 0;
+}
+.info-card__body h3 {
+    margin: 0 0 6px;
+    font-size: 1.05rem;
+}
+.info-card__body p {
+    margin: 6px 0;
+    opacity: 0.95;
+}
+/* Readable code blocks inside info cards */
+.info-card pre {
+    margin: 8px 0;
+    padding: 10px 12px;
+    background: rgba(20, 20, 30, 0.55);
+    border: 1px solid rgba(255, 255, 255, 0.08);
+    border-radius: 10px;
+    overflow-x: auto;
+    white-space: pre;
+}
+.info-card code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+    font-size: 0.95em;
+}
+.info-card pre code {
+    display: block;
+}
+.info-card p {
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+}
+.info-card p code {
+    word-break: break-all;
+}
+.info-list {
+    margin: 6px 0 0 18px;
+    padding: 0;
+}
+.info-hint {
+    margin-top: 8px;
+    font-size: 0.9em;
+    opacity: 0.9;
+}
+
+/* Light theme adjustments */
+@media (prefers-color-scheme: light) {
+    .info-card {
+        border-color: rgba(0, 0, 0, 0.08);
+        background: linear-gradient(180deg, rgba(255,255,255,0.95), rgba(255,255,255,0.9));
+    }
+    .info-card::before {
+        background: linear-gradient(90deg, rgba(99,102,241,0.08), rgba(59,130,246,0.06));
+    }
+    .info-card pre {
+        background: rgba(245, 246, 250, 0.95);
+        border-color: rgba(0, 0, 0, 0.08);
+    }
+}
+
+/* Sidebar Navigation - styled like the previous tabs */
+.sidebar-nav {
+    background: transparent !important;
+    border: none !important;
+    padding: 0 !important;
+}
+.sidebar-nav .form {
+    gap: 8px !important;
+    display: flex !important;
+    flex-direction: column !important;
+    border: none !important;
+    background: transparent !important;
+}
+.sidebar-nav label {
+    display: flex !important;
+    align-items: center !important;
+    padding: 10px 12px !important;
+    border-radius: 10px !important;
+    border: 1px solid rgba(255, 255, 255, 0.08) !important;
+    background: linear-gradient(180deg, rgba(255,255,255,0.05), rgba(255,255,255,0.03)) !important;
+    transition: background .2s ease, border-color .2s ease, box-shadow .2s ease, transform .06s ease !important;
+    cursor: pointer !important;
+    margin-bottom: 0 !important;
+    width: 100% !important;
+    justify-content: flex-start !important;
+    text-align: left !important;
+}
+.sidebar-nav label:hover {
+    border-color: rgba(99,102,241,0.28) !important;
+    background: linear-gradient(180deg, rgba(99,102,241,0.10), rgba(59,130,246,0.08)) !important;
+}
+/* Selected state - Gradio adds 'selected' class to the label in some versions, or we check input:checked */
+.sidebar-nav label.selected {
+    border-color: rgba(99,102,241,0.35) !important;
+    box-shadow: inset 0 0 0 1px rgba(99,102,241,0.25), 0 1px 2px rgba(0,0,0,0.25) !important;
+    background: linear-gradient(180deg, rgba(99,102,241,0.18), rgba(59,130,246,0.14)) !important;
+    color: rgba(255, 255, 255, 0.95) !important;
+}
+
+/* Light theme adjustments for sidebar */
+@media (prefers-color-scheme: light) {
+    .sidebar-nav label {
+        border-color: rgba(0, 0, 0, 0.08) !important;
+        background: linear-gradient(180deg, rgba(255,255,255,0.95), rgba(255,255,255,0.90)) !important;
+        color: rgba(0, 0, 0, 0.85) !important;
+    }
+    .sidebar-nav label:hover {
+        border-color: rgba(99,102,241,0.25) !important;
+        background: linear-gradient(180deg, rgba(99,102,241,0.08), rgba(59,130,246,0.06)) !important;
+    }
+    .sidebar-nav label.selected {
+        border-color: rgba(99,102,241,0.35) !important;
+        background: linear-gradient(180deg, rgba(99,102,241,0.16), rgba(59,130,246,0.12)) !important;
+        color: rgba(0, 0, 0, 0.85) !important;
+    }
+}
+
+/* Hide scrollbars/arrows that can appear on the description block in some browsers */
+/* stylelint-disable compat-api/css */
+article.prose, .prose, .gr-prose {
+    overflow: visible !important;
+    max-height: none !important;
+    -ms-overflow-style: none !important; /* IE/Edge */
+    scrollbar-width: none !important; /* Firefox */
+}
+/* stylelint-enable compat-api/css */
+article.prose::-webkit-scrollbar,
+.prose::-webkit-scrollbar,
+.gr-prose::-webkit-scrollbar {
+    display: none !important;            /* Chrome/Safari */
+}
+
+/* Fix for white background on single-line inputs in dark mode */
+.gradio-container input[type="text"], 
+.gradio-container input[type="password"], 
+.gradio-container input[type="number"], 
+.gradio-container input[type="email"] {
+    background-color: var(--input-background-fill) !important;
+    color: var(--body-text-color) !important;
+}
+
+/* Custom glossy purple styling for primary action buttons */
+.gradio-container button.primary {
+    border: 1px solid rgba(99, 102, 241, 0.35) !important;
+    background: linear-gradient(180deg, rgba(99, 102, 241, 0.25), rgba(59, 130, 246, 0.20)) !important;
+    box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.12), 0 2px 4px rgba(0, 0, 0, 0.15) !important;
+    color: rgba(255, 255, 255, 0.95) !important;
+    transition: background .2s ease, border-color .2s ease, box-shadow .2s ease, transform .06s ease !important;
+}
+.gradio-container button.primary:hover {
+    border-color: rgba(99, 102, 241, 0.5) !important;
+    background: linear-gradient(180deg, rgba(99, 102, 241, 0.35), rgba(59, 130, 246, 0.28)) !important;
+    box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 3px 6px rgba(0, 0, 0, 0.2) !important;
+}
+.gradio-container button.primary:active {
+    transform: scale(0.98) !important;
+    box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.2), 0 1px 2px rgba(0, 0, 0, 0.1) !important;
+}
+@media (prefers-color-scheme: light) {
+    .gradio-container button.primary {
+        border-color: rgba(99, 102, 241, 0.4) !important;
+        background: linear-gradient(180deg, rgba(99, 102, 241, 0.85), rgba(79, 70, 229, 0.75)) !important;
+        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25), 0 2px 4px rgba(0, 0, 0, 0.12) !important;
+        color: rgba(255, 255, 255, 0.98) !important;
+    }
+    .gradio-container button.primary:hover {
+        background: linear-gradient(180deg, rgba(99, 102, 241, 0.95), rgba(79, 70, 229, 0.85)) !important;
+        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.3), 0 3px 6px rgba(0, 0, 0, 0.15) !important;
+    }
+}
+
+/* Hide the actual tabs since we use the sidebar to control them */
+.hidden-tabs .tab-nav,
+.hidden-tabs [role="tablist"] {
+    display: none !important;
+}
+/* Hide the entire first row of the tabs container (contains tab buttons + overflow) */
+.hidden-tabs > div:first-child {
+    display: none !important;
+}
+/* Ensure audio component buttons remain visible - they're inside tab panels, not the first row */
+.hidden-tabs [role="tabpanel"] button {
+    display: inline-flex !important;
+}
+
+/* Custom scrollbar styling - Progressive enhancement, falls back to default scrollbars */
+/* stylelint-disable compat-api/css */
+* {
+    scrollbar-width: thin;
+    scrollbar-color: rgba(61, 212, 159, 0.4) rgba(255, 255, 255, 0.05);
+}
+*::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+*::-webkit-scrollbar-track {
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 4px;
+}
+*::-webkit-scrollbar-thumb {
+    background: linear-gradient(180deg, rgba(61, 212, 159, 0.5), rgba(17, 186, 136, 0.4));
+    border-radius: 4px;
+    border: 1px solid rgba(119, 247, 209, 0.2);
+}
+*::-webkit-scrollbar-thumb:hover {
+    background: linear-gradient(180deg, rgba(85, 250, 192, 0.7), rgba(65, 184, 131, 0.6));
+}
+*::-webkit-scrollbar-corner {
+    background: rgba(255, 255, 255, 0.05);
+}
+@media (prefers-color-scheme: light) {
+    * {
+        scrollbar-color: rgba(61, 212, 159, 0.4) rgba(0, 0, 0, 0.05);
+    }
+    *::-webkit-scrollbar-track {
+        background: rgba(0, 0, 0, 0.05);
+    }
+    *::-webkit-scrollbar-thumb {
+        background: linear-gradient(180deg, rgba(61, 212, 159, 0.5), rgba(17, 186, 136, 0.4));
+        border-color: rgba(0, 0, 0, 0.1);
+    }
+    *::-webkit-scrollbar-thumb:hover {
+        background: linear-gradient(180deg, rgba(85, 250, 192, 0.7), rgba(65, 184, 131, 0.6));
+    }
+    *::-webkit-scrollbar-corner {
+        background: rgba(0, 0, 0, 0.05);
+    }
+}
 /* stylelint-enable compat-api/css */