anthropic-a2ui 0.1.0__py3-none-any.whl

anthropic_a2ui/__init__.py

@@ -0,0 +1,83 @@
+"""anthropic-a2ui: integración de A2UI con el SDK de Anthropic.
+
+Paquete que compone ``a2ui-agent-sdk`` con ``anthropic`` para que Claude
+genere respuestas conformes al protocolo A2UI. No envuelve el SDK de
+Anthropic: se usa ``anthropic`` directamente y se plugan las piezas de A2UI.
+
+API pública:
+
+- ``ClaudeA2uiPromptBuilder``: genera el system prompt con esquema + ejemplos.
+- ``create_a2ui_tool``: define la tool ``send_a2ui_json_to_client``.
+- ``ClaudeStreamParser``: parsea el stream de Anthropic y emite
+  ``ResponsePart`` de A2UI.
+- ``to_a2ui_part``, ``A2uiPart``, ``MIME_A2UI``: helpers de transporte.
+- ``SUPPORTED_VERSIONS``, ``DEFAULT_VERSION``: constantes del protocolo.
+"""
+
+from __future__ import annotations
+
+from .parts import A2uiPart, MIME_A2UI, parse_a2ui_part_json, to_a2a_datapart, to_a2ui_part
+from .prompt_builder import (
+    DEFAULT_VERSION,
+    SUPPORTED_VERSIONS,
+    ClaudeA2uiPromptBuilder,
+)
+from .repair import (
+    find_orphans,
+    patch_catalog_schema,
+    repair_childlists,
+    repair_functions,
+    repair_icons,
+    repair_orphans,
+)
+from .retry import (
+    A2uiConversation,
+    A2uiConversationAsync,
+    ConversationTurn,
+    RetryResult,
+    create_a2ui_response_format,
+    generate_a2ui,
+    generate_a2ui_async,
+    parse_json_response,
+)
+from .stream_parser import ClaudeStreamParser
+from .tool import (
+    TOOL_DESCRIPTION,
+    TOOL_NAME,
+    create_a2ui_tool,
+    make_parser_for_tool,
+    validate_tool_input,
+)
+from .version import __version__
+
+__all__ = [
+    "A2uiConversation",
+    "A2uiConversationAsync",
+    "A2uiPart",
+    "ConversationTurn",
+    "MIME_A2UI",
+    "RetryResult",
+    "SUPPORTED_VERSIONS",
+    "DEFAULT_VERSION",
+    "TOOL_NAME",
+    "TOOL_DESCRIPTION",
+    "ClaudeA2uiPromptBuilder",
+    "ClaudeStreamParser",
+    "create_a2ui_response_format",
+    "create_a2ui_tool",
+    "find_orphans",
+    "generate_a2ui",
+    "generate_a2ui_async",
+    "make_parser_for_tool",
+    "parse_a2ui_part_json",
+    "parse_json_response",
+    "patch_catalog_schema",
+    "repair_childlists",
+    "repair_functions",
+    "repair_icons",
+    "repair_orphans",
+    "to_a2a_datapart",
+    "to_a2ui_part",
+    "validate_tool_input",
+    "__version__",
+]

