lucida-analytics 0.1.0__py3-none-any.whl

lucida/__init__.py

@@ -0,0 +1,72 @@
+"""Lucida server SDK."""
+
+
+from ._ai_config import AiConfig, ai_config
+from ._agent import AgentConversation
+from ._build import BeforeSend, OnError
+from ._context import (
+    DISTINCT_ID_HEADER,
+    SESSION_ID_HEADER,
+    Context,
+    client_ip,
+    get_context,
+    identify_context,
+    new_context,
+    read_tracing_headers,
+    request_context_args,
+    request_properties,
+    scoped,
+    set_context_session,
+    tag,
+)
+from ._core import VERSION as __version__
+from ._core import ImportEvent, LucidaError
+from ._flagcache import FlagDefinitionCacheProvider, InMemoryFlagDefinitionCache
+from ._flagcache_kv import RedisFlagDefinitionCache, RedisLike
+from ._flags import FlagDetails, FlagValue
+from ._snapshot import FlagSnapshot, device_scope, flag_event_props
+from ._global import delegate as _delegate
+from ._global import shutdown as shutdown
+from .aio import AsyncLucida
+from .client import Lucida
+
+# Module-level facade: set these, then call lucida.capture(...) etc. (see README "Global client").
+api_key: str | None = None
+host: str | None = None
+secret_key: str | None = None
+debug: bool | None = None
+disabled: bool | None = None
+flush_at: int | None = None
+flush_interval: float | None = None
+max_batch_size: int | None = None
+before_send: BeforeSend | None = None
+on_error: OnError | None = None
+sync_mode: bool | None = None
+disable_geoip: bool | None = None
+flag_timeout: float | None = None
+default_properties: dict[str, object] | None = None
+timeout: float | None = None
+
+capture = _delegate("capture")
+capture_immediate = _delegate("capture_immediate")
+identify = _delegate("identify")
+alias = _delegate("alias")
+group_identify = _delegate("group_identify")
+flush = _delegate("flush")
+register = _delegate("register")
+unregister = _delegate("unregister")
+get_feature_flag = _delegate("get_feature_flag")
+is_feature_enabled = _delegate("is_feature_enabled")
+get_feature_flag_payload = _delegate("get_feature_flag_payload")
+get_ai_config = _delegate("get_ai_config")
+get_all_flags = _delegate("get_all_flags")
+get_remote_config_payload = _delegate("get_remote_config_payload")
+evaluate_flags = _delegate("evaluate_flags")
+
+__all__: list[str] = [
+    "AgentConversation", "DISTINCT_ID_HEADER", "SESSION_ID_HEADER", "AsyncLucida", "Context", "FlagDefinitionCacheProvider",
+    "FlagDetails", "FlagValue", "ImportEvent", "InMemoryFlagDefinitionCache", "Lucida", "LucidaError", "RedisFlagDefinitionCache", "RedisLike", "__version__",
+    "client_ip", "get_context", "identify_context", "new_context", "read_tracing_headers", "request_context_args", "request_properties",
+    "scoped", "set_context_session", "tag", "shutdown", "FlagSnapshot", "device_scope", "flag_event_props",
+    "AiConfig", "ai_config",
+]  # fmt: skip

lucida/_agent.py

@@ -0,0 +1,257 @@
+"""Agent analytics (P-AGENT): conversation events for in-product AI agents and chatbots.
+
+Product side only: no tokens, latency, cost or model names (Watchtower owns LLM observability). The only
+Watchtower touchpoint is the optional `$ai_trace_id`. Helpers match packages/sdk-core/src/agent.ts and the
+vectors in testdata/agent-analytics/.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+Props = dict[str, Any]
+Emit = Callable[[str, Props], None]
+
+ROLES = ("user", "assistant")
+OUTCOMES = ("resolved", "unresolved", "escalated", "abandoned", "error")
+FEEDBACK_KINDS = ("thumbs", "rating", "comment")
+MAX_TEXT, MAX_COMMENT = 4000, 2000
+
+_TOKEN = re.compile(r"[^\W_]+")
+_TRACE = re.compile(r"[0-9a-f]{32}")
+_PUNCT = re.compile(r"[.,!?;:]")
+_WS = re.compile(r"\s+")
+_FNV_OFFSET, _FNV_PRIME, _MASK = 0xCBF29CE484222325, 0x100000001B3, (1 << 64) - 1
+
+NEG = (
+    "wrong", "useless", "not helpful", "unhelpful", "doesn't work", "does not work", "didn't help",
+    "did not help", "not what i asked", "that's not it", "stupid", "terrible", "awful", "frustrating",
+    "frustrated", "annoying", "worst", "hate", "incorrect", "nonsense", "confusing", "makes no sense",
+    "real person", "human agent", "talk to a human", "speak to a human", "wtf", "ugh",
+)  # fmt: skip
+POS = ("thanks", "thank you", "great", "perfect", "awesome", "helpful", "that worked", "works now", "solved", "exactly")
+
+
+def _fnv1a64(token: str) -> int:
+    h = _FNV_OFFSET
+    for b in token.encode("utf-8"):
+        h = ((h ^ b) * _FNV_PRIME) & _MASK
+    return h
+
+
+def text_hash(text: str) -> str | None:
+    """simhash64 of the lowercased letter/digit tokens (>= 2 code points), 16 hex chars; None without tokens."""
+    tokens = [t for t in _TOKEN.findall(text.lower()) if len(t) >= 2]
+    if not tokens:
+        return None
+    v = [0] * 64
+    for t in tokens:
+        h = _fnv1a64(t)
+        for i in range(64):
+            v[i] += 1 if (h >> i) & 1 else -1
+    out = sum(1 << i for i in range(64) if v[i] > 0)
+    return f"{out:016x}"
+
+
+def sentiment(text: str) -> int:
+    """-1 / 0 / 1 from the shared phrase lexicon (testdata/agent-analytics/lexicon.json)."""
+    norm = _PUNCT.sub(" ", text.lower().replace("’", "'"))
+    padded = " " + _WS.sub(" ", norm).strip() + " "
+    neg = 0
+    for p in NEG:
+        if f" {p} " in padded:
+            neg += 1
+            padded = padded.replace(f" {p} ", " ")
+    pos = sum(1 for p in POS if f" {p} " in padded)
+    return -1 if neg > pos else 1 if pos > neg else 0
+
+
+def _digits(s: str) -> int:
+    return sum(1 for c in s if "0" <= c <= "9")
+
+
+def _luhn(s: str) -> bool:
+    d = [ord(c) - 48 for c in s if "0" <= c <= "9"]
+    if not 13 <= len(d) <= 19:
+        return False
+    total = 0
+    for i, x in enumerate(reversed(d)):
+        total += (x * 2 - 9 if x > 4 else x * 2) if i % 2 == 1 else x
+    return total % 10 == 0
+
+
+# Same detectors, order and replacement as crates/lc-replay/src/mask.rs (the worker re-applies it).
+_RULES: tuple[tuple[re.Pattern[str], Callable[[str], bool]], ...] = (
+    (re.compile(r"\b\d(?:[ -]?\d){12,18}\b"), _luhn),
+    (re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}"), lambda _: True),
+    (re.compile(r"\+?\d[\d\s().-]{7,}\d"), lambda s: 10 <= _digits(s) <= 15),
+)
+
+
+def stars(s: str) -> str:
+    return "".join(c if c.isspace() else "*" for c in s)
+
+
+def redact(text: str) -> str | None:
+    """Masked copy (cards, emails, phones -> `*`, whitespace kept); None when nothing matched."""
+    cur = text
+    for rx, ok in _RULES:
+
+        def mask(m: re.Match[str], ok: Callable[[str], bool] = ok) -> str:
+            return stars(m[0]) if ok(m[0]) else m[0]
+
+        cur = rx.sub(mask, cur)
+    return None if cur == text else cur
+
+
+def trace_id(v: object) -> str | None:
+    """A W3C trace id (32 lowercase hex) or None."""
+    if not isinstance(v, str):
+        return None
+    t = v.lower()
+    return t if _TRACE.fullmatch(t) else None
+
+
+def outcome(v: object) -> str | None:
+    return v if isinstance(v, str) and v in OUTCOMES else None
+
+
+def _label(v: object, n: int) -> str | None:
+    return v[:n] if isinstance(v, str) and v else None
+
+
+def _text_props(key: str, text: str, cap: int) -> Props:
+    masked = redact(text[:cap])
+    return {key: masked if masked is not None else text[:cap], **({"$ai_text_redacted": True} if masked is not None else {})}
+
+
+def message_props(role: str, text: str, index: int, capture_text: bool) -> Props | None:
+    """`$ai_message` props, None for a role other than user/assistant."""
+    if role not in ROLES:
+        return None
+    p: Props = {"$ai_role": role, "$ai_message_index": index, "$ai_text_length": len(text)}
+    if role == "user":
+        h = text_hash(text)
+        if h is not None:
+            p["$ai_text_hash"] = h
+        p["$ai_sentiment"] = sentiment(text)
+    if capture_text:
+        p.update(_text_props("$ai_text", text, MAX_TEXT))
+    return p
+
+
+def feedback_props(
+    kind: str, value: float | None, comment: str | None, message_index: int | None, capture_text: bool
+) -> Props | None:
+    """`$ai_feedback` props, None when kind/value is invalid (thumbs 1|-1, rating integer 1..5)."""
+    if kind == "thumbs" and value not in (1, -1):
+        return None
+    if kind == "rating" and (isinstance(value, bool) or not isinstance(value, (int, float)) or not 1 <= value <= 5 or value != int(value)):
+        return None
+    if kind not in FEEDBACK_KINDS:
+        return None
+    p: Props = {"$ai_feedback_kind": kind}
+    if kind != "comment":
+        p["$ai_feedback_value"] = int(value)  # type: ignore[arg-type]
+    if comment and capture_text:
+        masked = redact(comment[:MAX_COMMENT])
+        p["$ai_feedback_comment"] = masked if masked is not None else comment[:MAX_COMMENT]
+    if message_index is not None:
+        p["$ai_message_index"] = message_index
+    return p
+
+
+def outcome_props(o: str | None, resolution: str | None) -> Props:
+    p: Props = {}
+    if (v := outcome(o)) is not None:
+        p["$ai_outcome"] = v
+    if (r := _label(resolution, 64)) is not None:
+        p["$ai_resolution"] = r
+    return p
+
+
+def common_props(
+    conversation_id: str | None = None,
+    agent_name: str | None = None,
+    agent_version: str | None = None,
+    trace: str | None = None,
+    topic: str | None = None,
+    use_case: str | None = None,
+) -> Props:
+    p: Props = {"$ai_conversation_id": conversation_id or str(uuid.uuid4())}
+    for key, v, n in (("$ai_agent_name", agent_name, 128), ("$ai_agent_version", agent_version, 64),
+                      ("$ai_topic", topic, 128), ("$ai_use_case", use_case, 128)):  # fmt: skip
+        if (s := _label(v, n)) is not None:
+            p[key] = s
+    if (t := trace_id(trace)) is not None:
+        p["$ai_trace_id"] = t
+    return p
+
+
+class AgentConversation:
+    """One agent conversation; every event goes through the client's normal `capture`."""
+
+    def __init__(self, emit: Emit, common: Props, capture_text: bool) -> None:
+        self._emit, self._common, self._capture_text = emit, common, capture_text
+        self._next = 0
+
+    @property
+    def id(self) -> str:
+        return str(self._common["$ai_conversation_id"])
+
+    def _send(self, event: str, props: Props) -> None:
+        self._emit(event, {**self._common, **props})
+
+    def start(self) -> AgentConversation:
+        self._send("$ai_conversation_started", {})
+        return self
+
+    def message(self, role: str, text: str, index: int | None = None) -> bool:
+        """`$ai_message`; the index auto-increments per conversation unless given. False (no event) for a bad role."""
+        i = self._next if index is None else index
+        p = message_props(role, text, i, self._capture_text)
+        if p is None:
+            return False
+        self._next = i + 1
+        self._send("$ai_message", p)
+        return True
+
+    def feedback(
+        self, kind: str, value: float | None = None, comment: str | None = None, message_index: int | None = None
+    ) -> bool:
+        p = feedback_props(kind, value, comment, message_index, self._capture_text)
+        if p is None:
+            return False
+        self._send("$ai_feedback", p)
+        return True
+
+    def end(self, outcome: str | None = None, resolution: str | None = None) -> None:
+        self._send("$ai_conversation_ended", outcome_props(outcome, resolution))
+
+    def outcome(self, outcome: str, resolution: str | None = None) -> bool:
+        """A resolution known later (e.g. the support ticket closed). False (no event) for an unknown outcome."""
+        p = outcome_props(outcome, resolution)
+        if "$ai_outcome" not in p:
+            return False
+        self._send("$ai_outcome", p)
+        return True
+
+
+def start_conversation(
+    capture: Callable[..., None],
+    distinct_id: str | None,
+    capture_text: bool,
+    *,
+    conversation_id: str | None = None,
+    agent_name: str | None = None,
+    agent_version: str | None = None,
+    trace_id: str | None = None,
+    topic: str | None = None,
+    use_case: str | None = None,
+) -> AgentConversation:
+    """Shared by the sync and asyncio clients: `capture(distinct_id, event, props)` is the client's normal capture."""
+    common = common_props(conversation_id, agent_name, agent_version, trace_id, topic, use_case)
+    return AgentConversation(lambda event, props: capture(distinct_id, event, props), common, capture_text).start()

