clue-python-sdk-core 0.0.1__py3-none-any.whl

clue_python_sdk_core/runtime.py

@@ -0,0 +1,894 @@
+from __future__ import annotations
+
+import atexit
+import os
+import time
+import uuid
+from collections.abc import Mapping, Sequence
+from contextlib import ContextDecorator
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+
+from .adapters import (
+	JsonValue,
+	build_account_associated_event,
+	build_backend_context,
+	build_custom_event,
+	build_domain_command_event,
+	build_identity_identified_event,
+	build_identity_logged_out_event,
+	build_sdk_diagnostic_event,
+	build_state_transition_event,
+	build_subject_profile,
+	build_tool_call_event,
+)
+from .client import (
+	DEFAULT_FLUSH_INTERVAL_MS,
+	DEFAULT_FLUSH_THRESHOLD_BYTES,
+	DEFAULT_MAX_BUFFER_BYTES,
+	DEFAULT_MAX_BUFFER_EVENTS,
+	DEFAULT_MAX_PAYLOAD_BYTES,
+	CluePythonClient,
+)
+from .contracts import (
+	BACKEND_RUNTIME_LANGUAGE,
+	BACKEND_STATUS_FAILED,
+	BACKEND_STATUS_FINISHED,
+	BACKEND_STATUS_STARTED,
+	CUSTOM_EVENT_SDK_INITIALIZED,
+	SDK_COLLECTION_MODE_STANDARD,
+)
+from .event_size import DEFAULT_MAX_EVENT_BYTES
+from .otel_bridge import annotate_current_otel_span, merge_current_otel_span_context, resolve_current_otel_span_context
+from .privacy import DEFAULT_DENIED_KEYS
+
+_current_client: ContextVar[CluePythonClient | None] = ContextVar(
+	"clue_python_current_client",
+	default=None,
+)
+_current_context: ContextVar[Mapping[str, JsonValue] | None] = ContextVar(
+	"clue_python_current_context",
+	default=None,
+)
+_configured_settings: CluePythonSettings | None = None
+_shared_clients: dict[str, CluePythonClient] = {}
+DEFAULT_INGEST_ENDPOINT = "https://clue.example.com/api/v1/ingest/backend"
+LOCAL_SETUP_CHECK_ENDPOINT_ENV = "CLUE_LOCAL_SETUP_CHECK_ENDPOINT"
+DEFAULT_SHUTDOWN_FLUSH_TIMEOUT_SECONDS = 5.0
+
+
+@dataclass(frozen=True)
+class CluePythonSettings:
+	enabled: bool
+	endpoint: str | None
+	project_key: str | None
+	environment: str
+	api_key: str | None
+	service_name: str
+	allowed_value_paths: tuple[str, ...]
+	denied_keys: tuple[str, ...]
+	service_key: str = "python-service"
+	producer_id: str = "python-service"
+	sdk_collection_mode: str = SDK_COLLECTION_MODE_STANDARD
+	max_event_bytes: int | None = DEFAULT_MAX_EVENT_BYTES
+	max_buffer_events: int = DEFAULT_MAX_BUFFER_EVENTS
+	max_payload_bytes: int = DEFAULT_MAX_PAYLOAD_BYTES
+	flush_threshold_bytes: int = DEFAULT_FLUSH_THRESHOLD_BYTES
+	max_buffer_bytes: int = DEFAULT_MAX_BUFFER_BYTES
+	flush_interval_ms: int = DEFAULT_FLUSH_INTERVAL_MS
+	capture_outbound_requests: bool = True
+	capture_celery: bool = True
+	capture_orm: bool = False
+	state_fields: tuple[str, ...] = ()
+
+
+def create_trace_id() -> str:
+	return uuid.uuid4().hex
+
+
+def create_span_id() -> str:
+	return uuid.uuid4().hex[:16]
+
+
+def create_request_span_id() -> str:
+	return f"rsp_{uuid.uuid4()}"
+
+
+def create_interaction_id() -> str:
+	return f"int_{uuid.uuid4()}"
+
+
+def _require_non_empty(value: str, field_name: str) -> str:
+	normalized = value.strip()
+	if not normalized:
+		raise ValueError(f"{field_name} is required")
+	return normalized
+
+
+def _positive_int(value: object, fallback: int) -> int:
+	try:
+		parsed = int(str(value))
+	except (TypeError, ValueError):
+		return fallback
+	return parsed if parsed > 0 else fallback
+
+
+def build_settings(
+	*,
+	project_key: str,
+	environment: str,
+	api_key: str | None = None,
+	endpoint: str | None = None,
+	service_name: str = "python-service",
+	service_key: str | None = None,
+	producer_id: str | None = None,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+	max_event_bytes: int | None = DEFAULT_MAX_EVENT_BYTES,
+	max_buffer_events: int = DEFAULT_MAX_BUFFER_EVENTS,
+	max_payload_bytes: int = DEFAULT_MAX_PAYLOAD_BYTES,
+	flush_threshold_bytes: int = DEFAULT_FLUSH_THRESHOLD_BYTES,
+	max_buffer_bytes: int = DEFAULT_MAX_BUFFER_BYTES,
+		flush_interval_ms: int = DEFAULT_FLUSH_INTERVAL_MS,
+		capture_outbound_requests: bool = True,
+		capture_celery: bool = True,
+		capture_orm: bool = False,
+	state_fields: Sequence[str] = (),
+	sdk_collection_mode: str = SDK_COLLECTION_MODE_STANDARD,
+) -> CluePythonSettings:
+	resolved_endpoint = (
+		os.environ.get(LOCAL_SETUP_CHECK_ENDPOINT_ENV)
+		or endpoint
+		or os.environ.get("CLUE_INGEST_ENDPOINT")
+		or DEFAULT_INGEST_ENDPOINT
+	)
+	resolved_producer_id = (
+		producer_id
+		or os.environ.get("CLUE_PRODUCER_ID")
+		or service_name
+	)
+	resolved_service_key = (
+		service_key
+		or os.environ.get("CLUE_SERVICE_KEY")
+		or resolved_producer_id
+		or service_name
+	)
+	env_state_fields = os.environ.get("CLUE_STATE_FIELDS", "")
+	resolved_state_fields = tuple(
+		dict.fromkeys(
+			[
+				*(str(entry).strip() for entry in state_fields if str(entry).strip()),
+				*(
+					entry.strip()
+					for entry in env_state_fields.split(",")
+					if entry.strip()
+				),
+			]
+		)
+	)
+	resolved_max_buffer_events = _positive_int(
+		os.environ.get("CLUE_MAX_BUFFER_EVENTS"),
+		max_buffer_events,
+	)
+	resolved_flush_interval_ms = _positive_int(
+		os.environ.get("CLUE_FLUSH_INTERVAL_MS"),
+		flush_interval_ms,
+	)
+	return CluePythonSettings(
+		enabled=bool(project_key and environment.strip()),
+		endpoint=resolved_endpoint,
+		project_key=project_key or None,
+		environment=environment.strip(),
+		api_key=api_key,
+		service_name=service_name,
+		service_key=resolved_service_key,
+		producer_id=resolved_producer_id,
+		sdk_collection_mode=(
+			sdk_collection_mode
+			if sdk_collection_mode in {"standard", "diagnostic"}
+			else SDK_COLLECTION_MODE_STANDARD
+		),
+		allowed_value_paths=tuple(
+			str(entry) for entry in allowed_value_paths if str(entry).strip()
+		),
+		denied_keys=tuple(
+			dict.fromkeys(
+				[
+					*DEFAULT_DENIED_KEYS,
+					*(str(entry) for entry in denied_keys if str(entry).strip()),
+				]
+			)
+		),
+		max_event_bytes=max_event_bytes,
+		max_buffer_events=max(1, resolved_max_buffer_events),
+		max_payload_bytes=max(1024, max_payload_bytes),
+		flush_threshold_bytes=max(1024, min(flush_threshold_bytes, max_payload_bytes)),
+		max_buffer_bytes=max(1024, max_buffer_bytes),
+		flush_interval_ms=max(1, resolved_flush_interval_ms),
+		capture_outbound_requests=capture_outbound_requests,
+		capture_celery=capture_celery,
+		capture_orm=capture_orm,
+		state_fields=resolved_state_fields,
+	)
+
+
+def load_settings() -> CluePythonSettings:
+	if _configured_settings is not None:
+		return _configured_settings
+
+	return build_settings(
+		project_key="",
+		environment="",
+		service_name="python-service",
+		service_key="python-service",
+		producer_id="python-service",
+		capture_outbound_requests=False,
+		capture_celery=False,
+		capture_orm=False,
+	)
+
+
+def configure_settings(settings: CluePythonSettings | None) -> None:
+	global _configured_settings
+	_configured_settings = settings
+
+
+def clear_configured_settings() -> None:
+	configure_settings(None)
+	for client in tuple(_shared_clients.values()):
+		close = getattr(client, "close", None)
+		if callable(close):
+			close()
+	_shared_clients.clear()
+
+
+def create_client(settings: CluePythonSettings) -> CluePythonClient | None:
+	if not settings.enabled or not settings.endpoint or not settings.project_key:
+		return None
+	return CluePythonClient(
+		endpoint=settings.endpoint,
+		project_key=settings.project_key,
+		environment=settings.environment,
+		producer_id=settings.producer_id,
+		api_key=settings.api_key,
+		max_event_bytes=settings.max_event_bytes,
+		max_buffer_events=settings.max_buffer_events,
+		max_payload_bytes=settings.max_payload_bytes,
+		flush_threshold_bytes=settings.flush_threshold_bytes,
+		max_buffer_bytes=settings.max_buffer_bytes,
+		flush_interval_ms=settings.flush_interval_ms,
+	)
+
+
+def _shared_client_key(settings: CluePythonSettings) -> str:
+	return "|".join(
+		[
+			settings.endpoint or "",
+			settings.project_key or "",
+			settings.environment,
+			settings.producer_id,
+		]
+	)
+
+
+def get_shared_client(settings: CluePythonSettings) -> CluePythonClient | None:
+	if not settings.enabled or not settings.endpoint or not settings.project_key:
+		return None
+	key = _shared_client_key(settings)
+	client = _shared_clients.get(key)
+	if client is not None:
+		return client
+	client = CluePythonClient(
+		endpoint=settings.endpoint,
+		project_key=settings.project_key,
+		environment=settings.environment,
+		producer_id=settings.producer_id,
+		api_key=settings.api_key,
+		max_event_bytes=settings.max_event_bytes,
+		max_buffer_events=settings.max_buffer_events,
+		max_payload_bytes=settings.max_payload_bytes,
+		flush_threshold_bytes=settings.flush_threshold_bytes,
+		max_buffer_bytes=settings.max_buffer_bytes,
+		flush_interval_ms=settings.flush_interval_ms,
+		auto_flush=True,
+	)
+	_shared_clients[key] = client
+	return client
+
+
+def enqueue_event_to_shared(
+	settings: CluePythonSettings,
+	event: Mapping[str, JsonValue],
+) -> bool:
+	client = get_shared_client(settings)
+	if client is None:
+		return False
+	return client.add_event(event)
+
+
+def enqueue_client_events(
+	settings: CluePythonSettings,
+	client: CluePythonClient,
+) -> int:
+	shared_client = get_shared_client(settings)
+	if shared_client is None:
+		return 0
+	count = 0
+	for event in client.drain_events():
+		if shared_client.add_event(event):
+			count += 1
+	return count
+
+
+def flush_shared_clients(
+	timeout_seconds: float = DEFAULT_SHUTDOWN_FLUSH_TIMEOUT_SECONDS,
+) -> None:
+	for client in tuple(_shared_clients.values()):
+		try:
+			client.flush(timeout_seconds=timeout_seconds)
+		except Exception:
+			continue
+
+
+def emit_sdk_initialized(settings: CluePythonSettings) -> bool:
+	context = build_backend_context(
+		service_name=settings.service_name,
+		service_key=settings.service_key,
+		producer_id=settings.producer_id,
+		environment=settings.environment,
+		sdk_collection_mode=settings.sdk_collection_mode,
+	)
+	return enqueue_event_to_shared(
+		settings,
+		build_custom_event(
+			context=context,
+			event_name=CUSTOM_EVENT_SDK_INITIALIZED,
+			properties={
+				"backend_scope": "sdk",
+				"sdk_action": "initialize",
+			},
+			metrics={"count": 1},
+			denied_keys=settings.denied_keys,
+		),
+	)
+
+
+def create_request_context(
+	*,
+	settings: CluePythonSettings,
+	request: object | None = None,
+	service_name: str | None = None,
+	request_id: str | None = None,
+	request_span_id: str | None = None,
+	interaction_id: str | None = None,
+	trace_id: str | None = None,
+	session_id: str | None = None,
+) -> dict[str, JsonValue]:
+	anonymous_id: str | None = None
+	user_id: str | None = None
+	account_id: str | None = None
+	tab_id: str | None = None
+	parent_span_id: str | None = None
+	request_span_id_is_explicit = request_span_id is not None
+	if request is not None:
+		cookies = getattr(request, "COOKIES", None)
+		if isinstance(cookies, Mapping) and session_id is None:
+			raw_session_id = cookies.get("sessionid")
+			if raw_session_id is not None:
+				session_id = str(raw_session_id)
+
+		headers = getattr(request, "headers", None)
+		if hasattr(headers, "get"):
+			raw_anonymous_id = headers.get("x-clue-anonymous-id")
+			if raw_anonymous_id:
+				anonymous_id = str(raw_anonymous_id)
+			raw_user_id_header = headers.get("x-clue-user-id")
+			if raw_user_id_header:
+				user_id = str(raw_user_id_header)
+			raw_account_id = headers.get("x-clue-account-id")
+			if raw_account_id:
+				account_id = str(raw_account_id)
+			raw_session_id_header = headers.get("x-clue-session-id")
+			if raw_session_id_header:
+				session_id = str(raw_session_id_header)
+			raw_tab_id = headers.get("x-clue-tab-id")
+			if raw_tab_id:
+				tab_id = str(raw_tab_id)
+			if request_id is None:
+				raw_request_id = headers.get("x-request-id") or headers.get("x-clue-request-id")
+				if raw_request_id:
+					request_id = str(raw_request_id)
+				if request_span_id is None:
+					raw_request_span_id = headers.get("x-clue-request-span-id")
+					if raw_request_span_id:
+						request_span_id = str(raw_request_span_id)
+						request_span_id_is_explicit = True
+				if interaction_id is None:
+					raw_interaction_id = headers.get("x-clue-interaction-id")
+					if raw_interaction_id:
+						interaction_id = str(raw_interaction_id)
+			if trace_id is None:
+				raw_trace_id = headers.get("x-clue-trace-id")
+				if raw_trace_id:
+					trace_id = str(raw_trace_id)
+				if trace_id is None:
+					traceparent = headers.get("traceparent")
+					if isinstance(traceparent, str) and traceparent.count("-") >= 3:
+						parts = traceparent.split("-")
+						trace_id = parts[1]
+						if len(parts) >= 3 and parts[2]:
+							parent_span_id = parts[2]
+						else:
+							parent_span_id = None
+					else:
+						parent_span_id = None
+				else:
+					parent_span_id = None
+			else:
+				parent_span_id = None
+		else:
+			parent_span_id = None
+
+			if user_id is None:
+				user = getattr(request, "user", None)
+				if user is not None and getattr(user, "is_authenticated", False):
+					raw_user_id = getattr(user, "id", None)
+					if raw_user_id is not None:
+						user_id = str(raw_user_id)
+
+	if trace_id is None:
+		trace_id = create_trace_id()
+
+	context = {
+		"service_name": service_name or settings.service_name,
+		"service_key": settings.service_key,
+		"producer_id": settings.producer_id,
+		"runtime_language": BACKEND_RUNTIME_LANGUAGE,
+		"environment": settings.environment,
+		"sdk_collection_mode": settings.sdk_collection_mode,
+		"anonymous_id": anonymous_id,
+		"user_id": user_id,
+		"account_id": account_id,
+		"session_id": session_id,
+		"tab_id": tab_id,
+		"request_id": request_id or str(uuid.uuid4()),
+		"request_span_id": request_span_id if request_span_id_is_explicit else None,
+		"interaction_id": interaction_id,
+		"trace_id": trace_id,
+		"span_id": create_span_id(),
+		"parent_span_id": parent_span_id,
+	}
+	if request is not None:
+		context = merge_current_otel_span_context(
+			context,
+			expected_kind="SERVER",
+			use_otel_request_span_id=not request_span_id_is_explicit,
+		)
+	context["request_span_id"] = (
+		request_span_id
+		if request_span_id_is_explicit
+		else (
+			context.get("request_span_id")
+			if isinstance(context.get("request_span_id"), str)
+			and context.get("request_span_id")
+			else create_request_span_id()
+		)
+	)
+	return context
+
+
+def set_current_state(
+	*,
+	client: CluePythonClient,
+	context: Mapping[str, JsonValue],
+) -> tuple[Token[CluePythonClient | None], Token[Mapping[str, JsonValue] | None]]:
+	return _current_client.set(client), _current_context.set(context)
+
+
+def reset_current_state(
+	client_token: Token[CluePythonClient | None],
+	context_token: Token[Mapping[str, JsonValue] | None],
+) -> None:
+	_current_client.reset(client_token)
+	_current_context.reset(context_token)
+
+
+def get_current_client() -> CluePythonClient | None:
+	return _current_client.get()
+
+
+def get_current_context() -> Mapping[str, JsonValue] | None:
+	return _current_context.get()
+
+
+def _update_current_context(
+	fields: Mapping[str, JsonValue],
+) -> Mapping[str, JsonValue] | None:
+	context = get_current_context()
+	if context is None:
+		return None
+	updated = dict(context)
+	updated.update(fields)
+	_current_context.set(updated)
+	return updated
+
+
+def add_event(event: Mapping[str, JsonValue]) -> bool:
+	client = get_current_client()
+	if client is None:
+		return False
+	result = client.add_event(event)
+	return result is not False
+
+
+def ClueIdentify(user_id: str, traits: Mapping[str, object] | None = None) -> bool:
+	normalized_user_id = user_id.strip()
+	if not normalized_user_id:
+		raise ValueError("user_id is required")
+	settings = load_settings()
+	context = _update_current_context(
+		{
+			"user_id": normalized_user_id,
+			"user_profile": build_subject_profile(traits),
+		}
+	)
+	if context is None:
+		return False
+	return add_event(
+		build_identity_identified_event(
+			context=context,
+			user_id=normalized_user_id,
+			traits=traits,
+			denied_keys=settings.denied_keys,
+		)
+	)
+
+
+def ClueSetAccount(
+	account_id: str,
+	traits: Mapping[str, object] | None = None,
+) -> bool:
+	normalized_account_id = account_id.strip()
+	if not normalized_account_id:
+		raise ValueError("account_id is required")
+	workspace_id = None
+	if traits is not None:
+		raw_workspace_id = traits.get("workspace_id") or traits.get("workspaceId")
+		if isinstance(raw_workspace_id, str) and raw_workspace_id.strip():
+			workspace_id = raw_workspace_id.strip()
+	settings = load_settings()
+	context = _update_current_context(
+		{
+			"account_id": normalized_account_id,
+			"account_profile": build_subject_profile(traits),
+			"workspace_id": workspace_id,
+		}
+	)
+	if context is None:
+		return False
+	return add_event(
+		build_account_associated_event(
+			context=context,
+			account_id=normalized_account_id,
+			traits=traits,
+			denied_keys=settings.denied_keys,
+		)
+	)
+
+
+def ClueLogout(reason: str | None = None) -> bool:
+	settings = load_settings()
+	context = get_current_context()
+	if context is None:
+		return False
+	emitted = add_event(
+		build_identity_logged_out_event(
+			context=context,
+			reason=reason,
+			denied_keys=settings.denied_keys,
+		)
+	)
+	_update_current_context(
+		{
+			"user_id": None,
+			"account_id": None,
+			"user_profile": None,
+			"account_profile": None,
+			"workspace_id": None,
+		}
+	)
+	return emitted
+
+
+def ClueTrack(
+	event_name: str,
+	properties: Mapping[str, object] | None = None,
+	metrics: Mapping[str, object] | None = None,
+) -> bool:
+	settings = load_settings()
+	context = get_current_context()
+	if context is None:
+		return False
+	return add_event(
+		build_custom_event(
+			context=context,
+			event_name=event_name,
+			properties=properties,
+			metrics=metrics,
+			denied_keys=settings.denied_keys,
+		)
+	)
+
+
+class ClueCommand(ContextDecorator):
+	def __init__(self, command_key: str, command_label: str | None = None) -> None:
+		self.command_key = _require_non_empty(command_key, "command_key")
+		self.command_label = (
+			command_label.strip() if command_label and command_label.strip() else None
+		)
+		self._started_at: float | None = None
+		self._span_id: str | None = None
+		self._parent_span_id: str | None = None
+
+	def __enter__(self):
+		context = get_current_context()
+		if context is None:
+			return self
+		self._started_at = time.perf_counter()
+		otel_span = resolve_current_otel_span_context("INTERNAL")
+		self._span_id = (
+			otel_span["span_id"]
+			if otel_span is not None and otel_span.get("span_id")
+			else create_span_id()
+		)
+		self._parent_span_id = (
+			otel_span.get("parent_span_id") or None if otel_span is not None else None
+		)
+		annotate_current_otel_span(
+			{
+				"clue.flow.kind": "domain_command",
+				"clue.command.key": self.command_key,
+				"clue.command.label": self.command_label,
+			},
+			expected_kind="INTERNAL",
+		)
+		add_event(
+			build_domain_command_event(
+				context=context,
+				status=BACKEND_STATUS_STARTED,
+				command_key=self.command_key,
+				command_label=self.command_label,
+				span_id=self._span_id,
+				parent_span_id=self._parent_span_id,
+			)
+		)
+		return self
+
+	def __exit__(self, exc_type, _exc_value, _traceback) -> bool:
+		context = get_current_context()
+		if context is None:
+			return False
+		started_at = (
+			self._started_at if self._started_at is not None else time.perf_counter()
+		)
+		duration_ms = max(0, int((time.perf_counter() - started_at) * 1000))
+		add_event(
+			build_domain_command_event(
+				context=context,
+				status=BACKEND_STATUS_FAILED if exc_type is not None else BACKEND_STATUS_FINISHED,
+				command_key=self.command_key,
+				command_label=self.command_label,
+				duration_ms=duration_ms,
+				span_id=self._span_id,
+				parent_span_id=self._parent_span_id,
+			)
+		)
+		return False
+
+
+class ClueToolCall(ContextDecorator):
+	def __init__(
+		self,
+		tool_provider: str,
+		tool_name: str,
+		*,
+		tool_call_id: str | None = None,
+		tool_schema_hash: str | None = None,
+		validation_field_paths: Sequence[str] = (),
+	) -> None:
+		self.tool_provider = _require_non_empty(tool_provider, "tool_provider")
+		self.tool_name = _require_non_empty(tool_name, "tool_name")
+		self.tool_call_id = (
+			tool_call_id.strip() if tool_call_id and tool_call_id.strip() else None
+		)
+		self.tool_schema_hash = (
+			tool_schema_hash.strip()
+			if tool_schema_hash and tool_schema_hash.strip()
+			else None
+		)
+		self.validation_field_paths = tuple(
+			str(path).strip() for path in validation_field_paths if str(path).strip()
+		)
+		self._started_at: float | None = None
+		self._span_id: str | None = None
+		self._parent_span_id: str | None = None
+
+	def __enter__(self):
+		context = get_current_context()
+		if context is None:
+			return self
+		self._started_at = time.perf_counter()
+		otel_span = resolve_current_otel_span_context("INTERNAL")
+		self._span_id = (
+			otel_span["span_id"]
+			if otel_span is not None and otel_span.get("span_id")
+			else create_span_id()
+		)
+		self._parent_span_id = (
+			otel_span.get("parent_span_id") or None if otel_span is not None else None
+		)
+		annotate_current_otel_span(
+			{
+				"clue.flow.kind": "tool_call",
+				"clue.tool.provider": self.tool_provider,
+				"clue.tool.name": self.tool_name,
+				"clue.tool.schema_hash": self.tool_schema_hash,
+			},
+			expected_kind="INTERNAL",
+		)
+		add_event(
+			build_tool_call_event(
+				context=context,
+				status=BACKEND_STATUS_STARTED,
+				tool_provider=self.tool_provider,
+				tool_name=self.tool_name,
+				tool_call_id=self.tool_call_id,
+				tool_schema_hash=self.tool_schema_hash,
+				validation_field_paths=self.validation_field_paths,
+				span_id=self._span_id,
+				parent_span_id=self._parent_span_id,
+			)
+		)
+		return self
+
+	def __exit__(self, exc_type, _exc_value, _traceback) -> bool:
+		context = get_current_context()
+		if context is None:
+			return False
+		started_at = (
+			self._started_at if self._started_at is not None else time.perf_counter()
+		)
+		duration_ms = max(0, int((time.perf_counter() - started_at) * 1000))
+		add_event(
+			build_tool_call_event(
+				context=context,
+				status=BACKEND_STATUS_FAILED if exc_type is not None else BACKEND_STATUS_FINISHED,
+				tool_provider=self.tool_provider,
+				tool_name=self.tool_name,
+				tool_call_id=self.tool_call_id,
+				tool_schema_hash=self.tool_schema_hash,
+				validation_field_paths=self.validation_field_paths,
+				duration_ms=duration_ms,
+				failure_type="exception" if exc_type is not None else None,
+				span_id=self._span_id,
+				parent_span_id=self._parent_span_id,
+			)
+		)
+		return False
+
+
+class ClueStateTransition(ContextDecorator):
+	def __init__(
+		self,
+		transition_key: str,
+		*,
+		from_state: str,
+		to_state: str,
+		transition_axis: str | None = None,
+		entity_id: object | None = None,
+	) -> None:
+		self.transition_key = _require_non_empty(transition_key, "transition_key")
+		self.from_state = _require_non_empty(from_state, "from_state")
+		self.to_state = _require_non_empty(to_state, "to_state")
+		self.transition_axis = (
+			transition_axis.strip()
+			if transition_axis and transition_axis.strip()
+			else None
+		)
+		self.entity_id = entity_id
+		self._started_at: float | None = None
+		self._span_id: str | None = None
+		self._parent_span_id: str | None = None
+
+	def __enter__(self):
+		context = get_current_context()
+		if context is None:
+			return self
+		self._started_at = time.perf_counter()
+		otel_span = resolve_current_otel_span_context("INTERNAL")
+		self._span_id = (
+			otel_span["span_id"]
+			if otel_span is not None and otel_span.get("span_id")
+			else create_span_id()
+		)
+		self._parent_span_id = (
+			otel_span.get("parent_span_id") or None if otel_span is not None else None
+		)
+		annotate_current_otel_span(
+			{
+				"clue.flow.kind": "state_transition",
+				"clue.transition.key": self.transition_key,
+				"clue.transition.from_state": self.from_state,
+				"clue.transition.to_state": self.to_state,
+				"clue.transition.axis": self.transition_axis,
+			},
+			expected_kind="INTERNAL",
+		)
+		add_event(
+			build_state_transition_event(
+				context=context,
+				status=BACKEND_STATUS_STARTED,
+				transition_key=self.transition_key,
+				from_state=self.from_state,
+				to_state=self.to_state,
+				transition_axis=self.transition_axis,
+				entity_id=self.entity_id,
+				span_id=self._span_id,
+				parent_span_id=self._parent_span_id,
+			)
+		)
+		return self
+
+	def __exit__(self, exc_type, _exc_value, _traceback) -> bool:
+		context = get_current_context()
+		if context is None:
+			return False
+		started_at = (
+			self._started_at if self._started_at is not None else time.perf_counter()
+		)
+		duration_ms = max(0, int((time.perf_counter() - started_at) * 1000))
+		add_event(
+			build_state_transition_event(
+				context=context,
+				status=BACKEND_STATUS_FAILED if exc_type is not None else BACKEND_STATUS_FINISHED,
+				transition_key=self.transition_key,
+				from_state=self.from_state,
+				to_state=self.to_state,
+				transition_axis=self.transition_axis,
+				entity_id=self.entity_id,
+				duration_ms=duration_ms,
+				span_id=self._span_id,
+				parent_span_id=self._parent_span_id,
+			)
+		)
+		return False
+
+
+def flush_client(client: CluePythonClient) -> dict[str, JsonValue]:
+	try:
+		return client.flush()
+	except Exception:
+		return {}
+
+
+def build_internal_diagnostic_event(
+	settings: CluePythonSettings,
+) -> dict[str, JsonValue] | None:
+	client = get_current_client()
+	context = get_current_context()
+	if client is None or context is None:
+		return None
+	return build_sdk_diagnostic_event(
+		context=context,
+		metrics=client.internal_metrics(),
+		instrumentation_active={
+			"requests": settings.capture_outbound_requests,
+			"celery": settings.capture_celery,
+			"orm": settings.capture_orm,
+		},
+		last_flush_status="pending",
+		denied_keys=settings.denied_keys,
+	)
+
+
+atexit.register(flush_shared_clients)