logfire-api 4.35.0__tar.gz → 4.36.0__tar.gz

{logfire_api-4.35.0 → logfire_api-4.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logfire-api
-Version: 4.35.0
+Version: 4.36.0
 Summary: Shim for the Logfire SDK which does nothing unless Logfire is installed
 Author-email: Pydantic Team <engineering@pydantic.dev>, Samuel Colvin <samuel@pydantic.dev>, Hasan Ramezani <hasan@pydantic.dev>, Adrian Garcia Badaracco <adrian@pydantic.dev>, David Montague <david@pydantic.dev>, Marcelo Trylesinski <marcelo@pydantic.dev>, David Hewitt <david.hewitt@pydantic.dev>, Alex Hall <alex@pydantic.dev>
 License-Expression: MIT

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/__init__.pyi

@@ -16,7 +16,7 @@ from logfire.propagate import attach_context as attach_context, get_context as g
 from logfire.sampling import SamplingOptions as SamplingOptions
 from typing import Any
 
-__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'warning', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_asgi', 'instrument_wsgi', 'instrument_pydantic', 'instrument_pydantic_ai', 'instrument_fastapi', 'instrument_openai', 'instrument_openai_agents', 'instrument_anthropic', 'instrument_google_genai', 'instrument_litellm', 'instrument_dspy', 'instrument_print', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_aiohttp_server', 'instrument_sqlalchemy', 'instrument_sqlite3', 'instrument_aws_lambda', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_surrealdb', 'instrument_system_metrics', 'instrument_mcp', 'instrument_claude_agent_sdk', 'AutoTraceModule', 'with_tags', 'with_settings', 'suppress_scopes', 'shutdown', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'add_non_user_code_prefix', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions', 'VariablesOptions', 'LocalVariablesOptions', 'variables', 'var', 'variables_clear', 'variables_get', 'variables_push', 'variables_push_types', 'variables_validate', 'variables_push_config', 'variables_pull_config', 'variables_build_config', 'logfire_info', 'get_baggage', 'set_baggage', 'get_context', 'attach_context', 'url_from_eval', 'forward_export_request', 'forward_export_request_starlette']
+__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'warning', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_asgi', 'instrument_wsgi', 'instrument_pydantic', 'instrument_pydantic_ai', 'instrument_fastapi', 'instrument_openai', 'instrument_openai_agents', 'instrument_anthropic', 'instrument_google_genai', 'instrument_litellm', 'instrument_dspy', 'instrument_print', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_aiohttp_server', 'instrument_sqlalchemy', 'instrument_sqlite3', 'instrument_aws_lambda', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_surrealdb', 'instrument_system_metrics', 'instrument_mcp', 'instrument_claude_agent_sdk', 'AutoTraceModule', 'with_tags', 'with_settings', 'suppress_scopes', 'shutdown', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'add_non_user_code_prefix', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions', 'VariablesOptions', 'LocalVariablesOptions', 'variables', 'var', 'template_var', 'variables_clear', 'variables_get', 'variables_push', 'variables_push_types', 'variables_validate', 'variables_push_config', 'variables_pull_config', 'variables_build_config', 'logfire_info', 'get_baggage', 'set_baggage', 'get_context', 'attach_context', 'url_from_eval', 'forward_export_request', 'forward_export_request_starlette']
 
 DEFAULT_LOGFIRE_INSTANCE = Logfire()
 span = DEFAULT_LOGFIRE_INSTANCE.span
@@ -74,6 +74,7 @@ error = DEFAULT_LOGFIRE_INSTANCE.error
 fatal = DEFAULT_LOGFIRE_INSTANCE.fatal
 exception = DEFAULT_LOGFIRE_INSTANCE.exception
 var = DEFAULT_LOGFIRE_INSTANCE.var
+template_var = DEFAULT_LOGFIRE_INSTANCE.template_var
 variables_clear = DEFAULT_LOGFIRE_INSTANCE.variables_clear
 variables_get = DEFAULT_LOGFIRE_INSTANCE.variables_get
 variables_push = DEFAULT_LOGFIRE_INSTANCE.variables_push

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/_internal/config.pyi

@@ -81,8 +81,8 @@ class PydanticPlugin:
     This class is deprecated for external use. Use `logfire.instrument_pydantic()` instead.
     """
     record: PydanticPluginRecordValues = ...
-    include: set[str] = field(default_factory=set)
-    exclude: set[str] = field(default_factory=set)
+    include: set[str] = field(default_factory=set[str])
+    exclude: set[str] = field(default_factory=set[str])
 
 @dataclass
 class MetricsOptions:
@@ -99,6 +99,8 @@ class CodeSource:
     revision: str
     root_path: str = ...
 
+TemplateMismatchPolicy: Incomplete
+
 @dataclass
 class VariablesOptions:
     """Configuration for managed variables using the Logfire remote API.
