Module adcp.decisioning.property_list
Property-list resolver and product intersection helper for get_products.
Capability-gated framework support for the property_list buyer-side filter
on get_products.
When an adopter declares
Features(property_list_filtering=True) on their
:class:~adcp.decisioning.platform.DecisioningCapabilities, the framework
automatically (using MCP by default):
- Resolves the buyer's typed property list over MCP, including all pages.
- Applies :func:
filter_products_by_property_list()to the platform's response. - Sets
response.property_list_applied = Trueon the returned envelope.
Adopters who want to apply the filter themselves (e.g., pushed down into a DB
query) retain Features(property_list_filtering=True) and pass
property_list_filter_mode="platform" to the server builder. They own both
filtering and the property_list_applied response flag; the SDK does not fetch
or filter in that mode.
Reference pattern: :mod:adcp.decisioning.webhook_emit (capability-gated
post-adapter side effect).
Functions
def filter_products_by_property_list(products: list[Any], allowed_property_ids: set[str]) ‑> list[typing.Any]-
Expand source code
def filter_products_by_property_list( products: list[Any], allowed_property_ids: set[str], ) -> list[Any]: """Filter a product list to those matching the buyer's authorized property IDs. Respects ``publisher_properties.selection_type``: * ``'all'`` — product covers all publisher properties; always included. * ``'by_id'`` — intersect the product's ``property_ids`` with ``allowed_property_ids``. * ``'by_tag'`` — property tags cannot be matched against a property ID list; this entry does not contribute to inclusion. Respects ``product.property_targeting_allowed``: * ``False`` (default, "all or nothing") — the product's full set of ``by_id`` property IDs must be a subset of ``allowed_property_ids``. * ``True`` (permissive) — any non-empty intersection is sufficient. A product is included if ANY of its ``publisher_properties`` entries passes the filter. This models the semantics of a product covering inventory from multiple publishers: if ANY publisher's inventory is in the buyer's allowed set, the product is relevant. :param products: Products from the platform's ``get_products`` response. :param allowed_property_ids: Set of property_id strings the buyer is authorized to spend on (result of :func:`resolve_property_list`). :returns: Filtered product list; original order preserved. """ return [p for p in products if _product_matches(p, allowed_property_ids)]Filter a product list to those matching the buyer's authorized property IDs.
Respects
publisher_properties.selection_type:'all'— product covers all publisher properties; always included.'by_id'— intersect the product'sproperty_idswithallowed_property_ids.'by_tag'— property tags cannot be matched against a property ID list; this entry does not contribute to inclusion.
Respects
product.property_targeting_allowed:False(default, "all or nothing") — the product's full set ofby_idproperty IDs must be a subset ofallowed_property_ids.True(permissive) — any non-empty intersection is sufficient.
A product is included if ANY of its
publisher_propertiesentries passes the filter. This models the semantics of a product covering inventory from multiple publishers: if ANY publisher's inventory is in the buyer's allowed set, the product is relevant.:param products: Products from the platform's
get_productsresponse. :param allowed_property_ids: Set of property_id strings the buyer is authorized to spend on (result of :func:resolve_property_list()). :returns: Filtered product list; original order preserved. async def maybe_apply_property_list_filter(*,
params: Any,
response: Any,
fetcher: PropertyListFetcher | None,
capability_enabled: bool,
filter_mode: "Literal['sdk', 'platform']" = 'sdk') ‑> Any-
Expand source code
async def maybe_apply_property_list_filter( *, params: Any, response: Any, fetcher: PropertyListFetcher | None, capability_enabled: bool, filter_mode: Literal["sdk", "platform"] = "sdk", ) -> Any: """Post-adapter gate: apply property-list filtering to a get_products response. Called by the ``get_products`` handler shim after the platform method returns. The gate is a no-op when either: * ``capability_enabled`` is False (adopter hasn't declared the feature). * ``params.property_list`` is absent (buyer didn't send a list reference). When ``fetcher`` is None, use the built-in MCP resolver. Platform mode returns the seller's response untouched, including its ``property_list_applied`` flag. SDK mode copies dict/model responses to avoid mutating the platform's return value. :raises AdcpError: ``recovery='transient'`` propagated from :func:`resolve_property_list` on fetch failure. """ if filter_mode == "platform" or not capability_enabled: return response from adcp.property_lists import ( MCPPropertyListFetcher, ProductPropertyPolicy, _default_property_list_fetcher, request_property_list, ) property_list_ref = request_property_list(params) if property_list_ref is None: return response # Submitted/unchanged/error envelopes must keep their original semantics. if _field(response, "status") in {"submitted", "working", "input-required"}: return response outcome = _field(response, "outcome") if outcome in {"unchanged", "rejected"} or _field(response, "products") is None: return response fetcher = fetcher if fetcher is not None else _default_property_list_fetcher() products: list[Any] = list(_field(response, "products") or []) applied = True if isinstance(fetcher, MCPPropertyListFetcher): allowed_list = await fetcher.resolve(property_list_ref) policy = ProductPropertyPolicy(fetcher=fetcher) # Products with no declared property inventory cannot match a property # list. Exclude them, as the custom property-ID path already does. candidates = [product for product in products if _field(product, "publisher_properties")] assessments = await policy.assess(candidates, allowed_list, seller_url="") # Declared inventory that cannot be resolved remains a transient error. if any(item.status == "unjudgeable" for item in assessments): from adcp.decisioning.types import AdcpError raise AdcpError( "SERVICE_UNAVAILABLE", message="Product property expansion failed", recovery="transient", ) filtered = [ product for product, item in zip(candidates, assessments) if item.status == "match" ] else: allowed = await resolve_property_list(property_list_ref, fetcher=fetcher) filtered = filter_products_by_property_list(products, allowed) update: dict[str, Any] = {"products": filtered} # Compact response schemas forbid arbitrary top-level fields. Report the # acknowledgement through ext; legacy discovery has a dedicated field. if outcome in {"listed", "products_available", "proposed"}: ext = _field(response, "ext") or {} if hasattr(ext, "model_dump"): ext = ext.model_dump(mode="json") update["ext"] = {**ext, "property_list_applied": applied} if not isinstance(response, dict): from adcp.types.domains.core.ext import ExtensionObject update["ext"] = ExtensionObject.model_validate(update["ext"]) else: update["property_list_applied"] = applied if outcome in {"products_available", "proposed"} and len(filtered) != len(products): continuation = _field(response, "purchase_continuation") if ( not filtered or outcome == "proposed" or _field(continuation, "kind") != "listed_purchase" ): # Proposals have immutable commercial terms and a bound digest; # legacy continuations bind an opaque observed payload. Neither # can be rewritten safely after removing one of its products. rejected = ( dict(response) if isinstance(response, dict) else response.model_dump(mode="json", exclude_none=True) ) rejected.update( outcome="rejected", reason="The available products do not satisfy the requested property list.", ext=( update["ext"] if isinstance(update["ext"], dict) else update["ext"].model_dump(mode="json") ), ) for name in ("products", "proposals", "purchase_continuation", "incomplete", "task_id"): rejected.pop(name, None) if isinstance(response, dict): return rejected from pydantic import TypeAdapter from adcp.types.domains.media_buy.request_proposals_response import ( RequestProposalsResponse, ) return TypeAdapter(RequestProposalsResponse).validate_python(rejected) product_ids = [str(_field(product, "product_id")) for product in filtered] update["purchase_continuation"] = ( {**continuation, "product_ids": product_ids} if isinstance(continuation, dict) else continuation.model_copy(update={"product_ids": product_ids}) ) if isinstance(response, dict): return {**response, **update} return response.model_copy(update=update)Post-adapter gate: apply property-list filtering to a get_products response.
Called by the
get_productshandler shim after the platform method returns. The gate is a no-op when either:capability_enabledis False (adopter hasn't declared the feature).params.property_listis absent (buyer didn't send a list reference).
When
fetcheris None, use the built-in MCP resolver.Platform mode returns the seller's response untouched, including its
property_list_appliedflag. SDK mode copies dict/model responses to avoid mutating the platform's return value.:raises AdcpError:
recovery='transient'propagated from :func:resolve_property_list()on fetch failure. def property_list_capability_enabled(platform: Any) ‑> bool-
Expand source code
def property_list_capability_enabled(platform: Any) -> bool: """Return True if ``platform.capabilities.media_buy.features.property_list_filtering`` is set. Centralises the three-level ``getattr`` chain used in both ``handler.py`` and ``serve.py`` so they can't drift apart. """ media_buy = getattr(getattr(platform, "capabilities", None), "media_buy", None) features = getattr(media_buy, "features", None) return bool(getattr(features, "property_list_filtering", False))Return True if
platform.capabilities.media_buy.features.property_list_filteringis set.Centralises the three-level
getattrchain used in bothhandler.pyandserve.pyso they can't drift apart. async def resolve_property_list(ref: Any,
*,
fetcher: PropertyListFetcher | None = None) ‑> set[str]-
Expand source code
async def resolve_property_list( ref: Any, *, fetcher: PropertyListFetcher | None = None, ) -> set[str]: """Resolve canonical identifier values (or legacy custom-fetcher property IDs). :param ref: ``PropertyList`` wire object (has ``agent_url``, ``list_id``, ``auth_token``). :param fetcher: Optional custom fetcher; defaults to a cached MCP resolver. :returns: Set of allowed canonical values. Use MCPPropertyListFetcher.resolve when identifier types are needed for matching. :raises AdcpError: ``recovery='transient'`` on any fetch failure. ``auth_token`` is never included in the error details. """ from adcp.decisioning.types import AdcpError from adcp.property_lists import MCPPropertyListFetcher, _default_property_list_fetcher from adcp.webhooks import ( WebhookDestinationPolicy, WebhookDestinationValidationError, validate_webhook_destination_url, ) fetcher = fetcher if fetcher is not None else _default_property_list_fetcher() if isinstance(fetcher, MCPPropertyListFetcher): resolved = await fetcher.resolve(ref) return {identifier.value for identifier in resolved.identifiers} list_id: str = _field(ref, "list_id") agent_url: str = str(_field(ref, "agent_url")) auth_token: str | None = _field(ref, "auth_token") if not re.fullmatch(r"[A-Za-z0-9._~-]+", list_id): raise AdcpError( "INVALID_REQUEST", message="Property list_id must be a single URL-safe path segment", recovery="correctable", details={"list_id": list_id}, ) try: validation = validate_webhook_destination_url( agent_url, policy=WebhookDestinationPolicy.production(), field="property_list.agent_url", ) except WebhookDestinationValidationError as exc: raise AdcpError( "INVALID_REQUEST", message="Property list agent_url failed destination policy", recovery="correctable", details={"reason": exc.reason}, ) from None parsed = urlsplit(validation.original_url) safe_origin = f"{parsed.scheme}://{parsed.hostname or ''}" if parsed.port is not None: safe_origin += f":{parsed.port}" try: ids = await fetcher.fetch(validation.original_url, list_id, auth_token=auth_token) return set(ids) except Exception as exc: # Exception text may carry auth_token or credential-shaped upstream # values. Log only the class and deliberately omit the exception chain. logger.warning( "[adcp.property_list] fetch failed for list_id=%r agent_origin=%r (%s)", list_id, safe_origin, type(exc).__name__, ) raise AdcpError( "SERVICE_UNAVAILABLE", message=( f"Property list fetch failed for list_id={list_id!r} " f"from agent_origin={safe_origin!r}" ), recovery="transient", details={"list_id": list_id, "agent_origin": safe_origin}, ) from NoneResolve canonical identifier values (or legacy custom-fetcher property IDs).
:param ref:
PropertyListwire object (hasagent_url,list_id,auth_token). :param fetcher: Optional custom fetcher; defaults to a cached MCP resolver. :returns: Set of allowed canonical values. Use MCPPropertyListFetcher.resolve when identifier types are needed for matching. :raises AdcpError:recovery='transient'on any fetch failure.auth_tokenis never included in the error details. def validate_property_list_config(*,
capability_enabled: bool,
fetcher: PropertyListFetcher | None,
filter_mode: "Literal['sdk', 'platform']" = 'sdk') ‑> None-
Expand source code
def validate_property_list_config( *, capability_enabled: bool, fetcher: PropertyListFetcher | None, filter_mode: Literal["sdk", "platform"] = "sdk", ) -> None: """Validate ownership mode; SDK mode has a built-in MCP fetcher.""" if filter_mode not in {"sdk", "platform"}: raise ValueError("property_list_filter_mode must be 'sdk' or 'platform'") # A built-in MCP fetcher is available when no custom dependency is supplied. returnValidate ownership mode; SDK mode has a built-in MCP fetcher.
Classes
class PropertyListFetcher (*args, **kwargs)-
Expand source code
@runtime_checkable class PropertyListFetcher(Protocol): """Adopter-supplied protocol for fetching a buyer's authorized property IDs. Custom fetchers may return publisher property IDs for existing integrations. The default :class:`adcp.property_lists.MCPPropertyListFetcher` resolves typed identifiers using the MCP ``get_property_list`` tool at ``agent_url`` with the reference's bearer token, follows pagination, and caches until ``cache_valid_until``. No REST path convention is assumed. Custom network implementations MUST pin delivery to a validated public IP, disable redirects and environment proxies, and never log bearer tokens. """ async def fetch( self, agent_url: str, list_id: str, *, auth_token: str | None = None, ) -> list[str]: """Fetch and return the list of allowed property_id strings. :param agent_url: Buyer agent URL from the wire ``PropertyList`` reference. :param list_id: Property list identifier. :param auth_token: Optional JWT/bearer token. Never log this value. :returns: List of allowed property_id strings (``^[a-z0-9_]+$`` format). :raises Exception: Any exception; the framework wraps it in :class:`~adcp.decisioning.types.AdcpError` with ``recovery='transient'``. """ ...Adopter-supplied protocol for fetching a buyer's authorized property IDs.
Custom fetchers may return publisher property IDs for existing integrations. The default :class:
MCPPropertyListFetcherresolves typed identifiers using the MCPget_property_listtool atagent_urlwith the reference's bearer token, follows pagination, and caches untilcache_valid_until. No REST path convention is assumed.Custom network implementations MUST pin delivery to a validated public IP, disable redirects and environment proxies, and never log bearer tokens.
Ancestors
- typing.Protocol
- typing.Generic
Methods
async def fetch(self, agent_url: str, list_id: str, *, auth_token: str | None = None) ‑> list[str]-
Expand source code
async def fetch( self, agent_url: str, list_id: str, *, auth_token: str | None = None, ) -> list[str]: """Fetch and return the list of allowed property_id strings. :param agent_url: Buyer agent URL from the wire ``PropertyList`` reference. :param list_id: Property list identifier. :param auth_token: Optional JWT/bearer token. Never log this value. :returns: List of allowed property_id strings (``^[a-z0-9_]+$`` format). :raises Exception: Any exception; the framework wraps it in :class:`~adcp.decisioning.types.AdcpError` with ``recovery='transient'``. """ ...Fetch and return the list of allowed property_id strings.
:param agent_url: Buyer agent URL from the wire
PropertyListreference. :param list_id: Property list identifier. :param auth_token: Optional JWT/bearer token. Never log this value. :returns: List of allowed property_id strings (^[a-z0-9_]+$format). :raises Exception: Any exception; the framework wraps it in :class:~adcp.decisioning.types.AdcpErrorwithrecovery='transient'.