Allora Forge Builder Kit

Build, evaluate, and deploy ML inference workers on the Allora Network.

Important

SDK v10 — testnet and mainnet. Both networks have completed the emissions v9 → v10 chain upgrade. This repository pins allora-sdk==1.4.0rc4 for scalar and labeled multi-output submissions.

pip install "allora-forge-builder-kit @ git+https://github.com/allora-network/allora-forge-builder-kit.git@main"

Contents

• What is Allora?
• What is the Allora Forge?
• What you get
• Topic types
• Topics
• Quick start
• The learning problem
• Evaluation metrics
• Worker operations
• Development and references

What is Allora?

Allora is a decentralized AI network that coordinates predictions across many independent ML models. Rather than relying on a single model, the network aggregates inferences from competing workers and weights them by historical accuracy — producing a combined output that outperforms any individual contributor.

The network is organized into topics. Each topic defines a prediction task (e.g. "8-hour BTC/USD log return") and runs a continuous lifecycle:

1. Submission window opens — the network pings all registered workers for their inference
2. Workers respond with a prediction value
3. Evaluation window runs for the topic's time horizon (e.g. 8 hours)
4. Scores are revealed — workers are ranked by loss against the ground truth, and rewards are distributed

time ──────────────────────────────────────────────────────────────────►

  ◄── submission ──►◄─────────────── evaluation period (e.g. 8h) ──────►
  │                 │                                                    │
open             close                                               scores
workers          predictions                                        revealed
polled           locked                                           + rewarded

Live topics include crypto market predictions and commodity triple-barrier classification. New topics are added over time.

What is the Allora Forge?

The Allora Model Forge is the hub for ML practitioners to compete, earn rewards, and build reputation on the network. Workers start on testnet to establish a track record, then graduate to mainnet where top performers earn ALLO token rewards.

This toolkit handles everything between your model and the network: data, feature engineering, evaluation, wallet management, and worker deployment.

What you get

• Workflow API — backfill historical data → engineer features → build training datasets
• Evaluation — grade your model against Allora's scoring methodology before deploying
• Deployment tooling — wallet creation, faucet funding, worker lifecycle management
• Monitoring dashboard — web UI showing submission history, on-chain scores, and live logs
• Topic discovery — query all live topics on testnet and mainnet

---

Topic types

The workflow supports three target types. Price topics use the log-return workflow and convert its prediction to an absolute price at submission.

Topic family	Workflow target_type	Worker output
Price / log returns	log_return (default)	Absolute price or log return, as required by the topic
Volatility	volatility	Nonnegative horizon-scaled realized volatility
Triple barrier	triple_barrier	Labeled probabilities: down, neutral, up

Topics

Price / log returns

Predict future price or log(future price / current price). Start with the topic 69 price walkthrough, topic 77 fast price walkthrough, or topic 83 log-return workflow.

Playground topics:

Testnet ID	Name	Target type	Notes
69	BTC/USD - 1 Day Price Prediction	Price	Example walkthroughs use this
77	BTC/USD - 5 Min Price Prediction	Price	Playground Fast
90	Hyperliquid perps — 3-minute log returns	Labeled log returns	Pooled LightGBM; up to 100 asset labels per worker

Mainnet topics and testnet equivalents:

Mainnet ID	Mainnet Name	Testnet ID	Testnet Name
1	BTC/USD - Log Returns - 8h	83	BTC/USD - 8h Log-Return Prediction
2	ETH/USD - Log Returns - 8h	84	ETH/USD - 8h Log-Return Prediction
3	SOL/USD - Log Returns - 8h	58	8h SOL/USD Log-Return Prediction
9	ETH/USD - Price Prediction - 8h	41	ETH/USD - 8h Price Prediction
10	SOL/USD - Price Prediction - 8h	38	SOL/USD - 8h Price Prediction
14	BTC/USD - Price Prediction - 8h	42	BTC/USD - 8h Price Prediction
15	BTC/USD - Log Returns - 24h	61	1 day BTC/USD Log-Return Prediction
16	ETH/USD - Log Returns - 24h	63	1 day ETH/USD Log-Return Prediction
17	SOL/USD - Log Returns - 24h	62	1 day SOL/USD Log-Return Prediction
18	BTC/USD - Log Returns - 20m	—	Missing
19	NEAR/USD - Log Returns - 8h	71	8h NEAR/USD Log-Return Prediction

