1  """
 2  Custom type aliases for the A2A helper layer.
 3  """
 4  
 5  from typing import Union, Optional, Dict, Any, List
 6  from a2a.types import TextPart, DataPart, FilePart, AgentSkill
 7  from pydantic import BaseModel, Field, ConfigDict, field_validator
 8  
 9  # A type alias for the raw content parts of a message or artifact.
10  # This is the type that application logic should work with, insulating it
11  # from the SDK's generic `Part` wrapper.
12  ContentPart = Union[TextPart, DataPart, FilePart]
13  
14  
15  class SamAgentSkill(AgentSkill):
16      """
17      SAM extension of AgentSkill that includes required_scopes for access control.
18      """
19  
20      required_scopes: List[str] = Field(default_factory=list)
21  
22  
23  class ToolsExtensionParams(BaseModel):
24      """
25      The parameters for the custom 'tools' AgentCard extension.
26      """
27  
28      tools: list[SamAgentSkill]
29  
30  
31  class SchemasExtensionParams(BaseModel):
32      """
33      The parameters for the custom 'schemas' AgentCard extension.
34      """
35  
36      input_schema: Optional[Dict[str, Any]] = None
37      output_schema: Optional[Dict[str, Any]] = None
38  
39  
40  class ArtifactInfo(BaseModel):
41      """
42      Represents information about an artifact, typically for listing or display.
43      Mirrors the frontend ArtifactInfo type and the model used in artifact_helpers.py.
44      """
45  
46      filename: str
47      mime_type: Optional[str] = None
48      size: int
49      last_modified: Optional[str] = None
50      description: Optional[str] = None
51      schema_definition: Optional[Dict[str, Any]] = Field(default=None, alias="schema")
52      uri: Optional[str] = None
53      version: Optional[Union[int, str]] = None
54      version_count: Optional[int] = None
55      source: Optional[str] = None  # Optional: Source of the artifact (e.g., "project")
56      tags: Optional[List[str]] = None  # Optional: Tags for categorization (e.g., ["__working"])
57      source_project_id: Optional[str] = None  # Optional: ID of the project this artifact came from
58  
59      model_config = ConfigDict(populate_by_name=True)
60  
61      @field_validator("version")
62      @classmethod
63      def validate_version_string(cls, v: Union[int, str]) -> Union[int, str]:
64          if isinstance(v, str):
65              if v.lower() == "latest":
66                  return v
67              try:
68                  int(v)
69                  return v
70              except ValueError as exc:
71                  raise ValueError(
72                      f"String version must be 'latest' or a valid integer representation. Got: '{v}'"
73                  ) from exc
74          return v