correx/core/inference/AGENTS.md

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

./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).