@adcp/sdk 6.8.0 → 6.10.0

package/compliance/cache/3.0.6/specialisms/signal-owned/index.yaml

@@ -0,0 +1,316 @@
+id: signal_owned
+version: "1.0.0"
+title: "Owned signal agent"
+protocol: signals
+category: signal_owned
+summary: "Signal agent serving first-party or proprietary audience data without external catalog verification."
+track: signals
+required_tools:
+  - get_signals
+
+narrative: |
+  You operate a first-party data platform — a retailer CDP, publisher contextual data
+  provider, or proprietary audience platform. Your signals are agent-native: they come
+  from your own data, not from third-party catalogs.
+
+  Buyers trust your agent directly. There's no external adagents.json to verify against —
+  provenance is the agent itself. This simplifies the flow: discovery and activation,
+  without the verification step that marketplace agents require.
+
+  Owned signal agents often have richer signal types. A retailer might expose purchase
+  frequency as a numeric signal (0-30 visits/month) or loyalty tier as categorical
+  (platinum/gold/silver/bronze). A publisher might expose content category, subscriber
+  tenure, or engagement scores.
+
+  This storyboard walks through discovery and both activation patterns.
+
+  Pricing is hard-required here for the same reason as signal marketplaces: signals
+  are rate-carded goods. Buyers cannot activate without a pricing_option_id to anchor
+  billing. Agents distributing first-party signals without commercial terms belong on
+  list_authorized_properties or a different specialism, not this one.
+
+agent:
+  interaction_model: owned_signals
+  capabilities: []
+  examples:
+    - "Retailer CDPs (e.g., loyalty and purchase data)"
+    - "Publisher contextual platforms (e.g., content category, subscriber data)"
+    - "First-party audience platforms (e.g., CRM-derived segments)"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The buyer has a campaign brief with targeting objectives. The test kit provides
+    sample owned signal definitions with various value types (binary, categorical,
+    numeric) and pricing models.
+  test_kit: "test-kits/nova-motors.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports signals before discovering or activating audience data.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring signals in supported_protocols, confirming the agent serves audience signals.
+        sample_request:
+          context:
+            correlation_id: "signal_owned--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_owned--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: discovery
+    title: "Signal discovery"
+    narrative: |
+      The buyer describes targeting objectives and your agent returns matching signals
+      from your proprietary data. Unlike marketplace agents, these signals have
+      signal_type "owned" — provenance is the agent itself.
+
+      Owned signals often include richer value types. A retailer can expose loyalty
+      tiers as categorical signals and purchase frequency as numeric signals, giving
+      buyers more precise targeting than binary include/exclude.
+
+    steps:
+      - id: search_owned_signals
+        title: "Discover owned signals"
+        narrative: |
+          The buyer searches for audience segments using a natural language description.
+          Your agent returns signals from your proprietary data — loyalty tiers, purchase
+          history, engagement scores, contextual categories.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        comply_scenario: signals_flow
+        stateful: false
+        expected: |
+          Return matching signals from your proprietary data. Each signal must include:
+          - signal_agent_segment_id for activation
+          - signal_id with source: "agent_native"
+          - name, description, and value_type
+          - coverage_percentage
+          - pricing_options
+          - signal_type: "owned"
+
+          For categorical signals, include the allowed_values.
+          For numeric signals, include the range (min/max).
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_spec: "High-value customers likely to purchase electronics, with loyalty program data"
+
+          context:
+            correlation_id: "signal_owned--search_owned_signals"
+        validations:
+          - check: response_schema
+            description: "Response matches get-signals-response.json schema"
+          - check: field_present
+            path: "signals[0].signal_agent_segment_id"
+            description: "Each signal has a signal_agent_segment_id"
+          - check: field_present
+            path: "signals[0].pricing_options"
+            description: "Each signal has pricing options"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_owned--search_owned_signals"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "signals[0].signal_id.source"
+            description: "Signal ID includes source discriminator"
+      - id: filter_by_criteria
+        title: "Filter signals by criteria"
+        narrative: |
+          The buyer narrows the search using filters — maximum CPM, specific signal
+          types, or coverage thresholds. This tests that your agent handles filter
+          parameters correctly and returns only matching signals.
+        task: get_signals
+        schema_ref: "signals/get-signals-request.json"
+        response_schema_ref: "signals/get-signals-response.json"
+        doc_ref: "/signals/tasks/get_signals"
+        comply_scenario: signals_flow
+        stateful: false
+        expected: |
+          Return only signals matching the filter criteria. If no signals match,
+          return an empty signals array — not an error.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_spec: "Purchase behavior signals"
+          filters:
+            max_cpm: 5.00
+
+          context:
+            correlation_id: "signal_owned--filter_by_criteria"
+        validations:
+          - check: response_schema
+            description: "Response matches schema"
+          - check: field_present
+            path: "signals"
+            description: "Response contains a signals array"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_owned--filter_by_criteria"
+            description: "Context correlation_id returned unchanged"
+  - id: platform_activation
+    title: "Activate on a DSP"
+    narrative: |
+      The buyer activates a signal directly on a DSP. Your agent pushes the segment
+      to the platform and returns a segment_id the buyer uses for campaign targeting.
+
+      Use platform destinations when the buyer manages DSP campaigns directly.
+
+    steps:
+      - id: activate_on_platform
+        title: "Activate owned signal on a DSP"
+        narrative: |
+          The buyer selects a signal and activates it on a DSP. For owned signals,
+          this means your platform pushes first-party segment data to the DSP. The
+          buyer gets back a segment_id for targeting.
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/tasks/activate_signal"
+        comply_scenario: signals_flow
+        stateful: true
+        expected: |
+          Return a deployment with:
+          - type: "platform"
+          - is_live status (may be async)
+          - activation_key with type: "segment_id" when live
+          - estimated_activation_duration_minutes if not immediately live
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_agent_segment_id: "prism_high_ltv"
+          pricing_option_id: "po_prism_flat_monthly"
+          destinations:
+            - type: "platform"
+              platform: "the-trade-desk"
+              account: "agency-123-ttd"
+          idempotency_key: "$generate:uuid_v4#signal_owned_activate_platform"
+          context:
+            correlation_id: "signal_owned--activate_on_platform"
+          ext:
+            test_platform:
+              test_run: true
+        validations:
+          - check: response_schema
+            description: "Response matches activate-signal-response.json schema"
+          - check: field_present
+            path: "deployments[0].type"
+            description: "Deployment includes type"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_owned--activate_on_platform"
+            description: "Context correlation_id returned unchanged"
+  - id: agent_activation
+    title: "Activate on a sales agent"
+    narrative: |
+      The buyer activates a signal on a sales agent. The SA records the activation
+      and handles downstream DSP coordination — the buyer doesn't need to know which
+      platform the SA uses.
+
+      This is the right pattern when buying media through a sales agent.
+
+    steps:
+      - id: activate_on_agent
+        title: "Activate owned signal on a sales agent"
+        narrative: |
+          The buyer activates a signal with the SA's URL as the destination. The
+          activation is typically synchronous. The SA records it internally and
+          applies the targeting when the buyer later calls create_media_buy.
+        task: activate_signal
+        schema_ref: "signals/activate-signal-request.json"
+        response_schema_ref: "signals/activate-signal-response.json"
+        doc_ref: "/signals/tasks/activate_signal"
+        comply_scenario: signals_flow
+        stateful: true
+        expected: |
+          Return a deployment with:
+          - type: "agent"
+          - agent_url matching the SA
+          - is_live: true (sync activation)
+          - activation_key with type: "key_value"
+          - deployed_at timestamp
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_agent_segment_id: "prism_cart_abandoner"
+          pricing_option_id: "po_prism_abandoner_cpm"
+          destinations:
+            - type: "agent"
+              agent_url: "https://wonderstruck.salesagents.example"
+          idempotency_key: "$generate:uuid_v4#signal_owned_activate_agent"
+          context:
+            correlation_id: "signal_owned--activate_on_agent"
+          ext:
+            test_platform:
+              test_run: true
+        validations:
+          - check: response_schema
+            description: "Response matches activate-signal-response.json schema"
+          - check: field_present
+            path: "deployments[0].activation_key"
+            description: "Deployment includes activation key"
+          - check: field_value
+            path: "deployments[0].type"
+            value: "agent"
+            description: "Deployment type is 'agent'"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signal_owned--activate_on_agent"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.0.6/test-kits/acme-outdoor.yaml

