fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/llm/provider/openai/llm_openai_compatible.py

@@ -0,0 +1,138 @@
+from typing import Type
+
+from fast_agent.interfaces import ModelT
+from fast_agent.llm.model_database import ModelDatabase
+from fast_agent.llm.provider.openai.llm_openai import OpenAILLM
+from fast_agent.mcp.helpers.content_helpers import split_thinking_content
+from fast_agent.types import PromptMessageExtended, RequestParams
+
+
+class OpenAICompatibleLLM(OpenAILLM):
+    """Shared helpers for OpenAI-compatible providers that need structured output prompting."""
+
+    STRUCTURED_PROMPT_TEMPLATE = """YOU MUST RESPOND WITH A JSON OBJECT IN EXACTLY THIS FORMAT:
+{format_description}
+
+IMPORTANT RULES:
+- Respond ONLY with the JSON object, no other text
+- Do NOT include "properties" or "schema" wrappers
+- Do NOT use code fences or markdown
+- The response must be valid JSON that matches the format above
+- All required fields must be included"""
+
+    async def _apply_prompt_provider_specific_structured(
+        self,
+        multipart_messages: list[PromptMessageExtended],
+        model: Type[ModelT],
+        request_params: RequestParams | None = None,
+    ) -> tuple[ModelT | None, PromptMessageExtended]:
+        if not self._supports_structured_prompt():
+            return await super()._apply_prompt_provider_specific_structured(
+                multipart_messages, model, request_params
+            )
+
+        request_params = self.get_request_params(request_params)
+
+        prompt_format = self._structured_prompt_format()
+        if prompt_format == "json_object" and not request_params.response_format:
+            request_params.response_format = {"type": "json_object"}
+
+        instructions = self._build_structured_prompt_instruction(model)
+        if instructions:
+            multipart_messages[-1].add_text(instructions)
+
+        return await super()._apply_prompt_provider_specific_structured(
+            multipart_messages, model, request_params
+        )
+
+    def _supports_structured_prompt(self) -> bool:
+        """Allow subclasses to opt-out of shared structured prompting."""
+        return True
+
+    def _structured_prompt_format(self) -> str | None:
+        """Return the response_format type this provider expects."""
+        return "json_object"
+
+    def _build_structured_prompt_instruction(self, model: Type[ModelT]) -> str | None:
+        template = self._structured_prompt_template()
+        if not template:
+            return None
+
+        schema = model.model_json_schema()
+        format_description = self._schema_to_json_object(schema, schema.get("$defs"))
+        return template.format(format_description=format_description)
+
+    def _structured_prompt_template(self) -> str | None:
+        return self.STRUCTURED_PROMPT_TEMPLATE
+
+    def _prepare_structured_text(self, text: str) -> str:
+        reasoning_mode = self._structured_reasoning_mode()
+        if reasoning_mode == "tags":
+            thinking, trimmed = split_thinking_content(text)
+            if thinking is None:
+                closing_tag = "</think>"
+                closing_index = text.find(closing_tag)
+                if closing_index != -1:
+                    trimmed = text[closing_index + len(closing_tag) :].lstrip()
+                else:
+                    trimmed = text
+            return trimmed
+
+        if "</think>" in text:
+            logger = getattr(self, "logger", None)
+            if logger:
+                logger.warning(
+                    "Model emitted reasoning tags without 'tags' reasoning mode",
+                    data={
+                        "model": getattr(self.default_request_params, "model", None),
+                        "text_preview": text[:200],
+                    },
+                )
+        return text
+
+    def _structured_reasoning_mode(self) -> str | None:
+        model_name = self.default_request_params.model if self.default_request_params else None
+        return ModelDatabase.get_reasoning(model_name) if model_name else None
+
+    def _schema_to_json_object(
+        self, schema: dict, defs: dict | None = None, visited: set | None = None
+    ) -> str:
+        """Render a compact, human-friendly shape of the JSON schema."""
+        visited = visited or set()
+
+        if id(schema) in visited:
+            return '"<recursive>"'
+        visited.add(id(schema))
+
+        if "$ref" in schema:
+            ref = schema.get("$ref", "")
+            if ref.startswith("#/$defs/"):
+                target = ref.split("/")[-1]
+                if defs and target in defs:
+                    return self._schema_to_json_object(defs[target], defs, visited)
+            return f'"<ref:{ref}>"'
+
+        schema_type = schema.get("type")
+        description = schema.get("description", "")
+        required = schema.get("required", [])
+
+        if schema_type == "object":
+            props = schema.get("properties", {})
+            result = "{\n"
+            for prop_name, prop_schema in props.items():
+                is_required = prop_name in required
+                prop_str = self._schema_to_json_object(prop_schema, defs, visited)
+                if is_required:
+                    prop_str += " // REQUIRED"
+                result += f'  "{prop_name}": {prop_str},\n'
+            result += "}"
+            return result
+        elif schema_type == "array":
+            items = schema.get("items", {})
+            items_str = self._schema_to_json_object(items, defs, visited)
+            return f"[{items_str}]"
+        elif schema_type:
+            comment = f" // {description}" if description else ""
+            return f'"{schema_type}"' + comment
+
+        return '"<unknown>"'

