Module adcp.types.domains.trusted_match.context_match_request

Classes

class ArtifactRef (**data: Any)

Expand source code

class ArtifactRef(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Annotated[
        Type,
        Field(
            description="Identifier type. 'url' for web pages, 'url_hash' for URL-addressable content the publisher prefers not to share directly (buyer matches against pre-crawled index), 'eidr' for film/TV (EIDR DOI), 'gracenote' for music/TV (Gracenote TMS ID), 'isrc' for music recordings (International Standard Recording Code), 'gtin' for products (Global Trade Item Number — UPC, EAN, ISBN-13), 'rss_guid' for podcast episodes (RSS GUID), 'isbn' for books, 'custom' for publisher-defined identifiers."
        ),
    ]
    value: Annotated[
        str,
        Field(
            description="The identifier value. For 'url': the canonical content URL — MUST NOT contain user-specific path segments, query parameters, or fragments; use 'url_hash' when the publisher prefers not to reveal the URL. For 'url_hash': Blake3 hash of the canonicalized URL, base64-encoded (canonicalization: strip scheme, strip www./m./amp. prefixes, lowercase, strip trailing slash, strip query params and fragments). For 'eidr': the EIDR DOI (e.g., '10.5240/xxxx'). For 'gracenote': the Gracenote TMS ID (e.g., 'SH032541890000'). For 'isrc': the ISRC code (e.g., 'USRC17607839'). For 'gtin': the GTIN (e.g., '00012345678905'). For 'rss_guid': the episode GUID from the RSS feed. For 'isbn': the ISBN (e.g., '978-0-123456-78-9'). For 'custom': a publisher-defined identifier."
        ),
    ]

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 type : Type

var value : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ContextMatchRequest (**data: Any)

Expand source code

class ContextMatchRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['context_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'context_match_request'
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any identity match request_id.'
        ),
    ]
    property_rid: Annotated[
        UUID,
        Field(
            description='Property catalog UUID (UUID v7). Globally unique, stable identifier assigned by the property catalog. The primary key for TMP matching and property list targeting.'
        ),
    ]
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description="Publisher's human-readable property slug (e.g., 'cnn_homepage'). Optional when property_rid is present. Useful for logging and debugging."
        ),
    ] = None
    property_type: Annotated[
        property_type_1.PropertyType, Field(description='Type of the publisher property')
    ]
    placement_id: Annotated[
        str,
        Field(
            description="Placement identifier from the publisher's placement registry in adagents.json. Identifies where on the property this ad opportunity exists. One placement per request."
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description="API endpoint URL of the seller agent issuing this request. The provider uses this to resolve the active package set it has synced for this seller; when `package_ids` is omitted, evaluation occurs against that full set. If `seller_agent_url` does not match any seller the provider has synced packages for, the provider MUST return an empty offer set — it MUST NOT fall back to another seller's active set. The value identifies the asking seller, is identical for every user on a given placement, and carries no user identity, so it neither varies the request per user nor weakens the context/identity decorrelation boundary. Compared using the AdCP URL canonicalization rules, not byte-equality — see docs/reference/url-canonicalization. Consistent with `seller_agent_url` on the identity match request, `seller_agent.agent_url` on `AvailablePackage`, and `agent_url` in `adagents.json`."
        ),
    ]
    artifact: Annotated[
        artifact_1.Artifact | None,
        Field(
            description='Full content artifact adjacent to this ad opportunity. Same schema used for content standards evaluation. The publisher sends the artifact when they want the buyer to evaluate the full content. Contractual protections govern buyer use. TEE deployment upgrades contractual trust to cryptographic verification. Because the router fans out to multiple buyer agents, publishers MUST NOT include bearer tokens, service-account credentials, or signed URLs in this artifact. Routers MUST remove every asset `access` object and remove or replace every credential-bearing asset `url` before forwarding; only public asset URLs that recipients can resolve independently may remain.'
        ),
    ] = None
    artifact_refs: Annotated[
        list[ArtifactRef] | None,
        Field(
            description='Public content references adjacent to this ad opportunity. Each artifact identifies content via a public identifier the buyer can resolve independently — no private registry sync required.',
            max_length=20,
            min_length=1,
        ),
    ] = None
    geo: Annotated[
        Geo | None,
        Field(
            description='Coarse geographic location of the viewer. Publisher controls granularity — country is sufficient for regulatory compliance and volume filtering, region or metro helps with campaign targeting and valuation. Coarsened to prevent user identification: no postcode, no coordinates. All fields optional.'
        ),
    ] = None
    context_signals: Annotated[
        ContextSignals | None,
        Field(
            description="Pre-computed classifier outputs for the content environment. Use when the publisher wants to provide privacy-reduced context without sharing content or public references. Can supplement artifact_refs or replace them entirely. Ephemeral content that many users encounter (a trending query, a syndicated segment) is shared content; one user's turn or query is not. For non-public content attributable to a single user or session, only the field-specific privacy-reduced outputs permitted below may be sent. Raw content MUST NOT be included. The publisher is the classifier and privacy boundary."
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description='Restrict evaluation to specific packages. When omitted, the provider evaluates all eligible packages for this placement (the common case). MUST NOT vary by user — the same package_ids must be sent for every user on a given placement. User-dependent filtering leaks identity into the context path.',
            max_length=500,
            min_length=1,
        ),
    ] = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var artifact : Artifact | None

