Skip to content

Changelog

All notable changes to the Coalex SDKs are documented here. Both SDKs follow Semantic Versioning.

Starting from v1.0.0, both the Python and TypeScript SDKs are versioned together — but not lock-stepped: a release that only touches one language moves only that version. Each entry below names the SDK it applies to.

Current versions

Python coalex 1.32.0 · TypeScript @coalex-ai/sdk 1.21.0

For the API surface itself — field aliasing, the X-Deprecation header, and the deprecation window — see API Changelog & Versioning Policy. That page is about the platform's HTTP contract; this one is about the client libraries.

v1.32.0 — Python · v1.21.0 — TypeScript

A metric never returns a number it did not measure.

  • A metric with nothing to measure now says so instead of returning a value that looks measured.

v1.31.0 — Python · v1.20.0 — TypeScript

The approver sees the arguments, and an unknown verdict refuses.

  • A held call carries its arguments through to the approver.
  • A verdict the SDK does not recognise is refused rather than guessed at.

v1.30.1 — Python

  • A Console outage stops costing a fetch per verification.

v1.30.0 — Python · v1.19.0 — TypeScript

§6 de-biasing is one rule, not three that share a word list.

  • The three de-biasing paths were collapsed into the single rule they were always meant to be.

v1.29.0 — Python

  • A hold created by the Gateway now stops waiting.

v1.28.1 — Python · v1.17.1 — TypeScript

  • Maps the escalation status the platform writes most often, which the SDKs did not recognise.

v1.28.0 — Python

One governed call, one escalation.

  • A single governed call no longer produces more than one escalation.

v1.18.0 — TypeScript

An outage stops being invisible.

  • The TypeScript SDK reports an export outage instead of failing silently.

v1.27.1 — Python

  • Fixes audit rows that named the wrong agent, and a spool that lost them.

v1.27.0 — Python

An action that ran without governance leaves a trace.

Added

  • coalex.record_ungoverned() — record that an action proceeded because the platform could not be reached. Writes to a local spool and delivers when the connection returns, so it does not depend on the platform being up at the moment it is called. Never raises.
  • coalex.flush_ungoverned() — deliver what the spool is holding; also called automatically after any successful platform call, since success is the only honest signal that the platform is back.

Before this there was no way to record it at all: evaluate() is a single POST, so a failure left no escalation, no audit row, and nothing for a compliance report to show — an omission rather than a mislabelling.

v1.26.1 — Python · v1.17.0 — TypeScript

  • Diagnostics can be turned on and off by the customer.

v1.26.0 — Python

  • The guard no longer records successes for calls that never happened.

v1.16.0 — TypeScript

  • Removes de-biasing the TypeScript JSDoc promised and the SDK never did.

v1.25.0 — Python

The audit trail forms beside the thread as the agent works.

v1.24.0 — Python

  • An approver can read the document they are approving.

v1.23.0 — Python

The Question Composer stage.

v1.22.0 — Python

  • A held call reaches the approver with something to read.

v1.21.0 — Python

  • Republished so the context fix from 1.20.1 is installable, and adds the CI guard that stops an SDK source change merging without a version bump.

v1.20.1 — Python

  • Republished so the context fix is actually installable from the index.

v1.20.0 — Python

Per-agent trust score.

  • Seeded per-agent trust score, with policy thresholds.

v1.19.0 — Python

  • Escalations carry a card reason.

v1.18.0 — Python

  • The resolver is persisted on and exposed by escalations — the foundation for role-gated resolve.

v1.17.0 — Python

Added

  • resume_body_from_result() — turn an ElicitationResult into the body an agent's resume endpoint expects.

v1.16.0 — Python

Gateway v0 policy layer.

  • allow / escalate / block, with an audit row for each.

v1.15.1 — Python

  • Documents the intentional rejected → failed (Gateway) vs completed / decline (SDK) divergence.

v1.15.0 — Python · v1.15.0 — TypeScript

Added

  • resume_hook on evaluate() — an agent registers where its run can be resumed, so the platform can push a resolution instead of waiting to be polled. ResumeHook(kind="checkpoint", url=...).

