Module adcp.types.domains.signals

Types the AdCP signals schemas declare.

Importing from the domain says which variant you mean, where the flat adcp.types namespace can only bind one class per name:

from adcp.types.domains.signals import <Type>

A type this domain declares in more than one schema is not here: import it from its own schema's module, adcp.types.domains.signals.<schema>. Nothing here is renamed.

Auto-generated from the generated domain tree. DO NOT EDIT MANUALLY. Generation date: 2026-10-04 18:45:11 UTC

Sub-modules

adcp.types.domains.signals.activate_signal_request

adcp.types.domains.signals.activate_signal_response

adcp.types.domains.signals.get_signals_async_response_submitted

adcp.types.domains.signals.get_signals_async_response_working

adcp.types.domains.signals.get_signals_request

adcp.types.domains.signals.get_signals_response

Classes

class Action (*args, **kwds)

Expand source code

class Action(StrEnum):
    activate = 'activate'
    deactivate = 'deactivate'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var activate

var deactivate

class ActivateSignalRequest (**data: Any)

Expand source code

class ActivateSignalRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    action: Annotated[
        Action | None,
        Field(
            description="Whether to activate or deactivate the signal. Deactivating removes the segment from downstream platforms, required when campaigns end to comply with data governance policies (GDPR, CCPA). Defaults to 'activate' when omitted."
        ),
    ] = Action.activate
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description='Opaque activation handle returned in the signal_agent_segment_id field of each get_signals response entry. Pass this string verbatim — do not pass the signal_id object.'
        ),
    ]
    destinations: Annotated[
        list[destination.Destination],
        Field(
            description='Target destination(s) for activation. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ]
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="The pricing option selected from the signal's pricing_options in the get_signals response. Required when the signal has pricing options. Records the buyer's pricing commitment at activation time; pass this same value in report_usage for billing verification."
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque authorization context returned by an approved check_governance decision for this signal activation. Required when the account has a registered governance agent; signal agents MUST reject governed activations that omit a valid context. Conditions and denied decisions never produce this value.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this activation. Associates with a commercial relationship established via sync_accounts.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate activations on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

A consumer holding one can resolve its account, decide at-most-once, echo its context and negotiate version – the whole transport-boundary job – before knowing which tool it is. issubclass(model, AdcpRequest) is the registration-time proof that a model is spec-derived rather than a hand-written parallel: a field test passes for a forged model, descent does not.

Each accessor returns the field's value, or None when this tool's schema declares no such field. Only 49 of the 87 request schemas declare an account and only 43 an idempotency_key, so asking the request is what replaces getattr(req, "account", None) against Any at the boundary.

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

• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var account : AccountReference1 | AccountReference2 | None

var action : Action | None

var context : ContextObject | None

var destinations : list[Destination1 | Destination2]

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var model_config

var pricing_option_id : str | None

var signal_agent_segment_id : str

Inherited members

• AdcpRequest:
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ActivateSignalResponse1 (**data: Any)

Expand source code

class ActivateSignalResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    deployments: list[deployment_1.Deployment]
    sandbox: bool | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

A consumer holding one can route on task state, pick up an async task_id, split envelope from payload and log uniformly, before knowing which tool answered. Which makes one generic poll-to-terminal loop possible for all 77 tasks, where today each arm has no common type at all.

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

• AdcpResponse
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var deployments : list[Deployment1 | Deployment2]

var ext : ExtensionObject | None

var model_config

var sandbox : bool | None

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ActivateSignalResponse2 (**data: Any)

Expand source code

class ActivateSignalResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

A consumer holding one can route on task state, pick up an async task_id, split envelope from payload and log uniformly, before knowing which tool answered. Which makes one generic poll-to-terminal loop possible for all 77 tasks, where today each arm has no common type at all.

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

• AdcpResponse
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class AiActRiskClass (*args, **kwds)

Expand source code

class AiActRiskClass(StrEnum):
    minimal = 'minimal'
    limited = 'limited'
    high_risk = 'high_risk'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var high_risk

var limited

var minimal

class Art9Basis (*args, **kwds)

Expand source code

class Art9Basis(StrEnum):
    explicit_consent = 'explicit_consent'
    manifestly_made_public = 'manifestly_made_public'
    substantial_public_interest = 'substantial_public_interest'
    vital_interests = 'vital_interests'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var explicit_consent

var manifestly_made_public

var substantial_public_interest

var vital_interests

class CacheScope (*args, **kwds)

Expand source code

class CacheScope(StrEnum):
    public = 'public'
    account = 'account'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var account

var public

class Channel (**data: Any)

Expand source code

class Channel(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    rights: Annotated[list[Right], Field(min_length=1)]
    url: AnyUrl | None = None
    email: EmailStr | None = None
    languages: list[str] | None = None
    countries: list[Country] | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var countries : list[Country] | None

var email : pydantic.networks.EmailStr | None

var languages : list[str] | None

var model_config

var rights : list[Right]

var url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DataSource (*args, **kwds)

Expand source code

class DataSource(StrEnum):
    app_behavior = 'app_behavior'
    app_usage = 'app_usage'
    web_usage = 'web_usage'
    geo_location = 'geo_location'
    email = 'email'
    tv_ott_or_stb_device = 'tv_ott_or_stb_device'
    panel = 'panel'
    online_ecommerce = 'online_ecommerce'
    credit_data = 'credit_data'
    loyalty_card = 'loyalty_card'
    transaction = 'transaction'
    online_survey = 'online_survey'
    offline_survey = 'offline_survey'
    public_record_census = 'public_record_census'
    public_record_voter_file = 'public_record_voter_file'
    public_record_other = 'public_record_other'
    offline_transaction = 'offline_transaction'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var app_behavior

var app_usage

var credit_data

var email

var geo_location

var loyalty_card

var offline_survey

var offline_transaction

var online_ecommerce

var online_survey

var panel

var public_record_census

var public_record_other

var public_record_voter_file

var transaction

var tv_ott_or_stb_device

var web_usage

class DataSubjectRights (**data: Any)

Expand source code

class DataSubjectRights(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    upstream_source_domain: Annotated[
        str | None,
        Field(
            max_length=253,
            pattern='^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]{0,61}[A-Za-z0-9])$',
        ),
    ] = None
    channels: Annotated[list[Channel], Field(min_length=1)]
    response_sla_days: Annotated[SchemaInt | None, Field(ge=1, le=90)] = None
    ccpa_opt_out_url: AnyUrl | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var ccpa_opt_out_url : pydantic.networks.AnyUrl | None

var channels : list[Channel]

var model_config

var response_sla_days : int | None

var upstream_source_domain : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DiscoveryMode (*args, **kwds)

Expand source code

class DiscoveryMode(StrEnum):
    brief = 'brief'
    wholesale = 'wholesale'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var brief

var wholesale

class Field1 (*args, **kwds)

Expand source code

class Field1(StrEnum):
    signal_ref = 'signal_ref'
    signal_id = 'signal_id'
    signal_agent_segment_id = 'signal_agent_segment_id'
    name = 'name'
    description = 'description'
    value_type = 'value_type'
    categories = 'categories'
    range = 'range'
    demographic_predicate = 'demographic_predicate'
    signal_type = 'signal_type'
    data_provider = 'data_provider'
    coverage_percentage = 'coverage_percentage'
    deployments = 'deployments'
    pricing_options = 'pricing_options'
    taxonomy = 'taxonomy'
    data_sources = 'data_sources'
    methodology = 'methodology'
    segmentation_criteria = 'segmentation_criteria'
    criteria_url = 'criteria_url'
    refresh_cadence = 'refresh_cadence'
    lookback_window = 'lookback_window'
    onboarder = 'onboarder'
    modeling = 'modeling'
    audience_expansion = 'audience_expansion'
    device_expansion = 'device_expansion'
    countries = 'countries'
    consent_basis = 'consent_basis'
    restricted_attributes = 'restricted_attributes'
    policy_categories = 'policy_categories'
    art9_basis = 'art9_basis'
    data_subject_rights = 'data_subject_rights'
    last_updated = 'last_updated'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var art9_basis

var audience_expansion

var categories

var consent_basis

var countries

var coverage_percentage

var criteria_url

var data_provider

var data_sources

var data_subject_rights

var demographic_predicate

var deployments

var description

var device_expansion

var last_updated

var lookback_window

var methodology

var modeling

var name

var onboarder

var policy_categories

var pricing_options

var range

var refresh_cadence

var restricted_attributes

var segmentation_criteria

var signal_agent_segment_id

var signal_id

var signal_ref

var signal_type

var taxonomy

var value_type

class GetSignalsRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as demographic_predicate, taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When demographic_predicate, consent_basis, or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own semantics or processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        SchemaInt | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

A consumer holding one can resolve its account, decide at-most-once, echo its context and negotiate version – the whole transport-boundary job – before knowing which tool it is. issubclass(model, AdcpRequest) is the registration-time proof that a model is spec-derived rather than a hand-written parallel: a field test passes for a forged model, descent does not.

Each accessor returns the field's value, or None when this tool's schema declares no such field. Only 49 of the 87 request schemas declare an account and only 43 an idempotency_key, so asking the request is what replaces getattr(req, "account", None) against Any at the boundary.

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

• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var countries : list[Country] | None

var destinations : list[Destination1 | Destination2] | None

var discovery_mode : DiscoveryMode | None

var ext : ExtensionObject | None

var fields : list[Field1] | None

var filters : SignalFilters | None

var if_pricing_version : str | None

var if_wholesale_feed_version : str | None

var max_results : int | None

var model_config

var pagination : PaginationRequest | None

var push_notification_config : PushNotificationConfig | None

var signal_ids : list[SignalId8 | SignalId9] | None

var signal_refs : list[SignalRef1 | SignalRef2 | SignalRef3] | None

var signal_spec : str | None

Inherited members

• AdcpRequest:
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class GetSignalsResponse (**data: Any)

Expand source code

class GetSignalsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    signals: Annotated[Sequence[Signal] | None, Field(description='Array of matching signals')] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
        ),
    ] = None
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description="Declares what the agent could not finish within the caller's time_budget or due to internal limits. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete.",
            min_length=1,
        ),
    ] = None
    wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque token representing the version of the wholesale signals feed state used to compose this response. Agents that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so callers can cache and probe later. Callers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A caller caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model."
        ),
    ] = None
    pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque token representing the version of the pricing layer. When the agent supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Agents not separating these MAY omit pricing_version and use wholesale_feed_version for both.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope | None,
        Field(
            description="Declares whether the wholesale_feed_version and pricing_version on this response describe a universal layer or an account-specific overlay. REQUIRED on every 3.1+ response (the 3.1 schema enforces this — the safety property of the two-layer cache model depends on it). 'public': this response describes the agent's published rate card; the caller MAY dedupe under (agent, discovery_mode, filters, destinations, countries) without scoping by account. 'account': this response includes account-specific overrides; the caller MUST cache the version under that tuple plus account_id. When the request did NOT include `account`, the agent MUST return `cache_scope: 'public'`. When the request included `account`, the agent MUST return either 'public' (this account prices off the public rate card — caller dedupes) or 'account' (account-specific overrides exist — caller caches under the account key). Agents MAY return 'public' on an account-scoped request that previously had overrides — callers SHOULD interpret this as a downgrade. Without schema-required cache_scope, an agent silently omitting the field on an account-scoped response would cause callers to mis-key the cache and serve account-overlay payloads to other accounts — the canonical safety invariant of the entire cache layering model. **Backward-compatibility note for 3.1 validators:** SDKs validating strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version`. For responses with `adcp_version` starting `3.0`, the 3.1 cache_scope-required constraint MUST be relaxed — pre-3.1 agents correctly emit no cache_scope and remain conformant to their declared version. This is a tightening within 3.1, not a 3.0 break."
        ),
    ] = CacheScope.public
    unchanged: Annotated[
        Literal[True] | None,
        Field(
            description="Present and `true` ONLY on wholesale-mode responses when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the agent's current version for the caller's cache_scope, in which case signals[] MUST be omitted; wholesale_feed_version (echoed), cache_scope (echoed), and pricing_version (echoed when used) MUST still be present. Callers receiving unchanged: true MUST NOT mutate their local wholesale signals mirror. **One shape per state:** agents MUST NOT emit `unchanged: false` — the absence of the field IS the signal that the response carries signals. **Cross-scope isolation:** the comparator that decides `unchanged` MUST be keyed on `(cache_scope, wholesale_feed_version)`, not on the token value alone. An agent MUST NOT emit `unchanged: true` when it resolves the request to a different `cache_scope` than the one whose token the caller echoed in `if_wholesale_feed_version` (and/or `if_pricing_version`): because the token is scope-keyed, a value minted for `cache_scope: 'public'` cannot match the agent's current token for `cache_scope: 'account'` (or vice-versa), so such a request MUST return the full feed for the resolved scope with that scope's own token."
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

A consumer holding one can route on task state, pick up an async task_id, split envelope from payload and log uniformly, before knowing which tool answered. Which makes one generic poll-to-terminal loop possible for all 77 tasks, where today each arm has no common type at all.

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

• AdcpResponse
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var cache_scope : CacheScope | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var incomplete : list[IncompleteItem] | None

var model_config

var pagination : PaginationResponse | None

var pricing_version : str | None

var sandbox : bool | None

var signals : collections.abc.Sequence[Signal] | None

var unchanged : Literal[True] | None

var wholesale_feed_version : str | None

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class GetSignalsSubmitted (**data: Any)

Expand source code

class GetSignalsSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['submitted'],
        Field(
            description='Task-level status literal. Discriminates this async envelope from the synchronous success shape, whose signals array is issued in-line. See task-status.json for the full task-status enum.'
        ),
    ] = 'submitted'
    task_id: Annotated[
        str,
        Field(
            description='Task handle the caller uses with get_task_status (or the legacy AdCP tasks/get alias), and that the agent references on push-notification callbacks. The signals array is issued on the completion artifact, not here. This AdCP application-layer handle remains the snake_case task_id in every transport payload and is distinct from any transport-native A2A Task id.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description="Optional human-readable explanation of why the task is submitted — e.g., 'Provider discovery queued; typical turnaround 10-30 minutes.' Plain text only. Callers MUST treat this as untrusted agent input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile agent may inject prompt-injection payloads aimed at the caller's agent.",
            max_length=2000,
        ),
    ] = None
    estimated_completion: Annotated[
        AwareDatetime | None,
        Field(description='Estimated completion time for the signal discovery task.'),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories or partial provider unavailability). Terminal failures belong in the error branch, not here.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var estimated_completion : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal['submitted']

var task_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class GetSignalsWorking (**data: Any)

Expand source code

class GetSignalsWorking(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    percentage: Annotated[
        StrictFloat | None,
        Field(
            description='Progress percentage of the signal discovery operation.', ge=0.0, le=100.0
        ),
    ] = None
    current_step: Annotated[
        str | None,
        Field(
            description='Current step in the signal discovery process, such as `querying_providers`, `ranking_signals`, or `checking_deployments`.'
        ),
    ] = None
    total_steps: Annotated[
        SchemaInt | None,
        Field(description='Total number of steps in the signal discovery process.'),
    ] = None
    step_number: Annotated[
        SchemaInt | None, Field(description='Current step number (1-indexed).')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var current_step : str | None

var ext : ExtensionObject | None

var model_config

var percentage : float | None

var step_number : int | None

var total_steps : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class IncompleteItem (**data: Any)

Expand source code

class IncompleteItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Scope,
        Field(
            description="'signals': not all matching signals were returned. 'pricing': signals returned but pricing is absent or unconfirmed. 'wholesale_feed': in wholesale mode, full feed enumeration could not complete in the time budget."
        ),
    ]
    description: Annotated[
        str, Field(description='Human-readable explanation of what is missing and why.')
    ]
    estimated_wait: Annotated[
        duration.Duration | None,
        Field(
            description='How much additional time would resolve this scope. Allows the caller to decide whether to retry with a larger time_budget.'
        ),
    ] = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var description : str

var estimated_wait : Duration | None

var model_config

var scope : Scope

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MatchKey (*args, **kwds)

Expand source code

class MatchKey(StrEnum):
    name = 'name'
    address = 'address'
    email = 'email'
    postal = 'postal'
    lat_long = 'lat_long'
    mobile_id = 'mobile_id'
    cookie_id = 'cookie_id'
    ip = 'ip'
    customer_id = 'customer_id'
    phone = 'phone'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var address

var cookie_id

var customer_id

var email

var ip

var lat_long

var mobile_id

var name

var phone

var postal

class Method (*args, **kwds)

Expand source code

class Method(StrEnum):
    lookalike = 'lookalike'
    supervised = 'supervised'
    embedding = 'embedding'
    rules = 'rules'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var embedding

var lookalike

var rules

var supervised

class Methodology (*args, **kwds)

Expand source code

class Methodology(StrEnum):
    observed = 'observed'
    declared = 'declared'
    derived = 'derived'
    inferred = 'inferred'
    modeled = 'modeled'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var declared

var derived

var inferred

var modeled

var observed

class Modeling (**data: Any)

Expand source code

class Modeling(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    method: Method
    seed_source: SeedSource
    training_data_jurisdictions: Annotated[list[TrainingDataJurisdiction], Field(min_length=1)]
    ai_act_risk_class: AiActRiskClass
    disclosure: signal_modeling_disclosure.SignalModelingDisclosure | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var ai_act_risk_class : AiActRiskClass

var disclosure : SignalModelingDisclosure | None

var method : Method

var model_config

var seed_source : SeedSource

var training_data_jurisdictions : list[TrainingDataJurisdiction]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Onboarder (**data: Any)

Expand source code

class Onboarder(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    match_keys: Annotated[list[MatchKey], Field(min_length=1)]
    pre_onboarding_audience_expansion: StrictBool | None = None
    pre_onboarding_device_expansion: StrictBool | None = None
    pre_onboarding_precision_level: PreOnboardingPrecisionLevel | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var match_keys : list[MatchKey]

var model_config

var pre_onboarding_audience_expansion : bool | None

var pre_onboarding_device_expansion : bool | None

var pre_onboarding_precision_level : PreOnboardingPrecisionLevel | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ParentMatchBehavior (*args, **kwds)

Expand source code

class ParentMatchBehavior(StrEnum):
    exact_only = 'exact_only'
    descendants_supported = 'descendants_supported'
    unknown = 'unknown'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var descendants_supported

var exact_only

var unknown

class PreOnboardingPrecisionLevel (*args, **kwds)

Expand source code

class PreOnboardingPrecisionLevel(StrEnum):
    individual = 'individual'
    household = 'household'
    business = 'business'
    geography = 'geography'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var business

var geography

var household

var individual

class Range (**data: Any)

Expand source code

class Range(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min: Annotated[StrictFloat, Field(description='Minimum value, inclusive.')]
    max: Annotated[StrictFloat, Field(description='Maximum value, inclusive.')]

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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var max : float

var min : float

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RefreshCadence (*args, **kwds)

Expand source code

class RefreshCadence(StrEnum):
    intra_day = 'intra_day'
    daily = 'daily'
    weekly = 'weekly'
    monthly = 'monthly'
    bi_monthly = 'bi_monthly'
    quarterly = 'quarterly'
    bi_annually = 'bi_annually'
    annually = 'annually'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var annually

var bi_annually

var bi_monthly

var daily

var intra_day

var monthly

var quarterly

var weekly

class Right (*args, **kwds)

Expand source code

class Right(StrEnum):
    access = 'access'
    rectification = 'rectification'
    erasure = 'erasure'
    portability = 'portability'
    objection = 'objection'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var access

var erasure

var objection

var portability

var rectification

class Scope (*args, **kwds)

Expand source code

class Scope(StrEnum):
    signals = 'signals'
    pricing = 'pricing'
    wholesale_feed = 'wholesale_feed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var pricing

var signals

var wholesale_feed

class SeedSource (**data: Any)

Expand source code

class SeedSource(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Type
    provider_signed: Annotated[
        StrictBool,
        Field(
            description='Provider assertion that the seed source carries a signed attestation. Consumers MUST NOT treat this boolean alone as cryptographic proof.'
        ),
    ]

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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var provider_signed : bool

var type : Type

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Signal (**data: Any)

Expand source code

class Signal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older Signals Protocol clients.',
        ),
    ] = None
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ] = None
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description='Opaque resolved-segment handle issued by this signal source. Pass this string verbatim to activate_signal.signal_agent_segment_id, and echo it in package signal targeting when the selected product option exposes the same handle. Treat the value as provider-scoped and opaque: providers MAY namespace it so two providers can expose similarly named signals without relying on a shared taxonomy. Do not pass the signal_id object as this handle, and do not reconstruct a segment handle from categorical values when get_signals returned a resolved segment.'
        ),
    ]
    name: Annotated[
        str,
        Field(
            description="Human-readable signal name. Required when signal_ref_1.scope is 'product'. For data_provider and signal_source refs, this is optional contextual display text; the referenced definition or source remains authoritative."
        ),
    ]
    description: Annotated[
        str,
        Field(
            description='Detailed signal description. For data_provider and signal_source refs, this is optional contextual display text and MUST NOT replace the referenced definition.'
        ),
    ]
    value_type: Annotated[
        signal_value_type.SignalValueType | None,
        Field(
            description="The data type of this signal's values. Required when signal_ref_1.scope is 'product'."
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Valid values for categorical signals. Present when value_type is 'categorical'.",
            min_length=1,
        ),
    ] = None
    range: Annotated[
        Range | None,
        Field(description="Valid range for numeric signals. Present when value_type is 'numeric'."),
    ] = None
    signal_type: Annotated[
        signal_catalog_type.SignalAvailabilityType,
        Field(description='Commercial/provenance type of signal (marketplace, custom, owned)'),
    ]
    data_provider: Annotated[
        str | None,
        Field(
            description='Human-readable source name for the signal, when applicable. For data_provider-scoped signals this is the data provider name; for signal_source-scoped signals it may identify the signal source or proprietary origin.'
        ),
    ] = None
    coverage_percentage: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only. If coverage_forecast includes an absent bucket over the same denominator, coverage_percentage SHOULD align with 100 * (1 - absent coverage_rate.mid).',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    coverage_forecast: Annotated[
        signal_coverage_forecast.SignalCoverageForecast | None,
        Field(
            description='Optional forecast-shaped signal availability guidance. When present, this is authoritative for signal-level discovery coverage. Use this to disclose the denominator, bucket semantics, not-present bucket, aggregate present bucket, and per-value coverage distribution for the signal.'
        ),
    ] = None
    deployments: Annotated[
        Sequence[deployment.Deployment], Field(description='Array of deployment targets')
    ]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options available for this signal when it has an incremental price. The buyer selects one and passes its pricing_option_id in report_usage or package-level signal_targeting_groups for billing verification. Omit when pricing is unavailable to the caller, bundled into the destination product, or has no incremental cost.',
            min_length=1,
        ),
    ] = None
    methodology_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this definition record was last updated. This indicates freshness of the definition record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(description='Restricted attribute categories this signal touches.', min_length=1),
    ] = None
    demographic_predicate: Annotated[
        demographic_predicate_1.DemographicPredicate | None,
        Field(
            description="Projected authoritative demographic meaning for the signal. When projected from another provider, this MUST match the provider's definition exactly. Signal names alone never establish demographic semantics."
        ),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(description='Policy categories this signal is sensitive for.', min_length=1),
    ] = None
    taxonomy: Annotated[
        Taxonomy | None,
        Field(
            description='Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.'
        ),
    ] = None
    segmentation_criteria: Annotated[str | None, Field(max_length=500)] = None
    criteria_url: AnyUrl | None = None
    data_sources: Annotated[list[DataSource] | None, Field(min_length=1)] = None
    methodology: Methodology | None = None
    audience_expansion: StrictBool | None = None
    device_expansion: StrictBool | None = None
    refresh_cadence: RefreshCadence | None = None
    lookback_window: RefreshCadence | None = None
    onboarder: Onboarder | None = None
    countries: Annotated[list[Country] | None, Field(min_length=1)] = None
    consent_basis: Annotated[
        list[consent_basis_1.ConsentBasis] | None,
        Field(
            description="Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.",
            min_length=1,
        ),
    ] = None
    art9_basis: Annotated[
        Art9Basis | None,
        Field(
            description="Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis."
        ),
    ] = None
    modeling: Modeling | None = None
    data_subject_rights: Annotated[
        DataSubjectRights | None,
        Field(
            description='Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.'
        ),
    ] = None
    dts_compliant_version: str | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var art9_basis : Art9Basis | None

var audience_expansion : bool | None

var categories : list[str] | None

var consent_basis : list[ConsentBasis] | None

var countries : list[Country] | None

var coverage_forecast : SignalCoverageForecast | None

var coverage_percentage : float | None

var criteria_url : pydantic.networks.AnyUrl | None

var data_provider : str | None

var data_sources : list[DataSource] | None

var data_subject_rights : DataSubjectRights | None

var demographic_predicate : DemographicPredicate | None

var deployments : Sequence[Deployment1 | Deployment2]

var description : str

var device_expansion : bool | None

var dts_compliant_version : str | None

var last_updated : pydantic.types.AwareDatetime | None

var lookback_window : RefreshCadence | None

var methodology : Methodology | None

var methodology_url : pydantic.networks.AnyUrl | None

var model_config

var modeling : Modeling | None

var name : str

var onboarder : Onboarder | None

var policy_categories : list[str] | None

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var range : Range | None

var refresh_cadence : RefreshCadence | None

var restricted_attributes : list[RestrictedAttribute] | None

var segmentation_criteria : str | None

var signal_agent_segment_id : str

var signal_id : SignalId8 | SignalId9 | None

var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None

var signal_type : SignalAvailabilityType

var taxonomy : Taxonomy | None

var value_type : SignalValueType | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Taxonomy (**data: Any)

