diff options
Diffstat (limited to 'PLAN-OPENROUTER.md')
| -rw-r--r-- | PLAN-OPENROUTER.md | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/PLAN-OPENROUTER.md b/PLAN-OPENROUTER.md new file mode 100644 index 0000000..5534b29 --- /dev/null +++ b/PLAN-OPENROUTER.md @@ -0,0 +1,85 @@ +# Plan to Implement OpenRouter.ai Support + +This document outlines the steps to integrate OpenRouter.ai as a new LLM provider within Hexai. The implementation will follow the existing provider pattern, using `internal/llm/openai.go` as a template due to API similarities. + +## 1. Update Configuration (`internal/appconfig/config.go`) + +Status: Completed - configuration structs, env overrides, and sample config updated. + +The application needs to be aware of the new provider and its specific configuration settings. + +- **Add OpenRouter section to `fileConfig`:** + - Create a new `sectionOpenRouter` struct in `internal/appconfig/config.go` to handle settings from `config.toml`. + - It will contain `Model`, `BaseURL`, and `Temperature` fields. + - Add `OpenRouter sectionOpenRouter` to the `fileConfig` struct. + +- **Add fields to `App` struct:** + - Add `OpenRouterBaseURL`, `OpenRouterModel`, and `OpenRouterTemperature` to the main `App` struct. + +- **Update `loadFromEnv`:** + - Modify the `loadFromEnv` function in `internal/appconfig/config.go` to read `HEXAI_OPENROUTER_MODEL`, `HEXAI_OPENROUTER_BASE_URL`, and `HEXAI_OPENROUTER_TEMPERATURE` from environment variables. + +- **Update `toApp()` and `mergeProviderFields`:** + - Add logic to `fileConfig.toApp()` to convert the `sectionOpenRouter` into the `App` struct. + - Add logic to `App.mergeProviderFields()` to merge the OpenRouter configuration from different sources. + +- **Update `config.toml.example`:** + - Add a new `[openrouter]` section to the `config.toml.example` file to demonstrate configuration for users. + +## 2. Create OpenRouter Provider (`internal/llm/openrouter.go`) + +Status: Completed - provider implemented with required headers and logging. + +This will be the core implementation of the OpenRouter client. + +- **Create new file `internal/llm/openrouter.go`:** + - This file will be a copy of `internal/llm/openai.go` initially, and then modified for OpenRouter. + +- **Define `openRouterProvider` struct:** + - It will implement the `llm.Client` and `llm.Streamer` interfaces. + - It will hold the `httpClient`, `apiKey`, `baseURL`, `defaultModel`, etc. + +- **Implement `Chat` and `ChatStream` methods:** + - The request logic will be adapted from the OpenAI implementation. + - The base URL will default to `https://openrouter.ai/api/v1` if not provided in the config. + - **Add the required OpenRouter headers to every request:** + - `Authorization: Bearer $OPENROUTER_API_KEY` + - `HTTP-Referer: "https://github.com/snonux/hexai"` (or another suitable value) + - `X-Title: "Hexai"` + +- **Model Handling:** + - The `model` from the `Options` will be passed directly in the JSON request body, allowing users to leverage any model available on OpenRouter. + - Default model now uses `openrouter/auto` so requests succeed without additional configuration. + +## 3. Integrate into Provider Factory (`internal/llm/provider.go`) + +Status: Completed - provider factory wiring and API key plumbing added. + +The application needs to be able to select and instantiate the new provider. + +- **Update `Config` struct:** + - Add `OpenRouterBaseURL`, `OpenRouterModel`, and `OpenRouterTemperature` fields to the `llm.Config` struct. + +- **Update `NewFromConfig` function:** + - Add a new `case "openrouter":` to the `switch` statement. + - This case will be responsible for: + 1. Accepting an `openRouterAPIKey` string, which will be read from the `OPENROUTER_API_KEY` environment variable by the caller. + 2. Returning an error if the key is missing. + 3. Instantiating the new `openRouterProvider` with the correct configuration (API key, model, base URL, temperature). + +## 4. Add Tests (`internal/llm/openrouter_test.go`) + +Status: Completed - streaming and header unit tests added. + +- **Create `internal/llm/openrouter_test.go`:** + - Add unit tests for the `openRouterProvider`. + - Use an HTTP mock (similar to `openai_http_test.go`) to test the `Chat` and `ChatStream` implementations without making real API calls. + - Verify that the correct headers (`Authorization`, `HTTP-Referer`, `X-Title`) are being sent in the mock requests. + - Verify that the request body is correctly formatted. + +## 5. Update Documentation + +Status: Completed - README and configuration docs now mention OpenRouter setup. + +- Update `docs/configuration.md` and `README.md` to include instructions on how to configure and use the OpenRouter.ai provider. +- Explicitly mention the `OPENROUTER_API_KEY` environment variable and the new settings available in `config.toml`. |