matrx-assignment 0.1.0__py3-none-any.whl

matrx_assignment/__init__.py

@@ -0,0 +1,60 @@
+from matrx_assignment.coordinator import (
+    AssignmentCoordinator,
+    AssignmentExecutionFailure,
+    AssignmentExecutor,
+)
+from matrx_assignment.in_memory import InMemoryAssignmentStore
+from matrx_assignment.models import (
+    AssignmentBatchResult,
+    AssignmentClaim,
+    AssignmentError,
+    AssignmentExecutionOutput,
+    AssignmentItemResult,
+    AssignmentItemSnapshot,
+    AssignmentItemStatus,
+    AssignmentOrder,
+    AssignmentPlan,
+    AssignmentRow,
+    AssignmentSessionRequest,
+    AssignmentSessionStatus,
+    AssignmentSessionSummary,
+    AssignmentSource,
+    AssignmentUniqueness,
+    CartesianPlan,
+    CoordinatedRowsPlan,
+    IndependentRandomPlan,
+    MaterializedAssignment,
+    MaterializedPlan,
+)
+from matrx_assignment.planner import AssignmentPlanner, fingerprint_json
+from matrx_assignment.store import AssignmentStore
+
+__all__ = [
+    "AssignmentBatchResult",
+    "AssignmentClaim",
+    "AssignmentCoordinator",
+    "AssignmentError",
+    "AssignmentExecutionFailure",
+    "AssignmentExecutionOutput",
+    "AssignmentExecutor",
+    "AssignmentItemResult",
+    "AssignmentItemSnapshot",
+    "AssignmentItemStatus",
+    "AssignmentOrder",
+    "AssignmentPlan",
+    "AssignmentPlanner",
+    "AssignmentRow",
+    "AssignmentSessionRequest",
+    "AssignmentSessionStatus",
+    "AssignmentSessionSummary",
+    "AssignmentSource",
+    "AssignmentStore",
+    "AssignmentUniqueness",
+    "CartesianPlan",
+    "CoordinatedRowsPlan",
+    "IndependentRandomPlan",
+    "InMemoryAssignmentStore",
+    "MaterializedAssignment",
+    "MaterializedPlan",
+    "fingerprint_json",
+]

