spanlight 0.1.0__py3-none-any.whl

spanlight/_serialize.py

@@ -0,0 +1,126 @@
+"""Best-effort conversion of arbitrary Python values into JSON-compatible data.
+
+Captured inputs and outputs can be anything: pydantic models returned by
+provider SDKs, dataclasses, custom objects, huge strings. This module turns
+them into plain ``dict``/``list``/``str``/number values that ``json.dumps`` can
+always encode, while bounding size and depth so a single span can never
+produce an unreasonably large payload. It never raises.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+import enum
+import math
+import uuid
+from collections.abc import Mapping
+from typing import Any
+
+MAX_DEPTH = 12
+MAX_STRING_LENGTH = 32_000
+MAX_ITEMS = 1_000
+
+_TRUNCATION_MARKER = "...[truncated]"
+
+JsonValue = Any
+"""Alias documenting that a value is JSON-compatible (recursive types are awkward)."""
+
+
+def to_jsonable(value: Any) -> JsonValue:
+    """Convert ``value`` into a JSON-compatible structure.
+
+    Args:
+        value: Any Python object.
+
+    Returns:
+        A value composed only of ``dict``, ``list``, ``str``, ``int``,
+        ``float``, ``bool`` and ``None``. Unknown objects are rendered with
+        ``repr``. Oversized strings and collections are truncated.
+    """
+    try:
+        return _convert(value, depth=0)
+    except Exception:
+        return _truncate_string(_safe_repr(value))
+
+
+def _convert(value: Any, depth: int) -> JsonValue:
+    if value is None or isinstance(value, bool | int):
+        return value
+    if isinstance(value, float):
+        return value if math.isfinite(value) else str(value)
+    if isinstance(value, str):
+        return _truncate_string(value)
+    if depth >= MAX_DEPTH:
+        return "[max depth reached]"
+
+    if isinstance(value, Mapping):
+        return _convert_mapping(value, depth)
+    if isinstance(value, list | tuple | set | frozenset):
+        return _convert_sequence(list(value), depth)
+    if isinstance(value, bytes | bytearray | memoryview):
+        return f"<{len(value)} bytes>"
+    if isinstance(value, enum.Enum):
+        return _convert(value.value, depth + 1)
+    if isinstance(value, dt.datetime | dt.date | dt.time):
+        return value.isoformat()
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, BaseException):
+        return {"type": type(value).__name__, "message": _truncate_string(str(value))}
+
+    dumped = _dump_model(value)
+    if dumped is not None:
+        return _convert(dumped, depth + 1)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        fields = {field.name: getattr(value, field.name) for field in dataclasses.fields(value)}
+        return _convert_mapping(fields, depth)
+
+    return _truncate_string(_safe_repr(value))
+
+
+def _convert_mapping(value: Mapping[Any, Any], depth: int) -> dict[str, JsonValue]:
+    result: dict[str, JsonValue] = {}
+    for index, (key, item) in enumerate(value.items()):
+        if index >= MAX_ITEMS:
+            result["..."] = f"{len(value) - MAX_ITEMS} more keys truncated"
+            break
+        result[str(key)] = _convert(item, depth + 1)
+    return result
+
+
+def _convert_sequence(items: list[Any], depth: int) -> list[JsonValue]:
+    converted = [_convert(item, depth + 1) for item in items[:MAX_ITEMS]]
+    if len(items) > MAX_ITEMS:
+        converted.append(f"... {len(items) - MAX_ITEMS} more items truncated")
+    return converted
+
+
+def _dump_model(value: Any) -> Any | None:
+    """Return a plain representation of pydantic (v2 or v1) models, else ``None``."""
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        try:
+            return model_dump(mode="json", exclude_none=True)
+        except Exception:
+            return None
+    legacy_dict = getattr(value, "dict", None)
+    if callable(legacy_dict) and hasattr(value, "__fields__"):
+        try:
+            return legacy_dict()
+        except Exception:
+            return None
+    return None
+
+
+def _truncate_string(value: str) -> str:
+    if len(value) <= MAX_STRING_LENGTH:
+        return value
+    return value[:MAX_STRING_LENGTH] + _TRUNCATION_MARKER
+
+
+def _safe_repr(value: Any) -> str:
+    try:
+        return repr(value)
+    except Exception:
+        return f"<unrepresentable {type(value).__name__}>"

spanlight/_span.py

@@ -0,0 +1,337 @@
+"""Span and trace data structures.
+
+A :class:`Span` is a timed unit of work (an LLM call, a tool invocation, a
+whole request). Spans that share a :class:`TraceState` form one trace; the
+trace state carries trace-level fields such as ``user_id`` and ``session_id``
+that are attached to every span when it is exported.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import logging
+import re
+import threading
+import time
+import uuid
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any, Literal, get_args
+
+from ._ids import new_span_id, new_trace_id
+from ._serialize import JsonValue, to_jsonable
+
+logger = logging.getLogger("spanlight")
+
+SpanKind = Literal["llm", "tool", "retrieval", "chain", "http", "other"]
+SpanStatus = Literal["ok", "error", "unset"]
+
+_VALID_KINDS: frozenset[str] = frozenset(get_args(SpanKind))
+_MAX_STATUS_MESSAGE = 2_000
+_MAX_FINISH_REASON = 64
+_REQUEST_HASH_PATTERN = re.compile(r"[0-9a-f]{32}")
+
+
+def normalize_kind(kind: str) -> SpanKind:
+    """Return ``kind`` if it is a known span kind, otherwise ``"other"``."""
+    if kind in _VALID_KINDS:
+        return kind  # type: ignore[return-value]
+    logger.debug("Unknown span kind %r; using 'other'", kind)
+    return "other"
+
+
+def _isoformat_ns(epoch_ns: int) -> str:
+    seconds, nanos = divmod(epoch_ns, 1_000_000_000)
+    moment = dt.datetime.fromtimestamp(seconds, tz=dt.timezone.utc)
+    moment = moment.replace(microsecond=nanos // 1_000)
+    return moment.isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+class TraceState:
+    """Mutable trace-level fields shared by every span of one trace.
+
+    Instances are shared by reference between parent and child spans
+    (including children running in other asyncio tasks), so an
+    :func:`~spanlight.update_trace` call anywhere in the trace is
+    visible to every span exported afterwards.
+    """
+
+    def __init__(
+        self,
+        *,
+        trace_id: str | None = None,
+        name: str | None = None,
+        environment: str | None = None,
+        release: str | None = None,
+    ) -> None:
+        self.trace_id = trace_id or new_trace_id()
+        self.name = name
+        self.environment = environment
+        self.release = release
+        self.user_id: str | None = None
+        self.session_id: str | None = None
+        self.tags: list[str] = []
+        self._lock = threading.Lock()
+
+    def update(
+        self,
+        *,
+        name: str | None = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        tags: Iterable[str] | None = None,
+    ) -> None:
+        """Set trace-level fields. ``None`` leaves a field unchanged; tags accumulate."""
+        with self._lock:
+            if name is not None:
+                self.name = name
+            if user_id is not None:
+                self.user_id = user_id
+            if session_id is not None:
+                self.session_id = session_id
+            if tags is not None:
+                for tag in tags:
+                    if tag not in self.tags:
+                        self.tags.append(str(tag))
+
+    def to_payload(self) -> dict[str, JsonValue]:
+        """Return the ``trace`` object of the ingestion payload."""
+        with self._lock:
+            return {
+                "name": self.name,
+                "environment": self.environment,
+                "release": self.release,
+                "user_id": self.user_id,
+                "session_id": self.session_id,
+                "tags": list(self.tags),
+            }
+
+
+class Span:
+    """A single timed operation within a trace.
+
+    Spans are created by :meth:`Spanlight.span <spanlight.Spanlight.span>`,
+    the :func:`~spanlight.observe` decorator and the provider
+    wrappers; you normally receive one rather than constructing it. All
+    setters are safe to call at any time and never raise. Calls made after
+    the span has ended are ignored.
+
+    A span created while the SDK is disabled is *non-recording*: every method
+    is a cheap no-op.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        kind: SpanKind,
+        trace: TraceState,
+        parent_span_id: str | None,
+        on_end: Callable[[Span], None] | None,
+        recording: bool = True,
+    ) -> None:
+        self.name = name
+        self.kind = kind
+        self.trace = trace
+        self.span_id = new_span_id()
+        self.parent_span_id = parent_span_id
+        self.recording = recording
+
+        self.status: SpanStatus = "unset"
+        self.status_message: str | None = None
+        self.provider: str | None = None
+        self.model: str | None = None
+        self.input_tokens: int | None = None
+        self.output_tokens: int | None = None
+        self.cached_tokens: int | None = None
+        self.time_to_first_token_ms: float | None = None
+        self.request_hash: str | None = None
+        self.finish_reason: str | None = None
+        self.prompt_version_id: str | None = None
+        self.input: JsonValue = None
+        self.output: JsonValue = None
+        self.attributes: dict[str, JsonValue] = {}
+
+        self._on_end = on_end
+        self._start_epoch_ns = time.time_ns()
+        self._start_perf_ns = time.perf_counter_ns()
+        self._end_epoch_ns: int | None = None
+        self._end_lock = threading.Lock()
+
+    @property
+    def trace_id(self) -> str:
+        """The 32-hex-character id of the trace this span belongs to."""
+        return self.trace.trace_id
+
+    @property
+    def is_ended(self) -> bool:
+        """Whether :meth:`end` has already been called."""
+        return self._end_epoch_ns is not None
+
+    @property
+    def _mutable(self) -> bool:
+        return self.recording and not self.is_ended
+
+    def set_input(self, value: Any) -> None:
+        """Record the operation's input (any JSON-serializable-ish value)."""
+        if self._mutable:
+            self.input = to_jsonable(value)
+
+    def set_output(self, value: Any) -> None:
+        """Record the operation's output (any JSON-serializable-ish value)."""
+        if self._mutable:
+            self.output = to_jsonable(value)
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Attach a single custom attribute."""
+        if self._mutable:
+            self.attributes[str(key)] = to_jsonable(value)
+
+    def set_attributes(self, attributes: Mapping[str, Any]) -> None:
+        """Attach several custom attributes at once."""
+        for key, value in attributes.items():
+            self.set_attribute(key, value)
+
+    def set_model(self, model: str | None, *, provider: str | None = None) -> None:
+        """Record the model (and optionally the provider) that served the call."""
+        if not self._mutable:
+            return
+        if model:
+            self.model = str(model)
+        if provider:
+            self.provider = str(provider)
+
+    def set_usage(
+        self,
+        *,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        cached_tokens: int | None = None,
+    ) -> None:
+        """Record token usage. ``None`` leaves the existing value unchanged.
+
+        ``input_tokens`` is the *total* prompt size, including any cached
+        tokens; ``cached_tokens`` is the subset served from the prompt cache.
+        """
+        if not self._mutable:
+            return
+        if input_tokens is not None:
+            self.input_tokens = int(input_tokens)
+        if output_tokens is not None:
+            self.output_tokens = int(output_tokens)
+        if cached_tokens is not None:
+            self.cached_tokens = int(cached_tokens)
+
+    def set_request_hash(self, value: str | None) -> None:
+        """Record the request hash used to group identical calls.
+
+        Provider wrappers set this automatically. A value that is not 32
+        lowercase hex characters is ignored, because the server would reject
+        the whole batch.
+        """
+        if not self._mutable:
+            return
+        if value is None or (isinstance(value, str) and _REQUEST_HASH_PATTERN.fullmatch(value)):
+            self.request_hash = value
+        else:
+            logger.debug("Ignoring malformed request hash %r", value)
+
+    def set_finish_reason(self, reason: str | None) -> None:
+        """Record why generation stopped, exactly as the provider reports it."""
+        if self._mutable and (reason is None or isinstance(reason, str)):
+            self.finish_reason = reason[:_MAX_FINISH_REASON] if reason else None
+
+    def set_prompt_version(self, version_id: str | None) -> None:
+        """Link the span to the prompt version it used; ``None`` removes the link.
+
+        :class:`~spanlight.CompiledPrompt` does this for you. A value that is
+        not a UUID is ignored, because the server would reject the span.
+        """
+        if not self._mutable:
+            return
+        if version_id is None:
+            self.prompt_version_id = None
+            return
+        try:
+            self.prompt_version_id = str(uuid.UUID(str(version_id)))
+        except ValueError:
+            logger.debug("Ignoring malformed prompt version id %r", version_id)
+
+    def mark_first_token(self) -> None:
+        """Record time-to-first-token as "now"; only the first call counts."""
+        if self._mutable and self.time_to_first_token_ms is None:
+            elapsed_ns = time.perf_counter_ns() - self._start_perf_ns
+            self.time_to_first_token_ms = elapsed_ns / 1_000_000
+
+    def record_error(self, error: BaseException | str) -> None:
+        """Mark the span as failed.
+
+        Args:
+            error: The exception that occurred, or a human-readable message.
+        """
+        if not self._mutable:
+            return
+        self.status = "error"
+        if isinstance(error, BaseException):
+            message = str(error) or type(error).__name__
+            self.attributes["error.type"] = type(error).__name__
+        else:
+            message = error
+        self.status_message = message[:_MAX_STATUS_MESSAGE]
+
+    def end(self) -> None:
+        """Finish the span and hand it to the exporter. Idempotent."""
+        with self._end_lock:
+            if self._end_epoch_ns is not None:
+                return
+            elapsed_ns = time.perf_counter_ns() - self._start_perf_ns
+            self._end_epoch_ns = self._start_epoch_ns + elapsed_ns
+        if self.status == "unset":
+            self.status = "ok"
+        if self.recording and self._on_end is not None:
+            try:
+                self._on_end(self)
+            except Exception:
+                logger.debug("Failed to export span %s", self.span_id, exc_info=True)
+
+    def to_payload(self) -> dict[str, JsonValue]:
+        """Serialize the span into the ``POST /v1/traces`` span schema."""
+        end_ns = self._end_epoch_ns if self._end_epoch_ns is not None else time.time_ns()
+        usage: dict[str, int] | None = None
+        token_counts = {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cached_tokens": self.cached_tokens,
+        }
+        if any(count is not None for count in token_counts.values()):
+            usage = {key: count for key, count in token_counts.items() if count is not None}
+        payload: dict[str, JsonValue] = {
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+            "parent_span_id": self.parent_span_id,
+            "name": self.name,
+            "kind": self.kind,
+            "status": self.status,
+            "status_message": self.status_message,
+            "start_time": _isoformat_ns(self._start_epoch_ns),
+            "end_time": _isoformat_ns(end_ns),
+            "provider": self.provider,
+            "model": self.model,
+            "usage": usage,
+            "time_to_first_token_ms": self.time_to_first_token_ms,
+            "request_hash": self.request_hash,
+            "finish_reason": self.finish_reason,
+            "input": self.input,
+            "output": self.output,
+            "attributes": dict(self.attributes),
+            "trace": self.trace.to_payload(),
+        }
+        # Sent only when set, so payloads for servers that predate prompts stay unchanged.
+        if self.prompt_version_id is not None:
+            payload["prompt_version_id"] = self.prompt_version_id
+        return payload
+
+    def __repr__(self) -> str:
+        return (
+            f"Span(name={self.name!r}, kind={self.kind!r}, trace_id={self.trace_id!r}, "
+            f"span_id={self.span_id!r}, status={self.status!r})"
+        )

spanlight/_templates.py

@@ -0,0 +1,238 @@
+"""Prompt template compiler: ``{{name}}`` substitution, pure and engine-free.
+
+These are the same rules the Spanlight server and dashboard apply, checked against one shared
+fixture file. A variable is ``{{name}}`` with optional spaces or tabs inside the braces; values
+are inserted verbatim and never re-expanded. There are no sections, escapes or partials. The
+rendered output is capped at 256 KB (UTF-8, the text or all messages together).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+MAX_TEMPLATE_BYTES = 64 * 1024
+MAX_CHAT_MESSAGES = 50
+# Bound on the rendered output (text, or the sum of every message), in UTF-8 bytes. Without it a
+# small template that repeats a large variable could render hundreds of megabytes.
+MAX_COMPILED_BYTES = 256 * 1024
+
+Role = Literal["system", "user", "assistant"]
+Kind = Literal["text", "chat"]
+
+_ROLES: frozenset[str] = frozenset({"system", "user", "assistant"})
+_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,63}")
+# A closed `{{ ... }}` on one line (inner text may be anything), or a lone `{{` that never closes.
+_TOKEN = re.compile(r"\{\{(?P<inner>[^\n]*?)\}\}|\{\{")
+
+
+class InvalidTemplateError(ValueError):
+    """The template is malformed (bad braces, bad name, wrong shape or too large)."""
+
+
+class MissingVariablesError(ValueError):
+    """``compile`` was called without every variable the template uses.
+
+    Attributes:
+        names: Every missing variable name, sorted.
+    """
+
+    def __init__(self, names: tuple[str, ...]) -> None:
+        super().__init__(f"missing variables: {', '.join(names)}")
+        self.names = names
+
+
+class TemplateTooLargeError(ValueError):
+    """The rendered output would exceed ``MAX_COMPILED_BYTES`` (256 KB) with the variables in."""
+
+    def __init__(self) -> None:
+        super().__init__(f"compiled prompt exceeds {MAX_COMPILED_BYTES} bytes")
+
+
+@dataclass(frozen=True)
+class Message:
+    """One message of a chat template."""
+
+    role: Role
+    content: str
+
+
+@dataclass(frozen=True)
+class Template:
+    """A text template (``text``) or a chat template (``messages``)."""
+
+    kind: Kind
+    text: str | None = None
+    messages: tuple[Message, ...] | None = None
+
+
+@dataclass(frozen=True)
+class RenderedTemplate:
+    """The result of :func:`compile`."""
+
+    kind: Kind
+    text: str | None
+    messages: tuple[Message, ...] | None
+    variables_used: tuple[str, ...]
+    unused_variables: tuple[str, ...]
+
+
+# A scanned piece of a template: literal text, or a variable reference when `name` is set.
+@dataclass(frozen=True)
+class _Part:
+    literal: str
+    name: str | None = None
+
+
+def _position(source: str, offset: int) -> str:
+    line = source.count("\n", 0, offset) + 1
+    column = offset - (source.rfind("\n", 0, offset) + 1) + 1
+    return f"line {line}, column {column}"
+
+
+def _scan(source: str) -> list[_Part]:
+    parts: list[_Part] = []
+    cursor = 0
+    for match in _TOKEN.finditer(source):
+        if match.start() > cursor:
+            parts.append(_Part(source[cursor : match.start()]))
+        inner = match.group("inner")
+        if inner is None:
+            raise InvalidTemplateError(f"unclosed '{{{{' at {_position(source, match.start())}")
+        name = inner.strip(" \t")
+        if not _NAME.fullmatch(name):
+            raise InvalidTemplateError(
+                f"invalid variable name at {_position(source, match.start())}"
+            )
+        parts.append(_Part("", name))
+        cursor = match.end()
+    if cursor < len(source):
+        parts.append(_Part(source[cursor:]))
+    return parts
+
+
+def _sources(template: Template) -> list[str]:
+    """Validate the template's shape and bounds, and return its text blocks in order."""
+    if template.kind == "text":
+        if template.text is None or template.messages is not None:
+            raise InvalidTemplateError("a text template needs `text` and no `messages`")
+        blocks = [template.text]
+    elif template.kind == "chat":
+        if template.messages is None or template.text is not None:
+            raise InvalidTemplateError("a chat template needs `messages` and no `text`")
+        if not 1 <= len(template.messages) <= MAX_CHAT_MESSAGES:
+            raise InvalidTemplateError(f"a chat template needs 1 to {MAX_CHAT_MESSAGES} messages")
+        blocks = [message.content for message in template.messages]
+    else:
+        raise InvalidTemplateError(f"unknown template kind: {template.kind!r}")
+    if sum(len(block.encode("utf-8")) for block in blocks) > MAX_TEMPLATE_BYTES:
+        raise InvalidTemplateError(f"template exceeds {MAX_TEMPLATE_BYTES} bytes")
+    return blocks
+
+
+def _ordered_unique(parts_per_block: list[list[_Part]]) -> list[str]:
+    seen: dict[str, None] = {}
+    for parts in parts_per_block:
+        for part in parts:
+            if part.name is not None:
+                seen.setdefault(part.name)
+    return list(seen)
+
+
+def extract_variables(template: Template) -> tuple[str, ...]:
+    """Variable names in first-appearance order, de-duplicated."""
+    return tuple(_ordered_unique([_scan(block) for block in _sources(template)]))
+
+
+def _check_size(parts_per_block: list[list[_Part]], variables: Mapping[str, str]) -> None:
+    """Raise `TemplateTooLargeError` before rendering when the output would pass the cap."""
+    sizes: dict[str, int] = {}
+    total = 0
+    for parts in parts_per_block:
+        for part in parts:
+            if part.name is None:
+                total += len(part.literal.encode("utf-8"))
+            else:
+                if part.name not in sizes:
+                    sizes[part.name] = len(variables[part.name].encode("utf-8"))
+                total += sizes[part.name]
+            if total > MAX_COMPILED_BYTES:
+                raise TemplateTooLargeError()
+
+
+def _render(parts: list[_Part], variables: Mapping[str, str]) -> str:
+    return "".join(
+        variables[part.name] if part.name is not None else part.literal for part in parts
+    )
+
+
+def compile(template: Template, variables: Mapping[str, str]) -> RenderedTemplate:
+    """Substitute ``variables`` into ``template``.
+
+    Raises:
+        InvalidTemplateError: The template is malformed.
+        MissingVariablesError: A variable the template uses was not given.
+        TemplateTooLargeError: The rendered output would exceed 256 KB (UTF-8, the text or all
+            messages together).
+    """
+    scanned = [_scan(block) for block in _sources(template)]
+    used = _ordered_unique(scanned)
+    missing = tuple(sorted(name for name in used if name not in variables))
+    if missing:
+        raise MissingVariablesError(missing)
+    unused = tuple(sorted(name for name in variables if name not in used))
+    _check_size(scanned, variables)
+    if template.kind == "text":
+        return RenderedTemplate("text", _render(scanned[0], variables), None, tuple(used), unused)
+    assert template.messages is not None  # narrowed by _sources
+    messages = tuple(
+        Message(message.role, _render(parts, variables))
+        for message, parts in zip(template.messages, scanned, strict=True)
+    )
+    return RenderedTemplate("chat", None, messages, tuple(used), unused)
+
+
+def template_from_wire(raw: Any) -> Template:
+    """Build a :class:`Template` from its JSON form.
+
+    The JSON form is ``{"kind": "text", "text": ...}`` or
+    ``{"kind": "chat", "messages": [{"role": ..., "content": ...}, ...]}``.
+
+    Raises:
+        InvalidTemplateError: ``raw`` does not have that shape.
+    """
+    if not isinstance(raw, Mapping):
+        raise InvalidTemplateError("a template must be a JSON object")
+    kind = raw.get("kind")
+    if kind == "text":
+        text = raw.get("text")
+        if not isinstance(text, str) or raw.get("messages") is not None:
+            raise InvalidTemplateError("a text template needs a string `text` and no `messages`")
+        return Template("text", text=text)
+    if kind == "chat":
+        if raw.get("text") is not None:
+            raise InvalidTemplateError("a chat template needs `messages` and no `text`")
+        return Template("chat", messages=messages_from_wire(raw.get("messages")))
+    raise InvalidTemplateError(f"unknown template kind: {kind!r}")
+
+
+def messages_from_wire(raw: Any) -> tuple[Message, ...]:
+    """Build chat messages from a list of ``{"role", "content"}`` objects.
+
+    Raises:
+        InvalidTemplateError: An item is not a message with a known role and string content.
+    """
+    if not isinstance(raw, list | tuple):
+        raise InvalidTemplateError("a chat template needs a list of `messages`")
+    messages: list[Message] = []
+    for index, item in enumerate(raw):
+        role = item.get("role") if isinstance(item, Mapping) else None
+        content = item.get("content") if isinstance(item, Mapping) else None
+        if role not in _ROLES or not isinstance(content, str):
+            raise InvalidTemplateError(
+                f"message {index} needs a role of system, user or assistant and string content"
+            )
+        messages.append(Message(role, content))
+    return tuple(messages)