# core/inference — AGENTS.md

## Purpose

Provider abstraction and routing for LLM inference: defines `InferenceProvider`, `InferenceRouter`, prompt rendering, embedder/tokenizer contracts, and the projection stack for tracking inference history.

## Ownership

CORREX kernel team.

## Local Contracts

- `InferenceProvider` — interface for making inference calls. Implementations in `infrastructure/` (llama.cpp, remote providers).
- `InferenceRouter` / `DefaultInferenceRouter` — selects a provider, applies routing policy, caches provider selection.
- `InferenceRequest` / `InferenceResponse` — request/response types. `ResponseFormat` controls output structure.
- `GenerationConfig` — sampling parameters.
- `ModelCapability` — capability flags per model (e.g. tool-use, function-calling).
- `PromptRenderer` — renders a `ContextPack` into the provider's prompt format. All SYSTEM-role entries fold into the leading system message; ordering by `ContextEntry.ordinal` for non-system entries.
- `Embedder` / `NoopEmbedder` — vector embedding interface; `NoopEmbedder` for contexts without embedding support.
- `Tokenizer` — token counting interface; implementations in `infrastructure/`.
- `InferenceState` rebuilt from `InferenceEvents` via `DefaultInferenceReducer` + `InferenceProjector`.
- `InferenceRepository` wraps `EventReplayer<InferenceState>`.
- `InferenceCancellationToken` / `CancellationReason` — cooperative cancellation model.
- `ProviderHealth` — health status reported by a provider.
- `ToolDefinition` / `ToolCallRequest` — types for tool-use in inference requests.
- Hard Invariant #7: LLM outputs are untrusted until validated by `core:validation`.
- Hard Invariant #8: Replay uses `ReplayInferenceProvider` in `core:kernel` — no live LLM calls during replay.

## Work Guidance

- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
- `DefaultInferenceReducer` only does `state.copy(...)`.
- Never call a live provider from within this module's domain logic. Provider instantiation is in `infrastructure/`.
- `ModelLoadException` — thrown when a required model is unavailable. Callers must handle this as a terminal condition for the operation.

## Verification

```bash
./gradlew :core:inference:test --rerun-tasks
```

Tests in `testing/contracts/` (InferenceProviderContractTest, DefaultInferenceRouterTest) and `testing/projections/` (InferenceProjectorTest, InferenceReducerTest) and `testing/deterministic/` (PromptRendererOrderingTest).

## Child DOX Index

No child AGENTS.md (leaf module).