|
| 1 | +""" |
| 2 | +Consolidated Fireworks client factory. |
| 3 | +
|
| 4 | +This module provides a single point of instantiation for the Fireworks SDK client, |
| 5 | +ensuring consistent handling of environment variables and configuration across the |
| 6 | +eval_protocol codebase. |
| 7 | +
|
| 8 | +Environment variables: |
| 9 | + FIREWORKS_API_KEY: API key for authentication (required) |
| 10 | + FIREWORKS_ACCOUNT_ID: Account ID (optional, can be derived from API key) |
| 11 | + FIREWORKS_API_BASE: Base URL for the API (default: https://api.fireworks.ai) |
| 12 | + FIREWORKS_EXTRA_HEADERS: JSON-encoded extra headers to include in requests |
| 13 | + Example: '{"X-Custom-Header": "value", "X-Another": "another-value"}' |
| 14 | +""" |
| 15 | + |
| 16 | +import json |
| 17 | +import logging |
| 18 | +import os |
| 19 | +from typing import Mapping, Optional |
| 20 | + |
| 21 | +from fireworks import Fireworks |
| 22 | + |
| 23 | +from eval_protocol.auth import ( |
| 24 | + get_fireworks_account_id, |
| 25 | + get_fireworks_api_base, |
| 26 | + get_fireworks_api_key, |
| 27 | +) |
| 28 | + |
| 29 | +logger = logging.getLogger(__name__) |
| 30 | + |
| 31 | + |
| 32 | +def get_fireworks_extra_headers() -> Optional[Mapping[str, str]]: |
| 33 | + """ |
| 34 | + Retrieves extra headers from the FIREWORKS_EXTRA_HEADERS environment variable. |
| 35 | +
|
| 36 | + The value should be a JSON-encoded object mapping header names to values. |
| 37 | + Example: '{"X-Custom-Header": "value"}' |
| 38 | +
|
| 39 | + Returns: |
| 40 | + A mapping of header names to values if set and valid, otherwise None. |
| 41 | + """ |
| 42 | + extra_headers_str = os.environ.get("FIREWORKS_EXTRA_HEADERS") |
| 43 | + if not extra_headers_str or not extra_headers_str.strip(): |
| 44 | + return None |
| 45 | + |
| 46 | + try: |
| 47 | + headers = json.loads(extra_headers_str) |
| 48 | + if not isinstance(headers, dict): |
| 49 | + logger.warning( |
| 50 | + "FIREWORKS_EXTRA_HEADERS must be a JSON object, got %s. Ignoring.", |
| 51 | + type(headers).__name__, |
| 52 | + ) |
| 53 | + return None |
| 54 | + # Validate all keys and values are strings |
| 55 | + for k, v in headers.items(): |
| 56 | + if not isinstance(k, str) or not isinstance(v, str): |
| 57 | + logger.warning( |
| 58 | + "FIREWORKS_EXTRA_HEADERS contains non-string key or value: %s=%s. Ignoring all extra headers.", |
| 59 | + k, |
| 60 | + v, |
| 61 | + ) |
| 62 | + return None |
| 63 | + logger.debug("Using FIREWORKS_EXTRA_HEADERS: %s", list(headers.keys())) |
| 64 | + return headers |
| 65 | + except json.JSONDecodeError as e: |
| 66 | + logger.warning("Failed to parse FIREWORKS_EXTRA_HEADERS as JSON: %s. Ignoring.", e) |
| 67 | + return None |
| 68 | + |
| 69 | + |
| 70 | +def create_fireworks_client( |
| 71 | + *, |
| 72 | + api_key: Optional[str] = None, |
| 73 | + account_id: Optional[str] = None, |
| 74 | + base_url: Optional[str] = None, |
| 75 | + extra_headers: Optional[Mapping[str, str]] = None, |
| 76 | +) -> Fireworks: |
| 77 | + """ |
| 78 | + Create a Fireworks client with consistent configuration. |
| 79 | +
|
| 80 | + This factory function centralizes the logic for creating Fireworks clients, |
| 81 | + ensuring that environment variables are handled consistently across the codebase. |
| 82 | +
|
| 83 | + Resolution order for each parameter: |
| 84 | + 1. Explicit argument passed to this function |
| 85 | + 2. Environment variable (via auth module helpers) |
| 86 | + 3. SDK defaults (for base_url only) |
| 87 | +
|
| 88 | + Args: |
| 89 | + api_key: Fireworks API key. If not provided, resolves from FIREWORKS_API_KEY. |
| 90 | + account_id: Fireworks account ID. If not provided, resolves from FIREWORKS_ACCOUNT_ID |
| 91 | + or derives from the API key via the verifyApiKey endpoint. |
| 92 | + base_url: Base URL for the Fireworks API. If not provided, resolves from |
| 93 | + FIREWORKS_API_BASE or defaults to https://api.fireworks.ai. |
| 94 | + extra_headers: Additional headers to include in all requests. If not provided, |
| 95 | + resolves from FIREWORKS_EXTRA_HEADERS environment variable (JSON-encoded). |
| 96 | +
|
| 97 | + Returns: |
| 98 | + A configured Fireworks client instance. |
| 99 | +
|
| 100 | + Raises: |
| 101 | + fireworks.FireworksError: If api_key is not provided and FIREWORKS_API_KEY |
| 102 | + environment variable is not set. |
| 103 | + """ |
| 104 | + # Resolve parameters from environment if not explicitly provided |
| 105 | + resolved_api_key = api_key or get_fireworks_api_key() |
| 106 | + resolved_account_id = account_id or get_fireworks_account_id() |
| 107 | + resolved_base_url = base_url or get_fireworks_api_base() |
| 108 | + |
| 109 | + # Merge extra headers: env var headers first, then explicit headers override |
| 110 | + env_extra_headers = get_fireworks_extra_headers() |
| 111 | + merged_headers: Optional[Mapping[str, str]] = None |
| 112 | + if env_extra_headers or extra_headers: |
| 113 | + merged = {} |
| 114 | + if env_extra_headers: |
| 115 | + merged.update(env_extra_headers) |
| 116 | + if extra_headers: |
| 117 | + merged.update(extra_headers) |
| 118 | + merged_headers = merged if merged else None |
| 119 | + |
| 120 | + logger.debug( |
| 121 | + "Creating Fireworks client: base_url=%s, account_id=%s, extra_headers=%s", |
| 122 | + resolved_base_url, |
| 123 | + resolved_account_id, |
| 124 | + list(merged_headers.keys()) if merged_headers else None, |
| 125 | + ) |
| 126 | + |
| 127 | + return Fireworks( |
| 128 | + api_key=resolved_api_key, |
| 129 | + account_id=resolved_account_id, |
| 130 | + base_url=resolved_base_url, |
| 131 | + default_headers=merged_headers, |
| 132 | + ) |
0 commit comments