Source code for oas2mcp.agent.enhancer.models
"""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.
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,
)
"""
from __future__ import annotations
from typing import Any
from pydantic import Field
from oas2mcp.models.mcp import McpCandidateKind
from oas2mcp.models.normalized import NormalizedBaseModel
[docs]
class ResolvedSchemaContext(NormalizedBaseModel):
"""Resolved schema context for one schema reference.
Args:
None.
Returns:
None.
Raises:
None.
Examples:
.. code-block:: python
schema_context = ResolvedSchemaContext(
schema_ref="#/components/schemas/Pet",
schema_object={"type": "object"},
)
"""
[docs]
schema_object: dict = Field(default_factory=dict)
[docs]
class SecuritySchemeContext(NormalizedBaseModel):
"""Compact security scheme details used by the enhancer.
Args:
None.
Returns:
None.
Raises:
None.
Examples:
.. code-block:: python
scheme = SecuritySchemeContext(
name="petstore_auth",
type="oauth2",
flow_names=["implicit"],
)
"""
[docs]
location: str | None = None
[docs]
parameter_name: str | None = None
[docs]
scheme: str | None = None
[docs]
bearer_format: str | None = None
[docs]
flow_names: list[str] = Field(default_factory=list)
[docs]
class EnhancementPromptCandidate(NormalizedBaseModel):
"""Suggested prompt template for an enhanced operation.
Args:
None.
Returns:
None.
Raises:
None.
Examples:
.. code-block:: python
prompt = EnhancementPromptCandidate(
name="create-pet",
title="Create pet",
description="Create a new pet safely.",
)
"""
[docs]
arguments: list[str] = Field(default_factory=list)
[docs]
template: str | None = None
[docs]
version: str | None = None
[docs]
class OperationEnhancementContext(NormalizedBaseModel):
"""Deterministic agent-facing context for one operation.
Args:
None.
Returns:
None.
Raises:
None.
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",
)
"""
[docs]
server_urls: list[str] = Field(default_factory=list)
[docs]
catalog_summary_purpose: str
[docs]
catalog_domains: list[str] = Field(default_factory=list)
[docs]
operation_key: str
[docs]
operation_id: str | None = None
[docs]
operation_slug: str
[docs]
summary: str | None = None
[docs]
description: str | None = None
[docs]
tags: list[str] = Field(default_factory=list)
[docs]
candidate_kind_hint: str
[docs]
candidate_tool_name_hint: str | None = None
[docs]
candidate_resource_uri_hint: str | None = None
[docs]
candidate_requires_confirmation_hint: bool = False
[docs]
candidate_prompt_templates: list[EnhancementPromptCandidate] = Field(
default_factory=list
)
[docs]
request_schema_refs: list[str] = Field(default_factory=list)
[docs]
response_schema_refs: list[str] = Field(default_factory=list)
[docs]
resolved_schemas: list[ResolvedSchemaContext] = Field(default_factory=list)
[docs]
path_parameter_names: list[str] = Field(default_factory=list)
[docs]
query_parameter_names: list[str] = Field(default_factory=list)
[docs]
security_schemes: list[SecuritySchemeContext] = Field(default_factory=list)
[docs]
class OperationEnhancement(NormalizedBaseModel):
"""Structured enhancement result for one operation.
Args:
None.
Returns:
None.
Raises:
None.
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.",
)
"""
[docs]
operation_id: str | None = None
[docs]
final_kind: McpCandidateKind
[docs]
namespace: str | None = None
[docs]
component_name: str | None = None
[docs]
resource_uri: str | None = None
[docs]
component_version: str | None = None
[docs]
component_annotations: dict[str, Any] = Field(default_factory=dict)
[docs]
requires_confirmation: bool = False
[docs]
auth_notes: str | None = None
[docs]
prompt_templates: list[EnhancementPromptCandidate] = Field(default_factory=list)
[docs]
notes: list[str] = Field(default_factory=list)