matrx_assignment/coordinator.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import asyncio
+import socket
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime, timedelta
+from typing import Protocol
+
+from matrx_assignment.models import (
+    AssignmentBatchResult,
+    AssignmentClaim,
+    AssignmentError,
+    AssignmentExecutionOutput,
+    AssignmentItemResult,
+    AssignmentSessionRequest,
+    AssignmentSessionStatus,
+)
+from matrx_assignment.store import AssignmentStore
+
+
+class AssignmentExecutor(Protocol):
+    async def __call__(self, claim: AssignmentClaim) -> AssignmentExecutionOutput: ...
+
+
+ProgressCallback = Callable[[int, int], Awaitable[None]]
+
+
+class AssignmentExecutionFailure(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "assignment_execution_failed",
+        retryable: bool = True,
+        details: dict[str, object] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.error = AssignmentError(
+            code=code,
+            message=message,
+            retryable=retryable,
+            details=details or {},
+        )
+
+
+class AssignmentCoordinator:
+    """Lease and execute persisted items without knowing what the payload does."""
+
+    def __init__(self, store: AssignmentStore, *, holder: str | None = None) -> None:
+        self._store = store
+        self._holder = holder or socket.gethostname()
+
+    async def run(
+        self,
+        session_id: str,
+        request: AssignmentSessionRequest,
+        executor: AssignmentExecutor,
+        *,
+        progress: ProgressCallback | None = None,
+    ) -> AssignmentBatchResult:
+        await self._store.reap_expired_claims(session_id, now=datetime.now(UTC))
+        while True:
+            session = await self._store.get_session(session_id)
+            if session.status in {
+                AssignmentSessionStatus.COMPLETED,
+                AssignmentSessionStatus.PARTIALLY_FAILED,
+                AssignmentSessionStatus.FAILED,
+                AssignmentSessionStatus.CANCELLED,
+            }:
+                break
+
+            claims = await self._store.claim_items(
+                session_id,
+                holder=self._holder,
+                limit=request.max_concurrency,
+                lease_seconds=request.lease_seconds,
+            )
+            if not claims:
+                session = await self._store.finalize_session(session_id)
+                if session.status is AssignmentSessionStatus.RUNNING:
+                    await asyncio.sleep(
+                        min(1.0, max(0.05, float(request.retry_delay_seconds)))
+                    )
+                    continue
+                break
+
+            await asyncio.gather(
+                *(
+                    self._execute_one(
+                        claim,
+                        request=request,
+                        executor=executor,
+                    )
+                    for claim in claims
+                )
+            )
+            if progress is not None:
+                snapshot = await self._store.get_session(session_id)
+                await progress(snapshot.completed_items + snapshot.failed_items, snapshot.total_items)
+
+        await self._store.finalize_session(session_id)
+        return await self.snapshot(session_id)
+
+    async def snapshot(self, session_id: str) -> AssignmentBatchResult:
+        """Load the durable result without claiming or executing any work."""
+
+        final_session = await self._store.get_session(session_id)
+        items = await self._store.list_items(session_id)
+        return AssignmentBatchResult(
+            session=final_session,
+            items=[
+                AssignmentItemResult(
+                    id=item.id,
+                    ordinal=item.ordinal,
+                    key=item.key,
+                    status=item.status,
+                    values=item.values,
+                    output=item.output,
+                    output_kind=item.output_kind,
+                    output_kind_version=item.output_kind_version,
+                    conversation_id=item.conversation_id,
+                    runtime_execution_id=item.runtime_execution_id,
+                    error=item.error,
+                )
+                for item in items
+            ],
+        )
+
+    async def _execute_one(
+        self,
+        claim: AssignmentClaim,
+        *,
+        request: AssignmentSessionRequest,
+        executor: AssignmentExecutor,
+    ) -> None:
+        await self._store.mark_running(claim)
+        heartbeat_stop = asyncio.Event()
+        heartbeat = asyncio.create_task(
+            self._renew_lease(
+                claim,
+                lease_seconds=request.lease_seconds,
+                stop=heartbeat_stop,
+            )
+        )
+        try:
+            output = await executor(claim)
+        except AssignmentExecutionFailure as exc:
+            error = exc.error
+        except Exception as exc:  # executor boundary: unknown failures are retryable by default
+            error = AssignmentError(
+                code=type(exc).__name__,
+                message=str(exc) or type(exc).__name__,
+                retryable=True,
+            )
+        else:
+            await self._store.complete_item(claim, output)
+            return
+        finally:
+            heartbeat_stop.set()
+            await heartbeat
+
+        retryable = error.retryable and claim.attempt_number < claim.item.max_attempts
+        if retryable != error.retryable:
+            error = error.model_copy(update={"retryable": False})
+        delay = request.retry_delay_seconds * (2 ** max(0, claim.attempt_number - 1))
+        await self._store.fail_item(
+            claim,
+            error,
+            retry_at=datetime.now(UTC) + timedelta(seconds=delay),
+        )
+
+    async def _renew_lease(
+        self,
+        claim: AssignmentClaim,
+        *,
+        lease_seconds: int,
+        stop: asyncio.Event,
+    ) -> None:
+        interval = max(10.0, lease_seconds / 3)
+        while True:
+            try:
+                await asyncio.wait_for(stop.wait(), timeout=interval)
+                return
+            except TimeoutError:
+                if not await self._store.renew_claim(
+                    claim,
+                    lease_seconds=lease_seconds,
+                ):
+                    return

matrx_assignment/in_memory.py

@@ -0,0 +1,416 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from uuid import NAMESPACE_URL, uuid4, uuid5
+
+from matrx_assignment.models import (
+    AssignmentAttemptStatus,
+    AssignmentClaim,
+    AssignmentError,
+    AssignmentExecutionOutput,
+    AssignmentItemSnapshot,
+    AssignmentItemStatus,
+    AssignmentSessionRequest,
+    AssignmentSessionStatus,
+    AssignmentSessionSummary,
+    MaterializedAssignment,
+    MaterializedPlan,
+)
+
+
+@dataclass(slots=True)
+class _Session:
+    id: str
+    request: AssignmentSessionRequest
+    plan_fingerprint: str
+    status: AssignmentSessionStatus
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+
+
+@dataclass(slots=True)
+class _Item:
+    id: str
+    session_id: str
+    materialized: MaterializedAssignment
+    status: AssignmentItemStatus
+    attempt_count: int
+    max_attempts: int
+    created_at: datetime
+    updated_at: datetime
+    visible_at: datetime
+    lease_holder: str | None = None
+    lease_expires_at: datetime | None = None
+    conversation_id: str | None = None
+    runtime_execution_id: str | None = None
+    output: object = None
+    output_kind: str | None = None
+    output_kind_version: int | None = None
+    error: AssignmentError | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+
+
+@dataclass(slots=True)
+class _Attempt:
+    id: str
+    item_id: str
+    number: int
+    status: AssignmentAttemptStatus
+    holder: str
+    started_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+    error: AssignmentError | None = None
+
+
+class InMemoryAssignmentStore:
+    """Concurrency-safe reference store used by standalone hosts and tests."""
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._sessions: dict[str, _Session] = {}
+        self._session_by_key: dict[str, str] = {}
+        self._items: dict[str, _Item] = {}
+        self._attempts: dict[str, _Attempt] = {}
+
+    async def create_or_get_session(
+        self, request: AssignmentSessionRequest, materialized: MaterializedPlan
+    ) -> AssignmentSessionSummary:
+        async with self._lock:
+            existing_id = self._session_by_key.get(request.idempotency_key)
+            if existing_id is not None:
+                existing = self._sessions[existing_id]
+                if existing.plan_fingerprint != materialized.plan_fingerprint:
+                    raise ValueError(
+                        "idempotency key already belongs to a different assignment plan"
+                    )
+                return self._summary(existing)
+
+            now = datetime.now(UTC)
+            session_id = str(uuid4())
+            session = _Session(
+                id=session_id,
+                request=request,
+                plan_fingerprint=materialized.plan_fingerprint,
+                status=AssignmentSessionStatus.PENDING,
+                created_at=now,
+                updated_at=now,
+            )
+            self._sessions[session_id] = session
+            self._session_by_key[request.idempotency_key] = session_id
+            for materialized_item in materialized.items:
+                item_id = str(
+                    uuid5(
+                        NAMESPACE_URL,
+                        f"matrx-assignment:{session_id}:{materialized_item.ordinal}",
+                    )
+                )
+                self._items[item_id] = _Item(
+                    id=item_id,
+                    session_id=session_id,
+                    materialized=materialized_item,
+                    status=AssignmentItemStatus.PENDING,
+                    attempt_count=0,
+                    max_attempts=request.max_attempts,
+                    created_at=now,
+                    updated_at=now,
+                    visible_at=now,
+                    conversation_id=str(uuid5(NAMESPACE_URL, f"{item_id}:conversation")),
+                )
+            return self._summary(session)
+
+    async def get_session(self, session_id: str) -> AssignmentSessionSummary:
+        async with self._lock:
+            return self._summary(self._sessions[session_id])
+
+    async def list_items(self, session_id: str) -> list[AssignmentItemSnapshot]:
+        async with self._lock:
+            return [self._snapshot(item) for item in self._session_items(session_id)]
+
+    async def claim_items(
+        self,
+        session_id: str,
+        *,
+        holder: str,
+        limit: int,
+        lease_seconds: int,
+    ) -> list[AssignmentClaim]:
+        async with self._lock:
+            now = datetime.now(UTC)
+            candidates = [
+                item
+                for item in self._session_items(session_id)
+                if item.status
+                in {AssignmentItemStatus.PENDING, AssignmentItemStatus.RETRYABLE_FAILED}
+                and item.visible_at <= now
+            ][:limit]
+            claims: list[AssignmentClaim] = []
+            for item in candidates:
+                item.attempt_count += 1
+                item.status = AssignmentItemStatus.LEASED
+                item.lease_holder = holder
+                item.lease_expires_at = now + timedelta(seconds=lease_seconds)
+                item.updated_at = now
+                attempt_id = str(uuid5(NAMESPACE_URL, f"{item.id}:attempt:{item.attempt_count}"))
+                self._attempts[attempt_id] = _Attempt(
+                    id=attempt_id,
+                    item_id=item.id,
+                    number=item.attempt_count,
+                    status=AssignmentAttemptStatus.LEASED,
+                    holder=holder,
+                    started_at=now,
+                    updated_at=now,
+                )
+                claims.append(
+                    AssignmentClaim(
+                        attempt_id=attempt_id,
+                        attempt_number=item.attempt_count,
+                        holder=holder,
+                        item=self._snapshot(item),
+                    )
+                )
+            if candidates:
+                session = self._sessions[session_id]
+                session.status = AssignmentSessionStatus.RUNNING
+                session.updated_at = now
+            return claims
+
+    async def mark_running(self, claim: AssignmentClaim) -> None:
+        async with self._lock:
+            item = self._owned_item(claim)
+            now = datetime.now(UTC)
+            item.status = AssignmentItemStatus.RUNNING
+            item.started_at = item.started_at or now
+            item.updated_at = now
+            attempt = self._attempts[claim.attempt_id]
+            attempt.status = AssignmentAttemptStatus.RUNNING
+            attempt.updated_at = now
+
+    async def renew_claim(self, claim: AssignmentClaim, *, lease_seconds: int) -> bool:
+        async with self._lock:
+            item = self._items.get(claim.item.id)
+            if item is None or item.lease_holder != claim.holder:
+                return False
+            if item.status not in {AssignmentItemStatus.LEASED, AssignmentItemStatus.RUNNING}:
+                return False
+            now = datetime.now(UTC)
+            item.lease_expires_at = now + timedelta(seconds=lease_seconds)
+            item.updated_at = now
+            return True
+
+    async def complete_item(
+        self, claim: AssignmentClaim, output: AssignmentExecutionOutput
+    ) -> None:
+        async with self._lock:
+            if self._items[claim.item.id].status is AssignmentItemStatus.CANCELLED:
+                return
+            item = self._owned_item(claim)
+            now = datetime.now(UTC)
+            item.status = AssignmentItemStatus.COMPLETED
+            item.output = output.value
+            item.output_kind = output.kind
+            item.output_kind_version = output.kind_version
+            item.conversation_id = output.conversation_id or item.conversation_id
+            item.runtime_execution_id = output.runtime_execution_id
+            item.error = None
+            item.lease_holder = None
+            item.lease_expires_at = None
+            item.completed_at = now
+            item.updated_at = now
+            attempt = self._attempts[claim.attempt_id]
+            attempt.status = AssignmentAttemptStatus.COMPLETED
+            attempt.completed_at = now
+            attempt.updated_at = now
+
+    async def fail_item(
+        self,
+        claim: AssignmentClaim,
+        error: AssignmentError,
+        *,
+        retry_at: datetime,
+    ) -> None:
+        async with self._lock:
+            if self._items[claim.item.id].status is AssignmentItemStatus.CANCELLED:
+                return
+            item = self._owned_item(claim)
+            now = datetime.now(UTC)
+            item.error = error
+            item.lease_holder = None
+            item.lease_expires_at = None
+            item.visible_at = retry_at
+            item.updated_at = now
+            attempt = self._attempts[claim.attempt_id]
+            attempt.error = error
+            attempt.completed_at = now
+            attempt.updated_at = now
+            if error.retryable and item.attempt_count < item.max_attempts:
+                item.status = AssignmentItemStatus.RETRYABLE_FAILED
+                attempt.status = AssignmentAttemptStatus.RETRYABLE_FAILED
+            else:
+                item.status = AssignmentItemStatus.TERMINAL_FAILED
+                item.completed_at = now
+                attempt.status = AssignmentAttemptStatus.TERMINAL_FAILED
+
+    async def finalize_session(self, session_id: str) -> AssignmentSessionSummary:
+        async with self._lock:
+            session = self._sessions[session_id]
+            items = self._session_items(session_id)
+            statuses = {item.status for item in items}
+            now = datetime.now(UTC)
+            if session.status is AssignmentSessionStatus.CANCELLED:
+                session.status = AssignmentSessionStatus.CANCELLED
+            elif statuses <= {AssignmentItemStatus.COMPLETED}:
+                session.status = AssignmentSessionStatus.COMPLETED
+            elif statuses <= {AssignmentItemStatus.TERMINAL_FAILED}:
+                session.status = AssignmentSessionStatus.FAILED
+            elif statuses <= {
+                AssignmentItemStatus.COMPLETED,
+                AssignmentItemStatus.TERMINAL_FAILED,
+                AssignmentItemStatus.CANCELLED,
+            }:
+                session.status = AssignmentSessionStatus.PARTIALLY_FAILED
+            else:
+                session.status = AssignmentSessionStatus.RUNNING
+            if session.status in {
+                AssignmentSessionStatus.COMPLETED,
+                AssignmentSessionStatus.PARTIALLY_FAILED,
+                AssignmentSessionStatus.FAILED,
+                AssignmentSessionStatus.CANCELLED,
+            }:
+                session.completed_at = session.completed_at or now
+            session.updated_at = now
+            return self._summary(session)
+
+    async def reap_expired_claims(self, session_id: str, *, now: datetime) -> int:
+        async with self._lock:
+            count = 0
+            for item in self._session_items(session_id):
+                if item.status not in {AssignmentItemStatus.LEASED, AssignmentItemStatus.RUNNING}:
+                    continue
+                if item.lease_expires_at is None or item.lease_expires_at >= now:
+                    continue
+                error = AssignmentError(
+                    code="assignment_lease_expired",
+                    message="assignment worker lease expired before settlement",
+                    retryable=item.attempt_count < item.max_attempts,
+                )
+                item.error = error
+                item.lease_holder = None
+                item.lease_expires_at = None
+                item.visible_at = now
+                item.updated_at = now
+                attempt_id = str(
+                    uuid5(NAMESPACE_URL, f"{item.id}:attempt:{item.attempt_count}")
+                )
+                attempt = self._attempts[attempt_id]
+                attempt.status = AssignmentAttemptStatus.ABANDONED
+                attempt.error = error
+                attempt.completed_at = now
+                attempt.updated_at = now
+                if error.retryable:
+                    item.status = AssignmentItemStatus.RETRYABLE_FAILED
+                else:
+                    item.status = AssignmentItemStatus.TERMINAL_FAILED
+                    item.completed_at = now
+                count += 1
+            return count
+
+    async def cancel_session(self, session_id: str) -> AssignmentSessionSummary:
+        async with self._lock:
+            now = datetime.now(UTC)
+            session = self._sessions[session_id]
+            session.status = AssignmentSessionStatus.CANCELLED
+            session.updated_at = now
+            session.completed_at = now
+            for item in self._session_items(session_id):
+                if item.status is AssignmentItemStatus.COMPLETED:
+                    continue
+                item.status = AssignmentItemStatus.CANCELLED
+                item.lease_holder = None
+                item.lease_expires_at = None
+                item.updated_at = now
+                item.completed_at = now
+                if item.attempt_count > 0:
+                    attempt_id = str(
+                        uuid5(NAMESPACE_URL, f"{item.id}:attempt:{item.attempt_count}")
+                    )
+                    attempt = self._attempts.get(attempt_id)
+                    if attempt is not None:
+                        attempt.status = AssignmentAttemptStatus.CANCELLED
+                        attempt.updated_at = now
+                        attempt.completed_at = now
+            return self._summary(session)
+
+    def _owned_item(self, claim: AssignmentClaim) -> _Item:
+        item = self._items[claim.item.id]
+        if item.lease_holder != claim.holder:
+            raise RuntimeError("assignment claim ownership was lost")
+        if item.attempt_count != claim.attempt_number:
+            raise RuntimeError("assignment claim attempt is stale")
+        return item
+
+    def _session_items(self, session_id: str) -> list[_Item]:
+        return sorted(
+            (item for item in self._items.values() if item.session_id == session_id),
+            key=lambda item: item.materialized.ordinal,
+        )
+
+    def _summary(self, session: _Session) -> AssignmentSessionSummary:
+        items = self._session_items(session.id)
+        pending = sum(
+            item.status in {AssignmentItemStatus.PENDING, AssignmentItemStatus.RETRYABLE_FAILED}
+            for item in items
+        )
+        running = sum(
+            item.status in {AssignmentItemStatus.LEASED, AssignmentItemStatus.RUNNING}
+            for item in items
+        )
+        completed = sum(item.status is AssignmentItemStatus.COMPLETED for item in items)
+        failed = sum(item.status is AssignmentItemStatus.TERMINAL_FAILED for item in items)
+        cancelled = sum(item.status is AssignmentItemStatus.CANCELLED for item in items)
+        return AssignmentSessionSummary(
+            id=session.id,
+            idempotency_key=session.request.idempotency_key,
+            plan_fingerprint=session.plan_fingerprint,
+            status=session.status,
+            total_items=len(items),
+            pending_items=pending,
+            running_items=running,
+            completed_items=completed,
+            failed_items=failed,
+            cancelled_items=cancelled,
+            created_at=session.created_at,
+            updated_at=session.updated_at,
+            completed_at=session.completed_at,
+        )
+
+    @staticmethod
+    def _snapshot(item: _Item) -> AssignmentItemSnapshot:
+        return AssignmentItemSnapshot(
+            id=item.id,
+            session_id=item.session_id,
+            ordinal=item.materialized.ordinal,
+            key=item.materialized.key,
+            values=item.materialized.values,
+            metadata=item.materialized.metadata,
+            fingerprint=item.materialized.fingerprint,
+            status=item.status,
+            attempt_count=item.attempt_count,
+            max_attempts=item.max_attempts,
+            lease_holder=item.lease_holder,
+            lease_expires_at=item.lease_expires_at,
+            conversation_id=item.conversation_id,
+            runtime_execution_id=item.runtime_execution_id,
+            output=item.output,
+            output_kind=item.output_kind,
+            output_kind_version=item.output_kind_version,
+            error=item.error,
+            created_at=item.created_at,
+            updated_at=item.updated_at,
+            started_at=item.started_at,
+            completed_at=item.completed_at,
+        )

matrx_assignment/models.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
+
+
+class AssignmentModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, validate_default=True)
+
+
+class AssignmentSessionStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    PARTIALLY_FAILED = "partially_failed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class AssignmentItemStatus(StrEnum):
+    PENDING = "pending"
+    LEASED = "leased"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    RETRYABLE_FAILED = "retryable_failed"
+    TERMINAL_FAILED = "terminal_failed"
+    CANCELLED = "cancelled"
+
+
+class AssignmentAttemptStatus(StrEnum):
+    LEASED = "leased"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    RETRYABLE_FAILED = "retryable_failed"
+    TERMINAL_FAILED = "terminal_failed"
+    ABANDONED = "abandoned"
+    CANCELLED = "cancelled"
+
+
+class AssignmentOrder(StrEnum):
+    DECLARED = "declared"
+    RANDOM = "random"
+
+
+class AssignmentUniqueness(StrEnum):
+    ALLOW_REPEATS = "allow_repeats"
+    WITHOUT_REPLACEMENT = "without_replacement"
+
+
+class AssignmentRow(AssignmentModel):
+    key: str = Field(min_length=1, max_length=240)
+    values: dict[str, JsonValue] = Field(min_length=1)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_variable_names(self) -> AssignmentRow:
+        if any(not name.strip() for name in self.values):
+            raise ValueError("assignment variable names must be non-empty")
+        return self
+
+
+class CoordinatedRowsPlan(AssignmentModel):
+    strategy: Literal["coordinated_rows"] = "coordinated_rows"
+    rows: list[AssignmentRow] = Field(min_length=1)
+    order: AssignmentOrder = AssignmentOrder.DECLARED
+    limit: int | None = Field(default=None, ge=1)
+
+    @model_validator(mode="after")
+    def validate_rows(self) -> CoordinatedRowsPlan:
+        keys = [row.key for row in self.rows]
+        if len(keys) != len(set(keys)):
+            raise ValueError("coordinated row keys must be unique")
+        if self.limit is not None and self.limit > len(self.rows):
+            raise ValueError("limit cannot exceed the number of coordinated rows")
+        return self
+
+
+class IndependentRandomPlan(AssignmentModel):
+    strategy: Literal["independent_random"] = "independent_random"
+    variables: dict[str, list[JsonValue]] = Field(min_length=1)
+    count: int = Field(ge=1, le=100_000)
+    uniqueness: AssignmentUniqueness = AssignmentUniqueness.ALLOW_REPEATS
+
+    @model_validator(mode="after")
+    def validate_options(self) -> IndependentRandomPlan:
+        _validate_option_map(self.variables)
+        if self.uniqueness is AssignmentUniqueness.WITHOUT_REPLACEMENT:
+            capacity = _combination_capacity(self.variables)
+            if self.count > capacity:
+                raise ValueError(
+                    f"count={self.count} exceeds the {capacity} available combinations"
+                )
+        return self
+
+
+class CartesianPlan(AssignmentModel):
+    strategy: Literal["cartesian"] = "cartesian"
+    variables: dict[str, list[JsonValue]] = Field(min_length=1)
+    order: AssignmentOrder = AssignmentOrder.DECLARED
+    limit: int | None = Field(default=None, ge=1, le=100_000)
+
+    @model_validator(mode="after")
+    def validate_options(self) -> CartesianPlan:
+        _validate_option_map(self.variables)
+        capacity = _combination_capacity(self.variables)
+        if capacity > 100_000 and self.limit is None:
+            raise ValueError(
+                "cartesian plans over 100,000 combinations require an explicit limit"
+            )
+        if self.limit is not None and self.limit > capacity:
+            raise ValueError("limit cannot exceed the cartesian combination count")
+        return self
+
+
+AssignmentPlan = Annotated[
+    CoordinatedRowsPlan | IndependentRandomPlan | CartesianPlan,
+    Field(discriminator="strategy"),
+]
+
+
+class AssignmentSource(AssignmentModel):
+    kind: Literal["api", "workflow", "scheduler", "internal"]
+    execution_id: str | None = Field(default=None, min_length=1, max_length=200)
+    workflow_run_id: str | None = Field(default=None, min_length=1, max_length=200)
+    workflow_node_id: str | None = Field(default=None, min_length=1, max_length=200)
+
+
+class AssignmentSessionRequest(AssignmentModel):
+    idempotency_key: str = Field(min_length=1, max_length=500)
+    plan: AssignmentPlan
+    source: AssignmentSource
+    max_attempts: int = Field(default=3, ge=1, le=20)
+    lease_seconds: int = Field(default=900, ge=30, le=86_400)
+    max_concurrency: int = Field(default=5, ge=1, le=100)
+    retry_delay_seconds: int = Field(default=0, ge=0, le=86_400)
+    result_kind: str | None = Field(default=None, min_length=1, max_length=240)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class MaterializedAssignment(AssignmentModel):
+    ordinal: int = Field(ge=0)
+    key: str = Field(min_length=1, max_length=240)
+    values: dict[str, JsonValue] = Field(min_length=1)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+    fingerprint: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+
+class MaterializedPlan(AssignmentModel):
+    plan_fingerprint: str = Field(pattern=r"^[0-9a-f]{64}$")
+    items: list[MaterializedAssignment] = Field(min_length=1)
+
+
+class AssignmentError(AssignmentModel):
+    code: str = Field(min_length=1, max_length=160)
+    message: str = Field(min_length=1)
+    retryable: bool
+    details: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class AssignmentSessionSummary(AssignmentModel):
+    id: str
+    idempotency_key: str
+    plan_fingerprint: str
+    status: AssignmentSessionStatus
+    total_items: int = Field(ge=0)
+    pending_items: int = Field(ge=0)
+    running_items: int = Field(ge=0)
+    completed_items: int = Field(ge=0)
+    failed_items: int = Field(ge=0)
+    cancelled_items: int = Field(ge=0)
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+
+
+class AssignmentItemSnapshot(AssignmentModel):
+    id: str
+    session_id: str
+    ordinal: int = Field(ge=0)
+    key: str
+    values: dict[str, JsonValue]
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+    fingerprint: str
+    status: AssignmentItemStatus
+    attempt_count: int = Field(ge=0)
+    max_attempts: int = Field(ge=1)
+    lease_holder: str | None = None
+    lease_expires_at: datetime | None = None
+    conversation_id: str | None = None
+    runtime_execution_id: str | None = None
+    output: JsonValue = None
+    output_kind: str | None = None
+    output_kind_version: int | None = Field(default=None, ge=1)
+    error: AssignmentError | None = None
+    created_at: datetime
+    updated_at: datetime
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+
+
+class AssignmentClaim(AssignmentModel):
+    attempt_id: str
+    attempt_number: int = Field(ge=1)
+    holder: str = Field(min_length=1, max_length=240)
+    item: AssignmentItemSnapshot
+
+
+class AssignmentExecutionOutput(AssignmentModel):
+    value: JsonValue
+    kind: str | None = Field(default=None, min_length=1, max_length=240)
+    kind_version: int | None = Field(default=None, ge=1)
+    conversation_id: str | None = None
+    runtime_execution_id: str | None = None
+
+
+class AssignmentItemResult(AssignmentModel):
+    id: str
+    ordinal: int
+    key: str
+    status: AssignmentItemStatus
+    values: dict[str, JsonValue]
+    output: JsonValue = None
+    output_kind: str | None = None
+    output_kind_version: int | None = None
+    conversation_id: str | None = None
+    runtime_execution_id: str | None = None
+    error: AssignmentError | None = None
+
+
+class AssignmentBatchResult(AssignmentModel):
+    session: AssignmentSessionSummary
+    items: list[AssignmentItemResult]
+
+
+def _validate_option_map(variables: dict[str, list[JsonValue]]) -> None:
+    if any(not name.strip() for name in variables):
+        raise ValueError("assignment variable names must be non-empty")
+    empty = [name for name, options in variables.items() if not options]
+    if empty:
+        raise ValueError(f"assignment options cannot be empty: {empty}")
+    duplicated = [
+        name
+        for name, options in variables.items()
+        if len({_canonical_option(option) for option in options}) != len(options)
+    ]
+    if duplicated:
+        raise ValueError(
+            "assignment option lists cannot contain duplicate values because "
+            f"duplicates would bias selection: {duplicated}"
+        )
+
+
+def _combination_capacity(variables: dict[str, list[JsonValue]]) -> int:
+    capacity = 1
+    for options in variables.values():
+        capacity *= len(options)
+    return capacity
+
+
+def _canonical_option(value: JsonValue) -> str:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    )

