Skip to content
Trace
Resources

Changelog

Released versions of the Trace Python SDK and gateway, newest first.

trace-edu-sdk follows semantic versioning. The gateway is versioned separately in its path (/api/sdk/v1); a breaking change to the wire format would be /v2, and /v1 would keep working.

Documentation URLs and heading anchors under /resources/docs/sdk/ are a stability contract. Curriculum lessons link to them directly, so a published slug or anchor does not change. New pages may be added.

Unreleased#

  • SDK streaming relays provider chunks as they arrive and validates provider request and response payloads before they cross the gateway boundary.

0.1.0 — 2026-08-07#

First release.

SDK — mirrors the OpenAI library, improves only additively

  • Trace(api_key=None, base_url=None, model=None). The key resolves from the argument, then TRACE_API_KEY, then ~/.trace/credentials.json.
  • client.chat.completions.create(messages=..., model=None, tools=..., tool_choice=..., temperature=..., top_p=..., max_tokens=..., stream=..., seed=..., stop=...) → an OpenAI-shaped completion: choices, message, tool_calls, usage. Unsupported keyword arguments return a clear 400.
  • client.embeddings.create(input=..., model=None) → an OpenAI-shaped embedding response.
  • client.models.list() and client.models.retrieve(id), with the published credit rate on every model.
  • stream=True yields OpenAI-shaped ChatCompletionChunk objects; the final chunk has no choices and carries usage.
  • Trace-only namespace: client.credits.balance() and client.credits.usage(limit=...).
  • The additive layer, none of it replacing the mirror:
    • model= optional everywhere — the client default, then the roster default, which GET /models publishes.
    • completion.text (choices[0].message.content, "" on a tool-only turn) and completion.credits_spent; chunk.text and chunk.credits_spent on stream frames; usage.credits_spent added to OpenAI's usage object.
    • tools= accepts plain Python functions — type hints and docstring become the schema — plus an optional @trace_sdk.tool decorator for overriding the name or description, alongside raw OpenAI tool dicts.
    • tool_call.name and tool_call.arguments (parsed) beside OpenAI's tool_call.function.name and .arguments (the JSON string); tool_call.result(value) builds the answering message.
    • completion.run_tools(messages, confirm=...) requires approval before each local function and appends approved results to the history.
  • Typed errors: AuthenticationError, InsufficientCreditsError, ModelNotFoundError, RateLimitError, BadRequestError, PermissionDeniedError, ServiceUnavailableError, APIConnectionError, APITimeoutError, all under TraceError. Automatic retry of 429, 5xx, and connection failures.
  • CLI: trace login, trace logout, trace whoami, trace credits, trace models.
  • One dependency: httpx. Python 3.10 and newer.

Gateway (/api/sdk/v1)

  • POST /chat/completions (with SSE streaming and tool passthrough), POST /embeddings, GET /models, GET /credits, GET /credits/usage.
  • OpenAI-shaped requests and responses for the documented fields, including direct use from the official openai package as described in Authentication.
  • Child protection on every request: the approved child-safe roster only, server-side sanitize_prompt redaction over the same identifier list an agent-builder run uses, a 4000-token per-request cap, a 256 KB body cap, 30 requests per minute per key, and prepaid credit reservations. See Authentication.
  • model is optional on chat and embeddings requests; omitting it uses the roster default, which GET /models publishes as default_chat_model and default_embedding_model.
  • Device-code login: POST /api/sdk/device and POST /api/sdk/device/poll, approved in the browser at /account/link.
  • API keys stored as SHA-256 digests only, revocable at /account/developer.
  • Credit accounts and an append-only ledger, with one provider-cost settlement for every reservation.
  • One embedding model added to the approved catalog: openai/text-embedding-3-small.

Known limitations

  • Streamed tool calls arrive as fragments and the SDK does not reassemble them. Leave stream out when you need whole tool calls.
  • The Trace agent builder keeps its own per-run cost caps and does not draw on credit accounts. Unifying the two is planned.
  • Free accounts receive 2,000 credits ($2) each month, and Self-learner subscribers receive 5,000 credits ($5). Teachers and administrators can grant additional credits.
  • The per-key rate limit is held in the API process, so it is per process rather than per cluster.
  • No async client. Trace is synchronous.