Blame for README.md

---
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
base_model:
  - Qwen/Qwen3.5-4B
tags:
  - knowledge-graph
  - tool-use
  - graph-traversal
  - question-answering
  - scientific-reasoning
---

# Prospector-4B

Prospector is a compact LLM policy post-trained to answer questions over a
scientific knowledge graph. The policy traverses the graph with tools, one
call at a time, and answers with a chain of edges that is checked against
what the tools returned. Prospector-4B is the largest of the paper's three
policies, trained on one graph built from the semiconductor-manufacturing
literature. With frozen weights, the policy transfers to graphs from three
other fields.

This repository holds the served model as one checkpoint: Qwen3.5-4B with
the paper's three LoRA adapters merged into its language model, under the
policy's chat template. The checkpoint has Qwen3.5-4B's layout and loads
wherever the base model loads. On its own, the model writes one tool call
and stops, so the example below drives it through the harness that serves
its tools.

Code: https://github.com/lamm-mit/Prospector

Adapters, training rows, stored runs and the semiconductor graph:
https://huggingface.co/lamm-mit/Prospector

## Example

Clone the GitHub repository first

```bash
git clone https://github.com/lamm-mit/Prospector && cd Prospector
```

Then download the knowledge graph data, 8 MB, from the release

```bash
uvx --from huggingface_hub hf download lamm-mit/Prospector --local-dir . --include "data/raw/*"
```

Install the environment

```bash
# on a Mac ...
uv venv --python 3.12 .venv-mac && uv pip install --python .venv-mac/bin/python \
    -e ".[dev,train,mlx,app]" -c launch/constraints-mac.txt && source .venv-mac/bin/activate
# ... or on a Linux machine with an NVIDIA GPU, where CUDA's compiler needs sudo
launch/setup.sh && source .venv/bin/activate
```

Below is `example.py`, which asks Prospector-4B one question over the graph:

```python
import argparse
import importlib.util

from graph_reasoner.agent.backend import load_backend, resolve_kb
from graph_reasoner.agent.eval import build_generate_seam
from graph_reasoner.agent.gate import edge_dicts, gate_assertion
from graph_reasoner.agent.loop import EpisodeConfig, drive_episode, start_episode
from graph_reasoner.eval.parse import extract_final_answer, extract_graph_json
from graph_reasoner.schema import BenchmarkItem

QUESTION = ("In semiconductor metrology, which subsystem is typically paired with "
            "high-resolution nanoscale imaging techniques used for structural inspection?")


def default_engine() -> str:
    for engine, package in (("mlx", "mlx_lm"), ("vllm", "vllm")):
        if importlib.util.find_spec(package) is not None:
            return engine
    return "hf"


ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--model", default=f"{default_engine()}:lamm-mit/Prospector-4B")
ap.add_argument("--graph", default="tsmc", help="the substrate: tsmc, or biograph, pfas, matprop once downloaded")
ap.add_argument("--question", default=QUESTION)
args = ap.parse_args()

graph = load_backend(args.graph, resolve_kb(args.graph, None))
cfg = EpisodeConfig()          # the paper's protocol: 20 tool calls, 1,024 tokens a turn, greedy
seam = build_generate_seam(args.model, cfg)


def generate(conversations, max_new_tokens):
    """The harness's generate call, printing the turn it is answering and the turn it gets back."""
    print(conversations[0][-1]["content"], end="\n\n")
    out = seam(conversations, max_new_tokens)
    print(out[0], end="\n\n")
    return out


item = BenchmarkItem(id="example", tier="adhoc", question=args.question, gold_answer="",
                     gold_path={"nodes": [], "edges": []}, subgraph_edges=[], subgraph_text="")
ep = drive_episode(start_episode(item, graph, cfg), graph, generate, cfg)

answer = extract_final_answer(ep.final_text)
cited = extract_graph_json(ep.final_text)
verdict = gate_assertion(answer, edge_dicts(cited.edges if cited else None),
                         edge_dicts(ep.seen.values()))
print(f"answer: {answer}")
print(f"gate: {'passed' if verdict['gate_pass'] else 'failed, ' + verdict['gate_reason']}; "
      f"{ep.n_calls} tool calls, {len(ep.seen)} edges seen")
```

