AutoPredict

Quick Start — Simple Examples

New to AutoPredict? Start here before reading the full docs.

1. Scan what's trending on Polymarket right now

python3 predict.py --top 10

Shows the 10 most active markets with spreads, depth, and overround signals.

2. Show me the 5 most liquid markets

python3 predict.py --top 5 --verbose

Lists markets sorted by liquidity with full execution details.

3. Browse multi-outcome events for structural mispricing

python3 predict.py --events --top 10

Checks whether event probabilities sum to more or less than 100%.

4. What does the order book look like for a specific market?

python3 predict.py --fair 0.55 <condition_id>

Replace

<condition_id>

with the Polymarket ID. Provide your own fair probability estimate and AutoPredict evaluates the trade.

Run

python3 predict.py --help

for all flags. No credentials required for live reads.

---

AutoPredict is an execution framework for prediction-market trading. It is not a forecasting model.

• You provide

  fair_prob

  .
• The repo evaluates execution quality: side, order type, size, spread, depth, slippage, and risk.
• Live market reads require internet but no credentials.
• Real trading is scaffolded, not production-ready.

This skill was audited against the upstream repository layout and command surface, not just the README.

What Is Real vs Scaffold

Reliable entry points

• python3 predict.py

  scans live Polymarket markets.

• python3 predict.py --events

  inspects multi-outcome event overround / underround.

• python3 predict.py --fair 0.60 <condition_id>

  evaluates one market using your explicit probability.

• python3 -m autopredict.cli backtest --dataset ...

  runs an offline backtest.

• python3 -m autopredict.cli score-latest

  prints the most recent saved metrics JSON.

Partially implemented or scaffold-only

• python3 -m autopredict.cli learn analyze

  only works if you already have JSONL trade logs. Plain CLI backtests do not create those logs.

• python3 -m autopredict.cli learn tune

  and

  learn improve

  are placeholders that point to a nonexistent

  scripts/learn_and_improve.py

  .

• python3 -m autopredict.cli trade-live

  is intentionally disabled by config.

• scripts/run_paper.py

  and

  scripts/run_live.py

  are deployment scaffolds.

  run_live.py

  uses a

  MockVenueAdapter

  , so it is not a real exchange adapter.

Repo Map

• predict.py

  : live Polymarket scanner and one-off evaluation path.

• autopredict/cli.py

  : packaged CLI used for backtest, score-latest, and learning commands.

• run_experiment.py

  : simple offline backtest harness used by

  autopredict.cli backtest

  .

