Module adcp.types.domains.signals.get_signals_request

Classes

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

Expand source code

class Country(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}$'}

A str generated from a JSON Schema string root.

Ancestors

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

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