@adcp/sdk 6.8.0 → 6.10.0

package/compliance/cache/3.0.6/domains/signals/index.yaml

@@ -0,0 +1,266 @@
+id: signals_baseline
+version: "1.1.0"
+title: "Signals baseline"
+protocol: signals
+category: signals_baseline
+summary: "Baseline domain storyboard — every signals agent must discover signals and return an activation, regardless of whether they are owned or marketplace."
+track: signals
+required_tools:
+  - get_signals
+  - activate_signal
+
+narrative: |
+  Signals domain agents expose audience and contextual signals to buyers and
+  activate them on downstream destinations (DSPs, sales agents, clean rooms).
+  Every signals agent — whether a first-party owned platform or a third-party
+  marketplace — must support the same three-call flow at the protocol level:
+
+    1. Declare the signals protocol in get_adcp_capabilities.
+    2. Respond to get_signals with a schema-valid signals array.
+    3. Respond to activate_signal with a schema-valid deployments array.
+
+  This baseline tests those three calls and nothing beyond them. Specialism
+  storyboards (signal-owned, signal-marketplace) exercise the richer flows
+  specific to each model — pricing option selection, source/provenance
+  discriminators, agent-destination vs. platform-destination activation,
+  and deactivation for compliance.
+
+  Agents declaring supported_protocols: ["signals"] MUST pass this baseline
+  even before claiming a specialism. Declaring signals without exposing
+  get_signals or activate_signal fails the baseline with missing_tool.
+
+agent:
+  interaction_model: owned_signals
+  capabilities: []
+  examples:
+    - "Any signals agent (owned or marketplace)"
+    - "Retailer CDPs"
+    - "Publisher contextual platforms"
+    - "Data provider marketplaces"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The buyer has a campaign brief with broad targeting objectives. The test
+    kit provides a sample brand (Nova Motors) with a signal description that
+    any signals agent should be able to interpret.
+  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 serves signals
+      before issuing discovery or activation calls.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares `signals` in supported_protocols.
+          Without this claim the buyer will not send get_signals or
+          activate_signal.
+        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.
+
+        sample_request:
+          context:
+            correlation_id: "signals_baseline--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: "signals_baseline--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: discovery
+    title: "Signal discovery"
+    narrative: |
+      The buyer calls get_signals with a natural language signal_spec. Every
+      signals agent — owned or marketplace — must return a schema-valid
+      response. The buyer uses the returned signal_agent_segment_id values
+      to drive activation in the next phase.
+
+    steps:
+      - id: search_signals
+        title: "Discover signals matching a spec"
+        narrative: |
+          The buyer describes a target audience in natural language. The agent
+          returns a list of signals from its catalog that match. Each signal
+          must include the fields the buyer needs to proceed to activation.
+        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 a signals array with at least one entry. Each signal must
+          carry a signal_agent_segment_id that the buyer can pass to
+          activate_signal, along with pricing_options and a signal_id that
+          includes a source discriminator.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_spec: "Adults interested in electric vehicles"
+          context:
+            correlation_id: "signals_baseline--search_signals"
+        context_outputs:
+          - name: signal_agent_segment_id
+            path: "signals[0].signal_agent_segment_id"
+          - name: pricing_option_id
+            path: "signals[0].pricing_options[0].pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-signals-response.json schema"
+          - check: field_present
+            path: "signals[0].signal_agent_segment_id"
+            description: "First signal carries a signal_agent_segment_id"
+          - check: field_present
+            path: "signals[0].signal_id.source"
+            description: "Signal ID carries a source discriminator (agent_native or data_provider)"
+          - check: field_present
+            path: "signals[0].pricing_options"
+            description: "Signal carries pricing options the buyer can select"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signals_baseline--search_signals"
+            description: "Context correlation_id returned unchanged"
+
+  - id: activation
+    title: "Signal activation"
+    narrative: |
+      The buyer activates one of the signals returned from discovery against
+      a destination. The protocol baseline tests only that the agent accepts
+      the call and returns a schema-valid deployments array — specialisms
+      exercise owned vs. marketplace activation patterns in depth.
+
+    steps:
+      - id: activate_on_agent
+        title: "Activate on a sales agent destination"
+        narrative: |
+          Using the signal_agent_segment_id and pricing_option_id captured
+          from the previous step, the buyer activates the signal on a sales
+          agent destination. Every signals agent MUST accept `type: agent`
+          per the signals specification — the SA records the activation
+          internally and applies targeting in subsequent media-buy calls.
+        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 deployments array with at least one entry carrying a
+          `type` discriminator and, for live deployments, an
+          `activation_key`. Agents MAY return an async deployment with
+          `is_live: false` and `estimated_activation_duration_minutes`.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_agent_segment_id: "$context.signal_agent_segment_id"
+          pricing_option_id: "$context.pricing_option_id"
+          destinations:
+            - type: "agent"
+              agent_url: "https://wonderstruck.salesagents.example"
+          idempotency_key: "$generate:uuid_v4#signals_baseline_activate_agent"
+
+          context:
+            correlation_id: "signals_baseline--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].type"
+            description: "Deployment carries a type discriminator"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signals_baseline--activate_on_agent"
+            description: "Context correlation_id returned unchanged"
+
+      - id: activate_on_platform
+        title: "Activate on a platform destination"
+        narrative: |
+          The buyer re-activates the same signal against a platform
+          destination (a DSP). Signal agents MUST accept `type: platform`
+          per the signals specification — the agent pushes the segment to
+          the platform and returns a deployment record.
+        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 deployments array with at least one entry whose
+          `type: "platform"` and, for live deployments, an
+          `activation_key` with `type: "segment_id"`. Async deployments
+          MAY report `is_live: false` with
+          `estimated_activation_duration_minutes`.
+
+        sample_request:
+          account:
+            brand:
+              domain: "novamotors.example"
+            operator: "pinnacle-agency.example"
+          signal_agent_segment_id: "$context.signal_agent_segment_id"
+          pricing_option_id: "$context.pricing_option_id"
+          destinations:
+            - type: "platform"
+              platform: "the-trade-desk"
+              account: "agency-123-ttd"
+          idempotency_key: "$generate:uuid_v4#signals_baseline_activate_platform"
+
+          context:
+            correlation_id: "signals_baseline--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 carries a type discriminator"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "signals_baseline--activate_on_platform"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.0.6/domains/sponsored-intelligence/index.yaml

