matrx-batch 0.1.0__tar.gz

matrx_batch-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_batch-0.1.0/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md — matrx-batch
+
+> **Operating Principle: Build the platform, not the artifact.** Every task is a probe that exposes a missing capability — build it, then consume it. Full doctrine: [/PRINCIPLES.md](../../PRINCIPLES.md).
+
+**Package:** `matrx-batch` (PyPI) — Python 3.13+ — currently v0.1.0
+**Role in the graph:** One notch above `matrx-utils`. Depends on
+`matrx-utils` only. Consumed by `matrx-rag` (embedding cache) and
+`matrx-ai` (urgency router). MUST NOT depend on any other matrx-*
+sibling at module-import time.
+
+---
+
+## What this package owns
+
+Three primitives, one mission: make AI cost shape predictable.
+
+1. **`openai_batch.py`** — async wrapper over OpenAI's Batch API.
+   `submit_batch(jobs)` → uploads JSONL via `files.create(purpose="batch")`,
+   then `batches.create()`. `poll_batch(id)` returns a typed status.
+   `fetch_results(id)` parses the output JSONL into typed results.
+2. **`anthropic_batch.py`** — same shape over Anthropic Message Batches
+   (`messages.batches.create()`).
+3. **`router.py`** — `BatchRouter.submit(job)` decides live vs batch
+   based on `job.urgency`. `live` → direct provider call. `batch` →
+   enqueue. `auto` → cost-based (default threshold: >5000 estimated
+   tokens → batch).
+4. **`embedding_cache.py`** — `EmbeddingCache.get_or_compute(text,
+   model, organization_id=...)` reads/writes `rag.embedding_cache`.
+   SHA256(`f"{model}::{text}"`) keyed. Increments `hit_count` on every
+   reuse, on matrx-orm — see rule 4.
+
+---
+
+## The hard rules
+
+1. **No imports from `aidream/` or from any other matrx-* sibling.** This
+   is the Package Independence Rule (root CLAUDE.md). If matrx-batch
+   needs ORM models, settings, or a context resolver, it accepts them
+   via `configure(...)`.
+2. **No top-level provider SDK imports.** The `openai` / `anthropic`
+   imports happen lazily inside method bodies. Hosts that swap the
+   provider clients via `configure(...)` never pay the SDK import cost.
+3. **No new asyncpg pool.** The package never opens its own connection.
+4. **Every DB access goes through matrx-orm. There is no exception here.**
+   A package that touches a database depends on matrx-orm — always, no
+   package is exempt. "It's a sibling package, so it can't use the ORM"
+   is FALSE: models arrive by name through the injection seam
+   (`get_db_model(...)` / a `db/db_requirements.py` manifest), exactly as
+   matrx-rag and matrx-graph do. **Canonical doctrine — read it before
+   touching any DB code here:**
+   [`.claude/skills/eliminate-raw-sql/SKILL.md`](../../.claude/skills/eliminate-raw-sql/SKILL.md).
+   - `embedding_cache.py`'s `rag.embedding_cache` access is **fully
+     converted** — zero raw SQL remains in this package.
+
+---
+
+## The `configure()` injection pattern
+
+```python
+import matrx_batch
+
+matrx_batch.configure(
+    openai_client=AsyncOpenAI(api_key=...),     # provider client
+    anthropic_client=AsyncAnthropic(api_key=...),
+    pool_factory=async_callable_returning_asyncpg_pool,
+    cost_check=async_callable_for_budget_precheck,  # optional
+    # auto_threshold_tokens=5000,                  # optional override
+)
+```
+
+Hosts that don't configure a slot get a sensible fallback or a
+loud `BatchNotConfiguredError` at call time (never at import time —
+`import matrx_batch` always succeeds in a minimal environment).
+
+When adding a new injection point:
+
+1. Add a new keyword arg to `configure(...)` in `__init__.py`.
+2. Store it in `_ext.py`'s registry.
+3. Access via `get_ext("name")` at the call site (NOT at module top).
+4. Document the slot here and in the host's `package_integration.py`.
+
+---
+
+## Dependency rules specific to this package
+
+- ✅ `from matrx_utils import ...` — declared workspace dep.
+- ✅ `from openai import ...`, `from anthropic import ...` — declared
+   runtime deps; import lazily.
+- ✅ `from matrx_orm import ...` — matrx-batch touches a database, so it
+  uses the ORM like every other package. Concrete host models resolve by
+  name through the injection seam, never by importing host model files.
+- ❌ No hand-written SQL over a raw pool. (The legacy `asyncpg` pool in
+  `embedding_cache.py` is debt being burned down — do not add to it.)
+- ❌ No `from matrx_rag import ...` or `from matrx_ai import ...`
+  (they consume us, not the other way around — would create a cycle).
+- ❌ No `from aidream import ...` or any root-module imports.
+
+---
+
+## Testing this package in isolation
+
+```bash
+uv run pytest packages/matrx-batch/tests
+```
+
+Tests run with mocked providers and a mocked / in-memory pool. No live
+DB or provider keys required. Real-DB integration coverage lives in
+aidream's test suite.
+
+---
+
+## What lives where
+
+| File | Owns |
+|---|---|
+| `__init__.py` | Public API: `configure()`, `BatchRouter`, `BatchableJob`, `EmbeddingCache`, `get_embedding_cache()` |
+| `_ext.py` | Injection registry — host config storage |
+| `openai_batch.py` | OpenAI Batch submit / poll / fetch |
+| `anthropic_batch.py` | Anthropic Message Batches submit / poll / fetch |
+| `router.py` | Urgency-based routing decision |
+| `embedding_cache.py` | `rag.embedding_cache` read/write + hit_count |
+| `tests/test_embedding_cache.py` | Cache hit/miss/hit_count verification |
+| `tests/test_router.py` | Urgency routing decision |
+
+---
+
+## Known gotchas
+
+- Batch APIs have a 24h SLA. Never block inference on a batch
+  submission — the router always returns a `JobReceipt` immediately;
+  consumers poll the receipt or wire a webhook.
+- The embedding cache is content-addressable. Two orgs that produce
+  identical text get one row. `organization_id` is stored for cleanup
+  queries but is NOT part of the cache key.
+- `hit_count` is incremented in the SAME UPDATE that touches `created_at`,
+  so a high-traffic key is also a hot row. Acceptable: the index leaf
+  doesn't move because the PK is fixed.

