Evaluate Contract

Evaluate Contract

Abstract

The evaluate contract is the JSON dialect that lets AXIS, HOOX, CLI tools, and edge workers call any PYNE-compatible host interchangeably. Flask POST /run is the reference implementation; Python pyne-worker aims for the same HTTP fields. PyneTS speaks the in-process form (RuntimeResult).

This page freezes the semantic envelope — not transport auth headers.

Conceptual model

Rendering…

Invariant: given the same script + OHLCV + mode, hosts should agree on plot series and strategy events within known parity limits (see numerical validation and PyneTS parity). AXIS engines call Python hosts today, not PyneTS.

Interface surface

Request (single evaluate)

Bar

Response (success)

PlotMeta (Flask)

{
  "title": "C",
  "color": "#2196F3",
  "linewidth": 1,
  "index": 0,
  "kind": "plot"
}

kind is plot | hline | fill | bgcolor | plotshape | plotchar | plotarrow. Fill bands add plot1 / plot2 title refs; hline may add price. Extra style keys (style, linestyle, location, text, char, size) appear when the interpret collector has them.

StrategyEvent (minimum)

Hosts should preserve:

{
  "type": "string",
  "bar_index": 0,
  "script_id": "…",
  "run_id": "…"
}

Additional fields follow evaluator to_dict() / TS port parity — treat unknown keys as forward-compatible.

AlertEvent (minimum)

{
  "message": "string",
  "freq": "once_per_bar",
  "bar_index": 0,
  "time": 0,
  "source": "alert",
  "script_id": "…",
  "run_id": "…"
}

See Alerts for frequency rules and webhooks.

Response (failure)

Flask /run:

{
  "status": "error",
  "code": "EXECUTION_ERROR",
  "message": "Runtime Error at bar …",
  "error_kind": "runtime"
}

Optional error_type, error_bar, logs, profile, meta pass through when Runtime set them. error_kind is parse | compile | runtime | data | order | mode.

Workers may use equivalent { error: string } or HTTP 4xx/5xx with message body. Clients should accept:

1. Envelope status === "error" with message, or
2. Presence of top-level error string (raw Runtime.run shape).

Batch evaluate (Flask extension)

POST /run/batch:

Request: scripts: (string | {id, script})[] (max 8) + shared data + optional symbol / data_source / data_options / mode / profiler / libraries / timeout_seconds / webhook fields. Not on the batch schema: inputs.

Response:

{
  "status": "success" | "partial",
  "results": [ /* per-script success or error object with id */ ],
  "count": 0,
  "ok": 0,
  "data_source": "chart"
}

Workers may implement batch as N single evaluates; AXIS should not assume batch exists on every host.

Internals — reference mapping

Schema enforcement on Flask free tier: RUN_SCHEMA / RUN_BATCH_SCHEMA in backend/middleware/schemas.py (strict, reject extras). Webhook fields: webhook_url, forward_alerts, alert_last_bar, alert_batch. libraries and timeout_seconds are on both /run and /run/batch.

Tests: tests/test_backend.py (test_run_success, test_run_exports_alerts, webhook cases), tests/test_alert_forwarder.py.

Divergences to remember

Invariants and edge cases

1. Bar order is chronological ascending — hosts do not sort for you.
2. na / missing appear as JSON null in series arrays.
3. Duplicate plot titles get suffixes (_2, …) on Flask; clients should key on returned map keys, not assumed titles.
4. Idempotent script_id for identical source text across hosts.
5. run_id is not stable across retries — use for log correlation only.
6. Parity is best-effort on floating edges; pin fixtures when testing hosts against each other.

Worked example — host-agnostic client sketch

type EvaluateRequest = {
  script: string;
  data: Array<{
    time: number;
    open: number;
    high: number;
    low: number;
    close: number;
    volume?: number;
  }>;
  symbol?: string;
  mode?: "interpret" | "compile" | "auto";
  libraries?: Array<{
    namespace: string;
    name: string;
    version: number;
    source: string;
  }>;
};

type EvaluateSuccess = {
  plots: Array<number | null>;
  series: Record<string, Array<number | null>>;
  plot_meta: Record<string, Record<string, unknown>>;
  events: Array<Record<string, unknown>>;
  drawings: Array<Record<string, unknown>>;
  alerts: Array<Record<string, unknown>>;
  count: number;
  script_id: string;
  run_id: string;
  mode: string;
  auto_backend?: "compile" | "interpret";
  compile_fallback_reason?: string;
};

POST that body to Flask /run or the worker’s evaluate route; branch on status / error.

Failure modes

See also

• Run endpoint
• Runtime bridge
• pyne-worker
• pyne-agent-worker
• Pro API usage (end user)
• Events