AI/Tasks/LLMClientUpgrades/LLM_Phase02_ArchitecturalConsistency_Strict.txt
|
STRICT MODE: Improve architectural consistency and testability in the LLM client stack.
Mission: - Complete this phase with bounded steps and deterministic fallback behavior. - Apply changes ONLY within the LLM client stack, its configuration, and its tests. Concrete scope: - src/TechToolbox.Agent/Llm/LlmClientFactory.cs - src/TechToolbox.Agent/Llm/LlmClient.cs - src/TechToolbox.Agent/Llm/OpenAiCompatibleLlmClient.cs - src/TechToolbox.Agent/Configuration/AgentConfiguration.cs - src/TechToolbox.Agent/Tests/LlmClientTests.cs - src/TechToolbox.Agent/Tests/AgentOrchestratorTests.cs Requirements: - Introduce an injected transport abstraction if needed for deterministic tests. - Stop mutating caller-provided configuration objects during client resolution. - Prefer pure resolution paths that return resolved config/profile data instead of patching input objects. - Add endpoint flexibility for Ollama, including override support and HTTPS/remote deployment compatibility. - Replace static environment reads with injected or reloadable configuration where feasible in this phase. - Add characterization and phase-specific tests before or alongside each change in this phase. - Define ownership for any overlapping transport, callback, retry, or configuration work within this phase and document the boundaries. - Add dependency and compatibility gates before moving beyond this phase, and explicitly note any cross-phase requirements. - Make acceptance criteria mechanically verifiable where possible. - Do not expand into retry relocation, multi-model execution, persistent context, or compression unless specifically approved. - Enforce sensitive-data redaction and resource-limit checks in any diagnostics or logging introduced here. - Keep provider construction thread-safe and predictable. Step budget (hard limits): 1) Discovery: <= 6 read/search tool calls. 2) Edits: <= 8 file edits total. 3) Validation: 1 build + 1 targeted test run; allow exactly 1 repair cycle if failures are phase-related. 4) Stop once acceptance criteria pass. Loop guards: - If config-resolution logic is rewritten twice without clearer tests, stop and report blocker. - If endpoint-flexibility changes begin to affect unrelated providers, narrow back to the minimum viable seam. Fallback behavior: - Fallback A: introduce a minimal transport seam only for the code path that blocks deterministic testing. - Fallback B: if full immutable resolution is too large, isolate the mutation boundary and make it explicit. - Fallback C: after one failed repair cycle, emit FAILED_VALIDATION with precise failing assertions. Acceptance criteria: - Client creation does not depend on mutating shared configuration state. - Endpoint override behavior is supported without hard-coding localhost assumptions. - Tests can exercise the relevant client path deterministically. - Provider resolution remains stable and thread-safe. - Characterization or phase-specific tests cover the configuration and transport changes. - Dependency and ownership boundaries are explicit for shared resolution and transport seams. - Logging and diagnostics redact sensitive data and respect resource limits. Validation commands: - dotnet build src/TechToolbox.Agent/TechToolbox.Agent.csproj -c Release - dotnet test src/TechToolbox.Agent/Tests/TechToolbox.Agent.Tests.csproj -c Release --filter "Factory|Configuration|Endpoint|Transport|Profile" Output results in markdown using this structure: 1) Summary 2) Files changed 3) Transport and factory behavior 4) Configuration resolution behavior 5) Endpoint flexibility behavior 6) Tests added/updated 7) Validation results 8) Step-budget report (planned vs actual counts) |