@@ -0,0 +1,210 @@
+# Acme Outdoor — Sample Advertiser Test Kit
+#
+# Entity definition: fictional-entities.yaml → advertisers[acme_outdoor]
+#
+# Provides the "ingredients" needed to test creative agent storyboards:
+# a brand identity, sample assets at common dimensions, and sample text.
+#
+# This brand is registered as a sandbox brand in AgenticAdvertising.org (AAO).
+# Agents resolve acmeoutdoor.example via the standard AAO brand resolution path.
+# AAO returns the brand.json below but excludes sandbox brands from production
+# brand discovery results.
+
+id: acme_outdoor
+name: "Acme Outdoor"
+description: "Fictional outdoor gear brand for storyboard testing"
+sandbox: true
+
+# Authentication fixture for the universal security_baseline storyboard
+# (universal/security.yaml). Declares:
+#   - api_key: the demo Bearer the runner sends on the positive api-key
+#     probe. The conformance handle is the `demo-<kit>-` prefix — agents
+#     SHOULD accept any Bearer matching that prefix (not this literal
+#     value) so the suffix can rotate across spec versions without
+#     breaking previously-conformant agents.
+#   - probe_task: the protected, auth-required read the runner calls under
+#     `auth: none` and with a random-invalid key. Default is list_creatives;
+#     declare explicitly so the api_key phase runs instead of being skipped
+#     via `skip_if: "!test_kit.auth.api_key"`.
+auth:
+  api_key: "demo-acme-outdoor-v1"
+  probe_task: list_creatives
+
+brand:
+  house:
+    domain: "acmeoutdoor.example"
+    name: "Acme Outdoor"
+  brand_id: "acme_outdoor"
+  names:
+    - en: "Acme Outdoor"
+  description: "Premium outdoor gear for every adventure. From trail to summit, we make gear that performs."
+  industry: "retail"
+  keller_type: "master"
+  logos:
+    - url: "https://test-assets.adcontextprotocol.org/acme-outdoor/logo-primary.png"
+      orientation: "horizontal"
+      background: "light-bg"
+      variant: "primary"
+      width: 400
+      height: 100
+    - url: "https://test-assets.adcontextprotocol.org/acme-outdoor/logo-icon.png"
+      orientation: "square"
+      background: "transparent-bg"
+      variant: "icon"
+      width: 200
+      height: 200
+  colors:
+    primary: "#1B5E20"
+    secondary: "#FF6F00"
+    accent: "#FDD835"
+    background: "#FAFAFA"
+    text: "#212121"
+  fonts:
+    heading:
+      family: "Montserrat"
+      weight: 700
+      url: "https://fonts.googleapis.com/css2?family=Montserrat:wght@700"
+    body:
+      family: "Open Sans"
+      weight: 400
+      url: "https://fonts.googleapis.com/css2?family=Open+Sans"
+  tone:
+    voice: "Confident and adventurous, but never pretentious. We talk to people who do things, not people who buy things."
+    attributes:
+      - "active"
+      - "direct"
+      - "warm"
+    dos:
+      - "Use action verbs"
+      - "Reference real outdoor activities"
+      - "Keep it short"
+    donts:
+      - "Use superlatives without evidence"
+      - "Talk down to the reader"
+      - "Use corporate jargon"
+
+# Sample assets at common ad dimensions.
+# These are placeholder URLs — in production, these would point to actual hosted test images.
+assets:
+  images:
+    - id: "hero_300x250"
+      url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-300x250.jpg"
+      width: 300
+      height: 250
+      mime_type: "image/jpeg"
+      description: "Medium rectangle hero — hiker on mountain trail"
+
+    - id: "hero_728x90"
+      url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-728x90.jpg"
+      width: 728
+      height: 90
+      mime_type: "image/jpeg"
+      description: "Leaderboard hero — panoramic mountain vista"
+
+    - id: "hero_320x50"
+      url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-320x50.jpg"
+      width: 320
+      height: 50
+      mime_type: "image/jpeg"
+      description: "Mobile banner hero — trail gear close-up"
+
+    - id: "hero_160x600"
+      url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-160x600.jpg"
+      width: 160
+      height: 600
+      mime_type: "image/jpeg"
+      description: "Wide skyscraper hero — vertical trail scene"
+
+    - id: "hero_master"
+      url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-master.jpg"
+      width: 1200
+      height: 628
+      mime_type: "image/jpeg"
+      description: "Master hero image — high-res source for any size"
+
+  text:
+    headlines:
+      - "Summer Sale — 40% Off All Gear"
+      - "Built for the Trail"
+      - "Adventure Starts Here"
+    descriptions:
+      - "Premium outdoor gear tested on the world's toughest trails. Shop the summer collection."
+      - "From daypacks to expedition tents, gear that performs when it matters."
+    cta:
+      - "Shop Now"
+      - "Explore the Collection"
+      - "Find Your Gear"
+
+  click_url: "https://acmeoutdoor.example/summer-sale"
+
+# Inventory list fixtures for property_list / collection_list targeting tests.
+#
+# These reference lists a fictional governance/inventory agent would publish.
+# They let storyboards exercise the full PropertyListReference / CollectionListReference
+# contract without needing a live list server: scenarios point at list_id values
+# and the seller's test engine returns canned contents.
+#
+# Both matching and non-matching sets are provided so a single test fixture
+# covers targeting (buy should include listed inventory) and no-match behaviour
+# (buy references a list that resolves to zero matches in this seller's catalog).
+inventory_targets:
+  # --- Matching sets (Acme Outdoor's intended audience) ---
+  matching_properties:
+    agent_url: "https://governance.pinnacle-agency.example"
+    list_id: "acme_outdoor_allowlist_v1"
+    description: "Outdoor lifestyle properties relevant to Acme Outdoor campaigns."
+    # Expected contents when the list is fetched via get_property_list.
+    expected_identifiers:
+      - type: domain
+        value: "outdoormagazine.example"
+      - type: domain
+        value: "hikingtrails.example"
+      - type: domain
+        value: "campinggear.example"
+      - type: domain
+        value: "mountaineering.example"
+
+  matching_collections:
+    agent_url: "https://governance.pinnacle-agency.example"
+    list_id: "acme_outdoor_collections_v1"
+    description: "Outdoor programming the buyer wants to run alongside."
+    # Expected collection entries when fetched via get_collection_list.
+    expected_collections:
+      - collection_rid: "rid:outdoor:trail_life"
+        name: "Trail Life"
+        kind: "series"
+        genre: "outdoor"
+        distribution_ids:
+          - type: imdb_id
+            value: "tt9100001"
+      - collection_rid: "rid:outdoor:summit_stories"
+        name: "Summit Stories"
+        kind: "series"
+        genre: "outdoor"
+        distribution_ids:
+          - type: imdb_id
+            value: "tt9100002"
+
+  # --- No-match sets (nothing in this seller's catalog matches) ---
+  no_match_properties:
+    agent_url: "https://governance.pinnacle-agency.example"
+    list_id: "acme_outdoor_no_match_v1"
+    description: "Properties outside this seller's inventory — should yield zero matches."
+    expected_identifiers:
+      - type: domain
+        value: "never-sold-here.example"
+      - type: domain
+        value: "also-not-indexed.example"
+
+  no_match_collections:
+    agent_url: "https://governance.pinnacle-agency.example"
+    list_id: "acme_outdoor_no_match_collections_v1"
+    description: "Collections not carried by this seller — should yield zero matches."
+    expected_collections:
+      - collection_rid: "rid:food:bistro_kitchen"
+        name: "Bistro Kitchen"
+        kind: "series"
+        genre: "food"
+        distribution_ids:
+          - type: imdb_id
+            value: "tt9200001"

