AnyoneLearnAI
Start learning
Chapter DBatch API labPage 2 of 8

Batch API lab

Set up interfaces and contracts

Batch API lab is production work only when one frozen failure can be reproduced, one measurable gate can stop a release, and one operator can safely reverse it.

~14 minSetup

Before you start

Why this matters

Read this incident aloud: a provider partially completes a batch, retries callbacks, and returns results out of input order. In two minutes, write the earliest deterministic check that should fail, the telemetry signal you would inspect, and the action that must not happen automatically. Compare your answer with this chapter's boundary: batch payloads exclude restricted documents; signed result URLs expire and workers have write access only to the staging index.

1Learn the idea

Read

Build typed boundaries and fixtures

Code begins at the boundary, not at the provider SDK. Parse BatchItem with custom_id, document_id, chunk_hash, text, model, and index_version before any model or tool call, and return BatchRecord with job_id, state, completed, failed, cost_usd, manifest_hash, and result_uri even when the provider times out. Typed records make malformed data a normal error path instead of an exception discovered after a side effect. Inject the model client, clock, action adapter, and telemetry sink so tests can replace each one. That design also prevents a local test from accidentally reaching production.

The important implementation choice is ordering. Authenticate and normalize first; make the controlled call second; validate the response third; commit any state or action last. For this system, batch payloads exclude restricted documents; signed result URLs expire and workers have write access only to the staging index. A convenient function that mixes parsing, generation, action, and logging cannot prove that ordering. Keep each stage named so a trace can show which boundary rejected the request.

Use deterministic identifiers derived from stable business inputs when retries are possible. Record the release, fixture version, and policy version with the result. Never derive authorization from generated text. The code path should make the safe behavior easier than bypassing it: callers receive a decision object, not an unrestricted provider response.

For setup, define dataclasses or schemas, dependency protocols, and a fixture loader. Validate fixture uniqueness at startup and fail closed if required policy fields are absent. The contract should make illegal states difficult to construct.

Read

Focused implementation artifact

from dataclasses import dataclass

@dataclass(frozen=True)
class LabInput:
    payload: dict
    release: str
    trace_id: str

@dataclass(frozen=True)
class LabResult:
    passed: bool
    reasons: tuple[str, ...]
    metrics: dict[str, float]

def load_fixture() -> LabInput:
    payload = {"custom_id":"doc42:chunk7:sha256-ab12","document_id":"doc42","chunk_hash":"sha256-ab12","text":"Returns require a receipt.","model":"embed-v3","index_version":"staging-44"}
    assert payload, "fixture must not be empty"
    return LabInput(payload, "candidate", "trace-test-001")

Read

Exercise the contract

Construct the fixture through the typed input, then deliberately remove one required field and add one unknown field. Decide whether each is rejected at parse time or represented explicitly. A permissive dictionary that silently drops data is not a contract. Record validation errors with a fixture ID and trace ID, but not the rejected payload.

Next, substitute fake adapters for model, storage, clock, telemetry, and external actions. Each fake should record calls, support a deterministic response, and default to denying network or side effects. Use those records to prove that a malformed input causes zero provider calls. The contract's primary result should carry enough data to compute successful unique chunks per dollar and emit embedding_batch_completion_ratio without reopening raw input.

Recreate a retried completion webhook inserts the same chunk twice and silently increases index size as a fixture-construction test. If the type system cannot express the expectation, add an explicit policy field rather than hiding it in a comment. Keep the boundary enforceable in code. On violation, reconcile by custom_id, retry only failed items, verify the staging index, then atomically swap its alias.

Checking tutor…

Continue learning · glossary & guides