add clone

Filesystem/demo.txt

@@ -0,0 +1 @@
+Hello, World!

Modules/Agent_Terminal.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import os
+import sys
+import types
+import ast
+from io import StringIO
+from typing import Annotated
+import importlib.metadata
+
+import gradio as gr
+from ._docstrings import autodoc
+from .File_System import ROOT_DIR, File_System
+from .Web_Fetch import Web_Fetch
+from .Web_Search import Web_Search
+from .Memory_Manager import Memory_Manager
+from .Generate_Speech import Generate_Speech, List_Kokoro_Voices, List_Supertonic_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 app import _log_call_end, _log_call_start, _truncate_for_log
+
+def search_packages(query: str = "") -> str:
+    """Search for installed Python packages by name. If query is empty, lists all."""
+    packages = []
+    query = query.lower()
+    for dist in importlib.metadata.distributions():
+        name = dist.metadata['Name']
+        if query in name.lower():
+            packages.append(f"{name} ({dist.version})")
+    packages.sort()
+    if not packages:
+        return f"No packages found matching '{query}'."
+    return "\n".join(packages)
+
+def _get_tools_map():
+    return {
+        "Web_Fetch": Web_Fetch,
+        "Web_Search": Web_Search,
+        "Memory_Manager": Memory_Manager,
+        "Generate_Speech": Generate_Speech,
+        "List_Kokoro_Voices": List_Kokoro_Voices,
+        "List_Supertonic_Voices": List_Supertonic_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,
+    }
+
+def list_tools() -> list[str]:
+    """List all available tools in the Code Interpreter environment."""
+    return list(_get_tools_map().keys())
+
+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():
+        doc = (func.__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(f"--- {name} ---")
+        output.append(func.__doc__ or "No documentation available.")
+        output.append("")
+    return "\n".join(output)
+
+def usage(tool_name: str) -> str:
+    """Get detailed usage information for a specific tool."""
+    tools = _get_tools_map()
+    if tool_name not in tools:
+        return f"Tool '{tool_name}' not found. Available tools: {', '.join(tools.keys())}"
+    func = tools[tool_name]
+    return f"--- {tool_name} ---\n{func.__doc__ or 'No documentation available.'}"
+
+def _initialize_mock_modules():
+    """
+    Registers a mock 'functions' module in sys.modules so that LLMs
+    can do 'from functions import ...' without error.
+    """
+    mock_module = types.ModuleType("functions")
+    
+    # Add tools
+    for name, tool in _get_tools_map().items():
+        setattr(mock_module, name, tool)
+        
+    # Add helpers
+    helpers = {
+        "list_tools": list_tools,
+        "search_tools": search_tools,
+        "usage": usage,
+        "search_packages": search_packages,
+    }
+    for name, func in helpers.items():
+        setattr(mock_module, name, func)
+        
+    sys.modules["functions"] = mock_module
+
+_initialize_mock_modules()
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Executes Python code as the unified interface for the entire tools ecosystem. "
+    "All tool interactions must happen through this code-execution gateway. "
+    "Use Agent Terminal repeatedly whenever you need to chain or combine tool operations. "
+    "Available tools: `Web_Fetch`, `Web_Search`, `Code_Interpreter`, `Shell_Command`, `File_System`, `Obsidian_Vault`, `Memory_Manager`, `Generate_Speech`, `Generate_Image`, `Generate_Video`, `Deep_Research`."
+)
+
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Agent_Terminal(input: Annotated[str, (
+    "Python source code to run; stdout is captured and returned. "
+    "Execute these commands: "
+    "`search_tools('query')` to search for tools by name or capability; "
+    "`list_tools()` to list all available tools; "
+    "`usage('ToolName')` to inspect a tool’s expected input parameters; "
+    "`search_packages('query')` to search for installed Python libraries."
+)]) -> str:
+    _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
+    old_stdout = sys.stdout
+    old_cwd = os.getcwd()
+    redirected_output = sys.stdout = StringIO()
+    
+    # Prepare the execution environment with all tools
+    tools_env = {
+        "Web_Fetch": Web_Fetch,
+        "Web_Search": Web_Search,
+        "Memory_Manager": Memory_Manager,
+        "Generate_Speech": Generate_Speech,
+        "List_Kokoro_Voices": List_Kokoro_Voices,
+        "List_Supertonic_Voices": List_Supertonic_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,
+        "list_tools": list_tools,
+        "search_tools": search_tools,
+        "usage": usage,
+        "search_packages": search_packages,
+        "print": print,  # Ensure print is available
+        "__builtins__": __builtins__,
+    }
+    
+    try:
+        os.chdir(ROOT_DIR)
+        
+        # Parse code to check if the last statement is an expression
+        tree = ast.parse(input)
+        if tree.body and isinstance(tree.body[-1], ast.Expr):
+            last_node = tree.body.pop()
+            
+            # Execute preceding statements
+            if tree.body:
+                exec(compile(tree, filename="<string>", mode="exec"), tools_env)
+            
+            # Evaluate and print the last expression
+            expr = compile(ast.Expression(last_node.value), filename="<string>", mode="eval")
+            result_val = eval(expr, tools_env)
+            if result_val is not None:
+                print(result_val)
+        else:
+            exec(input, tools_env)
+            
+        result = redirected_output.getvalue()
+    except Exception as exc:  # pylint: disable=broad-except
+        result = str(exc)
+    finally:
+        sys.stdout = old_stdout
+        try:
+            os.chdir(old_cwd)
+        except Exception:
+            pass
+    _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

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+import sys
+from io import StringIO
+from typing import Annotated
+
+import gradio as gr
+from ._docstrings import autodoc
+from .File_System import ROOT_DIR
+
+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))
+    if code is None:
+        result = "No code provided."
+        _log_call_end("Code_Interpreter", result)
+        return result
+    old_stdout = sys.stdout
+    old_cwd = os.getcwd()
+    redirected_output = sys.stdout = StringIO()
+    try:
+        os.chdir(ROOT_DIR)
+        exec(code)
+        result = redirected_output.getvalue()
+    except Exception as exc:  # pylint: disable=broad-except
+        result = str(exc)
+    finally:
+        sys.stdout = old_stdout
+        try:
+            os.chdir(old_cwd)
+        except Exception:
+            pass
+    _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

@@ -0,0 +1,595 @@
+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
+
+HF_TEXTGEN_TOKEN = os.getenv("HF_READ_TOKEN") or os.getenv("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.6",
+            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.6)", 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\">Perform multi-query web research: search with DuckDuckGo, fetch up to 50 pages in parallel, "
+            "and generate a comprehensive report using a large LLM via Hugging Face Inference Providers (Cerebras). Requires HF_READ_TOKEN.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Deep_Research", "build_interface"]

Modules/File_System.py

@@ -0,0 +1,648 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import stat
+from datetime import datetime
+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
+
+
+TOOL_SUMMARY = (
+    "Browse, search, and manage files within a safe root. "
+    "Actions: list, read, write, append, mkdir, move, copy, delete, info, search, help. "
+    "Fill other fields as needed. "
+    "Use paths like `/` or `/notes/todo.txt` because all paths are relative to the root (`/`). "
+    "Use 'help' to see action-specific required fields and examples."
+)
+
+HELP_TEXT = (
+    "File System — actions and usage\n\n"
+    "Root: paths resolve under Nymbo-Tools/Filesystem by default (or NYMBO_TOOLS_ROOT if set). "
+    "Start paths with '/' to refer to the tool root (e.g., /notes). "
+    "Absolute paths are disabled unless UNSAFE_ALLOW_ABS_PATHS=1.\n\n"
+    "Actions and fields:\n"
+    "- list: path='/' (default), recursive=false, show_hidden=false, max_entries=20\n"
+    "- read: path (e.g., /notes/todo.txt), offset=0, max_chars=4000 (shows next_cursor when truncated)\n"
+    "- write: path, content (UTF-8), create_dirs=true\n"
+    "- append: path, content (UTF-8), create_dirs=true\n"
+    "- mkdir: path (directory), exist_ok=true\n"
+    "- move: path (src), dest_path (dst), overwrite=false\n"
+    "- copy: path (src), dest_path (dst), overwrite=false\n"
+    "- delete: path, recursive=true (required for directories)\n"
+    "- info: path\n"
+    "- search: path (dir or file), content=query text, recursive=false, show_hidden=false, max_entries=20, case_sensitive=false, offset=0\n"
+    "- help: show this guide\n\n"
+    "Errors are returned as JSON with fields: {status:'error', code, message, path?, hint?, data?}.\n\n"
+    "Examples:\n"
+    "- list current: action=list, path='/'\n"
+    "- make folder: action=mkdir, path='/notes'\n"
+    "- write file: action=write, path='/notes/todo.txt', content='hello'\n"
+    "- read file: action=read, path='/notes/todo.txt', max_chars=200\n"
+    "- move file: action=move, path='/notes/todo.txt', dest_path='/notes/todo-old.txt', overwrite=true\n"
+    "- delete dir: action=delete, path='/notes', recursive=true\n"
+    "- search text: action=search, path='/notes', content='TODO', recursive=true, max_entries=50\n"
+    "- page search results: action=search, content='TODO', offset=10\n"
+    "- case-sensitive search: action=search, content='TODO', case_sensitive=true\n"
+)
+
+
+def _default_root() -> str:
+    # Prefer explicit root via env var
+    root = os.getenv("NYMBO_TOOLS_ROOT")
+    if root and root.strip():
+        return os.path.abspath(os.path.expanduser(root.strip()))
+    # Default to "Nymbo-Tools/Filesystem" alongside this module package
+    try:
+        here = os.path.abspath(__file__)
+        tools_dir = os.path.dirname(os.path.dirname(here))  # .../Nymbo-Tools
+        default_root = os.path.abspath(os.path.join(tools_dir, "Filesystem"))
+        return default_root
+    except Exception:
+        # Final fallback
+        return os.path.abspath(os.getcwd())
+
+
+ROOT_DIR = _default_root()
+# Ensure the default root directory exists to make listing/writing more convenient
+try:
+    os.makedirs(ROOT_DIR, exist_ok=True)
+except Exception:
+    pass
+ALLOW_ABS = bool(int(os.getenv("UNSAFE_ALLOW_ABS_PATHS", "0")))
+
+def _safe_err(exc: Exception | str) -> str:
+    """Return an error string with any absolute root replaced by '/' and slashes normalized.
+    This handles variants like backslashes and duplicate slashes in OS messages.
+    """
+    s = str(exc)
+    # Normalize to forward slashes for comparison
+    s_norm = s.replace("\\", "/")
+    root_fwd = ROOT_DIR.replace("\\", "/")
+    # Collapse duplicate slashes in root representation
+    root_variants = {ROOT_DIR, root_fwd, re.sub(r"/+", "/", root_fwd)}
+    for variant in root_variants:
+        if variant:
+            s_norm = s_norm.replace(variant, "/")
+    # Collapse duplicate slashes in final output
+    s_norm = re.sub(r"/+", "/", s_norm)
+    return s_norm
+
+
+def _err(code: str, message: str, *, path: Optional[str] = None, hint: Optional[str] = None, data: Optional[dict] = None) -> str:
+    """Return a structured error JSON string.
+    Fields: status='error', code, message, path?, hint?, data?, root='/'
+    """
+    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 _resolve_path(path: str) -> tuple[str, str]:
+    """
+    Resolve a user-provided path to an absolute, normalized path constrained to ROOT_DIR
+    (unless UNSAFE_ALLOW_ABS_PATHS=1). Returns (abs_path, error_message). error_message is empty when ok.
+    """
+    try:
+        user_input = (path or "/").strip() or "/"
+        if user_input.startswith("/"):
+            # Treat leading '/' as the virtual root for the tool.
+            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 ALLOW_ABS:
+                # Absolute paths are not allowed in safe mode
+                return "", _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(ROOT_DIR, raw))
+        # Constrain to ROOT when not unsafe mode
+        if not ALLOW_ABS:
+            try:
+                common = os.path.commonpath([os.path.normpath(ROOT_DIR), os.path.normpath(abs_path)])
+            except Exception:
+                # Fallback to simple check
+                root_cmp = os.path.normcase(os.path.normpath(ROOT_DIR))
+                abs_cmp = os.path.normcase(os.path.normpath(abs_path))
+                if not abs_cmp.startswith(root_cmp):
+                    return "", _err(
+                        "path_outside_root",
+                        "Path not allowed outside root.",
+                        path=user_input.replace("\\", "/"),
+                        hint="Use a path under / (the tool's root)."
+                    )
+            else:
+                root_cmp = os.path.normcase(os.path.normpath(ROOT_DIR))
+                common_cmp = os.path.normcase(os.path.normpath(common))
+                if common_cmp != root_cmp:
+                    return "", _err(
+                        "path_outside_root",
+                        "Path not allowed outside root.",
+                        path=user_input.replace("\\", "/"),
+                        hint="Use a path under / (the tool's root)."
+                    )
+        return abs_path, ""
+    except Exception as exc:
+        return "", _err(
+            "resolve_path_failed",
+            "Failed to resolve path.",
+            path=(path or ""),
+            data={"error": _safe_err(exc)}
+        )
+
+
+def _fmt_size(num_bytes: int) -> str:
+    units = ["B", "KB", "MB", "GB", "TB"]
+    size = float(num_bytes)
+    for unit in units:
+        if size < 1024.0:
+            return f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} PB"
+
+
+def _display_path(abs_path: str) -> str:
+    """Return a user-friendly path relative to ROOT_DIR using forward slashes.
+    Example: ROOT_DIR -> '/', a file under it -> '/sub/dir/file.txt'."""
+    try:
+        norm_root = os.path.normpath(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
+    # Fallback to original absolute path
+    return abs_path.replace("\\", "/")
+
+
+def _list_dir(abs_path: str, *, show_hidden: bool, recursive: bool, max_entries: int) -> str:
+    lines: list[str] = []
+    total = 0
+    root_display = "/"
+    listing_display = _display_path(abs_path)
+    for root, dirs, files in os.walk(abs_path):
+        # filter hidden
+        if not show_hidden:
+            dirs[:] = [d for d in dirs if not d.startswith('.')]
+            files = [f for f in files if not f.startswith('.')]
+        try:
+            rel_root = os.path.relpath(root, ROOT_DIR)
+        except Exception:
+            rel_root = root
+        rel_root_disp = "/" if rel_root == "." else "/" + rel_root.replace("\\", "/")
+        lines.append(f"\n📂 {rel_root_disp}")
+        # sort
+        dirs.sort()
+        files.sort()
+        for d in dirs:
+            p = os.path.join(root, d)
+            try:
+                mtime = datetime.fromtimestamp(os.path.getmtime(p)).isoformat(sep=' ', timespec='seconds')
+            except Exception:
+                mtime = "?"
+            lines.append(f"  • [DIR] {d}    (modified {mtime})")
+            total += 1
+            if total >= max_entries:
+                lines.append(f"\n… Truncated at {max_entries} entries.")
+                return "\n".join(lines).strip()
+        for f in files:
+            p = os.path.join(root, f)
+            try:
+                size = _fmt_size(os.path.getsize(p))
+                mtime = datetime.fromtimestamp(os.path.getmtime(p)).isoformat(sep=' ', timespec='seconds')
+            except Exception:
+                size, mtime = "?", "?"
+            lines.append(f"  • {f}    ({size}, modified {mtime})")
+            total += 1
+            if total >= max_entries:
+                lines.append(f"\n… Truncated at {max_entries} entries.")
+                return "\n".join(lines).strip()
+        if not recursive:
+            break
+    header = f"Listing of {listing_display}\nRoot: {root_display}\nEntries: {total}"
+    return (header + "\n" + "\n".join(lines)).strip()
+
+
+def _search_text(
+    abs_path: str,
+    query: str,
+    *,
+    recursive: bool,
+    show_hidden: bool,
+    max_results: int,
+    case_sensitive: bool,
+    start_index: int,
+) -> str:
+    if not os.path.exists(abs_path):
+        return _err("path_not_found", f"Path not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+
+    query = query or ""
+    normalized_query = query if case_sensitive else query.lower()
+    if normalized_query == "":
+        return _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((_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"{_display_path(file_path)} ({_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: {_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(abs_path: str, *, offset: int, max_chars: int) -> str:
+    if not os.path.exists(abs_path):
+        return _err("file_not_found", f"File not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+    if os.path.isdir(abs_path):
+        return _err("is_directory", f"Path is a directory, not a file: {_display_path(abs_path)}", path=_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 _err("read_failed", "Failed to read file.", path=_display_path(abs_path), data={"error": _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
+    meta = {
+        "offset": start,
+        "returned": len(chunk),
+        "total": total,
+        "next_cursor": next_cursor,
+        "path": _display_path(abs_path),
+    }
+    header = (
+        f"Reading {_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 _ensure_parent(abs_path: str, create_dirs: bool) -> None:
+    parent = os.path.dirname(abs_path)
+    if parent and not os.path.exists(parent):
+        if create_dirs:
+            os.makedirs(parent, exist_ok=True)
+        else:
+            raise FileNotFoundError(f"Parent directory does not exist: {_display_path(parent)}")
+
+
+def _write_file(abs_path: str, content: str, *, append: bool, create_dirs: bool) -> str:
+    try:
+        _ensure_parent(abs_path, create_dirs)
+        mode = 'a' if append else 'w'
+        with open(abs_path, mode, encoding='utf-8') as f:
+            f.write(content or "")
+        return f"{'Appended to' if append else 'Wrote'} file: {_display_path(abs_path)} (chars={len(content or '')})"
+    except Exception as exc:
+        return _err("write_failed", "Failed to write file.", path=_display_path(abs_path), data={"error": _safe_err(exc)})
+
+
+def _mkdir(abs_path: str, exist_ok: bool) -> str:
+    try:
+        os.makedirs(abs_path, exist_ok=exist_ok)
+        return f"Created directory: {_display_path(abs_path)}"
+    except Exception as exc:
+        return _err("mkdir_failed", "Failed to create directory.", path=_display_path(abs_path), data={"error": _safe_err(exc)})
+
+
+def _move_copy(action: str, src: str, dst: str, *, overwrite: bool) -> str:
+    try:
+        if not os.path.exists(src):
+            return _err("source_not_found", f"Source not found: {_display_path(src)}", path=_display_path(src))
+        if os.path.isdir(dst):
+            # allow moving into an existing directory
+            dst_path = os.path.join(dst, os.path.basename(src))
+        else:
+            dst_path = dst
+        if os.path.exists(dst_path):
+            if overwrite:
+                if os.path.isdir(dst_path):
+                    shutil.rmtree(dst_path)
+                else:
+                    os.remove(dst_path)
+            else:
+                return _err(
+                    "destination_exists",
+                    f"Destination already exists: {_display_path(dst_path)}",
+                    path=_display_path(dst_path),
+                    hint="Set overwrite=True to replace the destination."
+                )
+        if action == 'move':
+            shutil.move(src, dst_path)
+        else:
+            if os.path.isdir(src):
+                shutil.copytree(src, dst_path)
+            else:
+                shutil.copy2(src, dst_path)
+        return f"{action.capitalize()}d: {_display_path(src)} -> {_display_path(dst_path)}"
+    except Exception as exc:
+        return _err(f"{action}_failed", f"Failed to {action}.", path=_display_path(src), data={"error": _safe_err(exc), "destination": _display_path(dst)})
+
+
+def _delete(abs_path: str, *, recursive: bool) -> str:
+    try:
+        if not os.path.exists(abs_path):
+            return _err("path_not_found", f"Path not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+        if os.path.isdir(abs_path):
+            if not recursive:
+                # Refuse to delete a dir unless recursive=True
+                return _err("requires_recursive", "Refusing to delete a directory without recursive=True", path=_display_path(abs_path), hint="Pass recursive=True to delete a directory.")
+            shutil.rmtree(abs_path)
+        else:
+            os.remove(abs_path)
+        return f"Deleted: {_display_path(abs_path)}"
+    except Exception as exc:
+        return _err("delete_failed", "Failed to delete path.", path=_display_path(abs_path), data={"error": _safe_err(exc)})
+
+
+def _info(abs_path: str) -> str:
+    try:
+        st = os.stat(abs_path)
+    except Exception as exc:
+        return _err("stat_failed", "Failed to stat path.", path=_display_path(abs_path), data={"error": _safe_err(exc)})
+    info = {
+        "path": _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, indent=2)
+
+
+@autodoc(summary=TOOL_SUMMARY)
+def File_System(
+    action: Annotated[str, "Operation to perform: 'list', 'read', 'write', 'append', 'mkdir', 'move', 'copy', 'delete', 'info', 'search'."],
+    path: Annotated[str, "Target path, relative to root unless UNSAFE_ALLOW_ABS_PATHS=1."] = "/",
+    content: Annotated[Optional[str], "Content for write/append actions or search query (UTF-8)."] = None,
+    dest_path: Annotated[Optional[str], "Destination for move/copy (relative to root unless unsafe absolute allowed)."] = None,
+    recursive: Annotated[bool, "For list/search (recurse into subfolders) and delete (required for directories)."] = False,
+    show_hidden: Annotated[bool, "Include hidden files (dotfiles) for list/search."] = False,
+    max_entries: Annotated[int, "Max entries to list or matches to return (for list/search)."] = 20,
+    offset: Annotated[int, "Start offset for reading files (for read)."] = 0,
+    max_chars: Annotated[int, "Max characters to return when reading (0 = full file)."] = 4000,
+    create_dirs: Annotated[bool, "Create parent directories for write/append if missing."] = True,
+    overwrite: Annotated[bool, "Allow overwrite for move/copy destinations."] = False,
+    case_sensitive: Annotated[bool, "Match case when searching text."] = False,
+) -> str:
+    _log_call_start(
+        "File_System",
+        action=action,
+        path=path,
+        dest_path=dest_path,
+        recursive=recursive,
+        show_hidden=show_hidden,
+        max_entries=max_entries,
+        offset=offset,
+        max_chars=max_chars,
+        create_dirs=create_dirs,
+        overwrite=overwrite,
+        case_sensitive=case_sensitive,
+    )
+    action = (action or "").strip().lower()
+    if action not in {"list", "read", "write", "append", "mkdir", "move", "copy", "delete", "info", "search", "help"}:
+        result = _err(
+            "invalid_action",
+            "Invalid action.",
+            hint="Choose from: list, read, write, append, mkdir, move, copy, delete, info, search, help."
+        )
+        _log_call_end("File_System", _truncate_for_log(result))
+        return result
+
+    abs_path, err = _resolve_path(path)
+    if err:
+        _log_call_end("File_System", _truncate_for_log(err))
+        return err
+
+    try:
+        if action == "help":
+            result = HELP_TEXT
+        elif action == "list":
+            if not os.path.exists(abs_path):
+                result = _err("path_not_found", f"Path not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+            else:
+                result = _list_dir(abs_path, show_hidden=show_hidden, recursive=recursive, max_entries=max_entries)
+        elif action == "read":
+            result = _read_file(abs_path, offset=offset, max_chars=max_chars)
+        elif action in {"write", "append"}:
+            # Prevent attempts to write to root or any directory
+            if _display_path(abs_path) == "/" or os.path.isdir(abs_path):
+                result = _err(
+                    "invalid_write_path",
+                    "Invalid path for write/append.",
+                    path=_display_path(abs_path),
+                    hint="Provide a file path under / (e.g., /notes/todo.txt)."
+                )
+            else:
+                result = _write_file(abs_path, content or "", append=(action == "append"), create_dirs=create_dirs)
+        elif action == "mkdir":
+            result = _mkdir(abs_path, exist_ok=True)
+        elif action in {"move", "copy"}:
+            if not dest_path:
+                result = _err("missing_dest_path", "dest_path is required for move/copy (ignored for other actions).")
+            else:
+                abs_dst, err2 = _resolve_path(dest_path)
+                if err2:
+                    result = err2
+                else:
+                    result = _move_copy(action, abs_path, abs_dst, overwrite=overwrite)
+        elif action == "delete":
+            result = _delete(abs_path, recursive=recursive)
+        elif action == "search":
+            query_text = content or ""
+            if query_text.strip() == "":
+                result = _err(
+                    "missing_search_query",
+                    "Search query is required for the search action.",
+                    hint="Provide text in the Content field to search for.",
+                )
+            else:
+                result = _search_text(
+                    abs_path,
+                    query_text,
+                    recursive=recursive,
+                    show_hidden=show_hidden,
+                    max_results=max_entries,
+                    case_sensitive=case_sensitive,
+                    start_index=offset,
+                )
+        else:  # info
+            result = _info(abs_path)
+    except Exception as exc:
+        result = _err("exception", "Unhandled error during operation.", data={"error": _safe_err(exc)})
+
+    _log_call_end("File_System", _truncate_for_log(result))
+    return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=File_System,
+        inputs=[
+            gr.Radio(
+                label="Action",
+                choices=["list", "read", "write", "append", "mkdir", "move", "copy", "delete", "info", "search", "help"],
+                value="help",
+                info="Operation to perform",
+            ),
+            gr.Textbox(label="Path", placeholder="/ or /src/file.txt", max_lines=1, value="/", info="Target path (relative to root)"),
+            gr.Textbox(label="Content", lines=6, placeholder="Text to write or search for...", info="Content for write/append actions or search query"),
+            gr.Textbox(label="Destination", max_lines=1, info="Destination path (Move/Copy only)"),
+            gr.Checkbox(label="Recursive", value=False, info="Recurse into subfolders (List/Delete/Search)"),
+            gr.Checkbox(label="Show hidden", value=False, info="Include hidden files (List/Search)"),
+            gr.Slider(minimum=10, maximum=5000, step=10, value=20, label="Max entries / matches", info="Max entries to list or matches to return (List/Search)"),
+            gr.Slider(minimum=0, maximum=1_000_000, step=100, value=0, label="Offset", info="Start offset (Read/Search)"),
+            gr.Slider(minimum=0, maximum=100_000, step=500, value=4000, label="Max chars", info="Max characters to return (Read, 0=all)"),
+            gr.Checkbox(label="Create parent dirs", value=True, info="Create parent directories if missing (Write)"),
+            gr.Checkbox(label="Overwrite destination", value=False, info="Allow overwrite (Move/Copy)"),
+            gr.Checkbox(label="Case sensitive search", value=False, info="Match case (Search)"),
+        ],
+        outputs=gr.Textbox(label="Result", lines=20),
+        title="File System",
+        description=(
+            "<div id=\"fs-desc\" style=\"text-align:center; overflow:hidden;\">Browse, search, and interact with a filesystem. "
+            "Choose an action and fill optional fields as needed." 
+            "</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Run",
+    )
+
+
+__all__ = ["File_System", "build_interface"]

Modules/Generate_Image.py

@@ -0,0 +1,141 @@
+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 .File_System import ROOT_DIR
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+HF_API_TOKEN = os.getenv("HF_READ_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., black-forest-labs/FLUX.1-Krea-dev)."] = "black-forest-labs/FLUX.1-Krea-dev",
+    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."
+    providers = ["auto", "replicate", "fal-ai"]
+    last_error: Exception | None = None
+    for provider in 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:  # pylint: disable=broad-except
+            last_error = exc
+            continue
+    msg = str(last_error) if last_error else "Unknown error"
+    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 ("api_key" in lowered) or ("hf auth login" in lowered) or ("unauthorized" in lowered) or ("forbidden" in lowered):
+        raise gr.Error("Please duplicate the space and provide a `HF_READ_TOKEN` to enable Image and Video Generation.")
+    _log_call_end("Generate_Image", f"error={_truncate_for_log(msg, 200)}")
+    raise gr.Error(f"Image generation failed: {msg}")
+
+
+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="black-forest-labs/FLUX.1-Krea-dev",
+                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 FLUX.1-Krea-dev.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Generate_Image", "build_interface"]

Modules/Generate_Speech.py

@@ -0,0 +1,677 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from contextlib import contextmanager
+from typing import Optional, Annotated
+from unicodedata import normalize
+import re
+import uuid
+import io
+import wave
+
+import numpy as np
+import onnxruntime as ort
+import scipy.io.wavfile
+import gradio as gr
+
+from .File_System import ROOT_DIR
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+try:
+    import torch  # type: ignore
+except Exception:  # pragma: no cover
+    torch = None  # type: ignore
+
+try:
+    from kokoro import KModel, KPipeline  # type: ignore
+except Exception:  # pragma: no cover
+    KModel = None  # type: ignore
+    KPipeline = None  # type: ignore
+
+try:
+    from huggingface_hub import snapshot_download, list_repo_files
+except ImportError:
+    snapshot_download = None
+    list_repo_files = None
+
+
+# --- Supertonic Helper Classes & Functions ---
+
+class UnicodeProcessor:
+    def __init__(self, unicode_indexer_path: str):
+        with open(unicode_indexer_path, "r") as f:
+            self.indexer = json.load(f)
+
+    def _preprocess_text(self, text: str) -> str:
+        # TODO: add more preprocessing
+        text = normalize("NFKD", text)
+        return text
+
+    def _get_text_mask(self, text_ids_lengths: np.ndarray) -> np.ndarray:
+        text_mask = length_to_mask(text_ids_lengths)
+        return text_mask
+
+    def _text_to_unicode_values(self, text: str) -> np.ndarray:
+        unicode_values = np.array(
+            [ord(char) for char in text], dtype=np.uint16
+        )  # 2 bytes
+        return unicode_values
+
+    def __call__(self, text_list: list[str]) -> tuple[np.ndarray, np.ndarray]:
+        text_list = [self._preprocess_text(t) for t in text_list]
+        text_ids_lengths = np.array([len(text) for text in text_list], dtype=np.int64)
+        text_ids = np.zeros((len(text_list), text_ids_lengths.max()), dtype=np.int64)
+        for i, text in enumerate(text_list):
+            unicode_vals = self._text_to_unicode_values(text)
+            text_ids[i, : len(unicode_vals)] = np.array(
+                [self.indexer[val] for val in unicode_vals], dtype=np.int64
+            )
+        text_mask = self._get_text_mask(text_ids_lengths)
+        return text_ids, text_mask
+
+
+class Style:
+    def __init__(self, style_ttl_onnx: np.ndarray, style_dp_onnx: np.ndarray):
+        self.ttl = style_ttl_onnx
+        self.dp = style_dp_onnx
+
+
+class TextToSpeech:
+    def __init__(
+        self,
+        cfgs: dict,
+        text_processor: UnicodeProcessor,
+        dp_ort: ort.InferenceSession,
+        text_enc_ort: ort.InferenceSession,
+        vector_est_ort: ort.InferenceSession,
+        vocoder_ort: ort.InferenceSession,
+    ):
+        self.cfgs = cfgs
+        self.text_processor = text_processor
+        self.dp_ort = dp_ort
+        self.text_enc_ort = text_enc_ort
+        self.vector_est_ort = vector_est_ort
+        self.vocoder_ort = vocoder_ort
+        self.sample_rate = cfgs["ae"]["sample_rate"]
+        self.base_chunk_size = cfgs["ae"]["base_chunk_size"]
+        self.chunk_compress_factor = cfgs["ttl"]["chunk_compress_factor"]
+        self.ldim = cfgs["ttl"]["latent_dim"]
+
+    def sample_noisy_latent(
+        self, duration: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        bsz = len(duration)
+        wav_len_max = duration.max() * self.sample_rate
+        wav_lengths = (duration * self.sample_rate).astype(np.int64)
+        chunk_size = self.base_chunk_size * self.chunk_compress_factor
+        latent_len = ((wav_len_max + chunk_size - 1) / chunk_size).astype(np.int32)
+        latent_dim = self.ldim * self.chunk_compress_factor
+        noisy_latent = np.random.randn(bsz, latent_dim, latent_len).astype(np.float32)
+        latent_mask = get_latent_mask(
+            wav_lengths, self.base_chunk_size, self.chunk_compress_factor
+        )
+
+        noisy_latent = noisy_latent * latent_mask
+        return noisy_latent, latent_mask
+
+    def _infer(
+        self, text_list: list[str], style: Style, total_step: int, speed: float = 1.05
+    ) -> tuple[np.ndarray, np.ndarray]:
+        assert (
+            len(text_list) == style.ttl.shape[0]
+        ), "Number of texts must match number of style vectors"
+        bsz = len(text_list)
+        text_ids, text_mask = self.text_processor(text_list)
+        dur_onnx, *_ = self.dp_ort.run(
+            None, {"text_ids": text_ids, "style_dp": style.dp, "text_mask": text_mask}
+        )
+        dur_onnx = dur_onnx / speed
+        text_emb_onnx, *_ = self.text_enc_ort.run(
+            None,
+            {"text_ids": text_ids, "style_ttl": style.ttl, "text_mask": text_mask},
+        )  # dur_onnx: [bsz]
+        xt, latent_mask = self.sample_noisy_latent(dur_onnx)
+        total_step_np = np.array([total_step] * bsz, dtype=np.float32)
+        for step in range(total_step):
+            current_step = np.array([step] * bsz, dtype=np.float32)
+            xt, *_ = self.vector_est_ort.run(
+                None,
+                {
+                    "noisy_latent": xt,
+                    "text_emb": text_emb_onnx,
+                    "style_ttl": style.ttl,
+                    "text_mask": text_mask,
+                    "latent_mask": latent_mask,
+                    "current_step": current_step,
+                    "total_step": total_step_np,
+                },
+            )
+        wav, *_ = self.vocoder_ort.run(None, {"latent": xt})
+        return wav, dur_onnx
+
+    def __call__(
+        self,
+        text: str,
+        style: Style,
+        total_step: int,
+        speed: float = 1.05,
+        silence_duration: float = 0.3,
+        max_len: int = 300,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        assert (
+            style.ttl.shape[0] == 1
+        ), "Single speaker text to speech only supports single style"
+        text_list = chunk_text(text, max_len=max_len)
+        wav_cat = None
+        dur_cat = None
+        for text in text_list:
+            wav, dur_onnx = self._infer([text], style, total_step, speed)
+            if wav_cat is None:
+                wav_cat = wav
+                dur_cat = dur_onnx
+            else:
+                silence = np.zeros(
+                    (1, int(silence_duration * self.sample_rate)), dtype=np.float32
+                )
+                wav_cat = np.concatenate([wav_cat, silence, wav], axis=1)
+                dur_cat += dur_onnx + silence_duration
+        return wav_cat, dur_cat
+
+    def stream(
+        self,
+        text: str,
+        style: Style,
+        total_step: int,
+        speed: float = 1.05,
+        silence_duration: float = 0.3,
+        max_len: int = 300,
+    ):
+        assert (
+            style.ttl.shape[0] == 1
+        ), "Single speaker text to speech only supports single style"
+        text_list = chunk_text(text, max_len=max_len)
+
+        for i, text in enumerate(text_list):
+            wav, _ = self._infer([text], style, total_step, speed)
+            yield wav.flatten()
+
+            if i < len(text_list) - 1:
+                silence = np.zeros(
+                    (int(silence_duration * self.sample_rate),), dtype=np.float32
+                )
+                yield silence
+
+    def batch(
+        self, text_list: list[str], style: Style, total_step: int, speed: float = 1.05
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return self._infer(text_list, style, total_step, speed)
+
+
+def length_to_mask(lengths: np.ndarray, max_len: Optional[int] = None) -> np.ndarray:
+    """
+    Convert lengths to binary mask.
+
+    Args:
+        lengths: (B,)
+        max_len: int
+
+    Returns:
+        mask: (B, 1, max_len)
+    """
+    max_len = max_len or lengths.max()
+    ids = np.arange(0, max_len)
+    mask = (ids < np.expand_dims(lengths, axis=1)).astype(np.float32)
+    return mask.reshape(-1, 1, max_len)
+
+
+def get_latent_mask(
+    wav_lengths: np.ndarray, base_chunk_size: int, chunk_compress_factor: int
+) -> np.ndarray:
+    latent_size = base_chunk_size * chunk_compress_factor
+    latent_lengths = (wav_lengths + latent_size - 1) // latent_size
+    latent_mask = length_to_mask(latent_lengths)
+    return latent_mask
+
+
+def load_onnx(
+    onnx_path: str, opts: ort.SessionOptions, providers: list[str]
+) -> ort.InferenceSession:
+    return ort.InferenceSession(onnx_path, sess_options=opts, providers=providers)
+
+
+def load_onnx_all(
+    onnx_dir: str, opts: ort.SessionOptions, providers: list[str]
+) -> tuple[
+    ort.InferenceSession,
+    ort.InferenceSession,
+    ort.InferenceSession,
+    ort.InferenceSession,
+]:
+    dp_onnx_path = os.path.join(onnx_dir, "duration_predictor.onnx")
+    text_enc_onnx_path = os.path.join(onnx_dir, "text_encoder.onnx")
+    vector_est_onnx_path = os.path.join(onnx_dir, "vector_estimator.onnx")
+    vocoder_onnx_path = os.path.join(onnx_dir, "vocoder.onnx")
+
+    dp_ort = load_onnx(dp_onnx_path, opts, providers)
+    text_enc_ort = load_onnx(text_enc_onnx_path, opts, providers)
+    vector_est_ort = load_onnx(vector_est_onnx_path, opts, providers)
+    vocoder_ort = load_onnx(vocoder_onnx_path, opts, providers)
+    return dp_ort, text_enc_ort, vector_est_ort, vocoder_ort
+
+
+def load_cfgs(onnx_dir: str) -> dict:
+    cfg_path = os.path.join(onnx_dir, "tts.json")
+    with open(cfg_path, "r") as f:
+        cfgs = json.load(f)
+    return cfgs
+
+
+def load_text_processor(onnx_dir: str) -> UnicodeProcessor:
+    unicode_indexer_path = os.path.join(onnx_dir, "unicode_indexer.json")
+    text_processor = UnicodeProcessor(unicode_indexer_path)
+    return text_processor
+
+
+def load_text_to_speech(onnx_dir: str, use_gpu: bool = False) -> TextToSpeech:
+    opts = ort.SessionOptions()
+    if use_gpu:
+        raise NotImplementedError("GPU mode is not fully tested")
+    else:
+        providers = ["CPUExecutionProvider"]
+        print("Using CPU for inference")
+    cfgs = load_cfgs(onnx_dir)
+    dp_ort, text_enc_ort, vector_est_ort, vocoder_ort = load_onnx_all(
+        onnx_dir, opts, providers
+    )
+    text_processor = load_text_processor(onnx_dir)
+    return TextToSpeech(
+        cfgs, text_processor, dp_ort, text_enc_ort, vector_est_ort, vocoder_ort
+    )
+
+
+def load_voice_style(voice_style_paths: list[str], verbose: bool = False) -> Style:
+    bsz = len(voice_style_paths)
+
+    # Read first file to get dimensions
+    with open(voice_style_paths[0], "r") as f:
+        first_style = json.load(f)
+    ttl_dims = first_style["style_ttl"]["dims"]
+    dp_dims = first_style["style_dp"]["dims"]
+
+    # Pre-allocate arrays with full batch size
+    ttl_style = np.zeros([bsz, ttl_dims[1], ttl_dims[2]], dtype=np.float32)
+    dp_style = np.zeros([bsz, dp_dims[1], dp_dims[2]], dtype=np.float32)
+
+    # Fill in the data
+    for i, voice_style_path in enumerate(voice_style_paths):
+        with open(voice_style_path, "r") as f:
+            voice_style = json.load(f)
+
+        ttl_data = np.array(
+            voice_style["style_ttl"]["data"], dtype=np.float32
+        ).flatten()
+        ttl_style[i] = ttl_data.reshape(ttl_dims[1], ttl_dims[2])
+
+        dp_data = np.array(
+            voice_style["style_dp"]["data"], dtype=np.float32
+        ).flatten()
+        dp_style[i] = dp_data.reshape(dp_dims[1], dp_dims[2])
+
+    if verbose:
+        print(f"Loaded {bsz} voice styles")
+    return Style(ttl_style, dp_style)
+
+
+@contextmanager
+def timer(name: str):
+    start = time.time()
+    print(f"{name}...")
+    yield
+    print(f"  -> {name} completed in {time.time() - start:.2f} sec")
+
+
+def sanitize_filename(text: str, max_len: int) -> str:
+    """Sanitize filename by replacing non-alphanumeric characters with underscores"""
+    prefix = text[:max_len]
+    return re.sub(r"[^a-zA-Z0-9]", "_", prefix)
+
+
+def chunk_text(text: str, max_len: int = 300) -> list[str]:
+    """
+    Split text into chunks by paragraphs and sentences.
+
+    Args:
+        text: Input text to chunk
+        max_len: Maximum length of each chunk (default: 300)
+
+    Returns:
+        List of text chunks
+    """
+    # Split by paragraph (two or more newlines)
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n+", text.strip()) if p.strip()]
+
+    chunks = []
+
+    for paragraph in paragraphs:
+        paragraph = paragraph.strip()
+        if not paragraph:
+            continue
+
+        # Split by sentence boundaries (period, question mark, exclamation mark followed by space)
+        # But exclude common abbreviations like Mr., Mrs., Dr., etc. and single capital letters like F.
+        pattern = r"(?<!Mr\.)(?<!Mrs\.)(?<!Ms\.)(?<!Dr\.)(?<!Prof\.)(?<!Sr\.)(?<!Jr\.)(?<!Ph\.D\.)(?<!etc\.)(?<!e\.g\.)(?<!i\.e\.)(?<!vs\.)(?<!Inc\.)(?<!Ltd\.)(?<!Co\.)(?<!Corp\.)(?<!St\.)(?<!Ave\.)(?<!Blvd\.)(?<!\b[A-Z]\.)(?<=[.!?])\s+"
+        sentences = re.split(pattern, paragraph)
+
+        current_chunk = ""
+
+        for sentence in sentences:
+            if len(current_chunk) + len(sentence) + 1 <= max_len:
+                current_chunk += (" " if current_chunk else "") + sentence
+            else:
+                if current_chunk:
+                    chunks.append(current_chunk.strip())
+                current_chunk = sentence
+
+        if current_chunk:
+            chunks.append(current_chunk.strip())
+
+    return chunks
+
+
+# --- Main Tool Logic ---
+
+# --- Kokoro State ---
+_KOKORO_STATE = {
+    "initialized": False,
+    "device": "cpu",
+    "model": None,
+    "pipelines": {},
+}
+
+# --- Supertonic State ---
+_SUPERTONIC_STATE = {
+    "initialized": False,
+    "tts": None,
+    "assets_dir": None,
+}
+
+def _audio_np_to_int16(audio_np: np.ndarray) -> np.ndarray:
+    audio_clipped = np.clip(audio_np, -1.0, 1.0)
+    return (audio_clipped * 32767.0).astype(np.int16)
+
+# --- Kokoro Functions ---
+
+def get_kokoro_voices() -> list[str]:
+    try:
+        if list_repo_files:
+            files = list_repo_files("hexgrad/Kokoro-82M")
+            voice_files = [file for file in files if file.endswith(".pt") and file.startswith("voices/")]
+            voices = [file.replace("voices/", "").replace(".pt", "") for file in voice_files]
+            return sorted(voices) if voices else _get_fallback_voices()
+        return _get_fallback_voices()
+    except Exception:
+        return _get_fallback_voices()
+
+
+def _get_fallback_voices() -> list[str]:
+    return [
+        "af_alloy", "af_aoede", "af_bella", "af_heart", "af_jessica", "af_kore", "af_nicole", "af_nova", "af_river", "af_sarah", "af_sky",
+        "am_adam", "am_echo", "am_eric", "am_fenrir", "am_liam", "am_michael", "am_onyx", "am_puck", "am_santa",
+        "bf_alice", "bf_emma", "bf_isabella", "bf_lily",
+        "bm_daniel", "bm_fable", "bm_george", "bm_lewis",
+        "ef_dora", "em_alex", "em_santa",
+        "ff_siwis",
+        "hf_alpha", "hf_beta", "hm_omega", "hm_psi",
+        "if_sara", "im_nicola",
+        "jf_alpha", "jf_gongitsune", "jf_nezumi", "jf_tebukuro", "jm_kumo",
+        "pf_dora", "pm_alex", "pm_santa",
+        "zf_xiaobei", "zf_xiaoni", "zf_xiaoxiao", "zf_xiaoyi",
+        "zm_yunjian", "zm_yunxi", "zm_yunxia", "zm_yunyang",
+    ]
+
+
+def _init_kokoro() -> None:
+    if _KOKORO_STATE["initialized"]:
+        return
+    if KModel is None or KPipeline is None:
+        raise RuntimeError("Kokoro is not installed. Please install the 'kokoro' package (>=0.9.4).")
+    device = "cpu"
+    if torch is not None:
+        try:
+            if torch.cuda.is_available():
+                device = "cuda"
+        except Exception:
+            device = "cpu"
+    model = KModel(repo_id="hexgrad/Kokoro-82M").to(device).eval()
+    pipelines = {"a": KPipeline(lang_code="a", model=False, repo_id="hexgrad/Kokoro-82M")}
+    try:
+        pipelines["a"].g2p.lexicon.golds["kokoro"] = "kˈOkəɹO"
+    except Exception:
+        pass
+    _KOKORO_STATE.update({"initialized": True, "device": device, "model": model, "pipelines": pipelines})
+
+# --- Supertonic Functions ---
+
+def _init_supertonic() -> None:
+    if _SUPERTONIC_STATE["initialized"]:
+        return
+    
+    if snapshot_download is None:
+        raise RuntimeError("huggingface_hub is not installed.")
+
+    # Use a local assets directory within Nymbo-Tools
+    # Assuming this file is in Nymbo-Tools/Modules
+    base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    assets_dir = os.path.join(base_dir, "assets", "supertonic")
+    
+    if not os.path.exists(assets_dir):
+        print(f"Downloading Supertonic models to {assets_dir}...")
+        snapshot_download(repo_id="Supertone/supertonic", local_dir=assets_dir)
+    
+    onnx_dir = os.path.join(assets_dir, "onnx")
+    tts = load_text_to_speech(onnx_dir, use_gpu=False)
+    
+    _SUPERTONIC_STATE.update({"initialized": True, "tts": tts, "assets_dir": assets_dir})
+
+
+def get_supertonic_voices() -> list[str]:
+    # We need assets to list voices. If not initialized, try to find them or init.
+    if not _SUPERTONIC_STATE["initialized"]:
+        # Check if assets exist without full init
+        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        assets_dir = os.path.join(base_dir, "assets", "supertonic")
+        if not os.path.exists(assets_dir):
+             # If we can't list, return a default list or empty
+             return ["F1", "F2", "M1", "M2"] # Known defaults
+    else:
+        assets_dir = _SUPERTONIC_STATE["assets_dir"]
+
+    voice_styles_dir = os.path.join(assets_dir, "voice_styles")
+    if not os.path.exists(voice_styles_dir):
+        return ["F1", "F2", "M1", "M2"]
+        
+    files = os.listdir(voice_styles_dir)
+    voices = [f.replace('.json', '') for f in files if f.endswith('.json')]
+    return sorted(voices)
+
+
+def List_Kokoro_Voices() -> list[str]:
+    return get_kokoro_voices()
+
+def List_Supertonic_Voices() -> list[str]:
+    return get_supertonic_voices()
+
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Synthesize speech from text using Supertonic-66M (default) or Kokoro-82M. "
+    "Supertonic: faster, supports steps/silence/chunking. "
+    "Kokoro: slower, supports many languages/accents. "
+    "Return the generated media to the user in this format `![Alt text](URL)`."
+)
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Generate_Speech(
+    text: Annotated[str, "The text to synthesize (English)."],
+    model: Annotated[str, "The TTS model to use: 'Supertonic' or 'Kokoro'."] = "Supertonic",
+    speed: Annotated[float, "Speech speed multiplier in 0.5–2.0; 1.0 = normal speed."] = 1.3,
+    steps: Annotated[int, "Supertonic only. Diffusion steps (1-50). Higher = better quality but slower."] = 5,
+    voice: Annotated[str, "Voice identifier. Default 'F1' for Supertonic, 'af_heart' for Kokoro."] = "F1",
+    silence_duration: Annotated[float, "Supertonic only. Silence duration between chunks (0.0-2.0s)."] = 0.3,
+    max_chunk_size: Annotated[int, "Supertonic only. Max text chunk length (50-1000)."] = 300,
+) -> str:
+    _log_call_start("Generate_Speech", text=_truncate_for_log(text, 200), model=model, speed=speed, voice=voice)
+    
+    if not text or not text.strip():
+        try:
+            _log_call_end("Generate_Speech", "error=empty text")
+        finally:
+            pass
+        raise gr.Error("Please provide non-empty text to synthesize.")
+
+    model_lower = model.lower()
+    
+    # Handle default voice switching if user didn't specify appropriate voice for model
+    if model_lower == "kokoro" and voice == "F1":
+        voice = "af_heart"
+    elif model_lower == "supertonic" and voice == "af_heart":
+        voice = "F1"
+
+    try:
+        if model_lower == "kokoro":
+            return _generate_kokoro(text, speed, voice)
+        else:
+            # Default to Supertonic
+            return _generate_supertonic(text, speed, voice, steps, silence_duration, max_chunk_size)
+            
+    except gr.Error as exc:
+        _log_call_end("Generate_Speech", f"gr_error={str(exc)}")
+        raise
+    except Exception as exc:  # pylint: disable=broad-except
+        _log_call_end("Generate_Speech", f"error={str(exc)[:120]}")
+        raise gr.Error(f"Error during speech generation: {exc}")
+
+
+def _generate_kokoro(text: str, speed: float, voice: str) -> str:
+    _init_kokoro()
+    model = _KOKORO_STATE["model"]
+    pipelines = _KOKORO_STATE["pipelines"]
+    pipeline = pipelines.get("a")
+    if pipeline is None:
+        raise gr.Error("Kokoro English pipeline not initialized.")
+    
+    audio_segments = []
+    pack = pipeline.load_voice(voice)
+    
+    segments = list(pipeline(text, voice, speed))
+    total_segments = len(segments)
+    for segment_idx, (text_chunk, ps, _) in enumerate(segments):
+        ref_s = pack[len(ps) - 1]
+        try:
+            audio = model(ps, ref_s, float(speed))
+            audio_segments.append(audio.detach().cpu().numpy())
+            if total_segments > 10 and (segment_idx + 1) % 5 == 0:
+                print(f"Progress: Generated {segment_idx + 1}/{total_segments} segments...")
+        except Exception as exc:
+            raise gr.Error(f"Error generating audio for segment {segment_idx + 1}: {exc}")
+            
+    if not audio_segments:
+        raise gr.Error("No audio was generated (empty synthesis result).")
+        
+    if len(audio_segments) == 1:
+        final_audio = audio_segments[0]
+    else:
+        final_audio = np.concatenate(audio_segments, axis=0)
+        if total_segments > 1:
+            duration = len(final_audio) / 24_000
+            print(f"Completed: {total_segments} segments concatenated into {duration:.1f} seconds of audio")
+    
+    # Save to file
+    filename = f"speech_kokoro_{uuid.uuid4().hex[:8]}.wav"
+    output_path = os.path.join(ROOT_DIR, filename)
+    
+    # Normalize to 16-bit PCM
+    audio_int16 = (final_audio * 32767).astype(np.int16)
+    scipy.io.wavfile.write(output_path, 24000, audio_int16)
+    
+    _log_call_end("Generate_Speech", f"saved_to={os.path.basename(output_path)} duration_sec={len(final_audio)/24_000:.2f}")
+    return output_path
+
+
+def _generate_supertonic(text: str, speed: float, voice: str, steps: int, silence_duration: float, max_chunk_size: int) -> str:
+    _init_supertonic()
+    tts = _SUPERTONIC_STATE["tts"]
+    assets_dir = _SUPERTONIC_STATE["assets_dir"]
+    
+    voice_path = os.path.join(assets_dir, "voice_styles", f"{voice}.json")
+    if not os.path.exists(voice_path):
+        # Fallback or error?
+        # Try to find if it's just a name mismatch or use default
+        if not os.path.exists(voice_path):
+             raise gr.Error(f"Voice style {voice} not found for Supertonic.")
+
+    style = load_voice_style([voice_path])
+    
+    sr = tts.sample_rate
+    
+    # Supertonic returns a generator of chunks, or we can use __call__ for full audio
+    # Using __call__ to get full audio for saving
+    # But __call__ returns (wav_cat, dur_cat)
+    
+    wav_cat, _ = tts(text, style, steps, speed, silence_duration, max_chunk_size)
+    
+    if wav_cat is None or wav_cat.size == 0:
+         raise gr.Error("No audio generated.")
+
+    # wav_cat is (1, samples) float32
+    final_audio = wav_cat.flatten()
+    
+    # Save to file
+    filename = f"speech_supertonic_{uuid.uuid4().hex[:8]}.wav"
+    output_path = os.path.join(ROOT_DIR, filename)
+    
+    audio_int16 = _audio_np_to_int16(final_audio)
+    scipy.io.wavfile.write(output_path, sr, audio_int16)
+    
+    _log_call_end("Generate_Speech", f"saved_to={os.path.basename(output_path)} duration_sec={len(final_audio)/sr:.2f}")
+    return output_path
+
+
+def build_interface() -> gr.Interface:
+    kokoro_voices = get_kokoro_voices()
+    supertonic_voices = get_supertonic_voices()
+    all_voices = sorted(list(set(kokoro_voices + supertonic_voices)))
+
+    return gr.Interface(
+        fn=Generate_Speech,
+        inputs=[
+            gr.Textbox(label="Text", placeholder="Type text to synthesize…", lines=4, info="The text to synthesize (English)"),
+            gr.Dropdown(label="Model", choices=["Supertonic", "Kokoro"], value="Supertonic", info="The TTS model to use"),
+            gr.Slider(minimum=0.5, maximum=2.0, value=1.3, step=0.1, label="Speed", info="Speech speed multiplier (1.0 = normal)"),
+            gr.Slider(minimum=1, maximum=50, value=5, step=1, label="Steps", info="Supertonic only: Diffusion steps (1-50)"),
+            gr.Dropdown(
+                label="Voice",
+                choices=all_voices,
+                value="F1",
+                info="Select voice (F1/F2/M1/M2 for Supertonic, others for Kokoro)",
+            ),
+            gr.Slider(minimum=0.0, maximum=2.0, value=0.3, step=0.1, label="Silence Duration", info="Supertonic only: Silence duration between chunks"),
+            gr.Slider(minimum=50, maximum=1000, value=300, step=10, label="Max Chunk Size", info="Supertonic only: Max text chunk length"),
+        ],
+        outputs=gr.Audio(label="Audio", type="filepath", format="wav"),
+        title="Generate Speech",
+        description=(
+            "<div style=\"text-align:center\">Generate speech with Supertonic-66M or Kokoro-82M. Runs on CPU.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Generate_Speech", "List_Kokoro_Voices", "List_Supertonic_Voices", "build_interface"]

Modules/Generate_Video.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import os
+import uuid
+import random
+import tempfile
+from typing import Annotated
+
+import gradio as gr
+from huggingface_hub import InferenceClient
+from .File_System import ROOT_DIR
+
+from app import _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+HF_VIDEO_TOKEN = os.getenv("HF_READ_TOKEN") or os.getenv("HF_TOKEN")
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Generate a short MP4 video from a text prompt via Hugging Face serverless inference; "
+    "control model, steps, guidance, seed, size, fps, and duration; returns a temporary MP4 file path. "
+    "Return the generated media to the user in this format `![Alt text](URL)`."
+)
+
+
+def _write_video_tmp(data_iter_or_bytes: object, suffix: str = ".mp4") -> str:
+    filename = f"video_{uuid.uuid4().hex[:8]}{suffix}"
+    path = os.path.join(ROOT_DIR, filename)
+    try:
+        with open(path, "wb") as file:
+            if isinstance(data_iter_or_bytes, (bytes, bytearray)):
+                file.write(data_iter_or_bytes)
+            elif hasattr(data_iter_or_bytes, "read"):
+                file.write(data_iter_or_bytes.read())
+            elif hasattr(data_iter_or_bytes, "content"):
+                file.write(data_iter_or_bytes.content)  # type: ignore[attr-defined]
+            elif hasattr(data_iter_or_bytes, "__iter__") and not isinstance(data_iter_or_bytes, (str, dict)):
+                for chunk in data_iter_or_bytes:  # type: ignore[assignment]
+                    if chunk:
+                        file.write(chunk)
+            else:
+                raise gr.Error("Unsupported video data type returned by provider.")
+    except Exception:
+        try:
+            os.remove(path)
+        except Exception:
+            pass
+        raise
+    return path
+
+
+@autodoc(
+    summary=TOOL_SUMMARY,
+)
+def Generate_Video(
+    prompt: Annotated[str, "Text description of the video to generate (e.g., 'a red fox running through a snowy forest at sunrise')."],
+    model_id: Annotated[str, "Hugging Face model id in the form 'creator/model-name'. Defaults to akhaliq/sora-2."] = "akhaliq/sora-2",
+    negative_prompt: Annotated[str, "What should NOT appear in the video."] = "",
+    steps: Annotated[int, "Number of denoising steps (1–100). Higher can improve quality but is slower."] = 25,
+    cfg_scale: Annotated[float, "Guidance scale (1–20). Higher = follow the prompt more closely, lower = more creative."] = 3.5,
+    seed: Annotated[int, "Random seed for reproducibility. Use -1 for a random seed per call."] = -1,
+    width: Annotated[int, "Output width in pixels (multiples of 8 recommended)."] = 768,
+    height: Annotated[int, "Output height in pixels (multiples of 8 recommended)."] = 768,
+    fps: Annotated[int, "Frames per second of the output video (e.g., 24)."] = 24,
+    duration: Annotated[float, "Target duration in seconds. For Sora-2, must be 4, 8, or 12."] = 4.0,
+) -> str:
+    _log_call_start(
+        "Generate_Video",
+        prompt=_truncate_for_log(prompt, 160),
+        model_id=model_id,
+        steps=steps,
+        cfg_scale=cfg_scale,
+        fps=fps,
+        duration=duration,
+        size=f"{width}x{height}",
+    )
+    if not prompt or not prompt.strip():
+        _log_call_end("Generate_Video", "error=empty prompt")
+        raise gr.Error("Please provide a non-empty prompt.")
+    providers = ["auto", "replicate", "fal-ai"]
+    last_error: Exception | None = None
+    parameters = {
+        "negative_prompt": negative_prompt or None,
+        "num_inference_steps": steps,
+        "guidance_scale": cfg_scale,
+        "seed": seed if seed != -1 else random.randint(1, 1_000_000_000),
+        "width": width,
+        "height": height,
+        "fps": fps,
+        "duration": duration,
+    }
+    for provider in providers:
+        try:
+            client = InferenceClient(api_key=HF_VIDEO_TOKEN, provider=provider)
+            if hasattr(client, "text_to_video"):
+                num_frames = int(duration * fps) if duration and fps else None
+                extra_body = {}
+                if width:
+                    extra_body["width"] = width
+                if height:
+                    extra_body["height"] = height
+                if fps:
+                    extra_body["fps"] = fps
+                if duration:
+                    extra_body["duration"] = duration
+                result = client.text_to_video(
+                    prompt=prompt,
+                    model=model_id,
+                    guidance_scale=cfg_scale,
+                    negative_prompt=[negative_prompt] if negative_prompt else None,
+                    num_frames=num_frames,
+                    num_inference_steps=steps,
+                    seed=parameters["seed"],
+                    extra_body=extra_body if extra_body else None,
+                )
+            else:
+                # Fallback for older clients or specific providers if needed, though InferenceClient usually has text_to_video
+                # Note: client.post is not available in some versions of InferenceClient
+                continue 
+            
+            path = _write_video_tmp(result, suffix=".mp4")
+            try:
+                size = os.path.getsize(path)
+            except Exception:
+                size = -1
+            _log_call_end("Generate_Video", f"provider={provider} path={os.path.basename(path)} bytes={size}")
+            return path
+        except KeyError as exc:
+            # Handle specific provider errors that manifest as KeyError (e.g. fal-ai missing 'video' key on error)
+            if "video" in str(exc):
+                last_error = ValueError(f"Provider {provider} returned an invalid response. This often happens with invalid parameters (e.g. duration must be 4, 8, or 12 for Sora-2).")
+            else:
+                last_error = exc
+            continue
+        except Exception as exc:  # pylint: disable=broad-except
+            last_error = exc
+            continue
+    msg = str(last_error) if last_error else "Unknown error"
+    lowered = msg.lower()
+    if "404" in msg:
+        raise gr.Error(f"Model not found or unavailable: {model_id}. Check the id and 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 ("api_key" in lowered) or ("hf auth login" in lowered) or ("unauthorized" in lowered) or ("forbidden" in lowered):
+        raise gr.Error("Please duplicate the space and provide a `HF_READ_TOKEN` to enable Image and Video Generation.")
+    _log_call_end("Generate_Video", f"error={_truncate_for_log(msg, 200)}")
+    raise gr.Error(f"Video generation failed: {msg}")
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Generate_Video,
+        inputs=[
+            gr.Textbox(label="Prompt", placeholder="Enter a prompt for the video", lines=2, info="Text description of the video to generate"),
+            gr.Textbox(
+                label="Model",
+                value="akhaliq/sora-2",
+                placeholder="creator/model-name",
+                max_lines=1,
+                info="<a href=\"https://huggingface.co/models?pipeline_tag=text-to-video&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="", lines=2, info="What should NOT appear in the video"),
+            gr.Slider(minimum=1, maximum=100, value=25, step=1, label="Steps", info="Number of denoising steps (1–100)"),
+            gr.Slider(minimum=1.0, maximum=20.0, value=3.5, step=0.1, label="CFG Scale", info="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=1920, value=768, step=8, label="Width", info="Output width in pixels"),
+            gr.Slider(minimum=64, maximum=1920, value=768, step=8, label="Height", info="Output height in pixels"),
+            gr.Slider(minimum=4, maximum=60, value=24, step=1, label="FPS", info="Frames per second"),
+            gr.Slider(minimum=1.0, maximum=10.0, value=4.0, step=0.5, label="Duration (s)", info="Target duration in seconds"),
+        ],
+        outputs=gr.Video(label="Generated Video", buttons=["download"], format="mp4"),
+        title="Generate Video",
+        description=(
+            "<div style=\"text-align:center\">Generate short videos via Hugging Face serverless inference. "
+            "Default model is Sora-2.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Generate_Video", "build_interface"]

Modules/Memory_Manager.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime
+from typing import Annotated, Dict, List, 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
+
+
+def _now_iso() -> str:
+    return datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S")
+
+
+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:
+        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
+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)."
+)
+
+
+@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,
+    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,
+    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,
+) -> str:
+    act = (action or "").lower().strip()
+    text = text or ""
+    tags = tags or ""
+    query = query or ""
+    memory_id = memory_id or ""
+    if act == "save":
+        if not text.strip():
+            return "Error: 'text' is required when action=save."
+        return _mem_save(text=text, tags=tags)
+    if act == "list":
+        return _mem_list(limit=limit, include_tags=include_tags)
+    if act == "search":
+        if not query.strip():
+            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)."
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Memory_Manager,
+        inputs=[
+            gr.Radio(label="Action", choices=["save", "list", "search", "delete"], value="list", 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.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)"),
+        ],
+        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>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = ["Memory_Manager", "build_interface", "_load_memories", "_save_memories"]

Modules/Obsidian_Vault.py

@@ -0,0 +1,495 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+from datetime import datetime
+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
+
+
+TOOL_SUMMARY = (
+    "Browse and search the Obsidian vault in read-only mode. "
+    "Actions: list, read, info, search, help. "
+    "All paths resolve within the vault root. Start paths with '/' (e.g., /Notes)."
+)
+
+HELP_TEXT = (
+    "Obsidian Vault — actions and usage\n\n"
+    "Root: Tools/Obsidian (override with OBSIDIAN_VAULT_ROOT). "
+    "Start paths with '/' to reference the vault root (e.g., /Projects/note.md). "
+    "Absolute paths are disabled unless UNSAFE_ALLOW_ABS_PATHS=1.\n\n"
+    "Actions and fields:\n"
+    "- list: path='/' (default), recursive=false, show_hidden=false, max_entries=20\n"
+    "- read: path (e.g., /Projects/note.md), offset=0, max_chars=4000 (shows next_cursor when truncated)\n"
+    "- info: path\n"
+    "- search: path (note or folder), query text in the Search field, recursive=false, show_hidden=false, max_entries=20, case_sensitive=false, offset=0\n"
+    "- help: show this guide\n\n"
+    "Errors are returned as JSON with fields: {status:'error', code, message, path?, hint?, data?}.\n\n"
+    "Examples:\n"
+    "- list current: action=list, path='/'\n"
+    "- read note: action=read, path='/Projects/note.md', max_chars=500\n"
+    "- show metadata: action=info, path='/Inbox'\n"
+    "- search notes: action=search, path='/Projects', query='deadline', recursive=true, max_entries=100\n"
+    "- case-sensitive search: action=search, query='TODO', case_sensitive=true\n"
+    "- page search results: action=search, query='TODO', offset=20\n"
+)
+
+
+def _default_root() -> str:
+    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())
+
+
+ROOT_DIR = _default_root()
+try:
+    os.makedirs(ROOT_DIR, exist_ok=True)
+except Exception:
+    pass
+ALLOW_ABS = bool(int(os.getenv("UNSAFE_ALLOW_ABS_PATHS", "0")))
+
+
+def _safe_err(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 = ROOT_DIR.replace("\\", "/")
+    root_variants = {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(code: str, message: str, *, path: str | None = None, hint: str | None = None, data: dict | None = None) -> str:
+    payload = {
+        "status": "error",
+        "code": code,
+        "message": message,
+        "root": "/",
+    }
+    if path:
+        payload["path"] = path
+    if hint:
+        payload["hint"] = hint
+    if data:
+        payload["data"] = data
+    return json.dumps(payload, ensure_ascii=False)
+
+
+def _display_path(abs_path: str) -> str:
+    try:
+        norm_root = os.path.normpath(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(path: str) -> tuple[str, str]:
+    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 ALLOW_ABS:
+                return "", _err(
+                    "absolute_path_disabled",
+                    "Absolute paths are disabled in safe mode.",
+                    path=raw.replace("\\", "/"),
+                    hint="Use a path relative to / (e.g., /Notes/index.md).",
+                )
+            abs_path = os.path.abspath(raw)
+        else:
+            abs_path = os.path.abspath(os.path.join(ROOT_DIR, raw))
+        if not ALLOW_ABS:
+            try:
+                common = os.path.commonpath([os.path.normpath(ROOT_DIR), os.path.normpath(abs_path)])
+            except Exception:
+                root_cmp = os.path.normcase(os.path.normpath(ROOT_DIR))
+                abs_cmp = os.path.normcase(os.path.normpath(abs_path))
+                if not abs_cmp.startswith(root_cmp):
+                    return "", _err(
+                        "path_outside_root",
+                        "Path not allowed outside root.",
+                        path=user_input.replace("\\", "/"),
+                        hint="Use a path under / (the vault root).",
+                    )
+            else:
+                root_cmp = os.path.normcase(os.path.normpath(ROOT_DIR))
+                common_cmp = os.path.normcase(os.path.normpath(common))
+                if common_cmp != root_cmp:
+                    return "", _err(
+                        "path_outside_root",
+                        "Path not allowed outside root.",
+                        path=user_input.replace("\\", "/"),
+                        hint="Use a path under / (the vault root).",
+                    )
+        return abs_path, ""
+    except Exception as exc:
+        return "", _err(
+            "resolve_path_failed",
+            "Failed to resolve path.",
+            path=(path or ""),
+            data={"error": _safe_err(exc)},
+        )
+
+
+def _fmt_size(num_bytes: int) -> str:
+    units = ["B", "KB", "MB", "GB", "TB"]
+    size = float(num_bytes)
+    for unit in units:
+        if size < 1024.0:
+            return f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} PB"
+
+
+def _list_dir(abs_path: str, *, show_hidden: bool, recursive: bool, max_entries: int) -> str:
+    lines: list[str] = []
+    total = 0
+    listing_display = _display_path(abs_path)
+    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('.')]
+        try:
+            rel_root = os.path.relpath(root, ROOT_DIR)
+        except Exception:
+            rel_root = root
+        rel_root_disp = "/" if rel_root == "." else "/" + rel_root.replace("\\", "/")
+        lines.append(f"\n📂 {rel_root_disp}")
+        dirs.sort()
+        files.sort()
+        for d in dirs:
+            p = os.path.join(root, d)
+            try:
+                mtime = datetime.fromtimestamp(os.path.getmtime(p)).isoformat(sep=' ', timespec='seconds')
+            except Exception:
+                mtime = "?"
+            lines.append(f"  • [DIR] {d}    (modified {mtime})")
+            total += 1
+            if total >= max_entries:
+                lines.append(f"\n… Truncated at {max_entries} entries.")
+                return "\n".join(lines).strip()
+        for f in files:
+            p = os.path.join(root, f)
+            try:
+                size = _fmt_size(os.path.getsize(p))
+                mtime = datetime.fromtimestamp(os.path.getmtime(p)).isoformat(sep=' ', timespec='seconds')
+            except Exception:
+                size, mtime = "?", "?"
+            lines.append(f"  • {f}    ({size}, modified {mtime})")
+            total += 1
+            if total >= max_entries:
+                lines.append(f"\n… Truncated at {max_entries} entries.")
+                return "\n".join(lines).strip()
+        if not recursive:
+            break
+    header = f"Listing of {listing_display}\nRoot: /\nEntries: {total}"
+    return (header + "\n" + "\n".join(lines)).strip()
+
+
+def _search_text(
+    abs_path: str,
+    query: str,
+    *,
+    recursive: bool,
+    show_hidden: bool,
+    max_results: int,
+    case_sensitive: bool,
+    start_index: int,
+) -> str:
+    if not os.path.exists(abs_path):
+        return _err("path_not_found", f"Path not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+
+    query = query or ""
+    normalized_query = query if case_sensitive else query.lower()
+    if normalized_query == "":
+        return _err(
+            "missing_search_query",
+            "Search query is required for the search action.",
+            hint="Provide text in the Search field to look 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((_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"{_display_path(file_path)} ({_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: {_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(abs_path: str, *, offset: int, max_chars: int) -> str:
+    if not os.path.exists(abs_path):
+        return _err("file_not_found", f"File not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+    if os.path.isdir(abs_path):
+        return _err(
+            "is_directory",
+            f"Path is a directory, not a file: {_display_path(abs_path)}",
+            path=_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 _err("read_failed", "Failed to read file.", path=_display_path(abs_path), data={"error": _safe_err(exc)})
+    total = len(data)
+    start = max(0, min(offset, total))
+    end = total if max_chars <= 0 else min(total, start + max_chars)
+    chunk = data[start:end]
+    next_cursor = end if end < total else None
+    header = (
+        f"Reading {_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 "")
+    )
+    return header + "\n\n---\n\n" + chunk
+
+
+def _info(abs_path: str) -> str:
+    try:
+        st = os.stat(abs_path)
+    except Exception as exc:
+        return _err("stat_failed", "Failed to stat path.", path=_display_path(abs_path), data={"error": _safe_err(exc)})
+    info = {
+        "path": _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, indent=2)
+
+
+@autodoc(summary=TOOL_SUMMARY)
+def Obsidian_Vault(
+    action: Annotated[str, "Operation to perform: 'list', 'read', 'info', 'search', 'help'."],
+    path: Annotated[str, "Target path, relative to the vault root." ] = "/",
+    query: Annotated[Optional[str], "Text to search for when action=search."] = None,
+    recursive: Annotated[bool, "Recurse into subfolders when listing/searching."] = False,
+    show_hidden: Annotated[bool, "Include hidden files when listing/searching."] = False,
+    max_entries: Annotated[int, "Max entries to list or matches to return (for list/search)."] = 20,
+    offset: Annotated[int, "Start offset when reading files."] = 0,
+    max_chars: Annotated[int, "Max characters to return when reading (0 = full file)."] = 4000,
+    case_sensitive: Annotated[bool, "Match case when searching text."] = False,
+) -> str:
+    _log_call_start(
+        "Obsidian_Vault",
+        action=action,
+        path=path,
+        query=query,
+        recursive=recursive,
+        show_hidden=show_hidden,
+        max_entries=max_entries,
+        offset=offset,
+        max_chars=max_chars,
+        case_sensitive=case_sensitive,
+    )
+    action = (action or "").strip().lower()
+    if action not in {"list", "read", "info", "search", "help"}:
+        result = _err(
+            "invalid_action",
+            "Invalid action.",
+            hint="Choose from: list, read, info, search, help.",
+        )
+        _log_call_end("Obsidian_Vault", _truncate_for_log(result))
+        return result
+
+    if action == "help":
+        result = HELP_TEXT
+        _log_call_end("Obsidian_Vault", _truncate_for_log(result))
+        return result
+
+    abs_path, err = _resolve_path(path)
+    if err:
+        _log_call_end("Obsidian_Vault", _truncate_for_log(err))
+        return err
+
+    try:
+        if action == "list":
+            if not os.path.exists(abs_path):
+                result = _err("path_not_found", f"Path not found: {_display_path(abs_path)}", path=_display_path(abs_path))
+            else:
+                result = _list_dir(abs_path, show_hidden=show_hidden, recursive=recursive, max_entries=max_entries)
+        elif action == "read":
+            result = _read_file(abs_path, offset=offset, max_chars=max_chars)
+        elif action == "search":
+            query_text = query or ""
+            if query_text.strip() == "":
+                result = _err(
+                    "missing_search_query",
+                    "Search query is required for the search action.",
+                    hint="Provide text in the Search field to look for.",
+                )
+            else:
+                result = _search_text(
+                    abs_path,
+                    query_text,
+                    recursive=recursive,
+                    show_hidden=show_hidden,
+                    max_results=max_entries,
+                    case_sensitive=case_sensitive,
+                    start_index=offset,
+                )
+        else:  # info
+            result = _info(abs_path)
+    except Exception as exc:
+        result = _err("exception", "Unhandled error during operation.", data={"error": _safe_err(exc)})
+
+    _log_call_end("Obsidian_Vault", _truncate_for_log(result))
+    return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Obsidian_Vault,
+        inputs=[
+            gr.Radio(
+                label="Action",
+                choices=["list", "read", "info", "search", "help"],
+                value="help",
+                info="Operation to perform",
+            ),
+            gr.Textbox(label="Path", placeholder="/ or /Notes/todo.md", max_lines=1, value="/", info="Target path (relative to vault root)"),
+            gr.Textbox(label="Search text", lines=3, placeholder="Text to search for...", info="Text to search for (Search only)"),
+            gr.Checkbox(label="Recursive", value=False, info="Recurse into subfolders (List/Search)"),
+            gr.Checkbox(label="Show hidden", value=False, info="Include hidden files (List/Search)"),
+            gr.Slider(minimum=10, maximum=5000, step=10, value=20, label="Max entries / matches", info="Max entries to list or matches to return (List/Search)"),
+            gr.Slider(minimum=0, maximum=1_000_000, step=100, value=0, label="Offset", info="Start offset (Read/Search)"),
+            gr.Slider(minimum=0, maximum=100_000, step=500, value=4000, label="Max chars", info="Max characters to return (Read, 0=all)"),
+            gr.Checkbox(label="Case sensitive search", value=False, info="Match case (Search)"),
+        ],
+        outputs=gr.Textbox(label="Result", lines=20),
+        title="Obsidian Vault",
+        description=(
+            "<div style=\"text-align:center; overflow:hidden;\">Explore and search notes in the vault without modifying them." "</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+        submit_btn="Run",
+    )
+
+
+__all__ = ["Obsidian_Vault", "build_interface"]

Modules/Shell_Command.py

@@ -0,0 +1,139 @@
+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 .File_System import _resolve_path, ROOT_DIR, _display_path
+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
+
+    # 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_Fetch.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import re
+from typing import Annotated, Dict, Literal, Tuple
+from urllib.parse import urlparse, urljoin
+
+import gradio as gr
+import requests
+from bs4 import BeautifulSoup
+from markdownify import markdownify as md
+from readability import Document
+
+from app import _fetch_rate_limiter, _log_call_end, _log_call_start, _truncate_for_log
+from ._docstrings import autodoc
+
+
+# Single source of truth for the LLM-facing tool description
+TOOL_SUMMARY = (
+    "Fetch a webpage and return clean Markdown, raw HTML, or a list of links, with max length and pagination via "
+    "offset; if truncated, the output includes a notice with next_cursor for exact continuation."
+)
+
+ModeOption = Literal["markdown", "html", "url_scraper"]
+
+
+def _http_get_enhanced(url: str, timeout: int | float = 30, *, skip_rate_limit: bool = False) -> requests.Response:
+    headers = {
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+        "Accept-Language": "en-US,en;q=0.9",
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+        "Accept-Encoding": "gzip, deflate, br",
+        "DNT": "1",
+        "Connection": "keep-alive",
+        "Upgrade-Insecure-Requests": "1",
+    }
+    if not skip_rate_limit:
+        _fetch_rate_limiter.acquire()
+    try:
+        response = requests.get(
+            url,
+            headers=headers,
+            timeout=timeout,
+            allow_redirects=True,
+            stream=False,
+        )
+        response.raise_for_status()
+        return response
+    except requests.exceptions.Timeout as exc:
+        raise requests.exceptions.RequestException("Request timed out. The webpage took too long to respond.") from exc
+    except requests.exceptions.ConnectionError as exc:
+        raise requests.exceptions.RequestException("Connection error. Please check the URL and your internet connection.") from exc
+    except requests.exceptions.HTTPError as exc:
+        if response.status_code == 403:
+            raise requests.exceptions.RequestException("Access forbidden. The website may be blocking automated requests.") from exc
+        if response.status_code == 404:
+            raise requests.exceptions.RequestException("Page not found. Please check the URL.") from exc
+        if response.status_code == 429:
+            raise requests.exceptions.RequestException("Rate limited. Please try again in a few minutes.") from exc
+        raise requests.exceptions.RequestException(f"HTTP error {response.status_code}: {exc}") from exc
+
+
+def _normalize_whitespace(text: str) -> str:
+    text = re.sub(r"[ \t\u00A0]+", " ", text)
+    text = re.sub(r"\n\s*\n\s*\n+", "\n\n", text.strip())
+    return text.strip()
+
+
+def _truncate(text: str, max_chars: int) -> Tuple[str, bool]:
+    if max_chars is None or max_chars <= 0 or len(text) <= max_chars:
+        return text, False
+    return text[:max_chars].rstrip() + " …", True
+
+
+def _shorten(text: str, limit: int) -> str:
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[: max(0, limit - 1)].rstrip() + "…"
+
+
+def _domain_of(url: str) -> str:
+    try:
+        return urlparse(url).netloc or ""
+    except Exception:
+        return ""
+
+
+def _normalize_mode(mode: str | None) -> ModeOption:
+    """Convert UI-supplied labels into canonical mode values."""
+    if not mode:
+        return "markdown"
+    normalized = mode.strip().lower()
+    normalized = normalized.replace("-", "_").replace(" ", "_")
+    if normalized in {"markdown", "markdown_mode", "md"}:
+        return "markdown"
+    if normalized in {"html", "html_mode"}:
+        return "html"
+    if normalized in {"url_scraper", "urlscraper", "url_mode", "scraper", "links", "link_mode"}:
+        return "url_scraper"
+    return "markdown"
+
+
+def _extract_links_from_soup(soup: BeautifulSoup, base_url: str) -> str:
+    links = []
+    for link in soup.find_all("a", href=True):
+        href = link.get("href")
+        text = link.get_text(strip=True)
+        if href.startswith("http"):
+            full_url = href
+        elif href.startswith("//"):
+            full_url = "https:" + href
+        elif href.startswith("/"):
+            full_url = urljoin(base_url, href)
+        else:
+            full_url = urljoin(base_url, href)
+        if text and href not in ["#", "javascript:void(0)"]:
+            links.append(f"- [{text}]({full_url})")
+    if not links:
+        return "No links found on this page."
+    title = soup.find("title")
+    title_text = title.get_text(strip=True) if title else "Links from webpage"
+    return f"# {title_text}\n\n" + "\n".join(links)
+
+
+def _fullpage_markdown_from_soup(full_soup: BeautifulSoup, base_url: str, strip_selectors: str = "") -> str:
+    if strip_selectors:
+        selectors = [s.strip() for s in strip_selectors.split(",") if s.strip()]
+        for selector in selectors:
+            try:
+                for element in full_soup.select(selector):
+                    element.decompose()
+            except Exception:
+                continue
+    for element in full_soup.select("script, style, nav, footer, header, aside"):
+        element.decompose()
+    main = (
+        full_soup.find("main")
+        or full_soup.find("article")
+        or full_soup.find("div", class_=re.compile(r"content|main|post|article", re.I))
+        or full_soup.find("body")
+    )
+    if not main:
+        return "No main content found on the webpage."
+    markdown_text = md(str(main), heading_style="ATX")
+    markdown_text = re.sub(r"\n{3,}", "\n\n", markdown_text)
+    markdown_text = re.sub(r"\[\s*\]\([^)]*\)", "", markdown_text)
+    markdown_text = re.sub(r"[ \t]+", " ", markdown_text)
+    markdown_text = markdown_text.strip()
+    title = full_soup.find("title")
+    if title and title.get_text(strip=True):
+        markdown_text = f"# {title.get_text(strip=True)}\n\n{markdown_text}"
+    return markdown_text or "No content could be extracted."
+
+
+def _truncate_with_notice(content: str, max_chars: int) -> Tuple[str, Dict[str, object]]:
+    total_chars = len(content)
+    if total_chars <= max_chars:
+        return content, {
+            "truncated": False,
+            "returned_chars": total_chars,
+            "total_chars_estimate": total_chars,
+            "next_cursor": None,
+        }
+    truncated = content[:max_chars]
+    last_paragraph = truncated.rfind("\n\n")
+    if last_paragraph > max_chars * 0.7:
+        truncated = truncated[:last_paragraph]
+        cursor_pos = last_paragraph
+    elif "." in truncated[-100:]:
+        last_period = truncated.rfind(".")
+        if last_period > max_chars * 0.8:
+            truncated = truncated[: last_period + 1]
+            cursor_pos = last_period + 1
+        else:
+            cursor_pos = len(truncated)
+    else:
+        cursor_pos = len(truncated)
+    metadata = {
+        "truncated": True,
+        "returned_chars": len(truncated),
+        "total_chars_estimate": total_chars,
+        "next_cursor": cursor_pos,
+    }
+    truncated = truncated.rstrip()
+    truncation_notice = (
+        "\n\n---\n"
+        f"**Content Truncated:** Showing {metadata['returned_chars']:,} of {metadata['total_chars_estimate']:,} characters "
+        f"({(metadata['returned_chars']/metadata['total_chars_estimate']*100):.1f}%)\n"
+        f"**Next cursor:** {metadata['next_cursor']} (use this value with offset parameter for continuation)\n"
+        "---"
+    )
+    return truncated + truncation_notice, metadata
+
+
+@autodoc(summary=TOOL_SUMMARY)
+def Web_Fetch(
+    url: Annotated[str, "The absolute URL to fetch (must return HTML)."],
+    max_chars: Annotated[int, "Maximum characters to return (0 = no limit, full page content)."] = 3000,
+    offset: Annotated[int, "Character offset to start from (for pagination, use next_cursor from previous call)."] = 0,
+    strip_selectors: Annotated[str, "CSS selectors to remove (comma-separated, e.g., '.header, .footer, nav')."] = "",
+    mode: Annotated[
+        str,
+        "Output mode: 'markdown' (default, clean content), 'html' (raw response), or 'url_scraper' (links list).",
+    ] = "markdown",
+) -> str:
+    canonical_mode = _normalize_mode(mode)
+    _log_call_start(
+        "Web_Fetch",
+        url=url,
+        max_chars=max_chars,
+        strip_selectors=strip_selectors,
+        mode=canonical_mode,
+        offset=offset,
+    )
+    if not url or not url.strip():
+        result = "Please enter a valid URL."
+        _log_call_end("Web_Fetch", _truncate_for_log(result))
+        return result
+    try:
+        resp = _http_get_enhanced(url)
+        resp.raise_for_status()
+    except requests.exceptions.RequestException as exc:
+        result = f"An error occurred: {exc}"
+        _log_call_end("Web_Fetch", _truncate_for_log(result))
+        return result
+    final_url = str(resp.url)
+    ctype = resp.headers.get("Content-Type", "")
+    if "html" not in ctype.lower():
+        result = f"Unsupported content type for extraction: {ctype or 'unknown'}"
+        _log_call_end("Web_Fetch", _truncate_for_log(result))
+        return result
+    resp.encoding = resp.encoding or resp.apparent_encoding
+    html = resp.text
+    full_soup = BeautifulSoup(html, "lxml")
+    if canonical_mode == "html":
+        _log_call_end("Web_Fetch", f"chars={len(html)}, mode={canonical_mode}, offset=0 (ignored)")
+        return html
+    if canonical_mode == "markdown":
+        full_result = _fullpage_markdown_from_soup(full_soup, final_url, strip_selectors)
+    elif canonical_mode == "url_scraper":
+        full_result = _extract_links_from_soup(full_soup, final_url)
+    else:
+        full_result = html
+
+    if offset > 0:
+        if offset >= len(full_result):
+            result = (
+                f"Offset {offset} exceeds content length ({len(full_result)} characters). "
+                f"Content ends at position {len(full_result)}."
+            )
+            _log_call_end("Web_Fetch", _truncate_for_log(result))
+            return result
+        result = full_result[offset:]
+    else:
+        result = full_result
+
+    if max_chars > 0 and len(result) > max_chars:
+        result, metadata = _truncate_with_notice(result, max_chars)
+        if offset > 0:
+            metadata["total_chars_estimate"] = len(full_result)
+            metadata["next_cursor"] = offset + metadata["next_cursor"] if metadata["next_cursor"] else None
+
+    _log_call_end("Web_Fetch", f"chars={len(result)}, mode={canonical_mode}, offset={offset}")
+    return result
+
+
+def build_interface() -> gr.Interface:
+    return gr.Interface(
+        fn=Web_Fetch,
+        inputs=[
+            gr.Textbox(label="URL", placeholder="https://example.com/article", max_lines=1),
+            gr.Slider(
+                minimum=0,
+                maximum=10000,
+                value=3000,
+                step=100,
+                label="Max Characters",
+                info="0 = no limit (full page), default 3000",
+            ),
+            gr.Slider(
+                minimum=0,
+                maximum=100000,
+                value=0,
+                step=100,
+                label="Offset",
+                info="Character offset to start from (use next_cursor from previous call for pagination)",
+            ),
+            gr.Textbox(
+                label="Strip Selectors",
+                placeholder=".header, .footer, nav, .sidebar",
+                value="",
+                max_lines=1,
+                info="CSS selectors to remove (comma-separated)",
+            ),
+            gr.Radio(
+                label="Mode",
+                choices=["Markdown Mode", "HTML Mode", "URL Scraper"],
+                value="Markdown Mode",
+                info="Markdown cleans content, HTML returns raw response, URL Scraper lists links.",
+            ),
+        ],
+        outputs=gr.Markdown(label="Extracted Content"),
+        title="Web Fetch",
+        description=(
+            "<div style=\"text-align:center\">Convert any webpage to Markdown, inspect the raw HTML response, or "
+            "extract all links. Supports custom element removal, length limits, and pagination with offset.</div>"
+        ),
+        api_description=TOOL_SUMMARY,
+        flagging_mode="never",
+    )
+
+
+__all__ = [
+    "Web_Fetch",
+    "build_interface",
+    "_http_get_enhanced",
+    "_fullpage_markdown_from_soup",
+]

Modules/Web_Search.py

@@ -0,0 +1,499 @@
+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"]

Modules/__init__.py

@@ -0,0 +1 @@
+"""Gradio tool modules bundled for Nymbo-Tools."""

Modules/_docstrings.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import inspect
+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 _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:
+        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"]

Obsidian/demo.md

@@ -0,0 +1,3 @@
+# Hello, World
+
+Clone this server locally and set your Obsidian vault's root path as an environment variable `OBSIDIAN_VAULT_ROOT` to access your own files.

README.md

@@ -1,12 +1,216 @@
 ---
-title: Clone Tools
-emoji: 📚
-colorFrom: purple
+title: Nymbo Tools MCP
+emoji: ⚙️
+colorFrom: green
 colorTo: gray
 sdk: gradio
-sdk_version: 6.0.2
+sdk_version: 6.0.0
 app_file: app.py
-pinned: false
+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.
+- 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).
+- url_scraper (bool): If true, return only a list of links from the page.
+- offset (int): Character offset for pagination; pass the previous next_cursor to continue.
+
+Output: Markdown string. 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 akhaliq/sora-2
+- 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, mkdir, move, copy, delete, info, help
+
+Key fields:
+- path, content (write/append), dest_path (move/copy), recursive, show_hidden, max_entries, offset, max_chars, create_dirs, overwrite
+
+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).
+
+## 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

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+# Project by Nymbo
+
+import json
+import os
+import sys
+import threading
+import time
+from datetime import datetime, timedelta
+from typing import Any
+
+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()}
+        print(f"[TOOL CALL] {func_name} inputs: {json.dumps(compact, ensure_ascii=False)[:800]}", flush=True)
+    except Exception as exc:
+        print(f"[TOOL CALL] {func_name} (failed to log inputs: {exc})", flush=True)
+
+
+def _log_call_end(func_name: str, output_desc: str) -> None:
+    try:
+        print(f"[TOOL RESULT] {func_name} output: {output_desc}", flush=True)
+    except Exception as exc:
+        print(f"[TOOL RESULT] {func_name} (failed to log output: {exc})", flush=True)
+
+# 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.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
+
+# Optional environment flags used to conditionally show API schemas (unchanged behavior)
+HF_IMAGE_TOKEN = bool(os.getenv("HF_READ_TOKEN"))
+HF_VIDEO_TOKEN = bool(os.getenv("HF_READ_TOKEN") or os.getenv("HF_TOKEN"))
+HF_TEXTGEN_TOKEN = bool(os.getenv("HF_READ_TOKEN") or os.getenv("HF_TOKEN"))
+
+# Load CSS from external file
+_css_path = os.path.join(os.path.dirname(__file__), "styles.css")
+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()
+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()
+
+_interfaces = [
+    agent_terminal_interface,
+    fetch_interface,
+    web_search_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",
+    "Web Fetch",
+    "Web Search",
+    "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;'>General purpose tools useful for any agent.</p>\n<code style='font-size: 0.7rem; word-break: break-all;'>https://nymbo.net/gradio_api/mcp/</code>")
+        
+        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.net/gradio_api/mcp/</code>
+                                </p>
+                                <p>Example client configuration:</p>
+                                <pre><code class="language-json">{
+  "mcpServers": {
+    "nymbo-tools": {
+      "url": "https://nymbo.net/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>
+                                <p>
+                                    The <code>Generate_Image</code>, <code>Generate_Video</code>, and <code>Deep_Research</code> tools require a
+                                    <code>HF_READ_TOKEN</code> set as a secret or environment variable.
+                                </p>
+                                <ul class="info-list">
+                                    <li>Duplicate this Space and add a HF token with model read access.</li>
+                                    <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.
+                                </div>
+                            </div>
+                        </section>
+
+                        <section class="info-card">
+                            <div class="info-card__body">
+                                <h3>Persistent Memories and Files</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.
+                                </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.
+                                </p>
+                            </div>
+                        </section>
+
+                        <section class="info-card">
+                            <div class="info-card__body">
+                                <h3>Tool Notes &amp; Kokoro Voice Legend</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>
+                                </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>
+                            </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)

memories.json

@@ -0,0 +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"
+  }
+]

requirements.txt

@@ -0,0 +1,14 @@
+gradio[mcp]==6.0.0
+requests
+beautifulsoup4
+lxml
+readability-lxml
+ddgs
+kokoro>=0.9.4
+numpy
+torch; platform_system != "Darwin" or platform_machine != "arm64"
+Pillow
+huggingface_hub>=0.30.0
+markdownify
+scipy
+onnxruntime

styles.css

@@ -0,0 +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);
+    }
+}
+/* stylelint-enable compat-api/css */