Make note generation provider-configurable using OpenAI SDK-compatible endpoints

[sammargolis]

Background

Today, note generation is tied to one provider path. We want a minimal refactor so note generation can switch providers by configuration only, while keeping behavior unchanged.

This issue should use the OpenAI SDK as the single client layer and support alternate OpenAI-compatible endpoints through config (baseURL, apiKey, model).

Objective

Implement a small abstraction around note generation model calls so we can:

1. Keep current default behavior out of the box.
2. Switch to compatible providers (Anthropic/Gemini-compatible endpoints) using env vars only.
3. Avoid future refactors in note-generation business logic.

---

Scope

1. Add note-generation config:

• NOTE_MODEL_PROVIDER (string; default = current provider value)
• NOTE_MODEL_BASE_URL (optional)
• NOTE_MODEL_API_KEY (required unless existing default path already injects key)
• NOTE_MODEL_NAME (required)

2. Add a small wrapper client for note generation only:

• Example interface: generateNoteCompletion(input): Promise<NoteResult>
• Wrapper owns OpenAI SDK initialization and request execution.
• Note generation service calls wrapper, not provider SDK directly.

3. Preserve existing output behavior:

• Same note format/schema.
• Same prompt/template flow.
• Same error surface where feasible (or mapped equivalent).

4. Add docs snippet:

• Env var examples for default provider and one alternate OpenAI-compatible endpoint.
• One short “how to add a new compatible provider” note.

Out of Scope

• Native Anthropic/Google SDK integration.
• Provider-specific feature parity (tools, reasoning knobs, etc.).
• UI changes.
• Refactors outside note generation.

---

Implementation Guidance (simple path)

1. Introduce a config resolver in note-generation module:

• Resolve provider + model settings from env.
• Validate required env vars at startup (or first call with clear error).

2. Create NoteModelClient wrapper:

• Build OpenAI client with:
  • apiKey: NOTE_MODEL_API_KEY
  • baseURL: NOTE_MODEL_BASE_URL (if set)
• Execute existing note-generation request path (chat/completions path already used by app).

3. Wire existing note generation flow to wrapper:

• No prompt logic changes.
• No response-schema changes.

4. Add lightweight tests:

• Config defaults.
• Config override behavior.
• Wrapper called by note generation path.
• Error message when required env missing.

---

Detailed Success Criteria

1. Functional parity

• With no new env vars set (default config), generated notes match current behavior/shape.
• No regressions in note-generation output contract.

2. Config-driven switching

• Setting only NOTE_MODEL_PROVIDER, NOTE_MODEL_BASE_URL, NOTE_MODEL_API_KEY, and NOTE_MODEL_NAME is sufficient to route note generation to another OpenAI-compatible endpoint.
• No code change required to switch endpoints.

3. Isolation

• Provider-specific initialization logic exists only in the new wrapper/config layer.
• Note-generation orchestration code contains no direct provider SDK wiring.

4. Reliability and error handling

• Missing/invalid required env vars produce clear, actionable errors (e.g., which var is missing).
• Non-2xx provider responses are surfaced with stable internal error mapping.

5. Non-functional constraints

• No UI changes.
• No behavior changes outside note generation.
• Docs updated with at least 2 runnable config examples.

6. Verification checklist (Definition of Done)

• Unit tests pass for config + wrapper wiring.
• Existing note-generation tests pass unchanged (or with minimal fixture updates if needed).
• Manual smoke test confirms:
  • default config works
  • alternate baseURL path works

---

Suggested Test Cases

1. Default path:

• Env unset except existing defaults -> note generation succeeds.

2. Override path:

• Set all NOTE_MODEL_* vars with compatible endpoint -> note generation succeeds.

3. Missing key:

• Missing NOTE_MODEL_API_KEY when required -> clear config error.

4. Missing model:

• Missing NOTE_MODEL_NAME -> clear config error.

5. Invalid base URL:

• Bad NOTE_MODEL_BASE_URL -> deterministic connection/error message.

---

Docs Snippet (example)

# Default (current behavior)
NOTE_MODEL_PROVIDER=openai
NOTE_MODEL_API_KEY=...
NOTE_MODEL_NAME=gpt-4o-mini

# Alternate OpenAI-compatible endpoint
NOTE_MODEL_PROVIDER=anthropic-compatible
NOTE_MODEL_BASE_URL=https://api.anthropic.com/v1/
NOTE_MODEL_API_KEY=...
NOTE_MODEL_NAME=claude-sonnet-4-5

References

• Anthropic OpenAI SDK compatibility
• Anthropic API release notes
• Gemini OpenAI compatibility