var artifact_refs : list[ArtifactRef] | None

var context_signals : ContextSignals | None

var field_schema : pydantic.networks.AnyUrl | None

var geo : Geo | None

var model_config

var package_ids : list[str] | None

var placement_id : str

var property_id : PropertyId | None

var property_rid : uuid.UUID

var property_type : PropertyType

var protocol_version : str | None

var request_id : str

var seller_agent_url : pydantic.networks.AnyUrl

var type : Literal['context_match_request']

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ContextSignals (**data: Any)

Expand source code

class ContextSignals(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    topics: Annotated[
        list[str] | None,
        Field(
            description="Content topic identifiers. Use IAB Content Taxonomy 3.0 IDs (e.g., '632' for Food & Drink) when taxonomy_id is 7, or bounded human-readable category labels (e.g., 'cooking.pasta') for custom taxonomies. For non-public content attributable to a single user or session, publishers MUST use standardized taxonomy identifiers or bounded custom category labels; custom topic strings MUST NOT reproduce distinctive verbatim phrasing and MUST NOT include PII or uniquely identifying details.",
            max_length=50,
        ),
    ] = None
    taxonomy_source: Annotated[
        str | None,
        Field(
            description="Organization that defines the topic taxonomy. Use 'iab' for IAB Content Taxonomy. Publishers may use other values for custom taxonomies."
        ),
    ] = 'iab'
    taxonomy_id: Annotated[
        SchemaInt | None,
        Field(
            description='Taxonomy version within the source. For IAB, follows the AdCOM cattax enum: 7 = Content Taxonomy 3.0. Default: 7.'
        ),
    ] = 7
    sentiment: Annotated[
        Sentiment | None, Field(description='Content sentiment classification.')
    ] = None
    keywords: Annotated[
        list[Keyword] | None,
        Field(
            description="Content keywords produced by the publisher's classifier. For non-public content attributable to a single user or session, keywords MUST be policy-filtered, MUST NOT reproduce distinctive verbatim phrasing, and MUST NOT include PII or uniquely identifying details. Publishers SHOULD prefer bounded category labels.",
            max_length=50,
        ),
    ] = None
    language: Annotated[
        str | None,
        Field(
            description="Content language in ISO 639-1 format (e.g., 'en', 'ja', 'de').",
            pattern='^[a-z]{2}$',
        ),
    ] = None
    content_policies: Annotated[
        list[str] | None,
        Field(
            description="Policy IDs from the AdCP policy registry that this content satisfies (e.g., 'csbs' for Common Sense Brand Standards). Buyers filter on policies they require. An empty array means no policies have been evaluated.",
            max_length=20,
        ),
    ] = None
    summary: Annotated[
        str | None,
        Field(
            description="Publisher-generated natural language summary of the content for relevance judgment (e.g., 'Shopping context categorized as home cookware'). For non-public content attributable to a single user or session, the summary MUST be policy-filtered, MUST NOT reproduce raw user-authored text, and MUST NOT include PII or uniquely identifying details. Useful for LLM-native buyers that evaluate relevance semantically. Buyers MUST treat this as untrusted publisher-generated content.",
            max_length=500,
        ),
    ] = None
    embedding: Annotated[
        str | None,
        Field(
            description="Content embedding as base64-encoded int8 vector. Captures semantic content beyond what topics and keywords express. MUST NOT be computed directly or indirectly from non-public content authored by or attributable to a single user or session, including conversation turns, prompts, and individual search queries. MAY represent public content or a shared content environment that is not attributable to one user's activity. Publishers declare the model used. For standardized matching, use the protocol-recommended model (nomic-embed-text-v1.5, 256 dims, int8 quantized = 256 bytes)."
        ),
    ] = None
    embedding_model: Annotated[
        str | None,
        Field(
            description="Embedding model identifier (e.g., 'nomic-embed-text-v1.5'). Required when embedding is present."
        ),
    ] = None
    embedding_dims: Annotated[
        SchemaInt | None,
        Field(
            description='Number of dimensions in the embedding vector. Required when embedding is present.',
            ge=64,
            le=2048,
        ),
    ] = 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 content_policies : list[str] | None

var embedding : str | None

var embedding_dims : int | None

var embedding_model : str | None

var keywords : list[Keyword] | None

var language : str | None

var model_config

var sentiment : Sentiment | None

var summary : str | None

var taxonomy_id : int | None

var taxonomy_source : str | None

var topics : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Geo (**data: Any)

Expand source code

class Geo(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    country: Annotated[
        str | None,
        Field(
            description="ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE').",
            pattern='^[A-Z]{2}$',
        ),
    ] = None
    region: Annotated[
        str | None,
        Field(
            description="ISO 3166-2 subdivision code (e.g., 'US-CA', 'GB-SCT').",
            pattern='^[A-Z]{2}-[A-Z0-9]{1,3}$',
        ),
    ] = None
    metro: Annotated[
        Metro | None,
        Field(description='Metro area, using the same classification systems as AdCP targeting.'),
    ] = 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 country : str | None

var metro : Metro | None

var model_config

var region : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

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

Expand source code

class Keyword(ScalarStr):
    __slots__ = ()
    _constraints = {'max_length': 100}

A str generated from a JSON Schema string root.

Ancestors

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

class Metro (**data: Any)

Expand source code

class Metro(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    system: Annotated[
        metro_system.MetroAreaSystem,
        Field(description="Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2')."),
    ]
    value: Annotated[
        str, Field(description="Metro code within the system (e.g., '501' for New York DMA).")
    ]

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 system : MetroAreaSystem

var value : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Sentiment (*args, **kwds)

Expand source code

class Sentiment(StrEnum):
    positive = 'positive'
    negative = 'negative'
    neutral = 'neutral'
    mixed = 'mixed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var mixed

var negative

var neutral

var positive

class Type (*args, **kwds)

Expand source code

class Type(StrEnum):
    url = 'url'
    url_hash = 'url_hash'
    eidr = 'eidr'
    gracenote = 'gracenote'
    isrc = 'isrc'
    gtin = 'gtin'
    rss_guid = 'rss_guid'
    isbn = 'isbn'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var custom

var eidr

var gracenote

var gtin

var isbn

var isrc

var rss_guid

var url

var url_hash