Lightning Rod Python SDK

The Lightning Rod SDK provides a simple Python API for generating custom forecasting datasets to train your LLMs. Transform news articles, documents, and other real-world data into high-quality training samples automatically.

Based on our research: Future-as-Label: Scalable Supervision from Real-World Outcomes

Documentation: docs.lightningrod.ai

👋 Quick Start

1. Install the SDK

Install for as a Python library:

pip install lightningrod-ai

Or install the Claude Code plugin for agentic use:

/plugin marketplace add lightning-rod-labs/lightningrod-python-sdk
/plugin install lightningrod-python-sdk

The plugin adds the lightningrod-assistant agent plus skills for forecasting datasets, content-learning datasets, tabular data, BigQuery seeds, custom files, and transform verification.

2. Get your API key

Sign up at dashboard.lightningrod.ai to get your API key and $50 of free credits.

lr = LightningRod(api_key="your-api-key")

Or export your API key in the shell before starting Claude Code session for agentic use:

export LIGHTNINGROD_API_KEY="your-api-key

3. Generate your first dataset

Generate 1000+ forecasting questions easily - from raw sources to labeled dataset, automatically. ⚡

pipeline = QuestionPipeline(...)
dataset = lr.transforms.run(pipeline)

We use this to generate the Future-as-Label training dataset for our research paper.

4. Train & eval a model on your dataset

Training a custom model is as easy as plugging in the generated dataset in the previous step:

train_dataset, test_dataset = prepare_for_training(dataset)
train_config = GRPOTrainingConfig(base_model_id="openai/gpt-oss-120b")
training_job = lr.training.run()
eval_job = lr.evals.run_from_training_job(train_config, training_job, test_dataset)

5. Inference

You can perform inference on your fine-tuned models or use our frontier forecasting models like Foresight-v3.

lr.predict(training_job.model_id, "Will the Fed cut rates by 25hp in the next 3 months?")

Check the API docs for use with OpenAI compatible API.

✨ Examples

We have example notebooks to help you get started. If you have trouble using the SDK, please submit an issue on GitHub.

Quick Start

Example Name	Path	Google Colab Link
Quick Start	notebooks/00_quickstart.ipynb	Open in Colab

Getting Started

Example Name	Path	Google Colab Link
News Datasource	notebooks/getting_started/01_news_datasource.ipynb	Open in Colab
Custom Documents	notebooks/getting_started/02_custom_documents_datasource.ipynb	Open in Colab
BigQuery Datasource	notebooks/getting_started/03_bigquery_datasource.ipynb	Open in Colab
Answer Types	notebooks/getting_started/04_answer_types.ipynb	Open in Colab
GRPO Training	notebooks/getting_started/05_grpo_training.ipynb	Open in Colab
SFT Training	notebooks/getting_started/06_sft_training.ipynb	Open in Colab

Custom Filesets

Example Name	Path	Google Colab Link
Create Fileset	notebooks/custom_filesets/01_create_fileset.ipynb	Open in Colab
Basic QA Generation	notebooks/custom_filesets/02_basic_qa_generation.ipynb	Open in Colab
Advanced Features	notebooks/custom_filesets/03_advanced_features.ipynb	Open in Colab
Beige Book (Document Labeling)	notebooks/custom_filesets/04_beige_book_e2e.ipynb	Open in Colab

Answer Types

Example Name	Path	Google Colab Link
Binary	notebooks/answer_types/binary.ipynb	Open in Colab
Continuous	notebooks/answer_types/continuous.ipynb	Open in Colab
Multiple Choice	notebooks/answer_types/multi-choice.ipynb	Open in Colab

Evaluation

Example Name	Path	Google Colab Link
Foresight-v3 Model	notebooks/evaluation/01_foresight_model.ipynb	Open in Colab
Model Consensus	notebooks/evaluation/02_model_consensus.ipynb	Open in Colab
Polymarket Backtesting	notebooks/evaluation/03_polymarket_backtesting.ipynb	Open in Colab
Document Classification	notebooks/evaluation/04_document_classification.ipynb	Open in Colab

Fine Tuning

Example Name	Path	Google Colab Link
Golf Forecasting	notebooks/fine_tuning/01_golf_forecasting.ipynb	Open in Colab
Trump Forecasting	notebooks/fine_tuning/02_trump_forecasting.ipynb	Open in Colab
Survival LLM	notebooks/fine_tuning/03_survival_llm.ipynb	Open in Colab
Military Strikes Forecasting	notebooks/fine_tuning/04_military_strikes.ipynb	Open in Colab

For full documentation, see docs.lightningrod.ai. For the SDK API reference in this repo, see API.md.