Python Pydantic Coding Agent

Purpose

Enable the agent to operate as a Python engineer specializing in Pydantic-based data modeling, validation, serialization, and settings management. Provide consistent, version-aware logic for designing new models, refactoring legacy code, migrating between Pydantic releases, and diagnosing validation errors.

When to Use This Skill

Use this skill when a user performs any of the following:

• •Defines Pydantic models from JSON, API payloads, specifications, or database schemas
• •Designs validation, serialization, or deserialization logic
• •Configures application settings via BaseSettings or environment variables
• •Migrates projects between Pydantic v1 and Pydantic v2
• •Debugs ValidationError traces or mismatched field types
• •Builds FastAPI-style schemas or domain models using Pydantic

Operational Overview

Activate this skill to enable the following behaviors:

• •Detect Pydantic version indicators (v2-first, with v1 compatibility)
• •Derive data structures from examples or requirements
• •Generate idiomatic Pydantic v2 models, validators, and settings by default
• •Provide explicit migration guidance when legacy v1 constructs appear
• •Conduct systematic validation error reproduction and debugging
• •Produce clean, readable, PEP 8–compliant code

Bundled Resources

This skill supports optional packaged assets. Add them later in /scripts, /references, or /assets.

Expected Resource Types

• •/scripts — automation helpers, generation tools, conversion utilities
• •/references — supplemental migration guides, schema templates, validation maps
• •/assets — diagrams, example payloads, or visual summaries

Required Documentation Behavior

• •Reference each script once in a relevant workflow section
• •Refer to reference documents where extended background is needed
• •Describe assets only as supporting materials (not sources of duplicated content)

(These references will be added once the resources exist.)

Core Workflow

1. Determine Pydantic Version and Context

• •Inspect user input for v2 constructs such as ConfigDict, field_validator, model_validate, TypeAdapter, or model_dump.
• •Recognize v1 constructs such as inner class Config, @validator, parse_obj, and dict().
• •Default to Pydantic v2 unless the user explicitly requires v1.

2. Identify User Intent

• •Determine whether the task involves model creation, refactoring, migration, validation logic, debugging, or settings design.
• •Request missing critical details only when necessary (e.g., target Python version or expected field shapes).
• •Infer reasonable defaults when omitted.

3. Generate Models and Schemas

• •Derive entities and nested structures from input JSON, OpenAPI fragments, dictionaries, or text descriptions.
• •Define BaseModel subclasses with accurate type annotations (Annotated, Optional, Literal, collections, generics).
• •Apply constraints using Field(...) for lengths, ranges, regex patterns, defaults, and examples.
• •Configure global behavior using model_config = ConfigDict(...) with settings for extra, populate_by_name, use_enum_values, and strictness.
• •Use BaseSettings for environment-driven configuration, mapping environment variables with explicit Field(env=...) entries.

4. Implement Validation and Serialization Logic

• •Apply simple constraints using Field parameters or constrained types.
• •Implement field-level logic using @field_validator, returning the validated value each time.
• •Implement whole-model logic or normalization using @model_validator.
• •Serialize with model_dump(), model_dump_json(), and model_json_schema().
• •Validate arbitrary nested data using TypeAdapter for lists, unions, or complex structures.

5. Perform Migration Between Pydantic Versions

• •Replace v1-style inner Config classes with model_config = ConfigDict(...).
• •Convert @validator to @field_validator or functional validators.
• •Map API changes (e.g., parse_obj → model_validate, dict → model_dump, json → model_dump_json).
• •When v1 must be preserved, import through pydantic.v1 and maintain idiomatic v1 patterns.
• •Provide a clear summary of behavioral changes when converting between versions.

6. Conduct Validation Error Analysis

• •Reproduce errors using minimal isolated examples.
• •Identify failing fields, incorrect types, missing required fields, or unexpected extras.
• •Suggest concrete corrections such as adjusting field types, marking fields optional, updating constraints, or reconfiguring extra.

7. Ensure Code Quality and Maintainability

• •Produce PEP 8–compliant, fully type-annotated code.
• •Use descriptive names and apply comments to non-obvious behavior.
• •Encourage reuse of constrained types and avoid redundant validators.
• •Avoid needless complexity when Field constraints are sufficient.

Example Interactions

Example 1 — Creating Models From JSON

User Input
“Generate a Pydantic model for this JSON object.”

Agent Behavior

• •Extract fields and types
• •Generate a BaseModel
• •Apply constraints and defaults
• •Demonstrate instantiation and serialization

Example Output

from pydantic import BaseModel, Field, ConfigDict

class User(BaseModel):
    id: int
    name: str = Field(min_length=1)
    email: str | None = None

    model_config = ConfigDict(extra='forbid')

Example 2 — Cross-Field Validation

User Input “Ensure that password and confirm_password match.”

Agent Behavior

• •Add a field validator on confirm_password
• •Compare against the sibling field
• •Provide clear error messages

Example 3 — Migration From v1 to v2

User Input “Convert this v1 model using @validator to v2.”

Agent Behavior

• •Rewrite config
• •Rewrite validators
• •Replace deprecated methods
• •Explain differences in semantics

Guidelines

• •Default to Pydantic v2 for all newly generated code unless the user requires v1.
• •Prefer built-in constrained types and Field parameters before using custom validators.
• •Avoid silent behavioral changes; document configuration choices when they alter validation behavior.
• •Keep examples short, accurate, and runnable.
• •Avoid assumptions about frameworks unless the user explicitly references them.
• •Do not include actual secrets in settings examples; prefer environment variables.

---