Fix API key initialization crash preventing first-time users from accessing settings

[Copilot]

Problem

New users could not use CodebookAI because the application crashed on startup when no OpenAI API key was configured. The error message was:

Failed to execute script 'main' due to unhandled exception: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable

This created a catch-22 situation: users needed an API key to open the application, but they needed the application to be running to access the Settings menu where they could enter their API key.

Root Cause

The issue was in settings/models_registry.py where the OpenAI client was instantiated at module import time:

client = OpenAI(api_key=secrets_store.load_api_key())  # This would crash if no key exists

Since main.py imports from models_registry, the application would crash during startup before the GUI could even load.

Solution

This PR implements graceful API key handling with minimal changes:

1. Safe Client Initialization

Modified models_registry.py to handle missing API keys gracefully:

# Before: Would crash immediately
client = OpenAI(api_key=secrets_store.load_api_key())

# After: Gracefully handles missing keys
try:
    api_key = secrets_store.load_api_key()
    client = OpenAI(api_key=api_key) if api_key else None
except Exception:
    client = None

2. User-Friendly Error Messages

Updated batch_method.py to provide clear guidance instead of crashing:

def get_client() -> OpenAI:
    api_key = secrets_store.load_api_key()
    if not api_key:
        raise Exception("OpenAI API key not configured. Please set it in Settings.")
    return OpenAI(api_key=api_key)

3. Client Refresh Mechanism

Added refresh_client() function and integrated it into the settings workflow so the client is properly reinitialized when users save their API key.

User Experience

Before this fix:

• Launch app → ❌ Crashes with OpenAI error
• Users cannot access Settings menu
• New users are completely blocked

After this fix:

• Launch app → ✅ Starts successfully
• File → Settings → ✅ Settings menu accessible
• Enter API key → ✅ Saves and refreshes client
• Use AI features → ✅ Full functionality available

Impact

• 3 files changed: models_registry.py, batch_method.py, settings_window.py
• 29 insertions, 3 deletions: Minimal surgical changes
• No breaking changes: Existing functionality preserved
• Security verified: CodeQL analysis shows no vulnerabilities

This fix resolves the primary blocker preventing new users from adopting CodebookAI while maintaining backward compatibility for existing users.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/tmaier-kettering/tmaier-kettering%2FCodebookAI/languages
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Currently new users cannot use the software because the api_key must be set but users obviously can't do that if they can't open the software to write their api key into the settings menu.
The full error message currently popping up is:
"Failed to execute script 'main' due to unhandled exception: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable

Fix this issue so first time users can open the software, navigate to the settings, and enter their key into the settings.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.