package/compliance/cache/3.0.6/test-kits/bistro-oranje.yaml

@@ -0,0 +1,126 @@
+# Bistro Oranje — Hospitality Advertiser Test Kit
+#
+# Entity definition: fictional-entities.yaml → advertisers[bistro_oranje]
+#
+# Dutch restaurant chain used in rights licensing scenarios.
+#
+# This brand is registered as a sandbox brand in AgenticAdvertising.org (AAO).
+# Agents resolve bistro-oranje.example via the standard AAO brand resolution path.
+# AAO returns the brand.json below but excludes sandbox brands from production
+# brand discovery results.
+
+id: bistro_oranje
+name: "Bistro Oranje"
+description: "Dutch restaurant chain for rights licensing storyboard testing"
+sandbox: true
+
+# security_baseline auth fixture — see acme-outdoor.yaml for semantics.
+auth:
+  api_key: "demo-bistro-oranje-v1"
+  probe_task: list_creatives
+
+brand:
+  house:
+    domain: "bistro-oranje.example"
+    name: "Bistro Oranje"
+  brand_id: "bistro_oranje"
+  names:
+    - en: "Bistro Oranje"
+    - nl: "Bistro Oranje"
+  description: "Modern Dutch dining — seasonal menus inspired by the Netherlands, served with warmth."
+  industry: "hospitality"
+  keller_type: "master"
+  logos:
+    - url: "https://test-assets.adcontextprotocol.org/bistro-oranje/logo-primary.png"
+      orientation: "horizontal"
+      background: "light-bg"
+      variant: "primary"
+      width: 400
+      height: 100
+    - url: "https://test-assets.adcontextprotocol.org/bistro-oranje/logo-icon.png"
+      orientation: "square"
+      background: "transparent-bg"
+      variant: "icon"
+      width: 200
+      height: 200
+  colors:
+    primary: "#E65100"
+    secondary: "#1B5E20"
+    accent: "#FFC107"
+    background: "#FFF8E1"
+    text: "#212121"
+  fonts:
+    heading:
+      family: "Playfair Display"
+      weight: 700
+      url: "https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700"
+    body:
+      family: "Source Sans Pro"
+      weight: 400
+      url: "https://fonts.googleapis.com/css2?family=Source+Sans+Pro"
+  tone:
+    voice: "Warm and inviting, with understated confidence. We let the food speak — no excess, no pretension."
+    attributes:
+      - "welcoming"
+      - "seasonal"
+      - "unpretentious"
+    dos:
+      - "Mention seasonal ingredients by name"
+      - "Reference Dutch culinary traditions"
+      - "Keep descriptions sensory and specific"
+    donts:
+      - "Use fine-dining jargon"
+      - "Overuse superlatives"
+      - "Promise exclusivity — Bistro Oranje is for everyone"
+
+assets:
+  images:
+    - id: "hero_300x250"
+      url: "https://test-assets.adcontextprotocol.org/bistro-oranje/hero-300x250.jpg"
+      width: 300
+      height: 250
+      mime_type: "image/jpeg"
+      description: "Medium rectangle hero — seasonal dish on rustic table"
+
+    - id: "hero_728x90"
+      url: "https://test-assets.adcontextprotocol.org/bistro-oranje/hero-728x90.jpg"
+      width: 728
+      height: 90
+      mime_type: "image/jpeg"
+      description: "Leaderboard hero — bistro exterior with canal backdrop"
+
+    - id: "hero_320x50"
+      url: "https://test-assets.adcontextprotocol.org/bistro-oranje/hero-320x50.jpg"
+      width: 320
+      height: 50
+      mime_type: "image/jpeg"
+      description: "Mobile banner hero — close-up of signature stamppot"
+
+    - id: "hero_160x600"
+      url: "https://test-assets.adcontextprotocol.org/bistro-oranje/hero-160x600.jpg"
+      width: 160
+      height: 600
+      mime_type: "image/jpeg"
+      description: "Wide skyscraper hero — vertical dining room scene"
+
+    - id: "hero_master"
+      url: "https://test-assets.adcontextprotocol.org/bistro-oranje/hero-master.jpg"
+      width: 1200
+      height: 628
+      mime_type: "image/jpeg"
+      description: "Master hero image — high-res chef plating seasonal dish"
+
+  text:
+    headlines:
+      - "Taste the Season at Bistro Oranje"
+      - "Dutch Comfort, Modern Kitchen"
+      - "Reserve Your Table Tonight"
+    descriptions:
+      - "Seasonal menus inspired by Dutch tradition, made with ingredients sourced within 50km. Bistro Oranje — Amsterdam, Rotterdam, Utrecht."
+      - "From stamppot to stroopwafel, every dish tells a story. Book your table at Bistro Oranje."
+    cta:
+      - "Reserve a Table"
+      - "View the Menu"
+      - "Find a Location"
+
+  click_url: "https://bistro-oranje.example/reservations"