matrx-assignment 0.1.0__tar.gz

matrx_assignment-0.1.0/.gitignore

@@ -0,0 +1,271 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+# The broad `logs/` rule above is for RUNTIME log output, but it also matched
+# the dashboard's SOURCE directory and silently swallowed an entire feature's
+# files (only the pre-existing index.tsx stayed tracked), breaking the prod
+# Docker build with "Could not resolve ./structured-tab". Re-include the source.
+!apps/dashboard/src/features/logs/
+!apps/dashboard/src/features/logs/**
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!apps/dashboard/src/lib/
+!apps/dashboard/src/lib/**
+!apps/workflow-studio/src/lib/
+!apps/workflow-studio/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+# Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
+# member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
+# IS committed; everything below is regenerated.
+node_modules/
+apps/**/.vite/
+apps/**/dist/
+.vite/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template

matrx_assignment-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

matrx_assignment-0.1.0/CLAUDE.md

@@ -0,0 +1,20 @@
+# CLAUDE.md — matrx-assignment
+
+`matrx-assignment` is the payload-agnostic assignment planner and coordinator. It
+materializes variable values, tracks resumable item state through an injected
+`AssignmentStore`, and calls a host-provided executor. It never imports an agent,
+workflow, HTTP, database, cache, or host application.
+
+Hard rules:
+
+- Every known contract is a strict Pydantic model with `extra="forbid"`.
+- Random choices use `secrets.SystemRandom`; pseudo-random seeds and time-derived
+  selection are forbidden.
+- A plan is materialized exactly once. Retries consume persisted items and never
+  re-randomize them.
+- Persistence is a protocol. Database implementations live in the host and must
+  use matrx-orm.
+- The coordinator owns assignment lifecycle only. It does not execute agents or
+  workflows itself.
+
+Run package tests with `uv run pytest packages/matrx-assignment/tests`.

matrx_assignment-0.1.0/FEATURE.md

@@ -0,0 +1,39 @@
+# Coordinated assignment engine
+
+`matrx-assignment` is the payload-blind planning and coordination library for
+turning variable option sets into durable, executable items. It has no agent,
+workflow, database, or HTTP dependency.
+
+## Contracts
+
+- All known request, plan, item, claim, error, and result shapes are strict,
+  frozen Pydantic models (`extra="forbid"`).
+- `coordinated_rows` preserves paired values such as `topic` + `research`.
+- `independent_random` draws combinations with `secrets.SystemRandom`; it can
+  allow repeats or sample without replacement.
+- `cartesian` enumerates every combination, in declared or randomized order.
+- A plan is materialized exactly once. Recovery always reuses the persisted
+  materialization and never redraws random values.
+
+## Host seams
+
+`AssignmentStore` is the only persistence protocol. `AssignmentCoordinator`
+leases items with `SKIP LOCKED` semantics supplied by the host, heartbeats long
+executions, retries retryable failures, reaps expired leases, and returns a
+complete typed result. The injected executor receives a resolved value map and
+can run an agent, image generator, or any future workload without changing the
+engine.
+
+## Recovery and idempotency
+
+The host supplies a logical session key. A retry with the same key resumes the
+same session and deterministic item identities. Each item owns a deterministic
+conversation identity, while attempts are separately audited. Provider calls
+remain at-least-once at the unavoidable crash boundary between an external side
+effect and its database acknowledgement; deterministic request identities make
+that boundary reconcilable instead of invisible.
+
+## Change log
+
+- **2026-07-18** — Initial strict planner, in-memory reference store, lease-based
+  coordinator, heartbeat/retry recovery, and standalone tests.

matrx_assignment-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,18 @@
+# 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/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-0.1.0/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