meta_mcp.utils
==============

.. py:module:: meta_mcp.utils


Classes
-------

.. autoapisummary::

   meta_mcp.utils.SchemaReasoningOutput


Functions
---------

.. autoapisummary::

   meta_mcp.utils.load_config
   meta_mcp.utils.to_message
   meta_mcp.utils.get_structured_response_litellm
   meta_mcp.utils.structured_response_to_output_model
   meta_mcp.utils.load_json_from_url
   meta_mcp.utils.fix_schema
   meta_mcp.utils.registry_json_to_df


Module Contents
---------------

.. py:function:: load_config(mcp_json_path: str) -> dict

   Load MCP configuration from a JSON file.

   :param mcp_json_path: Path to the MCP configuration JSON file.
   :type mcp_json_path: str

   :returns: MCP configuration data.
   :rtype: dict


.. py:function:: to_message(content: str, role: str = 'user', content_type: str = 'input_text')

   Create a message dictionary for LLM API calls.

   :param content: The message content text.
   :type content: str
   :param role: The role of the message sender (default: "user").
   :type role: str
   :param content_type: The type of content (default: "input_text").
   :type content_type: str

   :returns: Message payload for LLM API calls.
   :rtype: dict


.. py:function:: get_structured_response_litellm(input: str, system_prompt: str, output_model: type[pydantic.BaseModel], model: str = 'openai/gpt-5-nano', temperature: float = 1.0) -> pydantic.BaseModel

   Get a structured response from LiteLLM using JSON schema validation.

   :param input: The user input text.
   :type input: str
   :param system_prompt: The system prompt to guide the model.
   :type system_prompt: str
   :param output_model: Pydantic model class defining the expected output schema.
   :type output_model: type
   :param model: The model name to use (default: "openai/gpt-5-nano").
   :type model: str
   :param temperature: Sampling temperature (default: 1.0).
   :type temperature: float

   :returns: LiteLLM response object containing the structured output.
   :rtype: object

   :raises RuntimeError: If the LLM call fails:


.. py:function:: structured_response_to_output_model(response: litellm.Response, output_model: type[pydantic.BaseModel]) -> pydantic.BaseModel

   Convert a LiteLLM Response to a Pydantic model instance.

   :param response: LiteLLM response object containing the structured output.
   :type response: object
   :param output_model: Pydantic model class to instantiate.
   :type output_model: type

   :returns: Instance of the output_model populated with data from the response.
   :rtype: object

   :raises ValueError: If the response is invalid or cannot be parsed into the model:


.. py:class:: SchemaReasoningOutput(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   Output model for schema reasoning.


   .. py:attribute:: biocontextai_schema_reasoning
      :type:  Annotated[str, Field(description='Any reasoning that might help to arrive at an answer that matches the given schema.')]


.. py:function:: load_json_from_url(url_or_path: str, timeout: float = 10.0)

   Download and parse a JSON file from URL or load from file path.

   :param url_or_path: URL to download JSON from or local file path.
   :type url_or_path: str
   :param timeout: Timeout in seconds for URL requests (default: 10.0).
   :type timeout: float

   :returns: Parsed JSON data.
   :rtype: dict


.. py:function:: fix_schema(schema: dict) -> dict

   Recursively fix arrays with prefixItems but no items by converting prefixItems to items.


.. py:function:: registry_json_to_df(registry_json: list[dict]) -> pandas.DataFrame

   Convert registry JSON (list of dicts) to a pandas DataFrame.

   Collects all possible columns from all elements, handling missing keys.
   Nested JSON structures are converted to JSON strings.

   :param registry_json: List of dictionaries representing registry entries.
   :type registry_json: list[dict]

   :returns: DataFrame with all columns from all registry entries.
   :rtype: pd.DataFrame