flowspec2 1.0.0__py3-none-any.whl

flowspec2/observability.py

@@ -0,0 +1,151 @@
+"""Snowflake correlation IDs and structured logging helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import socket
+import time
+from collections.abc import Callable, Mapping
+from threading import Lock
+
+SNOWFLAKE_EPOCH_MILLISECONDS = 1_704_067_200_000
+SNOWFLAKE_TIMESTAMP_BITS = 41
+SNOWFLAKE_WORKER_BITS = 10
+SNOWFLAKE_SEQUENCE_BITS = 12
+SNOWFLAKE_MAX_WORKER_ID = (1 << SNOWFLAKE_WORKER_BITS) - 1
+SNOWFLAKE_MAX_SEQUENCE = (1 << SNOWFLAKE_SEQUENCE_BITS) - 1
+SNOWFLAKE_MAX_TIMESTAMP_DELTA = (1 << SNOWFLAKE_TIMESTAMP_BITS) - 1
+SNOWFLAKE_WORKER_SHIFT = SNOWFLAKE_SEQUENCE_BITS
+SNOWFLAKE_TIMESTAMP_SHIFT = SNOWFLAKE_WORKER_BITS + SNOWFLAKE_SEQUENCE_BITS
+
+ClockMilliseconds = Callable[[], int]
+_LOG_RECORD_RESERVED_FIELDS = frozenset(logging.makeLogRecord({}).__dict__) | {
+    "asctime",
+    "log_id",
+    "message",
+    "operation",
+}
+
+
+def _system_clock_milliseconds() -> int:
+    return time.time_ns() // 1_000_000
+
+
+class SnowflakeIdGenerator:
+    """Generate ordered decimal Snowflake IDs with an injectable clock."""
+
+    def __init__(
+        self,
+        *,
+        worker_id: int,
+        clock_milliseconds: ClockMilliseconds = _system_clock_milliseconds,
+        epoch_milliseconds: int = SNOWFLAKE_EPOCH_MILLISECONDS,
+    ) -> None:
+        if isinstance(worker_id, bool) or not 0 <= worker_id <= SNOWFLAKE_MAX_WORKER_ID:
+            raise ValueError(
+                f"worker_id must be between 0 and {SNOWFLAKE_MAX_WORKER_ID}, got {worker_id!r}"
+            )
+        if isinstance(epoch_milliseconds, bool) or epoch_milliseconds < 0:
+            raise ValueError("epoch_milliseconds must be a non-negative integer")
+        self.worker_id = worker_id
+        self._clock_milliseconds = clock_milliseconds
+        self._epoch_milliseconds = epoch_milliseconds
+        self._last_timestamp_milliseconds: int | None = None
+        self._sequence = 0
+        self._lock = Lock()
+
+    def generate(self) -> str:
+        """Return the next ID, advancing logical time across clock rollback or saturation."""
+
+        with self._lock:
+            clock_timestamp = self._clock_milliseconds()
+            if isinstance(clock_timestamp, bool) or not isinstance(clock_timestamp, int):
+                raise TypeError("clock_milliseconds must return an integer")
+            if clock_timestamp < self._epoch_milliseconds:
+                raise ValueError("clock timestamp precedes the configured Snowflake epoch")
+
+            last_timestamp = self._last_timestamp_milliseconds
+            logical_timestamp = (
+                clock_timestamp if last_timestamp is None else max(clock_timestamp, last_timestamp)
+            )
+            if last_timestamp is not None and logical_timestamp == last_timestamp:
+                self._sequence += 1
+                if self._sequence > SNOWFLAKE_MAX_SEQUENCE:
+                    logical_timestamp += 1
+                    self._sequence = 0
+            else:
+                self._sequence = 0
+
+            timestamp_delta = logical_timestamp - self._epoch_milliseconds
+            if timestamp_delta > SNOWFLAKE_MAX_TIMESTAMP_DELTA:
+                raise OverflowError("Snowflake timestamp exceeds the configured bit allocation")
+
+            self._last_timestamp_milliseconds = logical_timestamp
+            snowflake_id = (
+                (timestamp_delta << SNOWFLAKE_TIMESTAMP_SHIFT)
+                | (self.worker_id << SNOWFLAKE_WORKER_SHIFT)
+                | self._sequence
+            )
+            return str(snowflake_id)
+
+
+def _configured_worker_id() -> int:
+    configured_worker_id = os.environ.get("FLOWSPEC2_SNOWFLAKE_WORKER_ID")
+    if configured_worker_id is not None:
+        try:
+            worker_id = int(configured_worker_id)
+        except ValueError as error:
+            raise ValueError("FLOWSPEC2_SNOWFLAKE_WORKER_ID must be an integer") from error
+        if not 0 <= worker_id <= SNOWFLAKE_MAX_WORKER_ID:
+            raise ValueError("FLOWSPEC2_SNOWFLAKE_WORKER_ID is outside the supported worker range")
+        return worker_id
+
+    process_identity = f"{socket.gethostname()}:{os.getpid()}".encode("utf-8")
+    identity_digest = hashlib.blake2s(process_identity, digest_size=2).digest()
+    return int.from_bytes(identity_digest, byteorder="big") & SNOWFLAKE_MAX_WORKER_ID
+
+
+_default_generator_lock = Lock()
+_default_generator_process_id: int | None = None
+_default_generator: SnowflakeIdGenerator | None = None
+
+
+def default_log_id_generator() -> SnowflakeIdGenerator:
+    """Return the process-local generator, recreating it after a process fork."""
+
+    global _default_generator
+    global _default_generator_process_id
+
+    process_id = os.getpid()
+    with _default_generator_lock:
+        if _default_generator is None or _default_generator_process_id != process_id:
+            _default_generator = SnowflakeIdGenerator(worker_id=_configured_worker_id())
+            _default_generator_process_id = process_id
+        return _default_generator
+
+
+def log_event(
+    logger: logging.Logger,
+    level: int,
+    message: str,
+    *,
+    operation: str,
+    log_id_generator: SnowflakeIdGenerator | None = None,
+    context: Mapping[str, object] | None = None,
+    exc_info: bool = False,
+) -> str:
+    """Emit one structured event and return its correlation ID."""
+
+    if context:
+        conflicting_fields = _LOG_RECORD_RESERVED_FIELDS.intersection(context)
+        if conflicting_fields:
+            conflicts = ", ".join(sorted(conflicting_fields))
+            raise ValueError(f"logging context cannot override reserved fields: {conflicts}")
+    log_id = (log_id_generator or default_log_id_generator()).generate()
+    extra: dict[str, object] = {"log_id": log_id, "operation": operation}
+    if context:
+        extra.update(context)
+    logger.log(level, message, extra=extra, exc_info=exc_info)
+    return log_id

flowspec2/predicates.py

@@ -0,0 +1,89 @@
+"""The frozen object-form predicate grammar.
+
+A predicate is a single-key object over five read-only namespaces. There is no
+string sugar and no arbitrary computation — every gate, ``ask_when``,
+``send_when`` and correction route compiles to a call to :func:`evaluate`, which
+is a pure boolean function over ``ServiceState`` + the flow ``config`` block.
+
+Grammar (one operator per object)::
+
+    {"in":  ["slots.x", ["a", "b"]]}      # resolved(x) in the literal list
+    {"eq":  ["slots.x", "literal"]}       # resolved(x) == literal (either side may be a ref)
+    {"eq":  ["slots.x", {"literal": "config.flag"}]}  # namespaced literal
+    {"ne":  ["slots.x", "literal"]}
+    {"is_present": "slots.x"}              # filled and non-null/non-empty
+    {"and": [<pred>, ...]}
+    {"or":  [<pred>, ...]}
+    {"not": <pred>}
+
+Namespaces: ``slots.`` (state.data), ``internal.`` (state.internal),
+``payload.`` (state.payload), ``config.`` (the flow config block),
+``address.`` (state.data["address"]).
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeGuard
+
+from .models import ServiceState
+
+NAMESPACES = ("slots", "internal", "payload", "config", "address")
+
+
+def _is_ref(value: Any) -> TypeGuard[str]:
+    return isinstance(value, str) and "." in value and value.split(".", 1)[0] in NAMESPACES
+
+
+def _resolve(ref: str, state: ServiceState, config: dict[str, Any]) -> Any:
+    ns, key = ref.split(".", 1)
+    if ns == "slots":
+        return state.data.get(key)
+    if ns == "internal":
+        return state.internal.get(key)
+    if ns == "payload":
+        return state.payload.get(key)
+    if ns == "config":
+        return config.get(key)
+    if ns == "address":
+        resolved: Any = state.data.get("address") or {}
+        for path_segment in key.split("."):
+            if not isinstance(resolved, dict) or path_segment not in resolved:
+                return None
+            resolved = resolved[path_segment]
+        return resolved
+    raise ValueError(f"unknown predicate namespace: {ns!r}")
+
+
+def _operand(value: Any, state: ServiceState, config: dict[str, Any]) -> Any:
+    """Resolve namespaced strings and unwrap explicit ambiguous literals."""
+    if isinstance(value, dict) and set(value) == {"literal"}:
+        return value["literal"]
+    return _resolve(value, state, config) if _is_ref(value) else value
+
+
+def evaluate(pred: dict[str, Any], state: ServiceState, config: dict[str, Any]) -> bool:
+    """Evaluate a predicate against state + config. Pure, side-effect free."""
+    if not isinstance(pred, dict) or len(pred) != 1:
+        raise ValueError(f"predicate must be a single-key object, got {pred!r}")
+    ((op, val),) = pred.items()
+
+    if op == "in":
+        ref, options = val
+        return _operand(ref, state, config) in options
+    if op == "eq":
+        left, right = val
+        return bool(_operand(left, state, config) == _operand(right, state, config))
+    if op == "ne":
+        left, right = val
+        return bool(_operand(left, state, config) != _operand(right, state, config))
+    if op == "is_present":
+        resolved = _resolve(val, state, config)
+        return resolved is not None and resolved != ""
+    if op == "and":
+        return all(evaluate(p, state, config) for p in val)
+    if op == "or":
+        return any(evaluate(p, state, config) for p in val)
+    if op == "not":
+        return not evaluate(val, state, config)
+
+    raise ValueError(f"unknown predicate operator: {op!r}")

flowspec2/profiles.py

@@ -0,0 +1,118 @@
+"""Runtime profiles bind portable flow contracts to executable capabilities."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Final
+
+from .subflows import SubflowRegistry, default_subflows
+from .tools import ToolRegistry, default_tool_registry
+
+REFERENCE_PROFILE_ID: Final[str] = "flowspec2/reference@2"
+REFERENCE_DOMAIN_TYPES: Final[frozenset[str]] = frozenset(
+    {"categorical", "bool", "free_text", "brazilian_tax_id", "email", "name", "integer", "number"}
+)
+REFERENCE_CAPABILITIES: Final[frozenset[str]] = frozenset(
+    {
+        "auto_flow",
+        "await_external",
+        "external_authentication",
+        "geocoding",
+        "handoff",
+        "identity_lookup",
+        "location_in",
+        "media_in",
+        "media_out",
+        "session_reset",
+        "tts",
+    }
+)
+
+
+def capability_is_requested(capability_value: Any) -> bool:
+    """Return whether a normalized capability value requests host support."""
+
+    return (
+        capability_value is True
+        or isinstance(capability_value, Mapping)
+        and bool(capability_value)
+        or isinstance(capability_value, (list, tuple))
+        and bool(capability_value)
+    )
+
+
+@dataclass(frozen=True)
+class FlowProfile:
+    """Named registries and host features against which a flow is checked."""
+
+    identifier: str
+    tools: ToolRegistry
+    subflows: SubflowRegistry
+    capabilities: frozenset[str]
+    domain_types: frozenset[str]
+    allow_legacy_contracts: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.identifier.strip():
+            raise ValueError("profile identifier must be non-empty")
+        if any(not capability.strip() for capability in self.capabilities):
+            raise ValueError("profile capabilities must be non-empty strings")
+        if any(not domain_type.strip() for domain_type in self.domain_types):
+            raise ValueError("profile domain types must be non-empty strings")
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return the complete owned runtime-profile contract."""
+
+        return {
+            "identifier": self.identifier,
+            "allow_legacy_contracts": self.allow_legacy_contracts,
+            "capabilities": sorted(self.capabilities),
+            "domain_types": sorted(self.domain_types),
+            "tools": {
+                tool_name: tool_definition.as_dict()
+                for tool_name, tool_definition in sorted(self.tools.definitions.items())
+            },
+            "subflows": {
+                subflow_reference: subflow_definition.as_dict()
+                for subflow_reference, subflow_definition in sorted(
+                    self.subflows.definitions.items()
+                )
+            },
+        }
+
+    def canonical_json(self) -> str:
+        """Serialize the complete profile contract deterministically."""
+
+        return json.dumps(
+            self.as_dict(),
+            ensure_ascii=False,
+            allow_nan=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+
+    @property
+    def digest(self) -> str:
+        """Return the content identity used by IR and authoring provenance."""
+
+        return hashlib.sha256(self.canonical_json().encode("utf-8")).hexdigest()
+
+
+def reference_profile(
+    *,
+    tools: ToolRegistry | None = None,
+    subflows: SubflowRegistry | None = None,
+) -> FlowProfile:
+    """Build the executable profile shipped with the reference runtime."""
+
+    return FlowProfile(
+        identifier=REFERENCE_PROFILE_ID,
+        tools=tools or default_tool_registry(),
+        subflows=subflows or default_subflows(),
+        capabilities=REFERENCE_CAPABILITIES,
+        domain_types=REFERENCE_DOMAIN_TYPES,
+        allow_legacy_contracts=False,
+    )