flowspec2 1.0.0__py3-none-any.whl

flowspec2/json_codec.py

@@ -0,0 +1,120 @@
+"""Strict RFC 8259 JSON decoding for every external document boundary."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+
+class StrictJsonError(ValueError):
+    """Raised for JSON extensions or ambiguous duplicate object members."""
+
+
+class StrictJsonValueError(StrictJsonError):
+    """Raised with a JSON Pointer for an in-memory non-JSON value."""
+
+    def __init__(self, message: str, *, path: str) -> None:
+        self.path = path
+        super().__init__(message)
+
+
+def _value_error(boundary: str, path_segments: tuple[str | int, ...], detail: str) -> None:
+    path = _json_pointer(path_segments)
+    raise StrictJsonValueError(f"{boundary} at {path}: {detail}", path=path)
+
+
+def _json_pointer(path_segments: tuple[str | int, ...]) -> str:
+    return (
+        "".join(
+            "/" + str(path_segment).replace("~", "~0").replace("/", "~1")
+            for path_segment in path_segments
+        )
+        or "/"
+    )
+
+
+def validate_json_value(
+    value: Any,
+    *,
+    boundary: str,
+    path_segments: tuple[str | int, ...] = (),
+    active_containers: set[int] | None = None,
+) -> None:
+    """Reject Python values that cannot be represented as strict JSON."""
+
+    if value is None or isinstance(value, (bool, str, int)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            _value_error(boundary, path_segments, "non-finite number")
+        return
+
+    traversed_containers = set() if active_containers is None else active_containers
+    if isinstance(value, dict):
+        container_identifier = id(value)
+        if container_identifier in traversed_containers:
+            _value_error(boundary, path_segments, "cyclic JSON object")
+        traversed_containers.add(container_identifier)
+        try:
+            for member_name, member_value in value.items():
+                if not isinstance(member_name, str):
+                    _value_error(
+                        boundary,
+                        path_segments,
+                        "object member name has unsupported Python type "
+                        f"{type(member_name).__name__}",
+                    )
+                validate_json_value(
+                    member_value,
+                    boundary=boundary,
+                    path_segments=(*path_segments, member_name),
+                    active_containers=traversed_containers,
+                )
+        finally:
+            traversed_containers.remove(container_identifier)
+        return
+    if isinstance(value, list):
+        container_identifier = id(value)
+        if container_identifier in traversed_containers:
+            _value_error(boundary, path_segments, "cyclic JSON array")
+        traversed_containers.add(container_identifier)
+        try:
+            for element_index, element in enumerate(value):
+                validate_json_value(
+                    element,
+                    boundary=boundary,
+                    path_segments=(*path_segments, element_index),
+                    active_containers=traversed_containers,
+                )
+        finally:
+            traversed_containers.remove(container_identifier)
+        return
+    _value_error(
+        boundary,
+        path_segments,
+        f"unsupported Python type {type(value).__name__}",
+    )
+
+
+def _reject_nonstandard_constant(constant: str) -> None:
+    raise StrictJsonError(f"non-standard JSON numeric constant {constant!r} is not allowed")
+
+
+def _reject_duplicate_members(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    decoded_object: dict[str, Any] = {}
+    for member_name, member_value in pairs:
+        if member_name in decoded_object:
+            raise StrictJsonError(f"duplicate JSON object member {member_name!r} is not allowed")
+        decoded_object[member_name] = member_value
+    return decoded_object
+
+
+def strict_json_loads(serialized_document: str | bytes | bytearray) -> Any:
+    """Decode standards-compliant JSON while rejecting NaN and duplicate keys."""
+
+    return json.loads(
+        serialized_document,
+        parse_constant=_reject_nonstandard_constant,
+        object_pairs_hook=_reject_duplicate_members,
+    )

flowspec2/llm.py

@@ -0,0 +1,366 @@
+"""An LLM driver — the *non-deterministic execution* side of the boundary.
+
+flowspec2 pins the rails (states, closed value-domains, transitions). This module
+is the agent that reasons *within* them: given a flow's ``route.description`` and
+non-exclusive ``route.trigger_phrases`` examples it decides whether to enter,
+and at each pause it reads the user's free text/voice and the node's
+``payload_schema`` (or the interactive options) and
+extracts the **closed token** for the slot. The flowspec2 validators then enforce
+the rail — an out-of-domain extraction is rejected and the node re-asks.
+
+Default provider: Google Gemini (``gemini-2.5-flash``), via ``GEMINI_API_KEY``.
+The driver is a thin protocol —
+``route`` + ``extract`` — so any provider can implement it.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from jsonschema import Draft202012Validator
+
+from .json_codec import strict_json_loads
+from .models import CORRECTION_TARGETS_SCHEMA_KEY, AgentResponse
+
+DEFAULT_ROUTE_SYSTEM_PROMPT = (
+    "You route messages to a service catalog. "
+    "Given the user's message, decide which service, if any, handles the request. "
+    "Respond ONLY with JSON."
+)
+
+DEFAULT_EXTRACTION_SYSTEM_PROMPT = (
+    "You extract structured data for a conversational flow. "
+    "The system asked the user a question; convert the free-text response into a JSON "
+    "object with the requested fields, using ONLY permitted values for closed lists. "
+    "Interpret synonyms, informal expressions, numbers, and emojis. "
+    "Respond ONLY with JSON and no commentary."
+)
+
+
+@dataclass(frozen=True)
+class StructuredOutputRequest:
+    """Exact provider-neutral inputs for one closed structured-output turn."""
+
+    system: str
+    prompt: str
+    response_schema: dict[str, Any]
+
+
+def _enum_of(prop: dict[str, Any]) -> Optional[list[Any]]:
+    if "enum" in prop:
+        return list(prop["enum"])
+    if "const" in prop:
+        return [prop["const"]]
+    if "anyOf" in prop:
+        values: list[Any] = []
+        nullable = False
+        for sub in prop["anyOf"]:
+            if "enum" in sub:
+                values.extend(sub["enum"])
+            if sub.get("type") == "null":
+                nullable = True
+        if values:
+            return values + ([None] if nullable else [])
+    return None
+
+
+def _property_types(property_schema: dict[str, Any]) -> set[str]:
+    property_type = property_schema.get("type")
+    property_types: set[str] = set()
+    if isinstance(property_type, str):
+        property_types.add(property_type)
+    elif isinstance(property_type, list):
+        property_types.update(
+            candidate_type for candidate_type in property_type if isinstance(candidate_type, str)
+        )
+    for union_keyword in ("anyOf", "oneOf"):
+        property_types.update(
+            nested_schema["type"]
+            for nested_schema in property_schema.get(union_keyword, [])
+            if isinstance(nested_schema, dict) and isinstance(nested_schema.get("type"), str)
+        )
+    return property_types
+
+
+def _fields_spec(
+    ar: AgentResponse,
+) -> list[tuple[str, str, Optional[list[Any]], bool]]:
+    """Return ``(field, kind, allowed, nullable)`` for the current extraction."""
+    schema = ar.payload_schema or {}
+    props = schema.get("properties", {})
+    spec: list[tuple[str, str, Optional[list[Any]], bool]] = []
+    for name, prop in props.items():
+        allowed = _enum_of(prop)
+        property_types = _property_types(prop)
+        nullable = "null" in property_types or (allowed is not None and None in allowed)
+        if allowed is not None:
+            spec.append((name, "closed", allowed, nullable))
+        elif "boolean" in property_types:
+            spec.append((name, "bool", None, nullable))
+        elif "integer" in property_types:
+            spec.append((name, "integer", None, nullable))
+        elif "number" in property_types:
+            spec.append((name, "number", None, nullable))
+        elif property_types == {"null"}:
+            spec.append((name, "null", None, True))
+        else:
+            spec.append((name, "text", None, nullable))
+    if not spec and ar.interactive and ar.interactive.get("field"):
+        field = ar.interactive["field"]
+        buttons = ar.interactive.get("buttons") or []
+        ids = [b.get("id") for b in buttons if b.get("id")]
+        if ids and set(ids) <= {"yes", "no"}:
+            spec.append((field, "bool", None, False))
+        elif ids:
+            spec.append((field, "closed", ids, False))
+        else:
+            spec.append((field, "text", None, False))
+    return spec
+
+
+def _interactive_options(ar: AgentResponse) -> list[str]:
+    iv = ar.interactive or {}
+    if iv.get("buttons"):
+        return [b["title"] for b in iv["buttons"]]
+    if iv.get("sections"):
+        return [r["title"] for s in iv["sections"] for r in s["rows"]]
+    return []
+
+
+def _route_response_schema(flows: list[dict[str, Any]]) -> dict[str, Any]:
+    flow_identifiers = list(dict.fromkeys(flow["flow"] for flow in flows))
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["service"],
+        "properties": {"service": {"enum": [*flow_identifiers, None]}},
+    }
+
+
+def build_route_request(
+    text: str,
+    flows: list[dict[str, Any]],
+    *,
+    system_prompt: str = DEFAULT_ROUTE_SYSTEM_PROMPT,
+) -> StructuredOutputRequest:
+    """Render the exact routing request, including non-exclusive trigger examples."""
+
+    catalog = [
+        {
+            "service": flow["flow"],
+            "description": flow["route"]["description"],
+            "trigger_phrases": list(flow["route"].get("trigger_phrases", [])),
+        }
+        for flow in flows
+    ]
+    serialized_catalog = json.dumps(
+        catalog,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+    prompt = (
+        f"Service catalog as JSON:\n{serialized_catalog}\n\n"
+        "Use description as each service's primary definition. "
+        "trigger_phrases contains only examples of compatible messages; "
+        "do not treat them as an exclusive list or a match guarantee.\n\n"
+        f'User message: "{text}"\n\n'
+        'Return {"service": "<service name>"} if one applies, '
+        'or {"service": null} if none applies.'
+    )
+    return StructuredOutputRequest(
+        system=system_prompt,
+        prompt=prompt,
+        response_schema=_route_response_schema(flows),
+    )
+
+
+def _extraction_response_schema(agent_response: AgentResponse) -> dict[str, Any]:
+    payload_schema = agent_response.payload_schema or {}
+    properties = copy.deepcopy(payload_schema.get("properties", {}))
+    required = list(payload_schema.get("required", []))
+    if not properties:
+        for field, kind, allowed, nullable in _fields_spec(agent_response):
+            if kind == "closed":
+                properties[field] = {"enum": allowed or []}
+            elif kind == "bool":
+                properties[field] = {"type": ["boolean", "null"] if nullable else "boolean"}
+            elif kind in {"integer", "number"}:
+                properties[field] = {"type": [kind, "null"] if nullable else kind}
+            elif kind == "null":
+                properties[field] = {"type": "null"}
+            else:
+                properties[field] = {"type": ["string", "null"] if nullable else "string"}
+            required.append(field)
+    correction_targets = payload_schema.get(CORRECTION_TARGETS_SCHEMA_KEY)
+    allows_correction = (
+        isinstance(correction_targets, list)
+        and bool(correction_targets)
+        and all(isinstance(target, str) for target in correction_targets)
+    )
+    response_schema: dict[str, Any] = {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": properties,
+    }
+    if required:
+        response_schema["required"] = required
+    if allows_correction:
+        properties["correction"] = {"enum": correction_targets}
+        payload_branch = {
+            "required": required,
+            "not": {"required": ["correction"]},
+        }
+        correction_branch = {
+            "required": ["correction"],
+            "not": {"anyOf": [{"required": [field_name]} for field_name in required]},
+        }
+        response_schema.pop("required", None)
+        response_schema["oneOf"] = [payload_branch, correction_branch]
+    Draft202012Validator.check_schema(response_schema)
+    return response_schema
+
+
+def build_extraction_request(
+    text: str,
+    agent_response: AgentResponse,
+    *,
+    system_prompt: str = DEFAULT_EXTRACTION_SYSTEM_PROMPT,
+) -> StructuredOutputRequest:
+    """Render the exact extraction request, preserving payload-schema guidance."""
+
+    spec = _fields_spec(agent_response)
+    lines: list[str] = []
+    for field, kind, allowed, nullable in spec:
+        null_alternative = " or null" if nullable and kind != "closed" else ""
+        if kind == "closed":
+            values = ", ".join(
+                json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+                for value in (allowed or [])
+            )
+            lines.append(f'- "{field}": one of these EXACT values: [{values}]')
+        elif kind == "bool":
+            lines.append(
+                f'- "{field}": true (yes/affirmative), false (no/negative){null_alternative}'
+            )
+        elif kind == "integer":
+            lines.append(f'- "{field}": a JSON integer without quotes{null_alternative}')
+        elif kind == "number":
+            lines.append(f'- "{field}": a finite JSON number without quotes{null_alternative}')
+        elif kind == "null":
+            lines.append(f'- "{field}": null')
+        else:
+            lines.append(
+                f'- "{field}": a JSON string containing the supplied text{null_alternative}'
+            )
+    options = _interactive_options(agent_response)
+    options_hint = f"\nOptions offered to the user: {', '.join(options)}." if options else ""
+    correction_targets = (agent_response.payload_schema or {}).get(CORRECTION_TARGETS_SCHEMA_KEY)
+    correction_rule = (
+        "- If the user wants to CORRECT previously supplied data, return only "
+        '{"correction": "<identifier>"}, using one of these EXACT identifiers: '
+        f"{json.dumps(correction_targets, ensure_ascii=False)}.\n"
+        if isinstance(correction_targets, list) and correction_targets
+        else ""
+    )
+    prompt = (
+        f'System question: "{agent_response.description}"\n'
+        f"Fields to extract:\n" + "\n".join(lines) + options_hint + "\n\n"
+        f'User response: "{text}"\n\n'
+        "Rules:\n"
+        "- Use ONLY permitted values from closed lists.\n"
+        f"{correction_rule}"
+        "- Return only JSON with the requested fields."
+    )
+    return StructuredOutputRequest(
+        system=system_prompt,
+        prompt=prompt,
+        response_schema=_extraction_response_schema(agent_response),
+    )
+
+
+class StructuredOutputAgent:
+    """Provider-neutral routing and extraction over one closed JSON completion."""
+
+    def __init__(
+        self,
+        *,
+        route_system_prompt: str = DEFAULT_ROUTE_SYSTEM_PROMPT,
+        extraction_system_prompt: str = DEFAULT_EXTRACTION_SYSTEM_PROMPT,
+    ) -> None:
+        self.route_system_prompt = route_system_prompt
+        self.extraction_system_prompt = extraction_system_prompt
+
+    def _json(
+        self,
+        system: str,
+        prompt: str,
+        response_schema: dict[str, Any],
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def route(self, text: str, flows: list[dict[str, Any]]) -> Optional[str]:
+        request = build_route_request(text, flows, system_prompt=self.route_system_prompt)
+        return self._json(request.system, request.prompt, request.response_schema).get("service")
+
+    def extract(self, text: str, ar: AgentResponse) -> dict[str, Any]:
+        request = build_extraction_request(
+            text,
+            ar,
+            system_prompt=self.extraction_system_prompt,
+        )
+        return self._json(request.system, request.prompt, request.response_schema)
+
+
+class GeminiAgent(StructuredOutputAgent):
+    """Engine-side driver backed by Google Gemini structured output."""
+
+    def __init__(
+        self,
+        model: str = "gemini-2.5-flash",
+        api_key: Optional[str] = None,
+        *,
+        route_system_prompt: str = DEFAULT_ROUTE_SYSTEM_PROMPT,
+        extraction_system_prompt: str = DEFAULT_EXTRACTION_SYSTEM_PROMPT,
+    ) -> None:
+        from google import genai
+
+        super().__init__(
+            route_system_prompt=route_system_prompt,
+            extraction_system_prompt=extraction_system_prompt,
+        )
+        self.model = model
+        self.client = genai.Client(api_key=api_key or os.environ["GEMINI_API_KEY"])
+
+    def _json(
+        self,
+        system: str,
+        prompt: str,
+        response_schema: dict[str, Any],
+    ) -> dict[str, Any]:
+        from google.genai import types
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=prompt,
+            config=types.GenerateContentConfig(
+                system_instruction=system,
+                response_mime_type="application/json",
+                response_json_schema=response_schema,
+                temperature=0.0,
+            ),
+        )
+        try:
+            response_document = strict_json_loads(response.text or "{}")
+            if isinstance(response_document, dict) and Draft202012Validator(
+                response_schema
+            ).is_valid(response_document):
+                return response_document
+            return {}
+        except (ValueError, TypeError):
+            return {}

flowspec2/models.py

@@ -0,0 +1,121 @@
+"""The three runtime contracts that flow through a compiled graph.
+
+These mirror the production ``multi_step_service`` framework so the format maps
+1:1 onto it:
+
+- ``ServiceState`` — the single source of truth that traverses every node.
+  ``data`` persists and is visible to the agent; ``payload`` is ephemeral (the
+  fields the LLM extracted *this turn*); ``internal`` persists but is hidden.
+  There is **no step pointer** — position is rediscovered each turn from which
+  slots are filled in their configured partition.
+- ``AgentResponse`` — the contract back to the agent. ``description`` is the
+  citizen-facing text / deterministic fallback; ``payload_schema`` is the JSON
+  Schema handed to constrained decoding so the LLM extracts the right closed
+  token next turn; ``interactive`` optionally renders buttons/list/flow;
+  ``log_id`` correlates a warning or error with its structured log record.
+- ``ServiceMetadata`` — autogenerated timestamps, persisted contract provenance,
+  and a ``saved`` marker used by the empty-payload reset semantics.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Final, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictFloat, StrictInt, StrictStr
+
+from .clock import UtcClock, system_utc_now, utc_timestamp
+
+CORRECTION_TARGETS_SCHEMA_KEY: Final[str] = "x-flowspec2-correction-targets"
+CORRECTION_REQUESTED_INTERNAL_KEY: Final[str] = "_flowspec2_correction_requested"
+
+
+class AgentResponse(BaseModel):
+    """What a node hands back: a question (pause) or a result."""
+
+    service_name: Optional[str] = None
+    error_message: Optional[str] = None
+    log_id: Optional[str] = Field(default=None, pattern=r"^\d+$")
+    description: str = ""
+    payload_schema: Optional[dict[str, Any]] = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    # Optional signal to the tool layer to render this as a WhatsApp interactive
+    # (buttons/list/flow) instead of plain text. Shape mirrors the production
+    # ``AgentResponse.interactive``. ``None`` => zero effect (back-compat).
+    interactive: Optional[dict[str, Any]] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AwaitResumeProvenance(BaseModel):
+    """Persisted identity of the external-resume contract and accepted signal."""
+
+    step: str = Field(pattern=r"^[a-z][a-z0-9_]*$")
+    version: str = Field(pattern=r"^[1-9][0-9]*(?:\.[0-9]+){0,2}$")
+    digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    correlation_path: str = Field(pattern=r"^\$token(?:\.[A-Za-z][A-Za-z0-9_]*)+$")
+    correlation_value: Optional[StrictStr | StrictInt | StrictFloat | StrictBool] = None
+    deadline: Optional[datetime] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ServiceMetadata(BaseModel):
+    created_at: datetime = Field(default_factory=system_utc_now)
+    updated_at: Optional[datetime] = None
+    flow_version: Optional[str] = None
+    flow_ir_digest: Optional[str] = Field(default=None, pattern=r"^[0-9a-f]{64}$")
+    dependency_digest: Optional[str] = Field(default=None, pattern=r"^[0-9a-f]{64}$")
+    profile_digest: Optional[str] = Field(default=None, pattern=r"^[0-9a-f]{64}$")
+    await_resume: Optional[AwaitResumeProvenance] = None
+    # True once the workflow has been persisted at least once. Drives the
+    # empty-payload reset rule (never-saved => reset; in-progress => ignore).
+    saved: bool = False
+
+    model_config = ConfigDict(extra="forbid")
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.updated_at is None:
+            self.updated_at = self.created_at
+
+    @classmethod
+    def from_clock(
+        cls,
+        clock: UtcClock,
+        *,
+        flow_version: str,
+        flow_ir_digest: str,
+        dependency_digest: str,
+        profile_digest: str,
+    ) -> ServiceMetadata:
+        """Create timestamped metadata bound to one resolved flow contract."""
+
+        timestamp = utc_timestamp(clock)
+        return cls(
+            created_at=timestamp,
+            updated_at=timestamp,
+            flow_version=flow_version,
+            flow_ir_digest=flow_ir_digest,
+            dependency_digest=dependency_digest,
+            profile_digest=profile_digest,
+        )
+
+    def touch(self, clock: UtcClock = system_utc_now) -> None:
+        """Advance the update timestamp using an injectable clock."""
+
+        self.updated_at = utc_timestamp(clock)
+
+
+class ServiceState(BaseModel):
+    """The single object that traverses every node of a compiled flow graph."""
+
+    user_id: str
+    service_name: str
+    status: Literal["progress", "completed", "error"] = "progress"
+    data: dict[str, Any] = Field(default_factory=dict)
+    payload: dict[str, Any] = Field(default_factory=dict)
+    internal: dict[str, Any] = Field(default_factory=dict)
+    metadata: ServiceMetadata = Field(default_factory=ServiceMetadata)
+    agent_response: Optional[AgentResponse] = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")