@@ -112,6 +114,7 @@ class VariablesOptions:
     include_resource_attributes_in_context: bool = ...
     include_baggage_in_context: bool = ...
     instrument: bool = ...
+    template_mismatch_policy: TemplateMismatchPolicy = ...
     def __post_init__(self) -> None: ...
 
 @dataclass
@@ -125,6 +128,7 @@ class LocalVariablesOptions:
     include_resource_attributes_in_context: bool = ...
     include_baggage_in_context: bool = ...
     instrument: bool = ...
+    template_mismatch_policy: TemplateMismatchPolicy = ...
 
 class DeprecatedKwargs(TypedDict): ...
 
@@ -286,8 +290,8 @@ class LogfireConfig(_LogfireConfigData):
         This is used internally and should not be called by users of the SDK.
 
         If no provider has been explicitly configured (i.e. `variables=` was not passed to
-        `configure()`), but a `LOGFIRE_API_KEY` is available, a `LogfireRemoteVariableProvider`
-        will be lazily created on the first call.
+        `configure()`), but `configure()` has been called and a `LOGFIRE_API_KEY` is available,
+        a `LogfireRemoteVariableProvider` will be lazily created on the first call.
 
         Returns:
             The variable provider.

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/_internal/logs.pyi

@@ -11,9 +11,9 @@ from weakref import WeakSet
 class ProxyLoggerProvider(LoggerProvider):
     """A logger provider that wraps another internal logger provider allowing it to be re-assigned."""
     provider: LoggerProvider
-    loggers: WeakSet[ProxyLogger] = dataclasses.field(default_factory=WeakSet)
+    loggers: WeakSet[ProxyLogger] = dataclasses.field(default_factory=WeakSet['ProxyLogger'])
     lock: Lock = dataclasses.field(default_factory=Lock)
-    suppressed_scopes: set[str] = dataclasses.field(default_factory=set)
+    suppressed_scopes: set[str] = dataclasses.field(default_factory=set[str])
     min_level: int = ...
     def get_logger(self, name: str, version: str | None = None, schema_url: str | None = None, attributes: _ExtendedAttributes | None = None) -> Logger: ...
     def set_min_level(self, min_level: int) -> None: ...

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/_internal/main.pyi

@@ -14,10 +14,10 @@ from ..integrations.psycopg import CommenterOptions as PsycopgCommenterOptions
 from ..integrations.redis import RequestHook as RedisRequestHook, ResponseHook as RedisResponseHook
 from ..integrations.sqlalchemy import CommenterOptions as SQLAlchemyCommenterOptions
 from ..integrations.wsgi import RequestHook as WSGIRequestHook, ResponseHook as WSGIResponseHook
-from ..variables import ResolveFunction as ResolveFunction, ValidationReport as ValidationReport, Variable as Variable, VariablesConfig as VariablesConfig
+from ..variables import ResolveFunction as ResolveFunction, TemplateVariable as TemplateVariable, ValidationReport as ValidationReport, Variable as Variable, VariablesConfig as VariablesConfig
 from ..version import VERSION as VERSION
 from .auto_trace import AutoTraceModule as AutoTraceModule, install_auto_tracing as install_auto_tracing
-from .config import GLOBAL_CONFIG as GLOBAL_CONFIG, LogfireConfig as LogfireConfig
+from .config import GLOBAL_CONFIG as GLOBAL_CONFIG, LogfireConfig as LogfireConfig, TemplateMismatchPolicy as TemplateMismatchPolicy
 from .config_params import PydanticPluginRecordValues as PydanticPluginRecordValues
 from .constants import ATTRIBUTES_JSON_SCHEMA_KEY as ATTRIBUTES_JSON_SCHEMA_KEY, ATTRIBUTES_LOG_LEVEL_NUM_KEY as ATTRIBUTES_LOG_LEVEL_NUM_KEY, ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY, ATTRIBUTES_MESSAGE_TEMPLATE_KEY as ATTRIBUTES_MESSAGE_TEMPLATE_KEY, ATTRIBUTES_SAMPLE_RATE_KEY as ATTRIBUTES_SAMPLE_RATE_KEY, ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY, ATTRIBUTES_TAGS_KEY as ATTRIBUTES_TAGS_KEY, DISABLE_CONSOLE_KEY as DISABLE_CONSOLE_KEY, LEVEL_NUMBERS as LEVEL_NUMBERS, LevelName as LevelName, OTLP_MAX_INT_SIZE as OTLP_MAX_INT_SIZE, log_level_attributes as log_level_attributes
 from .formatter import logfire_format as logfire_format, logfire_format_with_magic as logfire_format_with_magic
