pyproject.toml

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "adcp"
version = "5.2.0"
description = "Official Python client for the Ad Context Protocol (AdCP)"
authors = [
    {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
]
readme = "README.md"
requires-python = ">=3.10"
license = {text = "Apache-2.0"}
keywords = ["adcp", "mcp", "a2a", "protocol", "advertising"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: Apache Software License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

dependencies = [
    "httpx>=0.24.0",
    # httpcore is a transitive dep of httpx, but we import from it
    # directly (``adcp.signing.ip_pinned_transport`` subclasses
    # ``SyncBackend`` / ``AnyIOBackend`` from ``httpcore._backends.*``).
    # Pin the major so a breaking upgrade fails at install rather than
    # at runtime. The contract test in
    # ``tests/conformance/signing/test_ip_pinned_transport_contract.py``
    # guards the specific API shapes we rely on.
    "httpcore>=1.0,<2.0",
    # Upper bound is load-bearing for ``adcp.types.error_narrowing``,
    # which depends on pydantic-2 ValidationError.errors() internals
    # (``err[\"type\"]`` literals like ``\"literal_error\"`` /
    # ``\"union_tag_not_found\"`` and CamelCase variant names interleaved
    # in ``err[\"loc\"]``). Pydantic 3 has no API guarantee on these
    # internals; bump only after porting the narrowing heuristics.
    "pydantic>=2.0.0,<3",
    "typing-extensions>=4.5.0",
    # A2A protocol v1.0 (protobuf types, ProtoJSON on the wire). We run
    # on the v1.0 Python SDK with ``enable_v0_3_compat=True`` on the
    # server-side JSON-RPC route factory, which dual-serves the AgentCard
    # and preserves 0.3 JSON shapes outbound for existing 0.3 clients.
    # No coordinated buyer migration needed.
    # Upper bound: 1.0.2 reads ``field.label`` on the upb FieldDescriptor,
    # which protobuf 7.x no longer exposes — every A2A ``message/send``
    # decorator (``@validate_proto_required_fields``) blows up with
    # ``'_upb._message.FieldDescriptor' object has no attribute 'label'``.
    # Lower bound: 1.0.1 reads ``field.is_repeated`` on the same descriptor,
    # which protobuf 5.x doesn't expose — same decorator, mirror failure
    # mode (``no attribute 'is_repeated'``). The protobuf floor below
    # closes the 5.x cell so this pin is safe.
    "a2a-sdk>=1.0.1,<1.0.2",
    # Floor coupled to ``a2a-sdk`` above. a2a-sdk 1.0.1 reads
    # ``field.is_repeated`` on the upb FieldDescriptor inside
    # ``@validate_proto_required_fields`` — the attribute exists on the
    # upb extension only from protobuf 6.x onward. With protobuf 5.x
    # adopters land in a broken cell where every ``message/send`` raises
    # ``AttributeError`` before any handler runs. Direct constraint here
    # rather than relying on a2a-sdk's transitive pin (which is wider).
    "protobuf>=6,<8",
    "sse-starlette>=2.0",  # required by a2a-sdk v0.3 compat adapter
    # 1.27.0 added ``session_idle_timeout`` to ``StreamableHTTPSessionManager``
    # which we pass when adopters opt into stateful streamable-http. Upper
    # bound at <2.0 because ``adcp.server.serve.create_mcp_server`` reads
    # FastMCP private attrs (``_mcp_server``, ``_event_store``,
    # ``_retry_interval``) when pre-creating the session manager — that
    # contract is not preserved across majors, and upstream signaled v2
    # development on ``main`` (v1.x maintenance branch only ports critical
    # fixes). Bump deliberately when v2 lands.
    "mcp>=1.27.0,<2.0",
    "email-validator>=2.0.0",
    "cryptography>=41.0.0",
    # RFC 8785 JSON Canonicalization Scheme — used by the server-side
    # idempotency middleware to compute the spec-mandated payload hash for
    # replay detection. Tiny pure-Python dep, no transitive weight.
    "rfc8785>=0.1.4",
    # JSON Schema validation — backs adcp.validation.schema_validator for
    # pre-send request / post-receive response drift detection against the
    # bundled AdCP schemas. Pin to the Draft 7 generation the schemas
    # declare via ``$schema``.
    "jsonschema>=4.0.0",
]

[project.scripts]
adcp = "adcp.__main__:main"
adcp-keygen = "adcp.signing.keygen:main"

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "pytest-asyncio>=0.21.0",
    "pytest-cov>=4.0.0",
    "mypy>=1.20.0,<1.21",
    "black>=23.0.0",
    "ruff>=0.1.0",
    # Pin to exact version: codegen's variant numbering (e.g. CreateMediaBuyResponse1 vs
    # CreateMediaBuyResponse) shifts between versions, producing diff churn and breaking
    # generated-code imports that reference specific suffixes.
    "datamodel-code-generator[http]==0.56.1",
    # Runs Starlette app lifespan under httpx.ASGITransport in tests —
    # the canonical library for what httpx doesn't do natively. Used by
    # tests/test_mcp_middleware_composition.py and future integration
    # tests that exercise the streamable-HTTP ASGI app in-process.
    "asgi-lifespan>=2.1.0",
    # mypy stubs for the protobuf runtime we use via a2a-sdk 1.0
    # (``google.protobuf.json_format``, ``struct_pb2``, ``timestamp_pb2``).
    # Without these mypy flags every import as ``import-untyped``.
    "types-protobuf>=7.34.1.20260408",
    # Mocks httpx in the v3 reference seller's translator-pattern tests
    # so we don't need to boot the JS mock-server in the Python pytest
    # CI run.
    "respx>=0.20.0",
]
docs = [
    "pdoc3>=0.10.0",
]
pg = [
    # PostgreSQL-backed adcp.signing.PgReplayStore,
    # adcp.decisioning.PostgresTaskRegistry (durable HITL task state), and
    # future PgIdempotencyBackend. psycopg3 ships both sync + async pool
    # interfaces so the single dep serves all three use cases.
    "psycopg[binary]>=3.1.0",
    "psycopg-pool>=3.2.0",
]

[project.urls]
Homepage = "https://github.com/adcontextprotocol/adcp-client-python"
Documentation = "https://docs.adcontextprotocol.org"
Repository = "https://github.com/adcontextprotocol/adcp-client-python"
Issues = "https://github.com/adcontextprotocol/adcp-client-python/issues"

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-data]
adcp = [
    "py.typed",
    "ADCP_VERSION",
    "signing/pg/*.sql",
    "decisioning/pg/*.sql",
    # AdCP JSON schemas, mirrored from ``schemas/cache/`` by
    # ``scripts/bundle_schemas.py`` so the wheel ships them for
    # ``adcp.validation.schema_loader``.
    "_schemas/**/*.json",
]
# Named schemas bundled directly with the SDK (committed, not generated).
# These live in src/adcp/schemas/ and are loaded via adcp.schemas.load_schema.
"adcp.schemas" = ["*.json"]

