Add OpenRouter as a first-class LLM provider #147

Problem

OpenRouter can currently be configured only through the generic openai_compatible_api provider slot. That workaround prevents users from keeping the bundled or another OpenAI-compatible runtime configured alongside OpenRouter, and it does not expose OpenRouter-specific defaults or guidance.

OpenRouter exposes an OpenAI-compatible API at https://openrouter.ai/api/v1, provides model discovery, and supports structured outputs for compatible models. It should be a dedicated provider anywhere ParseHawk exposes provider selection or configuration.

Proposed scope

• Add a stable openrouter provider name to the backend domain and public API schema.
• Seed the provider with https://openrouter.ai/api/v1 while preserving operator-configured values across restarts.
• Reuse ParseHawk's OpenAI-compatible chat-completions engine and encrypted provider-secret storage.
• Support configuration through the REST API, CLI, and Web UI, including OPENROUTER_API_KEY via --api-key-env.
• List OpenRouter model IDs through the provider models endpoint and surface them in the extractor model picker.
• Send OpenRouter's optional attribution headers with ParseHawk-owned values where appropriate:
  • HTTP-Referer
  • X-OpenRouter-Title
• Ensure extraction requests require routing to an upstream endpoint that supports the parameters ParseHawk sends, especially response_format with json_schema (for example through OpenRouter's provider.require_parameters preference).
• Document that selected models must support structured outputs and the input modalities used by the extractor.
• Add a dedicated OpenRouter how-to and include it in the provider overview, README, CLI reference, and generated OpenAPI/reference artifacts.

Acceptance criteria

• openrouter is returned by GET /v1/providers and accepted anywhere a ProviderName is used.
• A fresh installation seeds the OpenRouter base URL without requiring manual entry.
• Users can store, rotate, and clear an OpenRouter API key without read endpoints returning the secret.
• parsehawk providers models openrouter and the Web UI load model IDs from OpenRouter.
• An extractor can select openrouter plus an OpenRouter model ID and complete a schema-valid text extraction.
• Image or PDF extraction is covered by a test or documented manual verification with a compatible multimodal model.
• Existing OpenAI, Microsoft Foundry, and generic OpenAI-compatible provider behavior remains unchanged.
• Backend, CLI, Web UI, persistence/seed behavior, and generated contract tests cover the new provider.
• just openapi-export, just references-export, and just docs-check pass.

References

• OpenRouter quickstart
• OpenRouter structured outputs
• OpenRouter models API

Non-goals

• OpenRouter account, billing, or credit management
• A ParseHawk UI for OpenRouter's full provider-routing configuration
• Automatic fallback between ParseHawk provider slots