# Adding a Provider to Owlen

This guide complements `docs/provider-implementation.md` with a practical checklist for wiring a new model backend into the Phase 10 architecture.

## 1. Define the Provider Type

Providers live in their own crate (for example `owlen-providers`). Create a module that implements the `owlen_core::provider::ModelProvider` trait:

```rust
pub struct MyProvider {
    client: MyHttpClient,
    metadata: ProviderMetadata,
}

#[async_trait]
impl ModelProvider for MyProvider {
    fn metadata(&self) -> &ProviderMetadata { &self.metadata }
    async fn health_check(&self) -> Result<ProviderStatus> { ... }
    async fn list_models(&self) -> Result<Vec<ModelInfo>> { ... }
    async fn generate_stream(&self, request: GenerateRequest) -> Result<GenerateStream> { ... }
}
```

Set `ProviderMetadata::provider_type` to `ProviderType::Local` or `ProviderType::Cloud` so the TUI can label it correctly.

## 2. Register with `ProviderManager`

`ProviderManager` owns provider instances and tracks their health. In your startup code (usually `owlen-cli` or an MCP server), construct the provider and register it:

```rust
let manager = ProviderManager::new(config);
manager.register_provider(Arc::new(MyProvider::new(config)?.into())).await;
```

The manager caches `ProviderStatus` values so the TUI can surface availability in the picker and background worker events.

## 3. Expose Through MCP (Optional)

For providers that should run out-of-process, implement an MCP server (`owlen-mcp-llm-server` demonstrates the pattern). The TUI uses `RemoteMcpClient`, so exposing `generate_text` keeps the UI completely decoupled from provider details.

## 4. Add Tests

Commit 13 introduced integration tests in `crates/owlen-providers/tests`. Follow this pattern to exercise:

- registration with `ProviderManager`
- model aggregation across providers
- routing of `generate` requests
- provider status transitions when generation succeeds or fails

In-memory mocks are enough; the goal is to protect the trait contract and the manager’s health cache.

## 5. Document Configuration

Update `docs/configuration.md` and the default `config.toml` snippet so users can enable the new provider. Include environment variables, auth requirements, or special flags.

## 6. Update User-Facing Docs

- Add a short entry to the feature list in `README.md`.
- Mention the new provider in `CHANGELOG.md` under the “Added” section.
- If the provider requires troubleshooting steps, append them to `docs/troubleshooting.md`.

Following these steps keeps the provider lifecycle consistent with Owlen’s multi-provider architecture: providers register once, the manager handles orchestration, and the TUI reacts via message-driven updates.