Expand source code

class Taxonomy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    ref: AnyUrl
    version: str | None = None
    segtax: Annotated[SchemaInt | None, Field(ge=1)] = None
    etag: str | None = None
    values: Annotated[list[Value], Field(min_length=1)]
    value_mappings: Annotated[list[ValueMapping] | None, Field(min_length=1)] = None
    parent_match_behavior: ParentMatchBehavior | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var etag : str | None

var model_config

var parent_match_behavior : ParentMatchBehavior | None

var ref : pydantic.networks.AnyUrl

var segtax : int | None

var value_mappings : list[ValueMapping] | None

var values : list[Value]

var version : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class TrainingDataJurisdiction (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class TrainingDataJurisdiction(Country):
    pass

A str generated from a JSON Schema string root.

Ancestors

• Country
• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class Type (*args, **kwds)

Expand source code

class Type(StrEnum):
    first_party_crm = 'first_party_crm'
    panel = 'panel'
    declared_survey = 'declared_survey'
    transactional = 'transactional'
    behavioral = 'behavioral'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var behavioral

var declared_survey

var first_party_crm

var panel

var transactional

class Value (**data: Any)

Expand source code

class Value(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    id: Annotated[str, Field(min_length=1)]
    path: str | None = None
    modifiers: list[str] | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var id : str

var model_config

var modifiers : list[str] | None

var path : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ValueMapping (**data: Any)

Expand source code

class ValueMapping(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    value: str
    taxonomy_value_id: str
    path: str | None = None
    modifiers: list[str] | None = 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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var modifiers : list[str] | None

var path : str | None

var taxonomy_value_id : str

var value : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary