app.ai_providers

153class AIProvider(ABC):
154    """Abstract base class defining the interface for all AI providers.
155
156    Every concrete provider (Claude, OpenAI, Kimi, Local) implements this
157    interface so that the forensic analysis engine can call any provider
158    interchangeably.
159
160    Subclasses must implement:
161        * ``analyze`` -- single-shot prompt-to-text generation.
162        * ``analyze_stream`` -- incremental (streaming) text generation.
163        * ``get_model_info`` -- provider/model metadata dictionary.
164
165    Subclasses may override:
166        * ``analyze_with_attachments`` -- analysis with CSV file attachments.
167
168    Attributes:
169        attach_csv_as_file (bool): Whether to attempt uploading CSV artifacts
170            as file attachments rather than inlining them into the prompt.
171    """
172
173    @abstractmethod
174    def analyze(
175        self,
176        system_prompt: str,
177        user_prompt: str,
178        max_tokens: int = DEFAULT_MAX_TOKENS,
179    ) -> str:
180        """Send a prompt to the provider and return the complete generated text.
181
182        Args:
183            system_prompt: The system-level instruction text.
184            user_prompt: The user-facing prompt with investigation context.
185            max_tokens: Maximum number of tokens the model may generate.
186
187        Returns:
188            The generated text response as a string.
189
190        Raises:
191            AIProviderError: If the request fails for any reason.
192        """
193
194    @abstractmethod
195    def analyze_stream(
196        self,
197        system_prompt: str,
198        user_prompt: str,
199        max_tokens: int = DEFAULT_MAX_TOKENS,
200    ) -> Iterator[str]:
201        """Stream generated text chunks for the provided prompt.
202
203        Args:
204            system_prompt: The system-level instruction text.
205            user_prompt: The user-facing prompt with investigation context.
206            max_tokens: Maximum number of tokens the model may generate.
207
208        Yields:
209            Individual text chunks (deltas) as they are generated.
210
211        Raises:
212            AIProviderError: If the streaming request fails or produces no output.
213        """
214
215    @abstractmethod
216    def get_model_info(self) -> dict[str, str]:
217        """Return provider and model metadata for audit logging and reports.
218
219        Returns:
220            A dictionary with at least ``"provider"`` and ``"model"`` keys.
221        """
222
223    def analyze_with_attachments(
224        self,
225        system_prompt: str,
226        user_prompt: str,
227        attachments: list[Mapping[str, str]] | None,
228        max_tokens: int = DEFAULT_MAX_TOKENS,
229    ) -> str:
230        """Analyze with optional file attachments.
231
232        Providers that support file uploads override this method. The default
233        implementation inlines attachment content into the prompt so the model
234        always receives the evidence data, then delegates to ``analyze``.
235
236        Args:
237            system_prompt: The system-level instruction text.
238            user_prompt: The user-facing prompt with investigation context.
239            attachments: Optional list of attachment descriptors with
240                ``"path"``, ``"name"``, and ``"mime_type"`` keys.
241            max_tokens: Maximum number of tokens the model may generate.
242
243        Returns:
244            The generated text response as a string.
245
246        Raises:
247            AIProviderError: If the request fails.
248        """
249        from .utils import _inline_attachment_data_into_prompt
250
251        effective_prompt = user_prompt
252        if attachments:
253            effective_prompt, inlined = _inline_attachment_data_into_prompt(
254                user_prompt=user_prompt,
255                attachments=attachments,
256            )
257            if inlined:
258                logger.info("Base provider inlined attachment data into prompt.")
259
260        return self.analyze(
261            system_prompt=system_prompt,
262            user_prompt=effective_prompt,
263            max_tokens=max_tokens,
264        )
265
266    def _prepare_csv_attachments(
267        self,
268        attachments: list[Mapping[str, str]] | None,
269        *,
270        supports_file_attachments: bool = True,
271    ) -> list[dict[str, str]] | None:
272        """Apply shared CSV-attachment preflight checks and normalization.
273
274        Args:
275            attachments: Raw attachment descriptors from the caller.
276            supports_file_attachments: Whether the provider's SDK client
277                exposes the necessary file-upload APIs.
278
279        Returns:
280            A list of normalized attachment dicts, or ``None`` if attachment
281            mode should be skipped.
282        """
283        from .utils import normalize_attachment_inputs
284
285        if not bool(getattr(self, "attach_csv_as_file", False)):
286            return None
287        if not attachments:
288            return None
289        if getattr(self, "_csv_attachment_supported", None) is False:
290            return None
291        if not supports_file_attachments:
292            if hasattr(self, "_csv_attachment_supported"):
293                setattr(self, "_csv_attachment_supported", False)
294            return None
295
296        normalized_attachments = normalize_attachment_inputs(attachments)
297        if not normalized_attachments:
298            return None
299        return normalized_attachments

