Module adcp.types.domains.manifest_schema

Classes

class AdcpManifest (**data: Any)
Expand source code
class AdcpManifest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        str | None, Field(alias='$schema', description='Reference to this manifest meta-schema.')
    ] = None
    adcp_version: Annotated[
        str,
        Field(
            description='Full semver of the AdCP release this manifest describes.',
            pattern='^\\d+\\.\\d+\\.\\d+(-[A-Za-z0-9.-]+)?$',
        ),
    ]
    generated_at: Annotated[
        AwareDatetime,
        Field(
            description='ISO-8601 timestamp the manifest was generated. SDKs MAY use this for cache invalidation.'
        ),
    ]
    tools: Annotated[
        dict[ToolName, Tools],
        Field(
            description='Every tool the AdCP spec defines, keyed by tool name (the snake_case name used in MCP/A2A invocations).',
            min_length=1,
        ),
    ]
    task_result_resolution: Annotated[
        TaskResultResolution,
        Field(
            description='Machine-readable rule for resolving the schema of a tracked task result without generating the full async-response-data union as an SDK type. Consumers check terminal_schema_overrides first, then apply terminal_schema_pointer_template.'
        ),
    ]
    error_code_policy: Annotated[
        ErrorCodePolicy,
        Field(
            description="How SDKs should handle codes outside the standard set. The error vocabulary is open: sellers MAY return platform-specific codes that aren't in `error_codes`. Agents MUST fall back to `default_unknown_recovery` for unknown codes — they SHOULD NOT throw or treat unknown codes as malformed responses."
        ),
    ]
    error_codes: Annotated[
        dict[str, ErrorCodes],
        Field(
            description="Every standard error code in the AdCP error vocabulary, keyed by the SCREAMING_SNAKE code. Mirrors enums/error-code.json's enum + enumMetadata + enumDescriptions. Open-set: see error_code_policy for unknown-code handling.",
            min_length=1,
        ),
    ]
    specialisms: Annotated[
        dict[str, Specialisms],
        Field(
            description='Every storyboard specialism declared in static/compliance/source/specialisms/, keyed by specialism ID. Lets SDKs declare which specialisms they implement and verify their tool surface covers the required tools.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var adcp_version : str
var error_code_policy : ErrorCodePolicy
var error_codes : dict[str, ErrorCodes]
var field_schema : str | None
var generated_at : pydantic.types.AwareDatetime
var model_config
var specialisms : dict[str, Specialisms]
var task_result_resolution : TaskResultResolution
var tools : dict[ToolName, Tools]

Inherited members

class DefaultUnknownRecovery (*args, **kwds)
Expand source code
class DefaultUnknownRecovery(StrEnum):
    correctable = 'correctable'
    transient = 'transient'
    terminal = 'terminal'

Enum where members are also (and must be) strings

Ancestors

  • enum.StrEnum
  • builtins.str
  • enum.ReprEnum
  • enum.Enum

Class variables

var correctable
var terminal
var transient
class ErrorCodePolicy (**data: Any)
Expand source code
class ErrorCodePolicy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    default_unknown_recovery: Annotated[
        DefaultUnknownRecovery,
        Field(
            description="The recovery classification an agent MUST apply to a code that is not present in this manifest's `error_codes` block. `transient` is the safe default — unknown codes from a non-conforming seller should be retried with backoff, not classified as fatal."
        ),
    ]
    note: Annotated[str, Field(description='Human-readable summary of the open-set policy.')]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var default_unknown_recovery : DefaultUnknownRecovery
var model_config
var note : str

Inherited members

class ErrorCodes (**data: Any)
Expand source code
class ErrorCodes(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    recovery: Annotated[
        DefaultUnknownRecovery,
        Field(
            description='How the caller should respond. correctable: fix the request and retry. transient: retry with backoff. terminal: no autonomous recovery — operator intervention required.'
        ),
    ]
    description: Annotated[
        str,
        Field(
            description='Human-readable description of the error. Sourced from enumDescriptions in enums/error-code.json.'
        ),
    ]
    suggestion: Annotated[
        str,
        Field(
            description='Short remediation hint a buyer agent can act on. Sourced from enumMetadata in enums/error-code.json.'
        ),
    ]
    added_in: Annotated[
        str | None,
        Field(description='Semver of the AdCP release that introduced this code. Optional.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var added_in : str | None
var description : str
var model_config
var recovery : DefaultUnknownRecovery
var suggestion : str

Inherited members

class IdempotencyRequirement (*args, **kwds)
Expand source code
class IdempotencyRequirement(StrEnum):
    required = 'required'
    optional = 'optional'
    none = 'none'

Enum where members are also (and must be) strings

Ancestors

  • enum.StrEnum
  • builtins.str
  • enum.ReprEnum
  • enum.Enum

Class variables

var none
var optional
var required
class LegacyFallback (**data: Any)
Expand source code
class LegacyFallback(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    tool: Annotated[ToolName, Field(description='Legacy peer tool targeted by the adapter.')]
    mode: Annotated[
        Literal['direct'],
        Field(
            description="direct: one lossless translated call; orchestrated: the SDK must sequence legacy calls and preserve the current tool's semantics; none: no faithful legacy fallback exists."
        ),
    ] = 'direct'

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var mode : Literal['direct']
var model_config
var tool : ToolName

Inherited members

class LegacyFallback1 (**data: Any)
Expand source code
class LegacyFallback1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    tool: Annotated[ToolName, Field(description='Legacy peer tool targeted by the adapter.')]
    mode: Annotated[
        Literal['orchestrated'],
        Field(
            description="direct: one lossless translated call; orchestrated: the SDK must sequence legacy calls and preserve the current tool's semantics; none: no faithful legacy fallback exists."
        ),
    ] = 'orchestrated'

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var mode : Literal['orchestrated']
var model_config
var tool : ToolName

Inherited members

class LegacyFallback2 (**data: Any)
Expand source code
class LegacyFallback2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    tool: Annotated[
        ToolName | None, Field(description='Legacy peer tool targeted by the adapter.')
    ] = None
    mode: Annotated[
        Literal['none'],
        Field(
            description="direct: one lossless translated call; orchestrated: the SDK must sequence legacy calls and preserve the current tool's semantics; none: no faithful legacy fallback exists."
        ),
    ] = 'none'

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var mode : Literal['none']
var model_config
var tool : ToolName | None

Inherited members

class Mode (*args, **kwds)
Expand source code
class Mode(StrEnum):
    direct = 'direct'
    orchestrated = 'orchestrated'
    none = 'none'

Enum where members are also (and must be) strings

Ancestors

  • enum.StrEnum
  • builtins.str
  • enum.ReprEnum
  • enum.Enum

Class variables

var direct
var none
var orchestrated
class Protocol (*args, **kwds)
Expand source code
class Protocol(StrEnum):
    media_buy = 'media-buy'
    signals = 'signals'
    governance = 'governance'
    account = 'account'
    creative = 'creative'
    brand = 'brand'
    content_standards = 'content-standards'
    property = 'property'
    collection = 'collection'
    sponsored_intelligence = 'sponsored-intelligence'
    protocol = 'protocol'
    compliance = 'compliance'
    trusted_match = 'trusted-match'
    a2ui = 'a2ui'

Enum where members are also (and must be) strings

Ancestors

  • enum.StrEnum
  • builtins.str
  • enum.ReprEnum
  • enum.Enum

Class variables

var a2ui
var account
var brand
var collection
var compliance
var content_standards
var creative
var governance
var media_buy
var property
var protocol
var signals
var sponsored_intelligence
var trusted_match
class SchemaPath (value: Any = <object object>, *, root: Any = <object object>)
Expand source code
class SchemaPath(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*\\.json$'}
    _json_schema_extra = {
        'description': 'Normalized relative path to a JSON schema within the published release root.',
    }

A str generated from a JSON Schema string root.

Ancestors

  • adcp.types._scalar.ScalarStr
  • adcp.types._scalar._ScalarRoot
  • builtins.str
class Specialisms (**data: Any)
Expand source code
class Specialisms(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    protocol: Annotated[
        str,
        Field(
            description="The protocol surface this specialism belongs to. Sourced from index.yaml's `protocol` field. Note: this is the specialism's home protocol; individual `exercised_tools` may belong to other protocols (e.g., a sales-track specialism may exercise an account-protocol tool like sync_accounts)."
        ),
    ]
    title: Annotated[
        str | None,
        Field(description="Human-readable title. Sourced from index.yaml's `title` field."),
    ] = None
    entry_point_tools: Annotated[
        list[str],
        Field(
            description="The minimal contract: tools the spec asserts an implementer MUST ship to claim this specialism. Sourced from index.yaml's `required_tools` field. An agent declaring this specialism in its capabilities MUST respond to every tool listed here."
        ),
    ]
    exercised_tools: Annotated[
        list[str],
        Field(
            description="The full surface the conformance kit will call: union of entry_point_tools, the specialism's own phases[].steps[].task, and every linked scenario's tasks. An agent declaring this specialism MUST be prepared to handle every call here, even though some are inherited via storyboard scenarios rather than declared in `required_tools`. Use this set to size your tool registration, not entry_point_tools."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var entry_point_tools : list[str]
var exercised_tools : list[str]
var model_config
var protocol : str
var title : str | None

Inherited members

class TaskResultResolution (**data: Any)
Expand source code
class TaskResultResolution(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    discriminator_field: Literal['task_type'] = 'task_type'
    terminal_schema_pointer_template: Literal['/tools/{task_type}/response_schema'] = '/tools/{task_type}/response_schema'
    terminal_schema_overrides: Annotated[
        dict[ToolName, SchemaPath],
        Field(
            description='Result schemas for retained 3.x task_type values that do not name manifest tools, such as media_buy_delivery.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var discriminator_field : Literal['task_type']
var model_config
var terminal_schema_overrides : dict[ToolName, SchemaPath]
var terminal_schema_pointer_template : Literal['/tools/{task_type}/response_schema']

Inherited members

class ToolName (value: Any = <object object>, *, root: Any = <object object>)
Expand source code
class ToolName(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[a-z][a-z0-9_]*$'}
    _json_schema_extra = {
        'description': 'Canonical snake_case tool name safe for use as a manifest JSON Pointer segment.',
    }

A str generated from a JSON Schema string root.

Ancestors

  • adcp.types._scalar.ScalarStr
  • adcp.types._scalar._ScalarRoot
  • builtins.str
class Tools (**data: Any)
Expand source code
class Tools(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    protocol: Annotated[
        Protocol,
        Field(
            description='The protocol surface this tool belongs to. Derived from the source directory: media-buy, signals, governance, account, creative, brand, content-standards, property, collection, sponsored-intelligence, protocol, compliance, trusted-match.'
        ),
    ]
    mutating: Annotated[
        StrictBool,
        Field(
            description='True if invoking this tool can change server-side state. New mutating tools MUST require idempotency_key (or carry an explicit naturally-idempotent exemption). A stable 3.x compatibility facade may explicitly mark the key optional while narrower replacement tools carry the required-key contract. Verb prefixes are not authoritative.'
        ),
    ]
    summary: Annotated[
        str | None,
        Field(
            description='Optional concise, agent-facing description suitable for live tool discovery. This is separate from the canonical request schema description and does not affect validation.',
            max_length=240,
            min_length=1,
        ),
    ] = None
    operation_family: Annotated[
        str | None,
        Field(
            description='Stable logical operation identity used for authorization, idempotency equivalence, task recovery, and webhook identity. Aliases in the same family share this value.'
        ),
    ] = None
    idempotency_requirement: Annotated[
        IdempotencyRequirement | None,
        Field(
            description='Whether callers must, may, or cannot supply idempotency_key for this tool. Optional keys, when supplied, receive the same replay guarantees as required keys.'
        ),
    ] = None
    request_schema: SchemaPath
    response_schema: SchemaPath
    async_response_schemas: Annotated[
        list[SchemaPath],
        Field(
            description="Paths to the tool's async response variants (typically -submitted, -working, -input-required). Empty array if the tool has no async surface. Buyer agents MUST handle every entry — a tool with async_response_schemas non-empty can return any of these from a non-final task state."
        ),
    ]
    legacy_fallback: Annotated[
        LegacyFallback | LegacyFallback1 | LegacyFallback2 | None,
        Field(
            description="How an SDK exposing this tool's current API may satisfy it against a peer that only exposes a legacy tool. This is caller-side adaptation metadata, not authorization or idempotency equivalence.",
            discriminator='mode',
        ),
    ] = None
    superseded_by: Annotated[
        list[ToolName] | None,
        Field(
            description='Current tool names that replace this deprecated facade. This does not imply that each replacement is a one-call alias.',
            min_length=1,
        ),
    ] = None
    specialisms: Annotated[
        list[str] | None,
        Field(
            description='Specialism IDs that include this tool in their required_tools (or via inherited scenarios). Lets SDKs answer "if I claim specialism X, which tools must I implement?" without re-deriving from the compliance cache.'
        ),
    ] = None
    added_in: Annotated[
        str | None,
        Field(
            description='Semver of the AdCP release that introduced this tool. Optional; absent means "present since 1.0".'
        ),
    ] = None
    deprecated_in: Annotated[
        str | None,
        Field(
            description='Semver of the AdCP release that deprecated this tool. Absent means active.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var added_in : str | None
var async_response_schemas : list[SchemaPath]
var deprecated_in : str | None
var idempotency_requirement : IdempotencyRequirement | None
var legacy_fallback : LegacyFallback | LegacyFallback1 | LegacyFallback2 | None
var model_config
var mutating : bool
var operation_family : str | None
var protocol : Protocol
var request_schema : SchemaPath
var response_schema : SchemaPath
var specialisms : list[str] | None
var summary : str | None
var superseded_by : list[ToolName] | None

Inherited members