Skip to main content

alphaboard

Python SDK for AlphaBoard — strategy-level monitoring and reconciliation for algorithmic traders. (Formerly stratops; renamed to the single brand in OPM-762.)

from alphaboard import AlphaBoard

tracker = AlphaBoard(
    strategy="momentum_eth",
    broker="hyperliquid",
    account="main",
)

# Inside your trade execution function:
tracker.log_trade(symbol="ETH-PERP", side="buy", quantity=0.5, price=3800)
# ...and when the venue refuses an order (feeds the reject_rate alert):
tracker.log_reject(symbol="ETH-PERP", side="buy", quantity=0.5, reason="margin")

# Periodic sync:
tracker.sync_positions([{"symbol": "ETH-PERP", "quantity": 1.5, "avg_entry_price": 3750}])
tracker.log_equity(equity=50_000, cash=10_000)
tracker.heartbeat(open_positions=1)

Versions and change notes

Pass the code version the process runs, a git SHA or a script hash, and every trade and equity point carries it:

tracker = AlphaBoard(strategy="momentum_eth", broker="hyperliquid", account="main",
                     version="a1b2c3d")

When a fill or equity point reports a version the strategy has not run before, the server marks the equity chart by itself ("Version a1b2c3d (was 9f8e7d6)"). The Strategy page can then split returns before and after the mark, and a backtest uploaded with the same version is compared with that version's live span only.

For a change the version does not capture, write a note:

tracker.annotate("Stop widened from 2 to 3 ATR", kind="params")
tracker.annotate("Moved to the new VPS", kind="broker", global_=True)  # every strategy

kind is one of deploy, params, sizing, broker or note. Like every other call, annotate() returns at once and never raises.

Configuration

Connection settings resolve in this order (highest priority first):

  1. Constructor parameters — AlphaBoard(api_url=..., api_key=...)
  2. Environment variables — ALPHABOARD_API_URL, ALPHABOARD_API_KEY
  3. Config file — ~/.alphaboard/config.toml (override path via ALPHABOARD_CONFIG)
  4. Built-in defaults — http://localhost:8000, no key

The legacy STRATOPS_* env vars and ~/.stratops/config.toml are still read as a fallback (one-time deprecation warning) — switch to the new names.

Example ~/.alphaboard/config.toml:

api_url = "https://alphaboard.example.com"
api_key = "sk_..."
# Optional: turn on the durable spool (see below)
spool_dir = "C:/alphaboard-spool"

Is it actually connected? (alphaboard doctor)

Installing the SDK and seeing no errors proves nothing — the SDK never raises, by design, so a completely misconfigured client looks exactly like a working one from inside your strategy. alphaboard doctor is the one command that answers am I being watched?:

alphaboard doctor
alphaboard doctor --api-url https://alphaboard.example.com --api-key sk_...

It runs four checks in order and stops at the first failure, so you fix causes rather than symptoms:

Check Answers
api Is the server reachable, and is its database connected?
auth Does your API key authenticate?
probe Does ingestion accept a real write?
coverage The census: every strategy and account, the age of each stream, and a verdict of LIVE / DEGRADED / SILENT.

Exit codes make it usable from a scheduled task or a CI step: 2 if the API or the key is broken, 1 if everything is reachable but something is not reporting, 0 if all four pass.

Two properties are worth knowing about, because they are the difference between a diagnostic and a placebo:

  • It creates nothing. The write probe is a single infrastructure heartbeat that deliberately carries no strategy name. A probe posted under a real strategy would refresh that strategy's heartbeat stream and forward a success ping to its external monitor — so a strategy that had been dead for a day would read LIVE on the very next line of the diagnostic's own output, and its real alert would be silenced. Pass --no-probe to skip the write entirely and run read-only.
  • Zero strategies is a failure, not a pass. "0/0 live" is technically full coverage and is exactly the reassuring lie that hides a pipe that was never connected.

Durable spool (no-data-loss mode)

By default the SDK buffers events in memory only — a crash or an extended server outage can drop events (your trading is never affected either way). Setting a spool_dir (constructor param, ALPHABOARD_SPOOL_DIR, or the config file) turns on a disk-backed outbox:

tracker = AlphaBoard(strategy="momentum_eth", spool_dir="C:/alphaboard-spool")
  • Events are mirrored to a SQLite WAL file by the background worker and deleted only after the server confirms receipt — they survive SIGKILL, power loss, and outages of any length.
  • Replays reuse the same idempotency keys and carry the original event timestamps, so the server deduplicates them: at-least-once on the wire, effectively-once end-to-end.
  • The spool is bounded by rows, bytes, and age (defaults: 1M rows / 512 MB / 7 days; tune via spool_max_rows, spool_max_bytes, spool_max_age_s). On breach it drops oldest and surfaces the count via tracker.spool_dropped_count — an indefinite outage can't fill your disk.
  • Any spool failure (disk full, locked, corrupt) degrades the SDK back to memory-only. Durability never becomes a new way to crash the host.

Backfill (historical seeding + gap recovery)

alphaboard backfill replays a historical CSV — a broker statement, a Zorro log, your engine's own journal — through the server's batch endpoints with deterministic idempotency keys (UUIDv5 of each row's business key), so re-running the same file or window is a no-op, never a duplicate:

alphaboard backfill trades.csv  --kind trades --strategy momo --broker ib --account main
alphaboard backfill equity.csv  --kind equity --strategy momo --mapping '{"Time": "snapshot_at", "Equity": "equity"}'
alphaboard backfill positions.csv --kind positions --strategy momo --broker ib --account main --dry-run
  • --kind is trades, equity, or positions; --mapping renames CSV headers to canonical fields (same convention as the server's CSV import).
  • --strategy/--broker/--account fill in routing fields the CSV doesn't carry; columns present in the file win.
  • --since/--until window on the row's event time; --dry-run validates and counts without sending.
  • Rows must carry their original executed_at/snapshot_at — backfill refuses to stamp wall-clock-at-import times onto history.
  • Also available in code: tracker.backfill("trades.csv", kind="trades").

Design

The SDK is observation-path only. It never sits between your strategy and the broker. The single hard guarantee:

tracker.log_trade(...) returns in microseconds, never blocks, and never raises.

Every public method enqueues an event into a bounded in-memory deque (default 10 000 items, drop-oldest on overflow), and returns immediately. A daemon background thread batches events, posts them to the AlphaBoard API with exponential backoff, and never lets an exception escape back to user code.

If the AlphaBoard server is unreachable, events back up in the queue until it returns or the queue overflows. Your trading continues unaffected.

On process shutdown, an atexit hook drains the queue with a bounded timeout (default 5s) so events from the final loop iteration aren't lost.

Install

pip install alphaboard

That pulls in httpx and its transitive dependencies and nothing else — eight packages total. The SDK deliberately has no dependency on the API server, the dashboard, or anything else in the workspace, so it installs cleanly into a strategy process that shares none of them.

Working on the SDK itself? Install it from a checkout instead:

pip install ./packages/sdk

Licence

Apache 2.0.

Metadata

Release files for alphaboard 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alphaboard 0.2.0
File Size Uploaded Provenance Actions
alphaboard-0.2.0.tar.gz 69.9 kB With provenance Details for alphaboard-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alphaboard 0.2.0
File Interpreter ABI Platform Actions
alphaboard-0.2.0-py3-none-any.whl Python 3 none any Details for alphaboard-0.2.0-py3-none-any.whl

Total release size: 122.4 kB

Release files / alphaboard-0.2.0.tar.gz

Download URL alphaboard-0.2.0.tar.gz
Size 69.9 kB
Tags Source
SHA-256 checksum
How to use checksums
eab71b82c7615ba353b83872e8bf7a5c74286f5fd90d4c06c7c8a05312496be2
BLAKE2b-256 checksum
How to use checksums
8b0daf1b42ad576e64788db6b0408af2ab32d97899a050260ac481575d2e7bcf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / alphaboard-0.2.0-py3-none-any.whl

Download URL alphaboard-0.2.0-py3-none-any.whl
Size 52.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ccaef3fb4d08bc6538334d920b5e4ff916e3d18585005e5c7322415f8d641ef9
BLAKE2b-256 checksum
How to use checksums
a7a20659c229e641226bf0503d7cded3f24c194b56d8ebb4dd4a2ff6aa04e981
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Security for alphaboard 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for alphaboard-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page