mirror of https://github.com/lfnovo/open-notebook.git synced 2026-05-03 05:40:36 +00:00

feat: credential-based API key management (#477 ) (#540 )

* feat: replace provider config with credential-based system (#477)

Introduce a new credential management system replacing the old
ProviderConfig singleton and standalone Models page. Each credential
stores encrypted API keys and provider-specific configuration with
full CRUD support via a unified settings UI.

Backend:
- Add Credential domain model with encrypted API key storage
- Add credentials API router (CRUD, discovery, registration, testing)
- Add encryption utilities for secure key storage
- Add key_provider for DB-first env-var fallback provisioning
- Add connection tester and model discovery services
- Integrate ModelManager with credential-based config
- Add provider name normalization for Esperanto compatibility
- Add database migrations 11-12 for credential schema

Frontend:
- Rewrite settings/api-keys page with credential management UI
- Add model discovery dialog with search and custom model support
- Add compact default model assignments (primary/advanced layout)
- Add inline model testing and credential connection testing
- Add env-var migration banner
- Update navigation to unified settings page
- Remove standalone models page and old settings components

i18n:
- Update all 7 locale files with credential and model management keys

Closes #477

Co-Authored-By: JFMD <git@jfmd.us>
Co-Authored-By: OraCatQAQ <570768706@qq.com>

* fix: address PR #540 review comments

- Fix docs referencing removed Models page
- Fix error-handler returning raw messages instead of i18n keys
- Fix auth.py misleading docstring and missing no-password guard
- Fix connection_tester using wrong env var for openai_compatible
- Add provision_provider_keys before model discovery/sync
- Update CLAUDE.md to reflect credential-based system
- Fix missing closing brace in api-keys page useEffect

* fix: add logging to credential migration and surface errors in UI

- Add comprehensive logging to migrate-from-env and
  migrate-from-provider-config endpoints (start, per-provider
  progress, success/failure with stack traces, final summary)
- Fix frontend migration hooks ignoring errors array from response
- Show error toast when migration fails instead of "nothing to migrate"
- Invalidate status/envStatus queries after migration so banner updates

* docs: update CLAUDE.md files for credential system

Replace stale ProviderConfig and /api-keys/ references across 8 CLAUDE.md
files to reflect the new Credential-based system from PR #540.

* docs: update user documentation for credential-based system

Replace env var API key instructions with Settings UI credential
workflow across all user-facing documentation. The new flow is:
set OPEN_NOTEBOOK_ENCRYPTION_KEY → start services → add credential
in Settings UI → test → discover models → register.

- Rewrite ai-providers.md, api-configuration.md, environment-reference.md
- Update all quick-start guides and installation docs
- Update ollama.md, openai-compatible.md, local-tts/stt networking sections
- Update reverse-proxy.md, development-setup.md, security.md
- Fix broken links to non-existent docs/deployment/ paths
- Add credentials endpoints to api-reference.md
- Move all API key env vars to deprecated/legacy sections

* chore: bump version to 1.7.0-rc1

Release candidate for credential-based provider management system.

* fix: initialize provider before try block in test_credential

Prevents UnboundLocalError when Credential.get() throws (e.g.,
invalid credential_id) before provider is assigned.

* fix: reorder down migration to drop index before table

Removes duplicate REMOVE FIELD statement and reorders so the index
is dropped before the table, preventing rollback failures.

* refactor: simplify encryption key to always derive via SHA-256

Remove the dual code path in _ensure_fernet_key() that detected native
Fernet keys. Since the credential system is new, always deriving via
SHA-256 removes unnecessary complexity. Also removes the generate_key()
function and Fernet.generate_key() references from docs.

* fix: correct mock patch targets in embedding tests and URL validation

Fix embedding tests patching wrong module path for model_manager
(was targeting open_notebook.utils.embedding.model_manager but it's
imported locally from open_notebook.ai.models). Also fix URL validation
to allow unresolvable hostnames since they may be valid in the
deployment environment (e.g., Azure endpoints, internal DNS).

* feat: add global setup banner for encryption and migration status

Show a persistent banner in AppShell when encryption key is missing
(red) or env var API keys can be migrated (amber), so users see
these prompts on every page instead of only on Settings > API Keys.

Includes a docs link for the encryption banner and i18n support
across all 7 locales.

* docs: several improvements to docker-compose e env examples

* Update README.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* docs: fix env var format in README and update model setup instructions

Align the encryption key snippet in README Step 2 with the list
format used in the compose file. Replace deprecated "Settings →
Models" instructions with credential-based Discover Models flow.

* fix: address credential system review issues

- Fix SSRF bypass via IPv4-mapped IPv6 addresses (::ffff:169.254.x.x)
- Fix TTS connection test missing config parameter
- Add Azure-specific model discovery using api-key auth header
- Add Vertex static model list for credential-based discovery
- Fix PROVIDER_DISCOVERY_FUNCTIONS incorrect azure/vertex mapping
- Extract business logic to api/credentials_service.py (service layer)
- Move credential Pydantic schemas to api/models.py
- Update tests to use new service imports and ValueError assertions

* fix: sanitize error responses and migrate key_provider to Credential

- Replace raw exception messages in all credential router 500 responses
  with generic error strings (internal details logged server-side only)
- Refactor key_provider.py to use Credential.get_by_provider() instead
  of deprecated ProviderConfig.get_instance()
- Remove unused functions (get_provider_configs, get_default_api_key,
  get_provider_config) that were dead code

---------

Co-authored-by: JFMD <git@jfmd.us>
Co-authored-by: OraCatQAQ <570768706@qq.com>

2026-02-10 08:30:22 -03:00

5.6 KiB

Raw Blame History

AI Providers - Comparison & Selection Guide

Open Notebook supports 15+ AI providers. This guide helps you choose the right provider for your needs.

💡 Just want to set up a provider? Skip to the Configuration Guide for detailed setup instructions.

Quick Decision: Which Provider?

Cloud Providers (Easiest)

OpenAI (Recommended)

Cost: ~$0.03-0.15 per 1K tokens
Speed: Very fast
Quality: Excellent
Best for: Most users (best quality/price balance)

→ Setup Guide

Anthropic (Claude)

Cost: ~$0.80-3.00 per 1M tokens
Speed: Fast
Quality: Excellent
Best for: Long context (200K tokens), reasoning, latest AI
Advantage: Superior long-context handling

→ Setup Guide

Google Gemini

Cost: ~$0.075-0.30 per 1K tokens
Speed: Very fast
Quality: Good to excellent
Best for: Multimodal (images, audio, video)
Advantage: Longest context (up to 2M tokens)

→ Setup Guide

Groq (Ultra-Fast)

Cost: ~$0.05 per 1M tokens (cheapest)
Speed: Ultra-fast (fastest available)
Quality: Good
Best for: Budget-conscious, transformations, speed-critical tasks
Disadvantage: Limited model selection

→ Setup Guide

OpenRouter (100+ Models)

Cost: Pay-per-model (varies widely)
Speed: Varies by model
Quality: Varies by model
Best for: Model comparison, testing, unified billing
Advantage: One API key for 100+ models from different providers

→ Setup Guide

Local / Self-Hosted (Free)

Ollama (Recommended for Local)

Cost: Free (electricity only)
Speed: Depends on hardware (slow on CPU, fast on GPU)
Quality: Good (open-source models)
Setup: 10 minutes
Best for: Privacy-first, offline use
Privacy: 100% local, nothing leaves your machine

→ Setup Guide

LM Studio (Alternative)

Cost: Free (electricity only)
Speed: Depends on hardware
Quality: Good (same models as Ollama)
Setup: 15 minutes (GUI interface)
Best for: Non-technical users who prefer GUI over CLI
Privacy: 100% local

→ Setup Guide

Enterprise

Azure OpenAI

Cost: Same as OpenAI (usage-based)
Speed: Very fast
Quality: Excellent (same models as OpenAI)
Setup: 10 minutes (more complex)
Best for: Enterprise, compliance (HIPAA, SOC2), VPC integration

→ Setup Guide

Comparison Table

Provider	Speed	Cost	Quality	Privacy	Setup	Context
OpenAI	Very Fast		Excellent	Low	5 min	128K
Anthropic	Fast		Excellent	Low	5 min	200K
Google	Very Fast		Good-Excellent	Low	5 min	2M
Groq	Ultra Fast	$	Good	Low	5 min	32K
OpenRouter	Varies	Varies	Varies	Low	5 min	Varies
Ollama	Slow-Medium	Free	Good	Max	10 min	Varies
LM Studio	Slow-Medium	Free	Good	Max	15 min	Varies
Azure	Very Fast		Excellent	High	10 min	128K

Choosing Your Provider

I want the easiest setup

→ OpenAI — Most popular, best community support

I have unlimited budget

→ OpenAI — Best quality

I want to save money

→ Groq — Cheapest cloud ($0.05 per 1M tokens)

I want privacy/offline

→ Ollama — Free, local, private

I want a GUI (not CLI)

→ LM Studio — Desktop app

I'm in an enterprise

→ Azure OpenAI — Compliance, support

I need long context (200K+ tokens)

→ Anthropic — Best long-context model

I need multimodal (images, audio, video)

→ Google Gemini — Best multimodal support

I want access to many models with one API key

→ OpenRouter — 100+ models, unified billing

Ready to Set Up Your Provider?

Now that you've chosen a provider, follow the detailed setup instructions:

→ AI Providers Configuration Guide

This guide includes:

Step-by-step setup instructions for each provider via the Settings UI
How to add credentials, test connections, and discover models
Model selection and recommendations
Provider-specific troubleshooting
Hardware requirements (for local providers)
Cost optimization tips

Cost Estimator

OpenAI

Light use (10 chats/day): $1-5/month
Medium use (50 chats/day): $10-30/month
Heavy use (all-day use): $50-100+/month

Anthropic

Light use: $1-3/month
Medium use: $5-20/month
Heavy use: $20-50+/month

Groq

Light use: $0-1/month
Medium use: $2-5/month
Heavy use: $5-20/month

Ollama

Any use: Free (electricity only)
8GB GPU running 24/7: ~$10/month electricity

Next Steps

You've chosen a provider (from this comparison guide)
Follow the setup guide: AI Providers Configuration
Add your credential in Settings → API Keys
Test your connection and discover models
Start using Open Notebook!

Need Help?

Setup issues? See AI Providers Configuration for detailed troubleshooting per provider
General problems? Check Troubleshooting Guide
Questions? Join Discord community

5.6 KiB Raw Blame History

AI Providers - Comparison & Selection Guide

Quick Decision: Which Provider?

Cloud Providers (Easiest)

Local / Self-Hosted (Free)

Enterprise

Comparison Table

Choosing Your Provider

I want the easiest setup

I have unlimited budget

I want to save money

I want privacy/offline

I want a GUI (not CLI)

I'm in an enterprise

I need long context (200K+ tokens)

I need multimodal (images, audio, video)

I want access to many models with one API key

Ready to Set Up Your Provider?

Cost Estimator

OpenAI

Anthropic

Groq

Ollama

Next Steps

Need Help?

5.6 KiB

Raw Blame History