[tool.black]
line-length = 100
target-version = ["py310", "py311", "py312"]
# Skip auto-generated files. Running black on generated_poc/ during
# pre-commit after `make regenerate-schemas` causes a stash conflict
# (hook reformats, tries to re-apply over seller's already-modified
# files, rolls back). The regen script already runs black on the
# consolidated _generated.py; individual generated_poc/ files don't
# need formatting at commit time. Mirrors the ruff extend-exclude.
extend-exclude = "/(tasks|_generated|registry)\\.py$|/types/generated_poc/"

[tool.ruff]
line-length = 100
target-version = "py310"
extend-exclude = [
    "src/adcp/types/_generated.py",
    "src/adcp/types/registry.py",
    "src/adcp/types/tasks.py",
    "src/adcp/types/generated_poc/",
    "examples/",
    "scripts/",
]

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]
ignore = [
    "E402",  # Allow imports after module docstrings
    "UP038",  # isinstance() doesn't support X | Y syntax, only type hints do
]

[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_configs = true

[[tool.mypy.overrides]]
module = "tests.*"
disable_error_code = ["import-not-found", "no-untyped-def", "var-annotated", "operator"]

[[tool.mypy.overrides]]
module = "adcp.types.generated_poc.*"
disable_error_code = ["valid-type"]

[[tool.mypy.overrides]]
module = "tests.type_checks.*"
# Re-enable codes silenced by the broader tests.* override above.
# These files are the adopter-pattern contract: every file must pass
# mypy --strict with zero # type: ignore lines.
enable_error_code = ["no-untyped-def", "var-annotated", "operator", "import-not-found"]

[[tool.mypy.overrides]]
module = "tests.integration.*"
ignore_errors = true

# psycopg is an optional dep behind the [pg] extra; type stubs aren't
# guaranteed to be present when the base SDK is installed.
[[tool.mypy.overrides]]
module = ["psycopg", "psycopg.*", "psycopg_pool", "psycopg_pool.*"]
ignore_missing_imports = true

# jsonschema doesn't ship PEP 561 stubs in the default package; the
# ``types-jsonschema`` stub package is optional and we use
# :class:`Any`-typed returns across the validator boundary anyway.
[[tool.mypy.overrides]]
module = ["jsonschema", "jsonschema.*"]
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
markers = [
    "unit: Unit tests that don't require external services",
    "integration: Integration tests that hit real endpoints (may be slow/flaky)",
    "slow: Tests that take significant time to run",
]
# By default, skip integration tests for fast local development
addopts = "-m 'not integration'"

[tool.coverage.run]
source = ["src/adcp"]
omit = [
    "*/tests/*",
    "*/test_*.py",
]
branch = true

[tool.coverage.report]
precision = 2
show_missing = true
skip_covered = false
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise AssertionError",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
    "class .*\\bProtocol\\):",
    "@(abc\\.)?abstractmethod",
]
# Maintain current 86% coverage, fail if it drops below 80%
fail_under = 80

[tool.coverage.html]
directory = "htmlcov"

[tool.bandit]
exclude_dirs = ["tests", "scripts"]
skips = ["B101"]  # Allow assert in code (we're not using -O optimization)

[dependency-groups]
dev = [
    "datamodel-code-generator==0.56.1",
    "pre-commit>=4.4.0",
    "types-protobuf>=7.34.1.20260408",
    # Pinned in the dev group so ``uv run mypy`` (used by the pre-commit
    # hook) installs mypy into the project venv instead of falling
    # through to whatever ``mypy`` happens to be on $PATH (e.g. a
    # homebrew install). Without this, pre-commit's mypy version drifts
    # from CI's, producing a different error count than CI on the same
    # source — and a dead-weight hook that everyone bypasses with
    # ``SKIP=mypy``.
    "mypy>=1.20.0",
]