JSONLexicon
A local JSON-based implementation of the Lexicon interface for data persistence.
Overview
The JSONLexicon class provides a lightweight, file-based storage solution using the standard json library. It implements the abstract Lexicon interface to manage Entry and Relation objects with atomic-like updates via file rewrites.
"entries" (indexed by ID) and "relations" (a list of connection objects).
Initialization
__init__(storage_path: str = "codex_data.json")
Initializes the lexicon. If the specified JSON file does not exist, it triggers _initialize_storage() to create a template file.
| Parameter | Type | Default | Description |
|---|---|---|---|
storage_path |
String / Path | "codex_data.json" | The filesystem path where the JSON data will be stored. |
Persistence Methods
save(entry: Entry) -> None
Serializes an Entry dataclass into a JSON-compatible dictionary and saves it. Handles ISO format conversion for datetime objects.
save_relation(relation: Relation) -> None
Appends a new relationship between entries. It includes a safety check to prevent exact duplicate relations from being stored.
Data Retrieval
Methods designed to query the stored entries based on different attributes.
get_by_id(entry_id: str) -> Optional[Entry]
Fetches a single entry by its unique identifier. Returns None if not found.
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: datetime, end: datetime) -> List[Entry]
Returns entries created between the start and end timestamps (inclusive).
Relation Management
get_out_relations(entry_id: str) -> List[Relation]
Retrieves all relations where the given ID is the from_id (outgoing connections).
get_in_relations(entry_id: str) -> List[Relation]
Retrieves all relations where the given ID is the to_id (incoming connections).
Deletion & Integrity
delete(entry_id: str) -> bool
Removes an entry. Note: This method performs a cascade-style cleanup, removing all relations associated with this ID to prevent orphaned links.
delete_relation(from_id, to_id, type) -> bool
Removes a specific relation. If connection_type is omitted, all relations between the two nodes are removed.