Core Engine & Pipeline
The orchestration core and the request pipeline that every interaction flows through. For developers who want to understand how a prompt becomes a validated answer.
Deep-dive into the
orazaka-coremodule — the stateless, Spring AI-powered orchestration library.
1. Architectural Position
orazaka-core is the central orchestration library. It is strictly stateless, web-agnostic, database-agnostic, and security-context-agnostic. It wraps Spring AI (1.1.6) under a single entry facade: AiClient.
2. The AiClient Facade & Request Records
All AI operations invoke the unified AiClient:
public interface AiClient {
ChatResponse chat(ChatRequest request);
Flux<ChatResponse> stream(ChatRequest request);
AudioResponse audio(AudioRequest request);
ImageResponse image(ImageRequest request);
VideoResponse video(VideoRequest request);
}Request payloads are immutable Java records enforcing compact constructor validation boundaries (ERR-106, ERR-116).
3. Dynamic Pipeline Orchestrator
The orchestrator executes a sequence of PromptContextInterceptor beans. It can be bypassed using:
orazaka.core.orchestration.pipeline.enabled=false.
Routing Modes (orazaka.core.orchestration.routing.mode)
- DETERMINISTIC: Database-driven order configured in
pipeline_interceptor_config. - AGENTIC: LLM-driven runtime intent classification.
Kill-Switch
If orazaka.security.disable-ai=true, any interceptor returning isAiDependent() == true raises a SecurityException.
Core Interceptor Chain Blueprint
| Order | Interceptor | Module | AI-Dep | Purpose |
|---|---|---|---|---|
| 1 | UserContextResolver | context | No | RBAC & rate-limiting tier |
| 2 | SystemContextInjector | context | No | Hardware status & env tags |
| 3 | LanguageAlignmentInterceptor | translation | No | English reasoning enforcement |
| 3 (DB: 3) | RagInterceptor | enrichment | No | Vector store retrieval and context injection |
| 4 (DB: 4) | McpInterceptor | enrichment | No | External MCP knowledge resolution |
| 5 (DB: 5) | MemoryInterceptor | enrichment | No | Conversation history prepend (FIFO window) |
| 6 (DB: 6) | RefinerInterceptor | reformulation | Yes | Fuzzy query to precise instruction refinement |
| 7 (DB: 7) | RouterInterceptor | reformulation | Yes | Intent to optimal provider routing |
| 8 (DB: 8) | ToolInterceptor | tooling | No | Dynamic tool callback attachment |
| 9 (DB: 9) | MediaInterceptor | validation | No | Base64 media extraction and multimodal assembly |
| - | CostShieldInterceptor | validation | No | Offloads to cloud if host memory > 85% |
| Inf | QuantumValidationAdvisor | validation | Yes | 4-tier closed-loop validation |
4. Engine Topology
Engines map core models to Spring AI integrations:
5. Outbound Ports & Lifecycle Policies
- Interface-Driven Boundaries: Outbound ports (e.g.
ChatGeneratorClient,VideoGeneratorClient) live as public interfaces indomain.ports.outbound. Implementations reside in infrastructure packs as package-private beans. - Resource Recovery: Streams and SSE channels must register completion/timeout hooks (
onCompletion,.doFinally()) to dispose subscriptions (Disposable.dispose()) and prevent memory leaks. - Hikari Database Connection Eviction:
hikari: maximum-pool-size: 10 minimum-idle: 2 idle-timeout: 30000 # Evict idle connections in 30s max-lifetime: 60000 # Recycle before DB timeout connection-timeout: 5000 # Fail fast in 5s
6. Model Catalog & Chat Configuration
- Database Model Catalog: Image, video, and speech models reside in the
orazaka_modelstable. Cached via Caffeine TTL. - Chat Model Resolution Cascade:
ORAZAKA_OLLAMA_MODELenvironment variable (highest priority)spring.ai.ollama.chat.options.modelYAML value- Auto-detected default (first non-embedding model from Ollama tags catalog)