Support provider and model configuration via environment variables

[vzegnameta]

Support provider and model configuration via environment variables

Summary

Allow PDF_ANALYZER_PROVIDER and PDF_ANALYZER_MODEL environment variables to override the keychain-stored provider and model selection. This enables configuring the server at deploy time (e.g., via Cloud Run env vars) without running --setup inside the container.

Motivation

The current resolveActiveProvider() function reads the active provider, API key, and model from the OS keychain. This works well for local usage after running --setup, but doesn't work for cloud deployments where:

• There is no interactive terminal to run --setup
• There is no OS keychain available in the container
• The provider/model should be configurable at deploy time without rebuilding the image
• Different environments (staging vs production) may use different models

Environment variables are the standard way to configure containerized services.

Proposed changes

1. Update src/providers/registry.ts

resolveActiveProvider() should check environment variables before falling back to the keychain:

export function resolveActiveProvider() {
  // Env vars take precedence (for cloud deployments)
  const envProvider = process.env.PDF_ANALYZER_PROVIDER;
  const envModel = process.env.PDF_ANALYZER_MODEL;

  if (envProvider) {
    const provider = providers[envProvider];
    if (!provider) {
      throw new Error(
        `Unknown provider "${envProvider}". Valid providers: ${Object.keys(providers).join(", ")}`,
      );
    }
    const modelId = envModel && provider.models.some((m) => m.id === envModel)
      ? envModel
      : provider.defaultModel;

    // Vertex AI providers don't need an API key (ADC handles auth).
    // Direct providers still need one — check PDF_ANALYZER_API_KEY env var.
    const apiKey = process.env.PDF_ANALYZER_API_KEY || "";

    return { provider, apiKey, modelId };
  }

  // Fall back to keychain (for local usage via --setup)
  // ... existing logic unchanged ...
}

2. Environment variables

Variable	Required	Description
PDF_ANALYZER_PROVIDER	No	Provider ID to use. Overrides keychain. Valid values: google, google-vertex, anthropic, anthropic-vertex, openai
PDF_ANALYZER_MODEL	No	Model ID to use. Overrides keychain. Must be a valid model for the selected provider
PDF_ANALYZER_API_KEY	No	API key for direct providers (google, anthropic, openai). Not needed for Vertex AI providers

3. Precedence order

1. Environment variables (PDF_ANALYZER_PROVIDER + PDF_ANALYZER_MODEL) — highest priority
2. Keychain (set via --setup) — fallback for local usage

4. Example: Cloud Run deployment

# Deploy with Gemini 3.1 Pro
env:
  PDF_ANALYZER_PROVIDER: "google-vertex"
  PDF_ANALYZER_MODEL: "gemini-3.1-pro-preview"
  VERTEX_PROJECT: "your-project-id"
  VERTEX_LOCATION: "your-region"

# Switch to Claude Opus 4.6 — just change env vars, no rebuild
env:
  PDF_ANALYZER_PROVIDER: "anthropic-vertex"
  PDF_ANALYZER_MODEL: "claude-opus-4-6"
  VERTEX_PROJECT: "your-project-id"
  VERTEX_LOCATION: "your-region"

Backward compatibility

• No breaking changes. Without env vars set, behavior is identical to today (keychain lookup).
• --setup continues to work for local usage.
• Env vars simply take precedence when present.

Related

• Required by: Google Vertex AI provider, Anthropic Vertex AI provider, Streamable HTTP transport
• Without this, cloud deployments would need to either bake credentials into the image or run --setup inside the container — neither is practical.

[valentinozegna]

Implemented in #34.

What was done:

• Extended src/providers/registry.ts to resolve provider and model from environment variables
• PDF_ANALYZER_PROVIDER selects the provider (google, openai, anthropic, google-vertex, anthropic-vertex)
• PDF_ANALYZER_MODEL overrides the default model for any provider
• VERTEX_PROJECT and VERTEX_LOCATION configure Vertex AI specifics
• Env vars take precedence over OS credential store settings
• Added unit tests in src/providers/registry.test.ts

What was not done:

• API key via env var (Vertex providers use ADC; direct providers still use the OS credential store for the API key)