PydanticLexicon

A persistent storage implementation using Pydantic for validation and JSON for serialization.

Overview

The PydanticLexicon class is an implementation of the Lexicon interface. It provides a robust way to store Entries and Relations in a local JSON file, leveraging Pydantic's BaseModel for automatic data validation and date serialization.

Storage Strategy: Single-file JSON database (codex_pydantic.json) with full schema validation on every read/write operation.

Data Schemas

The following Pydantic models define the structure of the storage:

Schema Name	Description	Fields
`EntrySchema`	Represents a single content entry.	id, title, content, tags, category, timestamps, metadata
`RelationSchema`	Defines a connection between two entries.	from_id, to_id, connection_type, metadata
`CodexStorageSchema`	The root container for the JSON file.	entries (Dict), relations (List)

Lexicon Implementation

save(entry: Entry)

Validates and persists a core Entry dataclass into the JSON storage. Converts the dataclass to a Pydantic model automatically.

get_by_id(entry_id: str) -> Optional[Entry]

Retrieves a specific entry by its unique ID. Returns None if the entry does not exist.

save_relation(relation: Relation)

Stores a new relationship between entries. Prevents duplicate relations by checking existence before writing.

delete(entry_id: str) -> bool

Removes an entry and performs cascade deletion on all associated relations (incoming and outgoing).

get_by_tag(tag: str) -> List[Entry]

Filters and returns all entries that contain the specified tag in their metadata.

get_by_date_range(start, end) -> List[Entry]

Returns entries created within the specified datetime range.

Internal Helpers

These private methods handle the communication between the Core Dataclasses and the Pydantic Storage layer.

_read_data(): Loads the JSON file and parses it through CodexStorageSchema.

_write_data(): Uses model_dump_json() to save the state, ensuring datetime objects are ISO-formatted.

_map_to_core_entry(): Converts a Pydantic EntrySchema back into a domain Entry dataclass.