Source code for oas2mcp.agent.summarizer.models

"""Structured output models for the catalog summarizer agent.

Purpose:
    Define agent-facing structured output models for summarizing an API catalog
    as a whole before introducing per-operation enhancement agents.

Design:
    - Use concise, typed structures that an agent can reliably fill.
    - Emphasize purpose, conceptual structure, domains, and data model before
      operational concerns like authentication or MCP surface design.
    - Keep these models specific to the summarizer workflow.

Examples:
    .. code-block:: python

        summary = CatalogSummary(
            catalog_name="Petstore",
            api_purpose="Manage pets, store orders, and users.",
            conceptual_overview="A demo REST API organized around pets, store operations, and users.",
            data_model_summary="The core schemas are Pet, User, Order, and ApiResponse.",
            data_flow_summary="The API supports both reads and mutations across core domains.",
            authentication_summary="OAuth2 and API key auth are present.",
            recommended_mcp_surface="Mostly tools with a few read-oriented resources.",
        )
"""

from __future__ import annotations

from pydantic import Field

from oas2mcp.models.normalized import NormalizedBaseModel



[docs]
class CatalogTagSummary(NormalizedBaseModel):
    """Structured summary for one API tag or domain.

    Args:
        None.

    Returns:
        None.

    Raises:
        None.

    Examples:
        .. code-block:: python

            tag_summary = CatalogTagSummary(
                tag_name="pet",
                description="Operations for pet records and media.",
                operation_count=8,
            )
    """


[docs]
    tag_name: str


[docs]
    description: str


[docs]
    operation_count: int = 0


[docs]
    read_operation_count: int = 0


[docs]
    mutating_operation_count: int = 0


[docs]
    notable_operations: list[str] = Field(default_factory=list)





[docs]
class CatalogSummary(NormalizedBaseModel):
    """Structured overall summary of a normalized API catalog.

    Args:
        None.

    Returns:
        None.

    Raises:
        None.

    Examples:
        .. code-block:: python

            summary = CatalogSummary(
                catalog_name="Petstore",
                api_purpose="Manage pets, orders, and users.",
                conceptual_overview="A demo REST API organized around three domains.",
                data_model_summary="The main schemas are Pet, User, Order, and ApiResponse.",
                data_flow_summary="Supports both reads and mutations across core domains.",
                authentication_summary="OAuth2 and API key auth are present.",
                recommended_mcp_surface="Use tools for actions and selected resources for reads.",
            )
    """


[docs]
    catalog_name: str


[docs]
    api_purpose: str


[docs]
    conceptual_overview: str


[docs]
    primary_domains: list[CatalogTagSummary] = Field(default_factory=list)


[docs]
    data_model_summary: str


[docs]
    data_flow_summary: str



[docs]
    authentication_summary: str


[docs]
    operational_notes: list[str] = Field(default_factory=list)



[docs]
    recommended_mcp_surface: str


[docs]
    suggested_tool_domains: list[str] = Field(default_factory=list)


[docs]
    suggested_resource_domains: list[str] = Field(default_factory=list)



[docs]
    notes: list[str] = Field(default_factory=list)