@@ -64,6 +64,7 @@ from wsgiref.types import WSGIApplication
 
 ExcInfo = SysExcInfo | BaseException | bool | None
 T = TypeVar('T')
+InputsT = TypeVar('InputsT')
 
 class Logfire:
     """The main logfire class."""
@@ -1214,16 +1215,21 @@ class Logfire:
     def var(self, name: str, *, default: T, description: str | None = None) -> Variable[T]: ...
     @overload
     def var(self, name: str, *, type: type[T], default: T | ResolveFunction[T], description: str | None = None) -> Variable[T]: ...
+    @overload
+    def template_var(self, name: str, *, default: T, inputs_type: type[InputsT], description: str | None = None, template_mismatch_policy: TemplateMismatchPolicy | None = None) -> TemplateVariable[T, InputsT]: ...
+    @overload
+    def template_var(self, name: str, *, type: type[T], default: T | ResolveFunction[T], inputs_type: type[InputsT], description: str | None = None, template_mismatch_policy: TemplateMismatchPolicy | None = None) -> TemplateVariable[T, InputsT]: ...
     def variables_clear(self) -> None:
         """Clear all registered variables from this Logfire instance.
 
-        This removes all variables previously registered via [`var()`][logfire.Logfire.var],
+        This removes all variables previously registered via [`var()`][logfire.Logfire.var]
+        or [`template_var()`][logfire.Logfire.template_var],
         allowing them to be re-registered. This is primarily intended for use in tests
         to ensure a clean state between test cases.
         """
-    def variables_get(self) -> list[Variable[Any]]:
+    def variables_get(self) -> list[Variable[Any] | TemplateVariable[Any, Any]]:
         """Get all variables registered with this Logfire instance."""
-    def variables_push(self, variables: list[Variable[Any]] | None = None, *, dry_run: bool = False, yes: bool = False, strict: bool = False) -> bool:
+    def variables_push(self, variables: list[Variable[Any] | TemplateVariable[Any, Any]] | None = None, *, dry_run: bool = False, yes: bool = False, strict: bool = False) -> bool:
         """Push variable definitions (metadata only) to the configured variable provider.
 
         This method syncs local variable definitions with the provider:
@@ -1239,7 +1245,8 @@ class Logfire:
                 registered with this Logfire instance will be pushed.
             dry_run: If True, only show what would change without applying.
             yes: If True, skip confirmation prompt.
-            strict: If True, fail if any existing label values are incompatible with new schemas.
+            strict: If True, fail if any existing label values are incompatible with new schemas
+                or any reference errors are found.
 
         Returns:
             True if changes were applied (or would be applied in dry_run mode), False otherwise.
@@ -1316,7 +1323,7 @@ class Logfire:
                 )
             ```
         """
