Metadata-Version: 2.4
Name: matrx-batch
Version: 0.1.1
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.
