Skip to content

Commit a050666

Browse files
atc964atc964
authored
Merge pull request #42 from IABTechLab/docs/feature-stubs
Add Coming Soon stub pages for Phase 2 features
2 parents 104bd3c + 4927ba3 commit a050666

9 files changed

Lines changed: 651 additions & 4 deletions

File tree

‎docs/architecture/event-bus.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Event Bus
2+
3+
!!! info "Coming Soon"
4+
The event bus is planned for the buyer agent, based on the seller agent's implementation. This page describes the planned immutable event logging system for observability and auditability.
5+
6+
The event bus provides an immutable, append-only event log for all significant actions within the buyer agent. Every deal quote, negotiation round, booking, state transition, and budget reallocation is recorded as an event — giving operators full observability into what the buyer agent did, when, and why.
7+
8+
## Why an Event Bus
9+
10+
The buyer agent currently logs actions through standard Python logging and persists deal state in the [DealStore](deal-store.md). An event bus adds structured, queryable event records that serve multiple purposes:
11+
12+
- **Auditability** — Regulators, advertisers, and agency partners can trace every action the buyer agent took on their behalf
13+
- **Debugging** — Reconstruct the exact sequence of events that led to a deal outcome
14+
- **Analytics** — Query historical events for reporting (e.g., average negotiation rounds, win rates by seller, time-to-book)
15+
- **Integration** — External systems can subscribe to events for real-time dashboards, alerting, or downstream processing
16+
17+
## Planned Event Types
18+
19+
| Event Type | Emitted When | Example Payload |
20+
|------------|-------------|-----------------|
21+
| `quote.requested` | Quote request sent to seller | `{seller_url, product_id, target_cpm}` |
22+
| `quote.received` | Quote response received | `{quote_id, final_cpm, expires_at}` |
23+
| `negotiation.started` | Negotiation session opened | `{proposal_id, strategy, opening_offer}` |
24+
| `negotiation.round` | Each negotiation round completes | `{round_number, buyer_price, seller_price, action}` |
25+
| `negotiation.completed` | Negotiation session ended | `{outcome, final_price, rounds_count}` |
26+
| `deal.booked` | Deal booking confirmed | `{deal_id, quote_id, final_cpm}` |
27+
| `deal.state_changed` | Deal status transition | `{deal_id, from_state, to_state, reason}` |
28+
| `budget.reallocation` | Budget shifted between deals/channels | `{from_deal, to_deal, amount, reason}` |
29+
| `creative.validated` | Creative spec validation completed | `{creative_id, format, result, violations}` |
30+
31+
## Seller Event Bus Reference
32+
33+
The seller agent already implements an event bus for server-side observability. The buyer's event bus will follow the same architectural pattern — immutable append-only log with structured events — applied to buyer-side actions.
34+
35+
See the seller's event bus documentation: [Seller Event Bus](https://iabtechlab.github.io/seller-agent/event-bus/overview/)
36+
37+
## Key Planned Functionality
38+
39+
- **Immutable event log** — Append-only storage; events are never modified or deleted
40+
- **Structured events** — Each event has a type, timestamp, actor, and typed payload
41+
- **Queryable history** — Filter and search events by type, time range, deal ID, seller, or actor
42+
- **Event subscriptions** — Register handlers that fire when specific event types are emitted
43+
- **Correlation IDs** — Trace a chain of related events across a multi-step workflow (e.g., from quote request through negotiation to booking)
44+
- **Retention policies** — Configurable retention periods for compliance and storage management
45+
46+
## Related
47+
48+
- [Deal Store](deal-store.md) — Current deal persistence (event bus complements, does not replace)
49+
- [Order State Machine](state-machine.md) — State transitions emit events to the event bus
50+
- [Architecture Overview](overview.md) — System architecture context
51+
- [Seller Event Bus](https://iabtechlab.github.io/seller-agent/event-bus/overview/) — Seller-side event bus implementation

‎docs/architecture/state-machine.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Order State Machine
2+
3+
!!! info "Coming Soon"
4+
The formal order state machine is planned for the buyer agent, based on the seller agent's proven implementation. This page describes the planned state transition enforcement for the deal lifecycle.
5+
6+
The order state machine enforces valid state transitions for deals as they move through their lifecycle — from initial quote through booking, activation, and completion. By formalizing state transitions, the buyer agent can guarantee that deals never enter invalid states and that every transition is auditable.
7+
8+
## Why a State Machine
9+
10+
Today, deal status transitions in the buyer agent are tracked via the [DealStore](deal-store.md) and updated based on seller responses. The status field is a string that can be set freely. A formal state machine adds:
11+
12+
- **Transition validation** — Only defined transitions are allowed (e.g., a `completed` deal cannot move back to `proposed`)
13+
- **Guard conditions** — Transitions can require preconditions (e.g., a deal cannot move to `active` without confirmed creative assets)
14+
- **Transition hooks** — Actions triggered automatically on state change (e.g., notify the campaign manager when a deal moves to `active`)
15+
- **Audit trail** — Every transition is logged with timestamp, actor, and reason
16+
17+
## Planned State Transitions
18+
19+
The buyer-side deal lifecycle will follow these states:
20+
21+
```
22+
quoted --> proposed --> active --> completed
23+
| | |
24+
v v v
25+
expired rejected cancelled
26+
```
27+
28+
| From | To | Trigger | Guard |
29+
|------|----|---------|-------|
30+
| `quoted` | `proposed` | Buyer books the deal | Quote not expired |
31+
| `quoted` | `expired` | Quote TTL exceeded | — |
32+
| `proposed` | `active` | Seller activates the deal | — |
33+
| `proposed` | `rejected` | Seller rejects the booking | — |
34+
| `active` | `completed` | Impressions delivered / flight ended | — |
35+
| `active` | `cancelled` | Buyer or seller cancels | Cancellation policy allows |
36+
37+
## Seller State Machine Reference
38+
39+
The seller agent already implements a formal order lifecycle state machine. The buyer's state machine will complement the seller's, tracking the buyer-side view of the same deal lifecycle.
40+
41+
See the seller's state machine documentation for the authoritative server-side implementation: [Seller Order Lifecycle](https://iabtechlab.github.io/seller-agent/state-machines/order-lifecycle/)
42+
43+
## Key Planned Functionality
44+
45+
- **Declarative state definitions** — States and transitions defined in configuration, not scattered through code
46+
- **Transition guards** — Precondition checks before allowing a state change
47+
- **Transition hooks** — Automatic side effects on state change (notifications, logging, metric updates)
48+
- **Immutable transition log** — Append-only record of all state changes with metadata
49+
- **Sync with seller state** — Map seller-side state changes to buyer-side transitions when the seller reports status updates
50+
51+
## Related
52+
53+
- [Deal Store](deal-store.md) — Current deal persistence (state machine builds on this)
54+
- [Deals API](../api/deals.md) — Deal lifecycle statuses
55+
- [Event Bus](event-bus.md) — Planned event logging (state transitions emit events)
56+
- [Seller Order Lifecycle](https://iabtechlab.github.io/seller-agent/state-machines/order-lifecycle/) — Seller-side state machine

‎docs/guides/budget-pacing.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Budget Pacing & Reallocation
2+
3+
!!! info "Coming Soon — Phase 2"
4+
Budget pacing and reallocation (buyer-9zz) is part of Phase 2: Campaign Intelligence. It depends on the [Campaign Brief to Deal Pipeline](campaign-pipeline.md) (buyer-u8l). This page describes the planned budget management capability.
5+
6+
The budget pacing engine monitors campaign spend against plan in real time, detects over-delivery and under-delivery, and reallocates budget across channels and sellers mid-flight. When pacing is off-target, the engine can issue deal adjustment requests to sellers to bring the campaign back on track.
7+
8+
## What Budget Pacing Does
9+
10+
After a campaign's deals are booked (either manually or via the [campaign pipeline](campaign-pipeline.md)), the pacing engine tracks delivery against the plan. Without pacing, a campaign can exhaust its budget early (over-delivery) or fail to spend its budget (under-delivery) — both waste advertiser money or miss reach goals.
11+
12+
The pacing engine addresses three questions continuously:
13+
14+
1. **Are we on pace?** — Compare actual spend and impressions against the planned delivery curve
15+
2. **What is off?** — Identify which channels, sellers, or deals are over- or under-delivering
16+
3. **What should we do?** — Reallocate budget from under-performing deals to over-performing ones, or request delivery adjustments from sellers
17+
18+
## Planned Capabilities
19+
20+
### Spend Monitoring
21+
22+
- Track actual impressions and spend per deal, per channel, and per seller
23+
- Compare against the planned delivery curve (linear pacing, front-loaded, or back-loaded)
24+
- Surface pacing alerts when delivery deviates beyond configurable thresholds
25+
26+
### Delivery Detection
27+
28+
- **Over-delivery** — A deal or channel is spending faster than planned, risking early budget exhaustion
29+
- **Under-delivery** — A deal or channel is spending slower than planned, risking unspent budget at flight end
30+
- **Stalled delivery** — A deal has stopped delivering entirely (zero impressions over a configurable window)
31+
32+
### Budget Reallocation
33+
34+
- Shift budget from under-delivering deals to over-delivering ones within the same channel
35+
- Shift budget across channels when an entire channel is under-delivering
36+
- Respect minimum and maximum allocation constraints per seller and per channel
37+
- Log all reallocation decisions with rationale for auditability
38+
39+
### Seller Adjustment Requests
40+
41+
- Issue deal modification requests to sellers when pacing requires delivery changes
42+
- Request increased delivery on under-delivering deals (if seller has available inventory)
43+
- Request throttled delivery on over-delivering deals
44+
- Track seller responses and adjust the pacing model accordingly
45+
46+
## Key Planned Functionality
47+
48+
- **Real-time pacing dashboard** — Current spend vs. plan across all active deals
49+
- **Configurable pacing curves** — Linear, front-loaded, back-loaded, or custom delivery curves
50+
- **Automatic reallocation** — Rules-based budget shifting when pacing deviates beyond thresholds
51+
- **Manual override** — Campaign manager can approve or reject reallocation recommendations
52+
- **Deal adjustment API** — Request delivery changes from sellers via the [Deals API](../api/deals.md)
53+
- **Pacing history** — Full audit trail of pacing measurements and reallocation decisions
54+
55+
## Integration Points
56+
57+
Budget pacing builds on several existing and planned buyer agent capabilities:
58+
59+
- [Campaign Brief to Deal Pipeline](campaign-pipeline.md) — Defines the initial budget allocation that pacing monitors
60+
- [Deals API](../api/deals.md) — Used for deal status checks and modification requests
61+
- [Multi-Seller Orchestration](multi-seller-orchestration.md) — Portfolio-level optimization informs reallocation decisions
62+
- [Sessions](sessions.md) — Persistent seller sessions for mid-flight deal adjustments
63+
64+
## Related
65+
66+
- [Campaign Brief to Deal Pipeline](campaign-pipeline.md) — Initial campaign setup (pacing monitors what the pipeline books)
67+
- [Deals API](../api/deals.md) — Deal status and modification endpoints
68+
- [Multi-Seller Orchestration](multi-seller-orchestration.md) — Cross-seller portfolio management
69+
- [Seller Agent Docs](https://iabtechlab.github.io/seller-agent/) — Seller-side deal management

‎docs/guides/campaign-pipeline.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Campaign Brief to Deal Pipeline
2+
3+
!!! info "Coming Soon — Phase 2"
4+
The campaign pipeline (buyer-u8l) is part of Phase 2: Campaign Intelligence. The foundation it builds on — authentication, seller discovery, media kit browsing, negotiation, and the deals API — is all shipped and documented. This page describes the planned end-to-end pipeline capability.
5+
6+
The campaign pipeline transforms a structured **campaign brief** into **booked deals** — automating the entire workflow from audience planning through inventory discovery, pricing, negotiation, and booking. This is the "one-click campaign" capability: hand the buyer agent a brief describing what you want to achieve, and it returns a portfolio of booked deals that satisfy the brief's objectives.
7+
8+
## What the Pipeline Does
9+
10+
Today, assembling a media plan requires manually stepping through each stage: discover sellers, browse media kits, request quotes, negotiate pricing, evaluate options, and book deals. The campaign pipeline orchestrates all of these stages automatically.
11+
12+
Given a campaign brief, the pipeline will:
13+
14+
1. **Parse the brief** — Extract target audience, budget, channels, flight dates, and KPIs from a structured JSON input
15+
2. **Plan the audience** — Map the brief's audience definition to targeting parameters using the Universal Campaign Planner (UCP)
16+
3. **Discover inventory** — Query the seller registry and browse media kits across multiple sellers, filtering for inventory that matches the brief's channel and audience requirements
17+
4. **Request pricing** — Submit quote requests to qualifying sellers via the [Deals API](../api/deals.md)
18+
5. **Negotiate** — Run automated [negotiation](negotiation.md) with sellers whose quotes are within budget range
19+
6. **Optimize the portfolio** — Select the combination of deals that maximizes reach and efficiency within budget constraints
20+
7. **Book deals** — Convert selected quotes into confirmed deals
21+
22+
## Campaign Brief Structure
23+
24+
The pipeline accepts a JSON campaign brief as input. The brief describes the advertiser's goals without prescribing specific sellers or packages.
25+
26+
```json
27+
{
28+
"name": "Q3 2026 Back-to-School Campaign",
29+
"advertiser": "target-stores-001",
30+
"objectives": ["brand_awareness", "reach"],
31+
"budget": {
32+
"total_usd": 250000,
33+
"channel_allocation": {
34+
"ctv": 0.40,
35+
"display": 0.35,
36+
"mobile": 0.25
37+
}
38+
},
39+
"audience": {
40+
"demographics": {
41+
"age_range": "25-54",
42+
"gender": "all",
43+
"hhi_min": 50000
44+
},
45+
"interests": ["parenting", "education", "shopping"],
46+
"geo": {
47+
"country": "US",
48+
"dma_codes": ["501", "803", "602"]
49+
}
50+
},
51+
"flight": {
52+
"start_date": "2026-07-15",
53+
"end_date": "2026-09-15"
54+
},
55+
"kpis": {
56+
"target_cpm": 18.00,
57+
"max_cpm": 30.00,
58+
"min_reach_pct": 60
59+
},
60+
"constraints": {
61+
"max_sellers": 5,
62+
"min_deals_per_channel": 1,
63+
"brand_safety": ["standard"]
64+
}
65+
}
66+
```
67+
68+
## Planned Pipeline Stages
69+
70+
### Stage 1: Audience Planning
71+
72+
The pipeline translates the brief's high-level audience description into targeting parameters that can be matched against seller inventory. This includes mapping demographic targets to IAB audience segments and resolving geographic constraints to DMA codes.
73+
74+
### Stage 2: Inventory Discovery
75+
76+
Using the [Multi-Seller Discovery](multi-seller.md) workflow, the pipeline queries the seller registry for sellers that carry relevant inventory, browses their media kits, and builds a candidate set of packages that match the brief's channel and audience requirements.
77+
78+
### Stage 3: Pricing and Negotiation
79+
80+
The pipeline requests quotes from candidate sellers via the [Deals API](../api/deals.md) and runs automated negotiation using configurable [negotiation strategies](negotiation.md). The negotiation strategy can be set per-channel or per-seller.
81+
82+
### Stage 4: Portfolio Optimization
83+
84+
With quotes and negotiated prices in hand, the pipeline selects the optimal combination of deals. The optimizer balances price efficiency against reach, respects budget constraints and channel allocations, and ensures minimum deal counts per channel.
85+
86+
### Stage 5: Booking
87+
88+
Selected deals are booked through the standard [Deals API](../api/deals.md) quote-then-book flow. The pipeline returns a summary of all booked deals, including deal IDs, pricing, and activation instructions.
89+
90+
## Key Planned Functionality
91+
92+
- **Brief-driven execution** — Define campaign goals declaratively; the pipeline handles tactical execution
93+
- **Multi-channel orchestration** — Allocate budget across CTV, display, and mobile channels within a single pipeline run
94+
- **Automatic seller selection** — Discover and evaluate sellers based on brief requirements, not manual shortlists
95+
- **Budget-aware negotiation** — Negotiation strategies informed by the brief's target and maximum CPM
96+
- **Portfolio-level optimization** — Select deals that maximize campaign objectives, not just minimize individual CPMs
97+
- **Approval gates** — Optional human-in-the-loop checkpoints before booking (configurable via `auto_approve`)
98+
- **Idempotent execution** — Re-running the pipeline with the same brief produces consistent results
99+
100+
## Integration Points
101+
102+
The campaign pipeline builds on existing buyer agent capabilities:
103+
104+
- [Seller Discovery](../api/seller-discovery.md) — Registry-based seller lookup
105+
- [Media Kit Browsing](media-kit.md) — Inventory discovery across sellers
106+
- [Deals API](../api/deals.md) — Quote-then-book flow for pricing and booking
107+
- [Negotiation](negotiation.md) — Automated multi-turn price negotiation
108+
- [Identity Strategy](identity.md) — Per-seller identity disclosure decisions
109+
- [Sessions](sessions.md) — Persistent conversation context with sellers
110+
111+
## Related
112+
113+
- [Multi-Seller Discovery](multi-seller.md) — Manual multi-seller workflow (the pipeline automates this)
114+
- [Deals API](../api/deals.md) — The underlying quote-then-book API
115+
- [Budget Pacing & Reallocation](budget-pacing.md) — Mid-flight budget management (builds on the pipeline)

0 commit comments

Comments
 (0)