matrx_batch-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: matrx-batch
+Version: 0.1.0
+Summary: Cost-shield foundation for AI workloads: OpenAI + Anthropic Batch APIs, live/batch urgency router, shared embedding cache.
+Author-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: anthropic,batch,cost,embeddings,matrx,openai
+Classifier: Development Status :: 3 - 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: anthropic>=0.40
+Requires-Dist: matrx-orm
+Requires-Dist: matrx-utils
+Requires-Dist: openai>=2.0
+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-batch
+
+Cost-shield foundation for AI workloads in the Matrx ecosystem.
+
+Three primitives:
+
+1. **OpenAI Batch API + Anthropic Message Batches** — submit JSONL, poll
+   status, fetch results. Async wrappers over the provider SDKs.
+2. **Urgency router** — `BatchRouter.submit(job)` routes a job to live
+   inference, to the provider's Batch API (50% discount, 24h SLA), or
+   makes a cost-based decision automatically.
+3. **Embedding cache** — content-addressable (SHA256 of `model || text`)
+   reuse of embedding vectors across the org. Backed by
+   `rag.embedding_cache` via a host-supplied asyncpg pool.
+
+## Dependency posture
+
+`matrx-batch` sits one notch above `matrx-utils` in the dependency graph
+and is consumed by `matrx-rag` (embedding cache) and `matrx-ai` (urgency
+router, future). It **MUST NOT** import from `aidream/` or from any other
+`matrx-*` sibling — every cross-boundary dependency comes in via
+`matrx_batch.configure(...)`.
+
+## Usage (host-side wiring)
+
+```python
+import matrx_batch
+from openai import AsyncOpenAI
+from anthropic import AsyncAnthropic
+
+matrx_batch.configure(
+    openai_client=AsyncOpenAI(api_key=settings.OPENAI_API_KEY),
+    anthropic_client=AsyncAnthropic(api_key=settings.ANTHROPIC_API_KEY),
+    pool_factory=lambda: get_async_pg_pool(),
+    cost_check=_aidream_budget_precheck,
+)
+
+# Wire the cache into matrx-rag's embed() funnel
+import matrx_rag
+matrx_rag.configure(embedding_cache=matrx_batch.get_embedding_cache())
+```
+
+## Usage (consumer)
+
+```python
+from matrx_batch import BatchRouter, BatchableJob
+
+router = BatchRouter()
+receipt = await router.submit(
+    BatchableJob(
+        kind="chat",
+        provider="anthropic",
+        urgency="auto",
+        payload={"model": "claude-haiku-4-5", "messages": [...]},
+        estimated_tokens_in=8200,
+    )
+)
+```
+
+## See also
+
+- `CLAUDE.md` — package rules and injection-point contract.
+- `matrx_batch/embedding_cache.py` — chunk-level embedding reuse.
+- `matrx_batch/router.py` — urgency routing decisions.