matrx_assignment/planner.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+from collections.abc import Sequence
+from typing import TypeVar
+
+from pydantic import JsonValue, TypeAdapter
+
+from matrx_assignment.models import (
+    AssignmentOrder,
+    AssignmentPlan,
+    AssignmentUniqueness,
+    CartesianPlan,
+    CoordinatedRowsPlan,
+    IndependentRandomPlan,
+    MaterializedAssignment,
+    MaterializedPlan,
+)
+
+_PLAN_ADAPTER = TypeAdapter(AssignmentPlan)
+_T = TypeVar("_T")
+
+
+class AssignmentPlanner:
+    """Materialize a typed assignment plan exactly once."""
+
+    def __init__(self, *, random_source: secrets.SystemRandom | None = None) -> None:
+        self._random = random_source or secrets.SystemRandom()
+
+    def materialize(self, plan: AssignmentPlan) -> MaterializedPlan:
+        validated = _PLAN_ADAPTER.validate_python(plan)
+        if isinstance(validated, CoordinatedRowsPlan):
+            rows = self._coordinated_rows(validated)
+        elif isinstance(validated, IndependentRandomPlan):
+            rows = self._independent_random(validated)
+        elif isinstance(validated, CartesianPlan):
+            rows = self._cartesian(validated)
+        else:  # pragma: no cover - discriminated union is exhaustive
+            raise TypeError(f"unsupported assignment plan: {type(validated).__name__}")
+
+        items = [
+            MaterializedAssignment(
+                ordinal=ordinal,
+                key=key,
+                values=values,
+                metadata=metadata,
+                fingerprint=fingerprint_json({"key": key, "values": values, "metadata": metadata}),
+            )
+            for ordinal, (key, values, metadata) in enumerate(rows)
+        ]
+        return MaterializedPlan(
+            plan_fingerprint=fingerprint_json(validated.model_dump(mode="json")),
+            items=items,
+        )
+
+    def _coordinated_rows(
+        self, plan: CoordinatedRowsPlan
+    ) -> list[tuple[str, dict[str, JsonValue], dict[str, JsonValue]]]:
+        count = plan.limit or len(plan.rows)
+        indices = self._indices(len(plan.rows), count, plan.order)
+        return [
+            (plan.rows[index].key, dict(plan.rows[index].values), dict(plan.rows[index].metadata))
+            for index in indices
+        ]
+
+    def _independent_random(
+        self, plan: IndependentRandomPlan
+    ) -> list[tuple[str, dict[str, JsonValue], dict[str, JsonValue]]]:
+        names = list(plan.variables)
+        lengths = [len(plan.variables[name]) for name in names]
+        capacity = _product(lengths)
+        if plan.uniqueness is AssignmentUniqueness.WITHOUT_REPLACEMENT:
+            combination_indices = self._random.sample(range(capacity), plan.count)
+        else:
+            combination_indices = [self._random.randrange(capacity) for _ in range(plan.count)]
+        return [
+            (
+                f"random-{ordinal + 1:06d}",
+                _combination_at(index, names=names, variables=plan.variables, lengths=lengths),
+                {},
+            )
+            for ordinal, index in enumerate(combination_indices)
+        ]
+
+    def _cartesian(
+        self, plan: CartesianPlan
+    ) -> list[tuple[str, dict[str, JsonValue], dict[str, JsonValue]]]:
+        names = list(plan.variables)
+        lengths = [len(plan.variables[name]) for name in names]
+        capacity = _product(lengths)
+        count = plan.limit or capacity
+        indices = self._indices(capacity, count, plan.order)
+        return [
+            (
+                f"combination-{index + 1:06d}",
+                _combination_at(index, names=names, variables=plan.variables, lengths=lengths),
+                {},
+            )
+            for index in indices
+        ]
+
+    def _indices(self, capacity: int, count: int, order: AssignmentOrder) -> Sequence[int]:
+        if order is AssignmentOrder.DECLARED:
+            return range(count)
+        return self._random.sample(range(capacity), count)
+
+
+def fingerprint_json(value: JsonValue | dict[str, JsonValue]) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _product(values: list[int]) -> int:
+    result = 1
+    for value in values:
+        result *= value
+    return result
+
+
+def _combination_at(
+    index: int,
+    *,
+    names: list[str],
+    variables: dict[str, list[JsonValue]],
+    lengths: list[int],
+) -> dict[str, JsonValue]:
+    values: dict[str, JsonValue] = {}
+    remainder = index
+    positions = [0] * len(names)
+    for position in range(len(names) - 1, -1, -1):
+        remainder, option_index = divmod(remainder, lengths[position])
+        positions[position] = option_index
+    for name, option_index in zip(names, positions, strict=True):
+        values[name] = variables[name][option_index]
+    return values

