matrx-runtime 0.0.1__tar.gz

matrx_runtime-0.0.1/.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_runtime-0.0.1/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md — matrx-runtime
+
+> **Operating Principle: Build the platform, not the artifact.** Full doctrine: [/PRINCIPLES.md](../../PRINCIPLES.md).
+
+**Package:** `matrx-runtime` — the **Request Management Layer** — Python 3.13+ — pre-alpha (v0.0.1).
+**Role in the graph:** the generic request/execution substrate. Sits **below** every consumer (`matrx-ai`, `matrx-graph`, `matrx-scraper`, aidream) and **above** `matrx-utils` / `matrx-connect` / `matrx-orm`.
+
+Canonical design: **[docs/runtime/REQUEST_MANAGEMENT_LAYER.md](../../docs/runtime/REQUEST_MANAGEMENT_LAYER.md)** (read it first).
+
+---
+
+## What this package IS
+
+> You hand us a request; we own its entire life and its whole nested tree —
+> identity, nesting, status, every failure and success, accumulated cost and any
+> metered limit, context propagation, cancellation, and resume — **without knowing
+> or caring what the work is.**
+
+## The ONE invariant — payload-blind
+
+matrx-runtime **must never** know the words **chat, agent, conversation, provider,
+token, message, tool**. It deals only in generic `global_execution`s with an
+**opaque `type`** label (a "registered_action": `utility`/`conversation`/`workflow`/…
+— the host's strings, never enumerated here). Feature data lives in the consumer's
+OWN tables, reached only via the opaque `link_kind`/`link_id` pointer. The interiors
+of `MeterEvent` and `ExecutionContext` are opaque too — we sum numerics and
+propagate context without interpreting them.
+
+A test (`test_proof.py`) proves it: one engine drives `utility` + `conversation` +
+`workflow` + every nesting case identically. Run `uv run pytest packages/matrx-runtime/tests/test_proof.py -s`.
+
+## The surface
+
+- **`ExecutionEngine`** (`engine.py`) — the one typed service. `create_root` /
+  `spawn_child` (with a `ContextMode`: inherit|scope|replace) / lifecycle
+  transitions / `record(MeterEvent)` / tree rollups / `ensure_can_proceed` (budget
+  + per-quantity limit + cancel + deadline) / checkpoints. Status changes ONLY via
+  the lifecycle (`transition`), CAS so a terminal is written exactly once.
+- **`ExecutionScope`** (`engine.execution(...)` / `scope.child(...)`) — the ONE
+  uniform lifecycle wrapper every consumer runs work inside: enter creates+starts,
+  clean exit auto-completes with accrued cost, an exception auto-fails (structured
+  error) or cancels and re-raises; `record` / `ensure_can_proceed` / `checkpoint` /
+  `request_input` / `renew_lease` / `note` (opaque observability annotation on THIS
+  execution — the scope-level door to `record_note`) for the body; explicit
+  `complete/fail/cancel` for return-based consumers. No consumer hand-rolls lifecycle — utility/conversation/
+  workflow differ only in the body.
+- **Crash recovery — lease + reaper (layer 1, ACTS) + `find_stuck` (layer 2, ALARMS).**
+  `start(holder=, lease_seconds=)` leases a running execution (opt-in; unleased = never
+  reaped), `renew_lease(...)` heartbeats, **`reap_expired(now=)`** sweeps dead-worker
+  executions → FAILED `matrx_execution_abandoned` (cost preserved, CAS-safe). Because
+  unleased actives are structurally invisible to the reaper, **`find_stuck(now=, older_than=)`**
+  is the independent second layer: it RETURNS (never mutates) the reaper-blind stuck rows
+  (unleased/ never-started actives past a deadline) so the host watchdog screams — no work is
+  ever silently lost. Both host-scheduled.
+- **`MeterEvent`** (`models.py`) — the metering primitive. A consumer subclasses it
+  with numeric fields; EVERY numeric is a tracked quantity summed per execution +
+  tree; `money_field` feeds the budgeted `cost`. Covers money, tokens, rate-limits,
+  rows — one mechanism, runtime knows none of their meanings.
+- **`ExecutionContext`** + `ContextMode` — the typed context carrier. Runtime owns
+  PROPAGATION + per-execution SNAPSHOT across the tree (where the nested-handoff bug
+  class lived); the interior is opaque; creation stays Matrx Connect.
+- **Origin registry** (`origins.py`) — `sync_origins` (config-driven, drift-checked,
+  soft-deleted) + `is_caller_allowed` (host admission policy). CORS/transport stays
+  Connect; runtime owns only the guest list + policy.
+- **`ExecutionStore`** port + `InMemoryExecutionStore` (tests) + matrx-orm
+  `OrmExecutionStore` (the 7 `runtime.*` tables).
+
+## What this package is NOT
+
+- **NOT an executor.** The conversation loop is `matrx-ai`'s; the workflow superstep
+  is `matrx-graph`'s; utilities are the consumer's. They drive the engine; their
+  complexity never leaks in here.
+- **NOT transport** (CORS/auth/streaming = Matrx Connect), **NOT the work**, **NOT a
+  general logger**, **NOT feature tables.**
+
+## DB models
+
+`db/models_runtime.py` is GENERATED (the `runtime` entry in aidream's
+`db/matrx_orm.yaml`) — change the live schema, then `python db/generate.py`; never
+hand-edit beyond keeping it in sync. The 7 tables: `global_origin`,
+`global_request`, `global_execution`, `global_execution_control`,
+`global_execution_event`, `global_execution_checkpoint`, `global_meter_entry`.
+
+## Standalone substrate (the package DEFINES its own schema)
+
+matrx-runtime is a **standalone, opinionated** package: it ships the canonical
+substrate it needs and CREATES it on a bare DB. `db/bootstrap/*.sql` (applied in
+`NNN_*` order by **`apply_schema()`**) creates the schemas (`platform`/`iam`/`runtime`),
+the `visibility`/`permission_level` enums, the portable `_touch_row`/`_stamp_actor`
+trigger functions (GUC actor, NOT `auth.uid()`), a minimal `organizations` + registries
++ fail-closed `iam.has_access`, and the 7 `runtime.*` tables + indexes + triggers + RLS.
+- **Standalone:** `bootstrap_db()` (pool) → `await apply_schema()` (DDL). Fresh DB → working spine.
+- **Hosted (aidream):** the real substrate exists; aidream does NOT call `apply_schema()`.
+- **THE INVARIANT — non-destructive:** every statement is `IF NOT EXISTS` /
+  create-if-absent / `ON CONFLICT DO NOTHING`. Running it against aidream changes
+  NOTHING; it never overwrites a richer host object. `test_bootstrap_schema.py` enforces
+  this. Full design + the pattern for other packages: [docs/runtime/STANDALONE_SUBSTRATE.md](../../docs/runtime/STANDALONE_SUBSTRATE.md).
+
+## Dependency rules (mechanically enforced)
+
+- Declare ONLY what you import (`pydantic`, `matrx-orm`). The boundary gate fails
+  the build on an undeclared sibling or any `aidream`/repo-root import.
+- ❌ Never import an executor (`matrx-ai`, `matrx-graph`) — the dependency points the other way.
+- ❌ Never name a chat/agent/provider concept in this package.
+
+## Testing
+
+```bash
+uv run pytest packages/matrx-runtime/tests
+```
+
+The whole behavioral core is tested against `InMemoryExecutionStore`, **no
+database**. `OrmExecutionStore` is unit-tested with mocked matrx-orm Models
+(`test_orm_store.py`) — call-shape only, never a live DB.

matrx_runtime-0.0.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: matrx-runtime
+Version: 0.0.1
+Summary: The durable-execution substrate: one global_execution spine, one lifecycle state machine, one cost ledger, that every matrx-* executor (agent loop, workflow superstep, utilities) plugs into.
+Author-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: durable,execution,matrx,orchestration,runtime
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: matrx-orm>=3.1
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# matrx-runtime
+
+The durable-execution substrate for the Matrx platform.
+
+Every unit of work — a utility call, a workflow run, an agent session — is one
+row on a single `global_execution` spine that can nest inside any other. The
+substrate owns the concerns all three flavors share, so they compose freely and
+share **one lifecycle, one nesting tree, one cost ledger, and one enforced state
+machine**:
+
+- run identity + lineage (`parent_execution_id`, denormalized `root_execution_id`)
+- the lifecycle state machine (`transition()` — the only legal way to change status)
+- the cost ledger + tree-wide budget *(forthcoming)*
+- cancellation signal + down-tree propagation *(forthcoming)*
+- generalized checkpoint + lifecycle-event primitives *(forthcoming)*
+- the hardened write coordinator *(moving in from matrx-ai)*
+- the typed runtime context *(forthcoming)*
+
+Executors plug in as strategies and are NOT owned here: the agent loop
+(`matrx-ai`), the superstep DAG (`matrx-graph`), utility implementations
+(`matrx-scraper`).
+
+Status: **pre-alpha.** The pure decision core (lifecycle + spine models) is in
+place; the persistence/coordinator/context drops follow. Built behind a `/v2`
+route; the legacy `cx_*` / `wf_*` paths are untouched until cutover.
+
+Design + phased plan: [`docs/runtime/EXECUTION_SPINE.md`](../../docs/runtime/EXECUTION_SPINE.md).

matrx_runtime-0.0.1/README.md

@@ -0,0 +1,27 @@
+# matrx-runtime
+
+The durable-execution substrate for the Matrx platform.
+
+Every unit of work — a utility call, a workflow run, an agent session — is one
+row on a single `global_execution` spine that can nest inside any other. The
+substrate owns the concerns all three flavors share, so they compose freely and
+share **one lifecycle, one nesting tree, one cost ledger, and one enforced state
+machine**:
+
+- run identity + lineage (`parent_execution_id`, denormalized `root_execution_id`)
+- the lifecycle state machine (`transition()` — the only legal way to change status)
+- the cost ledger + tree-wide budget *(forthcoming)*
+- cancellation signal + down-tree propagation *(forthcoming)*
+- generalized checkpoint + lifecycle-event primitives *(forthcoming)*
+- the hardened write coordinator *(moving in from matrx-ai)*
+- the typed runtime context *(forthcoming)*
+
+Executors plug in as strategies and are NOT owned here: the agent loop
+(`matrx-ai`), the superstep DAG (`matrx-graph`), utility implementations
+(`matrx-scraper`).
+
+Status: **pre-alpha.** The pure decision core (lifecycle + spine models) is in
+place; the persistence/coordinator/context drops follow. Built behind a `/v2`
+route; the legacy `cx_*` / `wf_*` paths are untouched until cutover.
+
+Design + phased plan: [`docs/runtime/EXECUTION_SPINE.md`](../../docs/runtime/EXECUTION_SPINE.md).

matrx_runtime-0.0.1/matrx_runtime/__init__.py

@@ -0,0 +1,146 @@
+"""matrx-runtime — the Request Management Layer.
+
+You hand us a request; we own its entire life and its whole nested tree —
+identity, nesting, status, every failure and success, accumulated cost and any
+metered limit, context propagation, cancellation, and resume — WITHOUT knowing or
+caring what the work is. Payload-blind: never chat, agents, providers, tokens, or
+messages. Feature data stays in the consumer's tables, reached via an opaque
+`link_kind`/`link_id`.
+
+Design: docs/runtime/REQUEST_MANAGEMENT_LAYER.md. Public API = exactly __all__.
+"""
+
+from __future__ import annotations
+
+from matrx_runtime.lifecycle import (
+    ALLOWED_TRANSITIONS,
+    InvalidExecutionTransition,
+    TransitionResult,
+    can_transition,
+    event_for_transition,
+    is_terminal,
+    transition,
+)
+from matrx_runtime.engine import (
+    DEFAULT_LEASE_SECONDS,
+    BudgetExceeded,
+    ConcurrentTransition,
+    DeadlineExceeded,
+    ExecutionCancelled,
+    ExecutionEngine,
+    ExecutionNotFound,
+    ExecutionScope,
+    InvalidLeaseState,
+    LimitExceeded,
+)
+from matrx_runtime.models import (
+    TERMINAL_STATUSES,
+    ContextMode,
+    ExecutionCheckpoint,
+    ExecutionContext,
+    ExecutionControl,
+    ExecutionError,
+    ExecutionEvent,
+    ExecutionEventKind,
+    ExecutionOutcome,
+    ExecutionStatus,
+    ExecutionTree,
+    ExecutionTreeNode,
+    GlobalExecution,
+    MeterEntry,
+    MeterEvent,
+    Origin,
+    Request,
+)
+from matrx_runtime.store import ExecutionStore, InMemoryExecutionStore
+from matrx_runtime.orm_store import OrmExecutionStore
+from matrx_runtime.origins import (
+    OriginSpec,
+    OriginSyncResult,
+    is_caller_allowed,
+    sync_origins,
+)
+from matrx_runtime.db import PACKAGE_DB_NAME, apply_schema, bind_to_host, bootstrap_db
+
+__version__ = "0.0.1"
+
+
+def configure(*, db_config_name: str | None = None) -> None:
+    """Host-injection entry point (called once at startup; mirrors matrx-rag).
+    `db_config_name` is the matrx-orm pool the host already registered — we alias
+    the package's `"matrx_runtime"` name onto it and register the `runtime.*`
+    Models the `OrmExecutionStore` needs. Standalone installs call `bootstrap_db()`."""
+    from matrx_runtime import _config
+
+    if db_config_name is not None:
+        _config.set_db_config_name(db_config_name)
+        from matrx_orm import is_database_registered
+
+        from matrx_runtime.db import bind_to_host as _bind
+
+        if is_database_registered(db_config_name):
+            _bind(db_config_name)
+    _config.mark_configured()
+
+
+def is_configured() -> bool:
+    from matrx_runtime import _config
+
+    return _config.is_configured()
+
+
+__all__ = [
+    # lifecycle
+    "transition",
+    "can_transition",
+    "is_terminal",
+    "event_for_transition",
+    "TransitionResult",
+    "InvalidExecutionTransition",
+    "ALLOWED_TRANSITIONS",
+    # engine
+    "ExecutionEngine",
+    "ExecutionScope",
+    "ExecutionNotFound",
+    "ConcurrentTransition",
+    "BudgetExceeded",
+    "LimitExceeded",
+    "DeadlineExceeded",
+    "ExecutionCancelled",
+    "InvalidLeaseState",
+    "DEFAULT_LEASE_SECONDS",
+    # store
+    "ExecutionStore",
+    "InMemoryExecutionStore",
+    "OrmExecutionStore",
+    # origin registry
+    "OriginSpec",
+    "OriginSyncResult",
+    "sync_origins",
+    "is_caller_allowed",
+    # host wiring / db binding
+    "configure",
+    "is_configured",
+    "bind_to_host",
+    "bootstrap_db",
+    "apply_schema",
+    "PACKAGE_DB_NAME",
+    # models / enums
+    "GlobalExecution",
+    "ExecutionStatus",
+    "ExecutionEventKind",
+    "ContextMode",
+    "ExecutionContext",
+    "ExecutionError",
+    "ExecutionOutcome",
+    "ExecutionControl",
+    "ExecutionEvent",
+    "ExecutionCheckpoint",
+    "ExecutionTree",
+    "ExecutionTreeNode",
+    "MeterEvent",
+    "MeterEntry",
+    "Origin",
+    "Request",
+    "TERMINAL_STATUSES",
+]

matrx_runtime-0.0.1/matrx_runtime/_config.py

@@ -0,0 +1,52 @@
+"""Host-injection registry — the seam between matrx-runtime and its host.
+
+The host calls :func:`matrx_runtime.configure` once at startup; the package reads
+back what it needs here. Kept tiny and dependency-free (the boundary gate stays
+green). Today the only seam is the matrx-orm pool name the spine persists to; the
+Coordinator/context drops will add their seams here the same way.
+"""
+
+from __future__ import annotations
+
+import os
+
+_registry: dict[str, object] = {
+    # matrx-orm pool identifier the host registered via
+    # register_database_from_env. matrx_runtime.configure(db_config_name=...)
+    # aliases PACKAGE_DB_NAME onto it.
+    "db_config_name": None,
+}
+
+_configured = False
+
+
+def set_db_config_name(name: str) -> None:
+    _registry["db_config_name"] = name
+
+
+def is_configured() -> bool:
+    return _configured
+
+
+def mark_configured() -> None:
+    global _configured
+    _configured = True
+
+
+def get_db_config_name() -> str:
+    """Resolve the host's matrx-orm pool name.
+
+    Order: the name injected via ``configure(db_config_name=...)`` → the
+    ``MATRX_RUNTIME_DB_NAME`` env var (name of an already-registered config).
+    Raises if neither is set — running the ORM-bound store with no configured
+    pool is a wiring bug, surfaced loudly rather than silently no-op'd.
+    """
+    name = _registry.get("db_config_name") or os.environ.get("MATRX_RUNTIME_DB_NAME")
+    if not name:
+        raise RuntimeError(
+            "matrx-runtime: no database configured. Call "
+            "matrx_runtime.configure(db_config_name=<registered matrx-orm pool>) "
+            "at host startup, set MATRX_RUNTIME_DB_NAME, or use "
+            "matrx_runtime.bootstrap_db() for a standalone pool."
+        )
+    return str(name)