Skip to content

About

Local research agent built on Ollama native tool calling: web search, calculator and file tools, with JSONL traces and citation validation.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Local Research Agent

A local research agent that plans, calls tools, observes their real outputs, and produces an evidence-cited answer. It uses Ollama's native tool-calling interface rather than parsing tool instructions from plain text.

What it can do

  • Search the live web and return result URLs and page excerpts.
  • Perform safe arithmetic and numeric comparisons with a calculator.
  • Read text, Markdown, CSV, and JSON files from the project's knowledge/ directory.
  • Save each run as an inspectable JSONL trace in traces/.

The agent uses one tool call per model response and follows the requested tool order. It has a maximum step count, per-tool call limit, repeated-call detection, and token and shadow-cost checks before each model call. Calculator inputs are checked against numbers in the task and actual tool results; unsupported numeric inputs are rejected. Citations to nonexistent evidence IDs invalidate the completion status.

Requirements

  • Python 3.12 or later
  • Ollama installed and running
  • The local qwen2.5:3b model

Setup

From PowerShell in the project folder:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
ollama pull qwen2.5:3b

Keep Ollama running. If the Ollama desktop app is not running, open a second terminal and run ollama serve.

Run the agent

python .\run_agent.py --help

Example multi-step task that uses web search, calculation, a local reference file, and a final comparison:

python .\run_agent.py "Use tools in this order and one call per reply: (1) web-search the Ollama download size of Qwen2.5 3B; (2) use calculator to double the observed size in GB; (3) read project_brief.md to get the comparison limit; (4) use calculator to evaluate whether the doubled size is less than or equal to that limit. Do not answer before all four results exist. Cite each fact with its evidence ID."

Options include --model, --max-steps, --max-calls-per-tool, --max-output-tokens, and --shadow-budget-usd.

Run guardrail checks

python -m unittest discover -s tests -v

The tests verify duplicate tool-call detection, the step limit, and preflight blocking when a model call would exceed the shadow-cost budget.

Traces and cost accounting

Each run writes events to traces/run_<id>.jsonl. A trace records planning decisions, tool names and arguments, raw tool results, usage estimates, evidence checks, and the final status. The console may shorten long tool output; the JSONL trace retains the full result.

Ollama inference runs locally, so the actual local API cost is $0. The shadow estimate is a demonstration of cost-budget enforcement, not a charge for local inference. Its reference model, rates, budget, and pricing source are recorded in the usage summary.

Limitations

Live search and page extraction depend on network availability and can fail temporarily. If a requested fact is missing from the actual task and tool evidence, the calculator rejects the unsupported value; rerun the task after the source becomes available.

Example runs

  1. Web research and VRAM comparison — Finds the Qwen2.5 3B download size, doubles it, reads the project limit, and checks the comparison. Trace: traces/run_9ff159674c82.jsonl
  2. Local reference calculation — Reads the VRAM comparison limit and calculates half of it. Trace: traces/run_3700f2844d84.jsonl
  3. Documentation research and calculation — Searches the official Ollama tool-calling documentation, reads the project limit, and calculates half. Trace: traces/run_fb193ddbe9df.jsonl

About

Local research agent built on Ollama native tool calling: web search, calculator and file tools, with JSONL traces and citation validation.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages