witdem-sdk 0.1.0__tar.gz

witdem_sdk-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.duckdb
+/data/backups/
+.env
+.DS_Store
+!data/synthetic-ui-v2/
+!data/synthetic-ui-v2/**
+!data/synthetic-ui-v2/analytics.duckdb
+data/live/
+.claude/
+data/**/.DS_Store
+
+# Dashboard contributor build artifacts
+web/node_modules/
+web/*.tsbuildinfo
+web/vite.config.js
+web/vite.config.d.ts
+web/tailwind.config.js
+web/tailwind.config.d.ts
+
+# Locally generated live-matrix reports
+examples/product-factory/reports/

witdem_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: witdem-sdk
+Version: 0.1.0
+Summary: Public client SDK for emitting Witdem business-semantic records correlated to the caller's active OpenTelemetry execution.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: opentelemetry-api<2,>=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27
+Requires-Dist: opentelemetry-sdk<2,>=1.27
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: typing-extensions<5,>=4.12
+Provides-Extra: all
+Requires-Dist: anthropic<1,>=0.50; extra == 'all'
+Requires-Dist: haystack-ai<4,>=3.0; extra == 'all'
+Requires-Dist: langchain-core<2,>=0.3; extra == 'all'
+Requires-Dist: langgraph<2,>=0.2; extra == 'all'
+Requires-Dist: litellm<2,>=1.86; extra == 'all'
+Requires-Dist: openai-agents<0.21,>=0.0.10; extra == 'all'
+Requires-Dist: openai<4,>=1.68; extra == 'all'
+Requires-Dist: openinference-instrumentation-smolagents<1,>=0.1.20; extra == 'all'
+Requires-Dist: opentelemetry-haystack<2,>=1; extra == 'all'
+Requires-Dist: smolagents<2,>=1.18; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1,>=0.50; extra == 'anthropic'
+Provides-Extra: haystack
+Requires-Dist: haystack-ai<4,>=3.0; extra == 'haystack'
+Requires-Dist: opentelemetry-haystack<2,>=1; extra == 'haystack'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=0.3; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=0.2; extra == 'langgraph'
+Provides-Extra: litellm
+Requires-Dist: litellm<2,>=1.86; extra == 'litellm'
+Provides-Extra: openai
+Requires-Dist: openai-agents<0.21,>=0.0.10; extra == 'openai'
+Provides-Extra: openrouter
+Requires-Dist: openai<4,>=1.68; extra == 'openrouter'
+Provides-Extra: smolagents
+Requires-Dist: openinference-instrumentation-smolagents<1,>=0.1.20; extra == 'smolagents'
+Requires-Dist: smolagents<2,>=1.18; extra == 'smolagents'
+Description-Content-Type: text/markdown
+
+Witdem SDK provides optional application semantics and framework integrations for Witdem Analytics.

witdem_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling==1.32.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "witdem-sdk"
+version = "0.1.0"
+description = "Public client SDK for emitting Witdem business-semantic records correlated to the caller's active OpenTelemetry execution."
+readme = { text = "Witdem SDK provides optional application semantics and framework integrations for Witdem Analytics.", content-type = "text/markdown" }
+requires-python = ">=3.10,<3.14"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "opentelemetry-api>=1.27,<2",
+  "opentelemetry-exporter-otlp-proto-http>=1.27,<2",
+  "opentelemetry-sdk>=1.27,<2",
+  "httpx>=0.27,<1",
+  "pydantic>=2.10,<3",
+  "pyyaml>=6.0,<7",
+  "typing-extensions>=4.12,<5",
+]
+
+[project.scripts]
+witdem-sdk = "witdem_sdk.cli:main"
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.50,<1"]
+# openai-agents 0.21+ requires openai 3.x, while the supported LiteLLM
+# integration still requires openai <3. Keep the combined `all` extra solvable.
+openai = ["openai-agents>=0.0.10,<0.21"]
+langchain = ["langchain-core>=0.3,<2"]
+langgraph = ["langgraph>=0.2,<2"]
+haystack = ["haystack-ai>=3.0,<4", "opentelemetry-haystack>=1,<2"]
+litellm = ["litellm>=1.86,<2"]
+openrouter = ["openai>=1.68,<4"]
+smolagents = [
+  "smolagents>=1.18,<2",
+  "openinference-instrumentation-smolagents>=0.1.20,<1",
+]
+all = [
+  "anthropic>=0.50,<1",
+  "openai-agents>=0.0.10,<0.21",
+  "langchain-core>=0.3,<2",
+  "langgraph>=0.2,<2",
+  "haystack-ai>=3.0,<4",
+  "opentelemetry-haystack>=1,<2",
+  "litellm>=1.86,<2",
+  "openai>=1.68,<4",
+  "smolagents>=1.18,<2",
+  "openinference-instrumentation-smolagents>=0.1.20,<1",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3,<9",
+  "pytest-cov>=6,<7",
+  "ruff>=0.9,<1",
+  "mypy>=1.15,<2",
+  "types-PyYAML>=6.0,<7",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/witdem_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/witdem_sdk", "tests", "pyproject.toml"]
+
+[tool.uv]
+required-version = "==0.12.5"
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["witdem_sdk"]
+follow_imports_for_stubs = true
+
+[[tool.mypy.overrides]]
+module = ["numpy", "numpy.*"]
+follow_imports = "skip"

witdem_sdk-0.1.0/src/witdem_sdk/__init__.py

@@ -0,0 +1,189 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from witdem_sdk._contract import ContractResult, WitdemProjectConfig, load_project_config
+from witdem_sdk._correlation import resolve_correlation
+from witdem_sdk._errors import WitdemSDKError
+from witdem_sdk._payload import Kind as _Kind
+from witdem_sdk._payload import build_payload
+from witdem_sdk._protocol import SEMANTIC_RECORD_PROTOCOL_VERSION
+from witdem_sdk._telemetry import Operation, Witdem, configure
+from witdem_sdk._transport import DeliveryStatus, flush, submit_record
+
+__all__ = [
+    "WitdemSDKError",
+    "Witdem",
+    "Operation",
+    "configure",
+    "decision",
+    "event",
+    "evaluation",
+    "metric",
+    "outcome",
+    "flush",
+    "DeliveryStatus",
+    "SEMANTIC_RECORD_PROTOCOL_VERSION",
+    "ContractResult",
+    "WitdemProjectConfig",
+    "load_project_config",
+]
+
+try:
+    __version__ = version("witdem-sdk")
+except PackageNotFoundError:  # pragma: no cover - only an unpackaged source tree
+    __version__ = "0+unknown"
+
+
+def _emit(
+    kind: _Kind,
+    name: str,
+    value: Any,
+    attributes: dict[str, Any],
+    *,
+    execution_id: str | None,
+) -> None:
+    """Shared plumbing: resolve correlation, build the wire payload, send it."""
+
+    resolved_execution_id, trace_id, span_id = resolve_correlation(execution_id)
+    payload = build_payload(
+        kind=kind,
+        name=name,
+        value=value,
+        execution_id=resolved_execution_id,
+        trace_id=trace_id,
+        span_id=span_id,
+        attributes=attributes,
+    )
+    submit_record(payload)
+
+
+def event(
+    name: str,
+    payload: dict[str, Any] | None = None,
+    *,
+    attributes: Mapping[str, Any] | None = None,
+    execution_id: str | None = None,
+) -> 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.
+    """
+
+    _emit(
+        "event",
+        name,
+        None,
+        {**dict(payload or {}), **dict(attributes or {})},
+        execution_id=execution_id,
+    )
+
+
+def decision(
+    name: str,
+    value: Any,
+    *,
+    attributes: Mapping[str, Any] | None = None,
+    execution_id: str | None = None,
+) -> 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.
+    """
+
+    _emit("decision", name, value, dict(attributes or {}), execution_id=execution_id)
+
+
+def evaluation(
+    name: str,
+    *,
+    score: float | None = None,
+    label: str | None = None,
+    value: Any = None,
+    attributes: Mapping[str, Any] | None = None,
+    execution_id: str | None = None,
+) -> 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.
+    """
+
+    resolved_attributes = dict(attributes or {})
+    if score is not None:
+        resolved_attributes["score"] = score
+    if label is not None:
+        resolved_attributes["label"] = label
+    _emit("evaluation", name, value, resolved_attributes, execution_id=execution_id)
+
+
+def outcome(
+    name: str,
+    *,
+    status: str | None = None,
+    value: Any = None,
+    attributes: Mapping[str, Any] | None = None,
+    execution_id: str | None = None,
+) -> 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.
+    """
+
+    resolved_attributes = dict(attributes or {})
+    if status is not None:
+        resolved_attributes["status"] = status
+    _emit("outcome", name, value, resolved_attributes, execution_id=execution_id)
+
+
+def metric(
+    name: str,
+    value: Any,
+    *,
+    attributes: Mapping[str, Any] | None = None,
+    execution_id: str | None = None,
+) -> 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.
+    """
+
+    _emit("metric", name, value, dict(attributes or {}), execution_id=execution_id)

witdem_sdk-0.1.0/src/witdem_sdk/__main__.py

@@ -0,0 +1,3 @@
+from witdem_sdk.cli import main
+
+raise SystemExit(main())

witdem_sdk-0.1.0/src/witdem_sdk/_config.py

@@ -0,0 +1,38 @@
+"""Environment-based configuration for :mod:`witdem_sdk`."""
+
+from __future__ import annotations
+
+import os
+
+_ENDPOINT_ENV_VAR = "WITDEM_ENDPOINT"
+_DEFAULT_ENDPOINT = "http://localhost:4318"
+_endpoint_override: str | None = None
+
+
+def configure_records_endpoint(endpoint: str | None) -> str | None:
+    """Set the process-local endpoint override and return its previous value."""
+
+    global _endpoint_override
+    previous = _endpoint_override
+    _endpoint_override = endpoint.rstrip("/") if endpoint else None
+    return previous
+
+
+def records_endpoint() -> str:
+    """Base URL of the Witdem service.
+
+    Records are POSTed to ``f"{records_endpoint()}/sdk/v1/records"``. Read
+    fresh on every call (not cached at import time) so tests can repoint it
+    per-test via ``monkeypatch.setenv`` without reloading this module.
+    """
+
+    if _endpoint_override is not None:
+        return _endpoint_override
+    value = os.environ.get(_ENDPOINT_ENV_VAR)
+    if value:
+        return value.rstrip("/")
+    return _DEFAULT_ENDPOINT
+
+
+def api_key(explicit: str | None = None) -> str | None:
+    return explicit or os.getenv("WITDEM_API_KEY")