Edición 1.0.4 · Python 3.14 o posterior

Manual de referencia de Agnara

Consulta cómo se declara, compila y ejecuta una capacidad. Cada entrada explica para qué sirve un nombre público y reúne su firma, parámetros y miembros cuando corresponde.

Esta edición cubre las siete distribuciones publicadas y sus 174 exportaciones, incluidas ocho provisionales de A2A. Cada ficha indica su módulo de importación. En las firmas, * introduce parámetros que se pasan por nombre y / delimita los exclusivamente posicionales.

Contenido

  1. Primera ejecución
  2. Aplicación y capacidades agnara
  3. Inyección de dependencias agnara.di
  4. Ejecución de capacidades agnara.execution
  5. Exposiciones compiladas agnara.exposure
  6. Introspección y publicación agnara.introspection
  7. Confirmación de invocaciones agnara.policy
  8. Esquemas y datos JSON agnara.schema
  9. Adaptador HTTP agnara_http
  10. Adaptador MCP agnara_mcp
  11. Adaptador A2A provisional agnara_a2a
  12. Interfaz de línea de comandos agnara_cli
  13. Telemetría OpenTelemetry agnara_telemetry
  14. Espacio reservado para eventos agnara_events
  15. Índice alfabético
  16. Versión y fuentes

1. Primera ejecución

En un entorno de Python 3.14 o posterior, instala el núcleo. Añade los adaptadores que necesites con la misma versión.

python -m pip install agnara==1.0.4

El ejemplo declara una suma con permiso obligatorio y salida entera. Compila su plan una vez, construye un contexto por llamada y cierra el contenedor al terminar. La identidad se construye localmente para el ejemplo. En un servicio real el host la obtiene de su autenticación.

import asyncio
from agnara import Agnara, Principal
from agnara.di import DIContainer, DIRegistry
from agnara.execution import (
    ExecutionContext, ExecutionPlan, Failure, FailureCode,
    Invocation, Success, invoke_result,
)

async def main():
    app = Agnara("calculator")

    @app.capability(scopes={"calculator:use"}, output=int)
    def add(a: int, b: int) -> int:
        return a + b

    registry = DIRegistry()
    plan = ExecutionPlan.compile(app.compile()["calculator.add"], registry)
    container = DIContainer(registry)
    actor = Principal("demo", scopes={"calculator:use"})

    async def call(a, principal):
        invocation = Invocation(plan.definition.id, {"a": a, "b": 3}, {})
        context = ExecutionContext(invocation, container, principal=principal)
        return await invoke_result(plan, context)

    try:
        ok = await call(2, actor)
        denied = await call(2, Principal("guest"))
        malformed = await call(True, actor)
        assert isinstance(ok, Success) and ok.value == 5
        assert isinstance(denied, Failure) and denied.code is FailureCode.FORBIDDEN
        assert isinstance(malformed, Failure)
        assert malformed.code is FailureCode.INVALID_INPUT
        print(ok.value, denied.code.value, malformed.code.value)
    finally:
        await container.aclose()

asyncio.run(main())

Resultado verificado 5 forbidden invalid_input. La segunda llamada carece del permiso requerido. La tercera aporta un booleano donde el contrato exige un entero.

Para componer HTTP, declara una ruta con Http y los argumentos con Binding. Para MCP, publica la misma capacidad con Mcp.tool y construye el servidor con build_mcp_server.

2. Aplicación y capacidades

agnara · 41 exportaciones

Declara la operación de negocio una vez. La aplicación y sus contextos organizan el registro. Las políticas y los esquemas describen qué puede ejecutarse y qué datos admite cada operación.

Guía relacionada · AGENT_GUIDE.md

Agnara · AgnaraError · AnonymousPrincipal · App · AppDescriptor · CapabilityDefinition · CapabilityId · CapabilityRegistry · Confirmation · ConfirmationEvidence · ConfirmationVerdict · ConfirmationVerifier · DefinitionError · DuplicateAppError · DuplicateCapabilityError · FrozenCapabilityRegistry · Idempotency · InteractionKind · InteractionRequest · InteractionRequiredError · InvocationError · JsonSchema · Policy · PolicyDeniedError · PolicyFailure · PolicyInteractionRequired · PolicyResult · PolicySuccess · Principal · RegistryError · RegistryFrozenError · Risk · SchemaAdapter · SchemaError · ScopePolicy · StandardEffect · StandardSchemaAdapter · TypeSchema · UnknownCapabilityError · ValidationError · __version__

Agnara

Clase · Estable · agnara

Punto de entrada de una aplicación. Registra capacidades propias, monta contextos con include() y congela la colección con compile(). Su nombre funciona como espacio de nombres de las capacidades que declara directamente.

Agnara(name: str) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.

Importa Agnara para el proyecto y App para un contexto delimitado. El registro es mutable durante el arranque. La compilación cierra la declaración de capacidades.

Agnara.name Propiedad

Nombre de la aplicación y espacio de nombres de sus capacidades directas. str

Agnara.capabilities Propiedad

Accede al registro de capacidades declaradas. CapabilityRegistry

Agnara.is_compiled Propiedad

Indica que se cerró el registro. bool

Agnara.capability Método

capability(
    handler: Any = None,
    /,
    *,
    name: str | None = None,
    description: str | None = None,
    scopes: Iterable[str] = (),
    effects: Iterable[str] = (),
    risk: Risk | str = Risk.LOW,
    confirmation: Confirmation | str = Confirmation.NEVER,
    idempotent: bool | None = None,
    streaming: bool = False,
    output: object = typing.Any,
) -> Any

Registra una función como capacidad, con decorador directo o parametrizado. Conserva la función para usarla como referencia al componer exposiciones.

handler
Función Python que ejecuta la operación.
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
effects
Conjunto de etiquetas que describe los efectos de la capacidad.
risk
Clasificación del impacto potencial de una invocación incorrecta.
confirmation
Régimen de confirmación declarado para la capacidad.
idempotent
Atajo de declaración para indicar si es seguro repetir la operación.
streaming
Indica que la capacidad produce unidades mediante un stream.
output
Anotación explícita del contrato de salida.

Agnara.include Método

include(app: App) -> App

Monta las capacidades de un contexto y comprueba colisiones antes de incorporarlo.

app
Aplicación o contexto que posee las declaraciones.

Agnara.apps Propiedad

Devuelve los contextos montados en orden de inclusión. Mapping[str, App]

Agnara.compile Método

compile() -> FrozenCapabilityRegistry

Cierra el registro y devuelve una vista inmutable. Los planes se compilan en un paso separado.

AgnaraError

Excepción · Estable · agnara

Excepción base de Agnara. Permite capturar fallos del framework en un límite de aplicación.

AnonymousPrincipal

Clase · Estable · agnara

Identidad anónima sin permisos concedidos. Sirve para representar una invocación sin autenticar.

AnonymousPrincipal(metadata: collections.abc.Mapping[str, Any] | None = None) -> None
Parámetros
metadata
Datos auxiliares de contexto. No son una credencial ni conceden permisos.
Atributos
identity: str
Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
metadata: dict[str, typing.Any]
Datos auxiliares de contexto. No son una credencial ni conceden permisos.
scopes: frozenset[str]
Permisos declarados por la capacidad o concedidos a una identidad verificada.

App

Clase · Estable · agnara

Contexto delimitado que agrupa capacidades relacionadas. Puede montarse en una aplicación Agnara conservando su propio espacio de nombres.

App(name: str, *, description: str | None = None, module: str | None = None) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
module
Nombre de módulo de procedencia que puede aparecer en el descriptor.

App.descriptor Propiedad

Devuelve los metadatos de identidad del contexto. AppDescriptor

App.name Propiedad

Nombre del contexto y espacio de nombres de las capacidades propias. str

App.capabilities Propiedad

Devuelve el registro de capacidades declaradas en el contexto. CapabilityRegistry

App.capability Método

capability(
    handler: Any = None,
    /,
    *,
    name: str | None = None,
    description: str | None = None,
    scopes: Iterable[str] = (),
    effects: Iterable[str] = (),
    risk: Risk | str = Risk.LOW,
    confirmation: Confirmation | str = Confirmation.NEVER,
    idempotent: bool | None = None,
    streaming: bool = False,
    output: object = typing.Any,
) -> Any

Registra una función como capacidad de este contexto.

handler
Función Python que ejecuta la operación.
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
effects
Conjunto de etiquetas que describe los efectos de la capacidad.
risk
Clasificación del impacto potencial de una invocación incorrecta.
confirmation
Régimen de confirmación declarado para la capacidad.
idempotent
Atajo de declaración para indicar si es seguro repetir la operación.
streaming
Indica que la capacidad produce unidades mediante un stream.
output
Anotación explícita del contrato de salida.

AppDescriptor

Clase · Estable · agnara

Metadatos de identidad de un contexto delimitado para composición e introspección.

AppDescriptor(
    name: str,
    description: str | None = None,
    module: str | None = None,
) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
module
Nombre de módulo de procedencia que puede aparecer en el descriptor.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
description: str | None
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
module: str | None
Nombre de módulo de procedencia que puede aparecer en el descriptor.

CapabilityDefinition

Clase · Estable · agnara

Declaración de una capacidad independiente del transporte. Reúne la función, su contrato de salida, sus políticas y sus metadatos. Normalmente se obtiene al registrar una función.

CapabilityDefinition(
    id: CapabilityId,
    handler: Handler,
    description: str | None = None,
    effects: frozenset[str] = <factory>,
    scopes: frozenset[str] = <factory>,
    risk: Risk = Risk.LOW,
    confirmation: Confirmation = Confirmation.NEVER,
    idempotency: Idempotency = Idempotency.UNKNOWN,
    policies: tuple[Policy, ...] = <factory>,
    streaming: bool = False,
    output: object = typing.Any,
) -> None
Parámetros
id
Identificador del registro. Su tipo depende de la entidad.
handler
Función Python que ejecuta la operación.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects
Conjunto de etiquetas que describe los efectos de la capacidad.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk
Clasificación del impacto potencial de una invocación incorrecta.
confirmation
Régimen de confirmación declarado para la capacidad.
idempotency
Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
policies
Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
streaming
Indica que la capacidad produce unidades mediante un stream.
output
Anotación explícita de salida. El plan la compila al construir el contrato.

Un identificador inválido, una declaración incompatible o metadatos mal formados pueden producir DefinitionError durante la construcción.

Atributos
id: CapabilityId
Identificador del registro. Su tipo depende de la entidad.
handler: Handler
Función Python que ejecuta la operación.
description: str | None
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects: frozenset[str]
Conjunto de etiquetas que describe los efectos de la capacidad.
scopes: frozenset[str]
Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk: Risk
Clasificación del impacto potencial de una invocación incorrecta.
confirmation: Confirmation
Régimen de confirmación declarado para la capacidad.
idempotency: Idempotency
Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
policies: tuple[Policy, ...]
Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
streaming: bool
Indica que la capacidad produce unidades mediante un stream.
output: object
Anotación explícita de salida. El plan la compila al construir el contrato.

CapabilityDefinition.declare Método

declare(
    *,
    id: CapabilityId,
    handler: Handler,
    description: str | None = None,
    scopes: Iterable[str] = (),
    effects: Iterable[str] = (),
    risk: Risk | str = Risk.LOW,
    confirmation: Confirmation | str = Confirmation.NEVER,
    idempotency: Idempotency | str = Idempotency.UNKNOWN,
    policies: Iterable[Policy] = (),
    streaming: bool = False,
    output: object = typing.Any,
) -> Self

Construye una declaración validada a partir de los metadatos de autoría.

id
Identificador del registro. Su tipo depende de la entidad.
handler
Función Python que ejecuta la operación.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
effects
Conjunto de etiquetas que describe los efectos de la capacidad.
risk
Clasificación del impacto potencial de una invocación incorrecta.
confirmation
Régimen de confirmación declarado para la capacidad.
idempotency
Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
policies
Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
streaming
Indica que la capacidad produce unidades mediante un stream.
output
Anotación explícita del contrato de salida.

CapabilityDefinition.has_effect Método

has_effect(effect: str) -> bool

Comprueba si se declaró la etiqueta de efecto solicitada.

effect
Etiqueta de efecto que se comprueba o utiliza como filtro.

CapabilityDefinition.requires_scope Método

requires_scope(scope: str) -> bool

Comprueba si la capacidad declara ese permiso como requerido.

scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.

CapabilityId

Clase · Estable · agnara

Identificador lógico de una capacidad. La forma textual separa el espacio de nombres y el nombre con un punto.

CapabilityId(namespace: str, name: str) -> None
Parámetros
namespace
Espacio de nombres al que pertenece la capacidad.
name
Nombre lógico de la entidad que se declara, describe o publica.

Usa CapabilityId.parse("catalog.total") al recibir una identidad textual. Las invocaciones reciben el objeto CapabilityId.

Atributos
namespace: str
Espacio de nombres al que pertenece la capacidad.
name: str
Nombre lógico de la entidad que se declara, describe o publica.

CapabilityId.parse Método

parse(text: str) -> CapabilityId

Convierte un identificador textual con punto en un CapabilityId.

text
Identificador textual que se convierte a su forma estructurada.

CapabilityRegistry

Clase · Estable · agnara

Registro mutable durante el arranque. Detecta duplicados y se cierra con freeze().

CapabilityRegistry(definitions: Iterable[CapabilityDefinition] = ()) -> None
Parámetros
definitions
Declaraciones de capacidad con las que se inicializa el registro.

CapabilityRegistry.is_frozen Propiedad

Indica si se cerraron las declaraciones. bool

CapabilityRegistry.register Método

register(definition: CapabilityDefinition) -> CapabilityDefinition

Registra y devuelve una definición. Detecta identificadores duplicados.

definition
Declaración de la capacidad que se compila o expone.

CapabilityRegistry.freeze Método

freeze() -> FrozenCapabilityRegistry

Cierra el registro y devuelve su vista inmutable.

CapabilityRegistry.__getitem__ Método

__getitem__(key: CapabilityKey) -> CapabilityDefinition

Busca un elemento por su clave.

key
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.

CapabilityRegistry.__contains__ Método

__contains__(key: object) -> bool

Comprueba si la clave pertenece a la colección.

key
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.

CapabilityRegistry.__iter__ Método

__iter__() -> Iterator[CapabilityId]

Recorre las claves de la colección.

CapabilityRegistry.__len__ Método

__len__() -> int

Devuelve la cantidad de declaraciones o elementos de la colección.

Confirmation

Enumeración · Estable · agnara

Indica el régimen de confirmación humana de una capacidad. La evidencia debe pasar por un verificador configurado.

NEVER = 'never'
El régimen de la capacidad no exige confirmación.
POLICY = 'policy'
Una política decide si la invocación concreta requiere confirmación.
REQUIRED = 'required'
La capacidad exige confirmación verificada.

ConfirmationEvidence

Clase · Estable · agnara

Contenedor de evidencia opaca suministrada por un límite de confianza. El contenido requiere verificación antes de conceder una confirmación.

ConfirmationEvidence(value: object) -> None
Parámetros
value
Contenido opaco que interpreta el verificador de la aplicación.
Atributos
value: object
Contenido opaco que interpreta el verificador de la aplicación.

ConfirmationVerdict

Enumeración · Estable · agnara

Decisión que devuelve un verificador sobre la evidencia presentada para una invocación.

VALID = 'valid'
El verificador aceptó la evidencia para esta invocación.
INVALID = 'invalid'
El verificador rechazó la evidencia.

ConfirmationVerifier

Protocolo · Estable · agnara

Protocolo que implementa la aplicación para comprobar evidencia vinculada a una capacidad, invocación e identidad concretas.

ConfirmationVerifier.verify Método

async verify(
    evidence: ConfirmationEvidence,
    *,
    capability_id: CapabilityId,
    invocation: Invocation,
    principal: Principal,
) -> ConfirmationVerdict

Comprueba evidencia para la capacidad, solicitud e identidad indicadas y devuelve un ConfirmationVerdict.

evidence
Evidencia opaca que el verificador comprueba para esta solicitud.
capability_id
Identificador lógico de la capacidad.
invocation
Solicitud de ejecución que contiene identidad de capacidad y entrada.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

DefinitionError

Excepción · Estable · agnara

Una declaración de capacidad es inválida para el runtime.

DuplicateAppError

Excepción · Estable · agnara

Dos contextos montados reclaman la misma identidad.

DuplicateCapabilityError

Excepción · Estable · agnara

Dos declaraciones reclaman el mismo identificador de capacidad.

FrozenCapabilityRegistry

Clase · Estable · agnara

Vista inmutable de las capacidades registradas. Permite buscar por identificador y consultar subconjuntos por espacio de nombres o efecto.

FrozenCapabilityRegistry(
    definitions: Mapping[CapabilityId, CapabilityDefinition],
) -> None
Parámetros
definitions
Declaraciones de capacidad con las que se inicializa el registro.

FrozenCapabilityRegistry.__getitem__ Método

__getitem__(key: CapabilityKey) -> CapabilityDefinition

Busca un elemento por su clave.

key
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.

FrozenCapabilityRegistry.__contains__ Método

__contains__(key: object) -> bool

Comprueba si la clave pertenece a la colección.

key
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.

FrozenCapabilityRegistry.__iter__ Método

__iter__() -> Iterator[CapabilityId]

Recorre las claves de la colección.

FrozenCapabilityRegistry.__len__ Método

__len__() -> int

Devuelve la cantidad de declaraciones o elementos de la colección.

FrozenCapabilityRegistry.namespaces Propiedad

Devuelve los espacios de nombres con capacidades registradas. frozenset[str]

FrozenCapabilityRegistry.in_namespace Método

in_namespace(namespace: str) -> tuple[CapabilityDefinition, ...]

Devuelve las capacidades del espacio de nombres en orden de registro.

namespace
Espacio de nombres al que pertenece la capacidad.

FrozenCapabilityRegistry.with_effect Método

with_effect(effect: str) -> tuple[CapabilityDefinition, ...]

Devuelve las capacidades que declaran el efecto solicitado, en orden de registro.

effect
Etiqueta de efecto que se comprueba o utiliza como filtro.

Idempotency

Enumeración · Estable · agnara

Describe si una capacidad admite repetición segura. El metadato por sí solo no reserva una ejecución ni guarda su resultado.

YES = 'yes'
La capacidad declara que la repetición es segura.
NO = 'no'
La capacidad declara que repetirla puede duplicar efectos.
UNKNOWN = 'unknown'
La declaración no establece seguridad de repetición.

InteractionKind

Enumeración · Estable · agnara

Vocabulario de interacciones que pueden ser necesarias antes de continuar.

CONFIRMATION = 'confirmation'
Se requiere confirmación del llamador.

InteractionRequest

Clase · Estable · agnara

Información apta para mostrar al llamador cuando se requiere una interacción previa a la ejecución.

InteractionRequest(
    kind: InteractionKind,
    title: str,
    message: str,
    capability_id: CapabilityId,
    hints: Mapping[str, InteractionHint] = <factory>,
) -> None
Parámetros
kind
Categoría de interacción, proveedor o descriptor según el tipo indicado.
title
Título que puede mostrarse al lector.
message
Mensaje de fallo o interacción que el llamador puede leer.
capability_id
Identificador lógico de la capacidad.
hints
Información estructurada apta para orientar al llamador.
Atributos
kind: InteractionKind
Categoría de interacción, proveedor o descriptor según el tipo indicado.
title: str
Título que puede mostrarse al lector.
message: str
Mensaje de fallo o interacción que el llamador puede leer.
capability_id: CapabilityId
Identificador lógico de la capacidad.
hints: Mapping[str, InteractionHint]
Información estructurada apta para orientar al llamador.

InteractionRequiredError

Excepción · Estable · agnara

Interrumpe una invocación directa cuando se necesita una interacción con el llamador. Su solicitud describe el siguiente paso.

InteractionRequiredError(request: InteractionRequest) -> None
Parámetros
request
Solicitud de interacción que explica al llamador cómo continuar.
Atributos
request: InteractionRequest
Solicitud de interacción que explica al llamador cómo continuar.

InvocationError

Excepción · Estable · agnara

Una invocación directa es incoherente con el plan o el contexto que recibe el runtime.

JsonSchema

Alias de tipo · Estable · agnara

Alias para una representación de JSON Schema como mapeo de claves de texto.

JsonSchema = collections.abc.Mapping[str, typing.Any]

Policy

Protocolo · Estable · agnara

Protocolo de una regla evaluada antes del handler. Recibe el contexto y devuelve un PolicyResult.

Policy.evaluate Método

async evaluate(context: ExecutionContext) -> PolicyResult

Evalúa el contexto antes del handler y devuelve una autorización, denegación o solicitud de interacción.

context
Contexto de la invocación que se va a evaluar o ejecutar.

PolicyDeniedError

Excepción · Estable · agnara

Una política previa al handler denegó la invocación directa.

PolicyFailure

Clase · Estable · agnara

Resultado de política que deniega la operación.

PolicyFailure(reason: str) -> None
Parámetros
reason
Motivo seguro que acompaña a la denegación.
Atributos
reason: str
Motivo seguro que acompaña a la denegación.

PolicyInteractionRequired

Clase · Estable · agnara

Resultado de política que detiene la ejecución hasta que el llamador complete una interacción.

PolicyInteractionRequired(request: InteractionRequest) -> None
Parámetros
request
Solicitud de interacción que explica al llamador cómo continuar.
Atributos
request: InteractionRequest
Solicitud de interacción que explica al llamador cómo continuar.

PolicyResult

Alias de tipo · Estable · agnara

Unión de los resultados posibles de una política. Distingue autorización, denegación y necesidad de interacción.

PolicyResult = PolicySuccess | PolicyFailure | PolicyInteractionRequired

PolicySuccess

Clase · Estable · agnara

Resultado de política que permite continuar con la ejecución.

PolicySuccess() -> None

Principal

Clase · Estable · agnara

Identidad autenticada y permisos otorgados por el host. Los datos enviados en el payload no son una fuente de identidad.

Principal(
    identity: str,
    metadata: collections.abc.Mapping[str, Any] | None = None,
    scopes: collections.abc.Iterable[str] = (),
) -> None
Parámetros
identity
Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
metadata
Datos auxiliares de contexto. No son una credencial ni conceden permisos.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
Atributos
identity: str
Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
metadata: dict[str, typing.Any]
Datos auxiliares de contexto. No son una credencial ni conceden permisos.
scopes: frozenset[str]
Permisos declarados por la capacidad o concedidos a una identidad verificada.

RegistryError

Excepción · Estable · agnara

Uso incompatible con el contrato del registro de capacidades.

RegistryFrozenError

Excepción · Estable · agnara

Se intentó modificar un registro que ya está congelado.

Risk

Enumeración · Estable · agnara

Clasifica el daño potencial de una invocación errónea o maliciosa. Es metadato y la autorización depende de las políticas.

LOW = 'low'
Impacto bajo.
MEDIUM = 'medium'
Impacto medio.
HIGH = 'high'
Impacto alto.
CRITICAL = 'critical'
Impacto crítico.

SchemaAdapter

Protocolo · Estable · agnara

Protocolo que transforma una anotación de Python en un esquema reutilizable.

SchemaAdapter.compile Método

compile(annotation: Any) -> TypeSchema

Prepara un esquema reutilizable para la anotación o informa un SchemaError.

annotation
Anotación de tipo Python que se describe o compila.

SchemaAdapter.supports Método

supports(annotation: Any) -> bool

Indica si puede compilar esa anotación.

annotation
Anotación de tipo Python que se describe o compila.

SchemaError

Excepción · Estable · agnara

Una anotación no se pudo compilar como esquema.

ScopePolicy

Clase · Estable · agnara

Exige que la identidad activa tenga todos los permisos indicados por la regla.

ScopePolicy(required_scopes: Iterable[str] = ()) -> None
Parámetros
required_scopes
Permisos que la regla exige en conjunto.
Atributos
required_scopes: frozenset[str]
Permisos que la regla exige en conjunto.

ScopePolicy.evaluate Método

async evaluate(context: ExecutionContext) -> PolicyResult

Autoriza cuando la identidad activa posee todos los permisos que exige la regla.

context
Contexto de la invocación que se va a evaluar o ejecutar.

StandardEffect

Enumeración · Estable · agnara

Vocabulario de etiquetas para describir lecturas, escrituras y efectos destructivos.

NONE = 'none'
Sin efectos declarados.
READ = 'read'
Lectura.
CACHE_WRITE = 'cache-write'
Escritura en caché.
DATABASE_WRITE = 'database-write'
Escritura en base de datos.
EXTERNAL_WRITE = 'external-write'
Escritura en un sistema externo.
FINANCIAL_WRITE = 'financial-write'
Operación con efecto financiero.
DESTRUCTIVE = 'destructive'
Efecto destructivo.

StandardSchemaAdapter

Clase · Estable · agnara

Compila anotaciones comunes con la biblioteca estándar, incluidos tipos simples, contenedores, uniones, enumeraciones y dataclasses compatibles.

StandardSchemaAdapter() -> None

StandardSchemaAdapter.compile Método

compile(annotation: Any) -> TypeSchema

Compila la anotación con los tipos admitidos por el adaptador de biblioteca estándar.

annotation
Anotación de tipo Python que se describe o compila.

StandardSchemaAdapter.supports Método

supports(annotation: Any) -> bool

Comprueba si el adaptador estándar puede compilar la anotación.

annotation
Anotación de tipo Python que se describe o compila.

TypeSchema

Protocolo · Estable · agnara

Protocolo de un esquema compilado. Valida valores de Python y emite una representación JSON Schema.

TypeSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

TypeSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

UnknownCapabilityError

Excepción · Estable · agnara

El identificador solicitado no existe en el registro.

ValidationError

Excepción · Estable · agnara

Un valor incumple el contrato de su esquema. La ruta permite ubicar el campo o elemento afectado.

ValidationError(message: str, *, path: tuple[str | int, ...] = ()) -> None
Parámetros
message
Mensaje de fallo o interacción que el llamador puede leer.
path
Tupla de campos e índices que localiza el dato inválido. La raíz es la tupla vacía.
Atributos
message: str
Mensaje de fallo o interacción que el llamador puede leer.
path: tuple[str | int, ...]
Tupla de campos e índices que localiza el dato inválido. La raíz es la tupla vacía.

ValidationError.at Método

at(segment: str | int) -> ValidationError

Devuelve un nuevo error con un segmento adicional al principio de la ruta.

segment
Campo o índice que se antepone a la ruta del error.

ValidationError.location Propiedad

Representa la ruta de error para lectura humana. En la raíz usa <value>. str

__version__

Constante · Estable · agnara

Versión del paquete principal importado en este proceso.

__version__ = '1.0.4'

3. Inyección de dependencias

agnara.di · 9 exportaciones

Asocia cada tipo a un proveedor antes de compilar. Los recursos de invocación terminan con la llamada. Los singleton se cierran con su contenedor, en el bucle que los posee.

Guía relacionada · DEPENDENCIES.md

DIContainer · DIRegistry · DependencyCycleError · DependencyResolutionError · ProviderDefinition · ProviderType · Scope · compile_dag · provider

DIContainer

Clase · Estable · agnara.di

Resuelve dependencias y conserva los recursos singleton. Su propietario debe cerrarlo con aclose() en el bucle que lo usa.

DIContainer(registry: DIRegistry) -> None
Parámetros
registry
Registro de capacidades o asociaciones de DI del que parte la operación.

Scope.INVOCATION se libera con cada invocación. Scope.SINGLETON se libera con aclose(). Los proveedores que entregan recursos con yield deben liberar en finally.

Atributos
registry: DIRegistry
Registro de capacidades o asociaciones de DI del que parte la operación.
singleton_cache: dict[type, Any]
Caché de dependencias singleton que administra el contenedor. Trátala como estado del contenedor.
exit_stack
Pila de cierre que administra el contenedor. Cierra los recursos mediante aclose().

DIContainer.aclose Método

async aclose() -> None

Cierra los recursos singleton que posee el contenedor.

DIContainer.resolve_dependencies Método

resolve_dependencies(
    target_func: collections.abc.Callable[..., typing.Any],
    target_deps: collections.abc.Mapping[collections.abc.Callable[..., typing.Any], collections.abc.Sequence[type]],
) -> collections.abc.AsyncGenerator[dict[str, typing.Any]]

Resuelve los argumentos de dependencia de la función usando el grafo precompilado.

target_func
Función objetivo para la cual se resuelven dependencias.
target_deps
Mapa de dependencias del objetivo generado al compilar el grafo.

DIRegistry

Clase · Estable · agnara.di

Tabla de asociaciones explícitas entre tipos solicitados y proveedores. Se prepara antes de compilar los planes.

DIRegistry() -> None

DIRegistry.bind Método

bind(
    provides: type,
    provider: ProviderDefinition | collections.abc.Callable[..., Any],
) -> None

Asocia explícitamente un tipo a la declaración del proveedor que lo suministra.

provides
Tipo que suministra la asociación.
provider
Declaración de proveedor que se asocia al tipo.

DIRegistry.get_provider Método

get_provider(provides: type) -> ProviderDefinition | None

Obtiene el proveedor asociado al tipo.

provides
Tipo que suministra la asociación.

DIRegistry.is_bound Método

is_bound(provides: type) -> bool

Comprueba si existe una asociación para el tipo solicitado.

provides
Tipo que suministra la asociación.

DIRegistry.all_bindings Método

all_bindings() -> dict[type, ProviderDefinition]

Devuelve las asociaciones registradas.

DependencyCycleError

Excepción · Estable · agnara.di

El grafo de proveedores contiene un ciclo.

DependencyResolutionError

Excepción · Estable · agnara.di

Una dependencia no pudo resolverse para la ejecución solicitada.

ProviderDefinition

Clase · Estable · agnara.di

Descripción de un proveedor, de su tipo de callable y de la duración del recurso que entrega.

ProviderDefinition(
    func: collections.abc.Callable[..., typing.Any],
    scope: Scope,
    provider_type: ProviderType,
    return_type: type,
) -> None
Parámetros
func
Función o generador que proporciona la dependencia.
scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
provider_type
Clase de callable del proveedor, según ProviderType.
return_type
Tipo que declara producir el proveedor.
Atributos
func: collections.abc.Callable[..., typing.Any]
Función o generador que proporciona la dependencia.
scope: Scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
provider_type: ProviderType
Clase de callable del proveedor, según ProviderType.
return_type: type
Tipo que declara producir el proveedor.