v1.14.0 — Python · v1.14.0 — TypeScript

  • API versioning policy support: X-SDK-Version on every request, and a client-side warning when a response carries X-Deprecation. See API Changelog.
  • TypeScript: coalexContext() reaches parity on promptVersion / promptType.

v1.13.0 — Python · v1.13.0 — TypeScript

  • Version realignment with the monorepo release cadence. The two SDKs jump from 1.9.5 and 1.7.4 respectively to 1.13.0; no functional change.

v1.9.5 — Python

  • coalex_context() accepts prompt_version / prompt_type, for agents that cache a prompt at startup.

v1.9.4 — Python · v1.7.4 — TypeScript

  • Records coalex.prompt_version / coalex.prompt_type on spans after get_prompt().

v1.7.3 — TypeScript

Added

  • getPrompt() — fetch versioned prompts from the Prompt Vault, reaching parity with the Python SDK's get_prompt() from v1.8.0.

v1.9.3 — Python · v1.7.2 — TypeScript

  • Export-failure visibility, and @tool_span captures its output.

v1.9.2 — Python · v1.7.1 — TypeScript

  • agent_id propagation.

v1.9.1 — Python

  • expired joins VALID_DECISIONS: an approval card that times out is a distinct outcome from a rejection.

v1.9.0

Dogfood SDK for self-observability.

Added

  • Coalex SDK is now used internally by the transformer service for LLM judge self-observability
  • This validates the full SDK pipeline end-to-end within Coalex's own infrastructure

v1.8.0

Prompt Vault -- versioned prompt management.

Added (Python only)

  • get_prompt() -- fetch prompt templates from the Prompt Vault with environment-aware versioning
  • PromptVersion dataclass with id, agent_id, name, prompt_type, version, content, status, and metadata fields
  • Version resolution: "production" (default), "staging", "draft", "latest", or integer version number
  • API: GET /api/v2/prompts/{agent}/{name}

v1.7.0

Agent lifecycle states and lazy registration.

Added

  • declare_agent() / declareAgent() -- pre-register agents before traces arrive
  • AgentDeclaration dataclass/interface with agent_id, lifecycle, and created fields
  • Agent lifecycle states: "active", "staging", "deprecated"
  • display_name and metadata parameters for agent registration

v1.6.0

Structured reviewer identity on escalation resolve.

Changed

  • resolve() reviewer parameter now accepts a dict / object with name and email fields (in addition to plain string for backward compatibility)
  • ResolutionResult now includes reviewer_name / reviewerName and reviewer_email / reviewerEmail fields
  • The Coalex dashboard displays the reviewer's name alongside their email in the escalation audit trail

v1.5.0

Backward-compatible evaluate() API.

Changed

  • evaluate() now accepts both request_id (preferred) and trace_id (deprecated) parameters
  • trace_id is accepted for backward compatibility but logs a deprecation warning

v1.4.0

Context propagation fix for extension decorators.

Fixed

  • Fixed OTel context propagation for coalex.ext decorators across async boundaries (COA-191)
  • Added SpanContextBridge -- a thread-safe registry that tracks active parent span contexts per trace ID
  • Extension decorators now correctly find their parent span when running inside LangGraph async task executors
  • All spans are now tracked in the context bridge via CoalexAttributePropagator.on_start() and on_end()

v1.3.0

Precision-based health score from human reviews.

Added

  • evaluate() now accepts optional metadata parameter for attaching custom key-value data to evaluations
  • Health score computation based on approval precision from human reviews (COA-258)

v1.2.0

Production release.

Changed

  • Version bump for first production-grade release of both SDKs together

v1.1.0

ESM support and settings display.

Added

  • TypeScript: autoInstrumentAsync() -- async variant of autoInstrument() using dynamic import() instead of require(), enabling use in pure ESM projects (COA-230)
  • SDK endpoint and API key display in the Coalex dashboard settings page (COA-246)

v1.0.0

Breaking changes: evaluate() contract and span status.

Changed

  • evaluate(): Removed expected parameter. Expected values are now managed server-side. Use request_id instead of trace_id (COA-186)
  • Spans now set explicit OK or ERROR status instead of leaving UNSET (COA-207)

