metaspn-gates 0.1.0__tar.gz

metaspn_gates-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: metaspn-gates
+Version: 0.1.0
+Summary: Config-driven gate and state machine evaluator for MetaSPN entity pipelines
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/leoguinan/metaspn-gates
+Project-URL: Repository, https://github.com/leoguinan/metaspn-gates
+Project-URL: Issues, https://github.com/leoguinan/metaspn-gates/issues
+Keywords: metaspn,state-machine,gates,workflow
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: metaspn-schemas==0.1.0
+
+# metaspn-gates
+
+`metaspn-gates` is a config-driven gate + state-machine evaluator for MetaSPN entity pipelines.
+
+## Current implementation (v0.1 seed)
+
+- Deterministic gate evaluation from config
+- Hard requirements and soft thresholds
+- Per-gate per-entity cooldown checks
+- Transition attempt snapshots
+- Transition application + task emissions
+- Config parsing and validation from mapping
+- `metaspn-schemas` integration hooks (currently used for typed emission shaping)
+- Optional `metaspn-schemas` emission shaping (`Task` + `EmissionEnvelope`)
+
+## Public API
+
+- `evaluate_gates(config, entity_state, features, now)`
+- `apply_decisions(entity_state, decisions, caused_by=None)`
+- `parse_state_machine_config(payload)`
+- `load_state_machine_config(path)`
+
+## Notes
+
+- `load_state_machine_config` can use `metaspn_schemas` parsing/validation hooks when exposed by that package version.
+- If `metaspn_schemas` is unavailable, it falls back to JSON parsing only.
+- Current dependency target: `metaspn-schemas==0.1.0`.
+- `apply_decisions(..., use_schema_envelopes=True)` attaches schema-shaped payloads when `entity_state.entity_id` is present.
+
+## Release
+
+- GitHub Actions workflow: `/Users/leoguinan/MetaSPN/metaspn-gates/.github/workflows/publish.yml`
+- Publish trigger: GitHub Release published (or manual `workflow_dispatch`)
+- Publishing method: PyPI Trusted Publishing via `pypa/gh-action-pypi-publish`
+
+### One-time setup
+
+1. In PyPI, create project `metaspn-gates` and configure Trusted Publisher for this GitHub repo/workflow.
+2. In GitHub, create environment `pypi` (optional protection rules supported).
+
+### Release flow
+
+1. Bump `/Users/leoguinan/MetaSPN/metaspn-gates/pyproject.toml` version.
+2. Tag and push a release commit.
+3. Publish a GitHub Release for that tag.
+4. `publish.yml` builds and uploads to PyPI.

metaspn_gates-0.1.0/README.md

@@ -0,0 +1,46 @@
+# metaspn-gates
+
+`metaspn-gates` is a config-driven gate + state-machine evaluator for MetaSPN entity pipelines.
+
+## Current implementation (v0.1 seed)
+
+- Deterministic gate evaluation from config
+- Hard requirements and soft thresholds
+- Per-gate per-entity cooldown checks
+- Transition attempt snapshots
+- Transition application + task emissions
+- Config parsing and validation from mapping
+- `metaspn-schemas` integration hooks (currently used for typed emission shaping)
+- Optional `metaspn-schemas` emission shaping (`Task` + `EmissionEnvelope`)
+
+## Public API
+
+- `evaluate_gates(config, entity_state, features, now)`
+- `apply_decisions(entity_state, decisions, caused_by=None)`
+- `parse_state_machine_config(payload)`
+- `load_state_machine_config(path)`
+
+## Notes
+
+- `load_state_machine_config` can use `metaspn_schemas` parsing/validation hooks when exposed by that package version.
+- If `metaspn_schemas` is unavailable, it falls back to JSON parsing only.
+- Current dependency target: `metaspn-schemas==0.1.0`.
+- `apply_decisions(..., use_schema_envelopes=True)` attaches schema-shaped payloads when `entity_state.entity_id` is present.
+
+## Release
+
+- GitHub Actions workflow: `/Users/leoguinan/MetaSPN/metaspn-gates/.github/workflows/publish.yml`
+- Publish trigger: GitHub Release published (or manual `workflow_dispatch`)
+- Publishing method: PyPI Trusted Publishing via `pypa/gh-action-pypi-publish`
+
+### One-time setup
+
+1. In PyPI, create project `metaspn-gates` and configure Trusted Publisher for this GitHub repo/workflow.
+2. In GitHub, create environment `pypi` (optional protection rules supported).
+
+### Release flow
+
+1. Bump `/Users/leoguinan/MetaSPN/metaspn-gates/pyproject.toml` version.
+2. Tag and push a release commit.
+3. Publish a GitHub Release for that tag.
+4. `publish.yml` builds and uploads to PyPI.

metaspn_gates-0.1.0/metaspn_gates/__init__.py

