Metadata-Version: 2.5
Name: asta-theorizer
Version: 0.1.1
Summary: Generate literature-grounded scientific theories from a corpus of papers: search, fetch, extract, theorize, export
Project-URL: Homepage, https://github.com/allenai/asta-theorizer
Author: Allen Institute for AI
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: literature,llm,scientific-discovery,semantic-scholar,theory-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: asta-papers[mistral,pymupdf]>=0.1.0
Requires-Dist: click>=8.0
Requires-Dist: func-timeout>=4.3
Requires-Dist: json-repair>=0.30
Requires-Dist: litellm>=1.60
Requires-Dist: markdown>=3.5
Requires-Dist: numpy>=1.26
Requires-Dist: orjson>=3.9
Requires-Dist: requests>=2.31
Requires-Dist: tiktoken>=0.8
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: symbolic
Requires-Dist: pandas>=2.1; extra == 'symbolic'
Requires-Dist: scikit-learn>=1.4; extra == 'symbolic'
Requires-Dist: scipy>=1.11; extra == 'symbolic'
Description-Content-Type: text/markdown

# Theorizer CLI

The command line for [Theorizer](https://github.com/allenai/asta-theorizer), which generates literature-grounded scientific theories from a corpus of papers.

## Install and check

```bash
pip install asta-theorizer
export OPENAI_API_KEY=...                  # the default models are gpt-5.6-sol and, per paper, gpt-5.6-luna
export S2_API_KEY=...                      # optional: faster paper fetching
export MISTRAL_API_KEY=...                 # optional: Mistral OCR for PDFs instead of local conversion

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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
theorize -p vip/ init --model gpt-5.6-sol --extraction-model gpt-5.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

```bash
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)
```