matrx_batch-0.1.0/README.md

@@ -0,0 +1,64 @@
+# matrx-batch
+
+Cost-shield foundation for AI workloads in the Matrx ecosystem.
+
+Three primitives:
+
+1. **OpenAI Batch API + Anthropic Message Batches** — submit JSONL, poll
+   status, fetch results. Async wrappers over the provider SDKs.
+2. **Urgency router** — `BatchRouter.submit(job)` routes a job to live
+   inference, to the provider's Batch API (50% discount, 24h SLA), or
+   makes a cost-based decision automatically.
+3. **Embedding cache** — content-addressable (SHA256 of `model || text`)
+   reuse of embedding vectors across the org. Backed by
+   `rag.embedding_cache` via a host-supplied asyncpg pool.
+
+## Dependency posture
+
+`matrx-batch` sits one notch above `matrx-utils` in the dependency graph
+and is consumed by `matrx-rag` (embedding cache) and `matrx-ai` (urgency
+router, future). It **MUST NOT** import from `aidream/` or from any other
+`matrx-*` sibling — every cross-boundary dependency comes in via
+`matrx_batch.configure(...)`.
+
+## Usage (host-side wiring)
+
+```python
+import matrx_batch
+from openai import AsyncOpenAI
+from anthropic import AsyncAnthropic
+
+matrx_batch.configure(
+    openai_client=AsyncOpenAI(api_key=settings.OPENAI_API_KEY),
+    anthropic_client=AsyncAnthropic(api_key=settings.ANTHROPIC_API_KEY),
+    pool_factory=lambda: get_async_pg_pool(),
+    cost_check=_aidream_budget_precheck,
+)
+
+# Wire the cache into matrx-rag's embed() funnel
+import matrx_rag
+matrx_rag.configure(embedding_cache=matrx_batch.get_embedding_cache())
+```
+
+## Usage (consumer)
+
+```python
+from matrx_batch import BatchRouter, BatchableJob
+
+router = BatchRouter()
+receipt = await router.submit(
+    BatchableJob(
+        kind="chat",
+        provider="anthropic",
+        urgency="auto",
+        payload={"model": "claude-haiku-4-5", "messages": [...]},
+        estimated_tokens_in=8200,
+    )
+)
+```
+
+## See also
+
+- `CLAUDE.md` — package rules and injection-point contract.
+- `matrx_batch/embedding_cache.py` — chunk-level embedding reuse.
+- `matrx_batch/router.py` — urgency routing decisions.