Guide · Open source
How to use STORM: install, run and edit its reports
Updated · written with AI from the project's own documentation and checked against our catalogue data
STORM is an open-source research system from Stanford that takes a topic, searches the internet, and writes a full-length article with citations. This guide is for developers, writers and researchers who are comfortable with Python and have API keys ready. By the end you will know how to install the package, configure a language model and search provider, run the pipeline, and what to expect from the output.
STORMstanford-oval/storm · ★ 31.8k · MIT Install options & downloads Quick start
- 1Install the package. Run pip install knowledge-storm, or clone the repository and install its requirements in a Python 3.11 environment.
- 2Set your API keys. Export a language model key such as OPENAI_API_KEY and a search provider key such as YDC_API_KEY.
- 3Configure the language models. Assign a cheaper model to the conversation and question steps and a stronger model to outline and article generation.
- 4Choose a search module. Create a retriever such as YouRM and pass it to the runner along with your settings.
- 5Run the pipeline. Call runner.run with your topic and the stage flags you want, then call post_run and summary.
- 6Review and edit the draft. Check the outline, article and citations, then rewrite what needs work before using it.
What STORM does and what it does not do
STORM is a research system built on large language models. Given a topic, it searches the internet, simulates conversations to gather information, builds an outline, and writes an article with citations.
The README is clear that the output cannot be published as-is. Articles often need significant editing, though experienced Wikipedia editors have found it helpful in the pre-writing stage.
- Pre-writing stage: research the web to collect references and generate an outline.
- Writing stage: use the outline and references to generate the full-length article with citations.
- Co-STORM: lets a human join the discussion and steer the research.
Install the knowledge-storm package
The simplest route is the PyPI package. The README's examples use Python 3.11 in a Conda environment, so create one first if you use Conda.
If you want to modify the STORM engine itself, clone the repository and install its requirements instead.
- Install the library from PyPI.
- Clone the repository for a source install.
- Create a Python 3.11 environment and install requirements from source.
pip install knowledge-storm
git clone https://github.com/stanford-oval/storm.git
cd storm
conda create -n storm python=3.11
conda activate storm
pip install -r requirements.txtGet API keys for a language model and a search provider
STORM depends on external services. You need a language model provider and a search or retrieval provider. The README's example uses OpenAI models and the You.com search engine, read from the environment variables OPENAI_API_KEY and YDC_API_KEY.
Language models are reached through litellm, so any provider litellm supports can be used. Search options named in the README include YouRM, BingSearch, VectorRM (for your own documents), SerperRM, BraveRM, SearXNG, DuckDuckGoSearchRM, TavilySearchRM, GoogleSearch and AzureAISearch.
- Set your language model key, for example OPENAI_API_KEY.
- Set your search provider key, for example YDC_API_KEY for You.com.
- Other retrievers may need their own keys; check the provider named in your rm.py setup.
export OPENAI_API_KEY=your_key_here
export YDC_API_KEY=your_key_hereChoose models for each stage of the pipeline
STORM lets different components use different models. The README suggests a cheaper, faster model for the conversation simulator and question asker, and a more powerful model for outline and article generation.
Configure these with STORMWikiLMConfigs and LitellMModel, then pass the configured retriever and settings to a STORMWikiRunner.
- conv_simulator_lm and question_asker_lm: cheaper model, used to split queries and answer in the simulated conversation.
- outline_gen_lm, article_gen_lm and article_polish_lm: stronger model for the outline, cited article and polish.
- Check the STORMWikiRunnerArguments class for more settings.
import os
from knowledge_storm import STORMWikiRunnerArguments, STORMWikiRunner, STORMWikiLMConfigs
from knowledge_storm.lm import LitellmModel
from knowledge_storm.rm import YouRM
lm_configs = STORMWikiLMConfigs()
openai_kwargs = {
'api_key': os.getenv("OPENAI_API_KEY"),
'temperature': 1.0,
'top_p': 0.9,
}
gpt_35 = LitellmModel(model='gpt-3.5-turbo', max_tokens=500, **openai_kwargs)
gpt_4 = LitellmModel(model='gpt-4o', max_tokens=3000, **openai_kwargs)
lm_configs.set_conv_simulator_lm(gpt_35)
lm_configs.set_question_asker_lm(gpt_35)
lm_configs.set_outline_gen_lm(gpt_4)
lm_configs.set_article_gen_lm(gpt_4)
lm_configs.set_article_polish_lm(gpt_4)
engine_args = STORMWikiRunnerArguments(...)
rm = YouRM(ydc_api_key=os.getenv('YDC_API_KEY'), k=engine_args.search_top_k)
runner = STORMWikiRunner(engine_args, lm_configs, rm)Run STORM on a topic
Call the run method with your topic and choose which stages to execute. Each flag switches one stage on or off. When do_research is False, STORM loads previously saved results instead of searching again.
After the run, post_run and summary finish the job and print a summary.
- do_research: simulate conversations from different perspectives to collect information.
- do_generate_outline: generate an outline for the topic.
- do_generate_article: write the article with citations.
- do_polish_article: polish the finished article.
topic = input('Topic: ')
runner.run(
topic=topic,
do_research=True,
do_generate_outline=True,
do_generate_article=True,
do_polish_article=True,
)
runner.post_run()
runner.summary()Use Co-STORM to join the research
Co-STORM adds a human user to the discussion. Alongside the STORM experts, a moderator raises questions the system has found but not yet used, and you can either observe the discourse or inject your own messages to steer it.
Co-STORM also keeps a mind map, a hierarchical structure of the collected concepts, which the README says helps reduce mental load in long discussions.
- Co-STORM LLM experts answer grounded in sources and raise follow-up questions.
- The moderator suggests questions based on information not yet used.
- You can observe the discussion or actively steer it.
- The mind map organises information into concepts you can follow.
Edit the output before you use it
Treat the generated article as a first draft. The README says it is not publication-ready, so check each claim against the cited sources and rewrite sections that are thin or wrong.
Use the outline and reference list as a starting point for your own research, even if you rewrite the prose entirely.
- Verify every citation by opening the source.
- Remove or rewrite claims the sources do not support.
- Use the outline to plan your own structure.
What people use it for
- A writer building a first-draft outline and source list before drafting an article.
- A Wikipedia editor using the output in the pre-writing stage.
- A researcher getting a structured overview of an unfamiliar topic with references.
- A developer testing different language models and search engines in one pipeline.
Frequently asked questions
How do I install STORM?
Run pip install knowledge-storm for the PyPI package. To modify the engine, clone the stanford-oval/storm repository and install requirements.txt in a Python 3.11 environment.
Is STORM free to use?
STORM is released under the MIT licence. You still need API keys for a language model provider and a search provider, which may charge for usage.
What do I need to run STORM?
Python 3.11 is used in the README's examples, plus Conda or another environment manager. You also need API keys for a language model and a search provider.
Can STORM write publication-ready articles?
No. The README says the system cannot produce publication-ready articles and that they often need significant edits. It is most useful as a pre-writing aid.
What is the difference between STORM and Co-STORM?
STORM runs the research and writing automatically. Co-STORM adds a human user to the discussion, who can observe or steer the conversation, and it maintains a mind map of concepts.
What are alternatives to STORM?
The comparable projects listed for this tool include GPT Researcher, LangChain, and Perplexica, as well as other deep research agents. Choose based on whether you want a ready-made report pipeline or a framework to build your own.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
STORM suits developers who want a customisable research and report pipeline, and writers or researchers who want a cited first draft and outline. It is a poor fit if you need publication-ready text, have no API keys, or want a finished app with no setup, since the README centres on a Python package.
Install options & downloads