139class AIProviderError(RuntimeError):
140    """Raised when an AI provider request fails with a user-facing message.
141
142    All provider implementations translate SDK-specific exceptions into this
143    single exception type so that callers only need one ``except`` clause for
144    AI-related failures. The message is safe for display in the web UI.
145    """

 44class ClaudeProvider(AIProvider):
 45    """Anthropic Claude provider implementation.
 46
 47    Supports both synchronous and streaming generation, CSV file attachments
 48    via content blocks (base64-encoded PDFs or inline text), and automatic
 49    token-limit retry when ``max_tokens`` exceeds the model's maximum.
 50
 51    Attributes:
 52        api_key (str): The Anthropic API key.
 53        model (str): The Claude model identifier.
 54        attach_csv_as_file (bool): Whether to upload CSV artifacts as
 55            content blocks.
 56        request_timeout_seconds (float): HTTP timeout in seconds.
 57        client: The ``anthropic.Anthropic`` SDK client instance.
 58    """
 59
 60    def __init__(
 61        self,
 62        api_key: str,
 63        model: str = DEFAULT_CLAUDE_MODEL,
 64        attach_csv_as_file: bool = True,
 65        request_timeout_seconds: float = DEFAULT_CLOUD_REQUEST_TIMEOUT_SECONDS,
 66    ) -> None:
 67        """Initialize the Claude provider.
 68
 69        Args:
 70            api_key: Anthropic API key. Must be non-empty.
 71            model: Claude model identifier.
 72            attach_csv_as_file: If ``True``, send CSV artifacts as structured
 73                content blocks.
 74            request_timeout_seconds: HTTP timeout in seconds.
 75
 76        Raises:
 77            AIProviderError: If the ``anthropic`` SDK is not installed or
 78                the API key is empty.
 79        """
 80        try:
 81            import anthropic
 82        except ImportError as error:
 83            raise AIProviderError(
 84                "anthropic SDK is not installed. Install it with `pip install anthropic`."
 85            ) from error
 86
 87        normalized_api_key = _normalize_api_key_value(api_key)
 88        if not normalized_api_key:
 89            raise AIProviderError(
 90                "Claude API key is not configured. "
 91                "Set `ai.claude.api_key` in config.yaml or the ANTHROPIC_API_KEY environment variable."
 92            )
 93
 94        self._anthropic = anthropic
 95        self.api_key = normalized_api_key
 96        self.model = model
 97        self.attach_csv_as_file = bool(attach_csv_as_file)
 98        self._csv_attachment_supported: bool | None = None
 99        self.request_timeout_seconds = _resolve_timeout_seconds(
100            request_timeout_seconds,
101            DEFAULT_CLOUD_REQUEST_TIMEOUT_SECONDS,
102        )
103        self.client = anthropic.Anthropic(
104            api_key=normalized_api_key,
105            timeout=self.request_timeout_seconds,
106        )
107        logger.info("Initialized Claude provider with model %s (timeout %.1fs)", model, self.request_timeout_seconds)
108
109    def analyze(
110        self,
111        system_prompt: str,
112        user_prompt: str,
113        max_tokens: int = DEFAULT_MAX_TOKENS,
114    ) -> str:
115        """Send a prompt to Claude and return the generated text.
116
117        Args:
118            system_prompt: The system-level instruction text.
119            user_prompt: The user-facing prompt with investigation context.
120            max_tokens: Maximum completion tokens.
121
122        Returns:
123            The generated analysis text.
124
125        Raises:
126            AIProviderError: On any API or network failure.
127        """
128        return self.analyze_with_attachments(
129            system_prompt=system_prompt,
130            user_prompt=user_prompt,
131            attachments=None,
132            max_tokens=max_tokens,
133        )
134
135    def analyze_stream(
136        self,
137        system_prompt: str,
138        user_prompt: str,
139        max_tokens: int = DEFAULT_MAX_TOKENS,
140    ) -> Iterator[str]:
141        """Stream generated text chunks from Claude.
142
143        Args:
144            system_prompt: The system-level instruction text.
145            user_prompt: The user-facing prompt with investigation context.
146            max_tokens: Maximum completion tokens.
147
148        Yields:
149            Text chunk strings as they are generated.
150
151        Raises:
152            AIProviderError: On empty response or API failure.
153        """
154        def _stream() -> Iterator[str]:
155            request_kwargs: dict[str, Any] = {
156                "model": self.model,
157                "max_tokens": max_tokens,
158                "system": system_prompt,
159                "messages": [{"role": "user", "content": user_prompt}],
160                "stream": True,
161            }
162            try:
163                stream = _run_with_rate_limit_retries(
164                    request_fn=lambda: self._with_token_limit_retry(
165                        lambda kw: self.client.messages.create(**kw),
166                        request_kwargs,
167                    ),
168                    rate_limit_error_type=self._anthropic.RateLimitError,
169                    provider_name="Claude",
170                )
171                emitted = False
172                for event in stream:
173                    chunk_text = _extract_anthropic_stream_text(event)
174                    if not chunk_text:
175                        continue
176                    emitted = True
177                    yield chunk_text
178                if not emitted:
179                    raise AIProviderError("Claude returned an empty response.")
180            except AIProviderError:
181                raise
182            except self._anthropic.APIConnectionError as error:
183                raise AIProviderError(
184                    "Unable to connect to Claude API. Check network access and endpoint configuration."
185                ) from error
186            except self._anthropic.AuthenticationError as error:
187                raise AIProviderError(
188                    "Claude authentication failed. Check `ai.claude.api_key` or ANTHROPIC_API_KEY."
189                ) from error
190            except self._anthropic.BadRequestError as error:
191                if _is_context_length_error(error):
192                    raise AIProviderError(
193                        "Claude request exceeded the model context length. Reduce prompt size and retry."
194                    ) from error
195                raise AIProviderError(f"Claude request was rejected: {error}") from error
196            except self._anthropic.APIError as error:
197                raise AIProviderError(f"Claude API error: {error}") from error
198            except Exception as error:
199                raise AIProviderError(f"Unexpected Claude provider error: {error}") from error
200
201        return _stream()
202
203    def analyze_with_attachments(
204        self,
205        system_prompt: str,
206        user_prompt: str,
207        attachments: list[Mapping[str, str]] | None,
208        max_tokens: int = DEFAULT_MAX_TOKENS,
209    ) -> str:
210        """Analyze with optional CSV file attachments via Claude content blocks.
211
212        Args:
213            system_prompt: The system-level instruction text.
214            user_prompt: The user-facing prompt with investigation context.
215            attachments: Optional list of attachment descriptors.
216            max_tokens: Maximum completion tokens.
217
218        Returns:
219            The generated analysis text.
220
221        Raises:
222            AIProviderError: On any API or network failure.
223        """
224        def _request() -> str:
225            attachment_response = self._request_with_csv_attachments(
226                system_prompt=system_prompt,
227                user_prompt=user_prompt,
228                max_tokens=max_tokens,
229                attachments=attachments,
230            )
231            if attachment_response:
232                return attachment_response
233
234            effective_prompt = user_prompt
235            if attachments:
236                effective_prompt, inlined = _inline_attachment_data_into_prompt(
237                    user_prompt=user_prompt,
238                    attachments=attachments,
239                )
240                if inlined:
241                    logger.info("Claude attachment fallback inlined attachment data into prompt.")
242
243            response = self._create_message_with_stream_fallback(
244                system_prompt=system_prompt,
245                messages=[{"role": "user", "content": effective_prompt}],
246                max_tokens=max_tokens,
247            )
248            text = _extract_anthropic_text(response)
249            if not text:
250                raise AIProviderError("Claude returned an empty response.")
251            return text
252
253        return self._run_claude_request(_request)
254
255    def _run_claude_request(self, request_fn: Callable[[], _T]) -> _T:
256        """Execute a Claude request with rate-limit retries and error mapping.
257
258        Args:
259            request_fn: A zero-argument callable that performs the API request.
260
261        Returns:
262            The return value of ``request_fn`` on success.
263
264        Raises:
265            AIProviderError: On any Anthropic SDK error.
266        """
267        try:
268            return _run_with_rate_limit_retries(
269                request_fn=request_fn,
270                rate_limit_error_type=self._anthropic.RateLimitError,
271                provider_name="Claude",
272            )
273        except AIProviderError:
274            raise
275        except self._anthropic.APIConnectionError as error:
276            raise AIProviderError(
277                "Unable to connect to Claude API. Check network access and endpoint configuration."
278            ) from error
279        except self._anthropic.AuthenticationError as error:
280            raise AIProviderError(
281                "Claude authentication failed. Check `ai.claude.api_key` or ANTHROPIC_API_KEY."
282            ) from error
283        except self._anthropic.BadRequestError as error:
284            if _is_context_length_error(error):
285                raise AIProviderError(
286                    "Claude request exceeded the model context length. Reduce prompt size and retry."
287                ) from error
288            raise AIProviderError(f"Claude request was rejected: {error}") from error
289        except self._anthropic.APIError as error:
290            raise AIProviderError(f"Claude API error: {error}") from error
291        except Exception as error:
292            raise AIProviderError(f"Unexpected Claude provider error: {error}") from error
293
294    def _request_with_csv_attachments(
295        self,
296        system_prompt: str,
297        user_prompt: str,
298        max_tokens: int,
299        attachments: list[Mapping[str, str]] | None,
300    ) -> str | None:
301        """Attempt to send a request with CSV files as Claude content blocks.
302
303        Args:
304            system_prompt: The system-level instruction text.
305            user_prompt: The user-facing prompt text.
306            max_tokens: Maximum completion tokens.
307            attachments: Optional list of attachment descriptors.
308
309        Returns:
310            The generated text if attachment mode succeeded, or ``None``
311            if attachments were skipped or unsupported.
312        """
313        normalized_attachments = self._prepare_csv_attachments(attachments)
314        if not normalized_attachments:
315            return None
316
317        try:
318            content_blocks: list[dict[str, Any]] = [{"type": "text", "text": user_prompt}]
319            for attachment in normalized_attachments:
320                attachment_path = Path(attachment["path"])
321                mime_type = attachment["mime_type"].lower()
322                if mime_type == "application/pdf":
323                    encoded_data = base64.b64encode(attachment_path.read_bytes()).decode("ascii")
324                    content_blocks.append(
325                        {
326                            "type": "document",
327                            "source": {
328                                "type": "base64",
329                                "media_type": "application/pdf",
330                                "data": encoded_data,
331                            },
332                        }
333                    )
334                else:
335                    attachment_name = attachment.get("name", attachment_path.name)
336                    try:
337                        attachment_text = attachment_path.read_text(
338                            encoding="utf-8-sig", errors="replace"
339                        )
340                    except OSError:
341                        continue
342                    content_blocks.append(
343                        {
344                            "type": "text",
345                            "text": (
346                                f"--- BEGIN ATTACHMENT: {attachment_name} ---\n"
347                                f"{attachment_text.rstrip()}\n"
348                                f"--- END ATTACHMENT: {attachment_name} ---"
349                            ),
350                        }
351                    )
352
353            response = self._create_message_with_stream_fallback(
354                system_prompt=system_prompt,
355                messages=[{"role": "user", "content": content_blocks}],
356                max_tokens=max_tokens,
357            )
358            text = _extract_anthropic_text(response)
359            if not text:
360                raise AIProviderError("Claude returned an empty response for file-attachment mode.")
361
362            self._csv_attachment_supported = True
363            return text
364        except Exception as error:
365            if _is_attachment_unsupported_error(error):
366                self._csv_attachment_supported = False
367                logger.info(
368                    "Claude endpoint does not support CSV attachments; "
369                    "falling back to standard text mode."
370                )
371                return None
372            raise
373
374    def _create_message_with_stream_fallback(
375        self,
376        system_prompt: str,
377        messages: list[dict[str, Any]],
378        max_tokens: int,
379    ) -> Any:
380        """Create a Claude message, falling back to streaming for long requests.
381
382        Args:
383            system_prompt: The system-level instruction text.
384            messages: The conversation messages list.
385            max_tokens: Maximum completion tokens.
386
387        Returns:
388            The Anthropic ``Message`` response object.
389        """
390        request_kwargs: dict[str, Any] = {
391            "model": self.model,
392            "max_tokens": max_tokens,
393            "system": system_prompt,
394            "messages": messages,
395        }
396        try:
397            return self._with_token_limit_retry(
398                lambda kw: self.client.messages.create(**kw),
399                request_kwargs,
400            )
401        except ValueError as error:
402            if not _is_anthropic_streaming_required_error(error):
403                raise
404            logger.info(
405                "Claude SDK requires streaming for long request; retrying with messages.stream()."
406            )
407            return self._with_token_limit_retry(
408                lambda kw: self._stream_and_collect(**kw),
409                request_kwargs,
410            )
411
412    def _stream_and_collect(self, **kwargs: Any) -> Any:
413        """Stream a Claude request and return the final message.
414
415        Args:
416            **kwargs: Keyword arguments for ``client.messages.stream``.
417
418        Returns:
419            The final Anthropic ``Message`` response object.
420        """
421        with self.client.messages.stream(**kwargs) as stream:
422            return stream.get_final_message()
423
424    def _with_token_limit_retry(
425        self,
426        create_fn: Callable[[dict[str, Any]], Any],
427        request_kwargs: dict[str, Any],
428    ) -> Any:
429        """Execute a Claude API call with automatic token-limit retry.
430
431        If the initial request is rejected because ``max_tokens`` exceeds
432        the model's supported maximum, retries once with the lower limit
433        extracted from the error message.
434
435        This single method replaces the three near-identical retry methods
436        that existed previously.
437
438        Args:
439            create_fn: A callable that takes the request kwargs dict and
440                performs the API call.
441            request_kwargs: Keyword arguments for the API call.
442
443        Returns:
444            The API response object.
445
446        Raises:
447            anthropic.BadRequestError: If the request fails for a reason
448                other than token limits, or if the retry also fails.
449        """
450        effective_kwargs: dict[str, Any] = dict(request_kwargs)
451        for _ in range(2):
452            try:
453                return create_fn(effective_kwargs)
454            except self._anthropic.BadRequestError as error:
455                requested_tokens = int(effective_kwargs.get("max_tokens", 0))
456                retry_token_count = _resolve_completion_token_retry_limit(
457                    error=error,
458                    requested_tokens=requested_tokens,
459                )
460                if retry_token_count is None:
461                    raise
462                logger.warning(
463                    "Claude rejected max_tokens=%d; retrying with max_tokens=%d.",
464                    requested_tokens,
465                    retry_token_count,
466                )
467                effective_kwargs["max_tokens"] = retry_token_count
468        return create_fn(effective_kwargs)
469
470    def get_model_info(self) -> dict[str, str]:
471        """Return Claude provider and model metadata.
472
473        Returns:
474            A dictionary with ``"provider"`` and ``"model"`` keys.
475        """
476        return {"provider": "claude", "model": self.model}

 44class OpenAIProvider(AIProvider):
 45    """OpenAI API provider implementation.
 46
 47    Attributes:
 48        api_key (str): The OpenAI API key.
 49        model (str): The OpenAI model identifier.
 50        attach_csv_as_file (bool): Whether to upload CSV artifacts as
 51            file attachments via the Responses API.
 52        request_timeout_seconds (float): HTTP timeout in seconds.
 53        client: The ``openai.OpenAI`` SDK client instance.
 54    """
 55
 56    def __init__(
 57        self,
 58        api_key: str,
 59        model: str = DEFAULT_OPENAI_MODEL,
 60        attach_csv_as_file: bool = True,
 61        request_timeout_seconds: float = DEFAULT_CLOUD_REQUEST_TIMEOUT_SECONDS,
 62    ) -> None:
 63        """Initialize the OpenAI provider.
 64
 65        Args:
 66            api_key: OpenAI API key. Must be non-empty.
 67            model: OpenAI model identifier.
 68            attach_csv_as_file: If ``True``, attempt file uploads via
 69                the Responses API.
 70            request_timeout_seconds: HTTP timeout in seconds.
 71
 72        Raises:
 73            AIProviderError: If the ``openai`` SDK is not installed or
 74                the API key is empty.
 75        """
 76        try:
 77            import openai
 78        except ImportError as error:
 79            raise AIProviderError(
 80                "openai SDK is not installed. Install it with `pip install openai`."
 81            ) from error
 82
 83        normalized_api_key = _normalize_api_key_value(api_key)
 84        if not normalized_api_key:
 85            raise AIProviderError(
 86                "OpenAI API key is not configured. "
 87                "Set `ai.openai.api_key` in config.yaml or the OPENAI_API_KEY environment variable."
 88            )
 89
 90        self._openai = openai
 91        self.api_key = normalized_api_key
 92        self.model = model
 93        self.attach_csv_as_file = bool(attach_csv_as_file)
 94        self._csv_attachment_supported: bool | None = None
 95        self.request_timeout_seconds = _resolve_timeout_seconds(
 96            request_timeout_seconds,
 97            DEFAULT_CLOUD_REQUEST_TIMEOUT_SECONDS,
 98        )
 99        self.client = openai.OpenAI(
100            api_key=normalized_api_key,
101            timeout=self.request_timeout_seconds,
102        )
103        logger.info("Initialized OpenAI provider with model %s (timeout %.1fs)", model, self.request_timeout_seconds)
104
105    def analyze(
106        self,
107        system_prompt: str,
108        user_prompt: str,
109        max_tokens: int = DEFAULT_MAX_TOKENS,
110    ) -> str:
111        """Send a prompt to OpenAI and return the generated text.
112
113        Args:
114            system_prompt: The system-level instruction text.
115            user_prompt: The user-facing prompt with investigation context.
116            max_tokens: Maximum completion tokens.
117
118        Returns:
119            The generated analysis text.
120
121        Raises:
122            AIProviderError: On any API or network failure.
123        """
124        return self.analyze_with_attachments(
125            system_prompt=system_prompt,
126            user_prompt=user_prompt,
127            attachments=None,
128            max_tokens=max_tokens,
129        )
130
131    def analyze_stream(
132        self,
133        system_prompt: str,
134        user_prompt: str,
135        max_tokens: int = DEFAULT_MAX_TOKENS,
136    ) -> Iterator[str]:
137        """Stream generated text chunks from OpenAI.
138
139        Args:
140            system_prompt: The system-level instruction text.
141            user_prompt: The user-facing prompt with investigation context.
142            max_tokens: Maximum completion tokens.
143
144        Yields:
145            Text chunk strings as they are generated.
146
147        Raises:
148            AIProviderError: On empty response or API failure.
149        """
150        def _stream() -> Iterator[str]:
151            messages = [
152                {"role": "system", "content": system_prompt},
153                {"role": "user", "content": user_prompt},
154            ]
155            stream = self._run_openai_request(
156                lambda: self._create_chat_completion(
157                    messages=messages,
158                    max_tokens=max_tokens,
159                    stream=True,
160                )
161            )
162            emitted = False
163            try:
164                for chunk in stream:
165                    choices = getattr(chunk, "choices", None)
166                    if not choices:
167                        continue
168                    choice = choices[0]
169                    delta = getattr(choice, "delta", None)
170                    if delta is None and isinstance(choice, dict):
171                        delta = choice.get("delta")
172                    chunk_text = _extract_openai_delta_text(
173                        delta,
174                        ("content", "reasoning_content", "reasoning", "refusal"),
175                    )
176                    if not chunk_text:
177                        continue
178                    emitted = True
179                    yield chunk_text
180            except AIProviderError:
181                raise
182            except self._openai.APIConnectionError as error:
183                raise AIProviderError(
184                    "Unable to connect to OpenAI API. Check network access and endpoint configuration."
185                ) from error
186            except self._openai.AuthenticationError as error:
187                raise AIProviderError(
188                    "OpenAI authentication failed. Check `ai.openai.api_key` or OPENAI_API_KEY."
189                ) from error
190            except self._openai.BadRequestError as error:
191                if _is_context_length_error(error):
192                    raise AIProviderError(
193                        "OpenAI request exceeded the model context length. Reduce prompt size and retry."
194                    ) from error
195                raise AIProviderError(f"OpenAI request was rejected: {error}") from error
196            except self._openai.APIError as error:
197                raise AIProviderError(f"OpenAI API error: {error}") from error
198            except Exception as error:
199                raise AIProviderError(f"Unexpected OpenAI provider error: {error}") from error
200
201            if not emitted:
202                raise AIProviderError("OpenAI returned an empty response.")
203
204        return _stream()
205
206    def analyze_with_attachments(
207        self,
208        system_prompt: str,
209        user_prompt: str,
210        attachments: list[Mapping[str, str]] | None,
211        max_tokens: int = DEFAULT_MAX_TOKENS,
212    ) -> str:
213        """Analyze with optional CSV file attachments via the Responses API.
214
215        Args:
216            system_prompt: The system-level instruction text.
217            user_prompt: The user-facing prompt with investigation context.
218            attachments: Optional list of attachment descriptors.
219            max_tokens: Maximum completion tokens.
220
221        Returns:
222            The generated analysis text.
223
224        Raises:
225            AIProviderError: On any API or network failure.
226        """
227        def _request() -> str:
228            return self._request_non_stream(
229                system_prompt=system_prompt,
230                user_prompt=user_prompt,
231                max_tokens=max_tokens,
232                attachments=attachments,
233            )
234
235        return self._run_openai_request(_request)
236
237    def _run_openai_request(self, request_fn: Callable[[], _T]) -> _T:
238        """Execute an OpenAI request with rate-limit retries and error mapping.
239
240        Args:
241            request_fn: A zero-argument callable that performs the request.
242
243        Returns:
244            The return value of ``request_fn`` on success.
245
246        Raises:
247            AIProviderError: On any OpenAI SDK error.
248        """
249        try:
250            return _run_with_rate_limit_retries(
251                request_fn=request_fn,
252                rate_limit_error_type=self._openai.RateLimitError,
253                provider_name="OpenAI",
254            )
255        except AIProviderError:
256            raise
257        except self._openai.APIConnectionError as error:
258            raise AIProviderError(
259                "Unable to connect to OpenAI API. Check network access and endpoint configuration."
260            ) from error
261        except self._openai.AuthenticationError as error:
262            raise AIProviderError(
263                "OpenAI authentication failed. Check `ai.openai.api_key` or OPENAI_API_KEY."
264            ) from error
265        except self._openai.BadRequestError as error:
266            if _is_context_length_error(error):
267                raise AIProviderError(
268                    "OpenAI request exceeded the model context length. Reduce prompt size and retry."
269                ) from error
270            raise AIProviderError(f"OpenAI request was rejected: {error}") from error
271        except self._openai.APIError as error:
272            raise AIProviderError(f"OpenAI API error: {error}") from error
273        except Exception as error:
274            raise AIProviderError(f"Unexpected OpenAI provider error: {error}") from error
275
276    def _request_non_stream(
277        self,
278        system_prompt: str,
279        user_prompt: str,
280        max_tokens: int,
281        attachments: list[Mapping[str, str]] | None = None,
282    ) -> str:
283        """Perform a non-streaming OpenAI request with attachment handling.
284
285        Tries file-attachment mode first, then falls back to inlining
286        attachment data, and finally issues a plain Chat Completions request.
287
288        Args:
289            system_prompt: The system-level instruction text.
290            user_prompt: The user-facing prompt text.
291            max_tokens: Maximum completion tokens.
292            attachments: Optional list of attachment descriptors.
293
294        Returns:
295            The generated analysis text.
296
297        Raises:
298            AIProviderError: If the response is empty.
299        """
300        attachment_response = self._request_with_csv_attachments(
301            system_prompt=system_prompt,
302            user_prompt=user_prompt,
303            max_tokens=max_tokens,
304            attachments=attachments,
305        )
306        if attachment_response:
307            return attachment_response
308
309        prompt_for_completion = user_prompt
310        if attachments:
311            prompt_for_completion, inlined_attachment_data = _inline_attachment_data_into_prompt(
312                user_prompt=user_prompt,
313                attachments=attachments,
314            )
315            if inlined_attachment_data:
316                logger.info("OpenAI attachment fallback inlined attachment data into prompt.")
317
318        messages = [
319            {"role": "system", "content": system_prompt},
320            {"role": "user", "content": prompt_for_completion},
321        ]
322        response = self._create_chat_completion(
323            messages=messages,
324            max_tokens=max_tokens,
325        )
326        text = _extract_openai_text(response)
327        if not text:
328            raise AIProviderError("OpenAI returned an empty response.")
329        return text
330
331    def _create_chat_completion(
332        self,
333        messages: list[dict[str, str]],
334        max_tokens: int,
335        stream: bool = False,
336    ) -> Any:
337        """Create a Chat Completions request with token parameter fallback.
338
339        Tries ``max_completion_tokens`` first, then falls back to
340        ``max_tokens`` if the endpoint reports the parameter as unsupported.
341        Also retries with a reduced token count when the provider rejects
342        the requested maximum.
343
344        Args:
345            messages: The conversation messages list.
346            max_tokens: Maximum completion tokens.
347            stream: If ``True``, return a streaming response iterator.
348
349        Returns:
350            The OpenAI ``ChatCompletion`` response or streaming iterator.
351        """
352        def _create_with_token_parameter(token_parameter: str, token_count: int) -> Any:
353            """Try creating with a specific token parameter, retrying on token limit."""
354            request_kwargs: dict[str, Any] = {
355                "model": self.model,
356                "messages": messages,
357                token_parameter: token_count,
358            }
359            if stream:
360                request_kwargs["stream"] = True
361            try:
362                return self.client.chat.completions.create(**request_kwargs)
363            except self._openai.BadRequestError as error:
364                retry_token_count = _resolve_completion_token_retry_limit(
365                    error=error,
366                    requested_tokens=token_count,
367                )
368                if retry_token_count is None:
369                    raise
370                logger.warning(
371                    "OpenAI rejected %s=%d; retrying with %s=%d.",
372                    token_parameter,
373                    token_count,
374                    token_parameter,
375                    retry_token_count,
376                )
377                request_kwargs[token_parameter] = retry_token_count
378                return self.client.chat.completions.create(**request_kwargs)
379
380        try:
381            return _create_with_token_parameter(
382                token_parameter="max_completion_tokens",
383                token_count=max_tokens,
384            )
385        except self._openai.BadRequestError as error:
386            if not _is_unsupported_parameter_error(error, "max_completion_tokens"):
387                raise
388            return _create_with_token_parameter(
389                token_parameter="max_tokens",
390                token_count=max_tokens,
391            )
392
393    def _request_with_csv_attachments(
394        self,
395        system_prompt: str,
396        user_prompt: str,
397        max_tokens: int,
398        attachments: list[Mapping[str, str]] | None,
399    ) -> str | None:
400        """Attempt to send a request with CSV files via the Responses API.
401
402        Args:
403            system_prompt: The system-level instruction text.
404            user_prompt: The user-facing prompt text.
405            max_tokens: Maximum completion tokens.
406            attachments: Optional list of attachment descriptors.
407
408        Returns:
409            The generated text if succeeded, or ``None`` if skipped.
410        """
411        normalized_attachments = self._prepare_csv_attachments(
412            attachments,
413            supports_file_attachments=hasattr(self.client, "files") and hasattr(self.client, "responses"),
414        )
415        if not normalized_attachments:
416            return None
417
418        try:
419            text = upload_and_request_via_responses_api(
420                client=self.client,
421                openai_module=self._openai,
422                model=self.model,
423                normalized_attachments=normalized_attachments,
424                system_prompt=system_prompt,
425                user_prompt=user_prompt,
426                max_tokens=max_tokens,
427                provider_name="OpenAI",
428                upload_purpose="assistants",
429                convert_csv_to_txt=True,
430            )
431            self._csv_attachment_supported = True
432            return text
433        except Exception as error:
434            if _is_attachment_unsupported_error(error):
435                self._csv_attachment_supported = False
436                logger.info(
437                    "OpenAI endpoint does not support CSV attachments via /files + /responses; "
438                    "falling back to chat.completions text mode."
439                )
440                return None
441            raise
442
443    def get_model_info(self) -> dict[str, str]:
444        """Return OpenAI provider and model metadata.
445
446        Returns:
447            A dictionary with ``"provider"`` and ``"model"`` keys.
448        """
449        return {"provider": "openai", "model": self.model}