Source code for oas2mcp.agent.surface.models

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

from __future__ import annotations

from typing import Any, Literal

from pydantic import Field

from oas2mcp.models.mcp import McpCandidateKind
from oas2mcp.models.normalized import NormalizedBaseModel



[docs]
class CatalogSurfacePromptPlan(NormalizedBaseModel):
    """Catalog-level prompt definition proposed by the surface planner."""


[docs]
    name: str


[docs]
    title: str


[docs]
    description: str


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


[docs]
    template: str


[docs]
    version: str | None = None


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


[docs]
    meta: dict[str, Any] = Field(default_factory=dict)





[docs]
class CatalogSurfaceResourcePlan(NormalizedBaseModel):
    """Catalog-level resource definition proposed by the surface planner."""


[docs]
    kind: Literal["resource", "resource_template"]


[docs]
    uri: str


[docs]
    name: str


[docs]
    title: str


[docs]
    description: str


[docs]
    mime_type: str = "application/json"


[docs]
    handler: Literal["static", "operation_metadata", "namespace_operations"] = "static"


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


[docs]
    payload: Any | None = None


[docs]
    version: str | None = None


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


[docs]
    meta: dict[str, Any] = Field(default_factory=dict)


[docs]
    annotations: dict[str, Any] = Field(default_factory=dict)





[docs]
class CatalogSurfaceOperationContext(NormalizedBaseModel):
    """Compact operation summary used by the catalog surface planner."""


[docs]
    operation_slug: str


[docs]
    operation_id: str | None = None


[docs]
    final_kind: McpCandidateKind


[docs]
    namespace: str | None = None


[docs]
    title: str


[docs]
    description: str


[docs]
    tool_name: str | None = None


[docs]
    resource_uri: str | None = None


[docs]
    requires_confirmation: bool = False


[docs]
    auth_notes: str | None = None


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





[docs]
class CatalogSurfacePlanningContext(NormalizedBaseModel):
    """Deterministic context passed into the catalog surface planner agent."""


[docs]
    catalog_name: str


[docs]
    catalog_slug: str


[docs]
    catalog_version: str | None = None


[docs]
    source_uri: str



[docs]
    api_purpose: str


[docs]
    conceptual_overview: str


[docs]
    authentication_summary: str


[docs]
    recommended_mcp_surface: str


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


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


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


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



[docs]
    operations: list[CatalogSurfaceOperationContext] = Field(default_factory=list)



[docs]
    default_server_instructions: str


[docs]
    default_catalog_prompts: list[CatalogSurfacePromptPlan] = Field(
        default_factory=list
    )


[docs]
    default_catalog_resources: list[CatalogSurfaceResourcePlan] = Field(
        default_factory=list
    )





[docs]
class CatalogSurfacePlan(NormalizedBaseModel):
    """Structured catalog-level surface plan produced by the planner agent."""


[docs]
    server_instructions: str


[docs]
    catalog_prompts: list[CatalogSurfacePromptPlan] = Field(default_factory=list)


[docs]
    catalog_resources: list[CatalogSurfaceResourcePlan] = Field(default_factory=list)


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