ProviderDefinition.from_callable Método

from_callable(
    func: collections.abc.Callable[..., typing.Any],
    scope: Scope,
) -> ProviderDefinition

Construye la declaración e identifica la forma del callable y el tipo de retorno.

func
Función o generador que proporciona la dependencia.
scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.

ProviderType

Enumeración · Estable · agnara.di

Clasifica el proveedor según la forma en que produce el valor. El contenedor usa esa forma para adquirirlo y liberar sus recursos.

SYNC_FUNCTION = 'sync_function'
La función síncrona devuelve el recurso.
ASYNC_FUNCTION = 'async_function'
Se espera a la función asíncrona para obtener el recurso.
SYNC_GENERATOR = 'sync_generator'
El generador síncrono entrega un recurso y permite su liberación al cerrarlo.
ASYNC_GENERATOR = 'async_generator'
El generador asíncrono entrega un recurso y permite su liberación asíncrona.

Scope

Enumeración · Estable · agnara.di

Duración del valor que devuelve un proveedor.

SINGLETON = 'singleton'
Se reutiliza durante la vida del contenedor.
INVOCATION = 'invocation'
Se adquiere y libera con la invocación.

compile_dag

Función · Estable · agnara.di

Compila el grafo de dependencias de las funciones objetivo. Detecta ciclos y prepara la resolución antes de invocar.

compile_dag(
    registry: DIRegistry,
    target_funcs: list[collections.abc.Callable[..., typing.Any]],
) -> dict[collections.abc.Callable[..., typing.Any], list[type]]
Parámetros
registry
Registro de capacidades o asociaciones de DI del que parte la operación.
target_funcs
Funciones raíz cuyos proveedores se compilan.

provider

Función · Estable · agnara.di

Decorador que declara una función o generador como proveedor. Asocia el resultado a un tipo con DIRegistry.bind().

provider(
    *,
    scope: Scope = Scope.INVOCATION,
) -> collections.abc.Callable[[collections.abc.Callable[..., typing.Any]], ProviderDefinition]
Parámetros
scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.

4. Ejecución de capacidades

agnara.execution · 32 exportaciones

El plan prepara el trabajo de arranque. Cada llamada crea su propio contexto. Las políticas preceden a la materialización, validación y adquisición de recursos. El plazo usa un reloj monotónico y la cancelación del llamador se propaga.

Guía relacionada · DIRECT_IDEMPOTENCY.md

CanonicalResult · CapabilityInvoker · CapabilityRuntime · CapabilityStream · ExecutionContext · ExecutionPlan · Failure · FailureCode · IdempotencyClaimed · IdempotencyCompleted · IdempotencyConflict · IdempotencyConflictError · IdempotencyInProgress · IdempotencyInProgressError · IdempotencyInvocation · IdempotencyReservation · IdempotencyResultCodec · IdempotencyScope · IdempotencyStorageError · IdempotencyStore · InMemoryIdempotencyStore · Invocation · InvocationStartEvent · InvocationTerminalEvent · StreamInterrupted · StreamTerminal · Success · TelemetryHook · classify_failure · invoke · invoke_result · open_stream

CanonicalResult

Alias de tipo · Estable · agnara.execution

Resultado transportable de una invocación completa. Puede contener un éxito con valor o un fallo con categoría segura.

CanonicalResult = Success[T] | Failure

CapabilityInvoker

Clase · Estable · agnara.execution

Dependencia inyectada que permite invocar otra capacidad de resultado completo en la misma aplicación. La invocación hija vuelve a pasar por políticas.

Inyecta este tipo en el handler cuando uses CapabilityRuntime. Cada llamada hija pasa por el plan compilado.

CapabilityInvoker.invoke Método

async invoke(
    capability_id: CapabilityId,
    payload: Mapping[str, Any],
    *,
    timeout: float | None = None,
) -> CanonicalResult[Any]

Invoca una capacidad del mismo runtime como hija, con su propio contexto y evaluación de políticas.

capability_id
Identificador lógico de la capacidad.
payload
Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
timeout
Presupuesto de ejecución en segundos. None omite este límite explícito.

CapabilityRuntime

Clase · Estable · agnara.execution

Runtime de una aplicación compilada. Selecciona el plan desde la identidad de la invocación y gestiona composición anidada.

CapabilityRuntime(
    capabilities: FrozenCapabilityRegistry,
    plans: Sequence[ExecutionPlan],
    container: DIContainer,
    *,
    max_composition_depth: int = 8,
) -> None
Parámetros
capabilities
Conjunto de capacidades declaradas o compiladas que delimita la composición.
plans
Planes compilados que la superficie puede despachar o describir.
container
Contenedor de dependencias de la aplicación.
max_composition_depth
Profundidad máxima de invocaciones anidadas permitida.

El hijo vuelve a autorizarse con la identidad derivada del padre. La composición es dentro de la misma aplicación y comparte el presupuesto de tiempo según el contrato de ejecución anidada.

CapabilityRuntime.invoke Método

async invoke(context: ExecutionContext) -> Any

Selecciona el plan según el contexto y ejecuta con excepciones de Python.

context
Contexto de la invocación que se va a evaluar o ejecutar.

CapabilityRuntime.invoke_result Método

async invoke_result(
    context: ExecutionContext,
    *,
    input_materializer: Callable[[TypeSchema, object], object] | None = None,
) -> CanonicalResult[T]

Selecciona el plan y devuelve un resultado canónico.

context
Contexto de la invocación que se va a evaluar o ejecutar.
input_materializer
Conversión de datos del límite de transporte a valores de entrada Python.

CapabilityRuntime.aclose Método

async aclose() -> None

Cierra el contenedor de dependencias de la aplicación.

CapabilityStream

Clase · Estable · agnara.execution

Consumo asíncrono de un stream de una sola ejecución. Entrega unidades bajo demanda y expone cómo terminó.

CapabilityStream.units_emitted Propiedad

Número de unidades que ya recibió este consumidor. int

CapabilityStream.terminal Propiedad

Estado terminal del stream o None mientras siga activo. StreamTerminal | None

CapabilityStream.execution_id Propiedad

Identidad lógica de esta ejecución de streaming. str

CapabilityStream.__aiter__ Método

__aiter__() -> AsyncIterator[Any]

Entrega el iterador asíncrono de esta ejecución para async for.

CapabilityStream.__anext__ Método

async __anext__() -> Any

Solicita una unidad, sujeta al plazo de la invocación.

CapabilityStream.aclose Método

async aclose() -> None

Cierra el productor y libera los recursos del alcance de la invocación.

ExecutionContext

Clase · Estable · agnara.execution

Entorno de una invocación. Vincula entrada, contenedor e identidad verificada y expone el plazo e identidad de ejecución.

ExecutionContext(
    invocation: Invocation,
    di_container: DIContainer,
    tracking_id: str | None = None,
    principal: Principal | None = None,
    confirmation_evidence: ConfirmationEvidence | None = None,
    idempotency: IdempotencyInvocation | None = None,
) -> None
Parámetros
invocation
Solicitud de ejecución que contiene identidad de capacidad y entrada.
di_container
Contenedor que aporta los recursos de esta ejecución.
tracking_id
Etiqueta opcional de correlación externa. No concede autoridad.
principal
Identidad verificada. Queda fija durante la ejecución y el valor por omisión es anónimo.
confirmation_evidence
Evidencia opaca para esta invocación. Queda fija al construir el contexto.
idempotency
Configuración explícita de idempotencia fijada al construir el contexto.

Crea un contexto por llamada. Calcula un plazo de 30 segundos con asyncio.get_running_loop().time() + 30. La cancelación es cooperativa y las funciones síncronas pueden bloquear el bucle.

Atributos
invocation: Invocation
Solicitud de ejecución que contiene identidad de capacidad y entrada.
di_container: DIContainer
Contenedor que aporta los recursos de esta ejecución.
tracking_id: str | None
Etiqueta opcional de correlación externa. No concede autoridad.
state: dict[str, Any]
Diccionario mutable para datos de esta ejecución. Tiene alcance local a la invocación.

ExecutionContext.principal Propiedad

Identidad verificada. Queda fija durante la ejecución y el valor por omisión es anónimo. Principal

ExecutionContext.confirmation_evidence Propiedad

Evidencia opaca para esta invocación. Queda fija al construir el contexto. ConfirmationEvidence | None

ExecutionContext.idempotency Propiedad

Configuración explícita de idempotencia fijada al construir el contexto. IdempotencyInvocation | None

ExecutionContext.execution_id Propiedad

Identidad lógica opaca asignada por el runtime. Es independiente de tracking_id. str

ExecutionContext.deadline Propiedad

Plazo monotónico absoluto de la invocación, si se configuró. float | None

ExecutionContext.remaining_time Método

remaining_time(now: float | None = None) -> float | None

Calcula los segundos restantes, con mínimo cero. Devuelve None sin plazo.

now
Lectura monotónica usada para calcular el tiempo restante.

ExecutionPlan

Clase · Estable · agnara.execution

Plan inmutable que conecta una capacidad con esquemas, políticas, dependencias y hooks. Usa compile() como punto de composición.

Los parámetros protegidos los aporta el runtime. Un payload que intenta rellenarlos no puede sustituir una dependencia o el contexto.

Atributos
definition: CapabilityDefinition
Declaración de la capacidad que se compila o expone.
target_deps: Mapping[Callable[..., Any], Sequence[type]]
Mapa de dependencias del objetivo generado al compilar el grafo.
hooks: tuple[TelemetryHook, ...]
Observadores de telemetría del plan o de la superficie.
policies: tuple[Policy, ...]
Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
dependency_parameters: frozenset[str]
Nombres de parámetros vinculados a proveedores.
context_parameters: tuple[str, ...]
Parámetros del handler reservados para el contexto de ejecución.
capability_invoker_parameters: tuple[str, ...]
Parámetros de la función reservados para el invocador de capacidades.
protected_parameters: frozenset[str]
Parámetros que aporta el runtime y que el llamador no puede rellenar.
input_schemas: Mapping[str, TypeSchema]
Mapeo de parámetros de entrada a esquemas compilados.
required_inputs: frozenset[str]
Entradas que debe aportar el llamador.
output_schema: TypeSchema
Esquema compilado que valida el valor producido.

ExecutionPlan.compile Método

compile(
    definition: CapabilityDefinition,
    registry: DIRegistry,
    hooks: Sequence[TelemetryHook] = (),
    confirmation_verifier: ConfirmationVerifier | None = None,
    schema_adapter: SchemaAdapter | None = None,
) -> ExecutionPlan

Valida la declaración, clasifica los parámetros, compila los esquemas y resuelve el grafo de proveedores antes de invocar.

definition
Declaración de la capacidad que se compila o expone.
registry
Registro de capacidades o asociaciones de DI del que parte la operación.
hooks
Observadores de telemetría del plan o de la superficie.
confirmation_verifier
Verificador que la aplicación suministra al compilar.
schema_adapter
Adaptador que compila anotaciones en esquemas.

ExecutionPlan.dependencies Propiedad

Tipos de las dependencias directas en el orden de la firma del handler. tuple[type, ...]

ExecutionPlan.streaming Propiedad

Indica que este plan se consume mediante open_stream(). bool

Failure

Clase · Estable · agnara.execution

Fallo canónico con código, mensaje apto para el llamador y detalles inmutables. Los adaptadores lo proyectan a su protocolo.

Failure(
    code: FailureCode,
    message: str,
    details: Mapping[str, FailureDetail] = <factory>,
    execution_id: str | None = None,
) -> None
Parámetros
code
Categoría semántica del fallo.
message
Mensaje de fallo o interacción que el llamador puede leer.
details
Pares clave y valor aptos para publicar junto al fallo.
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
Atributos
code: FailureCode
Categoría semántica del fallo.
message: str
Mensaje de fallo o interacción que el llamador puede leer.
details: Mapping[str, FailureDetail]
Pares clave y valor aptos para publicar junto al fallo.
execution_id: str | None
Identidad lógica opaca que asigna o recupera el runtime.

FailureCode

Enumeración · Estable · agnara.execution

Categorías semánticas de fallo compartidas por los transportes.

INVALID_INPUT = 'invalid_input'
La entrada incumple el contrato.
UNAUTHENTICATED = 'unauthenticated'
Se necesita autenticación.
FORBIDDEN = 'forbidden'
La identidad carece de autoridad.
NOT_FOUND = 'not_found'
No se encontró el recurso o destino.
CONFLICT = 'conflict'
La solicitud entra en conflicto con el estado actual.
RATE_LIMITED = 'rate_limited'
Se alcanzó un límite de solicitudes.
INTERACTION_REQUIRED = 'interaction_required'
Hace falta una interacción con el llamador.
UNAVAILABLE = 'unavailable'
La operación está temporalmente indisponible.
TIMEOUT = 'timeout'
Se agotó el plazo de ejecución.
INTERNAL_FAILURE = 'internal_failure'
Se produjo un fallo interno con diagnóstico público redactado.

IdempotencyClaimed

Clase · Estable · agnara.execution

El llamador obtuvo la reserva atómica para ejecutar una operación.

IdempotencyClaimed(reservation: IdempotencyReservation) -> None
Parámetros
reservation
Reserva opaca que prueba que un intento puede completar o abandonar el selector.
Atributos
reservation: IdempotencyReservation
Reserva opaca que prueba que un intento puede completar o abandonar el selector.

IdempotencyCompleted

Clase · Estable · agnara.execution

El almacén contiene un éxito reutilizable para el selector y huella coincidentes.

IdempotencyCompleted(execution_id: str, result: bytes) -> None
Parámetros
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
result
Bytes opacos del éxito previamente almacenado.
Atributos
execution_id: str
Identidad lógica opaca que asigna o recupera el runtime.
result: bytes
Bytes opacos del éxito previamente almacenado.

IdempotencyConflict

Clase · Estable · agnara.execution

La misma clave se presentó con una huella de solicitud distinta.

IdempotencyConflict() -> None

IdempotencyConflictError

Excepción · Estable · agnara.execution

El selector no puede aplicarse a la invocación lógica actual.

IdempotencyInProgress

Clase · Estable · agnara.execution

La operación coincidente sigue reservada por otra invocación.

IdempotencyInProgress(execution_id: str) -> None
Parámetros
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
Atributos
execution_id: str
Identidad lógica opaca que asigna o recupera el runtime.

IdempotencyInProgressError

Excepción · Estable · agnara.execution

Otra invocación posee la reserva del selector coincidente.

IdempotencyInvocation

Clase · Estable · agnara.execution

Activa la idempotencia explícita de una invocación de resultado completo con selector, almacén, códec y duraciones.

IdempotencyInvocation(
    scope: IdempotencyScope,
    store: IdempotencyStore,
    codec: IdempotencyResultCodec,
    lease_ttl: float,
    result_ttl: float,
) -> None
Parámetros
scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
store
Almacén que arbitra reservas y éxitos de idempotencia.
codec
Códec de éxitos configurado para almacenamiento.
lease_ttl
Tiempo en segundos durante el cual la reserva conserva la propiedad.
result_ttl
Tiempo en segundos de conservación del éxito.

