[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 and TypeScript pine-worker aim for the same fields even when transport (Worker fetch, queue, etc.) differs.

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

Conceptual model

Invariant: given the same script + OHLCV + mode, hosts should agree on plot series and strategy events within known parity limits (see numerical validation and pine-worker testing).

Interface surface

Request (single evaluate)

Bar

Response (success)

PlotMeta (Flask)

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

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.

Response (failure)

Flask /run:

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

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 + same optional fields as single run.

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).

Tests: tests/test_backend.py (test_run_success, batch cases).

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";
};

type EvaluateSuccess = {
  plots: Array<number | null>;
  series: Record<string, Array<number | null>>;
  events: Array<Record<string, unknown>>;
  drawings: Array<Record<string, unknown>>;
  count: number;
  script_id: string;
  run_id: string;
  mode: 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
• pine-worker
• Pro API usage (end user)
• Events