Skip to content
Open in molab View on GitHub Download .py

Pulling Cards from the Library Ecosystem

psychscanner-primal doesn't ship every task card it can run -- two sibling repos hold public, versioned card indexes instead:

  • psyscan-library -- hand-curated, vetted task/experiment cards, one PASS gate away from merge (every card is run against a real mock-LLM check before it's accepted). Fetched with download_lib(), built into this package.
  • psychscanner-cog-atlas -- ~850 cards auto-generated from every task in the public Cognitive Atlas ontology. No built-in fetch helper exists for this one (it's a plain git checkout), so this page clones it directly.

Both hand back plain psychscanner task-card JSON -- once fetched, running a card is identical regardless of which index it came from. This page runs one card from each, against the built-in mock-llm family (no API key, no network needed for the model calls themselves -- only the two clone steps below touch the network).

1. A vetted card from psyscan-library

download_lib() clones/updates a cached checkout and hands back the tasks/ path for the installed distro (primal, since that's what's running this page). run_card() then does the rest -- task_library() lookup, ExpCardInit/ExpCard, ScannerModel().run() -- in one call.

import tempfile
from pathlib import Path

from psychscanner import download_lib, run_card, to_csv

lib_paths = download_lib()  # library="primal" (default) -- matches this page's install
proj_dir_a = Path(tempfile.mkdtemp(prefix="psychscanner_library_tutorial_"))

results_a = run_card(
    "rm_singleturn_demo",
    dirs=lib_paths["tasks"],
    projectname="from_psyscan_library",
    proj_dir=proj_dir_a,
)

Cloning into '/home/runner/.cache/psychscanner/psyscan-library'...

----<PROJECT AND DATA ROOT DIRECTORY>----
    Project root dir: /tmp/psychscanner_library_tutorial_rsg1lrjf
    Simulation data root dir: /tmp/psychscanner_library_tutorial_rsg1lrjf/from_psyscan_library/rm_singleturn_demo/mock-llm_mock-chat-model_SingleTurn
----<>----
--<chat model>-- metadata={'lc_versions': {'langchain-core': '1.6.0', 'langchain': '1.3.16'}} model_name='mock-chat-model' repeat_buffer_length=10

2026-08-23 19:37:03.529 | CRITICAL | psychscanner.session_tunnel.session_tunnel:create_tunnel:152 - BEGIN

TOTAL RUNS: 1 RESUME IDX: None
----<>---- task running

2026-08-23 19:37:03.549 | INFO     | psychscanner.session_tunnel.session_tunnel:scan_checkpoint:184 - scan-checkpoint

----<scanned runs>---- i = 0

2026-08-23 19:37:03.550 | CRITICAL | psychscanner.session_tunnel.session_tunnel:end_checkpoint:163 - END

run_card() against the psyscan-library card returned 1 result batch(es).

2. A Cognitive-Atlas-derived card from psychscanner-cog-atlas

No download_lib()-style helper exists for this index yet, so this clones it directly (shallow, single branch -- the same git-via-subprocess pattern download_lib() itself uses internally) and points task_library() at its tasks/non_reward/ folder. digit_span_task.json is tagged source.compatible_with: ["psychscanner", "psychscanner-primal"] in the card's own metadata, so it's confirmed to run on this distro.

import subprocess

cog_atlas_dir = Path(tempfile.mkdtemp(prefix="psychscanner_cog_atlas_"))
subprocess.run(
    [
        "git", "clone", "--depth", "1", "--branch", "main",
        "https://github.com/saurabhr/psychscanner-cog-atlas.git",
        str(cog_atlas_dir),
    ],
    check=True,
    capture_output=True,
)

CompletedProcess(args=['git', 'clone', '--depth', '1', '--branch', 'main', 'https://github.com/saurabhr/psychscanner-cog-atlas.git', '/tmp/psychscanner_cog_atlas_vr7xhknu'], returncode=0, stdout=b'', stderr=b"Cloning into '/tmp/psychscanner_cog_atlas_vr7xhknu'...\n")
proj_dir_b = Path(tempfile.mkdtemp(prefix="psychscanner_library_tutorial_"))
results_b = run_card(
    "digit_span_task",
    dirs=cog_atlas_dir / "tasks" / "non_reward",
    projectname="from_cog_atlas",
    proj_dir=proj_dir_b,
)

----<PROJECT AND DATA ROOT DIRECTORY>----
    Project root dir: /tmp/psychscanner_library_tutorial_4sa21obz
    Simulation data root dir: /tmp/psychscanner_library_tutorial_4sa21obz/from_cog_atlas/digit_span_task/mock-llm_mock-chat-model_SingleTurn
----<>----
--<chat model>-- metadata={'lc_versions': {'langchain-core': '1.6.0', 'langchain': '1.3.16'}} model_name='mock-chat-model' repeat_buffer_length=10

2026-08-23 19:37:03.918 | CRITICAL | psychscanner.session_tunnel.session_tunnel:create_tunnel:152 - BEGIN

TOTAL RUNS: 1 RESUME IDX: None
----<>---- task running

2026-08-23 19:37:03.925 | INFO     | psychscanner.session_tunnel.session_tunnel:scan_checkpoint:184 - scan-checkpoint

----<scanned runs>---- i = 0

2026-08-23 19:37:03.926 | CRITICAL | psychscanner.session_tunnel.session_tunnel:end_checkpoint:163 - END

run_card() against the cog-atlas card returned 1 result batch(es).

3. Both, side by side

Same run_card() call, same ExpCard/ScannerModel pipeline, two different origins for the task-card JSON -- the library a card comes from is irrelevant to how it runs once fetched.

# source=a directory scans recursively for the .psyscan checkpoint
# files run_card() just wrote, no ExpCard/ScannerModel handle needed.
df_a = to_csv(proj_dir_a)
df_b = to_csv(proj_dir_b)

Saved 8 rows → /tmp/psychscanner_library_tutorial_rsg1lrjf/from_psyscan_library_rm_singleturn_demo_mock-chat-model_SingleTurn_20260823_193703.csv
Saved 2 rows → /tmp/psychscanner_library_tutorial_4sa21obz/from_cog_atlas_digit_span_task_mock-chat-model_SingleTurn_20260823_193703.csv
Source Task Rows
psyscan-library rm_singleturn_demo 8
psychscanner-cog-atlas digit_span_task 2

Which index should a real task come from?

  • Publishing your own new task? Contribute it to psyscan-library (or, if it maps to an existing Cognitive Atlas ontology entry, a correction/addition to psychscanner-cog-atlas) -- see Contribute a task card in the sibling doc page for the exact PR workflow.
  • Just need something that already runs? Either index works the same way from here: download_lib()/a plain clone, then task_library()/run_card(). psyscan-library's cards are hand-vetted for both distros; psychscanner-cog-atlas's source.compatible_with field on each card tells you which distro(s) it's confirmed to run on before you try.