first

2026-09-08 07:21:34 -04:00
commit a4b224da8e
169 changed files with 27483 additions and 0 deletions
@@ -0,0 +1,65 @@
+# ADR-0004 — AI Gateway Abstraction Layer
+
+- **Status:** Accepted
+- **Date:** 2026-09-07
+- **Deciders:** ASF Architecture Team
+
+## Context
+
+ASF requires LLM capabilities for:
+- Code analysis
+- Requirement decomposition
+- Test generation
+- Context-aware chat ("Ask ASF")
+- Incident analysis
+
+Target inference backends include on-prem DGX Spark, OpenAI-compatible
+local APIs, commercial providers, and customer-hosted endpoints.
+
+Tenants may have different AI policies (allowed models, budgets,
+geographic restrictions).
+
+## Decision
+
+Introduce an **ASF AI Gateway** service (`services/asf-ai/`) with a
+stable Python interface.
+
+### Interface
+
+Business code requests **capabilities**, never models:
+
+```python
+class AIGateway(Protocol):
+    async def analyze_code(self, request: CodeAnalysisRequest) -> AnalysisResult: ...
+    async def generate_tests(self, request: TestGenerationRequest) -> GeneratedTests: ...
+    async def chat(self, request: ChatRequest, ctx: AIContext) -> ChatResponse: ...
+    async def decompose_requirement(self, req: RequirementDecomposeRequest) -> Decomposition: ...
+```
+
+Provider adapters implement the gateway. Model selection, routing,
+priority queuing, usage metering, cost tracking and tenant AI policy
+live inside the gateway — not in callers.
+
+### Bootstrap
+
+The first implementation ships with a `MockProvider` that returns
+deterministic canned responses with realistic latencies. Real providers
+(OpenAI-compatible, NVIDIA, etc.) are added as adapters later without
+touching domain/business code.
+
+## Consequences
+
+### Positive
+- No LLM provider lock-in — swap / add adapters freely.
+- Usage and cost tracking centralized.
+- Tenant-level policy enforceable at one boundary.
+- Tests for business logic run fast against the mock — no external API
+  calls, no flakiness.
+
+### Negative
+- One more abstraction — the initial API surface must be designed
+  carefully so future providers truly fit.
+
+### Mitigation
+- Provider adapters are written early for at least two real providers,
+  to validate the abstraction before domain code depends heavily on it.