Introduce less safe PydanticAdapter

[strawgate]

Right now we have a dataclassadapter and a pydanticadapter but are intended for data classes or base models.

This ensures we can use the class.

For certain use-cases like #250 we may want a less safe option which takes any python type and uses the magic of the Pedantic TypeAdapter to solve our problems for us. (perhaps with special handling for lists).

Let's come up with a plan to do this while keeping the dataclassadapter and pydanticadapter safe to use.

[coderabbitai]

🔗 Similar Issues

Related Issues

• Reconsider PydanticAdapter #140

👤 Suggested Assignees

• strawgate

---

Enable issue planning

_{To enable issue planning, add the following to your .coderabbit.yaml:}

issue_enrichment:
  planning:
    enabled: true

_{You can then request a plan by commenting @coderabbitai plan on any issue.}

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[claude]

Claude finished @strawgate's task in 4m 30s —— View job

---

Analysis Complete

TL;DR

PR #250 already implements the requested feature but has a critical bug. The PR generalizes PydanticAdapter to support any Pydantic-serializable type (not just BaseModel), which is exactly what this issue requests. However, it broke DataclassAdapter by renaming _is_list_model to _needs_wrapping in the base class without updating DataclassAdapter.

Recommendation

Complete and merge PR #250 after fixing the DataclassAdapter bug. This PR already provides the "less safe" PydanticAdapter functionality requested in this issue while keeping DataclassAdapter as the safe, type-constrained option.

Why this is the right approach:

1. Separation of concerns already exists: The codebase has two adapters with different safety levels:

   • DataclassAdapter: Safe, validates that types are dataclasses
   • PydanticAdapter: After PR Generalize PydanticAdapter to support any pydantic-serializable type #250, becomes the "less safe" adapter that accepts any type

2. PR Generalize PydanticAdapter to support any pydantic-serializable type #250 is nearly complete: All the hard work is done—type introspection, wrapping logic, comprehensive tests. It just needs the bug fix.

3. The architecture is sound: Using _needs_wrapping instead of _is_list_model is a better design that correctly handles the expanded type support.

Problems Encountered During Investigation

• The MCP generate_agents_md tool was not available in this environment
• Had to manually investigate the codebase structure

Findings

Current State (main branch)

PydanticAdapter (safe version):

• Type constraint: T = TypeVar("T", bound=BaseModel | Sequence[BaseModel])
• Only accepts Pydantic BaseModel subclasses and lists of BaseModels
• Uses _is_list_model flag to determine wrapping behavior
• Validates input type at initialization

DataclassAdapter (safe version):

• Type constraint: Still uses unbound TypeVar but validates at runtime
• Validates that the inner type is a dataclass using is_dataclass()
• Uses _is_list_model flag for list handling
• Provides safety through runtime validation

PR #250 Changes

What it does:

1. Removes type constraint from PydanticAdapter: T = TypeVar("T") (unbound)
2. Changes parameter type from type[T] to TypeForm[T] to support generic aliases like list[int]
3. Renames _is_list_model → _needs_wrapping in BasePydanticAdapter
4. Adds intelligent type detection via _check_needs_wrapping() and _serializes_to_dict()
5. Supports: BaseModel, dataclass, TypedDict, dict, list, tuple, set, primitives (int, str, datetime, UUID, etc.)

Storage strategy:

• Types that serialize to dicts (BaseModel, dataclass, TypedDict, dict) → stored directly
• Other types (list, tuple, set, primitives) → wrapped in {"items": <value>}

The Bug:

• BasePydanticAdapter changed from using _is_list_model to _needs_wrapping
• DataclassAdapter.__init__() still sets self._is_list_model = ... (line 48)
• DataclassAdapter never sets self._needs_wrapping
• Result: AttributeError: 'DataclassAdapter' object has no attribute '_needs_wrapping'

Test Coverage:

• PR adds comprehensive tests for new types: list[int], tuple, set, datetime, dict[str, int]
• Tests verify wrapping behavior and storage format
• All PydanticAdapter tests pass
• All DataclassAdapter tests fail due to the bug

Code Review Feedback:
CodeRabbit requested one minor improvement:

Consider more accurate type name for error messages. Now that the adapter supports more than BaseModel subclasses, returning "Pydantic model" is slightly misleading.

This is a cosmetic issue and doesn't affect functionality.

Detailed Action Plan

Step 1: Fix DataclassAdapter Bug

File: key-value/key-value-aio/src/key_value/aio/adapters/dataclass/adapter.py

Change required at lines 47-48:

# Current (broken):
origin = get_origin(dataclass_type)
self._is_list_model = origin is not None and isinstance(origin, type) and issubclass(origin, Sequence)

Fix option 1 (Simple rename):

origin = get_origin(dataclass_type)
self._needs_wrapping = origin is not None and isinstance(origin, type) and issubclass(origin, Sequence)

Fix option 2 (Use PydanticAdapter's logic):
Dataclasses always serialize to dicts, so:

origin = get_origin(dataclass_type)
# Dataclasses serialize to dicts, so only sequences need wrapping
self._needs_wrapping = origin is not None and isinstance(origin, type) and issubclass(origin, Sequence)

Both approaches are equivalent for dataclasses since a single dataclass serializes to a dict (no wrapping) and list[dataclass] needs wrapping.

Also update line 51:

# Current:
if self._is_list_model:

# Change to:
if self._needs_wrapping:

Step 2: Apply Same Fix to Sync Version

File: key-value/key-value-sync/src/key_value/sync/code_gen/adapters/dataclass/adapter.py

Apply the same changes (this is the auto-generated sync version).

Step 3: Run Tests

make test

Verify that all DataclassAdapter tests pass.

Step 4: Address CodeRabbit's Cosmetic Suggestion (Optional)

File: key-value/key-value-aio/src/key_value/aio/adapters/pydantic/adapter.py (line 94-96)

Current:

def _get_model_type_name(self) -> str:
    """Return the model type name for error messages."""
    return "Pydantic model"

Suggested improvement:

def _get_model_type_name(self) -> str:
    """Return the model type name for error messages."""
    # Try to get a more specific name from the type adapter
    try:
        return str(self._type_adapter.core_schema.get('type', 'value'))
    except (AttributeError, TypeError):
        return "pydantic-serializable value"

This is truly optional and cosmetic.

Step 5: Update Documentation (Optional)

Consider updating docs/adapters.md to clarify the two adapters' different safety levels:

### PydanticAdapter vs DataclassAdapter

- **PydanticAdapter**: Flexible adapter supporting any pydantic-serializable type. Less type-safe but more versatile.
- **DataclassAdapter**: Type-safe adapter that validates dataclass types at initialization. Safer but limited to dataclasses.

Step 6: Merge PR #250

Once tests pass and code review is addressed, merge the PR.

Related Issues and Pull Requests

Repository	Issue or PR	Relevance
strawgate/py-key-value	Generalize PydanticAdapter to support any pydantic-serializable type (PR #250)	This PR implements the feature requested in issue #252. It removes type constraints from PydanticAdapter, making it work with any Python type that Pydantic can serialize. The PR is nearly complete but has a bug in DataclassAdapter.
strawgate/py-key-value	Related issue #140	CodeRabbit identified this as a related issue (content not examined in detail).

Related Files

Repository	File	Relevance	Key Sections
strawgate/py-key-value	key-value/key-value-aio/src/key_value/aio/adapters/pydantic/adapter.py	Primary file implementing the generalized PydanticAdapter in PR #250. Contains the type introspection logic that determines whether values need wrapping.	58-72 (wrapping detection), 74-92 (type checking logic)
strawgate/py-key-value	key-value/key-value-aio/src/key_value/aio/adapters/pydantic/base.py	Base class for both PydanticAdapter and DataclassAdapter. PR #250 changed this to use _needs_wrapping instead of _is_list_model.	27 (field declaration), 59 (usage in validation)
strawgate/py-key-value	key-value/key-value-aio/src/key_value/aio/adapters/dataclass/adapter.py	The file with the bug. Still uses _is_list_model instead of _needs_wrapping, causing all DataclassAdapter tests to fail.	48 (bug location), 51 (also needs update)
strawgate/py-key-value	key-value/key-value-aio/tests/adapters/test_pydantic.py	Comprehensive test suite for the generalized PydanticAdapter. Tests new type support including list[int], tuple, set, datetime, dict. All tests pass.	124-128 (list[int] test), 227-262 (tuple, set, datetime, dict tests)
strawgate/py-key-value	docs/adapters.md	Documentation for adapters. Should be updated to clarify the different safety levels of PydanticAdapter vs DataclassAdapter after PR #250 is merged.	N/A

Related Webpages

Name	URL	Relevance
Pydantic TypeAdapter Documentation	https://docs.pydantic.dev/latest/concepts/type_adapter/	Official documentation for Pydantic's TypeAdapter, which is the core technology enabling the generalized PydanticAdapter. TypeAdapter can validate and serialize any Python type that Pydantic supports.
FastMCP Repository	https://github.com/jlowin/fastmcp	The use case mentioned in PR #250. FastMCP's caching middleware needs PydanticAdapter[list[Tool]] and PydanticAdapter[list[Resource]], which requires the generalized PydanticAdapter.

---

[strawgate]

@claude okay let's have 3 adapters, a DataClassAdapter, BaseModelAdapter, and PydanticAdapter please make a PR

[claude]

Claude finished @strawgate's task in 9m 25s —— View job • claude/issue-252-20260101-2147 • Create PR ➔

---

Completed: Create 3 separate adapters (DataClassAdapter, BaseModelAdapter, PydanticAdapter)

Todo List

• Read CLAUDE.md for repo-specific instructions
• Understand current codebase structure
• Design 3-adapter architecture
• Create BaseModelAdapter (safe, BaseModel-only)
• Modify PydanticAdapter (less safe, any pydantic-serializable type)
• Ensure DataclassAdapter remains safe
• Update tests for all adapters
• Update init.py exports
• Generate sync versions with make sync
• Run tests - all adapter tests passing ✅
• Commit and push changes
• Provide PR creation link

---

Summary

Successfully implemented the 3-adapter architecture as requested:

1. DataclassAdapter (safe, dataclass-only)

• Validates dataclass types with is_dataclass()
• Runtime type checking ensures safety
• No changes to existing behavior

2. BaseModelAdapter (new - safe, BaseModel-only)

• Type constraint: T = TypeVar("T", bound=BaseModel | Sequence[BaseModel])
• Safe, type-checked interface for Pydantic BaseModel subclasses
• Split from original PydanticAdapter implementation
• Full test suite included

3. PydanticAdapter (less safe, any pydantic-serializable type)

• Type constraint: T = TypeVar("T") (unbound)
• Accepts any pydantic-serializable type:
  • Pydantic BaseModel instances
  • Dataclasses (standard and Pydantic)
  • TypedDict
  • Primitive types (int, str, float, bool, etc.)
  • Collection types (list, dict, set, tuple, etc.)
  • Datetime and other common types
• Intelligent wrapping: types that serialize to dicts are stored directly, others wrapped in {"items": value}
• Uses _needs_wrapping flag instead of _is_list_model for better semantics

Changes Made

• Created BaseModelAdapter with full implementation and tests
• Modified PydanticAdapter to be the "less safe" version with broad type support
• Updated BasePydanticAdapter base class to use _needs_wrapping instead of _is_list_model
• Updated DataclassAdapter to use new _needs_wrapping flag
• Added comprehensive tests for BaseModelAdapter
• Updated test assertions for new model type names
• Added @bear_spray decorators to handle TypeForm type hints

All adapter tests pass (40/40) ✅

---