flowspec2 1.0.0__py3-none-any.whl

flowspec2/__init__.py

@@ -0,0 +1,105 @@
+"""flowspec2 — a JSON conversational-flow format compiled to a LangGraph StateGraph.
+
+Public API::
+
+    from flowspec2 import FlowRuntime, check_flow, load_flow, validate_flow, schema
+    from flowspec2 import ServiceState, AgentResponse, compile_flow
+
+See ``docs/DESIGN.md`` for the format rationale and the construct→primitive map.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import version as package_version
+
+from .backends import BackendConfig, make_registry
+from .checker import check_flow, check_json, structural_diagnostics
+from .clock import UtcClock
+from .compiler import CompiledFlow, compile_flow
+from .diagnostics import DiagnosticLocation, FlowCheckReport, FlowDiagnostic
+from .ir import (
+    FLOW_IR_FORMAT,
+    FlowIR,
+    FlowNode,
+    FlowReference,
+    FlowSlot,
+    FlowTransition,
+    build_flow_ir,
+    normalize_flow,
+)
+from .models import AgentResponse, AwaitResumeProvenance, ServiceMetadata, ServiceState
+from .observability import SnowflakeIdGenerator
+from .profiles import FlowProfile, reference_profile
+from .runtime import FlowRuntime
+from .schema import load_flow, schema, validate_flow
+from .semantics import FlowLinkError, semantic_diagnostics
+from .state_migration import (
+    FlowStateContract,
+    StateCopy,
+    StateDefault,
+    StateMigrationError,
+    StateMigrationLossReport,
+    StateMigrationPlan,
+    StateMigrationResult,
+    StatePath,
+    migrate_service_state,
+)
+from .subflows import SubflowDefinition, SubflowRegistry, default_subflows
+from .tools import ToolDefinition, ToolEffects, ToolRegistry, default_tool_registry
+
+__version__ = package_version("flowspec2")
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "FlowRuntime",
+    "FlowLinkError",
+    "FlowCheckReport",
+    "FlowDiagnostic",
+    "DiagnosticLocation",
+    "CompiledFlow",
+    "check_flow",
+    "check_json",
+    "structural_diagnostics",
+    "semantic_diagnostics",
+    "migrate_service_state",
+    "normalize_flow",
+    "build_flow_ir",
+    "FlowIR",
+    "FLOW_IR_FORMAT",
+    "FlowNode",
+    "FlowSlot",
+    "FlowReference",
+    "FlowTransition",
+    "FlowStateContract",
+    "FlowProfile",
+    "reference_profile",
+    "compile_flow",
+    "load_flow",
+    "validate_flow",
+    "schema",
+    "ServiceState",
+    "AgentResponse",
+    "AwaitResumeProvenance",
+    "ServiceMetadata",
+    "StatePath",
+    "StateCopy",
+    "StateDefault",
+    "StateMigrationPlan",
+    "StateMigrationResult",
+    "StateMigrationLossReport",
+    "StateMigrationError",
+    "SnowflakeIdGenerator",
+    "ToolRegistry",
+    "ToolDefinition",
+    "ToolEffects",
+    "UtcClock",
+    "default_tool_registry",
+    "SubflowRegistry",
+    "SubflowDefinition",
+    "default_subflows",
+    "BackendConfig",
+    "make_registry",
+    "__version__",
+]

flowspec2/authoring/__init__.py

@@ -0,0 +1,275 @@
+"""Provider-neutral evaluation contracts for AI-authored flow sources."""
+
+from .benchmark import (
+    AUTHORING_ACCEPTANCE_FORMAT,
+    DEFAULT_FORBIDDEN_CONSTRUCTS,
+    DEFAULT_VARIABLE_POINTER_PATTERNS,
+    TOKEN_PROXY_BYTES_PER_UNIT,
+    TOKEN_PROXY_METHOD,
+    AcceptanceExpectation,
+    AuthoredSource,
+    AuthoringAcceptanceContract,
+    AuthoringAttempt,
+    AuthoringAuthor,
+    AuthoringBenchmarkCase,
+    AuthoringBenchmarkLimits,
+    AuthoringBenchmarkReport,
+    AuthoringBenchmarkResult,
+    AuthoringRequest,
+    AuthoringSourceAdapter,
+    AuthoringTask,
+    FlowSpec2JsonAdapter,
+    ForbiddenConstruct,
+    RequiredFlowConstruct,
+    SourceAdaptation,
+    acceptance_diagnostics,
+    authoring_acceptance_for_flow,
+    observe_authoring_flow,
+    replay_authoring_benchmark,
+    run_authoring_benchmark,
+)
+from .corpus import (
+    AUTHORING_CASE_FORMAT,
+    AUTHORING_CORPUS_FORMAT,
+    REFERENCE_AUTHORING_CORPUS_ID,
+    AuthoringCorpus,
+    load_reference_authoring_corpus,
+)
+from .ctk import (
+    CTK_CORPUS_FORMAT,
+    CTK_REPORT_FORMAT,
+    CTK_VERSION,
+    CtkCase,
+    CtkCaseReport,
+    CtkCorpus,
+    CtkDiagnosticOracle,
+    CtkIrOracle,
+    CtkReport,
+    CtkTurn,
+    load_ctk_corpus,
+    run_ctk_corpus,
+)
+from .evidence import (
+    AUTHORING_EVIDENCE_FORMAT,
+    SOURCE_ADAPTER_CONTRACT,
+    AuthoringBenchmarkEvidence,
+    AuthoringCapture,
+    AuthoringProviderProvenance,
+    RecordingAuthor,
+)
+from .evidence_signature import (
+    AUTHORING_EVIDENCE_SIGNATURE_ALGORITHM,
+    AUTHORING_EVIDENCE_SIGNATURE_FORMAT,
+    AuthoringEvidenceAuthentication,
+    AuthoringEvidenceSignature,
+    authoring_evidence_signature_schema,
+    sign_authoring_evidence,
+    verify_authoring_evidence_signature,
+)
+from .evidence_verification import (
+    AuthoringEvidenceVerification,
+    authoring_evidence_schema,
+    verify_authoring_evidence,
+)
+from .gemini import (
+    DEFAULT_GEMINI_AUTHOR_MODEL,
+    DEFAULT_GEMINI_AUTHOR_TIMEOUT_MILLISECONDS,
+    GEMINI_AUTHOR_PROMPT_DIGEST,
+    GEMINI_AUTHOR_PROMPT_FORMAT,
+    GeminiAuthor,
+    GeminiAuthorError,
+)
+from .operational import (
+    AUTHORING_OPERATIONAL_EVIDENCE_FORMAT,
+    OPERATIONAL_CORPUS_FORMAT,
+    OPERATIONAL_EVIDENCE_CLASSIFICATION,
+    OPERATIONAL_PROBE_FORMAT,
+    OPERATIONAL_PROMPT_DIGEST,
+    OPERATIONAL_PROMPT_FORMAT,
+    AuthoringOperationalEvidence,
+    AuthoringOperationalEvidenceVerification,
+    OperationalCorpus,
+    OperationalModelResponse,
+    OperationalProbe,
+    OperationalProbeRequest,
+    authoring_operational_evidence_schema,
+    load_reference_operational_corpus,
+    run_authoring_operational_evidence,
+    verify_authoring_operational_evidence,
+)
+from .operational_providers import (
+    DEFAULT_GEMINI_OPERATIONAL_MODEL,
+    DEFAULT_GEMINI_OPERATIONAL_TIMEOUT_MILLISECONDS,
+    GeminiOperationalExecutor,
+    OperationalProviderError,
+)
+from .presentation_review import (
+    PRESENTATION_REVIEW_DRAFT_FORMAT,
+    PRESENTATION_REVIEW_FORMAT,
+    PRESENTATION_RUBRIC_CRITERIA,
+    PRESENTATION_RUBRIC_DIGEST,
+    PRESENTATION_RUBRIC_FORMAT,
+    PRESENTATION_RUBRIC_IDENTIFIER,
+    AuthoringPresentationReview,
+    PresentationAssessment,
+    PresentationCriterionResult,
+    PresentationReviewDraft,
+    PresentationReviewDraftSubject,
+    PresentationReviewTaskContext,
+    PresentationReviewVerification,
+    PresentationRubricCriterion,
+    PresentationSubject,
+    finalize_presentation_review_draft,
+    presentation_review_draft,
+    presentation_review_schema,
+    presentation_rubric,
+    verify_presentation_review,
+)
+from .presentation_review_signature import (
+    AUTHORING_PRESENTATION_REVIEW_SIGNATURE_ALGORITHM,
+    AUTHORING_PRESENTATION_REVIEW_SIGNATURE_FORMAT,
+    AuthoringPresentationReviewAuthentication,
+    AuthoringPresentationReviewSignature,
+    AuthoringPromotionVerification,
+    authoring_presentation_review_signature_schema,
+    sign_presentation_review,
+    verify_authoring_promotion,
+    verify_presentation_review_signature,
+)
+from .projection import (
+    AUTHORING_PROJECTION_FORMAT,
+    AUTHORING_PROJECTION_VERSION,
+    AuthoringProjectionArtifact,
+    AuthoringProjectionError,
+    authoring_projection,
+    authoring_projection_diagnostics,
+    canonical_projection_json,
+    lower_authoring_projection,
+    project_flow_document,
+)
+
+__all__ = [
+    "AUTHORING_ACCEPTANCE_FORMAT",
+    "DEFAULT_FORBIDDEN_CONSTRUCTS",
+    "DEFAULT_VARIABLE_POINTER_PATTERNS",
+    "DEFAULT_GEMINI_AUTHOR_MODEL",
+    "DEFAULT_GEMINI_AUTHOR_TIMEOUT_MILLISECONDS",
+    "TOKEN_PROXY_BYTES_PER_UNIT",
+    "TOKEN_PROXY_METHOD",
+    "AUTHORING_PROJECTION_FORMAT",
+    "AUTHORING_PROJECTION_VERSION",
+    "AUTHORING_PRESENTATION_REVIEW_SIGNATURE_ALGORITHM",
+    "AUTHORING_PRESENTATION_REVIEW_SIGNATURE_FORMAT",
+    "AUTHORING_CASE_FORMAT",
+    "AUTHORING_CORPUS_FORMAT",
+    "AUTHORING_EVIDENCE_FORMAT",
+    "AUTHORING_EVIDENCE_SIGNATURE_ALGORITHM",
+    "AUTHORING_EVIDENCE_SIGNATURE_FORMAT",
+    "AUTHORING_OPERATIONAL_EVIDENCE_FORMAT",
+    "CTK_CORPUS_FORMAT",
+    "CTK_REPORT_FORMAT",
+    "CTK_VERSION",
+    "AcceptanceExpectation",
+    "AuthoringAttempt",
+    "AuthoringAcceptanceContract",
+    "AuthoredSource",
+    "AuthoringBenchmarkEvidence",
+    "AuthoringEvidenceVerification",
+    "AuthoringEvidenceAuthentication",
+    "AuthoringEvidenceSignature",
+    "AuthoringAuthor",
+    "AuthoringBenchmarkCase",
+    "AuthoringBenchmarkLimits",
+    "AuthoringBenchmarkReport",
+    "AuthoringBenchmarkResult",
+    "AuthoringCapture",
+    "AuthoringCorpus",
+    "AuthoringProviderProvenance",
+    "AuthoringRequest",
+    "AuthoringSourceAdapter",
+    "AuthoringTask",
+    "AuthoringProjectionArtifact",
+    "AuthoringProjectionError",
+    "AuthoringPresentationReview",
+    "AuthoringPresentationReviewAuthentication",
+    "AuthoringPresentationReviewSignature",
+    "AuthoringOperationalEvidence",
+    "AuthoringOperationalEvidenceVerification",
+    "AuthoringPromotionVerification",
+    "CtkCase",
+    "CtkCaseReport",
+    "CtkCorpus",
+    "CtkDiagnosticOracle",
+    "CtkIrOracle",
+    "CtkReport",
+    "CtkTurn",
+    "FlowSpec2JsonAdapter",
+    "ForbiddenConstruct",
+    "RequiredFlowConstruct",
+    "RecordingAuthor",
+    "PRESENTATION_REVIEW_DRAFT_FORMAT",
+    "PRESENTATION_REVIEW_FORMAT",
+    "PRESENTATION_RUBRIC_CRITERIA",
+    "PRESENTATION_RUBRIC_DIGEST",
+    "PRESENTATION_RUBRIC_FORMAT",
+    "PRESENTATION_RUBRIC_IDENTIFIER",
+    "OPERATIONAL_CORPUS_FORMAT",
+    "OPERATIONAL_EVIDENCE_CLASSIFICATION",
+    "OPERATIONAL_PROBE_FORMAT",
+    "OPERATIONAL_PROMPT_DIGEST",
+    "OPERATIONAL_PROMPT_FORMAT",
+    "OperationalCorpus",
+    "OperationalModelResponse",
+    "OperationalProbe",
+    "OperationalProbeRequest",
+    "OperationalProviderError",
+    "PresentationAssessment",
+    "PresentationCriterionResult",
+    "PresentationReviewDraft",
+    "PresentationReviewDraftSubject",
+    "PresentationReviewTaskContext",
+    "PresentationReviewVerification",
+    "PresentationRubricCriterion",
+    "PresentationSubject",
+    "REFERENCE_AUTHORING_CORPUS_ID",
+    "SOURCE_ADAPTER_CONTRACT",
+    "SourceAdaptation",
+    "acceptance_diagnostics",
+    "authoring_acceptance_for_flow",
+    "authoring_projection",
+    "authoring_projection_diagnostics",
+    "authoring_evidence_schema",
+    "authoring_evidence_signature_schema",
+    "authoring_operational_evidence_schema",
+    "authoring_presentation_review_signature_schema",
+    "canonical_projection_json",
+    "finalize_presentation_review_draft",
+    "load_ctk_corpus",
+    "load_reference_authoring_corpus",
+    "load_reference_operational_corpus",
+    "lower_authoring_projection",
+    "observe_authoring_flow",
+    "presentation_review_draft",
+    "presentation_review_schema",
+    "presentation_rubric",
+    "project_flow_document",
+    "replay_authoring_benchmark",
+    "run_authoring_benchmark",
+    "run_authoring_operational_evidence",
+    "run_ctk_corpus",
+    "sign_authoring_evidence",
+    "sign_presentation_review",
+    "verify_authoring_promotion",
+    "verify_authoring_evidence",
+    "verify_authoring_evidence_signature",
+    "verify_authoring_operational_evidence",
+    "verify_presentation_review",
+    "verify_presentation_review_signature",
+    "GEMINI_AUTHOR_PROMPT_DIGEST",
+    "GEMINI_AUTHOR_PROMPT_FORMAT",
+    "GeminiAuthor",
+    "GeminiAuthorError",
+    "GeminiOperationalExecutor",
+    "DEFAULT_GEMINI_OPERATIONAL_MODEL",
+    "DEFAULT_GEMINI_OPERATIONAL_TIMEOUT_MILLISECONDS",
+]

flowspec2/authoring/authoring-evidence-signature.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wllsena.github.io/flowspec2/schemas/authoring-evidence-signature-1.json",
+  "title": "FlowSpec2 authoring evidence signature",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "algorithm",
+    "evidence_digest",
+    "key_id",
+    "signature"
+  ],
+  "properties": {
+    "format": {
+      "const": "flowspec2/authoring-evidence-signature@1"
+    },
+    "algorithm": {
+      "const": "ed25519"
+    },
+    "evidence_digest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "key_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9+/]{86}==$"
+    }
+  }
+}