psychscanner
psychscanner
PsychScanner: A framework for running psychological experiments with large language models.
Tested on Python 3.11
The package is under active development. Contributions are welcome.
Features
- Automated Cognitive Tasks — run validated psychological experiments (surveys, rating scales, cognitive tasks) with any LLM
- Flexible Memory — stateless (no-memory) and conversational (session memory) conditions in the same experiment
- Persona System — configure AI agents with system prompts, personality traits, and response formats
- Multi-provider — works with OpenAI, Anthropic, Groq, Mistral, Google, Ollama (local/remote), HuggingFace, and more via LangChain
- Session Recovery — checkpoint and resume long-running simulations with
SessionTunnel - Structured Output — export trial-level results to CSV with parsed response fields
Installation
1. Create the uv environment
Install uv first if you don’t have it (astral.sh/uv):
conda install -c conda-forge uv # if you use conda
# curl -LsSf https://astral.sh/uv/install.sh | sh # skip if you already have uv
uv venv psyscan --python 3.11
source psyscan/bin/activate
2. Install psychscanner
git clone https://github.com/saurabhr/psychscanner.git
cd psychscanner
uv pip install -e .
3. Set API keys
Create a .env file in your project directory (or export variables in your shell):
# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
MISTRAL_API_KEY=...
GOOGLE_API_KEY=...
HUGGINGFACEHUB_API_TOKEN=hf_...
# Ollama remote server (only needed when not using localhost)
OLLAMA_API_KEY=...
Keys are loaded automatically from the environment for each provider family. Ollama running locally needs no key.
Quick Start
This is the same code pinned by tests/test_readme_quickstart.py::test_readme_quickstart_live_ollama.
It runs against a local Ollama smol model (no API key) — pull it once with
ollama pull smollm2:360m-instruct-fp16, then run:
from pathlib import Path
from psychscanner import ExpCardInit, ExpCard, ScannerModel, to_csv
from psychscanner.parsers import DefaultLiteralVivid15
# 1. Configure the experiment
card = ExpCardInit(
model = "smollm2:360m-instruct-fp16", # local Ollama; alt: "openai/gpt-oss-120b" with family="groq"
family = "ollama",
parameters = {"temperature": 0},
projectname = "readme_quickstart",
proj_dir = Path.cwd() / "results", # output goes to ./results in your CWD
cogtype = "no", # no persona files — use nsim instead
nsim = 1, # 1 simulated participant (bump up for real studies)
memory = "SingleTurn",
parser = DefaultLiteralVivid15,
)
# 2. Run (uses built-in VVIQ-16 imagery questionnaire by default)
scanner = ScannerModel(expcard=ExpCard(card))
results = scanner.run()
# 3. Export to CSV (auto-named under proj_dir)
df = to_csv(scanner, path=card.proj_dir)
Supported Providers
| Family | Env var | Notes |
|---|---|---|
openai |
OPENAI_API_KEY |
GPT-4o, GPT-4o-mini, o1, … |
anthropic |
ANTHROPIC_API_KEY |
Claude 3.5, Claude 3 Haiku, … |
groq |
GROQ_API_KEY |
Llama 3, Mixtral on Groq Cloud |
mistral |
MISTRAL_API_KEY |
Mistral, Codestral |
google / gemini |
GOOGLE_API_KEY |
Gemini 2.0, 1.5 |
together |
TOGETHER_API_KEY |
Together.ai hosted models |
fireworks |
FIREWORKS_API_KEY |
Fireworks.ai |
azure |
AZURE_OPENAI_API_KEY |
Azure OpenAI |
huggingface |
HUGGINGFACEHUB_API_TOKEN |
HuggingFace Inference API |
ollama |
— (local) / OLLAMA_API_KEY (remote) |
Pass base_url in parameters for remote |
Examples
| Notebook | Description |
|---|---|
00_quickstart.ipynb |
Minimal working example |
01_ollama_local_models.ipynb |
Local models via Ollama |
02_parameters_reference.ipynb |
Full ExpCard parameter reference |
03_parsers.ipynb |
Response parsing overview |
04_parser_modules.ipynb |
Custom parser modules |
05_rm_task.ipynb |
Reality monitoring task |
06_feedback_api.ipynb |
Feedback / scoring API |
07_rm_feedback_task.ipynb |
Reality monitoring with feedback |
08_ps_parser_guide.ipynb |
Structured output parsing guide |
09_vviq16_study.ipynb |
VVIQ-16 imagery questionnaire study |