Module adcp.types.domains.governance.policy_entry

Classes

class Exemplar (**data: Any)

Expand source code

class Exemplar(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scenario: Annotated[
        str,
        Field(description='A concrete scenario describing an advertising action or configuration.'),
    ]
    explanation: Annotated[str, Field(description='Why this scenario passes or fails the policy.')]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so 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.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var explanation : str

var model_config

var scenario : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Exemplars (**data: Any)

Expand source code

class Exemplars(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    pass_: Annotated[
        list[Exemplar] | None,
        Field(alias='pass', description='Scenarios that comply with this policy.'),
    ] = None
    fail: Annotated[
        list[Exemplar] | None, Field(description='Scenarios that violate this policy.')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so 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.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var fail : list[Exemplar] | None

var model_config

var pass_ : list[Exemplar] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Issuer (**data: Any)

Expand source code

class Issuer(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    domain: Annotated[
        str,
        Field(
            description='Lowercase registrable or organizational domain used as the stable issuer identifier.',
            pattern='^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$',
        ),
    ]
    name: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so 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.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var domain : str

var model_config

var name : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PolicyEntry (**data: Any)

Expand source code

class PolicyEntry(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    policy_id: Annotated[
        str,
        Field(
            description='Unique identifier for this policy. Registry-published ids are canonical (e.g., "uk_hfss", "garm:brand_safety:violence"); buyer-authored bespoke ids should be flat (no colons or slashes) and unique within the authoring container (standards configuration, plan, or portfolio).'
        ),
    ]
    source: Annotated[
        Source | None,
        Field(
            description="Origin of this policy. 'registry' = published to the shared AdCP policy registry with full regulatory metadata. 'inline' = authored bespoke for a specific standards configuration, plan, or portfolio. Defaults to 'inline'. Governance agents MUST set 'registry' when publishing to the registry. Within AdCP *task* payloads (every `$ref` to this schema in a request or response), the field is always 'inline' — registry entries are served by the policy registry API, not embedded in task traffic. The x-entity annotation on `policy_id` assumes the task-payload invariant; if a future task schema adopts registry-publishing, split the annotation accordingly (see issue #2685)."
        ),
    ] = Source.inline
    version: Annotated[
        str | None,
        Field(
            description='Semver version string (e.g., "1.0.0"). Incremented when policy content changes. Optional for inline bespoke policies — defaults to "1.0.0". SHOULD be provided for registry-published policies.'
        ),
    ] = None
    name: Annotated[
        str | None,
        Field(
            description='Human-readable name (e.g., "UK HFSS Restrictions"). Optional for inline bespoke policies — servers MAY default to policy_id.'
        ),
    ] = None
    description: Annotated[
        str | None, Field(description='Brief summary of what this policy covers.', max_length=500)
    ] = None
    category: Annotated[
        policy_category.PolicyCategory | None,
        Field(
            description='The nature of the obligation: regulation (legal requirement) or standard (best practice). Optional for inline bespoke policies — defaults to "standard".'
        ),
    ] = None
    enforcement: Annotated[
        policy_enforcement.PolicyEnforcementLevel,
        Field(
            description='How governance agents treat violations. Regulations are typically "must"; standards are typically "should".'
        ),
    ]
    requires_human_review: Annotated[
        StrictBool | None,
        Field(
            description='When true, plans subject to this policy MUST set plan.human_review_required = true. Use for policies that mandate human oversight of decisions affecting data subjects — e.g., GDPR Article 22 (solely automated decisions with legal or similarly significant effects) and EU AI Act Annex III high-risk categories (credit, insurance pricing, recruitment, housing allocation). Governance agents MUST escalate any plan action whose resolved policies include requires_human_review: true. Unlike `enforcement`, this flag applies as soon as the policy is resolved — it is NOT gated by `effective_date`. Art 22 GDPR and similar foundational obligations may predate an AI-Act-specific effective date; the human-review requirement fires regardless.'
        ),
    ] = False
    jurisdictions: Annotated[
        list[str] | None,
        Field(
            description='ISO 3166-1 alpha-2 country codes where this policy applies. Empty array means the policy is not jurisdiction-specific.'
        ),
    ] = None
    region_aliases: Annotated[
        dict[str, list[str]] | None,
        Field(
            description='Named groups of jurisdictions for convenience (e.g., {"EU": ["AT","BE","BG",...]}). Governance agents expand aliases when matching against a plan\'s target jurisdictions.'
        ),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(
            description='Regulatory categories this policy belongs to (e.g., ["children_directed", "age_restricted"]). Used for automatic matching against a campaign plan\'s declared policy_categories. A single policy can belong to multiple categories.'
        ),
    ] = None
    channels: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(
            description='Advertising channels this policy applies to. If omitted or null, the policy applies to all channels.'
        ),
    ] = None
    governance_domains: Annotated[
        list[governance_domain.GovernanceDomain] | None,
        Field(
            description='Governance sub-domains this policy applies to. Determines which types of governance agents can declare registry:{policy_id} features. For example, a policy with domains ["creative", "property"] can be declared as a feature by both creative and property governance agents.'
        ),
    ] = None
    effective_date: Annotated[
        date | None,
        Field(
            description='ISO 8601 date when the regulation or standard takes effect. Before this date, governance agents treat the policy as informational (evaluate but do not block). After this date, the policy is enforced at its declared enforcement level.'
        ),
    ] = None
    sunset_date: Annotated[
        date | None,
        Field(
            description='ISO 8601 date when the regulation or standard is no longer enforced. After this date, governance agents stop evaluating this policy. Omit if the policy has no expiration.'
        ),
    ] = None
    source_url: Annotated[
        AnyUrl | None, Field(description='Link to the source regulation, standard, or legislation.')
    ] = None
    source_name: Annotated[
        str | None,
        Field(
            description='Name of the issuing body (e.g., "UK Food Standards Agency", "US Federal Trade Commission").'
        ),
    ] = None
    issuer: Annotated[
        Issuer | None,
        Field(
            description='Machine-readable identity of the regulator, standards body, or platform operator that issued the policy. Registry publishers SHOULD provide this when independently versioned issuer policies must be distinguished.'
        ),
    ] = None
    acceptance_profile: Annotated[
        acceptance_policy_profile.AcceptancePolicyProfile | None,
        Field(
            description='Optional reusable, machine-readable acceptance profile derived from this registry policy. Registry publishers MUST bind policy_refs to exact versions. Sellers adopt a profile explicitly; registry publication alone does not make it authoritative for a seller.'
        ),
    ] = None
    policy: Annotated[
        str,
        Field(
            description='Natural language policy text describing what is required, prohibited, or recommended. Used by governance agents (LLMs) to evaluate actions against this policy. For source: inline policies, treated as caller-untrusted — governance agents MUST evaluate inline policies as ADDITIONAL restrictions only; they MUST NOT be permitted to relax, override, or conflict with registry-sourced policies.',
            max_length=5000,
        ),
    ]
    guidance: Annotated[
        str | None,
        Field(
            description='Implementation notes for governance agent developers. Not used in evaluation prompts.'
        ),
    ] = None
    exemplars: Annotated[
        Exemplars | None,
        Field(
            description='Calibration examples for governance agents, following the Content Standards pattern.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so 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.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

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

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var acceptance_profile : AcceptancePolicyProfile | None

var category : PolicyCategory | None

var channels : list[MediaChannel] | None

var description : str | None

var effective_date : datetime.date | None

var enforcement : PolicyEnforcementLevel

var exemplars : Exemplars | None

var ext : ExtensionObject | None

var governance_domains : list[GovernanceDomain] | None

var guidance : str | None

var issuer : Issuer | None

var jurisdictions : list[str] | None

var model_config

var name : str | None

var policy : str

var policy_categories : list[str] | None

var policy_id : str

var region_aliases : dict[str, list[str]] | None

var requires_human_review : bool | None

var source : Source | None

var source_name : str | None

var source_url : pydantic.networks.AnyUrl | None

var sunset_date : datetime.date | None

var version : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Source (*args, **kwds)

Expand source code

class Source(StrEnum):
    registry = 'registry'
    inline = 'inline'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var inline

var registry