oas2mcp.agent.base
==================

.. py:module:: oas2mcp.agent.base

.. autoapi-nested-parse::

   Thin LangChain v1 agent factory helpers for ``oas2mcp``.

   Purpose:
       Provide shared helpers for constructing LangChain v1 agents and the default
       OpenAI-backed chat model used by ``oas2mcp`` workflows.

   Design:
       - Keep the wrapper intentionally thin.
       - Centralize common defaults such as runtime context schema and state schema.
       - Centralize default model construction, reasoning configuration, and
         environment loading.
       - Leave workflow-specific prompts, middleware, and structured outputs to
         submodules like ``summarizer`` and ``enhancer``.

   .. rubric:: Examples

   .. code-block:: python

       model = build_default_chat_model()
       agent = build_base_agent(
           model=model,
           response_format=MyOutputModel,
       )



Attributes
----------

.. autoapisummary::

   oas2mcp.agent.base.DEFAULT_MODEL_NAME
   oas2mcp.agent.base.DEFAULT_REASONING_EFFORT


Functions
---------

.. autoapisummary::

   oas2mcp.agent.base.build_base_agent
   oas2mcp.agent.base.build_default_chat_model
   oas2mcp.agent.base.load_project_env
   oas2mcp.agent.base.require_openai_api_key


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

.. py:function:: build_base_agent(*, response_format: Any, tools: list[Any] | None = None, middleware: list[Any] | None = None, system_prompt: str | None = None, model: Any | None = None, model_name: str = DEFAULT_MODEL_NAME, reasoning_effort: str = DEFAULT_REASONING_EFFORT, model_kwargs: dict[str, Any] | None = None)

   Build a stateful LangChain v1 agent for ``oas2mcp``.

   :param response_format: Structured output schema or strategy.
   :param tools: Optional tools.
   :param middleware: Optional middleware stack.
   :param system_prompt: Optional base system prompt.
   :param model: Optional model instance or model identifier.
   :param model_name: Default model name when ``model`` is omitted.
   :param reasoning_effort: Default reasoning effort when ``model`` is omitted.
   :param model_kwargs: Extra kwargs used only when building the default model.

   :returns: The constructed LangChain agent runnable.

   :raises RuntimeError: If the default model is used and no API key is available.


.. py:function:: build_default_chat_model(*, model_name: str = DEFAULT_MODEL_NAME, reasoning_effort: str = DEFAULT_REASONING_EFFORT, api_key: str | None = None, **kwargs: Any) -> langchain_openai.ChatOpenAI

   Build the default OpenAI chat model.

   :param model_name: The OpenAI model name.
   :param reasoning_effort: The reasoning effort to request.
   :param api_key: Optional OpenAI API key.
   :param \*\*kwargs: Extra keyword arguments forwarded to ``ChatOpenAI``.

   :returns: Configured chat model.
   :rtype: ChatOpenAI

   :raises RuntimeError: If no API key is available.


.. py:function:: load_project_env() -> None

   Load likely project-local environment files.

   :param None.:

   :returns: None.

   :raises None.:


.. py:function:: require_openai_api_key() -> str

   Return the OpenAI API key from the environment.

   :param None.:

   :returns: The resolved API key.
   :rtype: str

   :raises RuntimeError: If the key is not available.


.. py:data:: DEFAULT_MODEL_NAME
   :value: 'gpt-5.1'


.. py:data:: DEFAULT_REASONING_EFFORT
   :value: 'high'