Configura la huella y clave en el límite de confianza. El runtime comprueba autoridad antes de reutilizar un éxito. El almacén de referencia no conserva datos al reiniciar.

Atributos
scope: IdempotencyScope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
store: IdempotencyStore
Almacén que arbitra reservas y éxitos de idempotencia.
codec: IdempotencyResultCodec
Códec de éxitos configurado para almacenamiento.
lease_ttl: float
Tiempo en segundos durante el cual la reserva conserva la propiedad.
result_ttl: float
Tiempo en segundos de conservación del éxito.

IdempotencyReservation

Clase · Estable · agnara.execution

Credencial opaca de una reserva aceptada. El almacén la comprueba para completar o abandonar el intento.

IdempotencyReservation(scope: IdempotencyScope, execution_id: str, token: str) -> None
Parámetros
scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
token
Valor opaco del almacén que distingue esta reserva de las demás.
Atributos
scope: IdempotencyScope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
execution_id: str
Identidad lógica opaca que asigna o recupera el runtime.
token: str
Valor opaco del almacén que distingue esta reserva de las demás.

IdempotencyResultCodec

Protocolo · Estable · agnara.execution

Protocolo para convertir éxitos a bytes acotados y reconstruirlos. El códec pertenece a la aplicación.

IdempotencyResultCodec.encode Método

encode(value: object, /) -> bytes

Convierte un valor satisfactorio en bytes acotados para almacenarlo.

value
Valor que se valida, contiene o transforma.

IdempotencyResultCodec.decode Método

decode(payload: bytes, /) -> object

Reconstruye el valor de éxito desde los bytes guardados.

payload
Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.

IdempotencyScope

Clase · Estable · agnara.execution

Identidad compuesta de la solicitud para idempotencia. Vincula capacidad, identidad, clave y huella.

IdempotencyScope(
    capability_id: CapabilityId,
    principal_id: str,
    key: str,
    fingerprint: bytes,
) -> None
Parámetros
capability_id
Identificador lógico de la capacidad.
principal_id
Identidad estable asociada al selector de idempotencia.
key
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
fingerprint
Huella del contenido lógico de la solicitud que calcula la aplicación.
Atributos
capability_id: CapabilityId
Identificador lógico de la capacidad.
principal_id: str
Identidad estable asociada al selector de idempotencia.
key: str
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
fingerprint: bytes
Huella del contenido lógico de la solicitud que calcula la aplicación.

IdempotencyStorageError

Excepción · Estable · agnara.execution

El almacén configurado no puede realizar la operación de idempotencia de forma segura.

IdempotencyStore

Protocolo · Estable · agnara.execution

Protocolo de almacenamiento que coordina reservas y conserva éxitos mediante operaciones atómicas.

Las reservas caducan. El almacén compara la reserva al completar o abandonar para proteger a un propietario nuevo de un intento anterior.

IdempotencyStore.claim Método

async claim(
    scope: IdempotencyScope,
    *,
    lease_ttl: float,
) -> IdempotencyClaimed | IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflict

Reserva atómicamente el selector o devuelve el estado que ya tiene.

scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
lease_ttl
Tiempo en segundos durante el cual la reserva conserva la propiedad.

IdempotencyStore.lookup Método

async lookup(
    scope: IdempotencyScope,
) -> IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflict | None

Consulta el estado sin adquirir una reserva.

scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.

IdempotencyStore.complete Método

async complete(
    reservation: IdempotencyReservation,
    result: bytes,
    *,
    result_ttl: float,
) -> bool

Publica atómicamente un éxito si la reserva aún pertenece al intento.

reservation
Reserva opaca que prueba que un intento puede completar o abandonar el selector.
result
Valor o bytes del resultado según el contrato del método.
result_ttl
Tiempo en segundos de conservación del éxito.

IdempotencyStore.abandon Método

async abandon(reservation: IdempotencyReservation) -> bool

Libera una reserva vigente tras fallo o cancelación.

reservation
Reserva opaca que prueba que un intento puede completar o abandonar el selector.

InMemoryIdempotencyStore

Clase · Estable · agnara.execution

Almacén de referencia con capacidad acotada dentro de un proceso. Sus registros desaparecen al reiniciar.

InMemoryIdempotencyStore(
    *,
    max_entries: int = 1024,
    clock: Callable[[], float] = monotonic,
) -> None
Parámetros
max_entries
Cantidad máxima de registros que el almacén de referencia puede conservar.
clock
Función de reloj que devuelve segundos monotónicos.

InMemoryIdempotencyStore.claim Método

async claim(
    scope: IdempotencyScope,
    *,
    lease_ttl: float,
) -> IdempotencyClaimed | IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflict

Reserva atómicamente el selector o devuelve el estado que ya tiene.

scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
lease_ttl
Tiempo en segundos durante el cual la reserva conserva la propiedad.

InMemoryIdempotencyStore.lookup Método

async lookup(
    scope: IdempotencyScope,
) -> IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflict | None

Consulta el estado sin adquirir una reserva.

scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.

InMemoryIdempotencyStore.complete Método

async complete(
    reservation: IdempotencyReservation,
    result: bytes,
    *,
    result_ttl: float,
) -> bool

Publica atómicamente un éxito si la reserva aún pertenece al intento.

reservation
Reserva opaca que prueba que un intento puede completar o abandonar el selector.
result
Valor o bytes del resultado según el contrato del método.
result_ttl
Tiempo en segundos de conservación del éxito.

InMemoryIdempotencyStore.abandon Método

async abandon(reservation: IdempotencyReservation) -> bool

Libera una reserva vigente tras fallo o cancelación.

reservation
Reserva opaca que prueba que un intento puede completar o abandonar el selector.

Invocation

Clase · Estable · agnara.execution

Entrada aún sin validar de una ejecución, con identidad de capacidad, datos, metadatos y un plazo monotónico opcional.

Invocation(
    capability_id: CapabilityId,
    payload: dict[str, typing.Any],
    metadata: dict[str, typing.Any],
    deadline: float | None = None,
) -> None
Parámetros
capability_id
Identificador lógico de la capacidad.
payload
Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
metadata
Datos auxiliares de la llamada. execution_id está reservado al runtime.
deadline
Instante absoluto en el reloj monotónico del bucle de ejecución.
Atributos
capability_id: CapabilityId
Identificador lógico de la capacidad.
payload: dict[str, typing.Any]
Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
metadata: dict[str, typing.Any]
Datos auxiliares de la llamada. execution_id está reservado al runtime.
deadline: float | None
Instante absoluto en el reloj monotónico del bucle de ejecución.

InvocationStartEvent

Clase · Estable · agnara.execution

Evento de telemetría emitido al comenzar una invocación.

InvocationStartEvent(
    capability_id: CapabilityId,
    tracking_id: str | None,
    invocation_id: str,
    execution_id: str | None = None,
    parent_execution_id: str | None = None,
) -> None
Parámetros
capability_id
Identificador lógico de la capacidad.
tracking_id
Etiqueta opcional de correlación externa. No concede autoridad.
invocation_id
Identificador del intento de invocación observado.
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id
Identidad lógica de la ejecución padre, si existe.
Atributos
capability_id: CapabilityId
Identificador lógico de la capacidad.
tracking_id: str | None
Etiqueta opcional de correlación externa. No concede autoridad.
invocation_id: str
Identificador del intento de invocación observado.
execution_id: str | None
Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id: str | None
Identidad lógica de la ejecución padre, si existe.

InvocationTerminalEvent

Clase · Estable · agnara.execution

Evento de telemetría que identifica el final, duración y desenlace de una invocación.

InvocationTerminalEvent(
    capability_id: CapabilityId,
    tracking_id: str | None,
    duration_ns: int,
    outcome: str,
    invocation_id: str,
    units: int | None = None,
    execution_id: str | None = None,
    parent_execution_id: str | None = None,
) -> None
Parámetros
capability_id
Identificador lógico de la capacidad.
tracking_id
Etiqueta opcional de correlación externa. No concede autoridad.
duration_ns
Duración de la invocación en nanosegundos.
outcome
Desenlace de la invocación o resultado canónico que se proyecta.
invocation_id
Identificador del intento de invocación observado.
units
Cantidad de unidades del stream asociadas al evento terminal.
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id
Identidad lógica de la ejecución padre, si existe.
Atributos
capability_id: CapabilityId
Identificador lógico de la capacidad.
tracking_id: str | None
Etiqueta opcional de correlación externa. No concede autoridad.
duration_ns: int
Duración de la invocación en nanosegundos.
outcome: str
Desenlace de la invocación o resultado canónico que se proyecta.
invocation_id: str
Identificador del intento de invocación observado.
units: int | None
Cantidad de unidades del stream asociadas al evento terminal.
execution_id: str | None
Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id: str | None
Identidad lógica de la ejecución padre, si existe.

StreamInterrupted

Excepción · Estable · agnara.execution

Excepción de consumo que lleva el fallo canónico y el número de unidades ya entregadas.

StreamInterrupted(failure: Failure, units_emitted: int) -> None
Parámetros
failure
Fallo canónico que explica la interrupción o se proyecta al adaptador.
units_emitted
Cantidad de unidades entregadas antes de detenerse.
Atributos
failure: Failure
Fallo canónico que explica la interrupción o se proyecta al adaptador.
units_emitted: int
Cantidad de unidades entregadas antes de detenerse.

StreamTerminal

Enumeración · Estable · agnara.execution

Describe la forma en que acabó un stream.

COMPLETED = 'completed'
El productor terminó normalmente.
INTERRUPTED = 'interrupted'
La producción se interrumpió por un fallo.
CANCELLED = 'cancelled'
Se canceló el consumo o la ejecución.
TIMED_OUT = 'timed_out'
Se agotó el plazo del stream.
ABANDONED = 'abandoned'
El consumidor cerró el stream antes de agotarlo.

Success

Clase · Estable · agnara.execution

Resultado canónico satisfactorio con el valor producido y una identidad de ejecución opcional.

Success(value: T, execution_id: str | None = None) -> None
Parámetros
value
Valor satisfactorio producido por el handler.
execution_id
Identidad lógica opaca que asigna o recupera el runtime.
Atributos
value: T
Valor satisfactorio producido por el handler.
execution_id: str | None
Identidad lógica opaca que asigna o recupera el runtime.

TelemetryHook

Protocolo · Estable · agnara.execution

Protocolo síncrono para observar el inicio y el final de una invocación.

TelemetryHook.on_invocation_start Método

on_invocation_start(event: InvocationStartEvent) -> None

Recibe el evento previo a la adquisición de dependencias.

event
Evento de telemetría entregado al observador.

TelemetryHook.on_invocation_terminal Método

on_invocation_terminal(event: InvocationTerminalEvent) -> None

Recibe el evento de finalización con desenlace y duración.

event
Evento de telemetría entregado al observador.

classify_failure

Función · Estable · agnara.execution

Convierte una excepción en un fallo canónico y evita exponer diagnósticos internos de errores inesperados.

classify_failure(error: Exception, capability_id: CapabilityId) -> Failure
Parámetros
error
Excepción que se clasifica en el límite. La cancelación se propaga por separado.
capability_id
Identificador lógico de la capacidad.

invoke

Función asíncrona · Estable · agnara.execution

Ejecuta un plan con semántica ordinaria de Python. Devuelve el valor o propaga la excepción. Usa invoke_result() si el adaptador necesita un resultado canónico.

async invoke(plan: ExecutionPlan, context: ExecutionContext) -> Any
Parámetros
plan
Plan compilado que se va a ejecutar.
context
Contexto de la invocación que se va a evaluar o ejecutar.

invoke_result

Función asíncrona · Estable · agnara.execution

Ejecuta políticas, validación, dependencias y handler para una capacidad de resultado completo. Devuelve Success o Failure. La cancelación del llamador se propaga.

async invoke_result(
    plan: ExecutionPlan,
    context: ExecutionContext,
    *,
    input_materializer: Callable[[TypeSchema, object], object] | None = None,
) -> CanonicalResult[T]
Parámetros
plan
Plan compilado que se va a ejecutar.
context
Contexto de la invocación que se va a evaluar o ejecutar.
input_materializer
Conversión de datos del límite de transporte a valores de entrada Python.

Un fallo inesperado se convierte en INTERNAL_FAILURE con mensaje redactado. Un plazo agotado se representa como TIMEOUT. La cancelación del llamador sigue siendo CancelledError.

open_stream

Función · Estable · agnara.execution

Prepara el contexto asíncrono de un stream. Entra con async with y consume con async for para liberar los recursos incluso al terminar temprano.

open_stream(
    plan: ExecutionPlan,
    context: ExecutionContext,
    *,
    input_materializer: Callable[[TypeSchema, object], object] | None = None,
) -> CapabilityStream
Parámetros
plan
Plan compilado que se va a ejecutar.
context
Contexto de la invocación que se va a evaluar o ejecutar.
input_materializer
Conversión de datos del límite de transporte a valores de entrada Python.

El plazo alcanza la obtención de unidades. Los fallos posteriores al inicio pueden llegar como StreamInterrupted. El contexto asíncrono cierra el productor si se abandona la iteración.

5. Exposiciones compiladas

agnara.exposure · 7 exportaciones

Una exposición describe cómo se alcanza una capacidad en una superficie. El registro agregado permite consultar las superficies sin convertir el transporte en la definición de negocio.

Guía relacionada · API_DESIGN.md

CompiledExposure · ExposureError · ExposureId · FrozenExposureRegistry · SurfaceCompilation · SurfaceId · compile_exposures

CompiledExposure

Clase · Estable · agnara.exposure

Registro de una capacidad alcanzable a través de un destino de un adaptador, con detalles neutrales publicables.

CompiledExposure(
    id: ExposureId,
    capability_id: CapabilityId,
    detail: str = '{}',
) -> None
Parámetros
id
Identificador del registro. Su tipo depende de la entidad.
capability_id
Identificador lógico de la capacidad.
detail
Detalle de exposición aportado por el adaptador como datos.
Atributos
id: ExposureId
Identificador del registro. Su tipo depende de la entidad.
capability_id: CapabilityId
Identificador lógico de la capacidad.
detail: str
Detalle de exposición aportado por el adaptador como datos.

CompiledExposure.of Método

of(
    surface: SurfaceId,
    name: str,
    capability_id: CapabilityId,
    detail: object = None,
) -> CompiledExposure

Construye una exposición y normaliza los detalles aportados por el adaptador.

surface
Identidad o nombre de la superficie que sirve la exposición.
name
Nombre lógico de la entidad que se declara, describe o publica.
capability_id
Identificador lógico de la capacidad.
detail
Detalle de exposición aportado por el adaptador como datos.

CompiledExposure.surface Propiedad

Identidad de la superficie del adaptador que ofrece el destino. SurfaceId

CompiledExposure.published_detail Método

published_detail() -> dict[str, Any]

Devuelve los detalles publicables como datos JSON e incluye el nombre de la superficie.

ExposureError

Excepción · Estable · agnara.exposure

La declaración o combinación de exposiciones no satisface el contrato.

ExposureId

Clase · Estable · agnara.exposure

Identifica un destino dentro de una superficie de un adaptador.