@@ -0,0 +1,33 @@
+"""Config-driven gate and state-machine evaluator for MetaSPN pipelines."""
+
+from .models import (
+    GateConfig,
+    StateMachineConfig,
+    GateDecision,
+    TransitionApplied,
+    TransitionAttempted,
+    HardRequirement,
+    SoftThreshold,
+)
+from .config import ConfigError, load_state_machine_config, parse_state_machine_config, schemas_backend_available
+from .evaluator import Evaluator, evaluate_gates
+from .schemas import schemas_available
+from .applier import apply_decisions
+
+__all__ = [
+    "GateConfig",
+    "StateMachineConfig",
+    "GateDecision",
+    "TransitionApplied",
+    "TransitionAttempted",
+    "HardRequirement",
+    "SoftThreshold",
+    "Evaluator",
+    "evaluate_gates",
+    "apply_decisions",
+    "parse_state_machine_config",
+    "load_state_machine_config",
+    "schemas_backend_available",
+    "schemas_available",
+    "ConfigError",
+]

metaspn_gates-0.1.0/metaspn_gates/applier.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime
+from typing import Any, Iterable, Mapping
+
+from .models import GateDecision, TransitionApplied
+from .schemas import build_task_and_emission, schemas_available
+
+
+def apply_decisions(
+    entity_state: Mapping[str, Any],
+    decisions: Iterable[GateDecision],
+    caused_by: str | None = None,
+    use_schema_envelopes: bool = False,
+    default_task_priority: int = 50,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    new_state: dict[str, Any] = deepcopy(dict(entity_state))
+    emissions: list[dict[str, Any]] = []
+
+    attempts = new_state.setdefault("gate_attempts", [])
+    applied = new_state.setdefault("transitions_applied", [])
+    cooldowns = new_state.setdefault("gate_cooldowns", {})
+
+    if not isinstance(attempts, list):
+        raise ValueError("entity_state.gate_attempts must be a list when present")
+    if not isinstance(applied, list):
+        raise ValueError("entity_state.transitions_applied must be a list when present")
+    if not isinstance(cooldowns, dict):
+        raise ValueError("entity_state.gate_cooldowns must be an object when present")
+
+    for decision in decisions:
+        attempted = decision.transition_attempted
+        attempts.append(
+            {
+                "gate_id": attempted.gate_id,
+                "from": attempted.from_state,
+                "to": attempted.to_state,
+                "passed": attempted.passed,
+                "reason": attempted.reason,
+                "failed_requirement_id": attempted.failed_requirement_id,
+                "timestamp": attempted.timestamp.isoformat(),
+                "snapshot": deepcopy(dict(attempted.snapshot)),
+            }
+        )
+
+        if decision.passed:
+            new_state["state"] = decision.to_state
+
+            record = TransitionApplied(
+                gate_id=decision.gate_id,
+                from_state=decision.from_state,
+                to_state=decision.to_state,
+                caused_by=caused_by,
+                timestamp=attempted.timestamp,
+                snapshot=deepcopy(dict(attempted.snapshot)),
+            )
+            applied.append(
+                {
+                    "gate_id": record.gate_id,
+                    "from": record.from_state,
+                    "to": record.to_state,
+                    "caused_by": record.caused_by,
+                    "timestamp": record.timestamp.isoformat(),
+                    "snapshot": record.snapshot,
+                }
+            )
+
+            for task in decision.enqueue_tasks_on_pass:
+                base_emission: dict[str, Any] = {
+                    "kind": "task_enqueued",
+                    "task_id": task,
+                    "gate_id": decision.gate_id,
+                    "caused_by": caused_by,
+                    "timestamp": attempted.timestamp.isoformat(),
+                }
+                if use_schema_envelopes and schemas_available():
+                    entity_id = new_state.get("entity_id")
+                    if not isinstance(entity_id, str) or not entity_id:
+                        raise ValueError("entity_state.entity_id is required when use_schema_envelopes=True")
+                    schema_payload = build_task_and_emission(
+                        task_id=task,
+                        created_at=attempted.timestamp,
+                        caused_by=caused_by or "unknown",
+                        entity_id=entity_id,
+                        gate_id=decision.gate_id,
+                        emission_id=f"{decision.gate_id}:{task}:{int(attempted.timestamp.timestamp())}",
+                        priority=default_task_priority,
+                    )
+                    if schema_payload is not None:
+                        base_emission["schema"] = schema_payload
+                emissions.append(base_emission)
+
+        if decision.cooldown_on == "attempt" or (decision.cooldown_on == "pass" and decision.passed):
+            cooldowns[decision.gate_id] = decision.transition_attempted.timestamp.isoformat()
+
+    return new_state, emissions

metaspn_gates-0.1.0/metaspn_gates/config.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from .models import GateConfig, HardRequirement, SoftThreshold, StateMachineConfig
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def _mapping_from_object(value: Any) -> Mapping[str, Any] | None:
+    if isinstance(value, Mapping):
+        return value
+
+    for attr in ("model_dump", "dict", "to_dict"):
+        fn = getattr(value, attr, None)
+        if callable(fn):
+            candidate = fn()
+            if isinstance(candidate, Mapping):
+                return candidate
+    return None
+
+
+def _load_schemas_backend() -> Any | None:
+    try:
+        return importlib.import_module("metaspn_schemas")
+    except ImportError:
+        return None
+
+
+def schemas_backend_available() -> bool:
+    return _load_schemas_backend() is not None
+
+
+def _call_parser(fn: Callable[..., Any], raw: str, path: Path) -> Any:
+    last_exc: Exception | None = None
+    for args in ((raw, str(path)), (raw,), (str(path),), ()):
+        try:
+            return fn(*args)
+        except TypeError as exc:
+            last_exc = exc
+    if last_exc is not None:
+        raise last_exc
+    return None
+
+
+def _parse_with_schemas_backend(raw: str, path: Path, backend: Any) -> Mapping[str, Any] | None:
+    parser_names = (
+        "parse_state_machine_config_yaml",
+        "parse_state_machine_yaml",
+        "load_state_machine_config",
+        "load_yaml",
+        "parse_yaml",
+    )
+    for name in parser_names:
+        fn = getattr(backend, name, None)
+        if callable(fn):
+            parsed = _call_parser(fn, raw, path)
+            mapping = _mapping_from_object(parsed)
+            if mapping is not None:
+                return mapping
+    return None
+
+
+def _validate_with_schemas_backend(payload: Mapping[str, Any], backend: Any) -> Mapping[str, Any]:
+    validate_fn = getattr(backend, "validate_state_machine_config", None)
+    if callable(validate_fn):
+        try:
+            validated = validate_fn(payload)
+        except Exception as exc:  # pragma: no cover - backend-defined exception types
+            raise ConfigError(f"metaspn_schemas validation failed: {exc}") from exc
+        mapping = _mapping_from_object(validated)
+        if mapping is not None:
+            return mapping
+        return payload
+
+    schema_cls = getattr(backend, "StateMachineConfig", None)
+    if schema_cls is None:
+        return payload
+
+    model_validate = getattr(schema_cls, "model_validate", None)
+    parse_obj = getattr(schema_cls, "parse_obj", None)
+    try:
+        if callable(model_validate):
+            validated = model_validate(payload)
+        elif callable(parse_obj):
+            validated = parse_obj(payload)
+        else:
+            return payload
+    except Exception as exc:  # pragma: no cover - backend-defined exception types
+        raise ConfigError(f"metaspn_schemas validation failed: {exc}") from exc
+
+    mapping = _mapping_from_object(validated)
+    if mapping is not None:
+        return mapping
+    return payload
+
+
+def _require_str(mapping: Mapping[str, Any], key: str) -> str:
+    value = mapping.get(key)
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"{key} must be a non-empty string")
+    return value
+
+
+def _parse_hard_requirements(raw: Any) -> tuple[HardRequirement, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise ConfigError("hard_requirements must be a list")
+
+    parsed: list[HardRequirement] = []
+    for item in raw:
+        if not isinstance(item, Mapping):
+            raise ConfigError("hard requirement entries must be objects")
+        parsed.append(
+            HardRequirement(
+                requirement_id=_require_str(item, "requirement_id"),
+                field=_require_str(item, "field"),
+                op=_require_str(item, "op"),
+                value=item.get("value"),
+                source=item.get("source", "features"),
+            )
+        )
+    return tuple(parsed)
+
+
+def _parse_soft_thresholds(raw: Any) -> tuple[SoftThreshold, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise ConfigError("soft_thresholds must be a list")
+
+    parsed: list[SoftThreshold] = []
+    for item in raw:
+        if not isinstance(item, Mapping):
+            raise ConfigError("soft threshold entries must be objects")
+        if "value" not in item:
+            raise ConfigError("soft threshold value is required")
+        parsed.append(
+            SoftThreshold(
+                threshold_id=_require_str(item, "threshold_id"),
+                field=_require_str(item, "field"),
+                op=_require_str(item, "op"),
+                value=item["value"],
+                source=item.get("source", "features"),
+            )
+        )
+    return tuple(parsed)
+
+
+def parse_state_machine_config(payload: Mapping[str, Any]) -> StateMachineConfig:
+    backend = _load_schemas_backend()
+    if backend is not None:
+        payload = _validate_with_schemas_backend(payload, backend)
+
+    config_version = _require_str(payload, "config_version")
+
+    raw_gates = payload.get("gates")
+    if not isinstance(raw_gates, list) or not raw_gates:
+        raise ConfigError("gates must be a non-empty list")
+
+    gates: list[GateConfig] = []
+    gate_ids: set[str] = set()
+
+    for gate in raw_gates:
+        if not isinstance(gate, Mapping):
+            raise ConfigError("gate entries must be objects")
+
+        gate_id = _require_str(gate, "gate_id")
+        if gate_id in gate_ids:
+            raise ConfigError(f"duplicate gate_id: {gate_id}")
+        gate_ids.add(gate_id)
+
+        raw_tasks = gate.get("enqueue_tasks_on_pass") or []
+        if not isinstance(raw_tasks, list) or not all(isinstance(t, str) and t for t in raw_tasks):
+            raise ConfigError("enqueue_tasks_on_pass must be a list of non-empty strings")
+
+        raw_taxonomy = gate.get("failure_taxonomy") or {}
+        if not isinstance(raw_taxonomy, Mapping):
+            raise ConfigError("failure_taxonomy must be an object")
+
+        cooldown_seconds = gate.get("cooldown_seconds", 0)
+        if not isinstance(cooldown_seconds, int) or cooldown_seconds < 0:
+            raise ConfigError("cooldown_seconds must be a non-negative integer")
+
+        cooldown_on = gate.get("cooldown_on", "pass")
+        if cooldown_on not in {"pass", "attempt"}:
+            raise ConfigError("cooldown_on must be either 'pass' or 'attempt'")
+
+        min_soft_passed = gate.get("min_soft_passed")
+        if min_soft_passed is not None and (not isinstance(min_soft_passed, int) or min_soft_passed < 0):
+            raise ConfigError("min_soft_passed must be a non-negative integer when provided")
+
+        parsed = GateConfig(
+            gate_id=gate_id,
+            version=_require_str(gate, "version"),
+            track=gate.get("track"),
+            from_state=_require_str(gate, "from"),
+            to_state=_require_str(gate, "to"),
+            hard_requirements=_parse_hard_requirements(gate.get("hard_requirements")),
+            soft_thresholds=_parse_soft_thresholds(gate.get("soft_thresholds")),
+            min_soft_passed=min_soft_passed,
+            cooldown_seconds=cooldown_seconds,
+            cooldown_on=cooldown_on,
+            enqueue_tasks_on_pass=tuple(raw_tasks),
+            failure_taxonomy={str(k): str(v) for k, v in raw_taxonomy.items()},
+        )
+
+        if parsed.min_soft_passed is not None and parsed.min_soft_passed > len(parsed.soft_thresholds):
+            raise ConfigError("min_soft_passed cannot exceed number of soft_thresholds")
+
+        gates.append(parsed)
+
+    # Stable deterministic order.
+    gates.sort(key=lambda g: (g.track or "", g.from_state, g.gate_id))
+
+    return StateMachineConfig(config_version=config_version, gates=tuple(gates))
+
+
+def load_state_machine_config(path: str | Path) -> StateMachineConfig:
+    """Loads config using metaspn_schemas when available, otherwise JSON fallback."""
+
+    path = Path(path)
+    raw = path.read_text(encoding="utf-8")
+
+    backend = _load_schemas_backend()
+    payload: Mapping[str, Any] | None = None
+    if backend is not None:
+        payload = _parse_with_schemas_backend(raw, path, backend)
+
+    if payload is None:
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ConfigError(
+                "Config parsing failed. Install metaspn-schemas for YAML parsing, or provide JSON content."
+            ) from exc
+        payload = _mapping_from_object(parsed)
+
+    if payload is None or not isinstance(payload, Mapping):
+        raise ConfigError("top-level config must be an object")
+
+    return parse_state_machine_config(payload)

metaspn_gates-0.1.0/metaspn_gates/evaluator.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime, timedelta, timezone
+from typing import Any, Mapping
+
+from .models import GateDecision, GateConfig, StateMachineConfig, TransitionAttempted
+
+
+def _get_path(mapping: Mapping[str, Any], path: str) -> tuple[bool, Any]:
+    current: Any = mapping
+    for key in path.split("."):
+        if not isinstance(current, Mapping) or key not in current:
+            return False, None
+        current = current[key]
+    return True, current
+
+
+def _compare(op: str, actual: Any, expected: Any) -> bool:
+    if op == "eq":
+        return actual == expected
+    if op == "ne":
+        return actual != expected
+    if op == "gt":
+        return actual > expected
+    if op == "gte":
+        return actual >= expected
+    if op == "lt":
+        return actual < expected
+    if op == "lte":
+        return actual <= expected
+    if op == "in":
+        return actual in expected
+    if op == "not_in":
+        return actual not in expected
+    raise ValueError(f"unsupported operator: {op}")
+
+
+def _requirement_passed(source: Mapping[str, Any], field: str, op: str, value: Any) -> bool:
+    if op == "exists":
+        exists, _ = _get_path(source, field)
+        return exists
+    if op == "not_exists":
+        exists, _ = _get_path(source, field)
+        return not exists
+
+    exists, actual = _get_path(source, field)
+    if not exists:
+        return False
+    return _compare(op, actual, value)
+
+
+def _check_cooldown(gate: GateConfig, entity_state: Mapping[str, Any], now: datetime) -> bool:
+    if gate.cooldown_seconds <= 0:
+        return False
+
+    cooldowns = entity_state.get("gate_cooldowns")
+    if not isinstance(cooldowns, Mapping):
+        return False
+
+    raw_last = cooldowns.get(gate.gate_id)
+    if raw_last is None:
+        return False
+
+    if isinstance(raw_last, str):
+        last_attempt = datetime.fromisoformat(raw_last)
+    elif isinstance(raw_last, datetime):
+        last_attempt = raw_last
+    else:
+        return False
+
+    if last_attempt.tzinfo is None:
+        last_attempt = last_attempt.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    return now < (last_attempt + timedelta(seconds=gate.cooldown_seconds))
+
+
+def _matches_state(gate: GateConfig, entity_state: Mapping[str, Any]) -> bool:
+    if entity_state.get("state") != gate.from_state:
+        return False
+
+    if gate.track is None:
+        return True
+    return entity_state.get("track") == gate.track
+
+
+class Evaluator:
+    def evaluate_gates(
+        self,
+        config: StateMachineConfig,
+        entity_state: Mapping[str, Any],
+        features: Mapping[str, Any],
+        now: datetime,
+    ) -> list[GateDecision]:
+        return evaluate_gates(config, entity_state, features, now)
+
+
+def evaluate_gates(
+    config: StateMachineConfig,
+    entity_state: Mapping[str, Any],
+    features: Mapping[str, Any],
+    now: datetime,
+) -> list[GateDecision]:
+    decisions: list[GateDecision] = []
+
+    failure_overrides = entity_state.get("failure_overrides")
+    if not isinstance(failure_overrides, Mapping):
+        failure_overrides = {}
+
+    for gate in config.gates:
+        if not _matches_state(gate, entity_state):
+            continue
+
+        cooldown_active = _check_cooldown(gate, entity_state, now)
+        passed = not cooldown_active
+        reason: str | None = "cooldown_active" if cooldown_active else None
+        failed_requirement_id: str | None = None
+
+        feature_source = features
+        entity_source = entity_state
+
+        # Hard requirements short-circuit on first failure.
+        if passed:
+            for requirement in gate.hard_requirements:
+                source = entity_source if requirement.source == "entity" else feature_source
+                if not _requirement_passed(source, requirement.field, requirement.op, requirement.value):
+                    passed = False
+                    failed_requirement_id = requirement.requirement_id
+                    reason = gate.failure_taxonomy.get(requirement.requirement_id, "hard_requirement_failed")
+                    break
+
+        if passed and gate.soft_thresholds:
+            soft_passes = 0
+            for threshold in gate.soft_thresholds:
+                source = entity_source if threshold.source == "entity" else feature_source
+                if _requirement_passed(source, threshold.field, threshold.op, threshold.value):
+                    soft_passes += 1
+
+            needed = gate.min_soft_passed if gate.min_soft_passed is not None else len(gate.soft_thresholds)
+            if soft_passes < needed:
+                passed = False
+                reason = "soft_threshold_failed"
+
+        override_reason = failure_overrides.get(gate.gate_id)
+        if not passed and isinstance(override_reason, str) and override_reason:
+            reason = override_reason
+
+        snapshot = {
+            "feature_snapshot": deepcopy(dict(features)),
+            "entity_snapshot": deepcopy(dict(entity_state)),
+            "config_version": config.config_version,
+            "gate_version": gate.version,
+            "timestamp": now.isoformat(),
+            "cooldown_active": cooldown_active,
+        }
+
+        transition_attempted = TransitionAttempted(
+            gate_id=gate.gate_id,
+            from_state=gate.from_state,
+            to_state=gate.to_state,
+            passed=passed,
+            timestamp=now,
+            reason=reason,
+            failed_requirement_id=failed_requirement_id,
+            snapshot=snapshot,
+        )
+
+        decisions.append(
+            GateDecision(
+                gate_id=gate.gate_id,
+                gate_version=gate.version,
+                track=gate.track,
+                from_state=gate.from_state,
+                to_state=gate.to_state,
+                passed=passed,
+                reason=reason,
+                failed_requirement_id=failed_requirement_id,
+                cooldown_active=cooldown_active,
+                cooldown_on=gate.cooldown_on,
+                enqueue_tasks_on_pass=gate.enqueue_tasks_on_pass,
+                transition_attempted=transition_attempted,
+            )
+        )
+
+    return decisions

metaspn_gates-0.1.0/metaspn_gates/models.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class HardRequirement:
+    requirement_id: str
+    field: str
+    op: str
+    value: Any = None
+    source: str = "features"
+
+
+@dataclass(frozen=True)
+class SoftThreshold:
+    threshold_id: str
+    field: str
+    op: str
+    value: Any
+    source: str = "features"
+
+
+@dataclass(frozen=True)
+class GateConfig:
+    gate_id: str
+    version: str
+    track: str | None
+    from_state: str
+    to_state: str
+    hard_requirements: tuple[HardRequirement, ...] = field(default_factory=tuple)
+    soft_thresholds: tuple[SoftThreshold, ...] = field(default_factory=tuple)
+    min_soft_passed: int | None = None
+    cooldown_seconds: int = 0
+    cooldown_on: str = "pass"  # pass | attempt
+    enqueue_tasks_on_pass: tuple[str, ...] = field(default_factory=tuple)
+    failure_taxonomy: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class StateMachineConfig:
+    config_version: str
+    gates: tuple[GateConfig, ...]
+
+
+@dataclass(frozen=True)
+class TransitionAttempted:
+    gate_id: str
+    from_state: str
+    to_state: str
+    passed: bool
+    timestamp: datetime
+    reason: str | None
+    failed_requirement_id: str | None
+    snapshot: Mapping[str, Any]
+
+
+@dataclass(frozen=True)
+class GateDecision:
+    gate_id: str
+    gate_version: str
+    track: str | None
+    from_state: str
+    to_state: str
+    passed: bool
+    reason: str | None
+    failed_requirement_id: str | None
+    cooldown_active: bool
+    cooldown_on: str
+    enqueue_tasks_on_pass: tuple[str, ...]
+    transition_attempted: TransitionAttempted
+
+
+@dataclass(frozen=True)
+class TransitionApplied:
+    gate_id: str
+    from_state: str
+    to_state: str
+    caused_by: str | None
+    timestamp: datetime
+    snapshot: Mapping[str, Any]

metaspn_gates-0.1.0/metaspn_gates/schemas.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any, Mapping
+
+
+def _load_backend() -> Any | None:
+    try:
+        return importlib.import_module("metaspn_schemas")
+    except ImportError:
+        return None
+
+
+def schemas_available() -> bool:
+    return _load_backend() is not None
+
+
+def _to_dict(value: Any) -> Mapping[str, Any]:
+    if isinstance(value, Mapping):
+        return value
+    to_dict = getattr(value, "to_dict", None)
+    if callable(to_dict):
+        out = to_dict()
+        if isinstance(out, Mapping):
+            return out
+    raise TypeError("schema object is not serializable to mapping")
+
+
+def build_task_and_emission(
+    *,
+    task_id: str,
+    created_at,
+    caused_by: str,
+    entity_id: str,
+    gate_id: str,
+    emission_id: str,
+    priority: int = 50,
+) -> dict[str, Any] | None:
+    backend = _load_backend()
+    if backend is None:
+        return None
+
+    entity_ref = backend.EntityRef(ref_type="entity_id", value=entity_id)
+    task = backend.Task(
+        task_id=task_id,
+        task_type=task_id,
+        created_at=created_at,
+        priority=priority,
+        entity_ref=entity_ref,
+        context={"gate_id": gate_id, "caused_by": caused_by},
+    )
+    envelope = backend.EmissionEnvelope(
+        emission_id=emission_id,
+        timestamp=created_at,
+        emission_type="task_enqueued",
+        payload=task,
+        caused_by=caused_by,
+        entity_refs=(entity_ref,),
+    )
+
+    return {
+        "task": dict(_to_dict(task)),
+        "emission_envelope": dict(_to_dict(envelope)),
+    }

metaspn_gates-0.1.0/metaspn_gates.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: metaspn-gates
+Version: 0.1.0
+Summary: Config-driven gate and state machine evaluator for MetaSPN entity pipelines
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/leoguinan/metaspn-gates
+Project-URL: Repository, https://github.com/leoguinan/metaspn-gates
+Project-URL: Issues, https://github.com/leoguinan/metaspn-gates/issues
+Keywords: metaspn,state-machine,gates,workflow
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: metaspn-schemas==0.1.0
+
+# metaspn-gates
+
+`metaspn-gates` is a config-driven gate + state-machine evaluator for MetaSPN entity pipelines.
+
+## Current implementation (v0.1 seed)
+
+- Deterministic gate evaluation from config
+- Hard requirements and soft thresholds
+- Per-gate per-entity cooldown checks
+- Transition attempt snapshots
+- Transition application + task emissions
+- Config parsing and validation from mapping
+- `metaspn-schemas` integration hooks (currently used for typed emission shaping)
+- Optional `metaspn-schemas` emission shaping (`Task` + `EmissionEnvelope`)
+
+## Public API
+
+- `evaluate_gates(config, entity_state, features, now)`
+- `apply_decisions(entity_state, decisions, caused_by=None)`
+- `parse_state_machine_config(payload)`
+- `load_state_machine_config(path)`
+
+## Notes
+
+- `load_state_machine_config` can use `metaspn_schemas` parsing/validation hooks when exposed by that package version.
+- If `metaspn_schemas` is unavailable, it falls back to JSON parsing only.
+- Current dependency target: `metaspn-schemas==0.1.0`.
+- `apply_decisions(..., use_schema_envelopes=True)` attaches schema-shaped payloads when `entity_state.entity_id` is present.
+
+## Release
+
+- GitHub Actions workflow: `/Users/leoguinan/MetaSPN/metaspn-gates/.github/workflows/publish.yml`
+- Publish trigger: GitHub Release published (or manual `workflow_dispatch`)
+- Publishing method: PyPI Trusted Publishing via `pypa/gh-action-pypi-publish`
+
+### One-time setup
+
+1. In PyPI, create project `metaspn-gates` and configure Trusted Publisher for this GitHub repo/workflow.
+2. In GitHub, create environment `pypi` (optional protection rules supported).
+
+### Release flow
+
+1. Bump `/Users/leoguinan/MetaSPN/metaspn-gates/pyproject.toml` version.
+2. Tag and push a release commit.
+3. Publish a GitHub Release for that tag.
+4. `publish.yml` builds and uploads to PyPI.

metaspn_gates-0.1.0/metaspn_gates.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+metaspn_gates/__init__.py
+metaspn_gates/applier.py
+metaspn_gates/config.py
+metaspn_gates/evaluator.py
+metaspn_gates/models.py
+metaspn_gates/schemas.py
+metaspn_gates.egg-info/PKG-INFO
+metaspn_gates.egg-info/SOURCES.txt
+metaspn_gates.egg-info/dependency_links.txt
+metaspn_gates.egg-info/requires.txt
+metaspn_gates.egg-info/top_level.txt
+tests/test_gates.py

metaspn_gates-0.1.0/metaspn_gates.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

metaspn_gates-0.1.0/metaspn_gates.egg-info/requires.txt

@@ -0,0 +1 @@
+metaspn-schemas==0.1.0

metaspn_gates-0.1.0/metaspn_gates.egg-info/top_level.txt

@@ -0,0 +1 @@
+metaspn_gates

metaspn_gates-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metaspn-gates"
+version = "0.1.0"
+description = "Config-driven gate and state machine evaluator for MetaSPN entity pipelines"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+keywords = ["metaspn", "state-machine", "gates", "workflow"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "metaspn-schemas==0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/leoguinan/metaspn-gates"
+Repository = "https://github.com/leoguinan/metaspn-gates"
+Issues = "https://github.com/leoguinan/metaspn-gates/issues"
+
+[tool.setuptools]
+packages = ["metaspn_gates"]

metaspn_gates-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metaspn_gates-0.1.0/tests/test_gates.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest import mock
+
+from metaspn_gates import apply_decisions, evaluate_gates, parse_state_machine_config
+from metaspn_gates.config import ConfigError, load_state_machine_config, schemas_backend_available
+
+
+BASE_CONFIG = {
+    "config_version": "sm.v1",
+    "gates": [
+        {
+            "gate_id": "g.qualify.a",
+            "version": "1",
+            "track": "A",
+            "from": "candidate",
+            "to": "qualified",
+            "hard_requirements": [
+                {
+                    "requirement_id": "hr.followers",
+                    "field": "social.followers",
+                    "op": "gte",
+                    "value": 1000,
+                }
+            ],
+            "soft_thresholds": [
+                {
+                    "threshold_id": "st.quality",
+                    "field": "quality.score",
+                    "op": "gte",
+                    "value": 0.7,
+                }
+            ],
+            "min_soft_passed": 1,
+            "cooldown_seconds": 3600,
+            "cooldown_on": "attempt",
+            "enqueue_tasks_on_pass": ["task.review"],
+            "failure_taxonomy": {"hr.followers": "insufficient_reach"},
+        },
+        {
+            "gate_id": "g.qualify.b",
+            "version": "1",
+            "track": "B",
+            "from": "candidate",
+            "to": "qualified",
+            "hard_requirements": [],
+        },
+    ],
+}
+
+
+class GateTests(unittest.TestCase):
+    def test_deterministic_gate_evaluation(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        entity_state = {"state": "candidate", "track": "A"}
+        features = {"social": {"followers": 1500}, "quality": {"score": 0.8}}
+
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        d1 = evaluate_gates(config, entity_state, features, now)
+        d2 = evaluate_gates(config, entity_state, features, now)
+
+        self.assertEqual([d.gate_id for d in d1], ["g.qualify.a"])
+        self.assertEqual([d.passed for d in d1], [True])
+        self.assertEqual([(d.gate_id, d.passed, d.reason) for d in d1], [(d.gate_id, d.passed, d.reason) for d in d2])
+
+    def test_cooldown_correctness(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        recent = now - timedelta(minutes=5)
+
+        entity_state = {
+            "state": "candidate",
+            "track": "A",
+            "gate_cooldowns": {"g.qualify.a": recent.isoformat()},
+        }
+        features = {"social": {"followers": 1500}, "quality": {"score": 0.9}}
+
+        decisions = evaluate_gates(config, entity_state, features, now)
+        self.assertEqual(len(decisions), 1)
+        self.assertFalse(decisions[0].passed)
+        self.assertTrue(decisions[0].cooldown_active)
+        self.assertEqual(decisions[0].reason, "cooldown_active")
+
+    def test_config_parsing_validation(self) -> None:
+        bad = {
+            "config_version": "x",
+            "gates": [
+                {
+                    "gate_id": "a",
+                    "version": "1",
+                    "from": "s1",
+                    "to": "s2",
+                    "cooldown_seconds": -1,
+                }
+            ],
+        }
+        with self.assertRaises(ConfigError):
+            parse_state_machine_config(bad)
+
+    def test_snapshot_completeness(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        entity_state = {"state": "candidate", "track": "A"}
+        features = {"social": {"followers": 1500}, "quality": {"score": 0.9}}
+
+        decisions = evaluate_gates(config, entity_state, features, now)
+        self.assertEqual(len(decisions), 1)
+        snapshot = decisions[0].transition_attempted.snapshot
+        self.assertIn("feature_snapshot", snapshot)
+        self.assertIn("entity_snapshot", snapshot)
+        self.assertIn("config_version", snapshot)
+        self.assertIn("gate_version", snapshot)
+        self.assertIn("timestamp", snapshot)
+
+    def test_apply_decisions_emits_and_transitions(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        entity_state = {"state": "candidate", "track": "A"}
+        features = {"social": {"followers": 1500}, "quality": {"score": 0.9}}
+
+        decisions = evaluate_gates(config, entity_state, features, now)
+        new_state, emissions = apply_decisions(entity_state, decisions, caused_by="sig-123")
+
+        self.assertEqual(new_state["state"], "qualified")
+        self.assertEqual(len(new_state["gate_attempts"]), 1)
+        self.assertEqual(len(new_state["transitions_applied"]), 1)
+        self.assertEqual(len(emissions), 1)
+        self.assertEqual(emissions[0]["task_id"], "task.review")
+
+    def test_apply_decisions_schema_emissions(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        entity_state = {"entity_id": "ent-1", "state": "candidate", "track": "A"}
+        features = {"social": {"followers": 1500}, "quality": {"score": 0.9}}
+
+        decisions = evaluate_gates(config, entity_state, features, now)
+        with mock.patch("metaspn_gates.applier.schemas_available", return_value=True):
+            with mock.patch(
+                "metaspn_gates.applier.build_task_and_emission",
+                return_value={"task": {"task_id": "task.review"}, "emission_envelope": {"emission_type": "task_enqueued"}},
+            ):
+                _, emissions = apply_decisions(entity_state, decisions, caused_by="sig-123", use_schema_envelopes=True)
+        self.assertIn("schema", emissions[0])
+        self.assertEqual(emissions[0]["schema"]["task"]["task_id"], "task.review")
+
+    def test_apply_decisions_schema_emissions_require_entity_id(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        entity_state = {"state": "candidate", "track": "A"}
+        features = {"social": {"followers": 1500}, "quality": {"score": 0.9}}
+
+        decisions = evaluate_gates(config, entity_state, features, now)
+        with mock.patch("metaspn_gates.applier.schemas_available", return_value=True):
+            with self.assertRaises(ValueError):
+                apply_decisions(entity_state, decisions, caused_by="sig-123", use_schema_envelopes=True)
+
+    def test_failure_override_hook(self) -> None:
+        config = parse_state_machine_config(BASE_CONFIG)
+        now = datetime(2026, 2, 5, 0, 0, tzinfo=timezone.utc)
+        entity_state = {
+            "state": "candidate",
+            "track": "A",
+            "failure_overrides": {"g.qualify.a": "manual_override_reason"},
+        }
+        features = {"social": {"followers": 10}, "quality": {"score": 0.1}}
+
+        decisions = evaluate_gates(config, entity_state, features, now)
+        self.assertEqual(decisions[0].reason, "manual_override_reason")
+
+    def test_load_state_machine_config_json_fallback(self) -> None:
+        with mock.patch("metaspn_gates.config.importlib.import_module", side_effect=ImportError):
+            with TemporaryDirectory() as tmp:
+                path = Path(tmp) / "config.yaml"
+                path.write_text(
+                    '{"config_version":"sm.v1","gates":[{"gate_id":"g1","version":"1","from":"a","to":"b"}]}',
+                    encoding="utf-8",
+                )
+                config = load_state_machine_config(path)
+                self.assertEqual(config.config_version, "sm.v1")
+                self.assertEqual(config.gates[0].gate_id, "g1")
+
+    def test_load_state_machine_config_uses_schemas_backend(self) -> None:
+        class FakeSchemas:
+            @staticmethod
+            def parse_yaml(raw: str) -> dict:
+                if "config_version: sm.v2" not in raw:
+                    raise ValueError("unexpected input")
+                return {
+                    "config_version": "sm.v2",
+                    "gates": [
+                        {
+                            "gate_id": "g1",
+                            "version": "2",
+                            "from": "start",
+                            "to": "next",
+                        }
+                    ],
+                }
+
+        with mock.patch("metaspn_gates.config.importlib.import_module", return_value=FakeSchemas):
+            with TemporaryDirectory() as tmp:
+                path = Path(tmp) / "config.yaml"
+                path.write_text(
+                    "config_version: sm.v2\n"
+                    "gates:\n"
+                    "  - gate_id: g1\n"
+                    "    version: '2'\n"
+                    "    from: start\n"
+                    "    to: next\n",
+                    encoding="utf-8",
+                )
+                config = load_state_machine_config(path)
+                self.assertEqual(config.config_version, "sm.v2")
+                self.assertEqual(config.gates[0].version, "2")
+
+    def test_schemas_backend_available_helper(self) -> None:
+        with mock.patch("metaspn_gates.config.importlib.import_module", return_value=object()):
+            self.assertTrue(schemas_backend_available())
+        with mock.patch("metaspn_gates.config.importlib.import_module", side_effect=ImportError):
+            self.assertFalse(schemas_backend_available())
+
+    def test_parse_state_machine_config_runs_backend_validation(self) -> None:
+        class FakeSchemas:
+            called = False
+
+            @staticmethod
+            def validate_state_machine_config(payload: dict) -> dict:
+                FakeSchemas.called = True
+                out = dict(payload)
+                out["config_version"] = "validated"
+                return out
+
+        with mock.patch("metaspn_gates.config.importlib.import_module", return_value=FakeSchemas):
+            config = parse_state_machine_config(
+                {"config_version": "raw", "gates": [{"gate_id": "g1", "version": "1", "from": "a", "to": "b"}]}
+            )
+            self.assertTrue(FakeSchemas.called)
+            self.assertEqual(config.config_version, "validated")
+
+
+if __name__ == "__main__":
+    unittest.main()