From c117bf3e90f5e8e304b234142155b706dd3eeb25 Mon Sep 17 00:00:00 2001 From: adam Date: Wed, 8 Oct 2025 13:06:04 -0500 Subject: [PATCH 1/4] initial commit --- CODE_OF_CONDUCT.md | 0 CONTRIBUTING.md | 0 LICENSE | 93 ++++++++ LICENSE-APACHE | 202 ++++++++++++++++++ README.md | 120 ++++++++++- TRADEMARK.md | 45 ++++ community/README.md | 0 docs/README.md | 0 specs/roadmap.md | 0 specs/v1.0/README.md | 0 specs/v1.0/examples/buyer_agent_request.json | 0 specs/v1.0/examples/embedding_update.json | 0 .../v1.0/examples/seller_agent_response.json | 0 specs/v1.0/schema/agent_interface.schema.json | 0 .../v1.0/schema/embedding_format.schema.json | 0 15 files changed, 458 insertions(+), 2 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 LICENSE-APACHE create mode 100644 TRADEMARK.md create mode 100644 community/README.md create mode 100644 docs/README.md create mode 100644 specs/roadmap.md create mode 100644 specs/v1.0/README.md create mode 100644 specs/v1.0/examples/buyer_agent_request.json create mode 100644 specs/v1.0/examples/embedding_update.json create mode 100644 specs/v1.0/examples/seller_agent_response.json create mode 100644 specs/v1.0/schema/agent_interface.schema.json create mode 100644 specs/v1.0/schema/embedding_format.schema.json diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..e69de29 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e69de29 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4eb035e --- /dev/null +++ b/LICENSE @@ -0,0 +1,93 @@ +User Context Protocol (UCP) +Copyright (c) 2025 LiveRamp Holdings, Inc. + +====================================================================== +LICENSE OVERVIEW +====================================================================== + +This repository contains two types of materials, each with its own license: + +1. Specifications, schemas, and documentation + Licensed under: Creative Commons Attribution 4.0 International (CC BY 4.0) + See: https://creativecommons.org/licenses/by/4.0/ + +2. Reference implementations, SDKs, and source code + Licensed under: Apache License 2.0 + See: https://www.apache.org/licenses/LICENSE-2.0 + +Trademarks: +"User Context Protocol" is a trademark of LiveRamp Holdings, Inc. +Use of these marks is subject to the terms described in TRADEMARK.md and is not +granted by either license above. + +====================================================================== +LICENSE DETAILS +====================================================================== + +---------------------------------------------------------------------- +A. Specification and Documentation License (CC BY 4.0) +---------------------------------------------------------------------- + +Files covered: +- All Markdown files under /specs and /docs +- All schema and example files (.json, .yaml, .yml, .md) in the specification tree +- Any whitepapers, diagrams, and explanatory materials describing UCP + +Summary: +You are free to share and adapt the specification for any purpose, provided +that attribution is given to LiveRamp Holdings, Inc. + +Full license text available at: +https://creativecommons.org/licenses/by/4.0/legalcode.txt + +Example attribution: +"Portions of this work are based on the User Context Protocol, +developed by LiveRamp Holdings, Inc. (CC BY 4.0)." + +---------------------------------------------------------------------- +B. Software and Reference Implementation License (Apache 2.0) +---------------------------------------------------------------------- + +Files covered: +- Source code in /reference, /sdk, /tools, /tests, and related directories +- Build and configuration files used to execute or test reference implementations + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this software except in compliance with the License. +You may obtain a copy of the License at: + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed +under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +---------------------------------------------------------------------- +C. Trademark Notice +---------------------------------------------------------------------- + +The names "User Context Protocol" and "UCP" are trademarks of +LiveRamp Holdings, Inc. and are not included under either open-source license. + +You may not use these names or logos to imply endorsement, affiliation, +or official status without express written permission. + +For full details, see TRADEMARK.md. + +---------------------------------------------------------------------- +D. Contact +---------------------------------------------------------------------- + +For legal inquiries or permission requests, contact: + +LiveRamp Holdings, Inc. +Attn: Legal Department – User Context Protocol +225 Bush Street, 17th Floor +San Francisco, CA 94104 +Email: legal@liveramp.com + +====================================================================== +END OF LICENSE FILE +====================================================================== \ No newline at end of file diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/README.md b/README.md index 8107793..3c1b1f5 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,118 @@ -# user-context-protocol -An open standard by LiveRamp defining how intelligent agents exchange user context, enabling interoperability from prompt-based LLM coordination to embedding-based optimization. +# User Context Protocol™ (UCP) + +An Open Protocol for Intelligent Interoperability Across Advertising Agents + +--- + +## Overview + +The User Context Protocol (UCP) is an open standard proposed by LiveRamp to enable intelligent agents in advertising and marketing to interoperate with precision and efficiency. + +As the industry transitions into the agentic web, where autonomous buyer, seller, and measurement agents act on behalf of users and organizations, UCP provides a common language for exchanging context, intent, and results. +It defines how agents communicate, how context is shared and updated, and how intelligence can evolve from prompt-based reasoning to learned representations. + +--- + +## Motivation + +Today, the rise of large language models (LLMs) and agent frameworks has made it possible for general-purpose agents to plan, reason, and execute tasks using text-based prompts. +Frameworks such as the Model Context Protocol (MCP) define how these agents interact with external tools and APIs. +However, prompt-driven coordination is inefficient for high-frequency, data-intensive workflows like advertising optimization. + +UCP bridges this gap by defining a path from prompt-based interaction to embedding-based interoperability. + +1. **Phase 1 – Agent Interoperability Layer** + Enable existing LLM agents to exchange structured marketing context using standardized inputs and outputs. + Focus on context engineering, schema alignment, and real-time messaging between agents such as, but not limited to, buyer, seller, and measurement agents. + +2. **Phase 2 – Context Learning Layer** + Train deep learning models on the contextual and behavioral data exchanged through the protocol. + These models learn to represent user journeys, ad impressions, conversions, and marketplace signals as dynamic embeddings. + +3. **Phase 3 – Embedding Intelligence Layer** + Agents evolve from exchanging textual context to exchanging embeddings that encode understanding of user intent, campaign state, and performance. + These embeddings act as transferable memory between agents that share a compatible vector space, enabling near real-time optimization without large prompt contexts. + +--- + +## Core Principles + +- **Interoperability:** Define clear input and output contracts for all agent types. +- **Context Engineering:** Maintain relevant and bounded context to keep agents aligned on goals. +- **Incremental Evolution:** Support LLM agents and prompt orchestration today while enabling learned models tomorrow. +- **Identity and Privacy:** Preserve user trust with privacy-safe handling of identity and behavioral signals. +- **Composability:** Allow independent agents to cooperate through standardized schemas and embeddings. + +--- + +## Agent Ecosystem + +| Agent Type | Role | Early-Stage Interface | Future Interface | +|-------------|------|----------------------|------------------| +| Buyer Agent | Plans and executes ad placements | Prompt plus JSON I/O | Embedding-based optimization | +| Seller Agent | Publishes and prices inventory | Context-aware API | Vector similarity negotiation | +| Measurement Agent | Tracks outcomes and updates models | Event feed | Feedback embedding update | + +--- + +## Technical Vision + +UCP defines: + +1. **Protocol Interfaces** - APIs and schemas for exchanging context, signals, and results. +2. **Context Management** - Strategies for maintaining scoped, composable context windows in LLM-driven agents. +3. **Embedding Interoperability** - Standards for shared embedding structures, dimensional alignment, and vector-space identity. +4. **Agent Coordination Flows** - Request and response patterns for cross-agent actions. +5. **Privacy and Consent Controls** - Mechanisms for secure signal sharing. +6. **Agentic Attestation** - Governance of human or agentic inputs into systems interacting with consumer data. + +By evolving from structured text exchanges to compact vector exchanges, UCP will enable major gains in speed, scale, and cost efficiency for campaign optimization. + +--- + +## Example Evolution Path + +1. **Today:** + - A buyer agent prompts a seller agent: + "Provide available CTV inventory for users interested in electric vehicles in San Francisco this week." + - The seller agent responds using the UCP schema, returning JSON data on available segments. + - A measurement agent records conversions and feeds updates. + +2. **Future:** + - The buyer agent receives a user embedding representing current context. + - It queries seller embeddings directly in vector space to find optimal matches. + - Feedback embeddings from the measurement agent continuously refine the shared context model. + +--- + +## Roadmap + +1. **Specification Draft** - Schema and interfaces for prompt-driven interoperability. +2. **Reference SDKs** - Python and JavaScript libraries for MCP-compatible agents. +3. **Context Engine Framework** - Tools for managing context window updates and relevance. +4. **Embedding Schema Standard** - Common representation for learned user and campaign embeddings. +5. **Industry Working Group** - Partnership with open-source and adtech leaders to align adoption. + +--- + +## Contributing + +This repository hosts the evolving UCP specification and reference implementations. +We welcome contributions from engineers, researchers, and organizations shaping the next generation of agentic advertising. + +To get involved: +- Fork the repo and explore the `/specs` and `/reference` directories. +- Propose changes via pull request. +- Join or start a working group under `/community`. + +--- + +## License + +- Specification and Documentation: Creative Commons Attribution 4.0 International (CC BY 4.0) +- Reference Implementations: Apache License 2.0 + +"User Context Protocol" is a trademarks of LiveRamp Holdings, Inc. +Use of these marks is subject to the [TRADEMARK.md](./TRADEMARK.md) policy. + +--- diff --git a/TRADEMARK.md b/TRADEMARK.md new file mode 100644 index 0000000..cb45853 --- /dev/null +++ b/TRADEMARK.md @@ -0,0 +1,45 @@ +# Trademark Policy for User Context Protocol™ (UCP) + +This document describes the trademark policy for the "User Context Protocol" (UCP) project. + +"User Context Protocol" is a trademark of LiveRamp Holdings, Inc. + +--- + +## Purpose + +LiveRamp supports the open development of the User Context Protocol and encourages its adoption across the advertising and marketing ecosystem. +To protect the integrity and trust of the UCP brand, we maintain control over its trademarks while allowing fair use in accurate references, compatibility statements, and community-driven implementations. + +This policy explains how the trademarks may be used in connection with the project, its specifications, and derived works. + +--- + +## 1. Permitted Uses + +You **may** use the "User Context Protocol" or "UCP" name in the following ways without prior written permission: + +- **Accurate Reference:** To refer to the protocol itself, its open-source repository, or official specification (e.g., "This SDK implements the User Context Protocol"). +- **Compatibility Statements:** To describe interoperability, provided the statement is accurate and not misleading (e.g., "Compatible with UCP v1.0"). +- **Educational or Informational Contexts:** In blogs, articles, research papers, and presentations referring to the protocol. + +In all cases, the name must be used only as a reference to the standard or project — not to suggest ownership, endorsement, or sponsorship by LiveRamp. + +--- + +## 2. Restricted Uses + +You **may not**: + +- Use "User Context Protocol," or confusingly similar names in the name of your company, product, or service (e.g., "UCP AI Suite" or "User Context Labs") without permission. +- Use the trademarks in a way that implies official status, endorsement, or partnership with LiveRamp. +- Alter, stylize, or combine the trademarks with your own branding in a way that could confuse users about the source of the project. +- Use the trademarks to market modified versions of the protocol or specification as if they were the official standard. + +If you create a derivative or modified protocol, you must rename it to avoid confusion (e.g., "Extended Context Protocol (ECP) based on UCP"). + +--- + +## 3. Proper Attribution + +When referring to the project, please use the correct name and attribution line: \ No newline at end of file diff --git a/community/README.md b/community/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e69de29 diff --git a/specs/roadmap.md b/specs/roadmap.md new file mode 100644 index 0000000..e69de29 diff --git a/specs/v1.0/README.md b/specs/v1.0/README.md new file mode 100644 index 0000000..e69de29 diff --git a/specs/v1.0/examples/buyer_agent_request.json b/specs/v1.0/examples/buyer_agent_request.json new file mode 100644 index 0000000..e69de29 diff --git a/specs/v1.0/examples/embedding_update.json b/specs/v1.0/examples/embedding_update.json new file mode 100644 index 0000000..e69de29 diff --git a/specs/v1.0/examples/seller_agent_response.json b/specs/v1.0/examples/seller_agent_response.json new file mode 100644 index 0000000..e69de29 diff --git a/specs/v1.0/schema/agent_interface.schema.json b/specs/v1.0/schema/agent_interface.schema.json new file mode 100644 index 0000000..e69de29 diff --git a/specs/v1.0/schema/embedding_format.schema.json b/specs/v1.0/schema/embedding_format.schema.json new file mode 100644 index 0000000..e69de29 From 71c63d491ac7375ca82677336467a4b10c5a5273 Mon Sep 17 00:00:00 2001 From: adam Date: Fri, 24 Oct 2025 09:56:15 -0500 Subject: [PATCH 2/4] adding embedding taxonomy --- .../v1.0/{README.md => embedding-exchange.md} | 0 specs/v1.0/embedding-taxonomy.md | 446 ++++++++++++++++++ 2 files changed, 446 insertions(+) rename specs/v1.0/{README.md => embedding-exchange.md} (100%) create mode 100644 specs/v1.0/embedding-taxonomy.md diff --git a/specs/v1.0/README.md b/specs/v1.0/embedding-exchange.md similarity index 100% rename from specs/v1.0/README.md rename to specs/v1.0/embedding-exchange.md diff --git a/specs/v1.0/embedding-taxonomy.md b/specs/v1.0/embedding-taxonomy.md new file mode 100644 index 0000000..70f38e2 --- /dev/null +++ b/specs/v1.0/embedding-taxonomy.md @@ -0,0 +1,446 @@ +# UCP Embedding Taxonomy + +**Version:** 0.1 (Draft) +**Status:** Proposal +**Last Updated:** 2025-01-24 + +--- + +## Overview + +This document defines a taxonomy for classifying embeddings exchanged via the User Context Protocol. Embeddings encode different types of signals—identity, contextual, and reinforcement—and understanding their semantic purpose is critical for proper interpretation, combination, and usage by agents. + +The taxonomy categorizes embeddings along three dimensions: +1. **Signal Type** - What kind of information the embedding encodes +2. **Temporal Scope** - Time horizon the embedding represents +3. **Composition** - Whether it encodes a single signal type or multiple types + +--- + +## 1. Signal Type Classification + +### 1.1 Identity Embeddings + +**Purpose:** Represent a user's persistent identity, enabling cross-session recognition and historical behavior understanding. + +**Subcategories:** + +#### 1.1.1 PII-Derived Identity Embeddings +- **Description:** Learned representations of offline identity derived from personally identifiable information (PII) +- **Source Data:** Email addresses, phone numbers, postal addresses, device IDs (hashed/encrypted) +- **Model Type:** Transformer models trained on tokenized, anonymized PII +- **Use Cases:** Cross-device identity resolution, household linkage, deterministic matching +- **Privacy:** Must preserve k-anonymity; embeddings should not be reversible to raw PII +- **Example:** A text-based PII identifier transformer that encodes hashed email → 512-dim vector + +#### 1.1.2 Behavioral Identity Embeddings +- **Description:** Representations of a user based on long-term behavioral patterns +- **Source Data:** Purchase history, browsing patterns, app usage, content consumption over weeks/months +- **Model Type:** Recurrent networks (LSTM/GRU), transformers with temporal attention +- **Use Cases:** Lookalike modeling, lifetime value prediction, segment discovery +- **Temporal Scope:** Weeks to months of historical data +- **Example:** User journey embedding capturing 90-day behavioral fingerprint + +#### 1.1.3 Demographic Identity Embeddings +- **Description:** Representations of inferred or declared demographic attributes +- **Source Data:** Age, gender, income bracket, education, location, interests +- **Model Type:** Categorical embeddings, entity embeddings from tabular data +- **Use Cases:** Demographic targeting, audience extension, census-level aggregation +- **Example:** Combined demographic vector encoding {age_bucket, region, interest_category} + +#### 1.1.4 Graph-Based Identity Embeddings +- **Description:** Representations derived from identity graphs (device graphs, household graphs, social graphs) +- **Source Data:** Device co-occurrence, shared network connections, household relationships +- **Model Type:** Graph neural networks (GNN), node2vec, DeepWalk +- **Use Cases:** Probabilistic identity linking, fraud detection, household targeting +- **Example:** Node embedding in a device graph representing probabilistic linkage to 5 devices + +### 1.2 Contextual Embeddings + +**Purpose:** Represent the current situational context in which a user is operating, enabling real-time intent understanding. + +**Subcategories:** + +#### 1.2.1 Content Contextual Embeddings +- **Description:** Semantic representations of page/app content where ads may appear +- **Source Data:** Page text, article body, video metadata, app category +- **Model Type:** Sentence transformers (SBERT), BERT variants, multimodal models +- **Use Cases:** Contextual targeting, brand safety, semantic matching +- **Temporal Scope:** Instantaneous (current page view) +- **Example:** Page embedding from article about "electric vehicle financing" → 768-dim BERT embedding + +#### 1.2.2 Temporal Contextual Embeddings +- **Description:** Representations of time-based context (time of day, day of week, seasonality) +- **Source Data:** Timestamp, timezone, calendar features (weekday/weekend, holiday) +- **Model Type:** Sinusoidal encodings, learned temporal embeddings +- **Use Cases:** Dayparting optimization, seasonal campaign tuning +- **Example:** Time embedding encoding {Monday, 9am PST, non-holiday} → 64-dim vector + +#### 1.2.3 Geospatial Contextual Embeddings +- **Description:** Representations of location-based context +- **Source Data:** Country, region, DMA, postal code, lat/long (coarse), POI proximity +- **Model Type:** Geohashing embeddings, hierarchical location embeddings +- **Use Cases:** Local targeting, geo-fencing, regional campaign optimization +- **Privacy:** Must use coarse granularity (ZIP/postal code level, not GPS coordinates) +- **Example:** Location embedding for "San Francisco Bay Area, CA" → 128-dim vector + +#### 1.2.4 Device/Environment Contextual Embeddings +- **Description:** Representations of device and browsing environment +- **Source Data:** Device type, OS, browser, screen size, connection type, app vs web +- **Model Type:** Categorical embeddings, device fingerprint encoders +- **Use Cases:** Creative optimization (mobile vs desktop), format selection +- **Example:** Device embedding for {iOS, Safari, mobile, 5G} → 32-dim vector + +#### 1.2.5 Session Contextual Embeddings +- **Description:** Representations of current browsing session behavior +- **Source Data:** Pages visited in session, dwell time, scroll depth, engagement signals +- **Model Type:** Session RNNs, attention-based sequence models +- **Use Cases:** In-session intent prediction, urgency detection +- **Temporal Scope:** Minutes to hours (current session) +- **Example:** Session embedding capturing "researching → comparing → near-purchase" journey state + +### 1.3 Reinforcement Embeddings + +**Purpose:** Represent feedback signals from user interactions with advertising, enabling model updates and campaign optimization. + +**Subcategories:** + +#### 1.3.1 Engagement Reinforcement Embeddings +- **Description:** Representations of ad engagement behaviors short of conversion +- **Source Data:** Impressions, viewability, clicks, video completions, hover time, scroll-through +- **Model Type:** Event sequence encoders, survival models, interaction transformers +- **Use Cases:** Click prediction, viewability optimization, engagement modeling +- **Temporal Scope:** Seconds to hours post-exposure +- **Example:** Engagement embedding encoding {5 impressions, 2 clicks, 30s avg dwell} → 256-dim vector + +#### 1.3.2 Conversion Reinforcement Embeddings +- **Description:** Representations of conversion events and their context +- **Source Data:** Purchase, sign-up, download, form submission, attributed conversions +- **Model Type:** Conversion path encoders, attribution models +- **Use Cases:** Conversion rate prediction, incrementality measurement, ROAS optimization +- **Temporal Scope:** Hours to days post-exposure +- **Example:** Conversion embedding capturing {purchase, $150 AOV, 48hr lag, 3-touch path} → 512-dim vector + +#### 1.3.3 Attribution Reinforcement Embeddings +- **Description:** Representations of multi-touch attribution weights across touchpoints +- **Source Data:** Full conversion path, touchpoint timestamps, channel mix, credited value +- **Model Type:** Markov chain models, Shapley value calculators, path transformers +- **Use Cases:** Budget allocation, channel optimization, incrementality testing +- **Example:** Attribution embedding encoding contribution weights across {display, social, search} path + +#### 1.3.4 Feedback Reinforcement Embeddings +- **Description:** Representations of negative signals or policy violations +- **Source Data:** Ad fatigue indicators, frequency cap violations, user complaints, brand safety violations +- **Model Type:** Anomaly detection models, policy classifiers +- **Use Cases:** Frequency optimization, ad quality improvement, brand safety enforcement +- **Example:** Feedback embedding flagging {over-frequency, user opted out, creative underperforming} + +### 1.4 Creative Embeddings + +**Purpose:** Represent advertising creative assets, enabling semantic matching and creative optimization. + +**Subcategories:** + +#### 1.4.1 Visual Creative Embeddings +- **Description:** Representations of image/video creative elements +- **Source Data:** Image pixels, video frames, visual elements (objects, colors, composition) +- **Model Type:** CNN encoders (ResNet, EfficientNet), vision transformers (ViT), CLIP +- **Use Cases:** Visual similarity matching, A/B testing, dynamic creative optimization +- **Example:** Image embedding from display ad creative → 2048-dim ResNet embedding + +#### 1.4.2 Textual Creative Embeddings +- **Description:** Representations of ad copy, headlines, CTAs +- **Source Data:** Ad text, headlines, descriptions, call-to-action phrases +- **Model Type:** Sentence transformers, advertising-specific language models +- **Use Cases:** Copy testing, message-market fit, semantic creative matching +- **Example:** Text embedding from headline "Save 30% on Electric Vehicles" → 384-dim SBERT vector + +#### 1.4.3 Multimodal Creative Embeddings +- **Description:** Joint representations of visual + textual + audio creative elements +- **Source Data:** Combined image, text, audio from video ads or rich media +- **Model Type:** CLIP-style models, multimodal transformers, unified embedding spaces +- **Use Cases:** Holistic creative understanding, cross-modal retrieval, dynamic assembly +- **Example:** Multimodal embedding from 30s video ad with voiceover → 1024-dim joint vector + +#### 1.4.4 Creative Performance Embeddings +- **Description:** Representations combining creative features with performance history +- **Source Data:** Creative attributes + historical CTR/CVR/engagement metrics +- **Model Type:** Performance-aware encoders, metric-conditioned embeddings +- **Use Cases:** Creative ranking, performance prediction, winner prediction +- **Example:** Creative+performance embedding: {image_vector, historical_CTR=2.3%} → 768-dim vector + +### 1.5 Inventory Embeddings + +**Purpose:** Represent available advertising inventory, enabling supply-demand matching. + +**Subcategories:** + +#### 1.5.1 Publisher Inventory Embeddings +- **Description:** Representations of publisher properties and their characteristics +- **Source Data:** Domain, content category, audience reach, brand safety score, viewability rates +- **Model Type:** Publisher encoders, domain embedding models +- **Use Cases:** Publisher selection, PMPs, inventory quality scoring +- **Example:** Publisher embedding for "premium news site, politics category" → 256-dim vector + +#### 1.5.2 Placement Inventory Embeddings +- **Description:** Representations of specific ad placements/units +- **Source Data:** Format (banner/video/native), size, position (above/below fold), context +- **Model Type:** Placement feature encoders +- **Use Cases:** Format selection, placement optimization, yield management +- **Example:** Placement embedding for "300×250 banner, above-fold, homepage" → 128-dim vector + +#### 1.5.3 Audience Inventory Embeddings +- **Description:** Representations of targetable audience segments available in inventory +- **Source Data:** Segment definitions, reach, overlap, refresh rates, data source +- **Model Type:** Segment taxonomy embeddings, audience characteristic encoders +- **Use Cases:** Audience discovery, segment recommendation, overlap analysis +- **Example:** Segment embedding for "in-market auto shoppers, 2M reach" → 512-dim vector + +### 1.6 Query/Intent Embeddings + +**Purpose:** Represent user intent signals or agent queries for matching against inventory or audiences. + +**Subcategories:** + +#### 1.6.1 Search Query Embeddings +- **Description:** Representations of search queries indicating commercial intent +- **Source Data:** Search terms, query refinements, search session context +- **Model Type:** Query encoders, BERT-based search models +- **Use Cases:** Search retargeting, intent capture, keyword expansion +- **Example:** Query embedding for "best electric SUV 2025" → 768-dim vector + +#### 1.6.2 Buyer Intent Embeddings +- **Description:** Representations of what a buyer agent is seeking +- **Source Data:** Campaign goals, target audience description, creative requirements, budget constraints +- **Model Type:** Intent specification encoders, goal-aware transformers +- **Use Cases:** Inventory matching, seller discovery, programmatic negotiation +- **Example:** Buyer intent: "reach tech-savvy millennials interested in sustainable products" → 512-dim vector + +#### 1.6.3 Seller Offer Embeddings +- **Description:** Representations of what a seller agent is offering +- **Source Data:** Available inventory characteristics, pricing, audience profiles, context +- **Model Type:** Offer specification encoders +- **Use Cases:** Buyer-seller matching, marketplace efficiency, price discovery +- **Example:** Seller offer: "CTV inventory, sports content, 18-34 males, $15 CPM" → 512-dim vector + +--- + +## 2. Temporal Scope Classification + +Embeddings can be classified by the time horizon they represent: + +### 2.1 Persistent Embeddings +- **Time Horizon:** Weeks to months +- **Update Frequency:** Weekly to monthly +- **Examples:** PII-derived identity, behavioral identity, LTV predictions +- **Characteristics:** Stable, long-term representations + +### 2.2 Session Embeddings +- **Time Horizon:** Minutes to hours +- **Update Frequency:** Per session or hourly +- **Examples:** Session context, current intent, in-session behavior +- **Characteristics:** Medium-term, updated within browsing sessions + +### 2.3 Real-Time Embeddings +- **Time Horizon:** Seconds to minutes +- **Update Frequency:** Per event or continuously +- **Examples:** Current page context, immediate device context, ad request context +- **Characteristics:** Instantaneous, reflects current moment + +### 2.4 Retrospective Embeddings +- **Time Horizon:** Historical (post-event analysis) +- **Update Frequency:** Batch updates after campaigns complete +- **Examples:** Attribution embeddings, incrementality measurements, campaign performance +- **Characteristics:** Backward-looking, enable learning for future campaigns + +--- + +## 3. Composition Classification + +Embeddings can combine multiple signal types: + +### 3.1 Atomic Embeddings +- **Definition:** Encode a single signal type from a single source +- **Examples:** + - Pure content embedding (just the page text) + - Pure PII embedding (just the hashed email) + - Pure device embedding (just device characteristics) +- **Use Cases:** Building blocks for more complex representations, interpretability, debugging + +### 3.2 Composite Embeddings +- **Definition:** Combine multiple related signals of the same type +- **Examples:** + - User identity = PII embedding + behavioral embedding + demographic embedding + - Full context = content + temporal + device + geo embeddings +- **Method:** Concatenation, weighted averaging, learned fusion +- **Use Cases:** Richer representations, holistic understanding within a signal type + +### 3.3 Graph Embeddings +- **Definition:** Encode relational structures between entities +- **Examples:** + - Device graph embeddings (device-device relationships) + - User journey graph (page-to-page navigation) + - Conversion path graph (touchpoint sequences) + - Creative similarity graph (creative-creative relationships) +- **Model Type:** Graph Neural Networks (GNN), node2vec, GraphSAGE +- **Use Cases:** Relationship discovery, transitive inference, network effects + +### 3.4 Cross-Signal Fusion Embeddings +- **Definition:** Combine multiple signal types (identity + context + reinforcement) +- **Examples:** + - User-in-context: identity embedding + current contextual embedding + - Predictive fusion: identity + context → predicted engagement + - Feedback-informed identity: baseline identity + historical reinforcement signals +- **Method:** Multimodal fusion, cross-attention, gating mechanisms +- **Use Cases:** Comprehensive user understanding, real-time scoring, personalized predictions + +### 3.5 Hierarchical Embeddings +- **Definition:** Multi-level representations with coarse-to-fine granularity +- **Examples:** + - Geographic hierarchy: country → state → DMA → postal code + - Taxonomic hierarchy: IAB category L1 → L2 → L3 + - Temporal hierarchy: year → month → week → day → hour +- **Model Type:** Hierarchical encoders, tree-structured embeddings +- **Use Cases:** Multi-resolution targeting, privacy-aware aggregation, drill-down analysis + +--- + +## 4. Embedding Metadata Schema + +To properly interpret and use embeddings, agents must exchange metadata. The following fields should accompany embeddings: + +### Required Metadata +```json +{ + "embedding_id": "unique-id", + "taxonomy_class": { + "signal_type": "identity|contextual|reinforcement|creative|inventory|query", + "subtype": "pii_derived|behavioral|content|engagement|...", + "temporal_scope": "persistent|session|realtime|retrospective", + "composition": "atomic|composite|graph|fusion|hierarchical" + }, + "dimension": 512, + "model": { + "id": "model-identifier", + "version": "1.0.0", + "architecture": "transformer|cnn|gnn|...", + "embedding_space_id": "ucp://spaces/identity/pii-v1" + }, + "vector": [0.01, 0.02, ...], + "normalization": "l2_unit|none", + "metric": "cosine|dot|l2" +} +``` + +### Optional Metadata +```json +{ + "source_signals": ["hashed_email", "behavioral_history"], + "temporal_window": { + "start": "2025-01-01T00:00:00Z", + "end": "2025-01-24T00:00:00Z", + "scope": "90_days" + }, + "privacy": { + "k_anonymity": 100, + "differential_privacy": false, + "reversibility_risk": "low" + }, + "quality_metrics": { + "confidence": 0.95, + "coverage": 0.87, + "staleness_hours": 2 + }, + "interpretability": { + "top_features": ["feature1", "feature2"], + "attribution_method": "integrated_gradients" + } +} +``` + +--- + +## 5. Usage Guidelines + +### 5.1 Embedding Selection + +**For Buyer Agents:** +- Use **identity embeddings** (PII + behavioral) to understand who to target +- Use **contextual embeddings** (content + temporal + geo) to find when/where to show ads +- Use **creative embeddings** to select appropriate messaging +- Use **query/intent embeddings** to express what you're looking for + +**For Seller Agents:** +- Use **inventory embeddings** to represent what you're offering +- Use **contextual embeddings** to describe placement environment +- Use **audience embeddings** to communicate available segments + +**For Measurement Agents:** +- Use **reinforcement embeddings** (engagement + conversion) to provide feedback +- Use **attribution embeddings** to credit touchpoints +- Use **feedback embeddings** to flag quality issues + +### 5.2 Embedding Combination + +When combining embeddings from different classes: + +1. **Ensure compatible embedding spaces** - Check `embedding_space_id` and model compatibility +2. **Normalize before fusion** - Use consistent normalization (typically L2) +3. **Weight appropriately** - Identity may deserve higher weight than device context +4. **Consider temporal freshness** - Don't mix stale persistent embeddings with real-time context +5. **Preserve privacy** - Fusion should not reduce k-anonymity below thresholds + +### 5.3 Interoperability + +For cross-agent embedding exchange: + +- **Shared embedding spaces** - Agents using the same `embedding_space_id` can directly compare embeddings +- **Transfer learning** - Embeddings from compatible spaces can be projected into common space +- **Metadata transparency** - Always include taxonomy classification in metadata +- **Version compatibility** - Specify model version; newer versions should maintain backward compatibility when possible + +--- + +## 6. Future Extensions + +This taxonomy is a living document. Anticipated future additions: + +### 6.1 Additional Signal Types +- **Attention embeddings** - Representations of visual attention patterns (eye-tracking derived) +- **Emotional embeddings** - Affective responses to creative (sentiment, emotional arousal) +- **Trust embeddings** - Brand safety, verification, fraud risk signals +- **Privacy embeddings** - Consent state, privacy preferences, regulatory compliance signals + +### 6.2 Advanced Compositions +- **Causal embeddings** - Encode causal relationships (not just correlations) +- **Counterfactual embeddings** - "What would have happened without the ad?" +- **Ensemble embeddings** - Weighted combinations of multiple models' embeddings +- **Meta-embeddings** - Embeddings of embeddings (second-order representations) + +### 6.3 Dynamic Embeddings +- **Streaming embeddings** - Continuously updated via online learning +- **Adaptive embeddings** - Self-adjusting based on prediction accuracy +- **Context-conditional embeddings** - Same user/content but different embeddings based on query context + +--- + +## 7. References + +- User Context Protocol Embedding Format Specification (`embedding_format.schema.json`) +- AI/ML Models in Agentic Digital Advertising Era (whitepaper) +- Ad Context Protocol (ADCP) - https://github.com/adcontextprotocol/adcp + +--- + +## 8. Change Log + +- **v0.1 (2025-01-24)**: Initial draft taxonomy proposal + - Defined 6 primary signal types with subcategories + - Established temporal scope and composition classifications + - Added metadata schema and usage guidelines + +--- + +**Maintainers:** LiveRamp UCP Working Group +**Feedback:** Submit issues or PRs to the UCP repository +**License:** Creative Commons Attribution 4.0 International (CC BY 4.0) From 4e9b2fbebd22ee3b9a469690154d49add3a8ca9d Mon Sep 17 00:00:00 2001 From: adam Date: Fri, 24 Oct 2025 09:57:44 -0500 Subject: [PATCH 3/4] remove datestamp --- specs/v1.0/embedding-taxonomy.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/v1.0/embedding-taxonomy.md b/specs/v1.0/embedding-taxonomy.md index 70f38e2..2acebb2 100644 --- a/specs/v1.0/embedding-taxonomy.md +++ b/specs/v1.0/embedding-taxonomy.md @@ -2,7 +2,6 @@ **Version:** 0.1 (Draft) **Status:** Proposal -**Last Updated:** 2025-01-24 --- From acdb937979908fdfa5adf3f4dc2698d32fac02eb Mon Sep 17 00:00:00 2001 From: adam Date: Fri, 24 Oct 2025 09:58:56 -0500 Subject: [PATCH 4/4] fix date --- specs/v1.0/embedding-taxonomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/v1.0/embedding-taxonomy.md b/specs/v1.0/embedding-taxonomy.md index 2acebb2..6c37cd4 100644 --- a/specs/v1.0/embedding-taxonomy.md +++ b/specs/v1.0/embedding-taxonomy.md @@ -433,7 +433,7 @@ This taxonomy is a living document. Anticipated future additions: ## 8. Change Log -- **v0.1 (2025-01-24)**: Initial draft taxonomy proposal +- **v0.1 (2025-10-24)**: Initial draft taxonomy proposal - Defined 6 primary signal types with subcategories - Established temporal scope and composition classifications - Added metadata schema and usage guidelines