Quickstart¶
Runs against the built-in mock-llm family (no API key, no network),
so it works out of the box and this page can execute for real at
build time.
Swap model/family for a real provider (see the Supported
Providers table below) to run against an actual LLM.
import tempfile
from pathlib import Path
from psychscanner import ExpCard, ExpCardInit, ScannerModel, task_library, to_csv
task_path = task_library("rm_singleturn_demo", format="path", dirs="../examples/tasks")
# A fresh temp dir every run: ScannerModel refuses to reuse a proj_dir
# that already holds a completed session's tunnel file, which a
# committed results/ dir would trigger on every rebuild.
proj_dir = Path(tempfile.mkdtemp(prefix="psychscanner_quickstart_"))
card = ExpCardInit(
model="mock-llm",
family="mock-llm",
projectname="primal_quickstart",
proj_dir=proj_dir,
cogtype="no",
nsim=1,
memory="SingleTurn",
task_file=task_path,
)
scanner = ScannerModel(expcard=ExpCard(card))
results = scanner.run()
----<PROJECT AND DATA ROOT DIRECTORY>----
Project root dir: /tmp/psychscanner_quickstart_5kp2cec0
Simulation data root dir: /tmp/psychscanner_quickstart_5kp2cec0/primal_quickstart/rm_singleturn_demo/mock-llm_mock-llm_SingleTurn
----<>----
--<chat model>-- metadata={'lc_versions': {'langchain-core': '1.6.0', 'langchain': '1.3.16'}} model_name='mock-llm' repeat_buffer_length=10
2026-08-23 19:37:00.603 | CRITICAL | psychscanner.session_tunnel.session_tunnel:create_tunnel:152 - BEGIN
TOTAL RUNS: 1 RESUME IDX: None ----<>---- task running
2026-08-23 19:37:00.622 | INFO | psychscanner.session_tunnel.session_tunnel:scan_checkpoint:184 - scan-checkpoint
----<scanned runs>---- i = 0
2026-08-23 19:37:00.623 | CRITICAL | psychscanner.session_tunnel.session_tunnel:end_checkpoint:163 - END
scanner.run() returned 1 result batch(es).
Saved 8 rows → /tmp/psychscanner_quickstart_5kp2cec0/primal_quickstart_rm_singleturn_demo_mock-llm_SingleTurn_20260823_193700.csv
shape: (8, 19)
| sim_idx | model | family | memory | memory_k | projectname | cogtype | parser | taskname | tasktype | chain_type | trace_id | tunnel_id | trial_idx | trcode | context_item | stimulus | pred_resp_raw | fb_response |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| i64 | str | str | str | i64 | str | str | str | str | str | str | str | str | i64 | str | str | str | str | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 0 | "imagined_1" | "" | "{"Word_Pair": {"word_1": "sand… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 1 | "perceived_2" | "" | "{"Word_Pair": {"word_1": "suga… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 2 | "imagined_3" | "" | "{"Word_Pair": {"word_1": "subu… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 3 | "perceived_4" | "" | "{"Word_Pair": {"word_1": "chai… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 4 | "perceived_5" | "" | "{"Word_Pair": {"word_1": "lett… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 5 | "imagined_6" | "" | "{"Word_Pair": {"word_1": "buil… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 6 | "imagined_7" | "" | "{"Word_Pair": {"word_1": "blou… | "{ "Wor" | null |
| 0 | "mock-llm" | "mock-llm" | "SingleTurn" | -1 | "primal_quickstart" | "no" | "none" | "rm_singleturn_demo" | "sc" | "item" | "20260823T19-37-00primal_quicks… | "sidx-[0]-model-mock-llm-family… | 7 | "perceived_8" | "" | "{"Word_Pair": {"word_1": "pin"… | "{ "Wor" | null |
Supported providers¶
Only ollama ships out of the box (langchain-ollama is a base
dependency). Every other family needs its own LangChain integration
package too, e.g. uv pip install langchain-openai for openai.
| Family | Env var |
|---|---|
openai |
OPENAI_API_KEY |
anthropic |
ANTHROPIC_API_KEY |
groq |
GROQ_API_KEY |
mistral |
MISTRAL_API_KEY |
google / gemini |
GOOGLE_API_KEY |
huggingface |
HUGGINGFACEHUB_API_TOKEN |
ollama |
— (local) / OLLAMA_API_KEY (remote) |