$jxndZddlmZmZddlmZddlmZmZGddeZ Gdd e Z d S) z Abstract interface for LLM providers. This module defines the interface that all LLM providers must implement, enabling support for multiple LLM backends (OpenAI, Anthropic, Gemini, Codex, etc.) )ABCabstractmethod)Any)LLMToolCallResult TokenUsagec>eZdZdZ d/dedededededef d Zed0d Ze d1de e eefded zde d zde d zdede de de de de de d efdZe d2de e eefde e eefde d zde d zdede de de d"ee eefzd efd#Zd e fd$Z d3d'e e eefd(ed)ed e eeffd*Zd+ed e eeffd,Zd+ed e e eeffd-Zed0d.Zd S)4 LLMInterfacez Abstract interface for LLM providers. All LLM provider implementations must inherit from this class and implement the required methods. lowproviderapi_keybase_urlmodelreasoning_effortkwargsc p||_||_||_||_||_dS)a Initialize LLM provider. Args: provider: Provider name (e.g., "openai", "codex", "anthropic", "gemini"). api_key: API key or authentication token. base_url: Base URL for the API. model: Model name. reasoning_effort: Reasoning effort level for supported providers. **kwargs: Additional provider-specific parameters. N)lowerr r rrr)selfr r rrrrs j/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/hindsight_api/engine/llm_interface.py__init__zLLMInterface.__init__s8(!((     0returnNc KdS)z Verify that the LLM provider is configured correctly by making a simple test call. Raises: RuntimeError: If the connection test fails. Nrs rverify_connectionzLLMInterface.verify_connection0s  rmemory ?N@Fmessagesresponse_formatmax_completion_tokens temperaturescope max_retriesinitial_backoff max_backoffskip_validation strict_schema return_usagec  KdS)a Make an LLM API call with retry logic. Args: messages: List of message dicts with 'role' and 'content'. response_format: Optional Pydantic model for structured output. max_completion_tokens: Maximum tokens in response. temperature: Sampling temperature (0.0-2.0). scope: Scope identifier for tracking. max_retries: Maximum retry attempts. initial_backoff: Initial backoff time in seconds. max_backoff: Maximum backoff time in seconds. skip_validation: Return raw JSON without Pydantic validation. strict_schema: Use strict JSON schema enforcement (OpenAI only). return_usage: If True, return tuple (result, TokenUsage) instead of just result. Returns: If return_usage=False: Parsed response if response_format is provided, otherwise text content. If return_usage=True: Tuple of (result, TokenUsage) with token counts. Raises: OutputTooLongError: If output exceeds token limits. Exception: Re-raises API errors after retries exhausted. Nr) rr!r"r#r$r%r&r'r(r)r*r+s rcallzLLMInterface.call:sN rtools>@auto tool_choicec  KdS)a Make an LLM API call with tool/function calling support. Args: messages: List of message dicts. Can include tool results with role='tool'. tools: List of tool definitions in OpenAI format. max_completion_tokens: Maximum tokens in response. temperature: Sampling temperature (0.0-2.0). scope: Scope identifier for tracking. max_retries: Maximum retry attempts. initial_backoff: Initial backoff time in seconds. max_backoff: Maximum backoff time in seconds. tool_choice: How to choose tools - "auto", "none", "required", or specific function. Returns: LLMToolCallResult with content and/or tool_calls. Nr) rr!r.r#r$r%r&r'r(r2s rcall_with_toolszLLMInterface.call_with_toolscs < rc KdS)z Check if this provider supports batch API operations. Returns: True if provider supports submit_batch/get_batch_status/retrieve_batch_results Frrs rsupports_batch_apizLLMInterface.supports_batch_apis ur/v1/chat/completions24hrequestsendpointcompletion_windowc4Ktd|j)a Submit a batch of requests to the provider's batch API. Args: requests: List of request dicts in JSONL format (custom_id, method, url, body) endpoint: API endpoint for the batch (e.g., "/v1/chat/completions") completion_window: Completion window (e.g., "24h") Returns: Dict with batch metadata: {"batch_id": str, "status": str, ...} Raises: NotImplementedError: If provider doesn't support batch API &Batch API not supported for provider: NotImplementedErrorr )rr9r:r;s r submit_batchzLLMInterface.submit_batchs!(""Z4="Z"Z[[[rbatch_idc4Ktd|j)aI Get the status of a batch job. Args: batch_id: Batch identifier returned from submit_batch Returns: Dict with status info: {"batch_id": str, "status": str, "completed_at": str, ...} Raises: NotImplementedError: If provider doesn't support batch API r=r>rrAs rget_batch_statuszLLMInterface.get_batch_status!""Z4="Z"Z[[[rc4Ktd|j)a7 Retrieve completed batch results. Args: batch_id: Batch identifier returned from submit_batch Returns: List of result dicts (one per request, matched by custom_id) Raises: NotImplementedError: If provider doesn't support batch API r=r>rCs rretrieve_batch_resultsz#LLMInterface.retrieve_batch_resultsrErc KdS)z-Clean up resources (close connections, etc.).Nrrs rcleanupzLLMInterface.cleanups  r)r )rN) NNNrrrr FFF)NNr.r/rr0r1)r7r8)__name__ __module__ __qualname____doc__strrrrrlistdictintfloatboolr-rr4r6r@rDrGrIrrrr r s=!& 1111 1  1  111114   ^ '+,0$(!$! %#"& & tCH~&& t&  #Tz & T\ &  & & & & & & &  & & & ^& P -1$(!$!,2  tCH~& DcN#  #Tz  T\       4S>)     ^ >$/!& \\tCH~&\\ \ c3h \\\\, \s \tCH~ \ \ \ \ \S \T$sCx.=Q \ \ \ \   ^   rr ceZdZdZdS)OutputTooLongErrora  Bridge exception raised when LLM output exceeds token limits. This wraps provider-specific errors (e.g., OpenAI's LengthFinishReasonError) to allow callers to handle output length issues without depending on provider-specific implementations. N)rJrKrLrMrrrrUrUs DrrUN) rMabcrrtypingrresponse_modelsrrr ExceptionrUrrrrZs$#######::::::::u u u u u 3u u u p            r