anthropic_a2ui/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Internos de anthropic-a2ui.
+
+Reservado para compatibilidad futura. La adaptación de tipos de Anthropic
+se hace con ``getattr`` en ``stream_parser.py`` para no acoplarse a versiones
+del SDK.
+"""

anthropic_a2ui/parts.py

@@ -0,0 +1,108 @@
+"""Helpers de transporte para envolver JSON de A2UI en DataParts.
+
+Esta pieza es la menos acoplada a Anthropic: sirve igual si el JSON viene de
+tool use, de tags ``<a2ui-json>`` o de ``response_format``. Produce la
+envoltura estándar que los renderers de A2UI esperan (MIME
+``application/a2ui+json``), compatible con A2A.
+
+El módulo no depende de ``a2a-sdk`` para evitar arrastrar el transporte al
+importar ``anthropic-a2ui``; en su lugar define ``A2uiPart`` como un dataclass
+ligero. Si el caller ya usa ``a2a-sdk`` puede convertirlo fácilmente, y se
+ofrece ``to_a2a_datapart`` que intenta el bridge si ``a2a`` está instalado.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+MIME_A2UI = "application/a2ui+json"
+
+
+@dataclass(frozen=True, slots=True)
+class A2uiPart:
+  """Envoltura estándar de un mensaje A2UI para transporte.
+
+  Attributes:
+    mime: Tipo MIME bajo el que se etiqueta el payload. El protocolo A2UI
+      define ``application/a2ui+json`` como estándar para los DataParts.
+    data: El JSON A2UI ya parseado (lista de mensajes o mensaje único). Se
+      conserva como objeto para que el receptor lo use directamente; si hace
+      falta serializar, usar ``part.to_json_string()``.
+  """
+
+  mime: str = MIME_A2UI
+  data: Any = field(default=None)
+
+  def to_json_string(self, **kwargs: Any) -> str:
+    """Serializa ``data`` a cadena JSON compacta.
+
+    Args:
+      **kwargs: Argumentos extra para ``json.dumps`` (por ejemplo
+        ``indent=2`` para pretty-print).
+    """
+    kwargs.setdefault("ensure_ascii", False)
+    return json.dumps(self.data, **kwargs)
+
+  def to_dict(self) -> dict[str, Any]:
+    """Convierte el part a un dict plano apto para serialización genérica.
+
+    Útil para enviar por JSON-RPC, SSE o cualquier canal que no sea A2A.
+    """
+    return {"mimeType": self.mime, "data": self.data}
+
+
+def to_a2ui_part(payload: Any, *, mime: str = MIME_A2UI) -> A2uiPart:
+  """Envuelve un payload A2UI (dict o lista) en un ``A2uiPart``.
+
+  Args:
+    payload: El JSON A2UI ya parseado. Puede ser un único mensaje (dict) o
+      una lista de mensajes; el protocolo admite ambos.
+    mime: Tipo MIME a usar. Por defecto el estándar del protocolo.
+
+  Returns:
+    Un ``A2uiPart`` listo para entregar al renderer o al transporte.
+  """
+  return A2uiPart(mime=mime, data=payload)
+
+
+def to_a2a_datapart(part: A2uiPart) -> Any:
+  """Intenta convertir un ``A2uiPart`` a ``a2a.types.DataPart``.
+
+  Esta función es opcional y solo funciona si ``a2a-sdk`` está instalado. Si
+  no lo está, devuelve el dict plano (``part.to_dict()``) para que el caller
+  lo envuelva como prefiera.
+
+  Returns:
+    Un ``DataPart`` de ``a2a`` si está disponible, o un dict con
+    ``{"mimeType": ..., "data": ...}`` si no.
+  """
+  try:
+    from a2a.types import DataPart  # type: ignore
+  except Exception:
+    return part.to_dict()
+  dp = DataPart(**part.to_dict())  # type: ignore[call-arg]
+  return dp
+
+
+def parse_a2ui_part_json(raw: str | bytes) -> Any:
+  """Parsea una cadena JSON de A2UI y devuelve el objeto.
+
+  Es un atajo sobre ``json.loads`` que acepta ``str`` o ``bytes`` y que lanza
+  ``ValueError`` (en vez de ``json.JSONDecodeError``) para que el caller pueda
+  capturar de forma agnóstica al framework de serialización.
+
+  Args:
+    raw: Cadena o bytes con JSON A2UI.
+
+  Returns:
+    El objeto parseado (dict o lista).
+
+  Raises:
+    ValueError: Si el contenido no es JSON válido.
+  """
+  try:
+    return json.loads(raw)
+  except json.JSONDecodeError as exc:
+    raise ValueError(f"JSON A2UI inválido: {exc}") from exc

anthropic_a2ui/prompt_builder.py