matrx_assignment/store.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol
+
+from matrx_assignment.models import (
+    AssignmentClaim,
+    AssignmentError,
+    AssignmentExecutionOutput,
+    AssignmentItemSnapshot,
+    AssignmentSessionRequest,
+    AssignmentSessionSummary,
+    MaterializedPlan,
+)
+
+
+class AssignmentStore(Protocol):
+    async def create_or_get_session(
+        self, request: AssignmentSessionRequest, materialized: MaterializedPlan
+    ) -> AssignmentSessionSummary: ...
+
+    async def get_session(self, session_id: str) -> AssignmentSessionSummary: ...
+
+    async def list_items(self, session_id: str) -> list[AssignmentItemSnapshot]: ...
+
+    async def claim_items(
+        self,
+        session_id: str,
+        *,
+        holder: str,
+        limit: int,
+        lease_seconds: int,
+    ) -> list[AssignmentClaim]: ...
+
+    async def mark_running(self, claim: AssignmentClaim) -> None: ...
+
+    async def renew_claim(
+        self, claim: AssignmentClaim, *, lease_seconds: int
+    ) -> bool: ...
+
+    async def complete_item(
+        self, claim: AssignmentClaim, output: AssignmentExecutionOutput
+    ) -> None: ...
+
+    async def fail_item(
+        self,
+        claim: AssignmentClaim,
+        error: AssignmentError,
+        *,
+        retry_at: datetime,
+    ) -> None: ...
+
+    async def finalize_session(self, session_id: str) -> AssignmentSessionSummary: ...
+
+    async def reap_expired_claims(self, session_id: str, *, now: datetime) -> int: ...
+
+    async def cancel_session(self, session_id: str) -> AssignmentSessionSummary: ...

