oas2mcp.agent.summarizer.context ================================ .. py:module:: oas2mcp.agent.summarizer.context .. autoapi-nested-parse:: Deterministic context builders for the catalog summarizer agent. Purpose: Build compact, structured context objects for the catalog-level summarizer agent using normalized catalogs and optional MCP candidate bundles. Design: - Keep context building deterministic and side-effect free. - Emphasize the API's purpose, conceptual structure, domains, data model, and request/response patterns. - Preserve lightweight operational and MCP-oriented signals without letting them dominate the summarizer's input. - Support summarization with or without a classified MCP bundle. .. rubric:: Examples .. code-block:: python context = build_catalog_summary_context(catalog, bundle=bundle) print(context.catalog_name) print(context.primary_schema_refs[0].schema_ref) Classes ------- .. autoapisummary:: oas2mcp.agent.summarizer.context.CandidateExample oas2mcp.agent.summarizer.context.CatalogSecuritySchemeContext oas2mcp.agent.summarizer.context.CatalogSummaryContext oas2mcp.agent.summarizer.context.CatalogTagContext oas2mcp.agent.summarizer.context.SchemaRefSummary Functions --------- .. autoapisummary:: oas2mcp.agent.summarizer.context.build_catalog_summary_context Module Contents --------------- .. py:class:: CandidateExample(/, **data: Any) Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel` Compact MCP candidate example for summarizer input. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python candidate = CandidateExample( operation_key="GET /pets/{id}", operation_slug="get-pet-by-id", kind="resource", title="Get pet by ID", safety_level="safe_read", ) .. py:attribute:: kind :type: str .. py:attribute:: operation_key :type: str .. py:attribute:: operation_slug :type: str .. py:attribute:: resource_uri :type: str | None :value: None .. py:attribute:: safety_level :type: str .. py:attribute:: title :type: str .. py:attribute:: tool_name :type: str | None :value: None .. py:class:: CatalogSecuritySchemeContext(/, **data: Any) Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel` Compact security scheme context for summarizer input. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python scheme = CatalogSecuritySchemeContext( name="api_key", type="apiKey", location="header", parameter_name="X-API-Key", ) .. 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 .. py:class:: CatalogSummaryContext(/, **data: Any) Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel` Compact agent-facing context for catalog-level summarization. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python context = CatalogSummaryContext( catalog_name="Petstore", catalog_slug="petstore", source_uri="https://example.com/openapi.json", ) .. py:attribute:: candidate_count :type: int :value: 0 .. py:attribute:: candidate_kind_counts :type: dict[str, int] :value: None .. py:attribute:: candidate_safety_counts :type: dict[str, int] :value: None .. py:attribute:: catalog_name :type: str .. py:attribute:: catalog_slug :type: str .. py:attribute:: component_counts :type: dict[str, int] :value: None .. py:attribute:: deprecated_operation_count :type: int :value: 0 .. py:attribute:: destructive_operation_count :type: int :value: 0 .. py:attribute:: info_description :type: str | None :value: None .. py:attribute:: info_summary :type: str | None :value: None .. py:attribute:: info_title :type: str | None :value: None .. py:attribute:: info_version :type: str | None :value: None .. py:attribute:: mutating_operation_count :type: int :value: 0 .. py:attribute:: notable_mutating_operations :type: list[str] :value: None .. py:attribute:: notable_operations :type: list[str] :value: None .. py:attribute:: notable_read_operations :type: list[str] :value: None .. py:attribute:: openapi_version :type: str | None :value: None .. py:attribute:: operation_count :type: int :value: 0 .. py:attribute:: primary_schema_refs :type: list[SchemaRefSummary] :value: None .. py:attribute:: read_operation_count :type: int :value: 0 .. py:attribute:: request_schema_refs :type: list[SchemaRefSummary] :value: None .. py:attribute:: response_schema_refs :type: list[SchemaRefSummary] :value: None .. py:attribute:: sample_resource_candidates :type: list[CandidateExample] :value: None .. py:attribute:: sample_tool_candidates :type: list[CandidateExample] :value: None .. py:attribute:: security_schemes :type: list[CatalogSecuritySchemeContext] :value: None .. py:attribute:: server_urls :type: list[str] :value: None .. py:attribute:: source_uri :type: str .. py:attribute:: tag_summaries :type: list[CatalogTagContext] :value: None .. py:class:: CatalogTagContext(/, **data: Any) Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel` Deterministic tag/domain context for summarizer input. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python tag_context = CatalogTagContext( tag_name="pet", description="Everything about your Pets", operation_count=8, ) .. py:attribute:: description :type: str .. py:attribute:: mutating_operation_count :type: int :value: 0 .. py:attribute:: notable_operations :type: list[str] :value: None .. py:attribute:: operation_count :type: int :value: 0 .. py:attribute:: operation_ids :type: list[str] :value: None .. py:attribute:: operation_keys :type: list[str] :value: None .. py:attribute:: read_operation_count :type: int :value: 0 .. py:attribute:: tag_name :type: str .. py:class:: SchemaRefSummary(/, **data: Any) Bases: :py:obj:`oas2mcp.models.normalized.NormalizedBaseModel` Compact rollup for frequently referenced schema refs. :param None.: :returns: None. :raises None.: .. rubric:: Examples .. code-block:: python summary = SchemaRefSummary( schema_ref="#/components/schemas/Pet", count=4, ) .. py:attribute:: count :type: int .. py:attribute:: schema_ref :type: str .. py:function:: build_catalog_summary_context(catalog: oas2mcp.models.normalized.ApiCatalog, bundle: oas2mcp.models.mcp.McpBundle | None = None) -> CatalogSummaryContext Build deterministic summarizer context for an API catalog. :param catalog: The normalized API catalog. :param bundle: Optional MCP bundle produced by deterministic classification. :returns: A compact ``CatalogSummaryContext`` suitable for a summarizer agent. :raises None.: .. rubric:: Examples .. code-block:: python context = build_catalog_summary_context(catalog, bundle=bundle)