stack/docs/scratchpads/m3-001-provider-adapter.md

M3-001 Provider Adapter Pattern — Scratchpad

Objective

Refactor ProviderService into an IProviderAdapter pattern without breaking existing Ollama flow.

Plan

1. Add IProviderAdapter interface and supporting types to @mosaicstack/types provider package
2. Create apps/gateway/src/agent/adapters/ directory with:
   • provider-adapter.interface.ts — IProviderAdapter + ProviderHealth + CompletionParams + CompletionEvent
   • ollama.adapter.ts — extract existing Ollama logic
3. Refactor ProviderService:
   • Accept IProviderAdapter[] (injected via DI token)
   • registerAll() / listModels() aggregates from all adapters
   • getAdapter(name) — lookup by name
   • healthCheckAll() — check all adapters
   • Keep Pi ModelRegistry wiring (required by AgentService)
4. Wire up in AgentModule

Key Findings

Pi SDK Compatibility

• Pi SDK uses ModelRegistry as central registry; ProviderService wraps it
• ModelRegistry.registerProvider() is the integration point — adapters call this
• Pi doesn't have a native "IProviderAdapter" concept — adapters are a Mosaic abstraction on top
• The createAgentSession() call in AgentService uses modelRegistry: this.providerService.getRegistry()
• OllamaAdapter should call registry.registerProvider('ollama', {...}) same as today
• CompletionParams/CompletionEvent: Pi SDK streams via AgentSession.prompt(), not raw completion — IProviderAdapter.createCompletion() is for future direct use; for now stub or leave as interface-only — ASSUMPTION: createCompletion is reserved for future M3+ work; Pi SDK owns the actual streaming

Implementation Notes

• ESM: use .js extensions in all imports
• NestJS: use @Inject() explicitly
• Keep RoutingService working — it only uses providerService.listAvailableModels()
• Keep AgentService working — it uses providerService.getRegistry(), findModel(), getDefaultModel(), listAvailableModels()

Progress

• Add types to @mosaicstack/types
• Create adapters/ directory
• Create IProviderAdapter interface file
• Create OllamaAdapter
• Refactor ProviderService
• Update AgentModule
• Run tests
• Run quality gates

Risks

• Pi SDK doesn't natively support IProviderAdapter — adapters are a layer on top
• createCompletion() is architecturally sound but requires Pi session bypass (future work)