Skip to content

Export the error-details models from adcp.types (14 of 15 are unreachable outside generated_poc) #1080

Closed

Description

@KonstantinMirin

Summary

adcp/types/generated_poc/error_details/ contains a generated pydantic model for every
error-details/*.json schema in the bundle — 15 modules, e.g. ActionNotAllowedDetails,
AgentPermissionDeniedDetails, StaleResponseDetails, VersionUnsupportedDetails. Only
one of them, AuthorizationRequiredDetails, is re-exported from adcp.types:

from adcp.types import AuthorizationRequiredDetails   # works
from adcp.types import ActionNotAllowedDetails        # ImportError

Verified against adcp==6.6.0 / spec 3.1.1. dir(adcp.types) yields exactly one name
ending in Details, and the generated_poc path is documented as not-for-consumers.

Please export the rest.

Why a consumer needs them

error.details is typed dict on the Error model, so nothing at a raise site
constrains what goes in it. Five of these schemas declare required fields —
action-not-allowed (attempted_action, reason), agent-permission-denied
(scope, reason), billing-not-permitted-for-agent (rejected_billing),
stale-response (served_from_cache, cache_age_seconds), version-unsupported
(supported_versions) — and a seller that wants a missing required key to be a
typecheck error rather than a runtime surprise needs the model at the call site.

The models already exist and already encode exactly that. They are simply unreachable,
so every consumer that wants this has to re-declare them locally and then maintain a
guard asserting the local copy still matches the bundle schema — a transcription of
something you already ship, kept in sync by hand.

This is a small, additive change: the models are generated, the schemas are in the
bundle, and AuthorizationRequiredDetails already establishes the precedent for
exporting one.

Suggested shape

Re-export all 15 from adcp/types/__init__.py alongside AuthorizationRequiredDetails.
If a stable public name is wanted for the family, an adcp.types.error_details
subpackage re-exporting them would work equally well for consumers — the requirement is
just that they are importable from a supported path.

Note on extra

The generated models carry extra="allow", which is right for these: several of the
schemas omit additionalProperties, so draft-07 permits extension keys, and a seller
adding diagnostic fields should not be rejected. Two of the schemas do declare
additionalProperties: false; if the generator can reflect that as extra="forbid" on
just those two, the models would carry the distinction the schemas make. Not a blocker
for exporting them.

Related

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 24, 2026
  2. bokelley commented on Aug 24, 2026

    @bokelley
    Contributor

    Triage

    Classification: Bug
    Bucket(s): client (adcp.types public surface)
    Status: ready-to-implement

    What the experts said:

    • code-reviewer: Bug, not enhancement — AuthorizationRequiredDetails and UnsupportedRefinementDimensionDetails establish an unambiguous export precedent; 16 sibling classes from the same generated_poc/error_details/ family are simply missing. Change is purely additive (no existing imports disturbed); test_lazy_types.py provides a built-in completeness check that will fail if the three locations aren't updated atomically.
    • dx-expert: Clear yes — error.details typed as dict means every consumer who constructs a structured error payload must re-declare the model locally; exporting from adcp.types (not a subpackage) matches the established pattern and removes the maintenance burden.

    My take: The internal count is 18 error-details modules (the issue says 15, spec may have grown). All 16 unexported classes should be added in one PR; _generated.py already imports all of them, so this is a two-file wiring change. The single naming outlier is VendorErrorCodeRegistry (from vendor_error_codes.py) — the implementer should confirm whether ActionNotAllowedReason (an enum dependency already present in _generated.__all__) should be co-exported alongside ActionNotAllowedDetails.

    Implementation scope:

    • Files to change (only these two): src/adcp/types/_eager.py and src/adcp/types/__init__.py
    • Three locations must be updated atomically or test_lazy_types.py will fail:
      1. _eager.py — add the 16 names to the from adcp.types._generated import (...) block and to _eager.__all__
      2. __init__.py — add the same 16 names to __all__
      3. __init__.py — add the same 16 names to the TYPE_CHECKING re-export block (mypy sees only this path)
    • Classes to add (already in _generated.py at lines 1955–1997): AccessibilityViolationDetails, AccountMovedDetails, AccountSetupRequiredDetails, ActionNotAllowedDetails, AgentPermissionDeniedDetails, AudienceTooSmallDetails, BillingNotPermittedForAgentDetails, BillingNotSupportedDetails, BudgetTooLowDetails, ConflictDetails, CreativeRejectedDetails, PolicyViolationDetails, RateLimitedDetails, StaleResponseDetails, VendorErrorCodeRegistry, VersionUnsupportedDetails
    • Required checks: make lint && make typecheck-all && pytest tests/test_lazy_types.py tests/test_import_layering.py (no generated-file edits needed)
    • Non-breaking rationale: purely additive — new names in __all__, no existing symbols changed or removed

    Triaged by Claude Code. Session: https://claude.ai/code/session_01ESj4BDECaB5A3UBPyFYiev


    Generated by Claude Code

  3. added
    bugSomething isn't working
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 24, 2026
  4. KonstantinMirin commented on Aug 24, 2026

    @KonstantinMirin
    CollaboratorAuthor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions