flowspec2 1.0.0__py3-none-any.whl

flowspec2/authoring/corpus/gated_derive.case.json

@@ -0,0 +1,100 @@
+{
+  "format": "flowspec2/authoring-case@3",
+  "identifier": "gated_derivation",
+  "prompt": "Author the ordered steps collect_issue_category, collect_issue_detail, and derive_backend_classification. Collect required issue_category from the categorical IssueCategory values Pothole and Obstruction. Collect required issue_detail from categorical IssueDetail values Small and Large, require issue_category first, and ask only when slots.issue_category equals Pothole. Derive backend_classification from issue_category followed by issue_detail with Pothole|Small to POTHOLE_SMALL, Pothole|Large to POTHOLE_LARGE, Obstruction|null to STREET_OBSTRUCTION, and default $from[0]. Add no other semantic behavior. Flow identity, version, route prose, and non-verbatim prompt wording may vary.",
+  "feature_tags": ["gate", "derive", "closed_domain"],
+  "required_constructs": [
+    {
+      "identifier": "conditional-gate",
+      "pointer_pattern": "/path/*/ask_when",
+      "expected": {
+        "eq": [
+          "slots.issue_category",
+          "Pothole"
+        ]
+      }
+    },
+    {
+      "identifier": "derive-step",
+      "pointer_pattern": "/path/*/derive",
+      "expected": "backend_classification"
+    },
+    {
+      "identifier": "derive-definition",
+      "pointer_pattern": "/derive/*/writes",
+      "expected": "backend_classification"
+    },
+    {
+      "identifier": "derive-sources",
+      "pointer_pattern": "/derive/*/from",
+      "expected": [
+        "issue_category",
+        "issue_detail"
+      ]
+    }
+  ],
+  "source": {
+    "schema": "flowspec/2",
+    "flow": "gated_issue_classification",
+    "version": "1.0.0",
+    "route": {
+      "description": "Classify a street issue with a conditional detail."
+    },
+    "domains": {
+      "IssueCategory": {
+        "type": "categorical",
+        "values": ["Pothole", "Obstruction"]
+      },
+      "IssueDetail": {
+        "type": "categorical",
+        "values": ["Small", "Large"]
+      }
+    },
+    "slots": {
+      "issue_category": {
+        "domain": "IssueCategory",
+        "required": true
+      },
+      "issue_detail": {
+        "domain": "IssueDetail",
+        "required": true,
+        "requires": ["issue_category"]
+      }
+    },
+    "path": [
+      {
+        "step": "collect_issue_category",
+        "slot": "issue_category",
+        "prompt": {
+          "text": "Which type of issue are you reporting?"
+        }
+      },
+      {
+        "step": "collect_issue_detail",
+        "slot": "issue_detail",
+        "ask_when": {
+          "eq": ["slots.issue_category", "Pothole"]
+        },
+        "prompt": {
+          "text": "How large is the pothole?"
+        }
+      },
+      {
+        "step": "derive_backend_classification",
+        "derive": "backend_classification"
+      }
+    ],
+    "derive": [
+      {
+        "writes": "backend_classification",
+        "from": ["issue_category", "issue_detail"],
+        "lookup": {
+          "Pothole|Small": "POTHOLE_SMALL",
+          "Pothole|Large": "POTHOLE_LARGE",
+          "Obstruction|null": "STREET_OBSTRUCTION"
+        },
+        "default": "$from[0]"
+      }
+    ]
+  }
+}

flowspec2/authoring/corpus/linear.case.json

@@ -0,0 +1,55 @@
+{
+  "format": "flowspec2/authoring-case@3",
+  "identifier": "linear_collection",
+  "prompt": "Author a flow with the single ordered step collect_request_description. It collects the required request_description slot through the free-text RequestDescription domain and asks the citizen for a short maintenance-request description. Include route trigger examples and an extraction hint. Add no other domain, slot, path step, derive, subflow, confirmation, capability, or terminal behavior. Flow identity, version, route prose, trigger examples, non-verbatim prompt wording, and extraction guidance may vary.",
+  "feature_tags": ["linear", "collection"],
+  "required_constructs": [
+    {
+      "identifier": "collect-step",
+      "pointer_pattern": "/path/*/slot",
+      "expected": "request_description"
+    },
+    {
+      "identifier": "route-trigger-examples",
+      "pointer_pattern": "/route/trigger_phrases"
+    },
+    {
+      "identifier": "request-description-extraction-hint",
+      "pointer_pattern": "/path/*/prompt/extract_hint"
+    }
+  ],
+  "source": {
+    "schema": "flowspec/2",
+    "flow": "linear_maintenance_request",
+    "version": "1.0.0",
+    "route": {
+      "description": "Collect a short municipal maintenance request.",
+      "trigger_phrases": [
+        "cobalt lantern protocol",
+        "describe a maintenance request",
+        "report municipal maintenance"
+      ]
+    },
+    "domains": {
+      "RequestDescription": {
+        "type": "free_text"
+      }
+    },
+    "slots": {
+      "request_description": {
+        "domain": "RequestDescription",
+        "required": true
+      }
+    },
+    "path": [
+      {
+        "step": "collect_request_description",
+        "slot": "request_description",
+        "prompt": {
+          "text": "Describe the maintenance request.",
+          "extract_hint": "Set request_description to only the text inside `ZETA=[...]`; ignore `ALPHA=[...]`."
+        }
+      }
+    ]
+  }
+}

flowspec2/authoring/corpus/manifest.json

@@ -0,0 +1,31 @@
+{
+  "format": "flowspec2/authoring-corpus@3",
+  "identifier": "flowspec2_reference",
+  "cases": [
+    {
+      "identifier": "address_subflow",
+      "path": "subflow.case.json",
+      "sha256": "e7fe2fb903cc6557443fd8a9c37bbf2a68aa6ed914fa51952a7960179546ed31"
+    },
+    {
+      "identifier": "await_and_correction",
+      "path": "await_correction.case.json",
+      "sha256": "d36e8f98ce9832029595600b093a062e29ff34d37bd84c5a3c9ada87a5745711"
+    },
+    {
+      "identifier": "gated_derivation",
+      "path": "gated_derive.case.json",
+      "sha256": "643c7bbf085e685fa2237578d5940bb89f1343f44d92bdc9d4033c53bc0259cd"
+    },
+    {
+      "identifier": "linear_collection",
+      "path": "linear.case.json",
+      "sha256": "dbdb6535bfba1400513748fbbdd7527dcd3db6025492c166e0674cbce1e11048"
+    },
+    {
+      "identifier": "terminal_fulfillment",
+      "path": "terminal.case.json",
+      "sha256": "988b703c5d595346b9a3c0c0fdded54aea74b02d967a6c3330553c183d18da91"
+    }
+  ]
+}

flowspec2/authoring/corpus/subflow.case.json