ExposureId(surface: SurfaceId, name: str) -> None
Parámetros
surface
Identidad o nombre de la superficie que sirve la exposición.
name
Nombre lógico de la entidad que se declara, describe o publica.
Atributos
surface: SurfaceId
Identidad o nombre de la superficie que sirve la exposición.
name: str
Nombre lógico de la entidad que se declara, describe o publica.

ExposureId.adapter Propiedad

Protocolo al que pertenece este destino. str

FrozenExposureRegistry

Clase · Estable · agnara.exposure

Vista inmutable y ordenada de las exposiciones compiladas de un proyecto.

FrozenExposureRegistry(exposures: Iterable[CompiledExposure] = ()) -> None
Parámetros
exposures
Colección de destinos compilados de la superficie o del proyecto.

FrozenExposureRegistry.__getitem__ Método

__getitem__(key: ExposureId) -> CompiledExposure

Busca un elemento por su clave.

key
Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.

FrozenExposureRegistry.__iter__ Método

__iter__() -> Iterator[ExposureId]

Recorre las claves de la colección.

FrozenExposureRegistry.__len__ Método

__len__() -> int

Devuelve la cantidad de declaraciones o elementos de la colección.

FrozenExposureRegistry.surfaces Propiedad

Superficies que aportaron exposiciones, en el orden de agregación. tuple[SurfaceId, ...]

FrozenExposureRegistry.for_capability Método

for_capability(capability_id: CapabilityId) -> tuple[CompiledExposure, ...]

Filtra los destinos compilados de la capacidad.

capability_id
Identificador lógico de la capacidad.

FrozenExposureRegistry.on_surface Método

on_surface(surface: SurfaceId) -> tuple[CompiledExposure, ...]

Filtra los destinos de la superficie en su orden de emisión.

surface
Identidad o nombre de la superficie que sirve la exposición.

FrozenExposureRegistry.transports Método

transports(capability_id: CapabilityId) -> tuple[str, ...]

Devuelve los protocolos de exposición sin repeticiones y en orden de aparición.

capability_id
Identificador lógico de la capacidad.

SurfaceCompilation

Clase · Estable · agnara.exposure

Agrupa el artefacto operativo de una superficie y los registros neutrales que aporta.

SurfaceCompilation(
    surface: SurfaceId,
    runtime: RuntimeT,
    exposures: tuple[CompiledExposure, ...] = (),
) -> None
Parámetros
surface
Identidad o nombre de la superficie que sirve la exposición.
runtime
Artefacto de ejecución de la superficie o runtime compilado que despacha la invocación.
exposures
Colección de destinos compilados de la superficie o del proyecto.
Atributos
surface: SurfaceId
Identidad o nombre de la superficie que sirve la exposición.
runtime: RuntimeT
Artefacto de ejecución de la superficie o runtime compilado que despacha la invocación.
exposures: tuple[CompiledExposure, ...]
Colección de destinos compilados de la superficie o del proyecto.

SurfaceId

Clase · Estable · agnara.exposure

Identifica una superficie por adaptador y nombre.

SurfaceId(adapter: str, name: str) -> None
Parámetros
adapter
Identificador del adaptador o protocolo al que pertenece la superficie.
name
Nombre lógico de la entidad que se declara, describe o publica.
Atributos
adapter: str
Identificador del adaptador o protocolo al que pertenece la superficie.
name: str
Nombre lógico de la entidad que se declara, describe o publica.

compile_exposures

Función · Estable · agnara.exposure

Reúne las superficies compiladas y comprueba que sus destinos pertenezcan al conjunto de capacidades del proyecto.

compile_exposures(
    capabilities: FrozenCapabilityRegistry,
    compilations: Iterable[SurfaceCompilation[Any]] = (),
) -> FrozenExposureRegistry
Parámetros
capabilities
Conjunto de capacidades declaradas o compiladas que delimita la composición.
compilations
Artefactos de las superficies ya compiladas.

6. Introspección y publicación

agnara.introspection · 23 exportaciones

Describe aplicaciones compiladas, aplica visibilidad para el lector y serializa el resultado filtrado. El permiso para descubrir una capacidad es independiente de su permiso de ejecución.

Guía relacionada · INTROSPECTION.md

INTROSPECTION_FORMAT · INTROSPECTION_VERSION · AllCapabilitiesVisible · ApplicationDescriptor · BoundedContextDescriptor · CapabilityDescriptor · DependencyDescriptor · DiscoveryField · DiscoveryVisibility · ExposureDescriptor · Hiding · InputDescriptor · IntrospectionError · IntrospectionSnapshot · NoCapabilityVisible · PolicyDescriptor · ProviderDescriptor · ScopeVisible · TypeReference · VisibilityRule · describe_app · filter_snapshot · snapshot

INTROSPECTION_FORMAT

Constante · Estable · agnara.introspection

Identificador del formato de instantáneas de introspección.

INTROSPECTION_FORMAT = 'agnara-introspection'

INTROSPECTION_VERSION

Constante · Estable · agnara.introspection

Versión del formato de introspección, independiente de la versión del paquete.

INTROSPECTION_VERSION = '1'

AllCapabilitiesVisible

Clase · Estable · agnara.introspection

Regla que hace visible toda capacidad a cualquier lector. Útil para desarrollo y herramientas locales.

AllCapabilitiesVisible() -> None

AllCapabilitiesVisible.visible Método

visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool

Autoriza el descubrimiento para cualquier lector.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

ApplicationDescriptor

Clase · Estable · agnara.introspection

Descripción de una aplicación compilada con capacidades, proveedores y contextos montados.

ApplicationDescriptor(
    name: str,
    capabilities: tuple[CapabilityDescriptor, ...] = (),
    providers: tuple[ProviderDescriptor, ...] = (),
    apps: tuple[BoundedContextDescriptor, ...] = (),
) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
capabilities
Conjunto de capacidades declaradas o compiladas que delimita la composición.
providers
Descriptores del grafo de proveedores.
apps
Contextos delimitados montados.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
capabilities: tuple[CapabilityDescriptor, ...]
Conjunto de capacidades declaradas o compiladas que delimita la composición.
providers: tuple[ProviderDescriptor, ...]
Descriptores del grafo de proveedores.
apps: tuple[BoundedContextDescriptor, ...]
Contextos delimitados montados.

ApplicationDescriptor.transports Propiedad

Devuelve los protocolos de exposición sin repeticiones y en orden de aparición. tuple[str, ...]

ApplicationDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

BoundedContextDescriptor

Clase · Estable · agnara.introspection

Descripción de un contexto delimitado montado en una aplicación.

BoundedContextDescriptor(name: str, description: str | None = None) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
description: str | None
Descripción que acompaña a la declaración. Su publicación depende de la superficie.

BoundedContextDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

CapabilityDescriptor

Clase · Estable · agnara.introspection

Metadatos de una capacidad compilada para descubrimiento. El descriptor no transporta la función ejecutable.

CapabilityDescriptor(
    id: str,
    description: str | None = None,
    effects: tuple[str, ...] = (),
    scopes: tuple[str, ...] = (),
    risk: str = 'low',
    confirmation: str = 'never',
    idempotency: str = 'unknown',
    inputs: tuple[InputDescriptor, ...] = (),
    dependencies: tuple[DependencyDescriptor, ...] = (),
    policies: tuple[PolicyDescriptor, ...] = (),
    exposures: tuple[ExposureDescriptor, ...] = (),
) -> None
Parámetros
id
Identificador del registro. Su tipo depende de la entidad.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects
Conjunto de etiquetas que describe los efectos de la capacidad.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk
Clasificación del impacto potencial de una invocación incorrecta.
confirmation
Régimen de confirmación declarado para la capacidad.
idempotency
Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
inputs
Descriptores de entrada publicables.
dependencies
Registro de dependencias para composición o descriptores de dependencias en introspección.
policies
Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
exposures
Colección de destinos compilados de la superficie o del proyecto.
Atributos
id: str
Identificador del registro. Su tipo depende de la entidad.
description: str | None
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects: tuple[str, ...]
Conjunto de etiquetas que describe los efectos de la capacidad.
scopes: tuple[str, ...]
Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk: str
Clasificación del impacto potencial de una invocación incorrecta.
confirmation: str
Régimen de confirmación declarado para la capacidad.
idempotency: str
Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
inputs: tuple[InputDescriptor, ...]
Descriptores de entrada publicables.
dependencies: tuple[DependencyDescriptor, ...]
Registro de dependencias para composición o descriptores de dependencias en introspección.
policies: tuple[PolicyDescriptor, ...]
Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
exposures: tuple[ExposureDescriptor, ...]
Colección de destinos compilados de la superficie o del proyecto.

CapabilityDescriptor.transports Propiedad

Devuelve los protocolos de exposición sin repeticiones y en orden de aparición. tuple[str, ...]

CapabilityDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

DependencyDescriptor

Clase · Estable · agnara.introspection

Describe por nombre y tipo una dependencia declarada por una capacidad.

DependencyDescriptor(parameter: str, type: TypeReference) -> None
Parámetros
parameter
Nombre del parámetro de la función que solicita la dependencia.
type
Referencia descriptiva del tipo solicitado.
Atributos
parameter: str
Nombre del parámetro de la función que solicita la dependencia.
type: TypeReference
Referencia descriptiva del tipo solicitado.

DependencyDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

DiscoveryField

Enumeración · Estable · agnara.introspection

Enumera los campos de descubrimiento que pueden habilitarse de forma independiente.

DESCRIPTION = 'description'
Descripción textual.
EFFECTS = 'effects'
Etiquetas de efectos.
SCOPES = 'scopes'
Permisos declarados.
SAFETY = 'safety'
Metadatos de riesgo, confirmación e idempotencia.
INPUTS = 'inputs'
Parámetros de entrada y sus esquemas.
DEPENDENCIES = 'dependencies'
Dependencias declaradas por capacidades.
PROVIDERS = 'providers'
Descriptores de proveedores.
APPS = 'apps'
Contextos delimitados montados.
POLICIES = 'policies'
Tipos de políticas adjuntas.
EXPOSURES = 'exposures'
Destinos de los adaptadores.
EXPOSURE_DETAIL = 'exposure_detail'
Detalles adicionales de los destinos.
TYPE_MODULES = 'type_modules'
Nombres de módulo de los tipos.

DiscoveryVisibility

Clase · Estable · agnara.introspection

Combina una regla de acceso con el conjunto de campos a publicar.

DiscoveryVisibility(
    rule: VisibilityRule,
    published: Iterable[DiscoveryField | str],
) -> None
Parámetros
rule
Regla que decide qué capacidades son visibles para el lector.
published
Campos que la decisión de descubrimiento permite publicar.
Atributos
rule: VisibilityRule
Regla que decide qué capacidades son visibles para el lector.
published: frozenset[DiscoveryField]
Campos que la decisión de descubrimiento permite publicar.

DiscoveryVisibility.publishes Método

publishes(field: DiscoveryField) -> bool

Comprueba si la configuración habilita la publicación de ese campo.

field
Campo de descubrimiento que se consulta.

DiscoveryVisibility.identity_only Método

identity_only(rule: VisibilityRule) -> DiscoveryVisibility

Publica la identidad de las capacidades que admite la regla.

rule
Regla que decide la visibilidad de una capacidad.

DiscoveryVisibility.agent_safe Método

agent_safe(rule: VisibilityRule) -> DiscoveryVisibility

Habilita campos para que un agente pueda elegir y utilizar las capacidades visibles.

rule
Regla que decide la visibilidad de una capacidad.

DiscoveryVisibility.unrestricted Método

unrestricted(rule: VisibilityRule) -> DiscoveryVisibility

Habilita todos los campos. Adecuado para herramientas locales y desarrollo controlado.

rule
Regla que decide la visibilidad de una capacidad.

ExposureDescriptor

Clase · Estable · agnara.introspection

Vista serializable de un destino publicado por un adaptador.

ExposureDescriptor(transport: str, name: str, detail: str = '{}') -> None
Parámetros
transport
Nombre del protocolo de una exposición.
name
Nombre lógico de la entidad que se declara, describe o publica.
detail
Detalle de exposición aportado por el adaptador como datos.
Atributos
transport: str
Nombre del protocolo de una exposición.
name: str
Nombre lógico de la entidad que se declara, describe o publica.
detail: str
Detalle de exposición aportado por el adaptador como datos.

ExposureDescriptor.of Método

of(transport: str, name: str, detail: object = None) -> ExposureDescriptor

Construye un descriptor neutral desde protocolo, nombre y detalle publicable.

transport
Nombre del protocolo de una exposición.
name
Nombre lógico de la entidad que se declara, describe o publica.
detail
Detalle de exposición aportado por el adaptador como datos.

ExposureDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

Hiding

Clase · Estable · agnara.introspection

Oculta identificadores concretos y delega el resto de la decisión a otra regla.

Hiding(ids: Iterable[str], rule: VisibilityRule) -> None
Parámetros
ids
Identificadores que la regla oculta.
rule
Regla que decide la visibilidad de una capacidad.
Atributos
ids: frozenset[str]
Identificadores que la regla oculta.
rule: VisibilityRule
Regla que decide la visibilidad de una capacidad.

Hiding.visible Método

visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool

Rechaza identificadores ocultos y aplica la regla de respaldo a los demás.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

InputDescriptor

Clase · Estable · agnara.introspection

Describe un argumento de entrada, su obligatoriedad y su esquema publicado.

InputDescriptor(name: str, required: bool, schema: str) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
required
Indica si la entrada es obligatoria.
schema
Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
required: bool
Indica si la entrada es obligatoria.
schema: str
Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.

InputDescriptor.of Método

of(name: str, *, required: bool, schema: object) -> InputDescriptor

Construye un descriptor de entrada con su obligatoriedad y esquema.

name
Nombre lógico de la entidad que se declara, describe o publica.
required
Indica si la entrada es obligatoria.
schema
Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.

InputDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

IntrospectionError

Excepción · Estable · agnara.introspection

No se pudo construir una instantánea a partir de la superficie compilada proporcionada.

IntrospectionSnapshot

Clase · Estable · agnara.introspection

Vista inmutable y versionada de las aplicaciones compiladas de un proyecto.

IntrospectionSnapshot(
    applications: tuple[ApplicationDescriptor, ...] = (),
    project: str | None = None,
    format: str = 'agnara-introspection',
    version: str = '1',
    filtered: bool = False,
) -> None
Parámetros
applications
Descriptores de las aplicaciones incluidas.
project
Identificador del proyecto de introspección.
format
Identificador del formato serializado.
version
Versión anunciada por el documento, agente, servidor o formato.
filtered
Indica si la instantánea ya se filtró para su publicación.
Atributos
applications: tuple[ApplicationDescriptor, ...]
Descriptores de las aplicaciones incluidas.
project: str | None
Identificador del proyecto de introspección.
format: str
Identificador del formato serializado.
version: str
Versión anunciada por el documento, agente, servidor o formato.
filtered: bool
Indica si la instantánea ya se filtró para su publicación.

IntrospectionSnapshot.transports Propiedad

Devuelve los protocolos de exposición sin repeticiones y en orden de aparición. tuple[str, ...]

IntrospectionSnapshot.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

NoCapabilityVisible

Clase · Estable · agnara.introspection

Regla que oculta todas las capacidades.

NoCapabilityVisible() -> None

NoCapabilityVisible.visible Método

visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool

Deniega el descubrimiento para cualquier lector.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