Volatility

Predict sample_std(r₁, …, r_H) × √H for consecutive one-minute log returns, using ddof=1. See the BTC grid-search workflow. Equivalent workflows are available for ETH, XRP, SOL, and 4-hour ETH.

Testnet ID	Name	Target type	Notes
79	BTC/USD - 15 Min Volatility Prediction	Volatility	Sample std of 1-min log returns × √15
80	ETH/USD - 15 Min Volatility Prediction	Volatility	Same definition as 79, ETH pair
81	XRP/USD - 15 Min Volatility Prediction	Volatility	Same definition as 79, XRP pair
82	SOL/USD - 15 Min Volatility Prediction	Volatility	Same definition as 79, SOL pair
85	ETH/USD - 4h Volatility Prediction	Volatility	Sample std of 1-min log returns × √240

Triple barrier

Predict which price barrier is touched first, or neutral if neither is touched before expiry. Follow the triple-barrier walkthrough. These commodity datasets require Atlas; Binance is not an alternative source.

Testnet ID	Asset	Atlas dataset	Horizon
87	Gold	hl_xyzgold_1min	24h
88	Silver	hl_xyzsilver_1min	24h
89	WTI oil	hl_xyzcl_1min	24h

The tables are a repository reference. For current network metadata, see topic discovery and the Forge.

Quick start

1. Set up the environment

Use Python 3.10 or newer. The repository pins allora-sdk==1.4.0rc4, including support for labeled multi-output submissions.

git clone https://github.com/allora-network/allora-forge-builder-kit.git
cd allora-forge-builder-kit
python3.11 -m venv notebooks/.venv
source notebooks/.venv/bin/activate
pip install -e ".[dev,wallet-link]"
export REPO_ROOT="$PWD"

Get an API key from developer.allora.network, save it locally as .allora_api_key, then load it without displaying it:

export ALLORA_API_KEY="$(cat "$REPO_ROOT/.allora_api_key")"
export ALLORA_NETWORK=testnet

Keep the same shell for the commands below. Binance can be used for supported crypto datasets when adapting a workflow; the examples below use Atlas.

2. Run one example and deploy its artifact

Choose one block. Each uses its own working directory for artifacts and worker state. Training can take substantial time, especially the volatility grid search. The scripts print their evaluation results and output locations.

Hyperliquid perps — topic 90 (three workers):

Run from the repository root with the activated environment and Atlas API key configured above. The full parameter grid, lookback, six-month history, tree checkpoints, and number of exported models are at the top of example.py.

cd "$REPO_ROOT"
# Fetch available history; existing minute parquet stays under the example's data/.
python notebooks/testnet/topic_90_hyperliquid_3min_logreturn/example.py --backfill-only
# Train from that cache, evaluate, and export the three best distinct trials.
python notebooks/testnet/topic_90_hyperliquid_3min_logreturn/example.py
# Replace the path below with the results/model_search/<timestamp> printed above.
python notebooks/testnet/topic_90_hyperliquid_3min_logreturn/deploy_managed_example.py \
  --model-run notebooks/testnet/topic_90_hyperliquid_3min_logreturn/results/model_search/RUN_TIMESTAMP \
  --deploy

Each exported model_1 / model_2 / model_3 directory contains a full-data-refitted model.joblib, training-fitted return calibration, and raw/scaled validation reports in both pooled and equal-weight per-asset views. A chronological holdout reserves the latest 20% of observed timestamps for validation; training labels that resolve after the validation boundary are excluded. Selection uses the lowest validation MSE per trial. Those reports are validation-selected, not independent test results. top_models.json tells the launcher which models to package. Omit --deploy to create the callable artifacts without allocating workers.

