From 83404382420b14f16a201e9e44c595ac9b56d68b Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Sat, 21 Mar 2026 17:24:30 -0700 Subject: [PATCH 1/7] adds agentic audiences --- extensions/community_extensions/README.md | 8 +- .../community_extensions/agentic-audiences.md | 182 ++++++++++++++++++ 2 files changed, 189 insertions(+), 1 deletion(-) create mode 100644 extensions/community_extensions/agentic-audiences.md diff --git a/extensions/community_extensions/README.md b/extensions/community_extensions/README.md index faed4024..528433e1 100644 --- a/extensions/community_extensions/README.md +++ b/extensions/community_extensions/README.md @@ -57,4 +57,10 @@ See [extended-content-ids.md](extended-content-ids.md) for deatils. #### Notes -See [seat-non-bid.md](seat-non-bid.md) for deatils. \ No newline at end of file +See [seat-non-bid.md](seat-non-bid.md) for deatils. + +### Agentic Audiences + +#### Notes + +See [agentic-audiences.md](agentic-audiences.md) for details. Agentic Audiences (formerly UCP) defines how to convey vector embeddings—identity, contextual, and reinforcement signals—in `BidRequest.user.data` using the Data/Segment structure. \ No newline at end of file diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md new file mode 100644 index 00000000..6ed030e8 --- /dev/null +++ b/extensions/community_extensions/agentic-audiences.md @@ -0,0 +1,182 @@ +# Agentic Audiences in OpenRTB + +**Sponsors**: LiveRamp, IAB Tech Lab + +## Overview + +Agentic Audiences (formerly the User Context Protocol/UCP) is an open standard that defines how intelligent agents in advertising exchange signals—identity, contextual, and reinforcement information—that represent a consumer's real-time intent and response to advertising. Agentic Audiences has been added to IAB Tech Lab's open-source agentic initiative and is maintained in the [IABTechLab/agentic-audiences](https://github.com/IABTechLab/agentic-audiences) repository. + +Rather than exchanging raw data points or text descriptions, Agentic Audiences leverages **embeddings**—compact, learned vector representations that efficiently encode complex signals in a privacy-preserving, interoperable format. This enables the sub-100ms response times required for real-time bidding. + +## Request Change + +This community extension defines how Agentic Audiences embeddings are conveyed in OpenRTB bid requests. The extension uses the existing `Data` and `Segment` objects in `BidRequest.user.data`. Each data provider supplies one or more segment entries, where each entry is a vector embedding with metadata describing its type and model. + +## Specification + +### Object: `BidRequest.user.data` + +Per the OpenRTB 2.x API, the `Data` object array in `user.data` allows additional data about the user to be specified. For Agentic Audiences, each provider contributes one `Data` object with: + +- **name**: Provider identifier in snake_case (e.g., `live_ramp`, `optable`). Used to identify the source of the embedding data. +- **segment**: Array of Agentic Audiences segment entries (see below). + +### Object: `Data.segment` (Agentic Audiences Segment Extension) + +When conveying Agentic Audiences embeddings, each element in the `segment` array is an object with the following attributes: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeTypeDescription
verstringSpecification version for embedding schema compatibility (e.g., "1.0").
vectornumber arrayVector embedding as a float array. Typically 256–1024 dimensions.
modelstringModel identifier that produced the embedding (e.g., "sbert-mini-ctx-001", "optable-embed-v1").
dimensionnumberVector dimension (length of the vector array).
typenumber arrayEmbedding type(s): 1 = identity, 2 = contextual, 3 = reinforcement. An entry may encode multiple signal types.
+ +### List: Embedding Type Values + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
1Identity – Who the user is (hashed identifiers, segments, behavioral history)
2Contextual – What the user is doing right now (page content, time of day, device, engagement)
3Reinforcement – How the user responds to advertising (impressions, clicks, conversions, engagement)
+ +### Known Providers + +When integrating with client-side or server-side sources, the following provider names (snake_case) are commonly used: + +| Provider | Data object name | Notes | +| -------- | ---------------------------- | ----- | +| LiveRamp | live_ramp | Default storage key: _lr_agentic_audience_ | +| Optable | optable | Default storage key: _optable_agentic_audience_ | + +Additional providers may use their own identifier in snake_case. Implementations should pass the `name` value unchanged so downstream systems can identify the embedding source. + +## Example Bid Request + +### Single provider (LiveRamp only) + +```json +{ + "id": "req-12345", + "imp": [{ "id": "1", "banner": { "w": 300, "h": 250 } }], + "user": { + "data": [ + { + "name": "live_ramp", + "segment": [ + { + "ver": "1.0", + "vector": [0.1, -0.2, 0.3], + "model": "sbert-mini-ctx-001", + "dimension": 3, + "type": [1, 2] + } + ] + } + ] + } +} +``` + +### Multiple providers (LiveRamp and Optable) + +```json +{ + "id": "req-12345", + "imp": [{ "id": "1", "banner": { "w": 300, "h": 250 } }], + "user": { + "data": [ + { + "name": "live_ramp", + "segment": [ + { + "ver": "1.0", + "vector": [0.1, -0.2, 0.3], + "model": "sbert-mini-ctx-001", + "dimension": 3, + "type": [1] + } + ] + }, + { + "name": "optable", + "segment": [ + { + "ver": "1.0", + "vector": [0.5, 0.6, -0.1], + "model": "optable-embed-v1", + "dimension": 3, + "type": [2] + } + ] + } + ] + } +} +``` + +*Note: Embedding vectors in examples are truncated for illustration; actual vectors are typically 256–1024 dimensions.* + +## Storage (Client-Side) + +When Agentic Audiences data is sourced from browser storage (localStorage or cookie), the stored value **must be base64-encoded** JSON. The decoded structure must include an `entries` array, where each entry has: `ver`, `vector`, `model`, `dimension`, and `type`. The wire format sent in the bid request uses the decoded `entries` as the `segment` array for that provider's `Data` object. + +## Implementation Notes + +- **Vector dimensions**: Embedding vectors are typically 256–1024 dimensions. Implementers should agree on dimension and vector-space alignment when interoperating across providers. +- **Privacy**: Embeddings encode semantic meaning without exposing raw user data. Implementers must ensure appropriate consent and data handling policies are followed. +- **Model interoperability**: The `model` field enables downstream systems to select compatible embeddings. Similarity computations are meaningful only within the same model/vector space. +- **Related implementations**: [Prebid.js Agentic Audience Adapter](https://github.com/prebid/Prebid.js/pull/14626) (RTD module agenticAudienceAdapter) reads from browser storage and injects Agentic Audiences data into the OpenRTB bid request per this specification. + +## References + +- [Agentic Audiences | IAB Tech Lab](https://iabtechlab.com/standards/agentic-audiences/) +- [Agentic Audiences GitHub Repository](https://github.com/IABTechLab/agentic-audiences) +- [Prebid.js Agentic Audience Adapter (PR #14626)](https://github.com/prebid/Prebid.js/pull/14626) From b6e942ba2c3f46a299bb65acf890a188cecaf504 Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Sat, 21 Mar 2026 17:29:15 -0700 Subject: [PATCH 2/7] updates agentic doc --- extensions/community_extensions/agentic-audiences.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md index 6ed030e8..cb3d26a7 100644 --- a/extensions/community_extensions/agentic-audiences.md +++ b/extensions/community_extensions/agentic-audiences.md @@ -1,6 +1,6 @@ # Agentic Audiences in OpenRTB -**Sponsors**: LiveRamp, IAB Tech Lab +**Sponsors**: LiveRamp ## Overview From fb97aac87e925735128469c26eb0e2a6fef5f2d3 Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Sat, 21 Mar 2026 18:38:20 -0700 Subject: [PATCH 3/7] cleans up agentic docs --- .../community_extensions/agentic-audiences.md | 157 +++++++----------- 1 file changed, 57 insertions(+), 100 deletions(-) diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md index cb3d26a7..7d580884 100644 --- a/extensions/community_extensions/agentic-audiences.md +++ b/extensions/community_extensions/agentic-audiences.md @@ -1,6 +1,6 @@ # Agentic Audiences in OpenRTB -**Sponsors**: LiveRamp +**Sponsors**: LiveRamp, Raptive ## Overview @@ -18,105 +18,58 @@ This community extension defines how Agentic Audiences embeddings are conveyed i Per the OpenRTB 2.x API, the `Data` object array in `user.data` allows additional data about the user to be specified. For Agentic Audiences, each provider contributes one `Data` object with: -- **name**: Provider identifier in snake_case (e.g., `live_ramp`, `optable`). Used to identify the source of the embedding data. +- **name**: Provider identifier (e.g., `liveramp`). Used to identify the source of the embedding data. - **segment**: Array of Agentic Audiences segment entries (see below). ### Object: `Data.segment` (Agentic Audiences Segment Extension) -When conveying Agentic Audiences embeddings, each element in the `segment` array is an object with the following attributes: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeTypeDescription
verstringSpecification version for embedding schema compatibility (e.g., "1.0").
vectornumber arrayVector embedding as a float array. Typically 256–1024 dimensions.
modelstringModel identifier that produced the embedding (e.g., "sbert-mini-ctx-001", "optable-embed-v1").
dimensionnumberVector dimension (length of the vector array).
typenumber arrayEmbedding type(s): 1 = identity, 2 = contextual, 3 = reinforcement. An entry may encode multiple signal types.
+When conveying Agentic Audiences embeddings, each element in the `segment` array is a standard OpenRTB Segment object. The segment uses `id` and `name` for identification, with Agentic Audiences–specific attributes in `ext`: + +| Attribute | Type | Description | +| :-- | :-- | :-- | +| `id` | string | ID of the data segment (standard Segment field). | +| `name` | string | Descriptive name for the segment (standard Segment field). | +| `ext` | object | Extension object containing Agentic Audiences attributes (see below). | + +### Object: `Segment.ext` (Agentic Audiences) + +| Attribute | Type | Description | +| :-- | :-- | :-- | +| `ver` | string | Specification version for embedding schema compatibility (e.g., "1.0.0"). | +| `vector` | number array | Vector embedding as a float array. Typically 256–1024 dimensions. | +| `model` | string | Model identifier that produced the embedding (e.g., "sbert-mini-ctx-001"). | +| `dimension` | number | Vector dimension (length of the `vector` array). | +| `type` | number array | Embedding type(s): 1 = identity, 2 = contextual, 3 = reinforcement. An entry may encode multiple signal types. | ### List: Embedding Type Values - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
1Identity – Who the user is (hashed identifiers, segments, behavioral history)
2Contextual – What the user is doing right now (page content, time of day, device, engagement)
3Reinforcement – How the user responds to advertising (impressions, clicks, conversions, engagement)
- -### Known Providers - -When integrating with client-side or server-side sources, the following provider names (snake_case) are commonly used: - -| Provider | Data object name | Notes | -| -------- | ---------------------------- | ----- | -| LiveRamp | live_ramp | Default storage key: _lr_agentic_audience_ | -| Optable | optable | Default storage key: _optable_agentic_audience_ | - -Additional providers may use their own identifier in snake_case. Implementations should pass the `name` value unchanged so downstream systems can identify the embedding source. +| Value | Description | +| :-- | :-- | +| 1 | Identity – Who the user is (hashed identifiers, segments, behavioral history) | +| 2 | Contextual – What the user is doing right now (page content, time of day, device, engagement) | +| 3 | Reinforcement – How the user responds to advertising (impressions, clicks, conversions, engagement) | ## Example Bid Request -### Single provider (LiveRamp only) +### Single provider ```json { - "id": "req-12345", - "imp": [{ "id": "1", "banner": { "w": 300, "h": 250 } }], "user": { "data": [ { - "name": "live_ramp", + "name": "data-provider", "segment": [ { - "ver": "1.0", - "vector": [0.1, -0.2, 0.3], - "model": "sbert-mini-ctx-001", - "dimension": 3, - "type": [1, 2] + "id": "some-id", + "name": "descriptive-name", + "ext": { + "ver": "1.0.0", + "vector": [0.1, -0.2, 0.3], + "model": "sbert-mini-ctx-001", + "dimension": 3, + "type": [1, 2] + } } ] } @@ -125,35 +78,41 @@ Additional providers may use their own identifier in snake_case. Implementations } ``` -### Multiple providers (LiveRamp and Optable) +### Multiple providers ```json { - "id": "req-12345", - "imp": [{ "id": "1", "banner": { "w": 300, "h": 250 } }], "user": { "data": [ { - "name": "live_ramp", + "name": "provider-a", "segment": [ { - "ver": "1.0", - "vector": [0.1, -0.2, 0.3], - "model": "sbert-mini-ctx-001", - "dimension": 3, - "type": [1] + "id": "seg-1", + "name": "identity-contextual", + "ext": { + "ver": "1.0.0", + "vector": [0.1, -0.2, 0.3], + "model": "sbert-mini-ctx-001", + "dimension": 3, + "type": [1, 2] + } } ] }, { - "name": "optable", + "name": "provider-b", "segment": [ { - "ver": "1.0", - "vector": [0.5, 0.6, -0.1], - "model": "optable-embed-v1", - "dimension": 3, - "type": [2] + "id": "seg-2", + "name": "contextual", + "ext": { + "ver": "1.0.0", + "vector": [0.5, 0.6, -0.1], + "model": "contextual-model-v1", + "dimension": 3, + "type": [2] + } } ] } @@ -166,17 +125,15 @@ Additional providers may use their own identifier in snake_case. Implementations ## Storage (Client-Side) -When Agentic Audiences data is sourced from browser storage (localStorage or cookie), the stored value **must be base64-encoded** JSON. The decoded structure must include an `entries` array, where each entry has: `ver`, `vector`, `model`, `dimension`, and `type`. The wire format sent in the bid request uses the decoded `entries` as the `segment` array for that provider's `Data` object. +When Agentic Audiences data is sourced from browser storage (localStorage or cookie), the stored value **must be base64-encoded** JSON. The decoded structure must include an `entries` array. Each entry is a segment object with `id`, `name`, and `ext` containing `ver`, `vector`, `model`, `dimension`, and `type`. The wire format sent in the bid request uses these entries as the `segment` array for that provider's `Data` object. ## Implementation Notes - **Vector dimensions**: Embedding vectors are typically 256–1024 dimensions. Implementers should agree on dimension and vector-space alignment when interoperating across providers. - **Privacy**: Embeddings encode semantic meaning without exposing raw user data. Implementers must ensure appropriate consent and data handling policies are followed. - **Model interoperability**: The `model` field enables downstream systems to select compatible embeddings. Similarity computations are meaningful only within the same model/vector space. -- **Related implementations**: [Prebid.js Agentic Audience Adapter](https://github.com/prebid/Prebid.js/pull/14626) (RTD module agenticAudienceAdapter) reads from browser storage and injects Agentic Audiences data into the OpenRTB bid request per this specification. ## References - [Agentic Audiences | IAB Tech Lab](https://iabtechlab.com/standards/agentic-audiences/) - [Agentic Audiences GitHub Repository](https://github.com/IABTechLab/agentic-audiences) -- [Prebid.js Agentic Audience Adapter (PR #14626)](https://github.com/prebid/Prebid.js/pull/14626) From d85e7015bbd5a8b1ed16c3fa4b8dae176bde57c0 Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Sat, 21 Mar 2026 18:42:34 -0700 Subject: [PATCH 4/7] cleans up agentic docs --- extensions/community_extensions/agentic-audiences.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md index 7d580884..e47fe9cf 100644 --- a/extensions/community_extensions/agentic-audiences.md +++ b/extensions/community_extensions/agentic-audiences.md @@ -8,9 +8,9 @@ Agentic Audiences (formerly the User Context Protocol/UCP) is an open standard t Rather than exchanging raw data points or text descriptions, Agentic Audiences leverages **embeddings**—compact, learned vector representations that efficiently encode complex signals in a privacy-preserving, interoperable format. This enables the sub-100ms response times required for real-time bidding. -## Request Change +## Extension Scope -This community extension defines how Agentic Audiences embeddings are conveyed in OpenRTB bid requests. The extension uses the existing `Data` and `Segment` objects in `BidRequest.user.data`. Each data provider supplies one or more segment entries, where each entry is a vector embedding with metadata describing its type and model. +Embeddings are conveyed in `BidRequest.user.data` using the existing `Data` and `Segment` objects. Each data provider contributes one `Data` object whose `segment` array contains one or more embedding entries. Each segment is a standard OpenRTB Segment with `id` and `name` for identification. The `Segment.ext` object carries the embedding and metadata that downstream systems need to interpret, filter, and use the vector—for example, for similarity matching or model-specific processing. ## Specification @@ -33,6 +33,8 @@ When conveying Agentic Audiences embeddings, each element in the `segment` array ### Object: `Segment.ext` (Agentic Audiences) +The `Segment.ext` object extends the standard Segment with Agentic Audiences attributes. It carries the embedding vector and metadata so that buyers can interpret the segment (e.g., by model or signal type), validate compatibility, and use the vector for scoring or similarity operations. + | Attribute | Type | Description | | :-- | :-- | :-- | | `ver` | string | Specification version for embedding schema compatibility (e.g., "1.0.0"). | @@ -123,10 +125,6 @@ When conveying Agentic Audiences embeddings, each element in the `segment` array *Note: Embedding vectors in examples are truncated for illustration; actual vectors are typically 256–1024 dimensions.* -## Storage (Client-Side) - -When Agentic Audiences data is sourced from browser storage (localStorage or cookie), the stored value **must be base64-encoded** JSON. The decoded structure must include an `entries` array. Each entry is a segment object with `id`, `name`, and `ext` containing `ver`, `vector`, `model`, `dimension`, and `type`. The wire format sent in the bid request uses these entries as the `segment` array for that provider's `Data` object. - ## Implementation Notes - **Vector dimensions**: Embedding vectors are typically 256–1024 dimensions. Implementers should agree on dimension and vector-space alignment when interoperating across providers. From ba5813fd0909afeb347afa7cda88a71257c4417b Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Thu, 26 Mar 2026 14:29:36 -0700 Subject: [PATCH 5/7] updates vector to use base64 --- .../community_extensions/agentic-audiences.md | 69 ++++++++++++++++--- 1 file changed, 59 insertions(+), 10 deletions(-) diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md index e47fe9cf..ba0426fb 100644 --- a/extensions/community_extensions/agentic-audiences.md +++ b/extensions/community_extensions/agentic-audiences.md @@ -38,11 +38,63 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att | Attribute | Type | Description | | :-- | :-- | :-- | | `ver` | string | Specification version for embedding schema compatibility (e.g., "1.0.0"). | -| `vector` | number array | Vector embedding as a float array. Typically 256–1024 dimensions. | +| `vector` | string | Base64-encoded embedding. The binary payload is Float32 values packed as [IEEE 754](https://standards.ieee.org/standard/754_2019.html) binary32 in **little-endian** byte order (4 bytes per value), concatenated, then standard Base64 (RFC 4648). The embedding length in values is **implicit**: after decoding, `byteLength` must be divisible by 4; number of floats = `byteLength / 4`. | | `model` | string | Model identifier that produced the embedding (e.g., "sbert-mini-ctx-001"). | -| `dimension` | number | Vector dimension (length of the `vector` array). | | `type` | number array | Embedding type(s): 1 = identity, 2 = contextual, 3 = reinforcement. An entry may encode multiple signal types. | +#### Vector encoding + +**Encode:** write each float as 4-byte little-endian Float32, concatenate, Base64-encode. + +**Decode:** Base64-decode to raw bytes; reject if `byteLength % 4 !== 0`. Read each 4-byte little-endian Float32 to obtain the float array. + +Example (JavaScript) — encode: + +```javascript +const floats = [ + 1.2345678, -2.5, 0.0, 3.1415927, 12345.678, + -0.00012345, 42.42, -999.999, 0.000001, 987654.25 +]; + +function floats32ToBase64(arr) { + const buffer = new ArrayBuffer(arr.length * 4); + const view = new DataView(buffer); + arr.forEach((x, i) => view.setFloat32(i * 4, x, true)); // little-endian + const bytes = new Uint8Array(buffer); + let binary = ""; + for (const b of bytes) binary += String.fromCharCode(b); + return btoa(binary); +} + +/* floats32ToBase64(floats) → + UQaePwAAIMAAAAAA2w9JQLbmQEZbcgG5FK4pQvD/ecS9N4Y1ZCBxSQ== */ +``` + +Example (JavaScript) — decode: + +```javascript +function base64ToFloats32(b64) { + const binary = atob(b64); + const bytes = new Uint8Array(binary.length); + for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i); + if (bytes.byteLength % 4 !== 0) { + throw new Error("Invalid vector payload: byte length must be a multiple of 4"); + } + const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength); + const out = []; + for (let i = 0; i < bytes.byteLength; i += 4) { + out.push(view.getFloat32(i, true)); // little-endian + } + return out; +} + +/* base64ToFloats32("UQaePwAAIMAAAAAA2w9JQLbmQEZbcgG5FK4pQvD/ecS9N4Y1ZCBxSQ==") + → [ + 1.2345677614212036, -2.5, 0, 3.1415927410125732, 12345.677734375, + -0.0001234499941347167, 42.41999816894531, -999.9990234375, 9.999999974752427e-7, 987654.25 + ] */ +``` + ### List: Embedding Type Values | Value | Description | @@ -67,9 +119,8 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att "name": "descriptive-name", "ext": { "ver": "1.0.0", - "vector": [0.1, -0.2, 0.3], + "vector": "UQaePwAAIMAAAAAA2w9JQLbmQEZbcgG5FK4pQvD/ecS9N4Y1ZCBxSQ==", "model": "sbert-mini-ctx-001", - "dimension": 3, "type": [1, 2] } } @@ -94,9 +145,8 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att "name": "identity-contextual", "ext": { "ver": "1.0.0", - "vector": [0.1, -0.2, 0.3], + "vector": "UQaePwAAIMAAAAAA2w9JQLbmQEZbcgG5FK4pQvD/ecS9N4Y1ZCBxSQ==", "model": "sbert-mini-ctx-001", - "dimension": 3, "type": [1, 2] } } @@ -110,9 +160,8 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att "name": "contextual", "ext": { "ver": "1.0.0", - "vector": [0.5, 0.6, -0.1], + "vector": "AAAAP5qZGT/NzMy9", "model": "contextual-model-v1", - "dimension": 3, "type": [2] } } @@ -123,11 +172,11 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att } ``` -*Note: Embedding vectors in examples are truncated for illustration; actual vectors are typically 256–1024 dimensions.* +*Note: Real embeddings are typically 256–1024 Float32 values; the longer `vector` example encodes 10 floats. Length in floats is always `(Base64-decoded byte length) / 4`.* ## Implementation Notes -- **Vector dimensions**: Embedding vectors are typically 256–1024 dimensions. Implementers should agree on dimension and vector-space alignment when interoperating across providers. +- **Vector length**: Embeddings typically contain 256–1024 Float32 values. Implementers should agree on expected length and vector-space alignment when interoperating across producers and consumers. Consumers derive length from the decoded payload and should reject payloads whose byte length is not a multiple of 4. - **Privacy**: Embeddings encode semantic meaning without exposing raw user data. Implementers must ensure appropriate consent and data handling policies are followed. - **Model interoperability**: The `model` field enables downstream systems to select compatible embeddings. Similarity computations are meaningful only within the same model/vector space. From 237f27d41714568aec765425b761bbdb188c762e Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Fri, 27 Mar 2026 09:16:57 -0700 Subject: [PATCH 6/7] readds dimension --- extensions/community_extensions/agentic-audiences.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md index ba0426fb..dd765863 100644 --- a/extensions/community_extensions/agentic-audiences.md +++ b/extensions/community_extensions/agentic-audiences.md @@ -38,7 +38,8 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att | Attribute | Type | Description | | :-- | :-- | :-- | | `ver` | string | Specification version for embedding schema compatibility (e.g., "1.0.0"). | -| `vector` | string | Base64-encoded embedding. The binary payload is Float32 values packed as [IEEE 754](https://standards.ieee.org/standard/754_2019.html) binary32 in **little-endian** byte order (4 bytes per value), concatenated, then standard Base64 (RFC 4648). The embedding length in values is **implicit**: after decoding, `byteLength` must be divisible by 4; number of floats = `byteLength / 4`. | +| `vector` | string | Base64-encoded embedding. The binary payload is Float32 values packed as [IEEE 754](https://standards.ieee.org/standard/754_2019.html) binary32 in **little-endian** byte order (4 bytes per value), concatenated, then standard Base64 (RFC 4648). | +| `dimension` | number | Number of Float32 values in the embedding. Must equal `(Base64-decoded byte length) / 4`. The decoded byte length must be divisible by 4. | | `model` | string | Model identifier that produced the embedding (e.g., "sbert-mini-ctx-001"). | | `type` | number array | Embedding type(s): 1 = identity, 2 = contextual, 3 = reinforcement. An entry may encode multiple signal types. | @@ -46,7 +47,7 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att **Encode:** write each float as 4-byte little-endian Float32, concatenate, Base64-encode. -**Decode:** Base64-decode to raw bytes; reject if `byteLength % 4 !== 0`. Read each 4-byte little-endian Float32 to obtain the float array. +**Decode:** Base64-decode to raw bytes; reject if `byteLength % 4 !== 0` or if `byteLength / 4` does not equal `dimension`. Read each 4-byte little-endian Float32 to obtain the float array. Example (JavaScript) — encode: @@ -120,6 +121,7 @@ function base64ToFloats32(b64) { "ext": { "ver": "1.0.0", "vector": "UQaePwAAIMAAAAAA2w9JQLbmQEZbcgG5FK4pQvD/ecS9N4Y1ZCBxSQ==", + "dimension": 10, "model": "sbert-mini-ctx-001", "type": [1, 2] } @@ -146,6 +148,7 @@ function base64ToFloats32(b64) { "ext": { "ver": "1.0.0", "vector": "UQaePwAAIMAAAAAA2w9JQLbmQEZbcgG5FK4pQvD/ecS9N4Y1ZCBxSQ==", + "dimension": 10, "model": "sbert-mini-ctx-001", "type": [1, 2] } @@ -161,6 +164,7 @@ function base64ToFloats32(b64) { "ext": { "ver": "1.0.0", "vector": "AAAAP5qZGT/NzMy9", + "dimension": 3, "model": "contextual-model-v1", "type": [2] } @@ -172,11 +176,11 @@ function base64ToFloats32(b64) { } ``` -*Note: Real embeddings are typically 256–1024 Float32 values; the longer `vector` example encodes 10 floats. Length in floats is always `(Base64-decoded byte length) / 4`.* +*Note: Real embeddings are typically 256–1024 Float32 values; the longer `vector` example encodes 10 floats. `dimension` must match the number of Float32 values encoded in `vector` (i.e. decoded byte length ÷ 4).* ## Implementation Notes -- **Vector length**: Embeddings typically contain 256–1024 Float32 values. Implementers should agree on expected length and vector-space alignment when interoperating across producers and consumers. Consumers derive length from the decoded payload and should reject payloads whose byte length is not a multiple of 4. +- **Vector length**: Embeddings typically contain 256–1024 Float32 values. Implementers should agree on expected length and vector-space alignment when interoperating across producers and consumers. Consumers should validate that `dimension` equals `(Base64-decoded byte length) / 4` and reject invalid payloads. - **Privacy**: Embeddings encode semantic meaning without exposing raw user data. Implementers must ensure appropriate consent and data handling policies are followed. - **Model interoperability**: The `model` field enables downstream systems to select compatible embeddings. Similarity computations are meaningful only within the same model/vector space. From 01d6a816405b735e6199e5670e838efbfe49dcc7 Mon Sep 17 00:00:00 2001 From: Miguel Morales Date: Fri, 27 Mar 2026 09:21:10 -0700 Subject: [PATCH 7/7] adds not about dsp validation --- extensions/community_extensions/agentic-audiences.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/community_extensions/agentic-audiences.md b/extensions/community_extensions/agentic-audiences.md index dd765863..3519260e 100644 --- a/extensions/community_extensions/agentic-audiences.md +++ b/extensions/community_extensions/agentic-audiences.md @@ -39,7 +39,7 @@ The `Segment.ext` object extends the standard Segment with Agentic Audiences att | :-- | :-- | :-- | | `ver` | string | Specification version for embedding schema compatibility (e.g., "1.0.0"). | | `vector` | string | Base64-encoded embedding. The binary payload is Float32 values packed as [IEEE 754](https://standards.ieee.org/standard/754_2019.html) binary32 in **little-endian** byte order (4 bytes per value), concatenated, then standard Base64 (RFC 4648). | -| `dimension` | number | Number of Float32 values in the embedding. Must equal `(Base64-decoded byte length) / 4`. The decoded byte length must be divisible by 4. | +| `dimension` | number | Number of Float32 values in the embedding. Must equal `(Base64-decoded byte length) / 4`. The decoded byte length must be divisible by 4. This field allows a DSP (or other consumer) to perform **rapid validation**—for example, by comparing `dimension` to an expected length for a given `model` before or without fully decoding the vector. | | `model` | string | Model identifier that produced the embedding (e.g., "sbert-mini-ctx-001"). | | `type` | number array | Embedding type(s): 1 = identity, 2 = contextual, 3 = reinforcement. An entry may encode multiple signal types. |