PolicyDescriptor

Clase · Estable · agnara.introspection

Identifica el tipo de una política sin exponer su configuración ejecutable.

PolicyDescriptor(kind: str) -> None
Parámetros
kind
Categoría de interacción, proveedor o descriptor según el tipo indicado.
Atributos
kind: str
Categoría de interacción, proveedor o descriptor según el tipo indicado.

PolicyDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

ProviderDescriptor

Clase · Estable · agnara.introspection

Describe un proveedor como nodo del grafo de dependencias sin incluir su función.

ProviderDescriptor(
    provides: TypeReference,
    scope: str,
    kind: str,
    requires: tuple[TypeReference, ...] = (),
) -> None
Parámetros
provides
Tipo que suministra la asociación.
scope
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
kind
Categoría de interacción, proveedor o descriptor según el tipo indicado.
requires
Tipos que el proveedor necesita para construirse.
Atributos
provides: TypeReference
Tipo que suministra la asociación.
scope: str
Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
kind: str
Categoría de interacción, proveedor o descriptor según el tipo indicado.
requires: tuple[TypeReference, ...]
Tipos que el proveedor necesita para construirse.

ProviderDescriptor.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

ScopeVisible

Clase · Estable · agnara.introspection

Solo permite descubrir capacidades cuyos permisos declarados están presentes en la identidad del lector.

ScopeVisible() -> None

ScopeVisible.visible Método

visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool

Autoriza el descubrimiento cuando el lector posee los permisos declarados.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

TypeReference

Clase · Estable · agnara.introspection

Representación descriptiva del nombre de un tipo sin conservar el objeto Python.

TypeReference(name: str, module: str | None = None) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
module
Nombre de módulo de procedencia que puede aparecer en el descriptor.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
module: str | None
Nombre de módulo de procedencia que puede aparecer en el descriptor.

TypeReference.of Método

of(annotation: type) -> TypeReference

Describe la anotación por nombre sin conservar el objeto Python.

annotation
Anotación de tipo Python que se describe o compila.

TypeReference.json_data Método

json_data() -> dict[str, Any]

Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.

VisibilityRule

Protocolo · Estable · agnara.introspection

Protocolo para decidir si un lector puede descubrir una capacidad.

VisibilityRule.visible Método

visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool

Decide si la identidad indicada puede descubrir la capacidad.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

describe_app

Función · Estable · agnara.introspection

Construye descriptores de una aplicación a partir de sus planes y datos de composición.

describe_app(
    app: Agnara,
    plans: Iterable[ExecutionPlan],
    *,
    exposures: ExposureSource | None = None,
    dependencies: DIRegistry | None = None,
) -> ApplicationDescriptor
Parámetros
app
Aplicación o contexto que posee las declaraciones.
plans
Planes compilados que la superficie puede despachar o describir.
exposures
Colección de destinos compilados de la superficie o del proyecto.
dependencies
Registro de dependencias para composición o descriptores de dependencias en introspección.

filter_snapshot

Función · Estable · agnara.introspection

Aplica visibilidad y selección de campos antes de serializar una instantánea para un lector.

filter_snapshot(
    snapshot: IntrospectionSnapshot,
    visibility: DiscoveryVisibility,
    principal: Principal,
) -> IntrospectionSnapshot
Parámetros
snapshot
Instantánea de introspección que se filtra o publica.
visibility
Regla de visibilidad y selección de campos para la instantánea.
principal
Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.

Aplica este filtro antes de usar json_data() para un lector externo. La publicación de un identificador o una etiqueta no concede autoridad.

snapshot

Función · Estable · agnara.introspection

Combina descriptores de aplicaciones en una instantánea versionada.

snapshot(
    applications: Iterable[ApplicationDescriptor],
    *,
    project: str | None = None,
) -> IntrospectionSnapshot
Parámetros
applications
Descriptores de las aplicaciones incluidas.
project
Identificador del proyecto de introspección.

7. Confirmación de invocaciones

agnara.policy · 1 exportaciones

La evidencia llega desde el host y un verificador la vincula a la invocación. El llamador puede recibir una solicitud de interacción cuando falta una confirmación válida.

Guía relacionada · CONFIRMATION.md

ConfirmationPolicy

ConfirmationPolicy

Clase · Estable · agnara.policy

Política que exige evidencia verificada para continuar. Puede devolver una solicitud de interacción.

ConfirmationPolicy(capability_id: CapabilityId, verifier: ConfirmationVerifier) -> None
Parámetros
capability_id
Identificador lógico de la capacidad.
verifier
Autoridad de la aplicación que comprueba evidencia de confirmación.
Atributos
capability_id: CapabilityId
Identificador lógico de la capacidad.
verifier: ConfirmationVerifier
Autoridad de la aplicación que comprueba evidencia de confirmación.
request: InteractionRequest
Solicitud de interacción que explica al llamador cómo continuar.

ConfirmationPolicy.evaluate Método

async evaluate(context: ExecutionContext) -> PolicyResult

Consulta la evidencia y su verificador. Si se requiere interacción, detiene la invocación y devuelve la solicitud correspondiente.

context
Contexto de la invocación que se va a evaluar o ejecutar.

8. Esquemas y datos JSON

agnara.schema · 13 exportaciones

La validación directa comprueba tipos Python. En el límite de un transporte, la materialización explícita puede convertir estructuras JSON a dataclasses, tuplas o miembros de enum. La proyección JSON realiza la operación de salida.

Guía relacionada · SCHEMA_CONTRACTS.md

AnySchema · DataclassFieldSchema · DataclassSchema · DictionarySchema · EnumSchema · ListSchema · LiteralSchema · NoneSchema · PrimitiveSchema · TupleSchema · UnionSchema · materialize_json · serialize_json

AnySchema

Clase · Estable · agnara.schema

Esquema que admite cualquier valor Python.

AnySchema() -> None

AnySchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

AnySchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

DataclassFieldSchema

Clase · Estable · agnara.schema

Describe un campo de dataclass con su esquema recursivo y su obligatoriedad.

DataclassFieldSchema(name: str, schema: TypeSchema, required: bool) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
schema
Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
required
Indica si la entrada es obligatoria.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
schema: TypeSchema
Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
required: bool
Indica si la entrada es obligatoria.

DataclassSchema

Clase · Estable · agnara.schema

Comprueba instancias de una dataclass y los valores de sus campos.

DataclassSchema(dataclass_type: type, fields: tuple[DataclassFieldSchema, ...]) -> None
Parámetros
dataclass_type
Clase dataclass concreta que admite el esquema.
fields
Campos compilados de la dataclass.
Atributos
dataclass_type: type
Clase dataclass concreta que admite el esquema.
fields: tuple[DataclassFieldSchema, ...]
Campos compilados de la dataclass.

DataclassSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

DataclassSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

DictionarySchema

Clase · Estable · agnara.schema

Comprueba un diccionario de claves de texto con un esquema homogéneo para los valores.

DictionarySchema(value_schema: TypeSchema) -> None
Parámetros
value_schema
Esquema común de los valores del diccionario.
Atributos
value_schema: TypeSchema
Esquema común de los valores del diccionario.

DictionarySchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

DictionarySchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

EnumSchema

Clase · Estable · agnara.schema

Comprueba miembros de una enumeración específica y proyecta los valores representables en JSON.

EnumSchema(enum_type: type[Enum], values: tuple[object, ...]) -> None
Parámetros
enum_type
Clase de enumeración admitida por el esquema.
values
Valores admitidos por la enumeración o literal.
Atributos
enum_type: type[Enum]
Clase de enumeración admitida por el esquema.
values: tuple[object, ...]
Valores admitidos por la enumeración o literal.

EnumSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

EnumSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

ListSchema

Clase · Estable · agnara.schema

Comprueba una lista y valida cada elemento con el mismo esquema.

ListSchema(item_schema: TypeSchema) -> None
Parámetros
item_schema
Esquema que se aplica a cada elemento.
Atributos
item_schema: TypeSchema
Esquema que se aplica a cada elemento.

ListSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

ListSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

LiteralSchema

Clase · Estable · agnara.schema

Admite una selección finita de escalares exactos compatibles con JSON.

LiteralSchema(values: tuple[object, ...]) -> None
Parámetros
values
Valores admitidos por la enumeración o literal.
Atributos
values: tuple[object, ...]
Valores admitidos por la enumeración o literal.

LiteralSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

LiteralSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

NoneSchema

Clase · Estable · agnara.schema

Admite únicamente None.

NoneSchema() -> None

NoneSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

NoneSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

PrimitiveSchema

Clase · Estable · agnara.schema

Comprueba que el valor tenga exactamente el tipo primitivo indicado.

PrimitiveSchema(python_type: type) -> None
Parámetros
python_type
Tipo primitivo exacto que exige el esquema.

Los tipos se comprueban de forma exacta. Por ejemplo, True no satisface un contrato int.

Atributos
python_type: type
Tipo primitivo exacto que exige el esquema.

PrimitiveSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

PrimitiveSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

TupleSchema

Clase · Estable · agnara.schema

Comprueba una tupla fija por posición o una tupla variádica con elementos homogéneos.

TupleSchema(item_schemas: tuple[TypeSchema, ...], variadic: bool = False) -> None
Parámetros
item_schemas
Esquemas por posición o esquema repetido de la tupla.
variadic
Distingue una tupla homogénea de longitud variable de una tupla posicional.
Atributos
item_schemas: tuple[TypeSchema, ...]
Esquemas por posición o esquema repetido de la tupla.
variadic: bool
Distingue una tupla homogénea de longitud variable de una tupla posicional.

TupleSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

TupleSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

UnionSchema

Clase · Estable · agnara.schema

Admite un valor aceptado por al menos uno de los esquemas de la unión.

UnionSchema(choices: tuple[TypeSchema, ...]) -> None
Parámetros
choices
Esquemas alternativos que acepta la unión.
Atributos
choices: tuple[TypeSchema, ...]
Esquemas alternativos que acepta la unión.

UnionSchema.validate Método

validate(value: object) -> Any

Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.

value
Valor que se valida, contiene o transforma.

UnionSchema.json_schema Método

json_schema() -> JsonSchema

Proyecta el esquema compilado a datos JSON Schema.

materialize_json

Función · Estable · agnara.schema

Convierte datos JSON ya decodificados en valores Python para un esquema compatible. Por ejemplo, puede construir la dataclass que espera un handler.

materialize_json(schema: TypeSchema, value: object) -> Any
Parámetros
schema
Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
value
Valor que se valida, contiene o transforma.

Espera un valor JSON ya decodificado. Puede materializar una dataclass, tupla o enum antes de validar. Un esquema no reconocido recibe el valor sin conversión.

serialize_json

Función · Estable · agnara.schema

Proyecta un valor de Python a datos JSON. Devuelve los datos estructurados para el codificador, no una cadena JSON.

serialize_json(value: object) -> Any
Parámetros
value
Valor que se valida, contiene o transforma.

Emite objetos y arrays JSON como estructuras Python. Lanza ValidationError para valores incompatibles, números no finitos, claves de objeto ajenas a str o ciclos. La profundidad está acotada.

9. Adaptador HTTP

agnara_http · 14 exportaciones

Registra rutas con bindings explícitos y compílalas antes de servir. El servidor ASGI gestiona lifespan. OpenAPI, sus interfaces web y Explorer se habilitan de forma explícita con sus propios controles de publicación.

Guía relacionada · HTTP_COMPOSITION.md

Binding · BindingSource · DocumentationAssets · Http · HttpApplication · HttpDefinitionError · HttpDocumentation · HttpExplorer · OpenApiInfo · OpenApiOperation · OpenApiSchema · ReDoc · Scalar · SwaggerUI

Binding

Clase · Estable · agnara_http

Indica de qué parte de una petición HTTP procede un argumento de la capacidad.

Binding(input_name: str, source: BindingSource, *, wire_name: str | None = None) -> None
Parámetros
input_name
Parámetro de capacidad que se llena desde la petición.
source
Ubicación de la petición desde la que se lee el argumento.
wire_name
Nombre en la petición cuando difiere del parámetro de capacidad.

Binding.input_name Propiedad

Parámetro de capacidad que se llena desde la petición. str

Binding.source Propiedad

Ubicación de la petición desde la que se lee el argumento. BindingSource

Binding.wire_name Propiedad

Nombre en la petición cuando difiere del parámetro de capacidad. str | None

BindingSource

Enumeración · Estable · agnara_http

Enumera las fuentes HTTP admitidas para rellenar argumentos de una capacidad.

PATH = 'path'
Parámetro extraído de la ruta.
QUERY = 'query'
Parámetro extraído de la cadena de consulta.
HEADER = 'header'
Valor extraído de una cabecera.
BODY = 'body'
Valor leído del cuerpo JSON.
COOKIE = 'cookie'
Valor leído de una cookie.
FORM = 'form'
Campo de un formulario.
UPLOAD = 'upload'
Archivo recibido mediante un formulario multipart.

DocumentationAssets

Clase · Estable · agnara_http

Elige recursos locales verificados o habilita explícitamente orígenes HTTPS para recursos CDN fijados.

DocumentationAssets(
    allowed_remote_origins: frozenset[str] = frozenset(),
    remote_assets: bool = False,
) -> None
Parámetros
allowed_remote_origins
Orígenes HTTPS exactos que pueden proporcionar los recursos remotos fijados.
remote_assets
Selección explícita de recursos remotos.
Atributos
allowed_remote_origins: frozenset[str]
Orígenes HTTPS exactos que pueden proporcionar los recursos remotos fijados.
remote_assets: bool
Selección explícita de recursos remotos.

DocumentationAssets.local Método

local() -> Self

Selecciona recursos locales verificados por hash.

DocumentationAssets.remote Método

remote(*origins: str) -> Self

Habilita recursos CDN fijados cuando coinciden con un origen HTTPS explícito.

origins
Orígenes HTTPS explícitos habilitados para recursos remotos.

Http

Clase · Estable · agnara_http

Declara rutas de una superficie HTTP y las compila en una aplicación ASGI inmutable. Los bindings son explícitos.

Http(surface: str = 'default') -> None
Parámetros
surface
Identidad o nombre de la superficie que sirve la exposición.

Declara la relación entre método, ruta y capacidad en el adaptador. Las rutas publicadas en OpenAPI se seleccionan explícitamente.

Http.surface Propiedad

Identidad de esta superficie HTTP para el registro de exposiciones. SurfaceId

Http.is_compiled Propiedad

Indica que se cerró la declaración de rutas. bool

Http.route Método

route(
    method: str,
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    openapi: OpenApiOperation | None = None,
    max_body_bytes: int | None = None,
    max_parts: int | None = None,
) -> Self

Registra la ruta con método y bindings explícitos para la capacidad indicada.

method
Método HTTP de la ruta.
path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes
Tamaño máximo del cuerpo admitido en bytes.
max_parts
Número máximo de partes permitido para multipart.

Http.get Método

get(
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    openapi: OpenApiOperation | None = None,
) -> Self

Registra una ruta GET. El compilador también proporciona HEAD.

path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.

Http.post Método

post(
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    openapi: OpenApiOperation | None = None,
    max_body_bytes: int | None = None,
    max_parts: int | None = None,
) -> Self

Registra una ruta POST y permite limitar el cuerpo y sus partes.