WorkerManager allocates a separate local wallet for each model and records it in that model's managed_worker.json. Keep those files to reuse the same addresses. Workers run in independent process sessions: no tmux or open terminal is required. They survive launcher exit, but are not automatically restarted after a host reboot. Existing workers outside this deployment are not stopped.

Each artifact tops up its own in-memory minute buffer before listening. At inference it anchors to the nonce's minute, waits ten seconds, refreshes Atlas data in bulk, resamples history to that exact boundary, and applies each asset's partial-candle offset. It submits up to 100 available predictions by cached volume rank; unavailable assets are omitted. Runtime state and API keys are not embedded in the artifacts.

For example, a window opening at 12:01:27 UTC targets 12:01–12:04, even though submission closes around 12:01:57. The final completed input bar is labeled 11:58 and ends at 12:01. The worker separately checks each asset's 12:01-labeled partial candle and adds its observed log price drift to the model prediction; if that candle is missing, the asset gets a zero-drift adjustment. The ten-second wait does not move the target boundary.

For direct Atlas access, using a configured AtlasDataManager instance:

symbols = atlas.discover_hl_universe()
minutes = atlas.get_bulk_1min_candles(symbols, limit=10)

Discovery returns exact Atlas dataset names for fresh, consumable native perps. The bulk call uses one HTTP request; limit is per asset, with at most 10,000 requested rows across the batch. It returns raw one-minute OHLCV indexed by (symbol, open_time), preserving partial candles and gaps. It does not resample or write to the local cache.

Logs go to worker_logs/worker_90_<address>.log in the launch directory. Inspect workers with:

python -m allora_forge_builder_kit.workerctl dashboard

Price — topic 69:

mkdir -p "$REPO_ROOT/notebooks/runs/price_example"
cd "$REPO_ROOT/notebooks/runs/price_example"
python "$REPO_ROOT/notebooks/example_topic_69_bitcoin_walkthrough.py"
TOPIC_ID=69 PREDICT_PKL="$PWD/predict.pkl" python "$REPO_ROOT/notebooks/deploy_worker.py"

Volatility — topic 79: runs the default 800-day grid search and saves ranked artifacts and a scatter plot, and prints evaluation metrics. Deploy the highest-ranked artifact:

mkdir -p "$REPO_ROOT/notebooks/runs/volatility_example"
cd "$REPO_ROOT/notebooks/runs/volatility_example"
python "$REPO_ROOT/notebooks/testnet/topic_79_btc_vol/model_grid_retrain.py"
TOPIC_ID=79 PREDICT_PKL="$PWD/predict_79_grid_rank1.pkl" python "$REPO_ROOT/notebooks/deploy_worker.py"

Triple barrier — topic 87:

cd "$REPO_ROOT"
python notebooks/example_triple_barrier_walkthrough.py --topic 87
mkdir -p notebooks/triple_barrier_example_output/worker
cd notebooks/triple_barrier_example_output/worker
TOPIC_ID=87 PREDICT_PKL="$REPO_ROOT/notebooks/triple_barrier_example_output/predict.pkl" python "$REPO_ROOT/notebooks/deploy_worker.py"

Triple-barrier outputs are in notebooks/triple_barrier_example_output/: predict.pkl, config.json, metrics.json, predictions.csv, report.txt, trades.csv, and six charts. Repeated runs replace these outputs; use --output-dir to retain another run. Data is cached inside the output directory unless --cache-dir is supplied. To use Silver or WTI, change both the example's --topic and deployment's TOPIC_ID to 88 or 89.

Deployment creates a wallet, requests testnet funding, and starts a worker. Inspect worker_logs/ for funding, registration, or submission failures. A started process alone does not confirm successful submissions.

3. Monitor

From the same worker directory:

python -m allora_forge_builder_kit.web_dashboard

Open http://localhost:8787 to inspect submissions, scores, and logs. For a terminal summary, use python -m allora_forge_builder_kit.workerctl dashboard.

The learning problem

Framing forecasting as supervised learning