@@ -0,0 +1,198 @@
+"""Generación del system prompt para que Claude emita respuestas A2UI.
+
+Esta pieza delega en ``A2uiSchemaManager`` de ``a2ui-agent-sdk`` para montar
+el esquema del catálogo y los ejemplos few-shot, y expone una API pensada
+para el flujo de Anthropic: construir el prompt, pasar a ``system`` de
+``client.messages.stream(...)``, y opcionalmente podar componentes para
+ahorrar tokens.
+
+El paquete no redefine el formato del prompt; el ``A2uiSchemaManager`` es la
+fuente canónica del protocolo. Aquí solo se adapta el punto de entrada y se
+ofrece conveniencia (defaults razonables, validación de versiones soportadas).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from a2ui.basic_catalog.provider import BasicCatalog
+from a2ui.schema.catalog import CatalogConfig
+from a2ui.schema.manager import A2uiSchemaManager
+
+# Versiones de protocolo que a2ui-agent-sdk 0.2.x soporta. Se mantiene aquí
+# para dar errores claros antes de llegar al A2uiSchemaManager (que lanza un
+# ValueError genérico).
+SUPPORTED_VERSIONS = ("0.8", "0.9", "0.9.1")
+DEFAULT_VERSION = "0.9"
+
+
+class ClaudeA2uiPromptBuilder:
+  """Construye el system prompt para que Claude genere respuestas A2UI.
+
+  Envuelve a ``A2uiSchemaManager`` con defaults orientados a Anthropic: el
+  rol del asistente, descripción del flujo y activación de esquema +
+  ejemplos. Permite reutilizar una instancia para varias llamamas y podar el
+  catálogo a un subconjunto de componentes para reducir tokens.
+
+  Attributes:
+    version: Versión del protocolo A2UI (``"0.9"`` por defecto).
+    catalogs: Lista de ``CatalogConfig`` activos.
+    manager: El ``A2uiSchemaManager`` subyacente, expuesto para uso avanzado.
+
+  Example:
+    ```python
+    builder = ClaudeA2uiPromptBuilder()
+    system = builder.build(role_description="Construye formularios de contacto.")
+    # system -> string listo para pasar a client.messages.stream(system=system)
+    ```
+  """
+
+  def __init__(
+      self,
+      catalogs: Optional[list[CatalogConfig]] = None,
+      version: str = DEFAULT_VERSION,
+      accepts_inline_catalogs: bool = False,
+      schema_modifiers: Optional[
+          list[Callable[[dict[str, Any]], dict[str, Any]]]
+      ] = None,
+  ) -> None:
+    """Inicializa el builder.
+
+    Args:
+      catalogs: Catálogos de componentes. Si es ``None`` se usa el
+        ``BasicCatalog`` (Button, Text, TextField, etc.) bundled en
+        ``a2ui-agent-sdk``.
+      version: Versión del protocolo. Debe ser una de
+        ``SUPPORTED_VERSIONS``.
+      accepts_inline_catalogs: Si el cliente acepta catálogos inline.
+      schema_modifiers: Funciones para modificar el esquema antes de
+        inyectarlo en el prompt (caso avanzado).
+
+    Raises:
+      ValueError: Si ``version`` no está en ``SUPPORTED_VERSIONS``.
+    """
+    if version not in SUPPORTED_VERSIONS:
+      raise ValueError(
+          f"Versión no soportada: {version!r}. Versiones válidas: {SUPPORTED_VERSIONS}"
+      )
+    self.version = version
+    if catalogs is None:
+      catalogs = [BasicCatalog.get_config(version=version)]
+    self.catalogs = list(catalogs)
+    self.manager = A2uiSchemaManager(
+        version=version,
+        catalogs=self.catalogs,
+        accepts_inline_catalogs=accepts_inline_catalogs,
+        schema_modifiers=schema_modifiers,
+    )
+
+  def build(
+      self,
+      role_description: str,
+      workflow_description: str = "",
+      ui_description: str = "",
+      allowed_components: Optional[list[str]] = None,
+      allowed_messages: Optional[list[str]] = None,
+      include_schema: bool = True,
+      include_examples: bool = True,
+      validate_examples: bool = False,
+      include_icon_list: bool = True,
+      include_function_list: bool = True,
+  ) -> str:
+    """Genera el system prompt listo para pasar a Anthropic.
+
+    Args:
+      role_description: Descripcion del rol del agente (inyecta al inicio).
+      workflow_description: Descripcion del flujo de trabajo (opcional).
+      ui_description: Descripcion extra de la UI (opcional).
+      allowed_components: Subconjunto de nombres de componentes que el
+        agente puede usar. Si es ``None``, todos los del catalogo.
+      allowed_messages: Subconjunto de tipos de mensaje.
+      include_schema: Si incluir el JSON Schema en el prompt.
+      include_examples: Si incluir ejemplos few-shot.
+      validate_examples: Si validar los ejemplos contra el esquema.
+      include_icon_list: Si anadir la lista de iconos validos al final del
+        prompt. Evita que Claude invente nombres de iconos no permitidos.
+        Por defecto ``True``.
+
+    Returns:
+      Cadena con el system prompt completo.
+    """
+    prompt = self.manager.generate_system_prompt(
+        role_description=role_description,
+        workflow_description=workflow_description,
+        ui_description=ui_description,
+        client_ui_capabilities=None,
+        allowed_components=allowed_components,
+        allowed_messages=allowed_messages,
+        include_schema=include_schema,
+        include_examples=include_examples,
+        validate_examples=validate_examples,
+    )
+    if include_icon_list:
+      icons = _extract_valid_icons(self.get_catalog())
+      if icons:
+        prompt += (
+            "\n\n--- ICONOS VALIDOS ---\n"
+            "El componente Icon solo acepta estos nombres (no inventes "
+            "otros):\n"
+            + ", ".join(icons)
+            + "\n"
+        )
+    if include_function_list:
+      functions = _extract_valid_functions(self.get_catalog())
+      if functions:
+        prompt += (
+            "\n\n--- FUNCIONES VALIDAS ---\n"
+            "Las unicas funciones que puedes usar en FunctionCall son estas "
+            "(no inventes otras como ternary, if, switch, etc.):\n"
+            + ", ".join(functions)
+            + "\n"
+        )
+    return prompt
+
+  def get_catalog(self) -> Any:
+    """Devuelve el ``A2uiCatalog`` seleccionado (con poda aplicada si la hubo).
+
+    Expuesto para que el caller pueda obtener un validador o podar el
+    catálogo de forma independiente al prompt.
+    """
+    return self.manager.get_selected_catalog()
+
+  def get_validator(self) -> Any:
+    """Atajo para obtener el ``A2uiValidator`` del catalogo seleccionado."""
+    return self.get_catalog().validator
+
+
+def _extract_valid_icons(catalog: Any) -> list[str]:
+  """Extrae la lista de iconos validos del catalogo.
+
+  Recorre el schema del componente ``Icon`` y devuelve los valores del
+  ``enum`` en su propiedad ``name``.
+  """
+  components = catalog.catalog_schema.get("components", {})
+  icon_def = components.get("Icon")
+  if not icon_def:
+    return []
+  for sub in icon_def.get("allOf", []):
+    if "properties" not in sub:
+      continue
+    name_prop = sub["properties"].get("name")
+    if not name_prop:
+      continue
+    for branch in name_prop.get("oneOf", []):
+      if "enum" in branch:
+        return branch["enum"]
+    if "enum" in name_prop:
+      return name_prop["enum"]
+  return []
+
+
+def _extract_valid_functions(catalog: Any) -> list[str]:
+  """Extrae la lista de funciones validas del catalogo.
+
+  Devuelve los nombres de las funciones definidas en el catalogo, que son
+  las unicas que se pueden usar en ``FunctionCall``.
+  """
+  functions = catalog.catalog_schema.get("functions", {})
+  return list(functions.keys())