guardloop 0.2.0__py3-none-any.whl

guardloop/models.py

@@ -0,0 +1,94 @@
+"""Pydantic models for runtime configuration and results."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
+DecimalInput = Decimal | str | int | float
+
+
+class BudgetConfig(BaseModel):
+    """Hard resource limits for a single agent run."""
+
+    model_config = ConfigDict(frozen=True)
+
+    cost_limit_usd: DecimalInput | None = Field(default=None)
+    token_limit: int | None = Field(default=None)
+    time_limit_seconds: float | None = Field(default=None)
+    tool_call_limit: int | None = Field(default=None)
+
+    @field_validator("cost_limit_usd", mode="before")
+    @classmethod
+    def _parse_decimal(cls, value: object) -> object:
+        if value is None or isinstance(value, Decimal):
+            return value
+        return Decimal(str(value))
+
+    @field_validator("cost_limit_usd")
+    @classmethod
+    def _validate_cost_limit(cls, value: DecimalInput | None) -> DecimalInput | None:
+        decimal_value = Decimal(str(value)) if value is not None else None
+        if decimal_value is not None and decimal_value < 0:
+            raise ValueError("cost_limit_usd must be non-negative")
+        return value
+
+    @property
+    def cost_limit(self) -> Decimal | None:
+        if self.cost_limit_usd is None:
+            return None
+        if isinstance(self.cost_limit_usd, Decimal):
+            return self.cost_limit_usd
+        return Decimal(str(self.cost_limit_usd))
+
+    @field_validator("token_limit", "tool_call_limit")
+    @classmethod
+    def _validate_optional_non_negative_int(cls, value: int | None) -> int | None:
+        if value is not None and value < 0:
+            raise ValueError("limits must be non-negative")
+        return value
+
+    @field_validator("time_limit_seconds")
+    @classmethod
+    def _validate_time_limit(cls, value: float | None) -> float | None:
+        if value is not None and value <= 0:
+            raise ValueError("time_limit_seconds must be greater than zero")
+        return value
+
+
+class TelemetryConfig(BaseModel):
+    """OpenTelemetry behavior for runtime spans."""
+
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = True
+    service_name: str = "guardloop"
+    otlp_endpoint: str | None = None
+    console_exporter: bool = False
+
+
+class RunResult(BaseModel):
+    """Structured result returned from every runtime execution."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    output: str | None = None
+    success: bool
+    cost_usd: Decimal = Decimal("0")
+    estimated_cost_usd: Decimal = Decimal("0")
+    tokens_used: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    duration_seconds: float = 0.0
+    tool_calls: int = 0
+    trace_id: str | None = None
+    terminated_reason: str | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_serializer("cost_usd", "estimated_cost_usd")
+    def _serialize_decimal(self, value: Decimal) -> str:
+        return str(value)

guardloop/pricing.py