At any point in time $t$, the model observes a window of $N$ past bars as input features $\mathbf{x} \in \mathbb{R}^d$ and predicts a future outcome $y$ over the next $H$ bars. The target $y$ depends on the topic type:

• Price / log-return topics — $y = \log(p_{t+H} / p_t)$ or the absolute price $p_{t+H}$

• Volatility topics — $y = \text{sample_std}(r_1, \ldots, r_H)\sqrt{H}$, using ddof=1, where $r_i = \log(p_{t+i} / p_{t+i-1})$ are consecutive 1-minute log returns over the horizon

• Triple-barrier topics — a one-hot label for the first upper/lower barrier touched, or neutral at expiry. Models submit probabilities labeled down, neutral, and up.

By sliding this window across the full history, a single time series becomes thousands of labeled examples $(\mathbf{x}_i, y_i)$, turning forecasting into a standard supervised learning problem.

The AlloraMLWorkflow handles this construction: backfill() fetches historical data, get_full_feature_target_dataframe() builds the feature matrix and target vector, ready for any scikit-learn compatible model.

Triple-barrier targets

The horizon is target_bars × interval. The example uses 100 hourly input bars, 24 target bars, and a barrier multiplier of 0.25. These settings define Forge topics 87–89; changing the native interval or horizon defines a different target. The general builder accepts other configurations for research. Historical source candles must be one-minute data (Atlas supplies these regardless of feature interval). ATR is the mean high–low log range over 100 target horizons, computed on native/resampled candles.

For hourly bars and prediction time T, average the 2,400 samples opening in [T − 2401h, T − 1h). Each range includes both endpoints of [t − 24h, t] (25 hourly openings). Match the reputer's SQL by restricting history to the averaging interval first, so the initial ranges are partial.

With base price P equal to the minute close at T − 1m, upper and lower barriers are P × exp(0.25 × ATR) and P × exp(−0.25 × ATR). Test minute high/low candles in [T − 1m, T + 24h − 1m) chronologically: first lower touch → down; first upper touch → up; no touch → neutral. A same-minute tie resolves down. Missing required coverage leaves targets null. Allow 100 horizons plus one native bar of history before usable targets, plus sufficient training and evaluation data.

The walkthrough illustrates the learning problem, fold periods, confusion matrix, example trades, and cumulative PnL. Trades use overlapping one-unit positions, exact barrier fills, and the last in-window close at expiry. --trade-cost-bps sets per-side trading costs (default zero); these plots are not capital-normalized portfolio returns.

Target implementation.

Empirical risk minimization

The standard recipe is to pick a model $f$ by minimizing empirical (in-sample) loss:

$$f^* = \arg\min_{f \in \mathcal{F}} \frac{1}{n} \sum_{i=1}^{n} \ell(y_i,, f(\mathbf{x}_i))$$

The ERM assumption is that training and deployment data share the same distribution — so a model that fits well in-sample will generalize out-of-sample. This is a reasonable working assumption in many domains.

Why finance makes this hard

Financial markets violate the ERM assumption routinely:

• Regime changes — volatility regimes, macro shocks, and structural breaks mean the distribution of returns today can look nothing like last year's.
• Non-stationarity — correlations, volatility, and return distributions all drift over time.
• Low signal-to-noise — crypto returns are heavily noise-dominated, making it easy to fit noise rather than signal.

The practical consequence is that overfitting is the default failure mode. A model can lower in-sample loss while out-of-sample loss increases — more model complexity captures noise instead of signal. Traditional remedies (early stopping, depth limits, regularization, conservative learning rates) are especially important here.

Walk-forward validation

To measure true out-of-sample performance the toolkit uses walk-forward cross-validation: train on data up to time $t$, evaluate on data strictly after $t$, advance the window, repeat. This respects temporal ordering (no lookahead leakage) and produces a realistic sample of out-of-sample predictions. The evaluation metrics in the next section are computed entirely on these held-out predictions.

The model builder's job

The example notebooks use LightGBM (gradient boosting over decision trees) with conservative defaults as a starting point. Gradient boosting is a strong tabular baseline — it handles non-linearity and feature interactions well and is relatively robust to scale.

