clue-fastapi-sdk 0.0.1__py3-none-any.whl

clue_fastapi_sdk/__init__.py

@@ -0,0 +1,28 @@
+from clue_python_sdk_core import (
+	ClueCommand,
+	ClueIdentify,
+	ClueLogout,
+	ClueSetAccount,
+	ClueStateTransition,
+	ClueTrack,
+	ClueToolCall,
+)
+
+from .fastapi import (
+	ClueFastApiMiddleware,
+	clue_init_fastapi,
+	instrument_celery,
+)
+
+__all__ = [
+	"ClueFastApiMiddleware",
+	"ClueCommand",
+	"ClueIdentify",
+	"ClueLogout",
+	"ClueSetAccount",
+	"ClueStateTransition",
+	"ClueTrack",
+	"ClueToolCall",
+	"clue_init_fastapi",
+	"instrument_celery",
+]

clue_fastapi_sdk/fastapi.py

@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+import importlib
+import os
+import time
+from collections.abc import Awaitable, Callable, Sequence
+from types import SimpleNamespace
+from urllib.parse import parse_qs
+
+from clue_python_sdk_core import (
+	CluePythonBootstrapConfig,
+	CluePythonSettings,
+	JsonValue,
+	build_backend_error_event,
+	build_request_failed_event,
+	build_request_finished_event,
+	build_request_started_event,
+	configure_opentelemetry_environment,
+	create_client,
+	create_request_context,
+	default_traces_endpoint_from_ingest_endpoint,
+	enqueue_client_events,
+	initialize_opentelemetry,
+	instrument_celery_signals,
+	instrument_sqlalchemy_orm,
+	instrument_requests,
+	load_settings,
+	reset_current_state,
+	set_current_state,
+	to_path_template,
+)
+from clue_python_sdk_core.runtime import (
+	annotate_current_otel_span,
+	build_settings,
+	configure_settings,
+	emit_sdk_initialized,
+)
+
+ASGIApp = Callable[[dict[str, object], Callable[[], Awaitable[dict[str, object]]], Callable[[dict[str, object]], Awaitable[None]]], Awaitable[None]]
+
+
+class ClueFastApiMiddleware:
+	def __init__(
+		self,
+		app: ASGIApp,
+		*,
+		settings_loader: Callable[[], CluePythonSettings] = load_settings,
+		timer: Callable[[], float] = time.perf_counter,
+	) -> None:
+		self._app = app
+		self._settings_loader = settings_loader
+		self._timer = timer
+
+	def __call__(
+		self,
+		scope: dict[str, object],
+		receive: Callable[[], Awaitable[dict[str, object]]],
+		send: Callable[[dict[str, object]], Awaitable[None]],
+	) -> Awaitable[None]:
+		return self._dispatch(scope, receive, send)
+
+	async def _dispatch(
+		self,
+		scope: dict[str, object],
+		receive: Callable[[], Awaitable[dict[str, object]]],
+		send: Callable[[dict[str, object]], Awaitable[None]],
+	) -> None:
+		if scope.get("type") != "http":
+			await self._app(scope, receive, send)
+			return
+
+		settings = self._settings_loader()
+		if not settings.enabled:
+			await self._app(scope, receive, send)
+			return
+
+		client = create_client(settings)
+		if client is None:
+			await self._app(scope, receive, send)
+			return
+
+		request_messages, request_body = await _buffer_request_messages(receive)
+		request = _FastApiRequest(scope, request_body)
+		context = create_request_context(settings=settings, request=request)
+		annotate_current_otel_span(
+			{
+				"clue.request_id": context.get("request_id"),
+				"clue.request_span_id": context.get("request_span_id"),
+				"clue.interaction_id": context.get("interaction_id"),
+				"clue.anonymous_id": context.get("anonymous_id"),
+				"clue.user_id": context.get("user_id"),
+				"clue.account_id": context.get("account_id"),
+				"clue.session_id": context.get("session_id"),
+				"clue.tab_id": context.get("tab_id"),
+			},
+			expected_kind="SERVER",
+		)
+		handler_name = _resolve_handler_name(scope)
+		client.add_event(
+			build_request_started_event(
+				request=request,
+				context=context,
+				handler_name=handler_name,
+				allowed_value_paths=settings.allowed_value_paths,
+				denied_keys=settings.denied_keys,
+			)
+		)
+
+		started_at = self._timer()
+		response_capture = _ResponseCapture()
+		client_token, context_token = set_current_state(client=client, context=context)
+		replay_receive = _build_replay_receive(request_messages)
+
+		try:
+			await self._app(scope, replay_receive, response_capture.capture(send))
+		except Exception as exc:
+			client.add_event(
+				build_backend_error_event(
+					context=context,
+					handler_name=handler_name,
+					failure_type="unhandled_exception",
+					error_class=exc.__class__.__name__,
+					message=str(exc),
+					exception=exc,
+				)
+			)
+			client.add_event(
+				build_request_failed_event(
+					request=request,
+					context=context,
+					handler_name=handler_name,
+					response=_ErrorResponse(),
+					status_code=500,
+					duration_ms=int((self._timer() - started_at) * 1000),
+					allowed_value_paths=settings.allowed_value_paths,
+					denied_keys=settings.denied_keys,
+				)
+			)
+			enqueue_client_events(settings, client)
+			raise
+		finally:
+			reset_current_state(client_token, context_token)
+
+		client.add_event(
+			build_request_finished_event(
+				request=request,
+				response=response_capture.to_response(),
+				context=context,
+				handler_name=handler_name,
+				duration_ms=int((self._timer() - started_at) * 1000),
+				allowed_value_paths=settings.allowed_value_paths,
+				denied_keys=settings.denied_keys,
+			)
+		)
+		enqueue_client_events(settings, client)
+
+
+def clue_init_fastapi(
+	app: object,
+	*,
+	project_key: str,
+	environment: str,
+	api_key: str | None = None,
+	service_name: str = "python-service",
+	producer_id: str | None = None,
+	service_key: str | None = None,
+	instrument_outbound_requests: bool = True,
+	instrument_celery_if_available: bool = True,
+	instrument_orm_if_available: bool = False,
+	state_fields: Sequence[str] = (),
+) -> bool:
+	add_middleware = getattr(app, "add_middleware", None)
+	if not callable(add_middleware):
+		return False
+
+	settings = build_settings(
+		project_key=project_key,
+		environment=environment,
+		api_key=api_key,
+		service_name=service_name,
+		service_key=service_key,
+		producer_id=producer_id,
+		capture_outbound_requests=instrument_outbound_requests,
+		capture_celery=instrument_celery_if_available,
+		capture_orm=instrument_orm_if_available,
+		state_fields=state_fields,
+	)
+	configure_settings(settings)
+	emit_sdk_initialized(settings)
+	bootstrap_config = CluePythonBootstrapConfig(
+		service_name=service_name,
+		producer_id=settings.producer_id,
+		project_key=project_key,
+		environment=environment,
+		deployment_environment=environment,
+		service_type="api",
+		traces_endpoint=(
+			os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
+			or os.environ.get("CLUE_OTLP_TRACES_ENDPOINT")
+			or default_traces_endpoint_from_ingest_endpoint(settings.endpoint or "")
+		),
+		api_key=api_key,
+		service_version=(
+			os.environ.get("OTEL_SERVICE_VERSION")
+			or os.environ.get("CLUE_SERVICE_VERSION")
+		),
+		service_namespace=(
+			os.environ.get("OTEL_SERVICE_NAMESPACE")
+			or os.environ.get("CLUE_SERVICE_NAMESPACE")
+		),
+	)
+	configure_opentelemetry_environment(bootstrap_config)
+	initialize_opentelemetry(bootstrap_config)
+	add_middleware(ClueFastApiMiddleware)
+	updated = True
+
+	if instrument_outbound_requests and instrument_requests():
+		updated = True
+
+	if instrument_celery_if_available and instrument_celery():
+		updated = True
+
+	if instrument_orm_if_available and instrument_sqlalchemy_orm():
+		updated = True
+
+	return updated
+
+
+def instrument_celery() -> bool:
+	try:
+		from celery import signals
+	except ImportError:
+		try:
+			signals = importlib.import_module("celery.signals")
+		except ImportError:
+			return False
+
+	return instrument_celery_signals(
+		task_prerun=signals.task_prerun,
+		task_postrun=signals.task_postrun,
+		task_failure=signals.task_failure,
+		before_task_publish=getattr(signals, "before_task_publish", None),
+		after_task_publish=getattr(signals, "after_task_publish", None),
+		task_retry=getattr(signals, "task_retry", None),
+		task_revoked=getattr(signals, "task_revoked", None),
+	)
+
+
+class _FastApiRequest:
+	def __init__(self, scope: dict[str, object], body: bytes) -> None:
+		self.method = str(scope.get("method", "GET"))
+		self.path = str(scope.get("path", "/"))
+		self.body = body
+		self.scheme = str(scope.get("scheme", "http"))
+		self.headers = _decode_headers(scope.get("headers"))
+		self.GET = _decode_query(scope.get("query_string"))
+		self.COOKIES = _parse_cookies(self.headers.get("cookie"))
+		self.user = scope.get(
+			"user",
+			SimpleNamespace(is_authenticated=False),
+		)
+		self.resolver_match = SimpleNamespace(route=_resolve_path_template(scope, self.path))
+
+	def get_full_path(self) -> str:
+		if not self.GET:
+			return self.path
+		query_pairs: list[str] = []
+		for key, value in self.GET.items():
+			if isinstance(value, list):
+				for entry in value:
+					query_pairs.append(f"{key}={entry}")
+			else:
+				query_pairs.append(f"{key}={value}")
+		return f"{self.path}?{'&'.join(query_pairs)}"
+
+
+class _ResponseCapture:
+	def __init__(self) -> None:
+		self.status_code = 200
+		self.headers: dict[str, str] = {}
+		self.body_parts: list[bytes] = []
+
+	def capture(
+		self,
+		send: Callable[[dict[str, object]], Awaitable[None]],
+	) -> Callable[[dict[str, object]], Awaitable[None]]:
+		async def _send(message: dict[str, object]) -> None:
+			if message.get("type") == "http.response.start":
+				self.status_code = int(message.get("status", 200))
+				self.headers = _decode_headers(message.get("headers"))
+			elif message.get("type") == "http.response.body":
+				body = message.get("body", b"")
+				if isinstance(body, bytes):
+					self.body_parts.append(body)
+			await send(message)
+
+		return _send
+
+	def to_response(self) -> object:
+		return SimpleNamespace(
+			status_code=self.status_code,
+			body=b"".join(self.body_parts),
+			headers=self.headers,
+		)
+
+
+class _ErrorResponse:
+	status_code = 500
+	body = b""
+	headers: dict[str, JsonValue] = {}
+
+
+async def _buffer_request_messages(
+	receive: Callable[[], Awaitable[dict[str, object]]],
+) -> tuple[list[dict[str, object]], bytes]:
+	messages: list[dict[str, object]] = []
+	body_parts: list[bytes] = []
+	while True:
+		message = await receive()
+		messages.append(message)
+		if message.get("type") != "http.request":
+			break
+		body = message.get("body", b"")
+		if isinstance(body, bytes):
+			body_parts.append(body)
+		if not message.get("more_body", False):
+			break
+	return messages, b"".join(body_parts)
+
+
+def _build_replay_receive(
+	messages: list[dict[str, object]],
+) -> Callable[[], Awaitable[dict[str, object]]]:
+	queue = list(messages)
+
+	async def _receive() -> dict[str, object]:
+		if queue:
+			return queue.pop(0)
+		return {"type": "http.request", "body": b"", "more_body": False}
+
+	return _receive
+
+
+def _decode_headers(raw_headers: object) -> dict[str, str]:
+	if isinstance(raw_headers, dict):
+		return {str(key).lower(): str(value) for key, value in raw_headers.items()}
+	if not isinstance(raw_headers, list):
+		return {}
+	result: dict[str, str] = {}
+	for entry in raw_headers:
+		if not isinstance(entry, tuple) or len(entry) != 2:
+			continue
+		key, value = entry
+		key_text = key.decode("latin-1") if isinstance(key, bytes) else str(key)
+		value_text = value.decode("latin-1") if isinstance(value, bytes) else str(value)
+		result[key_text.lower()] = value_text
+	return result
+
+
+def _decode_query(raw_query: object) -> dict[str, JsonValue]:
+	if isinstance(raw_query, bytes):
+		parsed = parse_qs(raw_query.decode("utf-8"), keep_blank_values=True)
+		return {
+			key: values[0] if len(values) == 1 else values
+			for key, values in parsed.items()
+		}
+	return {}
+
+
+def _parse_cookies(raw_cookie: str | None) -> dict[str, str]:
+	if not raw_cookie:
+		return {}
+	result: dict[str, str] = {}
+	for entry in raw_cookie.split(";"):
+		key, _, value = entry.strip().partition("=")
+		if key:
+			result[key] = value
+	return result
+
+
+def _resolve_handler_name(scope: dict[str, object]) -> str | None:
+	route = scope.get("route")
+	route_name = getattr(route, "name", None)
+	if isinstance(route_name, str) and route_name.strip():
+		return route_name
+	endpoint = scope.get("endpoint")
+	name = getattr(endpoint, "__name__", None)
+	if isinstance(name, str) and name.strip():
+		return name
+	return None
+
+
+def _resolve_path_template(scope: dict[str, object], path: str) -> str:
+	route = scope.get("route")
+	path_format = getattr(route, "path_format", None)
+	if isinstance(path_format, str) and path_format.strip():
+		return path_format
+	return to_path_template(path)