@@ -0,0 +1,116 @@
+"""Provider/model pricing catalog.
+
+Prices are USD per one million tokens and are intentionally overrideable because
+provider pricing changes over time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from guardloop.exceptions import ModelPricingMissing
+
+MILLION = Decimal("1000000")
+
+
+class ModelPricing(BaseModel):
+    """Token pricing for one provider/model pair."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider: str
+    model: str
+    input_cost_per_million_tokens: Decimal
+    output_cost_per_million_tokens: Decimal
+
+    @field_validator(
+        "input_cost_per_million_tokens",
+        "output_cost_per_million_tokens",
+        mode="before",
+    )
+    @classmethod
+    def _parse_decimal(cls, value: object) -> object:
+        if isinstance(value, Decimal):
+            return value
+        return Decimal(str(value))
+
+    @field_validator("provider", "model")
+    @classmethod
+    def _normalize(cls, value: str) -> str:
+        return value.strip().lower()
+
+    def estimate_cost(self, *, input_tokens: int, output_tokens: int) -> Decimal:
+        input_cost = Decimal(input_tokens) * self.input_cost_per_million_tokens / MILLION
+        output_cost = Decimal(output_tokens) * self.output_cost_per_million_tokens / MILLION
+        return input_cost + output_cost
+
+
+def _price(provider: str, model: str, input_price: str, output_price: str) -> ModelPricing:
+    return ModelPricing(
+        provider=provider,
+        model=model,
+        input_cost_per_million_tokens=Decimal(input_price),
+        output_cost_per_million_tokens=Decimal(output_price),
+    )
+
+
+DEFAULT_MODEL_PRICES: tuple[ModelPricing, ...] = (
+    # OpenAI API pricing checked May 3, 2026.
+    _price("openai", "gpt-5.5", "5.00", "30.00"),
+    _price("openai", "gpt-5.4", "2.50", "15.00"),
+    _price("openai", "gpt-5.4-mini", "0.75", "4.50"),
+    _price("openai", "gpt-5.2", "1.75", "14.00"),
+    _price("openai", "gpt-5.2-2025-12-11", "1.75", "14.00"),
+    _price("openai", "gpt-5.2-chat-latest", "1.75", "14.00"),
+    _price("openai", "gpt-5.2-codex", "1.75", "14.00"),
+    _price("openai", "gpt-5.2-pro", "21.00", "168.00"),
+    _price("openai", "gpt-5.1", "1.25", "10.00"),
+    _price("openai", "gpt-5", "1.25", "10.00"),
+    _price("openai", "gpt-5-mini", "0.25", "2.00"),
+    _price("openai", "gpt-5-nano", "0.05", "0.40"),
+    _price("openai", "gpt-4.1", "2.00", "8.00"),
+    _price("openai", "gpt-4.1-mini", "0.40", "1.60"),
+    _price("openai", "gpt-4.1-nano", "0.10", "0.40"),
+    _price("openai", "gpt-4o", "2.50", "10.00"),
+    _price("openai", "gpt-4o-mini", "0.15", "0.60"),
+    # Anthropic Claude pricing checked May 3, 2026.
+    _price("anthropic", "claude-opus-4-1-20250805", "15.00", "75.00"),
+    _price("anthropic", "claude-opus-4-1", "15.00", "75.00"),
+    _price("anthropic", "claude-opus-4-20250514", "15.00", "75.00"),
+    _price("anthropic", "claude-opus-4-0", "15.00", "75.00"),
+    _price("anthropic", "claude-sonnet-4-20250514", "3.00", "15.00"),
+    _price("anthropic", "claude-sonnet-4-0", "3.00", "15.00"),
+    _price("anthropic", "claude-3-7-sonnet-20250219", "3.00", "15.00"),
+    _price("anthropic", "claude-3-7-sonnet-latest", "3.00", "15.00"),
+    _price("anthropic", "claude-3-5-haiku-20241022", "0.80", "4.00"),
+    _price("anthropic", "claude-3-5-haiku-latest", "0.80", "4.00"),
+    _price("anthropic", "claude-3-haiku-20240307", "0.25", "1.25"),
+)
+
+
+class PricingCatalog:
+    """Lookup table for model pricing with user-provided overrides."""
+
+    def __init__(
+        self,
+        prices: Iterable[ModelPricing] | None = None,
+        *,
+        include_defaults: bool = True,
+    ) -> None:
+        entries = list(DEFAULT_MODEL_PRICES if include_defaults else ())
+        if prices is not None:
+            entries.extend(prices)
+        self._prices = {(entry.provider, entry.model): entry for entry in entries}
+
+    def get(self, provider: str, model: str) -> ModelPricing:
+        key = (provider.strip().lower(), model.strip().lower())
+        if key not in self._prices:
+            raise ModelPricingMissing(
+                f"No pricing is configured for provider={provider!r}, model={model!r}. "
+                "Pass a custom ModelPricing entry to GuardLoop(pricing=[...]).",
+                details={"provider": provider, "model": model},
+            )
+        return self._prices[key]

guardloop/providers/__init__.py

