| --- |
| title: OpenResearcher |
| emoji: 🏃 |
| colorFrom: purple |
| colorTo: green |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| OpenResearcher DeepSearch agent. Inference runs locally in this Space via |
| ZeroGPU by default; a cloud OpenAI-compatible endpoint is used only as a |
| backup if local inference fails. An "Inference Mode" switch in the sidebar |
| (Auto / Local only / Cloud only) lets you override this per request. The |
| agent also plans an explicit research goal (with a 1-5 vagueness rating) up |
| front and stops as soon as that goal is met, instead of always running to |
| the round limit. |
|
|
| ## Configuration (Space secrets, all optional) |
|
|
| | Secret | Description | |
| |---|---| |
| | `MODEL_NAME` | Local model to run via ZeroGPU. Defaults to `OpenResearcher/Nemotron-3-Nano-30B-A3B`. | |
| | `OPENAI_BASE_URL` | Cloud backup, used only if local inference errors out. Base URL of an OpenAI-compatible API; `/chat/completions` is appended automatically. | |
| | `OPENAI_MODEL` | Model name for the cloud backup. Defaults to `MODEL_NAME`. | |
| | `OPENAI_API_KEY` | Bearer token for the cloud backup. | |
| | `JINA_MCP_BASE_URL` | Self-hosted Jina MCP server. Used exclusively for web search (`search_web` tool) and as the primary scraping backend (`read_url` tool). Defaults to `https://leon4gr45-jina.hf.space`. Its own API key is configured on that server, so none is needed here. | |
| | `MAX_CONTEXT_TOKENS` | Fallback input budget (approx. tokens), only used if the context length can't be auto-detected. Defaults to `100000`. | |
|
|
| The ReAct loop's conversation history is kept under a per-model token |
| budget automatically. That budget is auto-detected once per run: for the |
| local model, straight from its loaded config (`max_position_embeddings` |
| etc.); for the cloud backup, by querying `{OPENAI_BASE_URL}/models` and |
| reading off whichever context-length field the server reports (e.g. vLLM's |
| `max_model_len`, OpenRouter's `context_length` - the plain OpenAI API |
| itself doesn't expose this, so falls back to `MAX_CONTEXT_TOKENS` there). |
| In Auto mode, the tighter of the two detected limits is used, since either |
| backend might end up serving the request. Older rounds get truncated |
| (recent rounds stay verbatim) before each generation call, and again as an |
| emergency retry if a "context length exceeded" error still slips through. |
|
|
| Web search uses only Jina's `search_web` tool. (A self-hosted SearXNG |
| instance was tried, but Hugging Face's abuse-detector auto-paused that |
| Space over a process-name/cmdline match on "searxng" — not viable here.) |
| Page fetching tries Jina's `read_url` first, then falls back to a direct |
| HTTP fetch, then to Serper's scrape API if a key is provided in the UI. |
|
|
| This Space requires ZeroGPU (or another GPU) hardware to run local model |
| inference. |
|
|
| Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference |
|
|