-    def variables_validate(self, variables: list[Variable[Any]] | None = None) -> ValidationReport:
+    def variables_validate(self, variables: list[Variable[Any] | TemplateVariable[Any, Any]] | None = None) -> ValidationReport:
         """Validate that provider-side variable label values match local type definitions.
 
         This method fetches the current variable configuration from the provider and
@@ -1350,8 +1357,10 @@ class Logfire:
     def variables_push_config(self, config: VariablesConfig, *, mode: Literal['merge', 'replace'] = 'merge', dry_run: bool = False, yes: bool = False) -> bool:
         '''Push a VariablesConfig to the configured provider.
 
-        This method pushes a complete VariablesConfig (including labels and rollouts)
-        to the provider. It\'s useful for:
+        This method pushes a VariablesConfig (including labels and rollouts) to the
+        provider. For remote providers, version records are created from label
+        entries with inline serialized values; `latest_version` is pull/read state
+        derived by the server and is not pushed directly. It\'s useful for:
         - Pushing configs generated or modified locally
         - Pushing configs read from files
         - Partial updates (merge mode) or full replacement (replace mode)
@@ -1396,7 +1405,7 @@ class Logfire:
             print(config.model_dump_json(indent=2))
             ```
         '''
-    def variables_build_config(self, variables: list[Variable[Any]] | None = None) -> VariablesConfig:
+    def variables_build_config(self, variables: list[Variable[Any] | TemplateVariable[Any, Any]] | None = None) -> VariablesConfig:
         '''Build a VariablesConfig from registered Variable instances.
 
         This creates a minimal config with just the name, schema, and example for each variable.

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/_internal/metrics.pyi

@@ -11,9 +11,9 @@ from weakref import WeakSet
 @dataclasses.dataclass
 class ProxyMeterProvider(MeterProvider):
     provider: MeterProvider
-    meters: WeakSet[_ProxyMeter] = dataclasses.field(default_factory=WeakSet)
+    meters: WeakSet[_ProxyMeter] = dataclasses.field(default_factory=WeakSet['_ProxyMeter'])
     lock: Lock = dataclasses.field(default_factory=Lock)
-    suppressed_scopes: set[str] = dataclasses.field(default_factory=set)
+    suppressed_scopes: set[str] = dataclasses.field(default_factory=set[str])
     def get_meter(self, name: str, version: str | None = None, schema_url: str | None = None, attributes: Attributes | None = None) -> Meter: ...
     def suppress_scopes(self, *scopes: str) -> None: ...
     def set_meter_provider(self, meter_provider: MeterProvider) -> None: ...

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/_internal/tracer.pyi

@@ -25,9 +25,9 @@ class ProxyTracerProvider(TracerProvider):
     """A tracer provider that wraps another internal tracer provider allowing it to be re-assigned."""
     provider: TracerProvider
     config: LogfireConfig
-    tracers: WeakKeyDictionary[_ProxyTracer, Callable[[], Tracer]] = field(default_factory=WeakKeyDictionary)
+    tracers: WeakKeyDictionary[_ProxyTracer, Callable[[], Tracer]] = field(default_factory=WeakKeyDictionary['_ProxyTracer', Callable[[], Tracer]])
     lock: Lock = field(default_factory=Lock)
-    suppressed_scopes: set[str] = field(default_factory=set)
+    suppressed_scopes: set[str] = field(default_factory=set[str])
     def set_provider(self, provider: SDKTracerProvider) -> None: ...
     def suppress_scopes(self, *scopes: str) -> None: ...
     def get_tracer(self, instrumenting_module_name: str, *args: Any, is_span_tracer: bool = True, **kwargs: Any) -> _ProxyTracer: ...

logfire_api-4.36.0/logfire_api/variables/__init__.pyi

@@ -0,0 +1,6 @@
+from logfire.variables.abstract import ResolutionReason as ResolutionReason, ResolvedVariable as ResolvedVariable, SyncMode as SyncMode, ValidationReport as ValidationReport, VariableAlreadyExistsError as VariableAlreadyExistsError, VariableNotFoundError as VariableNotFoundError, VariableWriteError as VariableWriteError
+from logfire.variables.composition import ComposedReference as ComposedReference, VariableCompositionCycleError as VariableCompositionCycleError, VariableCompositionError as VariableCompositionError
+from logfire.variables.config import KeyIsNotPresent as KeyIsNotPresent, KeyIsPresent as KeyIsPresent, LabelRef as LabelRef, LabeledValue as LabeledValue, LatestVersion as LatestVersion, LocalVariablesOptions as LocalVariablesOptions, Rollout as Rollout, RolloutOverride as RolloutOverride, TemplateMismatchPolicy as TemplateMismatchPolicy, ValueDoesNotEqual as ValueDoesNotEqual, ValueDoesNotMatchRegex as ValueDoesNotMatchRegex, ValueEquals as ValueEquals, ValueIsIn as ValueIsIn, ValueIsNotIn as ValueIsNotIn, ValueMatchesRegex as ValueMatchesRegex, VariableConfig as VariableConfig, VariableTypeConfig as VariableTypeConfig, VariablesConfig as VariablesConfig
+from logfire.variables.variable import ResolveFunction as ResolveFunction, TemplateInputsMismatchError as TemplateInputsMismatchError, TemplateVariable as TemplateVariable, Variable as Variable, targeting_context as targeting_context
+
+__all__ = ['Variable', 'TemplateVariable', 'ResolvedVariable', 'ResolveFunction', 'VariablesConfig', 'VariableConfig', 'VariableTypeConfig', 'LocalVariablesOptions', 'LabeledValue', 'LabelRef', 'LatestVersion', 'Rollout', 'RolloutOverride', 'KeyIsPresent', 'KeyIsNotPresent', 'ValueEquals', 'ValueDoesNotEqual', 'ValueIsIn', 'ValueIsNotIn', 'ValueMatchesRegex', 'ValueDoesNotMatchRegex', 'targeting_context', 'ComposedReference', 'ResolutionReason', 'SyncMode', 'TemplateMismatchPolicy', 'ValidationReport', 'TemplateInputsMismatchError', 'VariableAlreadyExistsError', 'VariableCompositionCycleError', 'VariableCompositionError', 'VariableNotFoundError', 'VariableWriteError']

logfire_api-4.36.0/logfire_api/variables/_handlebars.pyi

@@ -0,0 +1,52 @@
+from functools import cache
+from pydantic_handlebars import CompiledTemplate, HandlebarsEnvironment
+
+COMPOSITION_OPEN_DELIM: str
+COMPOSITION_CLOSE_DELIM: str
+
+@cache
+def get_environment(strict: bool = False) -> HandlebarsEnvironment:
+    """Return a cached `HandlebarsEnvironment` configured for `@{...}@` composition.
+
+    Uses non-default delimiters so the composition pass leaves any
+    `{{...}}` runtime placeholders in the template as plain content; a
+    subsequent render pass with the default delimiters consumes those.
+
+    When *strict* is `True`, the environment raises `HandlebarsRuntimeError`
+    for any `@{ref}@` (or dotted `@{ref.field}@`) that doesn't resolve, rather
+    than rendering it as an empty string. Composition uses the strict
+    environment for provider/override values (so a missing reference triggers a
+    fall back to the code default) and the non-strict one for the code default
+    itself (the lenient last resort, where a missing reference renders empty).
+    """
+@cache
+def get_runtime_environment() -> HandlebarsEnvironment:
+    """Return a cached default-delimiter `HandlebarsEnvironment` for `{{...}}` rendering.
+
+    Used by `TemplateVariable.get(inputs)` to render the post-composition
+    serialized value against the provided inputs.
+    """
+def compile_composition_template(source: str, strict: bool = False) -> CompiledTemplate:
+    """Return a cached `CompiledTemplate` for *source* under composition delimiters.
+
+    Managed-variable values are typically stable across many resolutions, so
+    caching the parsed program lets `Variable._resolve` skip the parse on
+    every `get()` call. 1024 is large enough for any realistic number of
+    distinct templates in a single process while staying bounded for
+    long-running workers. Same rationale for `compile_runtime_template`.
+
+    *strict* selects the strict vs non-strict composition environment (see
+    `get_environment`); the two are cached separately.
+    """
+def compile_runtime_template(source: str) -> CompiledTemplate:
+    """Return a cached `CompiledTemplate` for *source* under default `{{...}}` delimiters."""
+def extract_composition_dependencies(template: str) -> frozenset[str]:
+    """Return the top-level `@{name}@` references in *template*.
+
+    Cached because cycle / reference validation runs over the same template
+    strings multiple times per push or sync. The underlying delegation goes
+    to `pydantic_handlebars.extract_dependencies` configured for the
+    composition delimiters, so block helpers, dotted paths, and helper
+    sub-expressions are handled AST-correctly. A `frozenset` is returned so the
+    cached value can't be mutated by a caller and poison later lookups.
+    """

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/variables/abstract.pyi

@@ -2,12 +2,14 @@ import logfire
 from _typeshed import Incomplete
 from abc import ABC, abstractmethod
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from logfire.variables.composition import ComposedReference
 from logfire.variables.config import VariableConfig, VariableTypeConfig, VariablesConfig
+from logfire.variables.template_validation import TemplateFieldIssue
 from logfire.variables.variable import Variable
 from typing import Any, Generic, TypeVar
 
-__all__ = ['ResolvedVariable', 'ResolutionReason', 'SyncMode', 'ValidationReport', 'VariableProvider', 'NoOpVariableProvider', 'VariableWriteError', 'VariableNotFoundError', 'VariableAlreadyExistsError']
+__all__ = ['ResolvedVariable', 'ResolutionReason', 'SyncMode', 'ValidationReport', 'VariableProvider', 'NoOpVariableProvider', 'VariableWriteError', 'VariableNotFoundError', 'VariableAlreadyExistsError', 'render_serialized_string']
 
 SyncMode: Incomplete
 T = TypeVar('T')
@@ -46,11 +48,27 @@ class ResolvedVariable(Generic[T_co]):
     label: str | None = ...
     version: int | None = ...
     exception: Exception | None = ...
+    composed_from: list[ComposedReference] = field(default_factory=list['ComposedReference'])
     reason: ResolutionReason
     def __post_init__(self) -> None: ...
     def __enter__(self): ...
     def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None: ...
 
+def render_serialized_string(serialized_json: str, inputs: Any) -> str:
+    """Render Handlebars templates in a serialized JSON string.
+
+    Decodes the JSON, renders all string values containing `{{placeholders}}`
+    using the provided inputs, then re-encodes to JSON.
+
+    Args:
+        serialized_json: A JSON-encoded string potentially containing Handlebars templates.
+        inputs: Template context values. Can be a Pydantic `BaseModel`, `dict`,
+            `Mapping`, or `None`.
+
+    Returns:
+        The rendered JSON string.
+    """
+
 @dataclass
 class LabelCompatibility:
     """Result of checking a label value's compatibility with a schema."""
@@ -72,12 +90,18 @@ class VariableChange:
     local_description: str | None = ...
     server_description: str | None = ...
     description_differs: bool = ...
+    template_inputs_schema: dict[str, Any] | None = ...
+    value_schema_changed: bool = ...
+    inputs_schema_changed: bool = ...
 
 @dataclass
 class VariableDiff:
     """Represents the diff between local and server variables."""
     changes: list[VariableChange]
     orphaned_server_variables: list[str]
+    reference_errors: list[str] = field(default_factory=list[str])
+    reference_cycles: list[str] = field(default_factory=list[str])
+    template_field_issues: list[TemplateFieldIssue] = field(default_factory=list)
     @property
     def has_changes(self) -> bool:
         """Return True if there are any changes to apply."""
@@ -116,12 +140,15 @@ class ValidationReport:
     variables_checked: int
     variables_not_on_server: list[str]
     description_differences: list[DescriptionDifference]
+    reference_errors: list[str] = field(default_factory=list[str])
+    reference_cycles: list[str] = field(default_factory=list[str])
+    template_field_issues: list[TemplateFieldIssue] = field(default_factory=list)
     @property
     def has_errors(self) -> bool:
         """Return True if there are any validation errors."""
     @property
     def is_valid(self) -> bool:
-        """Return False if there are any validation errors or any variables not defined in the (possibly remote) config."""
+        """Return False if there are validation errors, missing variables, or reference errors."""
     def format(self, *, colors: bool = True) -> str:
         """Format the validation report for human-readable output.
 
@@ -276,8 +303,10 @@ class VariableProvider(ABC):
     def push_config(self, config: VariablesConfig, *, mode: SyncMode = 'merge', dry_run: bool = False, yes: bool = False) -> bool:
         """Push a VariablesConfig to this provider.
 
-        This method pushes a complete VariablesConfig (including labels and rollouts)
-        to the provider. It's useful for:
+        This method pushes a VariablesConfig (including labels and rollouts) to the
+        provider. For remote providers, version records are created from label
+        entries with inline serialized values; `latest_version` is pull/read state
+        derived by the server and is not pushed directly. It's useful for:
         - Pushing configs generated or modified locally
         - Pushing configs read from files
         - Partial updates (merge mode) or full replacement (replace mode)
@@ -313,7 +342,8 @@ class VariableProvider(ABC):
             variables: Variable instances to push.
             dry_run: If True, only show what would change without applying.
             yes: If True, skip confirmation prompt.
-            strict: If True, fail if any existing label values are incompatible with new schemas.
+            strict: If True, fail if any existing label values are incompatible with new schemas
+                or any reference errors are found.
 
         Returns:
             True if changes were applied (or would be applied in dry_run mode), False otherwise.

logfire_api-4.36.0/logfire_api/variables/composition.pyi

@@ -0,0 +1,102 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from logfire.variables.abstract import ResolutionReason
+
+__all__ = ['MAX_COMPOSITION_DEPTH', 'VariableCompositionError', 'VariableCompositionCycleError', 'ComposedReference', 'expand_references', 'find_references', 'find_references_and_errors', 'has_references']
+
+MAX_COMPOSITION_DEPTH: int
+
+class VariableCompositionError(Exception):
+    """Error during variable composition (reference expansion)."""
+class VariableCompositionCycleError(VariableCompositionError):
+    """Circular reference detected during variable composition."""
+
+@dataclass
+class ComposedReference:
+    """Metadata about a single `@{reference}@` that was encountered during expansion.
+
+    This is a lightweight dataclass used to track composition results without
+    depending on ResolvedVariable, making it reusable from both the SDK and backend.
+    """
+    name: str
+    value: str | None
+    label: str | None
+    version: int | None
+    reason: ResolutionReason
+    error: str | None = ...
+    composed_from: list[ComposedReference] = field(default_factory=list['ComposedReference'])
+    fatal: bool = ...
+ResolveFn = Callable[[str], tuple[str | None, str | None, int | None, ResolutionReason]]
+
+def has_references(serialized_value: str) -> bool:
+    """Quick check for any `@{` in a serialized value.
+
+    Returns `True` whenever the string contains the composition open
+    delimiter, regardless of preceding backslashes. The actual
+    escape-or-real decision is made by `pydantic_handlebars` at render time
+    — distinguishing an escaped `\\@{x}@` from an unescaped `@{x}@` here
+    would require a variable-width lookbehind (the renderer counts
+    backslash parity to match Handlebars.js semantics) and is unnecessary:
+    `extract_composition_dependencies` returns an empty set for escaped-only
+    strings, and the renderer correctly leaves the literal text in place.
+    """
+def expand_references(serialized_value: str, variable_name: str, resolve_fn: ResolveFn, *, strict: bool = False, _visited: tuple[str, ...] = (), _depth: int = 0) -> tuple[str, list[ComposedReference]]:
+    """Expand `@{var}@` references in a serialized variable value.
+
+    Uses the Handlebars engine so `@{}@` supports the full Handlebars
+    syntax — simple references, dotted field reads, block helpers (including
+    with dotted or sub-expression headers like `@{#if user.active}@`), and
+    helper sub-expressions — while preserving `{{runtime}}` placeholders
+    untouched.
+
+    Args:
+        serialized_value: The raw JSON-serialized variable value.
+        variable_name: Name of the variable being expanded (for cycle detection).
+        resolve_fn: Function that resolves a variable name to
+            (serialized_value, label, version, reason).
+        strict: When `True`, an unresolved `@{ref}@` / `@{ref.field}@` raises
+            `HandlebarsRuntimeError` instead of rendering as an empty string.
+            The SDK composes provider/override values strictly (so a missing
+            reference falls back to the code default) and the code default
+            non-strictly (the lenient last resort). Nested expansions inherit
+            this flag.
+        _visited: Internal - ordered variable names in the current expansion chain.
+        _depth: Internal - current recursion depth.
+
+    Returns:
+        tuple of (expanded_serialized_value, list_of_composed_references).
+
+    Raises:
+        VariableCompositionError: If max depth is exceeded.
+        VariableCompositionCycleError: If a circular reference is detected.
+        HandlebarsRuntimeError: Under *strict*, if a reference is unresolved.
+    """
+def find_references(serialized_value: str) -> list[str]:
+    """Find all top-level `@{variable_name}@` references in a serialized value.
+
+    Walks the decoded JSON value and runs each string containing composition
+    syntax through `pydantic_handlebars.extract_dependencies`, so block
+    helpers (`@{#if var}@`), dotted paths (`@{var.field}@`), and
+    subexpressions (`@{lookup obj key}@`) are all picked up correctly. A string
+    whose `@{...}@` syntax can't be parsed is skipped (contributes no
+    references) so this never raises; use `find_references_and_errors` to also
+    surface those parse failures.
+
+    Args:
+        serialized_value: The raw JSON-serialized variable value to scan.
+
+    Returns:
+        Sorted (alphabetical) list of unique top-level variable names referenced.
+    """
+def find_references_and_errors(serialized_value: str) -> tuple[list[str], list[str]]:
+    """Find references AND parse-error messages in a serialized value.
+
+    Like `find_references`, but also returns a message for every string whose
+    `@{...}@` syntax can't be parsed (malformed template, reserved name). Used by
+    push / validate so a malformed value is surfaced as a loud error rather than
+    silently skipped the way `find_references` does (it skips them so resolution
+    can degrade gracefully).
+
+    Returns:
+        ``(sorted unique reference names, parse-error messages)``.
+    """

