MundoNano Local Research Agent

This project was built with AI assistance for the Hugging Face Agents Course.
This Space hosts source code and documentation. Inference runs locally in Ollama,
not on this static Space. No certification or score is claimed by this page.

Requirements: Python 3.12+, Ollama with a tool-capable model installed.
Only the Python standard library is required.

Reproduce:
  python -m unittest -v
  python fetch_questions.py
  python evaluate.py --model gemma4:26b-a4b-it-qat --output evaluation-v3-results.json
  python finalize.py --input evaluation-v3-results.json

Tools: bounded arithmetic, public HTTPS pages, public web and Wikipedia search,
Wikipedia section retrieval, text reversal, and read-only registered attachments.
The final formatter extracts the model's own answer without providing solutions.
No benchmark answer keys or fixed task answers are included.

Optional interactive public-web bridge (bridge.py):
Set AGENT_BRIDGE_DIR to a private local folder. The local model writes search/open
requests under requests/. An interactive Codex host executes the exact requested
query with its public web search/browser tool and writes the unedited tool response
under responses/<id>.json as {"id": "same id", "result": "tool response"}.
This mode requires an active host and its search access; it is not a standalone
free search API. The host does not solve tasks or insert answers. Source selection
and final answers remain model outputs. Full tool responses remain in local logs.
Set AGENT_THINK=true to enable model reasoning; AGENT_CONTEXT and AGENT_TOKENS
optionally control the Ollama context and generation limits. Both default to
16384 and 4096 respectively. CPU is the default. AGENT_GPU_LAYERS optionally
offloads layers to an available GPU; choose this according to your free VRAM.
The evidence bridge and local-only runs must be labeled separately when reported.

Optional final reasoning stage:
  python synthesize.py --input evaluation-v6-bridge.json --output evaluation-v7-synthesized.json --model qwen3.5:9b
This second model pass receives the original task, the draft, and bounded relevant
passages from the actual retrieval trace. It checks constraints and can complete
an answer when the tool loop ended before synthesis. It cannot fetch new facts.
Original drafts, source traces, model names and timings remain in local output.
No human-written corrections, grading answers or task-specific answer tables are used.

Known limitations: the public attachment API returned 404 for tested files;
audio/video are not supported. General search can be unavailable and then falls
back to Wikipedia. Unsupported tasks and errors are recorded rather than guessed.
The small local models can still give incorrect answers. Evaluation is exact-match.

Security: URLs must resolve to public addresses, downloads are bounded, fetched
Python code is read as text and never executed. Model output is not executed.
No credentials or personal files are included in this repository.

Evaluation and local test logs are intentionally excluded from the public bundle.
Official instructions: https://huggingface.co/learn/agents-course/en/unit4/hands-on