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.

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