// File: specs/200-fullstacks/236-unified-ocr-architecture/research.md
// Change Log:
// - 2026-06-13: Research decisions from ADR-036

# Research: Unified AI Model Architecture — Sandbox-Production Parity

## Overview

This document consolidates technical decisions from ADR-036 for the Unified AI Model Architecture feature. All decisions are already ratified in ADR-036; this document serves as a quick reference for implementation.

## Decisions

### D1: Calibration on Existing Profile/Prompt Stores

**Decision**: Reuse existing `ai_execution_profiles` as production parameter store and create new `ai_sandbox_profiles` as draft store. Do not create new parameter store in `system_settings`.

**Rationale**:
- Existing `ai_execution_profiles` already has the right structure (profile_name, temperature, top_p, etc.)
- Adding `canonical_model` column distinguishes np-dms-ai vs np-dms-ocr
- Avoids schema bloat and migration complexity
- Leverages existing Redis cache in AiPolicyService

**Alternatives Considered**:
- Create new `ai_model_parameters` table → Rejected: unnecessary duplication
- Use `system_settings` JSON → Rejected: loses type safety and queryability

---

### D2: Dual-Model Parameter Management

**Decision**: Store OCR parameters in dedicated row `ocr-extract` with `canonical_model='np-dms-ocr'`. Make `numCtx` and `maxTokens` nullable for OCR (not used).

**Rationale**:
- OCR has different parameter requirements than LLM (no context window, no max tokens)
- Single table with `canonical_model` column simplifies queries
- Nullable columns allow row-level variation without schema fragmentation

**Alternatives Considered**:
- Separate `ai_ocr_profiles` table → Rejected: adds join complexity
- JSON blob for model-specific params → Rejected: loses queryability

---

### D3: Snapshot Semantics

**Decision**: Parameters are frozen at job dispatch time (snapshot), not lazy-loaded during processing. `keep_alive` is excluded from snapshot (lazy-loaded per ADR-033).

**Rationale**:
- Ensures job consistency regardless of subsequent parameter changes
- Allows safe parameter tuning without affecting running jobs
- `keep_alive` is a resource parameter, not a model parameter (ADR-033)

**Alternatives Considered**:
- Lazy-load parameters during processing → Rejected: race condition risk
- Include `keep_alive` in snapshot → Rejected: violates ADR-033 residency logic

---

### D4: Dual-Model Snapshot for OCR+LLM Jobs

**Decision**: Support `ocrSnapshotParams` (OCR) and `snapshotParams` (LLM) in `AiJobPayload` for jobs that use both models.

**Rationale**:
- Migration jobs use both OCR and LLM
- Each model needs its own parameter set
- Separation allows independent tuning

**Alternatives Considered**:
- Single snapshot with union of params → Rejected: unclear which params apply to which model
- Job-level model selection → Rejected: adds complexity to processor logic

---

### D5: Master Data Context Parity in Sandbox

**Decision**: Require project selection in sandbox tests (no 'default' project). Use selected project/contract context for master data lookup.

**Rationale**:
- Eliminates parity gap where sandbox used 'default' while production used real project
- Ensures sandbox tests accurately reflect production behavior
- `{{master_data_context}}` in prompts will match production

**Alternatives Considered**:
- Keep 'default' project for sandbox → Rejected: inaccurate test results
- Auto-select first project → Rejected: hides context selection UI

---

### D6: System Prompt Integration

**Decision**: System prompts managed via ADR-029 (`ai_prompts` table), not duplicated in parameter store. Parameter interface links to Prompt Version UI.

**Rationale**:
- ADR-029 already has versioning, approval workflow, and audit trail
- Avoids duplication and maintenance burden
- Clear separation of concerns (prompts vs runtime parameters)

**Alternatives Considered**:
- Store system prompt in ai_execution_profiles → Rejected: duplicates ADR-029
- Inline system prompt in sandbox draft → Rejected: loses versioning

---

### D7: Model Name Alignment

**Decision**: Update model names from `typhoon2.5-np-dms`/`typhoon-np-dms-ocr` to `np-dms-ai`/`np-dms-ocr` across codebase.

**Rationale**:
- Canonical names are shorter and more semantic
- Aligns with ADR-034 decision
- Simplifies documentation and communication

**Alternatives Considered**:
- Keep typhoon names → Rejected: inconsistent with ADR-034
- Use generic names (main/ocr) → Rejected: loses semantic meaning

---

### D8: Security Guardrails

**Decision**: Apply endpoint requires Idempotency-Key validation, CASL permission (`system.manage_ai`), and parameter range validation (temperature/topP 0-1).

**Rationale**:
- Idempotency-Key prevents duplicate applies
- CASL enforces RBAC
- Range validation prevents invalid parameters
- Audit logging tracks all changes

**Alternatives Considered**:
- Skip Idempotency-Key → Rejected: risk of duplicate applies
- Use weaker permission → Rejected: security risk

---

### D9: Cache Invalidation

**Decision**: Invalidate Redis cache after applying parameters to production.

**Rationale**:
- Ensures new jobs use updated parameters
- Prevents stale cache issues
- Simple DEL operation on cache key

**Alternatives Considered**:
- Wait for cache TTL → Rejected: delayed effect
- No cache invalidation → Rejected: stale parameters

---

### D10: OCR Parameter Wiring to Sidecar

**Decision**: Add `typhoonOptions` to `OcrDetectionInput` and append temperature/topP/repeatPenalty to form data sent to sidecar.

**Rationale**:
- Sidecar already accepts overrides via form data
- Allows OCR model tuning without sidecar changes
- Maintains existing contract

**Alternatives Considered**:
- Modify sidecar API → Rejected: unnecessary infrastructure change
- Hardcode params in sidecar → Rejected: loses tunability

---

## Technology Stack

- **Backend**: NestJS 11, TypeORM, Redis, BullMQ
- **Frontend**: Next.js 16, TanStack Query, React Hook Form, Zod
- **Database**: MariaDB 11.8
- **Testing**: Jest (backend), Vitest + Playwright (frontend)

## Performance Targets

- Apply operation: <2s (including cache invalidation)
- Sandbox test cycle: <5s (test → apply → verify)
- Cache invalidation: <100ms

## Security Considerations

- CASL guard on apply endpoint
- Idempotency-Key validation (5-minute window)
- Parameter range validation (temperature/topP 0-1)
- Audit logging for all apply operations
- No direct DB/storage access from AI (ADR-023/023A)

## Dependencies

- ADR-029: Dynamic Prompt Management (system prompt integration)
- ADR-033: Adaptive OCR Residency (keep_alive lazy-loading)
- ADR-034: AI Model Change (canonical model names)
- Existing AiPolicyService with Redis cache
- Existing ai_audit_logs table