From here, improving your score comes down to three levers:

1. Feature engineering — what information goes into $\mathbf{x}$. The base features are normalized OHLCV ratios (last-close normalized to 1.0). Adding technical indicators (RSI, MACD, realized volatility), log-return series, or cross-asset signals is where most alpha lives.
2. Model and regularization — early stopping, tree depth, learning rate, and subsampling to keep variance in check.
3. Out-of-sample evaluation — use the metrics appropriate to the topic family below. The triple-barrier example defaults to five folds: the first three select the lowest mean log loss, and the last two supply combined OOS evaluation. The selected configuration stays fixed; each OOS fold refits using labels available at its cutoff, including earlier OOS outcomes once resolved. Production refitting follows evaluation. --folds and --holdout-folds control the split; LGBM_SEARCH_GRID and LGBM_FIXED_PARAMS near the top of the script expose the model search. Just below them, edit ENGINEERED_SPECS and engineer_features() to add derived features; the same function runs during training and is captured in the inference artifact.

For structured methodology guidance on each of these levers, see the Model creation skills section.

Evaluation metrics

Evaluation depends on the topic family. Offline reports help assess a model; network participation and live scores must be checked after deployment.

Price / log returns

The price examples evaluate predicted log returns before converting to prices for submission. PerformanceEvaluator reports seven primary criteria and a letter grade:

#	Criterion	Requirement
1	Effective samples	≥ 20, before horizon adjustment
2	Directional accuracy	One-sided 95% lower confidence bound > 50%
3	Pearson correlation	Two-sided 95% lower confidence bound > 0
4	WRMSE improvement	Horizon-adjusted 95% lower bound > 0
5	WCZAR improvement	Horizon-adjusted 95% lower bound > 0
6	Log aspect ratio	Confidence interval overlaps [-0.5, +0.5]
7	Participation	> 90%

All seven must pass for report["eligible"]. Estimators and criteria are ported from worker-metrics revision bd01f9d2bdb6351e351ecddeb68d0fb101ebc0ee. DA and improvement bounds use sqrt(max(1, horizon_minutes / 20)) as the effective-sample multiplier; Pearson and aspect ratio are unscaled.

Existing evaluate(y_true, y_pred, epoch_length_minutes=3) and print_report(report) calls still work. Without submission counts, the report explicitly assumes full offline participation. Supply n_expected_epochs and optionally n_submitted for observed participation; optional lags, gt_ratio, and horizon_seconds describe irregular/overlapping samples. Defaults assume one horizon per row. Offline pooled-asset results do not establish live participation or cross-asset independence.

Grading:

Points (out of 7)	Grade
7	A+
6	A
5	B+
4	B
3	C
2	D
≤ 1	F

Volatility

The volatility workflows calculate their own metrics in vol_metrics. These are example diagnostics, not the return evaluator's seven-point grade.

Metric	Purpose
Pearson r / Spearman rho	Linear / rank association
R² / RMSE	Explained variation / prediction error
QLIKE	Relative volatility prediction loss
Calibration ratio	Predicted standard deviation divided by actual standard deviation

The example ranks models using R² − 0.5 × QLIKE − 0.3 × abs(1 − calibration ratio); see composite_score.

Triple barrier

evaluate_classification consumes probabilities in [down, neutral, up] order. Hard classes for accuracy and confusion matrices use deterministic argmax; submissions retain probabilities. The causal baseline uses the previous 100 resolved targets, with uniform probabilities when no prior targets exist.

Criterion	Strict threshold
Accuracy improvement over baseline	> 0.02
Accuracy-improvement lower bound	> 0
Quadratic weighted kappa lower bound	> 0
Brier skill lower bound	> 0
Focal skill lower bound	> 0
Participation	> 0.90

Brier loss is the mean sum of squared probability errors. Focal loss is mean(−(1 − p_true)² × ln(p_true)), clipping only p_true to [1e-15, 1]. Both skills are 1 − worker loss / baseline loss. Kappa treats classes as ordinal.

Bounds use paired circular bootstrap blocks of 10 rows, 1,000 replicates, and 5th/95th percentiles. Reports include raw metrics, intervals, individual criteria, and eligible when all six pass; there is no letter grade. Offline participation is coverage of the evaluation sample, not observed network participation.

Optional directional payoff awards +1 for a correct directional class, −1 for an opposite class, and zero when either class is neutral, minus the declared cost for a directional prediction. --diagnostic-cost sets this cost in barrier units, separately from trading costs. It is not a seventh eligibility criterion.

Worker operations

Local workers

Use the deployment script and WorkerManager for lifecycle operations. Worker state, keys, and logs belong to the working directory used at deployment; run monitoring and wallet-linking commands there. Keep generated state and secrets out of git.

The dashboard defaults to localhost. --host 0.0.0.0 exposes it on all interfaces; use the authentication token printed to stderr as the URL's ?token=... parameter.

Managed-custody security: FORGE_API_KEY is a managed-wallet signing credential, not a transaction-scoped permission. The remote signer can sign arbitrary SignDoc bytes and 32-byte digests. Disabling the optional /transfer route does not constrain /sign. Protect and revoke this key like a private key.

Wallet linking: setup, options, and troubleshooting

Wallet linking

When you deploy a local-custody worker the signing key lives in worker_keys/ on your machine, but Forge doesn't know which allo1... addresses belong to your account. Wallet linking proves ownership: the CLI signs an ADR-036 challenge with each local worker key and a browser-authenticated Forge user approves the link.

Managed-custody workers (deployed with custody="managed") are linked automatically by the backend — no workerctl link step needed.

Custody modes at a glance

Mode	Key lives	Linking
Local (default)	worker_keys/ on your machine	Run workerctl link once per address
Managed	Forge backend (Privy wallet)	Automatic — no CLI step

Quick start

# Requires the wallet-link extra (cosmpy for ADR-036 signing)
pip install -e ".[wallet-link]"

# Link all local worker wallets to your Forge account
workerctl link

The CLI:

1. Reads your worker_secrets.json to find local key files
2. Opens a device-flow session with the Forge API
3. Signs each ADR-036 challenge locally — the mnemonic never leaves your machine
4. Opens your browser; you approve with your logged-in Forge account
5. Polls until approved and prints which addresses were linked

$ workerctl link

Linking 2 worker address(es) to Allora Forge at https://forge.allora.network

  First copy your one-time code: ABCD-1234
  Then approve the link at: https://forge.allora.network/link?code=ABCD-1234

Opened your browser. Waiting for approval...

Linked 2 verified worker(s):
  + allo1abc...
  + allo1def...

Link specific addresses

# Link a single address
workerctl link --address allo1abc...

# Link two specific addresses
workerctl link --address allo1abc... --address allo1def...

Headless / CI environments

# Print the URL and code without opening a browser
workerctl link --no-browser

Output the one-time code and URL to stdout so you can open them on a separate device or paste them into a CI log.

Non-default secrets file

workerctl link --secrets-path /path/to/worker_secrets.json

CLI reference

workerctl link accepts the following flags:

Flag	Default	Description
--secrets-path PATH	worker_secrets.json	Path to the WorkerManager secrets file that maps addresses to local key files.
--address ADDR	all local keys	Limit to a specific allo1... address. Repeatable — pass once per address.
--no-browser	off	Print the approval URL and code without auto-opening a browser.

Troubleshooting

cosmpy not found — install the wallet-link extra: pip install -e ".[wallet-link]" or pip install cosmpy==0.11.1.

No worker keys found — the secrets file is missing or empty. Deploy a local-custody worker first (WorkerManager.deploy_worker(...) or python deploy_worker.py).

No local key for: allo1... — the address is a managed-custody worker (linked automatically) or the secrets file is stale. Managed workers do not need manual linking.

Link request denied — the browser approval was rejected. Re-run workerctl link to start a fresh session.

Link request expired — the 30-minute approval window closed before the browser was used. Re-run to start a new session.

Hosting export

For hosted deployment, follow the runnable export walkthrough and export implementation. The package contains worker code, dependencies, a manifest, and optional weights. Choose training on the platform or bundling locally trained weights. The triple-barrier walkthrough currently demonstrates local WorkerManager deployment.

Hosting export: modes and deployment configuration

Or from the command line, which can also produce the upload-ready zip:

workerctl export-payload --config model.json --out build/my_lgbm_package --zip
# then upload build/my_lgbm_package.zip to forge (POST /api/v1/models)

--zip writes the package contents at the archive root, so forge finds manifest.json at the extraction root. The generated worker code is generic over pair/timeframe; code-only (train-on-platform) packages can be deployed against many pairs/timeframes/topics. Bundled-weight packages must use parameters matching how the weights were trained.

Two deployment modes

Exactly one of these must hold (forge rejects the package otherwise; export_payload_for_hosting enforces it and fails loudly):

Mode	Set	Weights	Who trains
Train-on-platform	supports_training=True (default)	none	the platform
Train-locally	supports_training=False (or --no-training) + --weights <dir>	bundled	you, before export

• Train-on-platform. The platform runs training as an allora-worker train job on a schedule the operator configures (it is not an in-process timer). Each run skips retraining if the current artifact is younger than 12h (unless FORCE_RETRAIN=true). Training only runs while supports_training is true. Before the first successful training run there is no artifact, and the generated worker's inference raises model artifact not found until one exists — expect the first inferences to fail until training completes and writes weights.
• Train-locally. supports_training=False means the platform never retrains; it serves the weights you bundled (imported into storage by the platform's import step). Updating those weights means re-exporting/re-importing — the generated worker does not hot-reload weights in this mode (the SDK's model watcher only runs for models that report a watchable artifact, which the generated model ties to supports_training).

Deployment env vars

pair/timeframe/topic are deploy-time parameters the operator injects as env vars, never baked into the package. The hosted worker reads:

Env var	Purpose	Default
PAIR	Trading pair, e.g. BTCUSD	required
TIMEFRAME	Bar interval, e.g. 5m, 1h	required
ALLORA_TOPIC_ID	Target topic	69
ALLORA_API_KEY	Required only for the allora data source	—
SUBMIT_RETURNS	true/false to force log-return vs price output; unset/auto derives it from the topic's on-chain loss method	auto
DATA_BASE_PATH	Where the worker reads/writes model artifacts	./data

Development and references

Testing

Run pytest tests/test_data_managers.py -v -m "not integration" for the data-manager unit checks. Network integration tests require RUN_INTEGRATION_TESTS=1 and an exported ALLORA_API_KEY.

For triple barrier, run RUN_INTEGRATION_TESTS=1 python -m pytest tests/test_triple_barrier.py -v -s. Its three tests build a real Atlas dataset and independently replay minute targets, run the complete example and reload its artifact, then deploy an isolated testnet worker and verify a labeled submission. They clean up their own files and worker. Add -k 'not deploy_worker' for data and example verification only.

Model creation skills

The allora_research_model_skills/ bundle contains three Claude Code skills for building financial prediction models. Each enters model design from a different angle:

Skill	Entry point
forge-hypothesis-driven	Start from a theory about what moves markets (deductive)
forge-signal-discovery	Start from interesting data, discover what is predictable (inductive)
forge-robustness-first	Start from validation gates, work backwards to a design that survives them (adversarial)

All three produce a complete, runnable pipeline and satisfy the same nine methodology principles. See allora_research_model_skills/README.md for selection guidance.

Module map

Module	Purpose
workflow.py	Data, features, and all three target builders
evaluation.py	Return and triple-barrier evaluation
engineered_features.py	Shared training/inference feature transformations
topic_discovery.py	Network topic metadata
worker_manager.py	Wallets and worker lifecycle
worker_runtime.py	Scalar and labeled inference submission
workerctl.py	CLI operations
web_dashboard.py	Monitoring UI
Feature example	Feature engineering walkthrough

Links

• Allora Network
• Allora Explorer
• Developer Portal
• Testnet Faucet
• Discord

License

MIT