oas2mcp.agent.surface.models
============================

.. py:module:: oas2mcp.agent.surface.models

.. autoapi-nested-parse::

   Structured models for the catalog surface planner agent.

   Purpose:
       Define the deterministic input and structured output models used by the
       catalog-level surface planner. This workflow refines shared FastMCP-facing
       server instructions, prompts, and resources after per-operation enhancement.

   Design:
       - Keep these models specific to catalog-level surface planning.
       - Separate deterministic planning context from LLM-produced surface output.
       - Preserve a stable, inspectable shape for later export and bootstrapping.
       - Constrain resource planning to handlers supported by the runtime layer.



Classes
-------

.. autoapisummary::

   oas2mcp.agent.surface.models.CatalogSurfaceOperationContext
   oas2mcp.agent.surface.models.CatalogSurfacePlan
   oas2mcp.agent.surface.models.CatalogSurfacePlanningContext
   oas2mcp.agent.surface.models.CatalogSurfacePromptPlan
   oas2mcp.agent.surface.models.CatalogSurfaceResourcePlan


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

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

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


   Compact operation summary used by the catalog surface planner.


   .. py:attribute:: auth_notes
      :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:: operation_id
      :type:  str | None
      :value: None



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


   .. py:attribute:: prompt_template_names
      :type:  list[str]
      :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:: CatalogSurfacePlan(/, **data: Any)

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


   Structured catalog-level surface plan produced by the planner agent.


   .. py:attribute:: catalog_prompts
      :type:  list[CatalogSurfacePromptPlan]
      :value: None



   .. py:attribute:: catalog_resources
      :type:  list[CatalogSurfaceResourcePlan]
      :value: None



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



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


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

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


   Deterministic context passed into the catalog surface planner agent.


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


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


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


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



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


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



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


   .. py:attribute:: default_catalog_prompts
      :type:  list[CatalogSurfacePromptPlan]
      :value: None



   .. py:attribute:: default_catalog_resources
      :type:  list[CatalogSurfaceResourcePlan]
      :value: None



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


   .. py:attribute:: operations
      :type:  list[CatalogSurfaceOperationContext]
      :value: None



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



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


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


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



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



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

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


   Catalog-level prompt definition proposed by the surface planner.


   .. 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


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


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



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

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


   Catalog-level resource definition proposed by the surface planner.


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



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



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


   .. py:attribute:: handler
      :type:  Literal['static', 'operation_metadata', 'namespace_operations']
      :value: 'static'



   .. py:attribute:: kind
      :type:  Literal['resource', 'resource_template']


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



   .. py:attribute:: mime_type
      :type:  str
      :value: 'application/json'



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


   .. py:attribute:: payload
      :type:  Any | None
      :value: None



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



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


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


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