Initialize Hugging Face Space starter

.env.example

@@ -0,0 +1,5 @@
+# Optional. For Hugging Face Inference API (free quota with your HF account).
+HF_TOKEN=hf_xxx
+
+# Default model shown in UI.
+DEFAULT_MODEL=Qwen/Qwen2.5-7B-Instruct

.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+
+# Logs / local files
+*.log
+.env
+.DS_Store

README.md

@@ -0,0 +1,57 @@
+---
+title: DeepResearch Space Starter
+emoji: 🔎
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.29.0
+app_file: app.py
+pinned: false
+---
+
+# DeepResearch Space Starter
+
+A standalone Hugging Face Space starter for a DeepResearch-style agent.
+
+It supports:
+- multi-turn reasoning loop
+- `search` tool (DuckDuckGo)
+- `visit` tool (webpage fetch + text extraction)
+- final answer in `<answer>...</answer>`
+- easy model replacement later
+
+## 1) Quick Start (Local)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+## 2) Deploy to Hugging Face Space
+
+1. Create a new Space (SDK = **Gradio**).
+2. Push this repository to the Space repository.
+3. In Space **Settings -> Secrets**, add:
+   - `HF_TOKEN` (recommended for stable free inference access)
+4. Optional Variables:
+   - `DEFAULT_MODEL` (default: `Qwen/Qwen2.5-7B-Instruct`)
+
+## 3) Free Model First, Your Model Later
+
+You can start with a free inference model, then switch by changing only env/config:
+
+- Current: `DEFAULT_MODEL=Qwen/Qwen2.5-7B-Instruct`
+- Later: set your own model name or API-compatible endpoint logic in `app.py` (`call_model` function).
+
+Recommended migration strategy:
+1. keep tool protocol unchanged (`<tool_call>`, `<tool_response>`, `<answer>`)
+2. replace only model adapter (`call_model`)
+3. keep UI and tool chain unchanged
+
+## 4) Notes
+
+- This is a lightweight starter, not a full production benchmark runner.
+- Web fetching quality depends on target website anti-bot rules and page structure.
+- For stronger reliability, add retry/backoff and persistent tool cache.

app.py

