# 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)