Python SDK

The public witdem_sdk package instruments application execution and reports business-semantic records. Private modules beginning with _ are intentionally excluded from this reference.

Install the base SDK or choose a framework extra:

python -m pip install witdem-sdk
python -m pip install "witdem-sdk[haystack]"

See Getting started for the end-to-end setup and YAML contracts for product-goal definitions.

witdem_sdk

witdem_sdk -- the public Witdem client SDK.

configure(...) provides one setup for OpenTelemetry traces and Witdem's business-semantic records. WITDEM_ENDPOINT is the common base URL for the trace and SDK ingest routes and defaults to http://localhost:4318.

The five typed semantic functions (events, decisions, evaluations, outcomes, metrics) remain available independently for applications that already own their OpenTelemetry setup.

Correlation is automatic: each call reads the active OTel span (trace_id/span_id) and "witdem.execution_id" baggage (execution_id) from the current OpenTelemetry context -- callers never copy ids by hand. If no execution id can be resolved (no baggage and no explicit execution_id= keyword argument), :class:WitdemSDKError is raised instead of sending an uncorrelated record.

Sending is fire-and-forget on a small bounded background thread pool: a network error, or Witdem being unreachable, is logged and dropped (after one quick retry) and never raised into caller code -- the one hard reliability requirement for this package.

The unified client exposes execution, model, tool, and generic operation contexts. It records standard GenAI attributes and flushes traces and semantic records at shutdown; provider pricing remains a server-side concern.

See docs/sdk.md §5 in the Witdem AI repository for the wire contract this package implements.

_Kind = Literal['event', 'decision', 'evaluation', 'outcome', 'metric'] module-attribute

SEMANTIC_RECORD_PROTOCOL_VERSION = '1.0' module-attribute

__all__ = ['WitdemSDKError', 'Witdem', 'Operation', 'configure', 'decision', 'event', 'evaluation', 'metric', 'outcome', 'flush', 'DeliveryStatus', 'SEMANTIC_RECORD_PROTOCOL_VERSION', 'ContractResult', 'WitdemProjectConfig', 'load_project_config'] module-attribute

__version__ = version('witdem-sdk') module-attribute

ContractResult dataclass

WitdemProjectConfig

Bases: BaseModel

WitdemSDKError

Bases: Exception

Raised when a call cannot be correlated to an execution.

This is raised instead of silently sending an uncorrelated (and therefore useless) record whenever there is no active OpenTelemetry span carrying "witdem.execution_id" baggage and the caller did not pass an explicit execution_id= keyword argument. It is never raised for transport/network failures -- those are logged and dropped (see :mod:witdem_sdk._transport), never surfaced to caller code.

Operation dataclass

A model/tool operation whose observed response facts can be recorded.

measure(name, value, *, unit, aggregation='sum', scope='operation', provenance='application_reported')

Record one typed, vendor-neutral operation measurement.

Witdem

One configured client for both traces and business-semantic records.

execution(name=None, *, execution_id=None, workflow=None, attributes=None)

Create one correlated execution for traces and SDK records.

operation(name=None, *, kind='component', type=None, family=None, operation_type=None, subtype=None, interface='unknown', role='application', input_modalities=(), output_modalities=(), provider=None, provider_id=None, model=None, model_id=None, implementation=None, implementation_id=None, framework=None, framework_id=None, execution_source=None, gateway=None, vendor=None, attributes=None)

Create a canonical operation context, or decorate a callable.

type/provider/model remain compatibility aliases for the explicit operation_type/provider_id/model_id contract.

evaluation_campaign(campaign_id, *, suite_id, dataset_id, dataset_version, candidate_version, baseline_version=None)

Attach framework-neutral offline-campaign identity to evaluations.

evaluation_case(case_id)

Attach a dataset-case identity inside an evaluation campaign.

report(*, result, requirements, contract=None, result_valid=True, decision=None, expected_decision=None, decision_correct=None, evaluations=None, metrics=None, dimensions=None, evidence_sufficient=True, required_path_observed=True, threshold=None, threshold_margin=None, attributes=None, execution_id=None)

Report explicit business meaning for a metadata-only contract.

The YAML supplies names and descriptions. This call supplies only the values known by the application; it never evaluates paths or rules. Framework integrations continue to report runtime telemetry automatically.

complete(result, *, contract=None, attributes=None, execution_id=None)

Reject the removed v1 expression-contract completion path.

DeliveryStatus dataclass

load_project_config(path=None, *, required=False)

resolve_correlation(explicit_execution_id)

Resolve (execution_id, trace_id, span_id) for the current call.

trace_id/span_id are read from trace.get_current_span() whenever it carries a valid span context, and are None otherwise -- that is never an error on its own, since they are correlation hints, not required fields (docs/architecture.md marks them optional).

execution_id resolves in this order:

1. explicit_execution_id (the caller's execution_id= keyword argument), if given -- an explicit argument always wins, so callers can deliberately attribute a call to a different execution than whatever the ambient context suggests.
2. OpenTelemetry baggage under :data:EXECUTION_ID_BAGGAGE_KEY, read from the current context -- the automatic path this package exists for.

If neither yields a non-empty string, :class:WitdemSDKError is raised rather than sending an uncorrelated record. Per docs/architecture.md, this is "no active span AND no explicit execution_id" in the common case, but the same error also covers the (rarer) case of an active span whose context simply never had witdem.execution_id baggage set on it.

build_payload(*, kind, name, value, execution_id, trace_id, span_id, attributes=None)

Build the exact wire dict POSTed to {endpoint}/sdk/v1/records.

event_id is generated here (client-side), per docs/architecture.md, as a fresh uuid4().hex -- it is the idempotency key the server dedupes on, so each call to a public witdem_sdk function produces exactly one new event_id, even if the resulting send is later retried by the transport layer (the retry resends the same built payload, not a new one).

configure(service_name=None, *, runtime=None, endpoint=None, telemetry_mode=None, tracer_provider=None, resource_attributes=None, api_key=None, config_path=None)

Configure Witdem from explicit values and optional project YAML.

flush(timeout=None)

submit_record(payload)

_emit(kind, name, value, attributes, *, execution_id)

Shared plumbing: resolve correlation, build the wire payload, send it.

event(name, payload=None, *, attributes=None, execution_id=None)

Record a domain event that happened during the active execution.

payload is an arbitrary JSON-serializable dict describing what happened; it is sent as the wire record's attributes. Raises :class:WitdemSDKError if execution_id cannot be resolved (see module docs). Never raises when Witdem is unavailable on the network.

decision(name, value, *, attributes=None, execution_id=None)

Record a business decision (e.g. a chosen route/branch) and its value.

Raises :class:WitdemSDKError if execution_id cannot be resolved (see module docs). Never raises when Witdem is unavailable on the network.

evaluation(name, *, score=None, label=None, value=None, attributes=None, execution_id=None)

Record a structured assessment: a score, a label, or both.

Raises :class:WitdemSDKError if execution_id cannot be resolved (see module docs). Never raises when Witdem is unavailable on the network.

outcome(name, *, status=None, value=None, attributes=None, execution_id=None)

Record an externally meaningful result of the active execution.

Raises :class:WitdemSDKError if execution_id cannot be resolved (see module docs). Never raises when Witdem is unavailable on the network.

metric(name, value, *, attributes=None, execution_id=None)

Record a numeric (or otherwise quantitative) measurement.

Raises :class:WitdemSDKError if execution_id cannot be resolved (see module docs). Never raises when Witdem is unavailable on the network.