clue_fastapi_sdk-0.0.1.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.1
+Name: clue-fastapi-sdk
+Version: 0.0.1
+Summary: Clue FastAPI SDK with built-in backend runtime
+Home-page: UNKNOWN
+License: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=3.9
+Requires-Dist: clue-python-sdk-core (==0.0.1)
+
+UNKNOWN
+

clue_fastapi_sdk-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+clue_fastapi_sdk/__init__.py,sha256=GnVawxmRWyQVeUn9J6xvi34qarHcxyz1fiYKct3z6gs,442
+clue_fastapi_sdk/fastapi.py,sha256=GePPWM2lge_BS1wi88z3lTBnxR2APfH9udr3Dsfq0JY,11432
+clue_fastapi_sdk-0.0.1.dist-info/METADATA,sha256=X9gG_E8JwcGAmsIP-Eom4JuXlYXykI7YbkELIpIdbW0,249
+clue_fastapi_sdk-0.0.1.dist-info/WHEEL,sha256=ewwEueio1C2XeHTvT17n8dZUJgOvyCWCt0WVNLClP9o,92
+clue_fastapi_sdk-0.0.1.dist-info/top_level.txt,sha256=ll7k_BH8VqU3IR0Xt00fWy5WYVezb9qSgIv--pWvMf8,17
+clue_fastapi_sdk-0.0.1.dist-info/RECORD,,

clue_fastapi_sdk-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.37.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clue_fastapi_sdk-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+clue_fastapi_sdk