@@ -0,0 +1,256 @@
+id: si_baseline
+version: "1.0.0"
+title: "Sponsored intelligence baseline"
+protocol: sponsored-intelligence
+category: si_baseline
+summary: "Baseline domain storyboard — every SI agent must discover offerings, initiate a session, exchange messages, and terminate cleanly."
+track: si
+required_tools:
+  - si_initiate_session
+
+narrative: |
+  You run an AI platform that supports sponsored intelligence — conversational ad experiences
+  embedded in AI-powered search, chat, or assistant products. A buyer agent connects to
+  discover what SI offerings are available, initiate a session, send messages within the
+  conversation, and cleanly terminate when done.
+
+  Sponsored intelligence is fundamentally different from display or video advertising. The
+  ad experience is conversational — the user asks a question, the AI responds, and sponsored
+  content is woven into the response in a way that is transparent and relevant.
+
+  This storyboard covers the SI session lifecycle from the buyer's perspective: discovering
+  what the platform offers, starting a conversation, exchanging messages, and ending the
+  session.
+
+agent:
+  interaction_model: si_platform
+  capabilities:
+    - sponsored_intelligence
+  examples:
+    - "Perplexity"
+    - "ChatGPT Search"
+    - "Arc Browser"
+    - "AI assistants with ad support"
+
+caller:
+  role: buyer_agent
+  example: "Nova Motors (advertiser)"
+
+prerequisites:
+  description: |
+    The caller needs brand context and campaign parameters for SI. The test kit provides
+    a sample brand (Nova Motors) with signal definitions suitable for conversational
+    ad experiences.
+  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 sponsored intelligence before initiating sessions.
+
+    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 sponsored_intelligence in supported_protocols, confirming the agent supports conversational ad experiences.
+        sample_request:
+          context:
+            correlation_id: "si_session--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: "si_session--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: offering_discovery
+    title: "Discover SI offerings"
+    narrative: |
+      Before initiating any session, the buyer discovers what sponsored intelligence
+      offerings the platform has available. This determines what kinds of conversational
+      experiences can be sponsored and at what pricing.
+
+    steps:
+      - id: si_get_offering
+        title: "Get available SI offerings"
+        narrative: |
+          The buyer calls si_get_offering to learn what conversational ad experiences
+          the platform supports. The response describes available offerings with pricing,
+          targeting options, and format specifications.
+        task: si_get_offering
+        schema_ref: "sponsored-intelligence/si-get-offering-request.json"
+        response_schema_ref: "sponsored-intelligence/si-get-offering-response.json"
+        doc_ref: "/sponsored-intelligence/tasks/si_get_offering"
+        comply_scenario: si_availability
+        stateful: false
+        expected: |
+          Return available SI offerings:
+          - Offering descriptions with pricing
+          - Supported conversation types
+          - Targeting and context options
+          - Format specifications for sponsored content
+
+        sample_request:
+          offering_id: "novamotors_conversational_v1"
+          context:
+            correlation_id: "si_session--si_get_offering"
+
+        context_outputs:
+          - name: offering_id
+            path: 'offering_id'
+        validations:
+          - check: response_schema
+            description: "Response matches si-get-offering-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "si_session--si_get_offering"
+            description: "Context correlation_id returned unchanged"
+  - id: session_lifecycle
+    title: "Session lifecycle"
+    narrative: |
+      The buyer initiates a session, exchanges messages within it, and terminates
+      cleanly. Each session represents a single conversational ad experience — the
+      buyer provides context and the platform weaves sponsored content into the
+      conversation.
+
+    steps:
+      - id: si_initiate_session
+        title: "Start a conversation session"
+        narrative: |
+          The buyer initiates a new SI session with campaign context. The platform
+          creates a session and returns a session ID that the buyer uses for subsequent
+          messages.
+        task: si_initiate_session
+        schema_ref: "sponsored-intelligence/si-initiate-session-request.json"
+        response_schema_ref: "sponsored-intelligence/si-initiate-session-response.json"
+        doc_ref: "/sponsored-intelligence/tasks/si_initiate_session"
+        comply_scenario: si_session_lifecycle
+        stateful: true
+        expected: |
+          Return a new session:
+          - session_id: platform-assigned session identifier
+          - status: active
+          - Initial context acknowledgment
+          - Available interaction modes
+
+        sample_request:
+          intent: "User is researching electric vehicles for long road trips and wants to talk to Nova Motors"
+          identity:
+            consent_granted: true
+            consent_timestamp: "2026-04-22T14:00:00Z"
+            user:
+              locale: "en-US"
+
+          idempotency_key: "$generate:uuid_v4#si_baseline_session_lifecycle_si_initiate_session"
+          context:
+            correlation_id: "si_session--si_initiate_session"
+        context_outputs:
+          - name: session_id
+            path: 'session_id'
+        validations:
+          - check: response_schema
+            description: "Response matches si-initiate-session-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "si_session--si_initiate_session"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "session_id"
+            description: "Platform assigns session_id — must be echoed in si_send_message and si_terminate_session"
+      - id: si_send_message
+        title: "Exchange messages"
+        narrative: |
+          The buyer sends a message within the active session. The platform processes
+          the message and returns a response that may include sponsored content woven
+          into the conversational experience.
+        task: si_send_message
+        schema_ref: "sponsored-intelligence/si-send-message-request.json"
+        response_schema_ref: "sponsored-intelligence/si-send-message-response.json"
+        doc_ref: "/sponsored-intelligence/tasks/si_send_message"
+        comply_scenario: si_session_lifecycle
+        stateful: true
+        expected: |
+          Process the message and return a response:
+          - Message acknowledgment
+          - Response content (may include sponsored elements)
+          - Session state (active, waiting, etc.)
+
+        sample_request:
+          session_id: "$context.session_id"
+          message: "What are the best electric vehicles for long road trips?"
+
+          idempotency_key: "$generate:uuid_v4#si_baseline_session_lifecycle_si_send_message"
+          context:
+            correlation_id: "si_session--si_send_message"
+        validations:
+          - check: response_schema
+            description: "Response matches si-send-message-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "si_session--si_send_message"
+            description: "Context correlation_id returned unchanged"
+      - id: si_terminate_session
+        title: "End the session"
+        narrative: |
+          The buyer terminates the SI session. The platform records session metrics
+          and returns a summary of the conversation including any sponsored content
+          that was delivered.
+        task: si_terminate_session
+        schema_ref: "sponsored-intelligence/si-terminate-session-request.json"
+        response_schema_ref: "sponsored-intelligence/si-terminate-session-response.json"
+        doc_ref: "/sponsored-intelligence/tasks/si_terminate_session"
+        comply_scenario: si_handoff
+        stateful: true
+        expected: |
+          Terminate the session and return a summary:
+          - session_id: confirms which session was terminated
+          - status: terminated
+          - Session metrics (duration, messages exchanged)
+          - Sponsored content delivery summary
+
+        sample_request:
+          session_id: "$context.session_id"
+          reason: "handoff_complete"
+
+          context:
+            correlation_id: "si_session--si_terminate_session"
+        validations:
+          - check: response_schema
+            description: "Response matches si-terminate-session-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "si_session--si_terminate_session"
+            description: "Context correlation_id returned unchanged"