Download it from this repository and run it from the clone's root:

```bash
uvx --from huggingface_hub hf download lamm-mit/Prospector-4B example.py --local-dir .
python example.py
```

The first run downloads this model from the Hub, about 9 GB. `--question` asks
another question, `--graph` names another downloaded graph, and `--model`
picks the engine by its prefix: `mlx:` on Apple silicon, `vllm:` on an
NVIDIA GPU, `hf:` wherever transformers runs.

Sample output, on a Mac through the `mlx:` driver:

```
Question: In semiconductor metrology, which subsystem is typically paired with high-resolution nanoscale imaging techniques used for structural inspection?

Find the entity named in the question, then explore outward.
Budget: 20 tool calls.

<think>Let's search for entities related to semiconductor metrology or high-resolution nanoscale imaging techniques.</think>
<tool_call>{"tool": "find", "args": {"name": "semiconductor metrology"}}</tool_call>

OBSERVATION (call 1/20, find):
FOUND 2 node(s) matching "semiconductor metrology":
  Metrology  [field, 1 connections]
  metrology  [method, 4 connections]
No edges returned — use expand() to see connections.
[0 new edges; 0 edges seen; 19 tool calls left]

<think>Let's search for "nanoscale imaging" or "high-resolution" or "structural inspection" or expand "metrology".</think>
<tool_call>{"tool": "expand", "args": {"node": "metrology"}}</tool_call>

OBSERVATION (call 2/20, expand):
metrology --[has property]--> atomic-scale processes
metrology --[measures]--> profile evolution models
electron microscopy --[is_a]--> metrology
metrology --[measures]--> sub-10 nm hole or trench
[4 new edges; 4 edges seen; 18 tool calls left]

<think>Let's expand "electron microscopy" or search for "nanoscale imaging" / "structural inspection".</think>
<tool_call>{"tool": "expand", "args": {"node": "electron microscopy"}}</tool_call>

OBSERVATION (call 3/20, expand):
STM --[is superior to]--> electron microscopy
optical system --[used with]--> electron microscopy
electron microscopy --[is_a]--> metrology
electron microscopy --[measures]--> number of adhered particles
deposition --[uses]--> electron microscopy
etching rate --[uses]--> electron microscopy
electron microscopy --[compared to]--> STM
[6 new edges; 10 edges seen; 17 tool calls left]

[... twelve more calls, then the final turn's reasoning ...]

<graph_json>{
  "nodes": [
    "optical system",
    "electron microscopy",
    "metrology"
  ],
  "edges": [
    {
      "source": "optical system",
      "relation": "used with",
      "target": "electron microscopy"
    },
    {
      "source": "electron microscopy",
      "relation": "is_a",
      "target": "metrology"
    }
  ]
}</graph_json>
ANSWER: In semiconductor metrology, the **optical system** is typically paired with **electron microscopy** (a high-resolution nanoscale imaging technique used in metrology).

answer: In semiconductor metrology, the **optical system** is typically paired with **electron microscopy** (a high-resolution nanoscale imaging technique used in metrology).
gate: passed; 15 tool calls, 111 edges seen
```

The code repository's README gives the command behind every number in the
paper, and `scripts/run_agent_eval.py` evaluates this model on a whole
benchmark with `--model vllm:lamm-mit/Prospector-4B` in place of the base
model and the adapter chain.

## Citation

```bibtex
@article{yang2026prospector,
  title   = {Prospector: learning a compact graph traversal policy for scientific reasoning},
  author  = {Yang, Haiqian and Buehler, Markus J.},
  journal = {arXiv preprint},
  year    = {2026}
}
```