@@ -0,0 +1,6 @@
+"""Provider-specific client wrappers."""
+
+from guardloop.providers.anthropic import WrappedAnthropicClient
+from guardloop.providers.openai import WrappedOpenAIClient
+
+__all__ = ["WrappedAnthropicClient", "WrappedOpenAIClient"]

guardloop/providers/anthropic.py

@@ -0,0 +1,150 @@
+"""Anthropic Messages API wrapper."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Mapping
+from typing import Any, Protocol, cast
+
+from guardloop.budget import BudgetController
+from guardloop.telemetry.conventions import llm_request_attributes, llm_response_attributes
+from guardloop.telemetry.tracer import Telemetry
+from guardloop.tokenization import estimate_anthropic_tokens
+
+
+class _MessagesAPI(Protocol):
+    def create(self, **kwargs: Any) -> Awaitable[object] | object: ...
+
+
+class _AnthropicClient(Protocol):
+    @property
+    def messages(self) -> _MessagesAPI: ...
+
+
+class WrappedAnthropicClient:
+    """Anthropic client facade that currently wraps `messages.create`."""
+
+    def __init__(
+        self,
+        client: object,
+        budget: BudgetController,
+        telemetry: Telemetry,
+    ) -> None:
+        typed_client = cast(_AnthropicClient, client)
+        self.messages = WrappedAnthropicMessages(typed_client.messages, budget, telemetry)
+
+
+class WrappedAnthropicMessages:
+    def __init__(
+        self,
+        messages: _MessagesAPI,
+        budget: BudgetController,
+        telemetry: Telemetry,
+    ) -> None:
+        self._messages = messages
+        self._budget = budget
+        self._telemetry = telemetry
+
+    async def create(self, **kwargs: Any) -> object:
+        model = _require_str(kwargs, "model")
+        max_tokens = _optional_positive_int(kwargs.get("max_tokens"))
+        estimated_input_tokens = estimate_anthropic_tokens(
+            {"system": kwargs.get("system"), "messages": kwargs.get("messages")}
+        )
+        preflight = self._budget.check_llm_call(
+            provider="anthropic",
+            model=model,
+            estimated_input_tokens=estimated_input_tokens,
+            reserved_output_tokens=max_tokens,
+        )
+
+        with self._telemetry.start_span(
+            "llm_call anthropic.messages.create",
+            llm_request_attributes(
+                provider="anthropic",
+                model=model,
+                estimated_input_tokens=estimated_input_tokens,
+                reserved_output_tokens=preflight.reserved_output_tokens,
+                estimated_cost_usd=preflight.estimated_cost_usd,
+            ),
+        ) as span:
+            try:
+                maybe_response = self._messages.create(**kwargs)
+                response = (
+                    await maybe_response if inspect.isawaitable(maybe_response) else maybe_response
+                )
+                input_tokens, output_tokens = _anthropic_usage_tokens(
+                    response,
+                    fallback_input_tokens=estimated_input_tokens,
+                )
+                actual_cost = self._budget.record_llm_call(
+                    provider="anthropic",
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                )
+                self._telemetry.set_attributes(
+                    span,
+                    llm_response_attributes(
+                        model=model,
+                        input_tokens=input_tokens,
+                        output_tokens=output_tokens,
+                        cost_usd=actual_cost,
+                    ),
+                )
+                self._telemetry.mark_ok(span)
+                return response
+            except Exception as exc:
+                self._telemetry.record_exception(span, exc)
+                raise
+
+
+def _require_str(kwargs: Mapping[str, Any], key: str) -> str:
+    value = kwargs.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"Anthropic messages.create requires a non-empty {key!r}.")
+    return value
+
+
+def _optional_positive_int(value: object) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    try:
+        parsed = int(str(value))
+    except ValueError:
+        return None
+    return parsed if parsed > 0 else None
+
+
+def _get(obj: object, key: str, default: object = None) -> object:
+    if isinstance(obj, Mapping):
+        return cast(Mapping[str, object], obj).get(key, default)
+    return getattr(obj, key, default)
+
+
+def _anthropic_usage_tokens(response: object, *, fallback_input_tokens: int) -> tuple[int, int]:
+    usage = _get(response, "usage")
+    if usage is None:
+        return fallback_input_tokens, 0
+    input_tokens = _as_int(
+        _get(usage, "input_tokens", fallback_input_tokens),
+        fallback_input_tokens,
+    )
+    cache_creation = _as_int(_get(usage, "cache_creation_input_tokens", 0), 0)
+    cache_read = _as_int(_get(usage, "cache_read_input_tokens", 0), 0)
+    output_tokens = _as_int(_get(usage, "output_tokens", 0), 0)
+    return input_tokens + cache_creation + cache_read, output_tokens
+
+
+def _as_int(value: object, default: int) -> int:
+    if isinstance(value, bool) or value is None:
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float | str):
+        return int(value)
+    return default

guardloop/providers/openai.py

@@ -0,0 +1,138 @@
+"""OpenAI Responses API wrapper."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Mapping
+from typing import Any, Protocol, cast
+
+from guardloop.budget import BudgetController
+from guardloop.telemetry.conventions import llm_request_attributes, llm_response_attributes
+from guardloop.telemetry.tracer import Telemetry
+from guardloop.tokenization import estimate_openai_tokens
+
+
+class _ResponsesAPI(Protocol):
+    def create(self, **kwargs: Any) -> Awaitable[object] | object: ...
+
+
+class _OpenAIClient(Protocol):
+    @property
+    def responses(self) -> _ResponsesAPI: ...
+
+
+class WrappedOpenAIClient:
+    """OpenAI client facade that currently wraps `responses.create`."""
+
+    def __init__(self, client: object, budget: BudgetController, telemetry: Telemetry) -> None:
+        typed_client = cast(_OpenAIClient, client)
+        self.responses = WrappedOpenAIResponses(typed_client.responses, budget, telemetry)
+
+
+class WrappedOpenAIResponses:
+    def __init__(
+        self,
+        responses: _ResponsesAPI,
+        budget: BudgetController,
+        telemetry: Telemetry,
+    ) -> None:
+        self._responses = responses
+        self._budget = budget
+        self._telemetry = telemetry
+
+    async def create(self, **kwargs: Any) -> object:
+        model = _require_str(kwargs, "model")
+        max_output_tokens = _optional_positive_int(kwargs.get("max_output_tokens"))
+        estimated_input_tokens = estimate_openai_tokens(model, kwargs.get("input"))
+        preflight = self._budget.check_llm_call(
+            provider="openai",
+            model=model,
+            estimated_input_tokens=estimated_input_tokens,
+            reserved_output_tokens=max_output_tokens,
+        )
+
+        with self._telemetry.start_span(
+            "llm_call openai.responses.create",
+            llm_request_attributes(
+                provider="openai",
+                model=model,
+                estimated_input_tokens=estimated_input_tokens,
+                reserved_output_tokens=preflight.reserved_output_tokens,
+                estimated_cost_usd=preflight.estimated_cost_usd,
+            ),
+        ) as span:
+            try:
+                maybe_response = self._responses.create(**kwargs)
+                response = (
+                    await maybe_response if inspect.isawaitable(maybe_response) else maybe_response
+                )
+                input_tokens, output_tokens = _openai_usage_tokens(
+                    response,
+                    fallback_input_tokens=estimated_input_tokens,
+                )
+                actual_cost = self._budget.record_llm_call(
+                    provider="openai",
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                )
+                self._telemetry.set_attributes(
+                    span,
+                    llm_response_attributes(
+                        model=model,
+                        input_tokens=input_tokens,
+                        output_tokens=output_tokens,
+                        cost_usd=actual_cost,
+                    ),
+                )
+                self._telemetry.mark_ok(span)
+                return response
+            except Exception as exc:
+                self._telemetry.record_exception(span, exc)
+                raise
+
+
+def _require_str(kwargs: Mapping[str, Any], key: str) -> str:
+    value = kwargs.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"OpenAI responses.create requires a non-empty {key!r}.")
+    return value
+
+
+def _optional_positive_int(value: object) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    try:
+        parsed = int(str(value))
+    except ValueError:
+        return None
+    return parsed if parsed > 0 else None
+
+
+def _get(obj: object, key: str, default: object = None) -> object:
+    if isinstance(obj, Mapping):
+        return cast(Mapping[str, object], obj).get(key, default)
+    return getattr(obj, key, default)
+
+
+def _openai_usage_tokens(response: object, *, fallback_input_tokens: int) -> tuple[int, int]:
+    usage = _get(response, "usage")
+    if usage is None:
+        return fallback_input_tokens, 0
+    input_tokens = _get(usage, "input_tokens", _get(usage, "prompt_tokens", fallback_input_tokens))
+    output_tokens = _get(usage, "output_tokens", _get(usage, "completion_tokens", 0))
+    return _as_int(input_tokens, fallback_input_tokens), _as_int(output_tokens, 0)
+
+
+def _as_int(value: object, default: int) -> int:
+    if isinstance(value, bool) or value is None:
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float | str):
+        return int(value)
+    return default