lucida/_ai_config.py

@@ -0,0 +1,65 @@
+"""AI Config flags (LC-FLG-25, P-M49): render the served variation of an `ai_config` flag.
+
+A variation is completion mode (chat ``messages``) or agent mode (``instructions`` plus ``tools``).
+The SDK only selects and renders it; evaluating model output is Watchtower's job. Mirrors
+``packages/sdk-core/src/ai-config.ts``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+_VAR = re.compile(r"\{\{\s*([\w.-]+)\s*\}\}")
+
+
+def _fill(s: str, variables: dict[str, str]) -> str:
+    return _VAR.sub(lambda m: variables.get(m.group(1), m.group(0)), s)
+
+
+@dataclass(frozen=True)
+class AiConfig:
+    """A rendered AI config. ``enabled`` is False when the flag served nothing and this is the fallback."""
+
+    model: str
+    enabled: bool = False
+    mode: str = "completion"
+    provider: str | None = None
+    messages: list[dict[str, str]] = field(default_factory=list)
+    instructions: str | None = None
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    parameters: dict[str, Any] = field(default_factory=dict)
+    variation: str | None = None
+    version: int | None = None
+
+
+def ai_config(variant: str | None, payload: Any, fallback: AiConfig, variables: dict[str, str] | None = None) -> AiConfig:
+    """The config served as ``variant`` with ``payload`` (or ``fallback``), ``{{var}}`` placeholders filled."""
+    v = variables or {}
+    p = payload if isinstance(payload, dict) else None
+    if variant and p is not None and isinstance(p.get("model"), str):
+        msgs = p.get("messages")
+        tools = p.get("tools")
+        instr = p.get("instructions")
+        version = p.get("version")
+        base = AiConfig(
+            model=p["model"],
+            enabled=True,
+            mode="agent" if p.get("mode") == "agent" else "completion",
+            provider=p.get("provider") or None,
+            messages=list(msgs) if isinstance(msgs, list) else [],
+            instructions=instr if isinstance(instr, str) else None,
+            tools=list(tools) if isinstance(tools, list) else [],
+            parameters=dict(p.get("parameters") or {}),
+            variation=variant,
+            version=version if isinstance(version, int) and not isinstance(version, bool) else None,
+        )
+    else:
+        mode = fallback.mode if fallback.mode != "completion" or fallback.instructions is None else "agent"
+        base = replace(fallback, enabled=False, mode=mode)
+    return replace(
+        base,
+        messages=[{"role": m["role"], "content": _fill(m["content"], v)} for m in base.messages],
+        instructions=_fill(base.instructions, v) if base.instructions is not None else None,
+    )

lucida/_build.py

@@ -0,0 +1,104 @@
+"""Event assembly shared by the sync and asyncio clients: context merge, super properties, personless, geoip, before_send."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import uuid as uuidlib
+from collections.abc import Callable, Mapping
+from datetime import datetime
+from typing import Any
+
+from ._context import get_context
+from ._core import LruSet, Props, WireEvent, make_event
+
+IDENTITY_DEDUPE_SIZE = 1000
+
+BeforeSend = Callable[[WireEvent], "WireEvent | None"]
+OnError = Callable[[Exception, "list[WireEvent]"], None]
+
+
+def notify(on_error: OnError | None, err: Exception, events: list[WireEvent]) -> None:
+    """Call the user's error callback; a raising callback must never break delivery."""
+    if on_error is None:
+        return
+    try:
+        on_error(err, events)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+class EventBuilder:
+    def __init__(
+        self,
+        *,
+        before_send: BeforeSend | None = None,
+        on_error: OnError | None = None,
+        disable_geoip: bool = False,
+        is_server: bool = False,
+    ) -> None:
+        self.before_send, self.on_error = before_send, on_error
+        self.disable_geoip = disable_geoip
+        self.super_props: dict[str, Any] = {}
+        self._is_server = is_server
+        self._identities = LruSet(IDENTITY_DEDUPE_SIZE)
+        self._identities_lock = threading.Lock()
+
+    def first_identity(self, *parts: Any) -> bool:
+        """True the first time this exact identify/group call (id + props) is seen in the process (bounded LRU)."""
+        key = hashlib.sha256(json.dumps(parts, sort_keys=True, default=str).encode()).hexdigest()
+        with self._identities_lock:
+            return self._identities.add(key)
+
+    def register(self, properties: Props) -> None:
+        """Client-wide default properties; per-event and context properties override them."""
+        self.super_props.update(properties)
+
+    def unregister(self, key: str) -> None:
+        self.super_props.pop(key, None)
+
+    def build(
+        self,
+        distinct_id: str | None,
+        event: str,
+        properties: Props | None = None,
+        *,
+        groups: Mapping[str, str] | None = None,
+        timestamp: datetime | str | None = None,
+        uuid: str | None = None,
+        set: Props | None = None,  # noqa: A002
+        set_once: Props | None = None,
+        process_person_profile: bool = True,
+        disable_geoip: bool | None = None,
+    ) -> WireEvent | None:
+        """The wire event, or None when `before_send` dropped it. Explicit arguments beat the context."""
+        ctx = get_context()
+        distinct_id = distinct_id or (ctx.distinct_id if ctx else None)
+        if not distinct_id:
+            if process_person_profile:
+                raise ValueError("distinct_id is required (pass one, or use a context with identify_context)")
+            distinct_id = str(uuidlib.uuid4())
+        props: dict[str, Any] = dict(self.super_props)
+        if self._is_server:
+            props["$is_server"] = True
+        if ctx:
+            props.update(ctx.properties)
+            if ctx.session_id:
+                props["$session_id"] = ctx.session_id
+        props.update(properties or {})
+        if not process_person_profile:
+            props["$process_person_profile"] = False
+            set = set_once = None  # noqa: A001 - ignored by the worker on personless events
+        if self.disable_geoip if disable_geoip is None else disable_geoip:
+            props["$geoip_disable"] = True
+        e = make_event(
+            distinct_id, event, props, groups=groups, timestamp=timestamp, uuid=uuid, set=set, set_once=set_once
+        )
+        if self.before_send is None:
+            return e
+        try:
+            return self.before_send(e)
+        except Exception as err:  # noqa: BLE001
+            notify(self.on_error, err, [e])
+            return e  # a raising hook keeps the original event

lucida/_context.py

@@ -0,0 +1,158 @@
+"""Ambient request context on contextvars (works across threads' own contexts and asyncio tasks).
+
+Explicit capture arguments always win over context values. Context properties are merged under the
+event's own properties; `distinct_id` and `$session_id` fill in only when the call gave none.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+import inspect
+import re
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, TypeVar, overload
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+DISTINCT_ID_HEADER = "X-Lucida-Distinct-Id"
+SESSION_ID_HEADER = "X-Lucida-Session-Id"
+_MAX_HEADER = 1000
+_CTRL = re.compile(r"[\x00-\x1f\x7f]")
+
+
+@dataclass
+class Context:
+    distinct_id: str | None = None
+    session_id: str | None = None
+    properties: dict[str, Any] = field(default_factory=dict)
+
+
+_current: contextvars.ContextVar[Context | None] = contextvars.ContextVar("lucida_context", default=None)
+
+
+def get_context() -> Context | None:
+    """The innermost active context, or None."""
+    return _current.get()
+
+
+@contextmanager
+def new_context(
+    *,
+    fresh: bool = False,
+    distinct_id: str | None = None,
+    session_id: str | None = None,
+    properties: Mapping[str, Any] | None = None,
+) -> Iterator[Context]:
+    """Open a context. Nested contexts inherit the parent's values unless `fresh=True`; changes never leak out."""
+    parent = None if fresh else _current.get()
+    ctx = Context(
+        distinct_id if distinct_id is not None else (parent.distinct_id if parent else None),
+        session_id if session_id is not None else (parent.session_id if parent else None),
+        {**(parent.properties if parent else {}), **(properties or {})},
+    )
+    token = _current.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _current.reset(token)
+
+
+@overload
+def scoped(fn: F) -> F: ...
+@overload
+def scoped(*, fresh: bool = ...) -> Callable[[F], F]: ...
+def scoped(fn: F | None = None, *, fresh: bool = False) -> Any:
+    """Decorator: run the function (sync or async) in its own context. `@scoped` or `@scoped(fresh=True)`."""
+
+    def wrap(f: F) -> F:
+        if inspect.iscoroutinefunction(f):
+
+            @functools.wraps(f)
+            async def aw(*a: Any, **k: Any) -> Any:
+                with new_context(fresh=fresh):
+                    return await f(*a, **k)
+
+            return aw  # type: ignore[return-value]
+
+        @functools.wraps(f)
+        def sw(*a: Any, **k: Any) -> Any:
+            with new_context(fresh=fresh):
+                return f(*a, **k)
+
+        return sw  # type: ignore[return-value]
+
+    return wrap(fn) if fn is not None else wrap
+
+
+def tag(key: str, value: Any) -> None:
+    """Add a property to the current context (no-op outside one)."""
+    if (c := _current.get()) is not None:
+        c.properties[key] = value
+
+
+def identify_context(distinct_id: str) -> None:
+    if (c := _current.get()) is not None:
+        c.distinct_id = distinct_id
+
+
+def set_context_session(session_id: str) -> None:
+    if (c := _current.get()) is not None:
+        c.session_id = session_id
+
+
+def clean_header(v: str | None) -> str | None:
+    """Strip ASCII control chars, trim, cap at 1000 chars; empty -> None."""
+    if not v:
+        return None
+    return _CTRL.sub("", v).strip()[:_MAX_HEADER] or None
+
+
+def read_tracing_headers(get: Callable[[str], str | None]) -> tuple[str | None, str | None]:
+    """(distinct_id, session_id) from the browser SDK's tracing headers. `get` looks a header up by name.
+
+    These headers are client-controlled: use them to join events to a browser session, never for authentication.
+    """
+    return clean_header(get(DISTINCT_ID_HEADER)), clean_header(get(SESSION_ID_HEADER))
+
+
+def request_properties(
+    *, url: str | None, method: str | None, path: str | None, user_agent: str | None, ip: str | None
+) -> dict[str, Any]:
+    """The request props middleware stamps on the context (absent values are left out)."""
+    raw = {"$current_url": url, "$request_method": method, "$request_path": path, "$user_agent": user_agent, "$ip": ip}
+    return {k: v for k, v in raw.items() if v}
+
+
+def client_ip(remote_addr: str | None, forwarded_for: str | None, trust_proxy: bool) -> str | None:
+    """First X-Forwarded-For entry only when `trust_proxy`; else the socket peer."""
+    if trust_proxy and forwarded_for:
+        first = forwarded_for.split(",")[0].strip()
+        if first:
+            return first
+    return remote_addr
+
+
+def request_context_args(
+    get_header: Callable[[str], str | None],
+    *,
+    method: str | None,
+    url: str | None,
+    path: str | None,
+    remote_addr: str | None,
+    trust_proxy: bool = False,
+    capture_tracing_headers: bool = True,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Keyword arguments for `new_context(fresh=True, **args)`: tracing-header ids plus the stamped request props."""
+    did, sid = read_tracing_headers(get_header) if capture_tracing_headers else (None, None)
+    props = request_properties(
+        url=url,
+        method=method,
+        path=path,
+        user_agent=clean_header(get_header("User-Agent")),
+        ip=client_ip(remote_addr, get_header("X-Forwarded-For"), trust_proxy),
+    )
+    return {"distinct_id": did, "session_id": sid, "properties": {**props, **(extra or {})}}