ADR-0004: Consolidate AI Services (AiService, JorvisAiService, OptimizedAiService)

Status

Proposed (2025-12-23)

Context

Currently, the Jorvis backend has three fragmented AI services:

1. AiService (Legacy): Used by most system flows, lacks structured JSON output support.
2. JorvisAiService (Modern): Gemini-focused, implements ADR-0001 (Structured JSON).
3. OptimizedAiService: Specialized for cost/speed optimizations.

This fragmentation leads to:

• Duplicate prompt logic.
• Inconsistent SQL generation quality.
• Maintenance overhead.
• Circular dependencies when attempting to inject one into another.

Proposed Changes

1. Consolidation: Merge AiService logic into JorvisAiService or vice versa.
2. Abstract AI Interface: Define a single AiProvider interface to decouple business logic from specific LLM implementations.
3. Circular Dependency Resolution:
   • Move shared interfaces (SqlGenerationResult, ConversationHistoryEntry) to a dedicated file src/types/ai.types.ts.
   • Use NestJS forwardRef() only as a last resort; prefer extracting shared logic into standalone utility classes or services.

Phased Migration

1. Phase A (Foundation): Extract shared types and interfaces to ai.types.ts.
2. Phase B (Unified Interface): Implement UnifiedAiService that wraps JorvisAiService.
3. Phase C (Feature Flag): Enable migration for specific callers using JORVIS_USE_UNIFIED_AI_SERVICE.
4. Phase D (Decommissioning): Gradually remove old AiService methods after verification.

Feature Flag

• JORVIS_USE_UNIFIED_AI_SERVICE: (Default: false). When true, system uses the consolidated logic for all SQL generation.

Verification Plan

1. Unit Testing: 100% test coverage for new UnifiedAiService.
2. Regression Testing: Run existing text2sql.eval.spec.ts to ensure no quality drop.
3. E2E Testing: Run pack.sh smoke for both AdventureWorks and Olist.
4. Manual Verification: Cross-verify logs for correct SQL hashing and structured JSON parsing.

Rollback Strategy

• Immediate rollback by setting JORVIS_USE_UNIFIED_AI_SERVICE=false.
• If critical failure persists, revert to the last stable tag (v37).

Security Non-Negotiables

• Maintain SQL sanitization in logs (no raw SQL).
• Ensure SqlGuard remains the final validator for all generated SQL.

Expected Outcome

• Single source of truth for AI interactions.
• Structured JSON output enabled for all system flows.
• Clean, lint-free architecture without circular dependencies.