Log, LogManager, and Config¶

Overview¶

This module introduces:

A LogManagerConfig class that holds configuration for where and how logs are stored (directory, file naming, capacity, etc.).
A Log class, an immutable record wrapping a dictionary of data.
A LogManager class, which manages collections of Log objects, handles persistence (CSV/JSON), and enforces capacity-based auto-saving.

Contents¶

LogManagerConfig¶

class lionagi.protocols.generic.log.LogManagerConfig¶

A pydantic-based configuration model that defines where logs should be stored, how files are named, and whether auto-saving or clearing is performed on certain conditions.

Attributes¶

persist_dirstr | Path: Base directory to store log files (defaults to "./data/logs").
subfolderstr | None: Optional subdirectory name inside persist_dir.
file_prefixstr | None: An optional prefix for log filenames.
capacityint | None: Maximum number of logs before an auto-dump is triggered (None for no limit).
extensionstr: File extension, must be one of .csv, .json, or .jsonl.
use_timestampbool: If True, timestamps are included in file names.
hash_digitsint | None: Number of random hash digits to include in filenames (None for none).
auto_save_on_exitbool: If True, logs are saved automatically when the Python process exits.
clear_after_dumpbool: If True, logs are cleared from memory after dumping to file.

Validation¶

classmethod _validate_non_negative(value) → int¶: Private class method that ensures that capacity and hash_digits are non-negative integers.

classmethod _ensure_dot_extension(value) → str¶: Private class method that ensures the extension starts with a dot and is one of the supported formats.

Example¶

from lionagi.protocols.generic.log import LogManagerConfig

config = LogManagerConfig(
    persist_dir="logs",
    file_prefix="session",
    capacity=100,
    extension=".csv",
)
print(config)  # => LogManagerConfig(persist_dir='logs', ...)

Log¶

class lionagi.protocols.generic.log.Log(Element)¶

Inherits from: Element

Represents an immutable log entry, wrapping a dictionary of content. Once created or loaded from a dictionary, its data can no longer be modified. This ensures that all logs are preserved in their original state.

Attributes¶

contentdict[str, Any]: The primary content of the log entry, typically an arbitrary dictionary of metadata or snapshot data.

Private Attributes¶

_immutable : bool: Private flag indicating whether this log entry is locked from further changes.

Methods¶

__setattr__(name: str, value: Any) → None¶: Prevents mutation if this log is already marked immutable. Raises AttributeError if a change is attempted.

classmethod from_dict(data: dict[str, Any]) → Log¶: Creates a Log from a dictionary. Marks the new log as immutable.

classmethod create(cls, content: Element | dict) → Log¶: Constructs a new log from either an Element (using its to_dict() method) or a dictionary. If the resulting content is empty, a log entry with an error message is created.

Example¶

from lionagi.protocols.generic.log import Log
from lionagi.protocols.generic.element import Element

class UserSession(Element):
    def __init__(self, session_data):
        super().__init__()
        self.session_data = session_data

session = UserSession({"user": "alice", "action": "login"})
log_entry = Log.create(session)
print(log_entry.content)

LogManager¶

class lionagi.protocols.generic.log.LogManager(Manager)¶

Inherits from: Manager

A manager that stores Log objects in a Pile. It optionally dumps them to files (CSV/JSON) automatically when certain conditions are met (like reaching a capacity limit or application exit).

Attributes¶

logsPile[Log]: The collection of logs being managed.
_configLogManagerConfig: Configuration parameters that control directory, file naming, capacity, and auto-save behavior.

Initialization¶

__init__(*, logs: Any = None, _config: LogManagerConfig = None, **kwargs) → None¶

Initializes a LogManager. If _config is not provided, a new LogManagerConfig is created from additional keyword arguments.

Parameters¶

logsAny: Initial logs, can be a dictionary, list, or existing Pile.
_configLogManagerConfig | None: If None, builds config from remaining kwargs.
**kwargs: Additional arguments passed to LogManagerConfig.

Notes¶

If auto_save_on_exit is True, a dump is automatically performed on interpreter shutdown.

Methods¶

log(log_: Log) → None¶: Adds a log synchronously. If the capacity is reached, triggers a dump() call automatically.

async alog(log_: Log) → None¶: Asynchronous version of log(), also checks capacity for auto-dump.

dump(clear: bool | None = None, persist_path: str | Path | None = None) → None¶: Dumps the logs to a file. If the extension is unsupported, raises a ValueError. Can optionally clear logs from memory afterward.

async adump(clear: bool | None = None, persist_path: str | Path | None = None) → None¶: Async version of dump().

save_at_exit() → None¶: Called at interpreter exit if LogManagerConfig.auto_save_on_exit is True. Attempts to dump logs before shutdown.

classmethod from_config(config: LogManagerConfig, logs: Any = None) → LogManager¶: Creates a new LogManager from a given config object, optionally seeded with logs.

Example¶

from lionagi.protocols.generic.log import Log, LogManager, LogManagerConfig

config = LogManagerConfig(capacity=10, extension=".json")
manager = LogManager.from_config(config)

# Create logs
log_entry = Log.create({"event": "user_signup", "user": "bob"})
manager.log(log_entry)   # add log synchronously

# Dump logs manually
manager.dump()

File Location¶

Source File: lionagi/protocols/generic/log.py