matrx_assignment-0.1.0.dist-info/METADATA

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: matrx-assignment
+Version: 0.1.0
+Summary: Typed planning and durable coordination for resolved variable assignments
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# matrx-assignment
+
+Typed, payload-agnostic assignment planning and durable coordination.
+
+The library turns a strict plan into immutable work items, then drives those
+items through an injected store and executor. Hosts can begin with coordinated
+rows (for example, 50 paired `topic` + `research` inputs) and later add policies
+without changing the agent or workflow execution systems.
+
+Supported plans:
+
+- `coordinated_rows`: preserve paired values and run every row once.
+- `independent_random`: choose every variable independently with unbiased system
+  randomness, optionally without repeating a full combination.
+- `cartesian`: enumerate combinations, optionally in unbiased random order.
+
+Random plans are materialized once and persisted by the host. Recovery therefore
+resumes the same items instead of producing a new draw.

matrx_assignment-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+matrx_assignment/__init__.py,sha256=UnSMFrwWX1hxBoB2p5U7p7PTfGbgg1d4Dqw4XN030j8,1598
+matrx_assignment/coordinator.py,sha256=hCRDI7K_R_uWXx30IdSO-B5Jp2l-n3fBiGpDwsV9s8w,6314
+matrx_assignment/in_memory.py,sha256=zEs6VjcBDwuifpntUMx75ZvAVQMUN_POyFrpYO2tUog,16688
+matrx_assignment/models.py,sha256=MOW7xvmwVZWB39NfkYq32ieb49-hPLyFd7UFRtz6F28,9054
+matrx_assignment/planner.py,sha256=zR-93MJHfXVxMh1Lzbm4M5rscJFSrZDv0UHzMGSPZPw,4895
+matrx_assignment/store.py,sha256=r15d_NsMAbmggfathy0iVHXT9wh1RbHlUrNwFCoopSk,1584
+matrx_assignment-0.1.0.dist-info/METADATA,sha256=bxVi90AtbfAugtadlpZEoSMfpGB5ke-MjIrTXt6PQIM,1232
+matrx_assignment-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+matrx_assignment-0.1.0.dist-info/RECORD,,

matrx_assignment-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any