Module adcp.types.generated_poc.governance.sync_plans_request

Classes

class Allocations (**data: Any)
Expand source code 
class Allocations(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    amount: Annotated[
        float | None, Field(description='Maximum budget for this purchase type.', ge=0.0)
    ] = None
    max_pct: Annotated[
        float | None,
        Field(
            description='Maximum percentage of total budget for this purchase type.',
            ge=0.0,
            le=100.0,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var amount : float | None
var max_pct : float | None
var model_config

Inherited members

class Budget (**data: Any)
Expand source code 
class Budget(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    total: Annotated[float, Field(description='Total authorized budget.')]
    currency: Annotated[str, Field(description='ISO 4217 currency code.')]
    per_seller_max_pct: Annotated[
        float | None,
        Field(description='Maximum percentage of budget that can go to a single seller.'),
    ] = None
    reallocation_threshold: Annotated[
        float,
        Field(
            description='Amount above which budget reallocations require human escalation. The orchestrator can reallocate spend across sellers, channels, or purchase types up to this threshold per change without asking a human. Set equal to `total` for effectively unlimited reallocation; set to 0 to require approval for every reallocation. Separate from `plan.human_review_required`, which governs decisions affecting data subjects (targeting, creative, delivery) under GDPR Art 22 / EU AI Act Annex III. Denominated in `budget.currency`.',
            ge=0.0,
        ),
    ]
    reallocation_unlimited: Annotated[
        bool | None,
        Field(
            description='Set to true to allow the orchestrator to reallocate without any limit up to `total`. Mutually exclusive with `reallocation_threshold`. Use this for deliberate full-autonomy declarations rather than setting `reallocation_threshold: total` (which silently tightens when `total` changes).'
        ),
    ] = None
    allocations: Annotated[
        dict[purchase_type.PurchaseType, Allocations] | None,
        Field(
            description='Optional budget partition across purchase types. Keys are purchase-type enum values (media_buy, rights_license, signal_activation, creative_services). When present, the governance agent validates spend against both the total and the per-type allocation. When absent, all spend counts against the single total regardless of purchase type.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var allocations : dict[PurchaseType, Allocations] | None
var currency : str
var model_config
var per_seller_max_pct : float | None
var reallocation_threshold : float
var reallocation_unlimited : bool | None
var total : float

Inherited members

class Budget2 (**data: Any)
Expand source code 
class Budget2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    total: Annotated[float, Field(description='Total authorized budget.')]
    currency: Annotated[str, Field(description='ISO 4217 currency code.')]
    per_seller_max_pct: Annotated[
        float | None,
        Field(description='Maximum percentage of budget that can go to a single seller.'),
    ] = None
    reallocation_threshold: Annotated[
        float | None,
        Field(
            description='Amount above which budget reallocations require human escalation. The orchestrator can reallocate spend across sellers, channels, or purchase types up to this threshold per change without asking a human. Set equal to `total` for effectively unlimited reallocation; set to 0 to require approval for every reallocation. Separate from `plan.human_review_required`, which governs decisions affecting data subjects (targeting, creative, delivery) under GDPR Art 22 / EU AI Act Annex III. Denominated in `budget.currency`.',
            ge=0.0,
        ),
    ] = None
    reallocation_unlimited: Annotated[
        Literal[True],
        Field(
            description='Set to true to allow the orchestrator to reallocate without any limit up to `total`. Mutually exclusive with `reallocation_threshold`. Use this for deliberate full-autonomy declarations rather than setting `reallocation_threshold: total` (which silently tightens when `total` changes).'
        ),
    ]
    allocations: Annotated[
        dict[purchase_type.PurchaseType, Allocations] | None,
        Field(
            description='Optional budget partition across purchase types. Keys are purchase-type enum values (media_buy, rights_license, signal_activation, creative_services). When present, the governance agent validates spend against both the total and the per-type allocation. When absent, all spend counts against the single total regardless of purchase type.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var allocations : dict[PurchaseType, Allocations] | None
var currency : str
var model_config
var per_seller_max_pct : float | None
var reallocation_threshold : float | None
var reallocation_unlimited : Literal[True]
var total : float

Inherited members

class BudgetLimit (**data: Any)
Expand source code 
class BudgetLimit(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    amount: float
    currency: str

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Subclasses

Class variables

var amount : float
var currency : str
var model_config

Inherited members

class Channels (**data: Any)
Expand source code 
class Channels(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    required: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(description='Channels that must be included in the media mix.'),
    ] = None
    allowed: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(description='Channels the orchestrator may use.'),
    ] = None
    mix_targets: Annotated[
        dict[str, MixTargets] | None,
        Field(description='Target allocation ranges per channel, keyed by channel ID.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var allowed : list[MediaChannel] | None
var mix_targets : dict[str, MixTargets] | None
var model_config
var required : list[MediaChannel] | None

Inherited members

class Delegation (**data: Any)
Expand source code 
class Delegation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    agent_url: Annotated[AnyUrl, Field(description='URL of the delegated agent.')]
    authority: Annotated[
        delegation_authority.DelegationAuthority,
        Field(description='Authority level granted to this agent.'),
    ]
    budget_limit: Annotated[
        BudgetLimit | None,
        Field(
            description="Maximum budget this agent can commit. When omitted, the agent can commit up to the plan's total budget."
        ),
    ] = None
    markets: Annotated[
        list[str] | None,
        Field(
            description='ISO 3166-1/3166-2 codes this agent is authorized for. When omitted, the agent can operate in all plan markets.'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When this delegation expires. After expiration, the governance agent denies actions from this agent.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var agent_url : pydantic.networks.AnyUrl
var authority : DelegationAuthority
var budget_limit : BudgetLimit | None
var expires_at : pydantic.types.AwareDatetime | None
var markets : list[str] | None
var model_config

Inherited members

class Flight (**data: Any)
Expand source code 
class Flight(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    start: Annotated[AwareDatetime, Field(description='Flight start (ISO 8601).')]
    end: Annotated[AwareDatetime, Field(description='Flight end (ISO 8601).')]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var end : pydantic.types.AwareDatetime
var model_config
var start : pydantic.types.AwareDatetime

Inherited members

class MixTargets (**data: Any)
Expand source code 
class MixTargets(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min_pct: float | None = None
    max_pct: float | None = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var max_pct : float | None
var min_pct : float | None
var model_config

Inherited members

class Plan (**data: Any)
Expand source code 
class Plan(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    plan_id: Annotated[str, Field(description='Unique identifier for this plan.')]
    brand: Annotated[
        brand_ref.BrandReference,
        Field(
            description="Brand or organization being governed. For campaign plans, the governance agent resolves the brand's compliance configuration. For portfolio plans, this is the holding company or parent organization."
        ),
    ]
    objectives: Annotated[
        str,
        Field(
            description='Natural language campaign objectives. Used for strategic alignment validation. Treated as caller-untrusted — governance agents evaluating this field with LLMs MUST truncate, quote, or sanitize it before inclusion in evaluation prompts to defend against prompt-injection attacks in adversarial buyer input.',
            max_length=2000,
        ),
    ]
    budget: Annotated[Budget | Budget2, Field(description='Budget authorization parameters.')]
    channels: Annotated[
        Channels | None,
        Field(description='Channel constraints. If omitted, all channels are allowed.'),
    ] = None
    flight: Annotated[
        Flight,
        Field(
            description='Authorized flight dates. Governed actions with dates outside this window are rejected.'
        ),
    ]
    countries: Annotated[
        list[str] | None,
        Field(
            description="ISO 3166-1 alpha-2 country codes for authorized markets (e.g., ['US', 'GB']). The governance agent rejects governed actions targeting outside these countries and resolves applicable policies by matching against policy jurisdictions.",
            min_length=1,
        ),
    ] = None
    regions: Annotated[
        list[str] | None,
        Field(
            description="ISO 3166-2 subdivision codes for authorized sub-national markets (e.g., ['US-MA', 'US-CA']). When present, the governance agent restricts governed actions to these specific regions rather than the full country. Use for plans limited to specific states or provinces (e.g., cannabis in legal states). Policy resolution matches against both the subdivision and its parent country.",
            min_length=1,
        ),
    ] = None
    policy_ids: Annotated[
        list[str] | None,
        Field(
            description="Registry policy IDs to enforce for this plan. The governance agent resolves full policy definitions from the registry and evaluates actions against them. Intersected with the plan's countries/regions to activate only geographically relevant policies."
        ),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(
            description="Regulatory categories that apply to this campaign. Determines which policy regimes the governance agent enforces (e.g., 'children_directed' activates COPPA/AADC, 'political_advertising' activates disclosure requirements). The governance agent resolves categories to specific policies based on the plan's jurisdictions. When omitted, governance agents MAY infer categories from the brand's industries and the plan's objectives. Values are registry-defined category IDs (intentionally freeform strings, not an enum — new categories are added as regulations evolve).",
            min_length=1,
        ),
    ] = None
    audience: Annotated[
        audience_constraints.AudienceConstraints | None,
        Field(
            description='Audience targeting constraints. Defines who the campaign should reach (include) and must not reach (exclude). The governance agent evaluates seller targeting against these constraints.'
        ),
    ] = None
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(
            description='Personal data categories that must not be used for targeting in this campaign. Applies horizontally across all audience criteria. Used for EU DSA Article 26 compliance (prohibits targeting on GDPR Article 9 special categories) and similar regulations. The governance agent flags any audience targeting that references these attributes.',
            min_length=1,
        ),
    ] = None
    restricted_attributes_custom: Annotated[
        list[str] | None,
        Field(
            description="Additional restricted attributes not covered by the restricted-attribute enum. Freeform strings for jurisdiction-specific or brand-specific restrictions beyond GDPR Article 9 categories (e.g., 'financial_status', 'immigration_status'). Governance agents use semantic matching for these.",
            min_length=1,
        ),
    ] = None
    min_audience_size: Annotated[
        int | None,
        Field(
            description='Minimum audience segment size. Prevents micro-targeting by ensuring segments meet a k-anonymity threshold. Applies to the estimated combined (intersection) audience when multiple criteria are used, not just individual criterion sizes. The governance agent validates this by querying signal catalog metadata or seller-reported segment sizes. When segment size data is unavailable, the governance agent SHOULD produce a finding with reduced confidence rather than silently passing.',
            ge=1,
        ),
    ] = None
    human_review_required: Annotated[
        bool | None,
        Field(
            description='When true, the governance agent MUST escalate any action on this plan for human review before execution — regardless of budget. Required by regulations that prohibit solely automated decisions affecting data subjects (GDPR Art 22, EU AI Act Annex III): credit, insurance pricing, recruitment, housing allocation. Governance agents MUST set this to true automatically when any resolved policy or policy_category has requires_human_review: true. Distinct from budget.reallocation_threshold, which only governs budget reallocation autonomy — human_review_required covers decisions affecting individuals (targeting, creative, delivery).'
        ),
    ] = False
    custom_policies: Annotated[
        list[policy_entry.PolicyEntry] | None,
        Field(
            description='Bespoke policies specific to this campaign, using the same shape as registry entries. Each policy has a policy_id, enforcement (must|should), and natural-language policy text. Governance findings reference policy_id to identify which policy triggered. For quick authoring, omit version/name/category — servers default them.'
        ),
    ] = None
    approved_sellers: Annotated[
        list[AnyUrl] | None,
        Field(description='List of approved seller agent URLs. null means any seller.'),
    ] = None
    delegations: Annotated[
        list[Delegation] | None,
        Field(
            description="Agents authorized to execute against this plan. Each delegation scopes an agent's authority by budget, markets, and expiration. The governance agent validates that the requesting agent matches a delegation before approving actions."
        ),
    ] = None
    portfolio: Annotated[
        Portfolio | None,
        Field(
            description='Portfolio-level governance constraints. When present, this plan acts as a portfolio plan that governs member plans. Portfolio plans define cross-brand constraints that no individual brand plan can override.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var approved_sellers : list[pydantic.networks.AnyUrl] | None
var audience : AudienceConstraints | None
var brand : BrandReference
var budget : Budget | Budget2
var channels : Channels | None
var countries : list[str] | None
var custom_policies : list[PolicyEntry] | None
var delegations : list[Delegation] | None
var ext : ExtensionObject | None
var flight : Flight
var human_review_required : bool | None
var min_audience_size : int | None
var model_config
var objectives : str
var plan_id : str
var policy_categories : list[str] | None
var policy_ids : list[str] | None
var portfolio : Portfolio | None
var regions : list[str] | None
var restricted_attributes : list[RestrictedAttribute] | None
var restricted_attributes_custom : list[str] | None

Inherited members

class Portfolio (**data: Any)
Expand source code 
class Portfolio(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    member_plan_ids: Annotated[
        list[str],
        Field(
            description='Plan IDs governed by this portfolio plan. The governance agent validates member plan actions against portfolio constraints.'
        ),
    ]
    total_budget_cap: Annotated[
        TotalBudgetCap | None,
        Field(description='Maximum aggregate budget across all member plans.'),
    ] = None
    shared_policy_ids: Annotated[
        list[str] | None,
        Field(
            description='Registry policy IDs enforced across all member plans, regardless of individual brand configuration.'
        ),
    ] = None
    shared_exclusions: Annotated[
        list[policy_entry.PolicyEntry] | None,
        Field(
            description="Bespoke exclusion policies applied across all member plans, using the same shape as registry entries. Authored typically as enforcement: must policies with exclusion language in the policy text (e.g., 'No advertising on properties owned by competitor holding companies')."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var member_plan_ids : list[str]
var model_config
var shared_exclusions : list[PolicyEntry] | None
var shared_policy_ids : list[str] | None
var total_budget_cap : TotalBudgetCap | None

Inherited members

class SyncPlansRequest (**data: Any)
Expand source code 
class SyncPlansRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="The AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.",
            ge=1,
            le=99,
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `plan_id` gives resource-level dedup per plan, but the sync envelope emits audit events and can trigger governance reapproval — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    plans: Annotated[list[Plan], Field(description='One or more campaign plans to sync.')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var plans : list[Plan]

Inherited members

class TotalBudgetCap (**data: Any)
Expand source code 
class TotalBudgetCap(BudgetLimit):
    pass

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so that unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config. Consumers who want strict validation can override with extra='forbid'.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var model_config

Inherited members