oas2mcp.agent.enhancer.models
=============================

.. py:module:: oas2mcp.agent.enhancer.models

.. autoapi-nested-parse::

   Structured models for the operation enhancer agent.

   Purpose:
       Define deterministic input and structured output models for refining one
       normalized API operation into a more MCP-friendly representation.

   Design:
       - Keep these models specific to the enhancer workflow.
       - Separate deterministic context objects from LLM-produced enhancement
         outputs.
       - Treat deterministic MCP classification data as hints rather than final
         truth.
       - Preserve enough detail for naming, auth, confirmation, and later export.

   .. rubric:: Examples

   .. code-block:: python

       enhancement = OperationEnhancement(
           operation_key="POST /pet",
           operation_slug="addpet",
           final_kind="tool",
           title="Create pet",
           description="Create a new pet record.",
           requires_confirmation=False,
       )



Classes
-------

.. autoapisummary::

   oas2mcp.agent.enhancer.models.EnhancementPromptCandidate
   oas2mcp.agent.enhancer.models.OperationEnhancement
   oas2mcp.agent.enhancer.models.OperationEnhancementContext
   oas2mcp.agent.enhancer.models.ResolvedSchemaContext
   oas2mcp.agent.enhancer.models.SecuritySchemeContext


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

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

   Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel`


   Suggested prompt template for an enhanced operation.

   :param None.:

   :returns: None.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       prompt = EnhancementPromptCandidate(
           name="create-pet",
           title="Create pet",
           description="Create a new pet safely.",
       )


   .. py:attribute:: arguments
      :type:  list[str]
      :value: None



   .. py:attribute:: description
      :type:  str


   .. py:attribute:: meta
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: tags
      :type:  list[str]
      :value: None



   .. py:attribute:: template
      :type:  str | None
      :value: None



   .. py:attribute:: title
      :type:  str


   .. py:attribute:: version
      :type:  str | None
      :value: None



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

   Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel`


   Structured enhancement result for one operation.

   :param None.:

   :returns: None.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       enhancement = OperationEnhancement(
           operation_key="POST /pet",
           operation_slug="addpet",
           final_kind="tool",
           title="Create pet",
           description="Create a new pet record.",
       )


   .. py:attribute:: auth_notes
      :type:  str | None
      :value: None



   .. py:attribute:: component_annotations
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: component_meta
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: component_name
      :type:  str | None
      :value: None



   .. py:attribute:: component_tags
      :type:  list[str]
      :value: None



   .. py:attribute:: component_version
      :type:  str | None
      :value: None



   .. py:attribute:: description
      :type:  str


   .. py:attribute:: final_kind
      :type:  oas2mcp.models.mcp.McpCandidateKind


   .. py:attribute:: namespace
      :type:  str | None
      :value: None



   .. py:attribute:: notes
      :type:  list[str]
      :value: None



   .. py:attribute:: operation_id
      :type:  str | None
      :value: None



   .. py:attribute:: operation_key
      :type:  str


   .. py:attribute:: operation_slug
      :type:  str


   .. py:attribute:: prompt_templates
      :type:  list[EnhancementPromptCandidate]
      :value: None



   .. py:attribute:: requires_confirmation
      :type:  bool
      :value: False



   .. py:attribute:: resource_uri
      :type:  str | None
      :value: None



   .. py:attribute:: title
      :type:  str


   .. py:attribute:: tool_name
      :type:  str | None
      :value: None



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

   Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel`


   Deterministic agent-facing context for one operation.

   :param None.:

   :returns: None.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       context = OperationEnhancementContext(
           catalog_name="Petstore",
           catalog_slug="petstore",
           source_uri="https://example.com/openapi.json",
           catalog_summary_purpose="Manage pets and orders.",
           catalog_domains=["pet", "store", "user"],
           operation_key="POST /pet",
           operation_slug="addpet",
           method="POST",
           path="/pet",
           candidate_kind_hint="tool",
       )


   .. py:attribute:: candidate_kind_hint
      :type:  str


   .. py:attribute:: candidate_prompt_templates
      :type:  list[EnhancementPromptCandidate]
      :value: None



   .. py:attribute:: candidate_requires_confirmation_hint
      :type:  bool
      :value: False



   .. py:attribute:: candidate_resource_uri_hint
      :type:  str | None
      :value: None



   .. py:attribute:: candidate_tool_name_hint
      :type:  str | None
      :value: None



   .. py:attribute:: catalog_domains
      :type:  list[str]
      :value: None



   .. py:attribute:: catalog_name
      :type:  str


   .. py:attribute:: catalog_slug
      :type:  str


   .. py:attribute:: catalog_summary_purpose
      :type:  str


   .. py:attribute:: description
      :type:  str | None
      :value: None



   .. py:attribute:: method
      :type:  str


   .. py:attribute:: operation_id
      :type:  str | None
      :value: None



   .. py:attribute:: operation_key
      :type:  str


   .. py:attribute:: operation_slug
      :type:  str


   .. py:attribute:: path
      :type:  str


   .. py:attribute:: path_parameter_names
      :type:  list[str]
      :value: None



   .. py:attribute:: query_parameter_names
      :type:  list[str]
      :value: None



   .. py:attribute:: request_schema_refs
      :type:  list[str]
      :value: None



   .. py:attribute:: resolved_schemas
      :type:  list[ResolvedSchemaContext]
      :value: None



   .. py:attribute:: response_schema_refs
      :type:  list[str]
      :value: None



   .. py:attribute:: security_schemes
      :type:  list[SecuritySchemeContext]
      :value: None



   .. py:attribute:: server_urls
      :type:  list[str]
      :value: None



   .. py:attribute:: source_uri
      :type:  str


   .. py:attribute:: summary
      :type:  str | None
      :value: None



   .. py:attribute:: tags
      :type:  list[str]
      :value: None



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

   Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel`


   Resolved schema context for one schema reference.

   :param None.:

   :returns: None.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       schema_context = ResolvedSchemaContext(
           schema_ref="#/components/schemas/Pet",
           schema_object={"type": "object"},
       )


   .. py:attribute:: schema_object
      :type:  dict
      :value: None



   .. py:attribute:: schema_ref
      :type:  str


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

   Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel`


   Compact security scheme details used by the enhancer.

   :param None.:

   :returns: None.

   :raises None.:

   .. rubric:: Examples

   .. code-block:: python

       scheme = SecuritySchemeContext(
           name="petstore_auth",
           type="oauth2",
           flow_names=["implicit"],
       )


   .. py:attribute:: bearer_format
      :type:  str | None
      :value: None



   .. py:attribute:: flow_names
      :type:  list[str]
      :value: None



   .. py:attribute:: location
      :type:  str | None
      :value: None



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: parameter_name
      :type:  str | None
      :value: None



   .. py:attribute:: scheme
      :type:  str | None
      :value: None



   .. py:attribute:: type
      :type:  str