Theorizer CLI

The command line for Theorizer, which generates literature-grounded scientific theories from a corpus of papers.

Install and check

pip install asta-theorizer
export OPENAI_API_KEY=...                  # the default models are gpt-6-sol and, per paper, gpt-6-luna
export S2_API_KEY=...                      # optional: faster paper fetching
export MISTRAL_API_KEY=...                 # optional: Mistral OCR for PDFs instead of local conversion
export NORA_RETRIEVAL_BEARER_TOKEN=...     # optional, with NORA_RETRIEVAL_ENV: full text from nora-retrieval first
export NORA_RETRIEVAL_ENV=prod             #   (prod or dev); USE_NORA_RETRIEVAL_FULLTEXT=false opts out

theorize doctor
theorize -p vip/ init
theorize -p vip/ init --model gpt-5-mini --extraction-model gpt-5-mini     # cheaper models for a first run
theorize --help
theorize papers --help

Papers from PaperFinder

theorize -p vip/ papers search "VIP interneurons visual cortex gain"
theorize -p vip/ papers fetch --top 1                    # fetches the full text of the top candidate into the project
theorize -p vip/ papers fetch 225095372 244348308        # or of these corpus ids
theorize -p vip/ show papers
theorize -p vip/ show papers --status metadata-only
theorize -p vip/ show candidates

Papers from your own files or a store

theorize -p vip/ papers import tests/fixtures/one-paper.md
theorize -p vip/ papers import my-papers/*.pdf                          # local conversion
theorize -p vip/ papers import my-papers/*.pdf --ocr mistral            # Mistral OCR
theorize -p vip/ papers import my-papers/ --no-metadata                 # skip the metadata call

asta-papers search "VIP interneurons visual cortex" --limit 1 | asta-papers store > store.json
theorize -p vip/ papers import store.json
theorize -p vip/ show papers

The whole run in one command

theorize -p vip/ run "Build a theory of how VIP interneurons control response gain in mouse V1" --max-papers 1
theorize -p vip/ export html
open vip/html/index.html

Stage by stage

theorize -p vip/ plan "Build a theory of how VIP interneurons control response gain in mouse V1"
theorize -p vip/ show plan
theorize -p vip/ show plan --full
theorize -p vip/ extract --max-papers 1
theorize -p vip/ extract
theorize -p vip/ show extraction
theorize -p vip/ theories generate
theorize -p vip/ show theories
theorize -p vip/ export html

Refine the schema from what came out

theorize -p vip/ report
theorize -p vip/ show variable-report
theorize -p vip/ schemas extend
theorize -p vip/ schemas extend --max-suggestions 5 --save-as schema-wide
theorize -p vip/ show schema-extended
theorize -p vip/ extract --schema schema-extended --save-as extraction-extended
theorize -p vip/ theories generate --extraction extraction-extended

Let the papers propose the schema

theorize -p vip/ discover
theorize -p vip/ schemas from-discovery
theorize -p vip/ show schemas#0
theorize -p vip/ extract --schema schemas#0 --save-as extraction-discovered
theorize -p vip/ theories generate --extraction extraction-discovered

Other theory generators

theorize -p vip/ theories generate --objective novelty --save-as theories-novelty
theorize -p vip/ theories generate --no-reflection --max-laws 2 --model gpt-5.2
theorize -p vip/ theories generate --max-data-tokens 800000                    # more evidence per call
theorize -p vip/ theories generate --suggestions variable-report
theorize -p vip/ theories sweep --debug-limit 2
theorize -p vip/ theories sweep --output-types "MECHANISTIC EXPLANATION" --inference-types none
theorize -p vip/ show theories

Symbolic laws

theorize -p vip/ schemas symbolic
theorize -p vip/ show symbolic-schema
theorize -p vip/ extract --schema symbolic-schema --save-as extraction-symbolic
theorize -p vip/ symbolic table
theorize -p vip/ symbolic solve
theorize -p vip/ symbolic solve --skip pysr_symbolic --skip gplearn_symbolic --timeout 60
theorize -p vip/ symbolic laws
theorize -p vip/ symbolic report symbolic-report
theorize -p vip/ symbolic report symbolic-report --out vip/laws.md

Evaluate the theories

theorize -p vip/ evaluate judge
theorize -p vip/ evaluate judge --only-novel --model gpt-5.2
theorize -p vip/ evaluate belief --samples 2 --limit 1
theorize -p vip/ evaluate novelty --limit 1
theorize -p vip/ show evaluation-novelty
theorize -p vip/ evaluate predictive --evidence-from 2024-01 --limit 1 --max-papers 1
theorize -p vip/ export html

Inspect and pipe

theorize -p vip/ show
theorize -p vip/ show 3
theorize -p vip/ load plan
theorize -p vip/ load plan --key output.paper_search_query
theorize -p vip/ load extraction > extraction.json
theorize -p vip/ --json show | jq '.data.items[].name'
theorize -p vip/ --json theories generate --no-reflection | jq '.data.theory_ids'
theorize -p vip/ -q show theories

Models and keys

theorize -p vip/ init --model gpt-6-sol --extraction-model gpt-6-luna         # the defaults
THEORIZER_MODEL=gpt-5.2 theorize -p vip/ theories generate
theorize -p vip/ theories generate --model gpt-5.2
LITELLM_BASE_URL=https://proxy.example/v1 LITELLM_USER_KEY=... theorize -p vip/ doctor
THEORIZER_PAPERFINDER_URL=http://localhost:8000 theorize -p vip/ papers search "VIP interneurons"

Resume and retry

theorize -p vip/ extract                       # reruns pick up where the last one stopped
theorize -p vip/ papers fetch 225095372        # a failed paper is fetched again
theorize -p vip/ theories sweep --debug-limit 2 --debug-seed 1

Exit codes

0  done
1  a stage ran and failed (no theories, nothing extracted, solver error)
2  usage (missing input, unknown reference, no papers)
3  preflight (another command holds the project, doctor found a problem)