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)

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)

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.