• strategy_configs/*.json

  : strategy knobs for offline experiments.

• autopredict/_defaults/datasets/sample_markets.json

  : bundled sample dataset. Use this when you need a known-good backtest input.

• autopredict/learning/tuner.py

  : reusable grid-search API. Better than the stub CLI.

• scripts/run_paper.py

  ,

  scripts/run_live.py

  : paper/live monitoring templates.

Decision Tree

1. Choose the workflow

If the user wants to:

• Find liquid live markets or structural event mispricing: use

  predict.py

  via

  scripts/scan_markets.sh

  .
• Evaluate one market with a known fair probability: use

  predict.py --fair ...

  .
• Compare strategy configs or produce reproducible metrics: use

  python3 -m autopredict.cli backtest --dataset ...

  via

  scripts/run_backtest.sh

  .
• Sweep parameters safely: use

  scripts/tune_params.sh

  . Do not use

  python3 -m autopredict.cli learn tune

  .
• Inspect trade logs: use

  python3 -m autopredict.cli learn analyze --log-dir ...

  only if JSONL logs already exist.
• Discuss paper/live deployment scaffolds: read

  docs/DEPLOYMENT.md

  ,

  configs/*.yaml

  , and the Python runners before claiming the repo can trade live.

2. Choose the command surface

• Use

  predict.py

  for live reads and one-off agent evaluation.
• Use

  python3 -m autopredict.cli ...

  for reproducible offline backtests.
• Avoid

  python3 -m autopredict.backtest.cli ...

  ; that submodule has brittle import behavior in the current repo state.

3. Choose the data source

• For a quick smoke test: use

  autopredict/_defaults/datasets/sample_markets.json

  .
• For real research: require a user-supplied dataset of historical snapshots.
• If the user has no dataset and wants strategy performance claims, stop and say the repo cannot produce a valid backtest without one.

Setup

Preferred helper:

bash skills/autopredict/scripts/setup.sh --dir /tmp/autopredict

Manual setup:

git clone https://github.com/howdymary/autopredict.git /tmp/autopredict
cd /tmp/autopredict
python3 -m pip install -e .
python3 predict.py --help
python3 -m autopredict.cli --help

After setup, keep work inside the cloned repo when invoking upstream commands.

Opinionated Workflows

Workflow A: Fast live market triage

Use this when the user wants ideas, not a PnL claim.

cd /tmp/autopredict
python3 predict.py --top 10 --verbose
python3 predict.py --events --top 10

Interpretation:

• Prefer markets with tight spreads and visible depth.
• Treat event underround as a structural clue, not automatic free money.
• Only move to trade evaluation once you can justify a

  fair_prob

  .

Workflow B: Evaluate a single conviction

Use this when the user already has a thesis on one market.

cd /tmp/autopredict
python3 predict.py --fair 0.60 <condition_id>

Important caveat:

• predict.py --fair

  constructs

  AutoPredictAgent(AgentConfig())

  directly.
• That means it uses default agent parameters, not

  strategy_configs/baseline.json

  or your edited JSON config.
• Use it as a default-policy sanity check, not as proof that a tuned config behaves the same way.

Workflow C: Backtest a strategy config

Use this when the user wants reproducible metrics or config comparisons.

cd /tmp/autopredict
python3 -m autopredict.cli backtest \
  --config strategy_configs/baseline.json \
  --dataset autopredict/_defaults/datasets/sample_markets.json

python3 -m autopredict.cli score-latest

Opinionated rule:

• Always pass

  --dataset

  .
• The repo default

  config.json

  sets

  "default_dataset": null

  .
• Running

  python3 -m autopredict.cli backtest

  with no dataset currently throws a

  TypeError

  .

Workflow D: Tune parameters

Use the bundled helper instead of the stub CLI:

bash skills/autopredict/scripts/tune_params.sh \
  --dir /tmp/autopredict \
  --dataset autopredict/_defaults/datasets/sample_markets.json \
  --param min_edge 0.03,0.05,0.08 \
  --param aggressive_edge 0.10,0.12,0.15

Opinionated tuning rules:

• Start with 1-2 parameters, not 6.
• Prefer

  sharpe

  or

  total_pnl

  only after sample size is reasonable.
• Reject “best” configs with too few trades.
• Save every run; do not trust memory or terminal output.

Workflow E: Review learning / deployment scaffolds

Use this when the user asks about self-improvement, paper trading, or live trading.

• autopredict.learning.tuner.GridSearchTuner

  is real and reusable.

• python3 -m autopredict.cli learn tune

  is just a message, not a tuning engine.

• scripts/run_paper.py

  is a monitoring loop template; it does not fetch real markets or execute the full agent logic.

• scripts/run_live.py

  requires confirmation and safety flags, but still uses

  MockVenueAdapter

  , so it cannot trade a real venue out of the box.

Strategy Knobs That Matter

Main JSON parameters in

strategy_configs/*.json

:

• min_edge

  : minimum edge before any trade is considered.

• aggressive_edge

  : threshold for using market orders more aggressively.

• max_risk_fraction

  : position sizing as fraction of bankroll.

• max_position_notional

  : hard dollar cap per order.

• min_book_liquidity

  : minimum visible depth required.

• max_spread_pct

  : spread filter.

• max_depth_fraction

  : cap as fraction of visible depth.

• split_threshold_fraction

  : start slicing when order is too large relative to depth.

Opinionated tuning guidance:

• Lower

  min_edge

  only if trade count is too low.
• Raise

  aggressive_edge

  if slippage is the dominant problem.
• Lower

  max_depth_fraction

  before touching risk caps when market impact is the problem.
• Do not loosen spread and liquidity filters at the same time; you will not know which one caused the regression.

Failure Modes and Edge Cases

Backtest failures

• TypeError

  before the backtest starts: almost always because no

  --dataset

  was passed and

  default_dataset

  is

  null

  .

• No metrics.json found under state directory

  :

  score-latest

  was run before a successful backtest.
• Malformed JSON errors: invalid strategy config or dataset schema.

Learning workflow failures

• learn analyze

  reports no logs: expected unless you created JSONL logs with

  TradeLogger

  or a scaffold that writes them.

• learn tune

  /

  learn improve

  prints advice only: expected. Those subcommands are placeholders.
• Docs mention

  scripts/learn_and_improve.py

  : that script does not exist in the audited upstream repo.

Live / paper trading confusion

• Paper trading is not the same as live market scanning:

  run_paper.py

  is a loop scaffold, not an end-to-end paper execution engine over Polymarket.
• Live trading docs sound complete, but adapter is mock:

  run_live.py

  cannot place real venue orders without extra implementation.

• trade-live

  CLI is disabled:

  config.json

  defaults

  live_trading_enabled

  to

  false

  .

Command-path gotchas

• Do not use

  python3 -m autopredict.backtest.cli

  in this repo state unless you are ready to debug import-path issues.
• Do not assume root docs and packaged CLI are fully synchronized. The package path under

  autopredict/

  is the safer source of truth.
• Do not claim config changes affect

  predict.py --fair

  unless you verified the code path. It currently ignores

  strategy_configs/*.json

  .

Helper Scripts Bundled With This Skill

• scripts/setup.sh

  : clone, install, verify, and smoke-test the repo.

• scripts/scan_markets.sh

  : wrapper around

  predict.py

  for live scan /

  --events

  /

  --fair

  paths.

• scripts/run_backtest.sh

  : safe backtest wrapper that always provides a dataset or fails with a useful error.

• scripts/tune_params.sh

  : grid-search wrapper that bypasses the upstream stub tuning CLI.

Recommended Agent Behavior

When using this skill:

• Lead with the limitation that AutoPredict optimizes execution, not prediction.
• Ask where

  fair_prob

  comes from before discussing edges as if they were alpha.
• Require a dataset for any serious backtest claim.
• Separate “works in the repo” from “documented in the repo”.
• Treat paper/live trading as architecture review unless the user is explicitly asking to extend the scaffold.

Autoresearch Pairing

Use this skill with

autoresearch

when the user wants disciplined tuning.

Recommended setup:

1. Define the target metric, usually

   sharpe

   ,

   total_pnl

   , or

   avg_slippage_bps

   .
2. Use

   scripts/run_backtest.sh

   or

   scripts/tune_params.sh

   as the experiment workload.
3. Keep one hypothesis per run.
4. Store configs and metrics under a dated output directory.

Good autoresearch prompt framing:

• “Optimize

  aggressive_edge

  and

  max_depth_fraction

  for lower slippage without collapsing trade count.”
• “Improve Sharpe on this dataset while keeping max drawdown below 35%.”

Bad framing:

• “Make it profitable” with no dataset.
• “Tune everything” with no metric priority.