{logfire_api-4.35.0 → logfire_api-4.36.0}/logfire_api/variables/config.pyi

@@ -1,12 +1,12 @@
 import re
 from collections.abc import Mapping, Sequence
-from logfire._internal.config import LocalVariablesOptions as LocalVariablesOptions
+from logfire._internal.config import LocalVariablesOptions as LocalVariablesOptions, TemplateMismatchPolicy as TemplateMismatchPolicy
 from logfire.variables.abstract import ResolvedVariable
 from logfire.variables.variable import Variable
 from pydantic import BaseModel
 from typing import Any, Literal
 
-__all__ = ['KeyIsNotPresent', 'KeyIsPresent', 'LabeledValue', 'LabelRef', 'LatestVersion', 'LocalVariablesOptions', 'Rollout', 'RolloutOverride', 'ValueDoesNotEqual', 'ValueDoesNotMatchRegex', 'ValueEquals', 'ValueIsIn', 'ValueIsNotIn', 'ValueMatchesRegex', 'VariableConfig', 'VariablesConfig', 'VariableTypeConfig']
+__all__ = ['KeyIsNotPresent', 'KeyIsPresent', 'LabeledValue', 'LabelRef', 'LatestVersion', 'LocalVariablesOptions', 'Rollout', 'RolloutOverride', 'TemplateMismatchPolicy', 'ValueDoesNotEqual', 'ValueDoesNotMatchRegex', 'ValueEquals', 'ValueIsIn', 'ValueIsNotIn', 'ValueMatchesRegex', 'VariableConfig', 'VariablesConfig', 'VariableTypeConfig']
 
 class ValueEquals(BaseModel):
     """Condition that matches when an attribute equals a specific value."""
