63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# 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.
|