guardloop/runtime.py

@@ -0,0 +1,190 @@
+"""Main GuardLoop entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any
+
+from opentelemetry.trace import Span, Tracer
+
+from guardloop.budget import BudgetController
+from guardloop.circuit_breaker import (
+    CircuitBreakerConfig,
+    CircuitBreakerRegistry,
+    CircuitBreakerSnapshot,
+)
+from guardloop.context import RunContext
+from guardloop.exceptions import GuardLoopError
+from guardloop.models import BudgetConfig, RunResult, TelemetryConfig
+from guardloop.pricing import ModelPricing, PricingCatalog
+from guardloop.telemetry.conventions import (
+    GUARDLOOP_TERMINATED_REASON,
+    run_attributes,
+)
+from guardloop.telemetry.tracer import Telemetry
+
+AgentCallable = Callable[..., Awaitable[object] | object]
+
+
+class GuardLoop:
+    """Execution wrapper that enforces runtime guardrails."""
+
+    def __init__(
+        self,
+        *,
+        budget: BudgetConfig | None = None,
+        telemetry: TelemetryConfig | None = None,
+        circuit_breakers: CircuitBreakerConfig | None = None,
+        pricing: Iterable[ModelPricing] | None = None,
+        include_default_pricing: bool = True,
+        openai_client: Any | None = None,
+        anthropic_client: Any | None = None,
+        tracer: Tracer | None = None,
+    ) -> None:
+        self.budget_config = budget or BudgetConfig()
+        self.telemetry_config = telemetry or TelemetryConfig()
+        self.pricing_catalog = PricingCatalog(pricing, include_defaults=include_default_pricing)
+        self._circuit_breakers = CircuitBreakerRegistry(circuit_breakers)
+        self._openai_client = openai_client
+        self._anthropic_client = anthropic_client
+        self._telemetry = Telemetry(self.telemetry_config, tracer=tracer)
+
+    def circuit_breaker_snapshots(self) -> dict[str, CircuitBreakerSnapshot]:
+        """Return current per-tool circuit breaker state."""
+
+        return self._circuit_breakers.snapshots()
+
+    def reset_circuit_breakers(self, tool_name: str | None = None) -> None:
+        """Reset all circuit breakers or one named tool breaker."""
+
+        self._circuit_breakers.reset(tool_name)
+
+    async def run(self, agent: AgentCallable, *args: object, **kwargs: object) -> RunResult:
+        budget = BudgetController(self.budget_config, self.pricing_catalog)
+        ctx = RunContext(
+            budget=budget,
+            telemetry=self._telemetry,
+            circuit_breakers=self._circuit_breakers,
+            openai_client=self._openai_client,
+            anthropic_client=self._anthropic_client,
+        )
+
+        with self._telemetry.start_span("agent_run", run_attributes()) as span:
+            trace_id = self._telemetry.trace_id(span)
+            try:
+                result = await self._run_with_optional_timeout(agent, ctx, *args, **kwargs)
+                self._telemetry.mark_ok(span)
+                return self._result(
+                    budget=budget,
+                    span=span,
+                    trace_id=trace_id,
+                    success=True,
+                    output=None if result is None else str(result),
+                )
+            except TimeoutError as exc:
+                self._telemetry.record_exception(span, exc)
+                span.set_attribute(GUARDLOOP_TERMINATED_REASON, "timeout")
+                return self._result(
+                    budget=budget,
+                    span=span,
+                    trace_id=trace_id,
+                    success=False,
+                    terminated_reason="timeout",
+                    error_type=type(exc).__name__,
+                    error_message=f"Run exceeded time limit of "
+                    f"{self.budget_config.time_limit_seconds:.3f}s.",
+                )
+            except GuardLoopError as exc:
+                self._telemetry.record_exception(span, exc)
+                span.set_attribute(GUARDLOOP_TERMINATED_REASON, exc.terminated_reason)
+                return self._result(
+                    budget=budget,
+                    span=span,
+                    trace_id=trace_id,
+                    success=False,
+                    terminated_reason=exc.terminated_reason,
+                    error_type=type(exc).__name__,
+                    error_message=str(exc),
+                    metadata={"details": _json_safe_details(exc.details)},
+                )
+            except Exception as exc:
+                self._telemetry.record_exception(span, exc)
+                span.set_attribute(GUARDLOOP_TERMINATED_REASON, "error")
+                return self._result(
+                    budget=budget,
+                    span=span,
+                    trace_id=trace_id,
+                    success=False,
+                    terminated_reason="error",
+                    error_type=type(exc).__name__,
+                    error_message=str(exc),
+                )
+
+    async def _run_with_optional_timeout(
+        self,
+        agent: AgentCallable,
+        ctx: RunContext,
+        *args: object,
+        **kwargs: object,
+    ) -> object:
+        if self.budget_config.time_limit_seconds is None:
+            return await _call_agent(agent, ctx, *args, **kwargs)
+        async with asyncio.timeout(self.budget_config.time_limit_seconds):
+            return await _call_agent(agent, ctx, *args, **kwargs)
+
+    @staticmethod
+    def _result(
+        *,
+        budget: BudgetController,
+        span: Span,
+        trace_id: str | None,
+        success: bool,
+        output: str | None = None,
+        terminated_reason: str | None = None,
+        error_type: str | None = None,
+        error_message: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RunResult:
+        return RunResult(
+            output=output,
+            success=success,
+            cost_usd=budget.cost_usd,
+            estimated_cost_usd=budget.estimated_cost_usd,
+            tokens_used=budget.tokens_used,
+            input_tokens=budget.input_tokens,
+            output_tokens=budget.output_tokens,
+            duration_seconds=budget.duration_seconds,
+            tool_calls=budget.tool_calls,
+            trace_id=trace_id or Telemetry.trace_id(span),
+            terminated_reason=terminated_reason,
+            error_type=error_type,
+            error_message=error_message,
+            metadata=metadata or {},
+        )
+
+
+async def _call_agent(
+    agent: AgentCallable,
+    ctx: RunContext,
+    *args: object,
+    **kwargs: object,
+) -> object:
+    result = agent(ctx, *args, **kwargs)
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+JsonSafeDetail = str | int | float | bool | None
+
+
+def _json_safe_details(details: dict[str, Any]) -> dict[str, JsonSafeDetail]:
+    return {key: _json_safe_detail(value) for key, value in details.items() if value is not None}
+
+
+def _json_safe_detail(value: Any) -> JsonSafeDetail:
+    if isinstance(value, str | int | float | bool):
+        return value
+    return str(value)