Developer docs

Clone OptionLab, run the demo, replay the journal.

These docs cover the local-first path for developers who want to run market-system infrastructure on their own machine with their own credentials and their own risk choices.

git clone https://github.com/davidjbeveridge/OptionLab cd OptionLab make dev-up make demo make run

Quick Start

Run the local demo

Prerequisites are Python 3.11+, Node.js 20+, and GNU Make. The default path creates a local Python environment, installs the runtime, writes a JSONL journal, and replays it without relying on any hosted OptionLab service.

git clone https://github.com/davidjbeveridge/OptionLab
cd OptionLab
make dev-up
make demo
make run

Credentials

Keep broker and data credentials local

Use environment variables or ignored local files for provider settings. The SimBroker path does not require external credentials.

export OPTIONLAB_BROKER=sim
export OPTIONLAB_MODE=paper
make run

Paper and live warning Live adapters are local interfaces for user-controlled execution. You are responsible for credentials, risk scale, legal compliance, broker behavior, and every activation decision.

Runtime Reference

Core objects

Strategy: User-defined name, asset class, and rule payload. Rules cannot define the user's risk scale.
StrategyExecutionConfig: Strategy id, risk limit, paper/live mode, and provider ref.
StrategyExecutionActivation: Acknowledgement record that ties user confirmation to an execution config.
DecisionSnapshot: Strategy id, activation id, signal label, order intent, and timestamp.
JsonlJournal: Local append-only event trail used by the demo and replay harness.

Plugin Reference

Provider manifests and local refs

Plugins describe capabilities. Provider instances bind a local ref to a manifest and operating mode. The default local provider is `sim`, backed by SimBroker and stub market-data behavior.

ProviderManifest: Name, version, capability list, and fingerprint.
ProviderInstance: Local ref, manifest, and mode. Provider refs are what runtime config points at.
Fingerprint: Stable provider identifier recorded for audit and replay context.
Capabilities: Examples include `marketdata.stub`, `broker.paper`, and `journal.replay`.

Commands

Development and verification

make dev-upCreate the local runtime environment. make demoRun the deterministic demo and replay generated events. make runRun the local paper path. make studioStart the local Studio UI. make site-buildValidate static website assets. make gate-ciRun runtime tests, Studio build, site checks, and public-safety scan. python -m optionlab.cli replayReplay a local journal and count event types.

Legal Boundary

OptionLab provides machinery. Users provide judgment.

OptionLab is software tooling, research infrastructure, deterministic automation, and plugin-based execution infrastructure. It is not an investment adviser, broker-dealer, signal service, copy-trading platform, or account operator.

Canonical rule: OptionLab never tells users what to trade, when to trade, or how much to trade.