@@ -0,0 +1,66 @@
+{
+  "format": "flowspec2/authoring-case@3",
+  "identifier": "address_subflow",
+  "prompt": "Author an ordered flow that first runs collect_reference_note for optional reference_note in the optional free-text ReferenceNote domain, then delegates address collection to address@1. Declare address@1 exactly once with required and needs_confirmation both true. Add no other semantic behavior. Flow identity, version, route prose, and non-verbatim prompt wording may vary.",
+  "feature_tags": ["subflow", "address"],
+  "required_constructs": [
+    {
+      "identifier": "subflow-anchor",
+      "pointer_pattern": "/path/*/use",
+      "expected": "address@1"
+    },
+    {
+      "identifier": "subflow-declaration",
+      "pointer_pattern": "/uses/*/ref",
+      "expected": "address@1"
+    },
+    {
+      "identifier": "subflow-configuration",
+      "pointer_pattern": "/uses/*/with",
+      "expected": {
+        "required": true,
+        "needs_confirmation": true
+      }
+    }
+  ],
+  "source": {
+    "schema": "flowspec/2",
+    "flow": "address_collection",
+    "version": "1.0.0",
+    "route": {
+      "description": "Collect and confirm the address for a municipal request."
+    },
+    "domains": {
+      "ReferenceNote": {
+        "type": "free_text",
+        "optional": true
+      }
+    },
+    "slots": {
+      "reference_note": {
+        "domain": "ReferenceNote"
+      }
+    },
+    "path": [
+      {
+        "step": "collect_reference_note",
+        "slot": "reference_note",
+        "prompt": {
+          "text": "Add an optional nearby reference point."
+        }
+      },
+      {
+        "use": "address@1"
+      }
+    ],
+    "uses": [
+      {
+        "ref": "address@1",
+        "with": {
+          "required": true,
+          "needs_confirmation": true
+        }
+      }
+    ]
+  }
+}

flowspec2/authoring/corpus/terminal.case.json

@@ -0,0 +1,94 @@
+{
+  "format": "flowspec2/authoring-case@3",
+  "identifier": "terminal_fulfillment",
+  "prompt": "Author an ordered flow that collects required problem_description through the free-text ProblemDescription domain in collect_problem_description, then executes the open_ticket terminal. Call open_service_request idempotently with problem_description as problem and store result.protocol_id as protocol_id. On success and fatal reset next; on retryable preserve state. Add no other semantic behavior. Flow identity, version, route prose, and non-verbatim prompt wording may vary.",
+  "feature_tags": ["terminal", "tool_contract", "idempotency"],
+  "required_constructs": [
+    {
+      "identifier": "terminal-marker",
+      "pointer_pattern": "/path/*/terminal",
+      "expected": true
+    },
+    {
+      "identifier": "terminal-tool",
+      "pointer_pattern": "/terminal/tool",
+      "expected": "open_service_request"
+    },
+    {
+      "identifier": "terminal-idempotency",
+      "pointer_pattern": "/terminal/idempotent",
+      "expected": true
+    },
+    {
+      "identifier": "terminal-input",
+      "pointer_pattern": "/terminal/input",
+      "expected": [
+        {
+          "param": "problem",
+          "slot": "problem_description"
+        }
+      ]
+    },
+    {
+      "identifier": "terminal-output",
+      "pointer_pattern": "/terminal/outputs/protocol_id",
+      "expected": "result.protocol_id"
+    }
+  ],
+  "source": {
+    "schema": "flowspec/2",
+    "flow": "terminal_ticket_fulfillment",
+    "version": "1.0.0",
+    "route": {
+      "description": "Collect a problem and create a municipal service ticket."
+    },
+    "domains": {
+      "ProblemDescription": {
+        "type": "free_text"
+      }
+    },
+    "slots": {
+      "problem_description": {
+        "domain": "ProblemDescription",
+        "required": true
+      }
+    },
+    "path": [
+      {
+        "step": "collect_problem_description",
+        "slot": "problem_description",
+        "prompt": {
+          "text": "Describe the service problem."
+        }
+      },
+      {
+        "terminal": true
+      }
+    ],
+    "terminal": {
+      "step": "open_ticket",
+      "tool": "open_service_request",
+      "idempotent": true,
+      "input": [
+        {
+          "param": "problem",
+          "slot": "problem_description"
+        }
+      ],
+      "outputs": {
+        "protocol_id": "result.protocol_id"
+      },
+      "outcomes": {
+        "success": {
+          "reset_next": true
+        },
+        "retryable": {
+          "preserve_state": true
+        },
+        "fatal": {
+          "reset_next": true
+        }
+      }
+    }
+  }
+}

flowspec2/authoring/corpus.py

@@ -0,0 +1,307 @@
+"""Versioned, packaged benchmark cases for AI flow authoring."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from typing import Any, Final, cast
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError
+
+from flowspec2.json_codec import strict_json_loads
+
+from .benchmark import AuthoringBenchmarkCase, RequiredFlowConstruct
+
+AUTHORING_CASE_FORMAT: Final[str] = "flowspec2/authoring-case@3"
+AUTHORING_CORPUS_FORMAT: Final[str] = "flowspec2/authoring-corpus@3"
+REFERENCE_AUTHORING_CORPUS_ID: Final[str] = "flowspec2_reference"
+
+_IDENTIFIER_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+_CASE_PATH_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z][a-z0-9_]*\.case\.json$")
+_DIGEST_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[0-9a-f]{64}$")
+_MANIFEST_SCHEMA: Final[dict[str, Any]] = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["format", "identifier", "cases"],
+    "properties": {
+        "format": {"const": AUTHORING_CORPUS_FORMAT},
+        "identifier": {"type": "string", "pattern": _IDENTIFIER_PATTERN.pattern},
+        "cases": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["identifier", "path", "sha256"],
+                "properties": {
+                    "identifier": {
+                        "type": "string",
+                        "pattern": _IDENTIFIER_PATTERN.pattern,
+                    },
+                    "path": {"type": "string", "pattern": _CASE_PATH_PATTERN.pattern},
+                    "sha256": {"type": "string", "pattern": _DIGEST_PATTERN.pattern},
+                },
+            },
+        },
+    },
+}
+_CASE_SCHEMA: Final[dict[str, Any]] = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": False,
+    "required": [
+        "format",
+        "identifier",
+        "prompt",
+        "feature_tags",
+        "required_constructs",
+        "source",
+    ],
+    "properties": {
+        "format": {"const": AUTHORING_CASE_FORMAT},
+        "identifier": {"type": "string", "pattern": _IDENTIFIER_PATTERN.pattern},
+        "prompt": {"type": "string", "minLength": 1},
+        "feature_tags": {
+            "type": "array",
+            "uniqueItems": True,
+            "items": {"type": "string", "pattern": _IDENTIFIER_PATTERN.pattern},
+        },
+        "required_constructs": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["identifier", "pointer_pattern"],
+                "properties": {
+                    "identifier": {
+                        "type": "string",
+                        "pattern": _IDENTIFIER_PATTERN.pattern,
+                    },
+                    "pointer_pattern": {"type": "string", "pattern": r"^/.+"},
+                    "expected": {},
+                },
+            },
+        },
+        "source": {"type": "object"},
+    },
+}
+_manifest_validator: Final[Draft202012Validator] = Draft202012Validator(_MANIFEST_SCHEMA)
+_case_validator: Final[Draft202012Validator] = Draft202012Validator(_CASE_SCHEMA)
+_reference_corpus_cache: AuthoringCorpus | None = None
+
+
+def _canonical_json(json_document: object) -> str:
+    return json.dumps(
+        json_document,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _validation_errors(
+    json_document: object,
+    validator: Draft202012Validator,
+) -> tuple[str, ...]:
+    validation_errors = sorted(
+        validator.iter_errors(cast(Any, json_document)),
+        key=lambda validation_error: (
+            tuple(str(path_segment) for path_segment in validation_error.absolute_path),
+            validation_error.message,
+        ),
+    )
+    return tuple(
+        f"{'.'.join(str(path_segment) for path_segment in validation_error.absolute_path) or '<root>'}: "
+        f"{validation_error.message}"
+        for validation_error in validation_errors
+    )
+
+
+def _load_case_document(case_resource: Traversable) -> dict[str, Any]:
+    decoded_case = strict_json_loads(case_resource.read_text(encoding="utf-8"))
+    if validation_errors := _validation_errors(decoded_case, _case_validator):
+        raise ValueError(
+            f"invalid packaged authoring case {case_resource.name}: " + "; ".join(validation_errors)
+        )
+    return cast(dict[str, Any], decoded_case)
+
+
+def _load_manifest(corpus_directory: Traversable) -> dict[str, Any]:
+    manifest_resource = corpus_directory.joinpath("manifest.json")
+    decoded_manifest = strict_json_loads(manifest_resource.read_text(encoding="utf-8"))
+    if validation_errors := _validation_errors(decoded_manifest, _manifest_validator):
+        raise ValueError(
+            "invalid packaged authoring corpus manifest: " + "; ".join(validation_errors)
+        )
+    return cast(dict[str, Any], decoded_manifest)
+
+
+def _benchmark_case(case_document: dict[str, Any]) -> AuthoringBenchmarkCase:
+    required_constructs = tuple(
+        (
+            RequiredFlowConstruct.expecting(
+                cast(str, required_construct["identifier"]),
+                cast(str, required_construct["pointer_pattern"]),
+                required_construct["expected"],
+            )
+            if "expected" in required_construct
+            else RequiredFlowConstruct(
+                identifier=cast(str, required_construct["identifier"]),
+                pointer_pattern=cast(str, required_construct["pointer_pattern"]),
+            )
+        )
+        for required_construct in cast(
+            list[dict[str, Any]],
+            case_document["required_constructs"],
+        )
+    )
+    return AuthoringBenchmarkCase.expecting_flow(
+        identifier=cast(str, case_document["identifier"]),
+        prompt=cast(str, case_document["prompt"]),
+        expected_flow=case_document["source"],
+        feature_tags=tuple(cast(list[str], case_document["feature_tags"])),
+        required_constructs=required_constructs,
+    )
+
+
+@dataclass(frozen=True)
+class AuthoringCorpus:
+    """Immutable cases and content identity for one benchmark corpus."""
+
+    format_identifier: str
+    case_format_identifier: str
+    identifier: str
+    digest: str
+    cases: tuple[AuthoringBenchmarkCase, ...]
+
+    def __post_init__(self) -> None:
+        if self.format_identifier != AUTHORING_CORPUS_FORMAT:
+            raise ValueError("unknown authoring corpus format")
+        if self.case_format_identifier != AUTHORING_CASE_FORMAT:
+            raise ValueError("unknown authoring case format")
+        if not _IDENTIFIER_PATTERN.fullmatch(self.identifier):
+            raise ValueError("authoring corpus identifier is invalid")
+        if not _DIGEST_PATTERN.fullmatch(self.digest):
+            raise ValueError("authoring corpus digest must be lowercase SHA-256")
+        case_identifiers = tuple(benchmark_case.identifier for benchmark_case in self.cases)
+        if not case_identifiers:
+            raise ValueError("authoring corpus requires at least one case")
+        if case_identifiers != tuple(sorted(case_identifiers)):
+            raise ValueError("authoring corpus cases must be sorted by identifier")
+        if len(set(case_identifiers)) != len(case_identifiers):
+            raise ValueError("authoring corpus case identifiers must be unique")
+
+    def metadata(self) -> dict[str, object]:
+        """Return deterministic corpus provenance without reference answers."""
+
+        return {
+            "format": self.format_identifier,
+            "case_format": self.case_format_identifier,
+            "identifier": self.identifier,
+            "digest": self.digest,
+            "case_identifiers": [benchmark_case.identifier for benchmark_case in self.cases],
+        }
+
+
+def _load_authoring_corpus(
+    corpus_directory: Traversable,
+    *,
+    expected_identifier: str,
+) -> AuthoringCorpus:
+    manifest_document = _load_manifest(corpus_directory)
+    if manifest_document["identifier"] != expected_identifier:
+        raise ValueError("authoring corpus manifest identifier is not the expected contract")
+    manifest_cases = cast(list[dict[str, Any]], manifest_document["cases"])
+    manifest_identifiers = tuple(
+        cast(str, case_contract["identifier"]) for case_contract in manifest_cases
+    )
+    manifest_paths = tuple(cast(str, case_contract["path"]) for case_contract in manifest_cases)
+    if manifest_identifiers != tuple(sorted(manifest_identifiers)):
+        raise ValueError("authoring corpus manifest cases must be sorted by identifier")
+    if len(set(manifest_identifiers)) != len(manifest_identifiers):
+        raise ValueError("authoring corpus manifest case identifiers must be unique")
+    if len(set(manifest_paths)) != len(manifest_paths):
+        raise ValueError("authoring corpus manifest case paths must be unique")
+    packaged_case_paths = {
+        child_resource.name
+        for child_resource in corpus_directory.iterdir()
+        if child_resource.is_file() and child_resource.name.endswith(".case.json")
+    }
+    if packaged_case_paths != set(manifest_paths):
+        missing_paths = sorted(set(manifest_paths) - packaged_case_paths)
+        unlisted_paths = sorted(packaged_case_paths - set(manifest_paths))
+        raise ValueError(
+            "authoring corpus manifest membership mismatch: "
+            f"missing={missing_paths}, unlisted={unlisted_paths}"
+        )
+
+    case_documents: list[dict[str, Any]] = []
+    for case_contract in manifest_cases:
+        case_path = cast(str, case_contract["path"])
+        case_resource = corpus_directory.joinpath(case_path)
+        serialized_case = case_resource.read_bytes()
+        observed_digest = hashlib.sha256(serialized_case).hexdigest()
+        expected_digest = cast(str, case_contract["sha256"])
+        if observed_digest != expected_digest:
+            raise ValueError(f"packaged authoring case failed integrity verification: {case_path}")
+        case_document = _load_case_document(case_resource)
+        if case_document["identifier"] != case_contract["identifier"]:
+            raise ValueError(
+                f"packaged authoring case identifier disagrees with manifest: {case_path}"
+            )
+        case_documents.append(case_document)
+
+    try:
+        benchmark_cases = tuple(
+            sorted(
+                (_benchmark_case(case_document) for case_document in case_documents),
+                key=lambda benchmark_case: benchmark_case.identifier,
+            )
+        )
+    except (ValidationError, ValueError) as case_contract_error:
+        raise ValueError(
+            "authoring corpus contains an invalid reference flow"
+        ) from case_contract_error
+    contract_document = {
+        "format": AUTHORING_CORPUS_FORMAT,
+        "case_format": AUTHORING_CASE_FORMAT,
+        "identifier": manifest_document["identifier"],
+        "cases": case_documents,
+        "resolved_acceptance": [
+            {
+                "identifier": benchmark_case.identifier,
+                "contract": benchmark_case.authoring_task().acceptance.to_dict(),
+            }
+            for benchmark_case in benchmark_cases
+        ],
+    }
+    corpus_digest = hashlib.sha256(_canonical_json(contract_document).encode("utf-8")).hexdigest()
+    return AuthoringCorpus(
+        format_identifier=AUTHORING_CORPUS_FORMAT,
+        case_format_identifier=AUTHORING_CASE_FORMAT,
+        identifier=cast(str, manifest_document["identifier"]),
+        digest=corpus_digest,
+        cases=benchmark_cases,
+    )
+
+
+def load_reference_authoring_corpus() -> AuthoringCorpus:
+    """Load and validate the immutable corpus distributed with flowspec2."""
+
+    global _reference_corpus_cache
+    if _reference_corpus_cache is not None:
+        return _reference_corpus_cache
+
+    corpus_directory = files("flowspec2.authoring").joinpath("corpus")
+    _reference_corpus_cache = _load_authoring_corpus(
+        corpus_directory,
+        expected_identifier=REFERENCE_AUTHORING_CORPUS_ID,
+    )
+    return _reference_corpus_cache