path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes
Tamaño máximo del cuerpo admitido en bytes.
max_parts
Número máximo de partes permitido para multipart.

Http.put Método

put(
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    openapi: OpenApiOperation | None = None,
    max_body_bytes: int | None = None,
    max_parts: int | None = None,
) -> Self

Registra una ruta PUT y permite limitar el cuerpo y sus partes.

path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes
Tamaño máximo del cuerpo admitido en bytes.
max_parts
Número máximo de partes permitido para multipart.

Http.patch Método

patch(
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    openapi: OpenApiOperation | None = None,
    max_body_bytes: int | None = None,
    max_parts: int | None = None,
) -> Self

Registra una ruta PATCH y permite limitar el cuerpo y sus partes.

path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes
Tamaño máximo del cuerpo admitido en bytes.
max_parts
Número máximo de partes permitido para multipart.

Http.delete Método

delete(
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    openapi: OpenApiOperation | None = None,
) -> Self

Registra una ruta DELETE.

path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.

Http.sse Método

sse(
    path: str,
    capability: CapabilityRef,
    *bindings: Binding,
    max_event_bytes: int | None = None,
) -> Self

Expone una capacidad de streaming en GET como eventos SSE.

path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability
Capacidad seleccionada o descriptor que evalúa la regla.
bindings
Asignaciones de partes de la petición a entradas de la capacidad.
max_event_bytes
Tamaño máximo de un evento SSE en bytes.

Http.compile Método

compile(
    capabilities: FrozenCapabilityRegistry,
    *,
    dependencies: DIRegistry | None = None,
    openapi: OpenApiInfo | None = None,
    openapi_path: str | None = None,
    documentation: HttpDocumentation | None = None,
    explorer: HttpExplorer | None = None,
    lifecycle: Lifecycle | None = None,
    request_timeout: float | None = None,
    problem_base_uri: str | None = None,
    hooks: Sequence[TelemetryHook] = (),
    confirmation_verifier: ConfirmationVerifier | None = None,
    schema_adapter: SchemaAdapter | None = None,
) -> HttpApplication

Valida rutas y dependencias y construye una aplicación ASGI inmutable.

capabilities
Conjunto de capacidades declaradas o compiladas que delimita la composición.
dependencies
Registro de dependencias para composición o descriptores de dependencias en introspección.
openapi
Opciones de publicación de OpenAPI para esta declaración o compilación.
openapi_path
Ruta que publica el documento OpenAPI generado.
documentation
Configuración explícita de OpenAPI y sus interfaces.
explorer
Configuración de la interfaz Explorer.
lifecycle
Contexto de ciclo de vida ASGI que aporta el host.
request_timeout
Presupuesto de tiempo de una petición HTTP en segundos.
problem_base_uri
URI base para los tipos de problemas HTTP.
hooks
Observadores de telemetría del plan o de la superficie.
confirmation_verifier
Verificador que la aplicación suministra al compilar.
schema_adapter
Adaptador que compila anotaciones en esquemas.

Http.__len__ Método

__len__() -> int

Devuelve la cantidad de declaraciones o elementos de la colección.

HttpApplication

Clase · Estable · agnara_http

Aplicación ASGI 3 compilada, con sus planes y exposiciones. Se obtiene con Http.compile().

HttpApplication.__call__ Método

async __call__(
    scope: _Scope,
    receive: Callable[[], Any],
    send: Callable[[Any], Any],
) -> None

Atiende una conexión ASGI de tipo http o lifespan.

scope
Ámbito de conexión que recibe la aplicación ASGI.
receive
Callable ASGI para recibir mensajes.
send
Callable ASGI para enviar mensajes.

HttpApplication.surface Propiedad

Identidad de esta aplicación HTTP compilada. SurfaceId

HttpApplication.exposures Propiedad

Registros neutrales de la superficie para agregación e introspección. SurfaceCompilation[Any]

HttpApplication.plans Propiedad

Planes compilados en orden de declaración. tuple[ExecutionPlan, ...]

HttpApplication.openapi Método

openapi() -> dict[str, Any]

Genera un documento OpenAPI 3.2 a partir de la superficie compilada.

HttpDefinitionError

Excepción · Estable · agnara_http

La composición HTTP es inválida, ambigua o se intentó después de cerrar las declaraciones.

HttpDocumentation

Clase · Estable · agnara_http

Configuración independiente para publicar el esquema OpenAPI y cada interfaz de documentación.

HttpDocumentation(
    schema: OpenApiSchema | None = <factory>,
    swagger: SwaggerUI | None = <factory>,
    scalar: Scalar | None = None,
    redoc: ReDoc | None = None,
) -> None
Parámetros
schema
Configuración de publicación de JSON OpenAPI.
swagger
Configuración opcional de Swagger UI.
scalar
Configuración opcional de Scalar.
redoc
Configuración opcional de ReDoc.
Atributos
schema: OpenApiSchema | None
Configuración de publicación de JSON OpenAPI.
swagger: SwaggerUI | None
Configuración opcional de Swagger UI.
scalar: Scalar | None
Configuración opcional de Scalar.
redoc: ReDoc | None
Configuración opcional de ReDoc.

HttpExplorer

Clase · Estable · agnara_http

Configuración del Explorer de solo lectura. Sirve una instantánea filtrada según la identidad y la visibilidad.

HttpExplorer(
    snapshot: IntrospectionSnapshot,
    visibility: DiscoveryVisibility,
    principals: Callable[[_Scope], Principal | None],
    path: str = '/agnara',
    challenge: str | None = None,
    allow_anonymous: bool = False,
    cache_control: str = 'private, no-store',
) -> None
Parámetros
snapshot
Instantánea de introspección que se filtra o publica.
visibility
Regla de visibilidad y selección de campos para la instantánea.
principals
Función del host que resuelve una identidad verificada desde el contexto del transporte.
path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
challenge
Desafío de autenticación HTTP que el host configura para las respuestas aplicables.
allow_anonymous
Permite que la superficie atienda lectores sin principal autenticado, sujetos a la política de visibilidad.
cache_control
Valor de la política HTTP de caché.

El host proporciona principals para identificar al lector. El filtro se aplica antes de entregar datos. Su caché es privada y no persistente por omisión.

Atributos
snapshot: IntrospectionSnapshot
Instantánea de introspección que se filtra o publica.
visibility: DiscoveryVisibility
Regla de visibilidad y selección de campos para la instantánea.
principals: Callable[[_Scope], Principal | None]
Función del host que resuelve una identidad verificada desde el contexto del transporte.
path: str
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
challenge: str | None
Desafío de autenticación HTTP que el host configura para las respuestas aplicables.
allow_anonymous: bool
Permite que la superficie atienda lectores sin principal autenticado, sujetos a la política de visibilidad.
cache_control: str
Valor de la política HTTP de caché.

OpenApiInfo

Clase · Estable · agnara_http

Metadatos del documento OpenAPI generado.

OpenApiInfo(
    title: str,
    version: str,
    *,
    summary: str | None = None,
    description: str | None = None,
) -> None
Parámetros
title
Título que puede mostrarse al lector.
version
Versión anunciada por el documento, agente, servidor o formato.
summary
Resumen breve que se publica para el documento o la operación.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.

OpenApiInfo.title Propiedad

Título que puede mostrarse al lector. str

OpenApiInfo.version Propiedad

Versión anunciada por el documento, agente, servidor o formato. str

OpenApiInfo.summary Propiedad

Resumen breve que se publica para el documento o la operación. str | None

OpenApiInfo.description Propiedad

Descripción que acompaña a la declaración. Su publicación depende de la superficie. str | None

OpenApiOperation

Clase · Estable · agnara_http

Metadatos y habilitación explícita de una operación en OpenAPI.

OpenApiOperation(
    *,
    summary: str | None = None,
    publish_description: bool = False,
    tags: Sequence[str] = (),
    deprecated: bool = False,
) -> None
Parámetros
summary
Resumen breve que se publica para el documento o la operación.
publish_description
Autoriza publicar la descripción declarada de la capacidad para esa operación.
tags
Etiquetas publicadas junto a una operación o habilidad.
deprecated
Marca la operación como obsoleta en OpenAPI.

OpenApiOperation.summary Propiedad

Resumen breve que se publica para el documento o la operación. str | None

OpenApiOperation.publish_description Propiedad

Autoriza publicar la descripción declarada de la capacidad para esa operación. bool

OpenApiOperation.tags Propiedad

Etiquetas publicadas junto a una operación o habilidad. tuple[str, ...]

OpenApiOperation.deprecated Propiedad

Marca la operación como obsoleta en OpenAPI. bool

OpenApiSchema

Clase · Estable · agnara_http

Configura la ruta estática que publica el documento JSON de OpenAPI.

OpenApiSchema(path: str = '/openapi.json') -> None
Parámetros
path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
Atributos
path: str
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.

ReDoc

Clase · Estable · agnara_http

Configura la página integrada de documentación ReDoc de solo lectura.

ReDoc(path: str = '/redoc', assets: DocumentationAssets = <factory>) -> None
Parámetros
path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
assets
Configuración de recursos que carga la interfaz.
Atributos
path: str
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
assets: DocumentationAssets
Configuración de recursos que carga la interfaz.

Scalar

Clase · Estable · agnara_http

Configura la página integrada de documentación Scalar y su modo interactivo.

Scalar(
    path: str = '/scalar',
    try_it: bool = False,
    assets: DocumentationAssets = <factory>,
) -> None
Parámetros
path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it
Habilita las llamadas interactivas desde la interfaz de documentación.
assets
Configuración de recursos que carga la interfaz.
Atributos
path: str
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it: bool
Habilita las llamadas interactivas desde la interfaz de documentación.
assets: DocumentationAssets
Configuración de recursos que carga la interfaz.

SwaggerUI

Clase · Estable · agnara_http

Configura Swagger UI y su modo interactivo.

SwaggerUI(
    path: str = '/docs',
    try_it: bool = False,
    assets: DocumentationAssets = <factory>,
) -> None
Parámetros
path
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it
Habilita las llamadas interactivas desde la interfaz de documentación.
assets
Configuración de recursos que carga la interfaz.
Atributos
path: str
Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it: bool
Habilita las llamadas interactivas desde la interfaz de documentación.
assets: DocumentationAssets
Configuración de recursos que carga la interfaz.

10. Adaptador MCP

agnara_mcp · 20 exportaciones

Compila herramientas de una aplicación. El host autentica el transporte, aporta el mapeo de identidad y cierra el cliente antes del contenedor. Descubrimiento e invocación comparten una tabla compilada.

Guía relacionada · MCP_TOOLS.md

MCP_PROTOCOL_VERSION · MCP_PYTHON_SDK_VERSION · SUPPORTED_MCP_PROTOCOL_VERSIONS · FrozenMcpTools · Mcp · McpAuthenticatedIdentity · McpAuthorization · McpAuthorizationDefinitionError · McpInteractionProjectionError · McpInvocationDefinitionError · McpPrincipalMapper · McpResultProjectionError · McpToolDefinitionError · McpToolExposure · McpToolInvoker · build_mcp_discovery_server · build_mcp_server · project_mcp_interaction_required · project_mcp_result · project_mcp_tools

MCP_PROTOCOL_VERSION

Constante · Estable · agnara_mcp

Revisión principal del protocolo MCP servida por este adaptador.

MCP_PROTOCOL_VERSION = '2026-07-28'

MCP_PYTHON_SDK_VERSION

Constante · Estable · agnara_mcp

Versión exacta del SDK Python MCP utilizada por el adaptador.

MCP_PYTHON_SDK_VERSION = '2.2.0'

SUPPORTED_MCP_PROTOCOL_VERSIONS

Constante · Estable · agnara_mcp

Tupla de revisiones MCP admitidas.

SUPPORTED_MCP_PROTOCOL_VERSIONS = ('2026-07-28',)

FrozenMcpTools

Clase · Estable · agnara_mcp

Colección inmutable de herramientas MCP compiladas en orden de registro.

FrozenMcpTools(exposures: tuple[McpToolExposure, ...]) -> None
Parámetros
exposures
Colección de destinos compilados de la superficie o del proyecto.

FrozenMcpTools.__getitem__ Método

__getitem__(name: str) -> McpToolExposure

Busca un elemento por su clave.

name
Nombre lógico de la entidad que se declara, describe o publica.

FrozenMcpTools.__iter__ Método

__iter__() -> Iterator[str]

Recorre las claves de la colección.

FrozenMcpTools.__len__ Método

__len__() -> int

Devuelve la cantidad de declaraciones o elementos de la colección.

FrozenMcpTools.exposures Propiedad

Herramientas compiladas en orden de registro. tuple[McpToolExposure, ...]

Mcp

Clase · Estable · agnara_mcp

Declara herramientas MCP para capacidades de una aplicación y congela su registro para composición.

Mcp(app: Agnara, *, surface: str = 'default') -> None
Parámetros
app
Aplicación o contexto que posee las declaraciones.
surface
Identidad o nombre de la superficie que sirve la exposición.

Mcp.is_compiled Propiedad

Indica que se cerró el registro de herramientas. bool

Mcp.surface Propiedad

Identidad de esta superficie MCP para el registro de exposiciones. SurfaceId

Mcp.tool Método

tool(
    capability: CapabilityDefinition | Callable[..., Any],
    /,
    *,
    name: str | None = None,
) -> McpToolExposure

Vincula una capacidad declarada con un nombre de herramienta MCP.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
name
Nombre lógico de la entidad que se declara, describe o publica.

Mcp.compile Método

compile() -> FrozenMcpTools

Cierra el registro y devuelve una instantánea de herramientas reutilizable.

Mcp.compile_surface Método

compile_surface() -> SurfaceCompilation[FrozenMcpTools]

Devuelve el registro compilado de herramientas y sus exposiciones neutrales.

Mcp.__len__ Método

__len__() -> int

Devuelve la cantidad de declaraciones o elementos de la colección.

McpAuthenticatedIdentity

Clase · Estable · agnara_mcp

Datos de identidad verificados y saneados que recibe el mapeador MCP. El token sin procesar queda en el límite del host.

McpAuthenticatedIdentity(
    client_id: str,
    issuer: str | None,
    subject: str | None,
    resource: str | None,
    scopes: frozenset[str],
) -> None
Parámetros
client_id
Identificador del cliente aportado por el verificador.
issuer
Identidad del emisor aportada por el verificador.
subject
Identidad del sujeto aportada por el verificador.
resource
Identidad del recurso que aporta el verificador MCP.
scopes
Permisos declarados por la capacidad o concedidos a una identidad verificada.
Atributos
client_id: str
Identificador del cliente aportado por el verificador.
issuer: str | None
Identidad del emisor aportada por el verificador.
subject: str | None
Identidad del sujeto aportada por el verificador.
resource: str | None
Identidad del recurso que aporta el verificador MCP.
scopes: frozenset[str]
Permisos declarados por la capacidad o concedidos a una identidad verificada.

McpAuthorization

Clase · Estable · agnara_mcp

Resuelve la identidad de la petición y filtra las herramientas visibles según sus permisos.

McpAuthorization(exposures: FrozenMcpTools, mapper: McpPrincipalMapper) -> None
Parámetros
exposures
Colección de destinos compilados de la superficie o del proyecto.
mapper
Función que convierte identidad MCP verificada en Principal.

El mapeador recibe datos saneados del verificador. Los parámetros de tools/call no conceden identidad o permisos.

McpAuthorization.tool_names Propiedad

Nombres de las exposiciones configuradas, en orden de declaración. tuple[str, ...]

McpAuthorization.principal Método

principal() -> Principal

Obtiene el principal de la petición a partir de la identidad que verificó el host.

McpAuthorization.discoverable_tool_names Método

discoverable_tool_names() -> frozenset[str]

Filtra las herramientas que el principal puede descubrir según sus permisos estáticos.

McpAuthorizationDefinitionError

Excepción · Estable · agnara_mcp

La composición de autorización MCP es inválida o incompatible con las herramientas.

McpInteractionProjectionError

Excepción · Estable · agnara_mcp

Un fallo que requiere interacción no puede proyectarse de manera segura a MCP.

McpInvocationDefinitionError

Excepción · Estable · agnara_mcp

La superficie de invocación MCP se configuró de manera incoherente.

McpPrincipalMapper

Protocolo · Estable · agnara_mcp

Protocolo invocable que transforma identidad MCP verificada en una identidad Principal de la aplicación.

McpPrincipalMapper.__call__ Método

__call__(identity: McpAuthenticatedIdentity, /) -> Principal

Transforma los datos saneados del verificador en un Principal de la aplicación.

identity
Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.

McpResultProjectionError

Excepción · Estable · agnara_mcp

El resultado canónico no puede representarse con seguridad como resultado de herramienta MCP.

McpToolDefinitionError

Excepción · Estable · agnara_mcp

Una exposición MCP es inválida o ambigua.

McpToolExposure

Clase · Estable · agnara_mcp

Asocia un nombre válido de herramienta MCP con una capacidad neutral al transporte.

McpToolExposure(name: str, definition: CapabilityDefinition) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
definition
Declaración de la capacidad que se compila o expone.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
definition: CapabilityDefinition
Declaración de la capacidad que se compila o expone.

McpToolInvoker

Clase · Estable · agnara_mcp

Resuelve tools/call contra una tabla inmutable y despacha al plan compilado.

McpToolInvoker(
    exposures: FrozenMcpTools,
    plans: Iterable[ExecutionPlan],
    di_container: DIContainer,
    *,
    authorization: McpAuthorization | None = None,
    timeout: float | None = None,
) -> None
Parámetros
exposures
Colección de destinos compilados de la superficie o del proyecto.
plans
Planes compilados que la superficie puede despachar o describir.
di_container
Contenedor que aporta los recursos de esta ejecución.
authorization
Resolución y filtrado de identidades para el servidor MCP.
timeout
Presupuesto de ejecución en segundos. None omite este límite explícito.

McpToolInvoker.tool_names Propiedad

Nombres de las herramientas invocables en orden de declaración. tuple[str, ...]

McpToolInvoker.__call__ Método

async __call__(
    ctx: ServerRequestContext[Any],
    params: CallToolRequestParams,
) -> CallToolResult | InputRequiredResult

Atiende tools/call con el contexto del SDK y despacha al plan autorizado.

ctx
Contexto de petición que entrega el SDK de MCP.
params
Parámetros de tools/call que suministra el SDK MCP.

build_mcp_discovery_server

Función · Estable · agnara_mcp

Construye un servidor del SDK oficial que permite descubrir herramientas de una instantánea.

build_mcp_discovery_server(
    tools: Iterable[Tool],
    *,
    name: str,
    version: str,
    instructions: str | None = None,
    authorization: McpAuthorization | None = None,
) -> Server[Any]
Parámetros
tools
Descriptores de herramientas que se publican en MCP.
name
Nombre lógico de la entidad que se declara, describe o publica.
version
Versión anunciada por el documento, agente, servidor o formato.
instructions
Texto de instrucciones que el servidor MCP ofrece al cliente.
authorization
Resolución y filtrado de identidades para el servidor MCP.

build_mcp_server

Función · Estable · agnara_mcp

Construye un servidor del SDK oficial que descubre e invoca herramientas. El host coordina el cierre del cliente y del contenedor.

build_mcp_server(
    exposures: FrozenMcpTools,
    plans: Iterable[ExecutionPlan],
    di_container: DIContainer,
    *,
    name: str,
    version: str,
    instructions: str | None = None,
    authorization: McpAuthorization | None = None,
    timeout: float | None = None,
) -> Server[Any]
Parámetros
exposures
Colección de destinos compilados de la superficie o del proyecto.
plans
Planes compilados que la superficie puede despachar o describir.
di_container
Contenedor que aporta los recursos de esta ejecución.
name
Nombre lógico de la entidad que se declara, describe o publica.
version
Versión anunciada por el documento, agente, servidor o formato.
instructions
Texto de instrucciones que el servidor MCP ofrece al cliente.
authorization
Resolución y filtrado de identidades para el servidor MCP.
timeout
Presupuesto de ejecución en segundos. None omite este límite explícito.

project_mcp_interaction_required

Función · Estable · agnara_mcp

Proyecta una solicitud canónica compatible de confirmación al formulario de interacción MCP.

project_mcp_interaction_required(failure: Failure) -> InputRequiredResult
Parámetros
failure
Fallo canónico que explica la interrupción o se proyecta al adaptador.

project_mcp_result

Función · Estable · agnara_mcp

Convierte un resultado canónico en la respuesta MCP correspondiente. No ejecuta la capacidad.

project_mcp_result(
    outcome: CanonicalResult[object],
) -> CallToolResult | InputRequiredResult
Parámetros
outcome
Desenlace de la invocación o resultado canónico que se proyecta.

project_mcp_tools

Función · Estable · agnara_mcp

Genera descriptores de herramientas del SDK desde las exposiciones y sus planes. Devuelve datos independientes de las tablas compiladas.

project_mcp_tools(
    exposures: FrozenMcpTools,
    plans: Iterable[ExecutionPlan],
) -> tuple[Tool, ...]
Parámetros
exposures
Colección de destinos compilados de la superficie o del proyecto.
plans
Planes compilados que la superficie puede despachar o describir.

11. Adaptador A2A provisional

agnara_a2a · 8 exportaciones

El perfil publicado cubre una habilidad de resultado completo. Sus ocho nombres son provisionales y pueden cambiar dentro de la línea 1.x tras revisión.

Guía relacionada · A2A_SERVICE.md

A2A_PROTOCOL_VERSION · A2A_PYTHON_SDK_VERSION · SUPPORTED_A2A_PROTOCOL_VERSIONS · A2a · A2aAgentCard · A2aDefinitionError · A2aSkillExposure · build_a2a_app

A2A_PROTOCOL_VERSION

Constante · Provisional · agnara_a2a

Versión de protocolo anunciada por el perfil A2A publicado.

A2A_PROTOCOL_VERSION = '1.0'

A2A_PYTHON_SDK_VERSION

Constante · Provisional · agnara_a2a

Versión exacta del SDK Python usada por el adaptador A2A.

A2A_PYTHON_SDK_VERSION = '1.3.0'

SUPPORTED_A2A_PROTOCOL_VERSIONS

Constante · Provisional · agnara_a2a

Tupla de versiones de protocolo admitidas por el perfil A2A.

SUPPORTED_A2A_PROTOCOL_VERSIONS = ('1.0',)

A2a

Clase · Provisional · agnara_a2a

Declara una superficie A2A provisional con una sola capacidad de resultado completo, publicada como habilidad.

A2a(app: Agnara, *, surface: str = 'default') -> None
Parámetros
app
Aplicación o contexto que posee las declaraciones.
surface
Identidad o nombre de la superficie que sirve la exposición.

El ejemplo de esta edición ejecuta el SDK oficial en proceso. Las tareas A2A y el streaming quedan fuera del perfil de esta edición.

A2a.is_compiled Propiedad

Indica que se cerró el registro de habilidades. bool

A2a.surface Propiedad

Identidad de esta superficie A2A para el registro de exposiciones. SurfaceId

A2a.skill Método

skill(
    capability: CapabilityDefinition | Callable[..., Any],
    /,
    *,
    id: str,
    name: str,
    description: str,
    tags: tuple[str, ...],
) -> A2aSkillExposure

Declara la única habilidad y la vincula a una capacidad registrada.

capability
Capacidad seleccionada o descriptor que evalúa la regla.
id
Identificador del registro. Su tipo depende de la entidad.
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
tags
Etiquetas publicadas junto a una operación o habilidad.

A2a.compile Método

compile() -> A2aSkillExposure

Cierra las declaraciones y devuelve la exposición de habilidad.

A2a.compile_surface Método

compile_surface() -> SurfaceCompilation[A2aSkillExposure]

Devuelve la habilidad compilada con el registro de exposición neutral.

A2aAgentCard

Clase · Provisional · agnara_a2a

Metadatos del agente para su Agent Card pública sin firma.

A2aAgentCard(name: str, description: str, version: str) -> None
Parámetros
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
version
Versión anunciada por el documento, agente, servidor o formato.
Atributos
name: str
Nombre lógico de la entidad que se declara, describe o publica.
description: str
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
version: str
Versión anunciada por el documento, agente, servidor o formato.

A2aDefinitionError

Excepción · Provisional · agnara_a2a

La configuración no satisface el perfil A2A de resultado completo.

A2aSkillExposure

Clase · Provisional · agnara_a2a

Une una capacidad declarada con la única habilidad que publica una superficie A2A.

A2aSkillExposure(
    definition: CapabilityDefinition,
    id: str,
    name: str,
    description: str,
    tags: tuple[str, ...],
) -> None
Parámetros
definition
Declaración de la capacidad que se compila o expone.
id
Identificador del registro. Su tipo depende de la entidad.
name
Nombre lógico de la entidad que se declara, describe o publica.
description
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
tags
Etiquetas publicadas junto a una operación o habilidad.
Atributos
definition: CapabilityDefinition
Declaración de la capacidad que se compila o expone.
id: str
Identificador del registro. Su tipo depende de la entidad.
name: str
Nombre lógico de la entidad que se declara, describe o publica.
description: str
Descripción que acompaña a la declaración. Su publicación depende de la superficie.
tags: tuple[str, ...]
Etiquetas publicadas junto a una operación o habilidad.

build_a2a_app

Función · Provisional · agnara_a2a

Construye la aplicación ASGI que sirve la Agent Card y la habilidad con el plan compilado. El host aporta identidad y es propietario del ciclo de vida.

build_a2a_app(
    exposure: A2aSkillExposure,
    plans: Iterable[ExecutionPlan],
    di_container: DIContainer,
    *,
    card: A2aAgentCard,
    url: str,
    principals: _PrincipalResolver,
    challenge: str,
    timeout: float = 30.0,
    max_body_bytes: int = 1048576,
    card_cache_control: str | None = None,
) -> Callable[[_Scope, _Receive, _Send], Awaitable[None]]
Parámetros
exposure
Exposición compilada que selecciona la capacidad servida.
plans
Planes compilados que la superficie puede despachar o describir.
di_container
Contenedor que aporta los recursos de esta ejecución.
card
Metadatos del agente que se publicarán en la Agent Card.
url
URL pública que se anuncia para la interfaz A2A.
principals
Función del host que resuelve una identidad verificada desde el contexto del transporte.
challenge
Desafío de autenticación HTTP que el host configura para las respuestas aplicables.
timeout
Presupuesto de ejecución en segundos. None omite este límite explícito.
max_body_bytes
Tamaño máximo del cuerpo admitido en bytes.
card_cache_control
Valor de Cache-Control de la Agent Card.

12. Interfaz de línea de comandos

agnara_cli · 4 exportaciones

La CLI genera estructuras de proyecto y permite inspeccionar composiciones. Usa agnara --help para ver los comandos instalados y agnara COMANDO --help para sus opciones.

Guía relacionada · CLI_SPEC.md

EXIT_FAILED · EXIT_OK · EXIT_USAGE · main

EXIT_FAILED

Constante · Estable · agnara_cli

Código de salida que indica que un comando no pudo completarse.

EXIT_FAILED = 1

EXIT_OK

Constante · Estable · agnara_cli

Código de salida de un comando completado correctamente.

EXIT_OK = 0

EXIT_USAGE

Constante · Estable · agnara_cli

Código de salida para uso incorrecto de la CLI.

EXIT_USAGE = 2

main

Función · Estable · agnara_cli

Ejecuta un comando de la CLI y devuelve su código de salida.

main(argv: Sequence[str] | None = None) -> int
Parámetros
argv
Argumentos de la CLI sin el nombre del ejecutable. Con None usa los argumentos del proceso.

Para un proceso nuevo se puede ejecutar python -m agnara_cli --help. EXIT_OK, EXIT_FAILED y EXIT_USAGE documentan los códigos de salida.

13. Telemetría OpenTelemetry

agnara_telemetry · 2 exportaciones

Los hooks observan la ejecución de la capacidad. La aplicación aporta el medidor o trazador y gestiona su ciclo de vida y sus exportadores.

Guía relacionada · TELEMETRY.md

OpenTelemetryMetricsHook · OpenTelemetryTracingHook

OpenTelemetryMetricsHook

Clase · Estable · agnara_telemetry

Hook que registra medidas al terminar una invocación con el medidor suministrado por el host.

OpenTelemetryMetricsHook(meter: opentelemetry.metrics.Meter) -> None
Parámetros
meter
Medidor OpenTelemetry suministrado por el host.

OpenTelemetryMetricsHook.on_invocation_start Método

on_invocation_start(event: InvocationStartEvent) -> None

Acepta el evento inicial sin mantener estado de correlación.

event
Evento de telemetría entregado al observador.

OpenTelemetryMetricsHook.on_invocation_terminal Método

on_invocation_terminal(event: InvocationTerminalEvent) -> None

Registra la duración y el desenlace con el medidor configurado.

event
Evento de telemetría entregado al observador.

OpenTelemetryTracingHook

Clase · Estable · agnara_telemetry

Hook que abre un span al comenzar la invocación y lo cierra con el evento terminal correspondiente.

OpenTelemetryTracingHook(tracer: opentelemetry.trace.Tracer) -> None
Parámetros
tracer
Trazador OpenTelemetry suministrado por el host.

OpenTelemetryTracingHook.on_invocation_start Método

on_invocation_start(event: InvocationStartEvent) -> None

Abre un span y lo establece como actual para las invocaciones anidadas.

event
Evento de telemetría entregado al observador.

OpenTelemetryTracingHook.on_invocation_terminal Método

on_invocation_terminal(event: InvocationTerminalEvent) -> None

Cierra el span asociado si existe un inicio correspondiente.

event
Evento de telemetría entregado al observador.

14. Espacio reservado para eventos

agnara_events · 0 exportaciones

La distribución agnara-events 1.0.4 instala este espacio de nombres con cero exportaciones públicas. El consumo de eventos y la ejecución durable se investigan por separado.

Guía relacionada · MATURITY.md

15. Índice alfabético

Las entradas enlazan a los nombres importables. Para un método o atributo, abre la ficha de su clase o usa la búsqueda del HTML.

16. Versión y fuentes

Agnara 1.0.4 se publicó el 10 de noviembre de 2026. Las firmas y los valores de constantes se comprobaron en los siete paquetes instalados con CPython 3.14.4. Los nombres coinciden con el manifiesto de la etiqueta v1.0.4.