Fixed

  • Set output.value on RETRIEVER spans for correct OpenInference display (COA-185)

TypeScript SDK v0.1.0

Initial release of the TypeScript SDK (@coalex-ai/sdk).

Added

  • register() -- configure the OTLP exporter with endpoint, API key, and service name
  • coalexContext() -- callback-based context manager with agentId, requestId, and version metadata
  • coalexContextSync() -- synchronous variant of coalexContext()
  • autoInstrument() -- patch installed LLM frameworks (OpenAI, LangChain, Anthropic)
  • evaluate() -- submit output for risk-based evaluation
  • resolve() -- submit human review decisions for escalated outputs
  • Extension wrapper functions (@coalex-ai/sdk/ext):
    • toolSpan() -- TOOL spans
    • embeddingSpan() / EmbeddingSpan -- EMBEDDING spans
    • retrievalSpan() / RetrievalSpan -- RETRIEVER spans
    • rerankerSpan() / RerankerSpan -- RERANKER spans
    • guardrailSpan() -- GUARDRAIL spans
  • Document interface and encodeDocuments() utility
  • Convenience functions: instrumentOpenAI(), instrumentLangChain(), instrumentAnthropic()
  • SafeOTLPSpanExporter and FilteringSpanExporter wrappers (same behavior as Python SDK)
  • CoalexAttributePropagator span processor for coalex.* attribute propagation
  • Package published to npm as @coalex-ai/sdk

Python SDK v0.3.0

Extension decorators, full auto-instrumentation, and evaluation API.

Added

  • Extension decorators for manual span creation:
    • @retrieval_span -- create RETRIEVER spans with Document dataclass for structured tracing
    • @embedding_span -- create EMBEDDING spans
    • @reranker_span -- create RERANKER spans
    • @tool_span -- create TOOL spans
    • @guardrail_span -- create GUARDRAIL spans
  • coalex.evaluate() -- submit agent outputs for risk assessment, returns auto_approved or escalated
  • coalex.resolve() -- submit human review decisions for escalated outputs with quality metrics
  • filter_non_ai_spans option in register() -- when enabled, only exports AI/LLM spans (filters out HTTP, DNS, and other non-AI spans)
  • 14 framework auto-instrumentation via OpenInference:
    • LLM Frameworks: OpenAI, LlamaIndex, LangChain
    • LLM Providers: Vertex AI, AWS Bedrock, Anthropic, MistralAI, Groq, liteLLM
    • Tools: DSPy, CrewAI, Haystack, Instructor, Guardrails
  • include_libraries / exclude_libraries parameters for selective auto-instrumentation
  • Convenience functions: instrument_openai(), instrument_langchain(), instrument_llamaindex(), instrument_vertexai(), instrument_bedrock(), instrument_anthropic()
  • suppress_export_errors option in register() for graceful degradation when the collector is unavailable
  • SafeOTLPSpanExporter wrapper that catches and logs export errors instead of crashing
  • FilteringSpanExporter that drops non-AI spans based on OpenInference span kind
  • Document dataclass (coalex.ext.retrieval.Document) for structured retrieval tracing

Changed

  • auto_instrument() now returns a dict[str, str] mapping each library to its status (success, not_installed, already_instrumented, error, excluded)

Python SDK v0.2.0

Context management and auto-instrumentation foundation.

Added

  • coalex.coalex_context() -- context manager that sets agent_id, request_id, and optional version on all spans within the block
  • coalex.auto_instrument() -- automatically patches installed LLM frameworks using OpenInference instrumentors
  • CoalexAttributePropagator span processor that injects context attributes into all child spans
  • CoalexConfig dataclass for SDK configuration

Changed

  • register() now configures BatchSpanProcessor with CoalexAttributePropagator for context propagation
  • OTLP exporter sends to {endpoint}/v1/traces (proxy path) instead of directly to collector

Python SDK v0.1.0

Initial release.

Added

  • coalex.register() -- configure the OTLP exporter with endpoint, API key, and service name
  • Basic OTLP/HTTP span export to Coalex proxy
  • Authorization: Bearer <api_key> header on all OTLP requests
  • service.name resource attribute configuration
  • Package published to PyPI as coalex