pydantic/pydantic

Can another program use it through a documented, machine-readable surface?

library ladder · level 4

• ✓ L1 An importable, packaged API exists. pyproject.toml Python package pydanticpydantic-core/src/lib.rs Rust library crate
• ✓ L2 The public API is delimited (__all__, an exports map, exported identifiers). pydantic/__init__.py __all__pydantic-core/src/lib.rs pub items
• ✓ L3 The public API is statically typed (py.typed, type declarations, a typed language). pydantic-core/python/pydantic_core/py.typed py.typedpydantic/py.typed py.typed
• ✓ L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). mkdocs.yml 1 matchpyproject.toml 1 match

Can integrators rely on it not changing under them?

• next: L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. (removed without prior deprecation: symbol AmqpDsn (removed in v2.13.0b1), symbol AnyHttpUrl (removed in v2.13.0b1), symbol CockroachDsn (removed in v2.13.0b1))

all ladder · level 3

• ✓ L1 Releases are versioned (semver tags or versioned changelog sections). 196 semver tags, latest v2.14.1
• ✓ L2 A changelog exists and marks breaking changes. HISTORY.md marks breaking changes
• ✓ L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. pydantic-core/python/pydantic_core/core_schema.py 25 matchespydantic/main.py 20 matches
• ✗ L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. removed without prior deprecation: symbol AmqpDsn (removed in v2.13.0b1), symbol AnyHttpUrl (removed in v2.13.0b1), symbol CockroachDsn (removed in v2.13.0b1)

Can others react to state changes without polling?

Can a machine act with its own revocable, least-privilege identity?

Can its data get in and out, in bulk, in open formats, with an explicit schema?

• next: L1 The data schema is explicit (migrations, DDL, schema files). (no migrations or schema files)

all ladder · level 0

• ✗ L1 The data schema is explicit (migrations, DDL, schema files). no migrations or schema files
• ✗ L2 An export exists (endpoint or command, not only the UI). no export
• ✗ L3 A bulk export in an open format, and a bulk import. no open export format
• ✗ L4 The export format is documented and the round trip is tested. the export format isn't documented

Can an automated caller use it without guessing, and recover from failure?

• next: L1 Errors are specific exception types, and library code never calls sys.exit. (library code exits the process: .github/actions/people/people.py)

library ladder · level 0

• ✗ L1 Errors are specific exception types, and library code never calls sys.exit. library code exits the process: .github/actions/people/people.py
• ✓ L2 Inputs are validated with messages naming the bad argument. pydantic/_internal/_validators.py 43 matchespydantic/_internal/_generate_schema.py 25 matches
• ✗ L3 Timeouts and retries are configurable. no retry parameter
• ✗ L4 Agent docs, and examples that run as tests (doctests). no agent docs

Can another system run and compose it without a human?

library ladder · level 4

• ✓ L1 Importable from source. pyproject.toml Python package pydanticpydantic-core/src/lib.rs Rust library crate
• ✓ L2 Installable as a package (a package manifest). pyproject.toml package manifestpydantic-core/src/lib.rs package manifest
• ✓ L3 Published to a public registry, with at most 10 runtime dependencies. .github/workflows/ci.yml 2 matches 1 runtime dependencies
• ✓ L4 Optional features behind extras/features. pyproject.toml 1 match

Can behaviour be added without modifying the code?

• next: L1 Internal seams: a registry, registration function or plugin manager. (no registry or registration function)

all ladder · level 0

• ✗ L1 Internal seams: a registry, registration function or plugin manager. no registry or registration function
• ✗ L2 The docs show how to add behaviour through those seams (even in-tree). no registration functions to document
• ✗ L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. extensions must be added inside the package
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. the extension API isn't versioned

Can an operator, or an orchestrating agent, tell whether it works and why not?

• next: L1 Logs through a standard logger namespace and never prints from library code. (no standard logger)

library ladder · level 0

• ✗ L1 Logs through a standard logger namespace and never prints from library code. no standard logger
• ✓ L2 Log levels are used meaningfully (at least two levels). levels: error, info
• ✗ L3 Optional metrics or tracing hooks. no metrics or tracing hooks
• ✗ L4 OpenTelemetry instrumentation available. no OpenTelemetry instrumentation

Can an agent change it safely with limited context?

• next: L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. (59% of modules fit 32k tokens; 10 files over 12k)

all ladder · level 2

• ✓ L1 A README and some tests. README.mdpydantic-core/tests/benchmarks/complete_schema.py 339 test files
• ✓ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). .github/workflows/ci.yml.github/workflows/codspeed.yml
• ✗ L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. 59% of modules fit 32k tokens; 10 files over 12k
• ✗ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). 3 import cycles (largest: pydantic/_internal/_config.py, pydantic/_internal/_dataclasses.py, pydantic/_internal/_decorators.py)