Module adcp.types.domains.formats.canonical.agent_placement

Classes

class CanonicalFormatAgentPlacementAiSurfaceSponsoredPlacement (**data: Any)

Expand source code

class CanonicalFormatAgentPlacementAiSurfaceSponsoredPlacement(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    experimental: Annotated[
        Any | None,
        Field(
            description="Marked experimental at 3.1 GA: the canonical's tracking model (mention-level impression + attribution, postback shape, cross-surface dedup) is intentionally underspecified for 3.1. Adopters claiming `agent_placement` ship private tracking integrations; buyer agents MUST treat attribution as adapter-defined until the 3.2 tracking-macro spec lands. Promotion to non-experimental gated on the 3.2 tracking-contract spec."
        ),
    ] = True
    v1_translatable: Annotated[
        Any | None,
        Field(
            description="Inherently new in v2 — AI-surface sponsored mentions weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural."
        ),
    ] = False
    slots: Annotated[
        Any | None,
        Field(
            description="agent_placement has minimal buyer-shipped slots — the surface composes the rendered output from brand context (resolved via the manifest's top-level `brand` BrandRef) plus optional offering_ref and landing_page_url assets. None of these assets are rendered verbatim by the buyer; the agent chooses how to use them."
        ),
    ] = [
        {'asset_group_id': 'offering_ref', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    output_modality: Annotated[
        OutputModality | None,
        Field(
            description='How the surface presents the mention. `text` = inline text (chat, search snippet). `audio` = TTS-synthesized voice. `card` = structured card with optional image + text.'
        ),
    ] = None
    max_mention_length_chars: Annotated[
        SchemaInt | None,
        Field(
            description='For text output: maximum length of the surface-composed mention text.',
            ge=1,
        ),
    ] = None
    max_mention_duration_ms: Annotated[
        SchemaInt | None,
        Field(
            description='For audio output: maximum duration of the spoken mention in milliseconds.',
            ge=1,
        ),
    ] = None
    supports_offering_reference: Annotated[
        StrictBool | None,
        Field(
            description='Whether the product accepts an offering reference (specific product/service to promote within the mention) in addition to brand context.'
        ),
    ] = None
    supports_landing_page_url: Annotated[
        StrictBool | None,
        Field(
            description='Whether the surface attaches a landing page URL to the mention (citation, learn-more link).'
        ),
    ] = None
    tone_constraints: Annotated[
        list[str] | None,
        Field(
            description="**Advisory only.** Buyer-declared brand-voice preferences the surface SHOULD honor (e.g., ['formal', 'no_superlatives']). LLM/agentic surfaces have no protocol-level mechanism to verify enforcement — adopters that need hard guarantees should rely on brand.json voice declarations and post-mention review rather than this field. Future revisions may tie this to a structured tone vocabulary; for now treat as free-text guidance."
        ),
    ] = None
    disclosure_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether the surface must include an explicit sponsorship disclosure label.'
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var disclosure_required : bool | None

var experimental : typing.Any | None

var max_mention_duration_ms : int | None

var max_mention_length_chars : int | None

var model_config

var output_modality : OutputModality | None

var slots : typing.Any | None

var supports_landing_page_url : bool | None

var supports_offering_reference : bool | None

var tone_constraints : list[str] | None

var v1_translatable : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class OutputModality (*args, **kwds)

Expand source code

class OutputModality(StrEnum):
    text = 'text'
    audio = 'audio'
    card = 'card'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audio

var card

var text