@@ -76,7 +76,13 @@ class LabeledValue(BaseModel):
     serialized_value: str
 
 class LabelRef(BaseModel):
-    """A label pointing to a version via a reference to another label, 'latest', or 'code_default'."""
+    """A label pointing to a version via a reference to another label, 'latest', or 'code_default'.
+
+    Note: `'latest'` and `'code_default'` are *reserved label names*. The platform rejects
+    user attempts to create labels with these names, so anywhere the SDK treats them as
+    special — `follow_ref` here, and the push-time validation that keys values by label
+    name — it can rely on them being unambiguous (no user-defined label can collide).
+    """
     version: int | None
     ref: str
 
@@ -117,6 +123,7 @@ class VariableConfig(BaseModel):
     type_name: str | None
     aliases: list[VariableName] | None
     example: str | None
+    template_inputs_schema: dict[str, Any] | None
     def resolve_label(self, targeting_key: str | None = None, attributes: Mapping[str, Any] | None = None) -> str | None:
         """Evaluate rollout rules and return the selected label name.
 
@@ -182,7 +189,7 @@ class VariablesConfig(BaseModel):
         Returns:
             A ResolvedVariable containing the serialized value (or None if not found).
         """
-    def get_validation_errors(self, variables: list[Variable[Any]]) -> dict[str, dict[str | None, Exception]]:
+    def get_validation_errors(self, variables: Sequence[Variable[Any]]) -> dict[str, dict[str | None, Exception]]:
         """Validate that all variable label values can be deserialized to their expected types.
 
         Args:
@@ -192,7 +199,7 @@ class VariablesConfig(BaseModel):
             A dict mapping variable names to dicts of label names (or None for general errors) to exceptions.
         """
     @staticmethod
-    def from_variables(variables: list[Variable[Any]]) -> VariablesConfig:
+    def from_variables(variables: Sequence[Variable[Any]]) -> VariablesConfig:
         """Create a VariablesConfig from a list of Variable instances.
 
         This creates a minimal config with just the name, schema, and example for each variable.

logfire_api-4.36.0/logfire_api/variables/template_validation.pyi

@@ -0,0 +1,53 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ['TemplateFieldIssue', 'TemplateValidationResult', 'validate_template_composition', 'detect_composition_cycles', 'extract_template_strings']
+
+@dataclass
+class TemplateFieldIssue:
+    """A `{{field}}` reference that doesn't match a template variable's `template_inputs_schema`."""
+    field_name: str
+    found_in_variable: str
+    found_in_label: str | None
+    reference_path: list[str]
+    root_variable: str
+
+@dataclass
+class TemplateValidationResult:
+    """Result of template composition validation."""
+    issues: list[TemplateFieldIssue] = field(default_factory=list[TemplateFieldIssue])
+
+def extract_template_strings(serialized_json: str) -> list[str]:
+    """Extract all string values from serialized JSON that contain `{{...}}` templates."""
+def validate_template_composition(variable_name: str, template_inputs_schema: dict[str, Any], get_all_serialized_values: Callable[[str], dict[str | None, str]]) -> TemplateValidationResult:
+    """Validate that `{{field}}` references in a template variable match its schema.
+
+    Walks the composition graph starting from *variable_name*, collecting all
+    template strings from the variable's values and its `@{ref}@` dependencies,
+    then uses AST-based schema checking via `check_template_compatibility` to
+    find incompatible field references.
+
+    Args:
+        variable_name: Name of the template variable to validate.
+        template_inputs_schema: JSON Schema describing the expected template inputs.
+        get_all_serialized_values: Function that returns `{label_or_none: serialized_json}`
+            for any variable name. Each key is the label that serves that value; the
+            `None` key is the code default, and `'latest'` is the latest version.
+
+    Returns:
+        A :class:`TemplateValidationResult` with any issues found.
+    """
+def detect_composition_cycles(variable_name: str, new_references: set[str], get_all_references: Callable[[str], set[str]]) -> list[str] | None:
+    """Check if adding *new_references* to *variable_name* would create a cycle.
+
+    Args:
+        variable_name: The variable being updated.
+        new_references: Set of variable names directly referenced by the new value.
+        get_all_references: Function that returns all variable names referenced by
+            any value of the given variable name.
+
+    Returns:
+        The cycle path (e.g., `['A', 'B', 'C', 'A']`) if a cycle is detected,
+        or `None` if no cycle exists.
+    """