auracle-client

Python SDK + CLI for the Auracle algorithmic trading platform.

Talk to a running Auracle install over HTTP from anywhere — your laptop, a Jupyter notebook on a different machine, a script on a server. Every Houston REST endpoint is one Python method call.

Install

pip install auracle-client

Quick start

Python

from auracle_client import AuracleClient

# Reads AURACLE_URL + AURACLE_API_KEY from env, or pass them in:
client = AuracleClient(
    base_url="https://your-auracle.example.com",
    api_key="your-per-user-api-key-from-/ui/account",
)

# Health check
print(client.healthz())   # {'status': 'ok'}

# Run a backtest synchronously (returns inline; see COMPATIBILITY.md
# for the full response shape).
result = client.backtest("strategies.templates.momentum_vol_target.MomentumVolTarget")
print(result["stats"]["sharpe"])
print(result["target_weights"])

# For long-running workloads, schedule + poll:
client.add_schedule(name="overnight_research",
                    strategy_path="strategies.heavy.MyHeavyStrategy",
                    cron="0 0 31 2 *", enabled=False)  # never auto-fires
job_id = client.run_schedule("overnight_research")
import time
while True:
    snapshot = client.get_job(job_id)
    if snapshot["status"] in ("succeeded", "failed"):
        break
    time.sleep(2)

# Schedule it to run every weekday at 13:35 UTC
client.add_schedule(
    name="daily_momentum",
    strategy_path="strategies.templates.momentum_vol_target.MomentumVolTarget",
    cron="35 13 * * 1-5",
)

CLI

# Set credentials once
export AURACLE_URL=https://your-auracle.example.com
export AURACLE_API_KEY=your-per-user-key

# Then:
auracle-client status
auracle-client securities list
auracle-client schedule list
auracle-client backtest strategies.templates.momentum_vol_target.MomentumVolTarget
auracle-client jobs list --limit 5
auracle-client logs --service scheduler --level error

For local installs with self-signed certs, add --insecure:

auracle-client --insecure --host https://localhost status

Don't have an install yet?

This SDK is a client — it talks to a running Auracle install over HTTP. To get the install itself running, see auracle-installer. One terminal command:

curl -fsSL https://raw.githubusercontent.com/SiixQuant/auracle-installer/main/install.sh | bash

Or paste the AI-install prompt from that repo's README into Claude Desktop / ChatGPT / Cursor and let it drive the install for you.

Compatibility

auracle-client and the auracle server negotiate at session init via a /version handshake — the SDK refuses to call features the server doesn't ship, and the server can refuse clients below a published floor. The current contract: server api_version: "v1", client __version__: "0.2.0", server's client_min_version: "0.1.0".

See COMPATIBILITY.md for the full matrix, exception classes, exit codes, and capability taxonomy.

API surface — v0.2.0 status

Some methods are fully working against Houston's JSON API today; others are scaffolded against endpoints that currently return HTML and need JSON variants on the backend (planned for engine v2.x).

Verified working in v0.2.0:

Method	Endpoint	Purpose
healthz()	GET /healthz	Liveness probe ✅
version()	GET /version	Version metadata ✅

Scaffolded but require backend JSON support (will be reliable once engine v2 ships JSON variants):

Method	Endpoint	Purpose
list_securities()	GET /master/securities	Master list
add_security(...)	POST /master/securities	Register a new security
ingest_bars(...)	POST /history/ingest	Pull bars from yfinance
get_bars(symbol, ...)	GET /history/{symbol}	Read bars from local DB
backtest(strategy_path, ...)	POST /backtest	Submit backtest
list_schedules()	GET /schedules	Schedules (currently returns HTML)
add_schedule(...)	POST /schedules	Add/update
remove_schedule(name)	DELETE /schedules/{name}	Delete
run_schedule(name)	POST /schedules/{name}/run	Trigger NOW
list_jobs(limit=20)	GET /jobs	Recent jobs (currently returns HTML)
get_job(id)	GET /jobs/{id}	Single job
ibkr_status()	GET /ibkr/status	IB Gateway state
ibkr_positions()	GET /ibkr/positions	Current positions
list_deploys()	GET /api/deploy	Cloud deploys
deploy_status(id)	GET /api/deploy/{id}/status	Single deploy
list_logs(...)	GET /logs	Recent log rows

If you need a method that's currently broken, the in-stack auracle CLI inside the install (run from a JupyterLab terminal) is the complete tool for now.

Configuration

The client resolves the URL + API key from these sources, in order:

Variable	Effect
AURACLE_URL	Houston URL (e.g. https://your-auracle)
AURACLE_HOUSTON_URL	Legacy alias for AURACLE_URL
AURACLE_API_KEY	Per-user API key
HOUSTON_API_KEY	Legacy alias for AURACLE_API_KEY
AURACLE_INSECURE_TLS=1	Skip TLS verification (self-signed certs)

Or pass them explicitly to the AuracleClient(...) constructor.

License

Apache-2.0 — use freely in any project, commercial or not.

The Auracle platform itself (the server-side code) is proprietary commercial software. This client SDK is open-source on purpose: integrators should be able to read every line they're embedding into their own tools.