@@ -0,0 +1,292 @@
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+import gradio as gr
+import requests
+from bs4 import BeautifulSoup
+from duckduckgo_search import DDGS
+from huggingface_hub import InferenceClient
+
+
+DEFAULT_MODEL = os.getenv("DEFAULT_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+
+SYSTEM_PROMPT = """You are a Deep Research assistant.
+You can think step by step, use tools, and then return a final answer.
+
+Tool protocol:
+- To call a tool, output exactly one block:
+<tool_call>
+{"name":"search","arguments":{"query":"...","max_results":5}}
+</tool_call>
+or
+<tool_call>
+{"name":"visit","arguments":{"url":"...","max_chars":6000}}
+</tool_call>
+
+- When you are done, output:
+<answer>
+...final answer...
+</answer>
+
+Rules:
+- Use tools when needed, but avoid repeated calls to the same URL/query.
+- Cite useful URLs in your final answer.
+- If a tool fails, recover and continue.
+"""
+
+
+TOOL_RESPONSE_TEMPLATE = """<tool_response>
+{payload}
+</tool_response>"""
+
+
+@dataclass
+class AgentState:
+    searched_queries: List[str] = field(default_factory=list)
+    visited_urls: List[str] = field(default_factory=list)
+    trace: List[Dict[str, Any]] = field(default_factory=list)
+
+
+def extract_answer(text: str) -> Optional[str]:
+    match = re.search(r"<answer>\s*(.*?)\s*</answer>", text, flags=re.DOTALL | re.IGNORECASE)
+    return match.group(1).strip() if match else None
+
+
+def parse_tool_call(text: str) -> Tuple[Optional[str], Optional[Dict[str, Any]], Optional[str]]:
+    match = re.search(r"<tool_call>\s*(.*?)\s*</tool_call>", text, flags=re.DOTALL | re.IGNORECASE)
+    if not match:
+        return None, None, None
+    payload = match.group(1).strip()
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError:
+        return None, None, "Invalid JSON in <tool_call> block."
+
+    name = data.get("name")
+    arguments = data.get("arguments", {})
+    if not isinstance(name, str) or not isinstance(arguments, dict):
+        return None, None, "Invalid tool format. Expect name(str) and arguments(dict)."
+    return name, arguments, None
+
+
+def run_search(query: str, max_results: int = 5) -> Dict[str, Any]:
+    if not query.strip():
+        return {"ok": False, "error": "Search query cannot be empty."}
+    rows: List[Dict[str, str]] = []
+    with DDGS() as ddgs:
+        for item in ddgs.text(query, max_results=max_results):
+            rows.append(
+                {
+                    "title": item.get("title", ""),
+                    "href": item.get("href", ""),
+                    "body": item.get("body", ""),
+                }
+            )
+    return {"ok": True, "query": query, "results": rows}
+
+
+def _clean_html_to_text(html: str, max_chars: int) -> str:
+    soup = BeautifulSoup(html, "html.parser")
+    for tag in soup(["script", "style", "noscript"]):
+        tag.decompose()
+    text = soup.get_text(separator=" ", strip=True)
+    text = re.sub(r"\s+", " ", text)
+    return text[:max_chars]
+
+
+def run_visit(url: str, max_chars: int = 6000) -> Dict[str, Any]:
+    if not url.strip():
+        return {"ok": False, "error": "URL cannot be empty."}
+    try:
+        resp = requests.get(
+            url,
+            timeout=20,
+            headers={"User-Agent": "Mozilla/5.0 (compatible; DeepResearchSpace/1.0)"},
+        )
+        resp.raise_for_status()
+        content_type = resp.headers.get("content-type", "")
+        if "text/html" in content_type or "<html" in resp.text[:200].lower():
+            text = _clean_html_to_text(resp.text, max_chars=max_chars)
+        else:
+            text = resp.text[:max_chars]
+        return {"ok": True, "url": url, "content": text}
+    except Exception as exc:
+        return {"ok": False, "url": url, "error": str(exc)}
+
+
+def call_model(
+    client: InferenceClient,
+    messages: List[Dict[str, str]],
+    model: str,
+    temperature: float,
+    max_new_tokens: int,
+) -> str:
+    completion = client.chat_completion(
+        model=model,
+        messages=messages,
+        temperature=temperature,
+        max_tokens=max_new_tokens,
+    )
+    return completion.choices[0].message.content or ""
+
+
+def build_research_agent(
+    question: str,
+    model: str,
+    max_turns: int,
+    max_search_results: int,
+    temperature: float,
+) -> Tuple[str, str]:
+    token = os.getenv("HF_TOKEN")
+    client = InferenceClient(token=token)
+    state = AgentState()
+
+    messages: List[Dict[str, str]] = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": question},
+    ]
+
+    final_answer: Optional[str] = None
+
+    for turn in range(1, max_turns + 1):
+        model_output = call_model(
+            client=client,
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            max_new_tokens=1400,
+        )
+        messages.append({"role": "assistant", "content": model_output})
+        state.trace.append({"turn": turn, "assistant": model_output})
+
+        extracted_answer = extract_answer(model_output)
+        if extracted_answer:
+            final_answer = extracted_answer
+            break
+
+        tool_name, tool_args, tool_err = parse_tool_call(model_output)
+        if tool_err:
+            tool_response = {"ok": False, "error": tool_err}
+        elif not tool_name:
+            # No explicit tool call and no final answer: force finalization.
+            messages.append(
+                {
+                    "role": "user",
+                    "content": "No tool call detected. Provide your best final answer in <answer>...</answer> now.",
+                }
+            )
+            continue
+        else:
+            if tool_name == "search":
+                query = str(tool_args.get("query", "")).strip()
+                max_results = int(tool_args.get("max_results", max_search_results))
+                max_results = max(1, min(max_results, 10))
+                if query:
+                    state.searched_queries.append(query)
+                tool_response = run_search(query=query, max_results=max_results)
+            elif tool_name == "visit":
+                url = str(tool_args.get("url", "")).strip()
+                max_chars = int(tool_args.get("max_chars", 6000))
+                max_chars = max(500, min(max_chars, 20000))
+                if url:
+                    state.visited_urls.append(url)
+                tool_response = run_visit(url=url, max_chars=max_chars)
+            else:
+                tool_response = {"ok": False, "error": f"Unknown tool: {tool_name}"}
+
+        state.trace.append({"turn": turn, "tool": tool_name, "tool_response": tool_response})
+        messages.append(
+            {
+                "role": "user",
+                "content": TOOL_RESPONSE_TEMPLATE.format(
+                    payload=json.dumps(tool_response, ensure_ascii=False)
+                ),
+            }
+        )
+
+    if final_answer is None:
+        final_answer = (
+            "I could not finish a complete research answer within the configured turns. "
+            "Try increasing max turns or switching to a stronger model."
+        )
+
+    citations = "\n".join(f"- {url}" for url in sorted(set(state.visited_urls)))
+    if citations:
+        final_answer = f"{final_answer}\n\n### Visited Sources\n{citations}"
+
+    trace_text = json.dumps(
+        {
+            "searched_queries": state.searched_queries,
+            "visited_urls": state.visited_urls,
+            "trace": state.trace,
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+    return final_answer, trace_text
+
+
+def run_ui(
+    question: str,
+    model: str,
+    max_turns: int,
+    max_search_results: int,
+    temperature: float,
+):
+    if not question.strip():
+        return "Please input a question.", "{}"
+    try:
+        return build_research_agent(
+            question=question,
+            model=model,
+            max_turns=max_turns,
+            max_search_results=max_search_results,
+            temperature=temperature,
+        )
+    except Exception as exc:
+        return f"Error: {exc}", json.dumps({"error": str(exc)}, ensure_ascii=False, indent=2)
+
+
+with gr.Blocks(title="DeepResearch Space Starter") as demo:
+    gr.Markdown(
+        """
+# DeepResearch Space Starter
+Ask a question, and the agent will iteratively search and visit pages before producing a final answer.
+
+This starter uses a free HF Inference model by default. You can switch models later with environment variables.
+"""
+    )
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            question = gr.Textbox(
+                label="Question",
+                placeholder="e.g. Compare top open-source deep research agents and summarize differences.",
+                lines=4,
+            )
+            model = gr.Textbox(label="Model", value=DEFAULT_MODEL)
+            with gr.Row():
+                max_turns = gr.Slider(label="Max Turns", minimum=2, maximum=20, value=8, step=1)
+                max_search_results = gr.Slider(
+                    label="Search Results Per Query", minimum=1, maximum=10, value=5, step=1
+                )
+                temperature = gr.Slider(
+                    label="Temperature", minimum=0.0, maximum=1.5, value=0.4, step=0.1
+                )
+            run_btn = gr.Button("Run Research", variant="primary")
+        with gr.Column(scale=3):
+            answer = gr.Markdown(label="Final Answer")
+            trace = gr.Code(label="Trace (JSON)", language="json")
+
+    run_btn.click(
+        fn=run_ui,
+        inputs=[question, model, max_turns, max_search_results, temperature],
+        outputs=[answer, trace],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio==5.29.0
+huggingface_hub==0.31.2
+duckduckgo_search==8.0.1
+requests==2.32.3
+beautifulsoup4==4.12.3