fast_agent/llm/provider/openai/llm_openrouter.py

@@ -0,0 +1,45 @@
+import os
+
+from fast_agent.llm.provider.openai.llm_openai import OpenAILLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.types import RequestParams
+
+DEFAULT_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+# No single default model for OpenRouter, users must specify full path
+DEFAULT_OPENROUTER_MODEL = None
+
+
+class OpenRouterLLM(OpenAILLM):
+    """Augmented LLM provider for OpenRouter, using an OpenAI-compatible API."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, provider=Provider.OPENROUTER, **kwargs)
+
+    def _initialize_default_params(self, kwargs: dict) -> RequestParams:
+        """Initialize OpenRouter-specific default parameters."""
+        # Get base defaults from parent (includes ModelDatabase lookup)
+        base_params = super()._initialize_default_params(kwargs)
+
+        # Override with OpenRouter-specific settings
+        # OpenRouter model names include the provider, e.g., "google/gemini-flash-1.5"
+        # The model should be passed in the 'model' kwarg during factory creation.
+        chosen_model = kwargs.get("model", DEFAULT_OPENROUTER_MODEL)
+        if chosen_model:
+            base_params.model = chosen_model
+        # If it's still None here, it indicates an issue upstream (factory or user input).
+        # However, the base class _get_model handles the error if model is None.
+
+        return base_params
+
+    def _base_url(self) -> str:
+        """Retrieve the OpenRouter base URL from config or use the default."""
+        base_url = os.getenv("OPENROUTER_BASE_URL", DEFAULT_OPENROUTER_BASE_URL)  # Default
+        config = self.context.config
+
+        # Check config file for override
+        if config and hasattr(config, "openrouter") and config.openrouter:
+            config_base_url = getattr(config.openrouter, "base_url", None)
+            if config_base_url:
+                base_url = config_base_url
+
+        return base_url

fast_agent/llm/provider/openai/llm_tensorzero_openai.py

@@ -0,0 +1,128 @@
+from typing import Any
+
+from openai.types.chat import ChatCompletionMessageParam, ChatCompletionSystemMessageParam
+
+from fast_agent.llm.provider.openai.llm_openai import OpenAILLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.types import RequestParams
+
+
+class TensorZeroOpenAILLM(OpenAILLM):
+    """
+    An LLM augmentation that interacts with TensorZero's OpenAI-compatible inference endpoint.
+    This class extends the base OpenAIAugmentedLLM to handle TensorZero-specific
+    features, such as system template variables and custom parameters.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        """
+        Initializes the TensorZeroOpenAIAugmentedLLM.
+
+        Args:
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
+        self._t0_episode_id = kwargs.pop("episode_id", None)
+        self._t0_function_name = kwargs.get("model", "")
+
+        super().__init__(*args, provider=Provider.TENSORZERO, **kwargs)
+        self.logger.info("TensorZeroOpenAILLM initialized.")
+
+    def _initialize_default_params(self, kwargs: dict) -> RequestParams:
+        """
+        Initializes TensorZero-specific default parameters. Ensures the model name
+        is correctly prefixed for the TensorZero API.
+        """
+        model = kwargs.get("model", "")
+        if not model.startswith("tensorzero::"):
+            model = f"tensorzero::function_name::{model}"
+
+        self.logger.debug(f"Initializing with TensorZero model: {model}")
+
+        return RequestParams(
+            model=model,
+            systemPrompt=self.instruction,
+            parallel_tool_calls=True,
+            max_iterations=10,
+            use_history=True,
+        )
+
+    def _base_url(self) -> str:
+        """
+        Constructs the TensorZero OpenAI-compatible endpoint URL.
+        """
+        default_url = "http://localhost:3000/openai/v1"
+        if self.context and self.context.config and hasattr(self.context.config, "tensorzero"):
+            base_url = getattr(self.context.config.tensorzero, "base_url", default_url)
+            # Ensure the path is correctly appended
+            if not base_url.endswith("/openai/v1"):
+                base_url = f"{base_url.rstrip('/')}/openai/v1"
+            self.logger.debug(f"Using TensorZero base URL from config: {base_url}")
+            return base_url
+        self.logger.debug(f"Using default TensorZero base URL: {default_url}")
+        return default_url
+
+    def _prepare_api_request(
+        self,
+        messages: list[ChatCompletionMessageParam],
+        tools: list[Any] | None,
+        request_params: RequestParams,
+    ) -> dict[str, Any]:
+        """
+        Prepares the API request for the TensorZero OpenAI-compatible endpoint.
+        This method injects system template variables and other TensorZero-specific
+        parameters into the request. It also handles multimodal inputs.
+        """
+        self.logger.debug("Preparing API request for TensorZero OpenAI endpoint.")
+
+        # Start with the base arguments from the parent class
+        arguments = super()._prepare_api_request(messages, tools, request_params)
+
+        # Handle system template variables
+        if request_params.template_vars:
+            self.logger.debug(f"Injecting template variables: {request_params.template_vars}")
+            system_message_found = False
+            for i, msg in enumerate(messages):
+                if msg.get("role") == "system":
+                    # If content is a string, convert it to the TensorZero format
+                    if isinstance(msg.get("content"), str):
+                        messages[i] = ChatCompletionSystemMessageParam(
+                            role="system", content=[request_params.template_vars]
+                        )
+                    elif isinstance(msg.get("content"), list):
+                        # If content is already a list, merge the template vars
+                        msg["content"][0].update(request_params.template_vars)
+                    system_message_found = True
+                    break
+
+            if not system_message_found:
+                # If no system message exists, create one
+                messages.insert(
+                    0,
+                    ChatCompletionSystemMessageParam(
+                        role="system", content=[request_params.template_vars]
+                    ),
+                )
+
+        # Add TensorZero-specific extra body parameters
+        extra_body = arguments.get("extra_body", {})
+
+        if self._t0_episode_id:
+            extra_body["tensorzero::episode_id"] = str(self._t0_episode_id)
+            self.logger.debug(f"Added tensorzero::episode_id: {self._t0_episode_id}")
+
+        # Merge metadata arguments
+        if request_params.metadata and isinstance(request_params.metadata, dict):
+            t0_args = request_params.metadata.get("tensorzero_arguments")
+            if t0_args:
+                self.logger.debug(f"Merging tensorzero_arguments from metadata: {t0_args}")
+                for msg in messages:
+                    if msg.get("role") == "system" and isinstance(msg.get("content"), list):
+                        msg["content"][0].update(t0_args)
+                        break
+
+        if extra_body:
+            arguments["extra_body"] = extra_body
+
+        self.logger.debug(f"Final API request arguments: {arguments}")
+        return arguments

fast_agent/llm/provider/openai/llm_xai.py

@@ -0,0 +1,38 @@
+import os
+
+from fast_agent.llm.provider.openai.llm_openai import OpenAILLM
+from fast_agent.llm.provider_types import Provider
+from fast_agent.types import RequestParams
+
+XAI_BASE_URL = "https://api.x.ai/v1"
+DEFAULT_XAI_MODEL = "grok-3"
+
+
+class XAILLM(OpenAILLM):
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(
+            *args, provider=Provider.XAI, **kwargs
+        )  # Properly pass args and kwargs to parent
+
+    def _initialize_default_params(self, kwargs: dict) -> RequestParams:
+        """Initialize xAI parameters"""
+        # Get base defaults from parent (includes ModelDatabase lookup)
+        base_params = super()._initialize_default_params(kwargs)
+
+        # Override with xAI-specific settings
+        chosen_model = kwargs.get("model", DEFAULT_XAI_MODEL)
+        base_params.model = chosen_model
+        base_params.parallel_tool_calls = False
+
+        return base_params
+
+    def _base_url(self) -> str:
+        base_url = os.getenv("XAI_BASE_URL", XAI_BASE_URL)
+        if self.context.config and self.context.config.xai:
+            base_url = self.context.config.xai.base_url
+
+        return base_url
+
+    async def _is_tool_stop_reason(self, finish_reason: str) -> bool:
+        # grok uses Null as the finish reason for tool calls?
+        return await super()._is_tool_stop_reason(finish_reason) or finish_reason is None