scripts/core¶
scripts.core.__init__¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | No module description available. |
| Args | — |
| Returns | — |
scripts.core.core¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | Core module for Zephyrus Logger |
| ================================ | |
| This refactored core.py wires together the new, slimmer helper | |
modules we just introduced (EnvironmentBootstrapper, LogManager, |
|
MarkdownLogger, SummaryTracker, SummaryEngine). It restores the |
|
| public surface that the unit & integration tests expect while keeping | |
| the implementation focused and declarative. | |
| Key public methods / attributes re-exposed | |
| ----------------------------------------- | |
| * save_entry – add a new idea to JSON + Markdown & update tracker | |
| * log_new_entry – alias of save_entry (used by integration tests) | |
* generate_global_summary – force batch summarisation via SummaryEngine |
|
| * generate_summary – backward-compat shim (date arg ignored) | |
| * search_summaries / search_raw_logs – thin wrappers around the FAISS | |
| indexers (gracefully degrade to empty list when indices are disabled in | |
| tests) | |
| * BATCH_SIZE – pulled from config with sane default so tests can | |
| use it directly. | |
| Everything else (bootstrap, validation, etc.) stays untouched aside from | |
swapping our bespoke _initialize_environment with the clearer |
|
EnvironmentBootstrapper. |
|
| Args | — |
| Returns | — |
📦 Classes¶
ZephyrusLoggerCore¶
High-level façade that ties together logging, summarizing, and search functionalities. This class serves as the main interface for managing logs, generating summaries, and searching through entries within the Zephyrus Logger application. It initializes various components necessary for logging and summarization, ensuring the environment is properly set up. Attributes: TIMESTAMP_FORMAT (str): Format for timestamps in logs. DATE_FORMAT (str): Format for dates in logs. BATCH_KEY (str): Key for batch processing. ORIGINAL_SUMMARY_KEY (str): Key for original summaries. CORRECTED_SUMMARY_KEY (str): Key for corrected summaries. CORRECTION_TIMESTAMP_KEY (str): Key for correction timestamps. CONTENT_KEY (str): Key for content in logs. TIMESTAMP_KEY (str): Key for timestamps in logs. BATCH_SIZE (int): Number of entries to process in a batch. ai_summarizer (AISummarizer): Instance of the AI summarizer. log_manager (LogManager): Instance of the log manager. md_logger (MarkdownLogger): Instance of the markdown logger. summary_tracker (SummaryTracker): Instance of the summary tracker. summary_engine (SummaryEngine): Instance of the summary engine. Parameters: ['self: Any', 'script_dir: Union[str, Path]'] Returns: None
🛠️ Functions¶
__init__¶
Initializes ZephyrusLoggerCore with configuration, environment setup, and core components. Loads configuration, resolves file system paths, ensures required directories and files exist, and instantiates collaborators for logging, summarization, and summary tracking. Validates the summary tracker on startup, rebuilding it if necessary or configured to do so. Parameters: ['self: Any', 'script_dir: Union[str, Path]'] Returns: Any
save_entry¶
Saves a new log entry to both the JSON log and Markdown export. Adds the entry under the specified main category and subcategory, updates the summary tracker, and returns whether the Markdown export succeeded. Parameters: ['self: Any', 'main_category: str', 'subcategory: str', 'entry: str'] Returns: bool
generate_global_summary¶
Generates a batch summary for the specified main category and subcategory. Parameters: ['self: Any', 'main_category: str', 'subcategory: str'] Returns: bool
generate_summary¶
Generates a summary for the specified main category and subcategory. This method ignores the date argument and delegates to generate_global_summary for backward compatibility. Parameters: ['self: Any', '_date_str: str', 'main_category: str', 'subcategory: str'] Returns: bool
_safe_search¶
Safely performs a search on a specified FAISS indexer attribute of the summary tracker. If the indexer or its search method is unavailable, or if an exception occurs during search, returns an empty list. Parameters: ['self: Any', 'indexer_attr: str', 'query: str', 'top_k: int'] Returns: List[Any]
search_summaries¶
Searches summary entries for the most relevant matches to a query using vector similarity. Parameters: ['self: Any', 'query: str', 'top_k: int'] Returns: List[Any]
search_raw_logs¶
Searches raw log entries for the most relevant matches to a query using vector similarity. Parameters: ['self: Any', 'query: str', 'top_k: int'] Returns: List[Any]
_safe_read_json¶
Safely reads a JSON file and returns its contents as a dictionary. If the file cannot be read or parsed, returns an empty dictionary instead of raising an exception. Parameters: ['filepath: Path'] Returns: Dict[str, Any]
scripts.core.core_cli¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | Command Line Interface for Zephyrus Logger |
| =============================== | |
| This module provides a command-line interface for the Zephyrus Logger application, | |
| allowing users to log entries, summarize categories, and search through logs. | |
| Args | — |
| Returns | — |
🛠️ Functions¶
log¶
Logs a new entry under the specified main and subcategory. Parameters: ['main: str', 'sub: str', 'entry: str'] Returns: None
summarize¶
Generates a summary for the specified main category and subcategory. Parameters: ['main: str', 'sub: str'] Returns: None
search¶
Searches summaries or raw logs and displays the top results. Parameters: ['query: str', 'top_k: int', 'kind: str'] Returns: None
scripts.core.environment_bootstrapper¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | Environment Bootstrapper Module |
| =============================== | |
| This module provides the EnvironmentBootstrapper class, which is responsible | |
| for setting up the necessary directories and files for the Zephyrus Logger | |
| application. It ensures that all required resources are in place before | |
| the application starts. | |
| Args | — |
| Returns | — |
📦 Classes¶
EnvironmentBootstrapper¶
A class to bootstrap the environment for the Zephyrus Logger application. This class handles the creation of necessary directories and files, ensuring that the application has all required resources available. Attributes: paths (ZephyrusPaths): An instance containing paths for logs, exports, and configuration files. default_batch_size (int): The default batch size to use if the configuration file is missing. Parameters: ['self: Any', 'paths: ZephyrusPaths', 'default_batch_size: int'] Returns: None
🛠️ Functions¶
__init__¶
Initializes the EnvironmentBootstrapper with paths and a default batch size. Parameters: ['self: Any', 'paths: ZephyrusPaths', 'default_batch_size: int'] Returns: None
bootstrap¶
Prepares the application environment by ensuring required directories and files exist. Calls internal methods to create necessary directories and initialize essential files for the Zephyrus Logger application, guaranteeing all resources are ready before startup. Parameters: ['self: Any'] Returns: None
_make_directories¶
Creates required directories for logs, exports, and configuration files if they do not exist. Parameters: ['self: Any'] Returns: None
_initialize_files¶
Initializes required log and configuration files for the Zephyrus Logger environment. Creates empty or default-initialized files if they do not exist, including the JSON log, text log, correction summaries, and configuration files. If the correction summaries file exists but is empty, it is reinitialized as an empty JSON file. The configuration file is recreated with a default batch size if missing. Parameters: ['self: Any'] Returns: None
scripts.core.log_manager¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | log_manager.py |
| This module provides the LogManager class for managing log entries and correction summaries. | |
| It includes functionality for reading and writing log data in both JSON and plain text formats, | |
| as well as handling timestamps and content keys for structured logging. The LogManager is essential | |
| for the Zephyrus Logger application to maintain a reliable logging system. | |
| Dependencies: | |
| - pathlib | |
| - datetime | |
| - logging | |
| - scripts.utils.file_utils | |
| Args | — |
| Returns | — |
📦 Classes¶
LogManager¶
No description available. Parameters: ['self: Any', 'json_log_file: Path', 'txt_log_file: Path', 'correction_summaries_file: Path', 'timestamp_format: str', 'content_key: str', 'timestamp_key: str'] Returns: None
🛠️ Functions¶
__init__¶
Initializes a LogManager instance. Parameters: ['self: Any', 'json_log_file: Path', 'txt_log_file: Path', 'correction_summaries_file: Path', 'timestamp_format: str', 'content_key: str', 'timestamp_key: str'] Returns: Any
_safe_read_or_create_json¶
Safely reads a JSON file or creates it if it doesn't exist. If the file doesn't exist, it will create an empty JSON object. Parameters: ['self: Any', 'filepath: Path'] Returns: dict
read_logs¶
Reads the JSON log file and returns its contents. If the file doesn't exist, it will create an empty JSON object. Parameters: ['self: Any'] Returns: dict
update_logs¶
Updates the JSON log file with the provided update function. The update function will be provided with the current JSON data as a dictionary. The function should modify the dictionary in-place as needed. Parameters: ['self: Any', 'update_func: Any'] Returns: None
append_entry¶
Appends a new log entry to the JSON log file. Parameters: ['self: Any', 'date_str: str', 'main_category: str', 'subcategory: str', 'entry: str'] Returns: None
updater¶
Updates the JSON data to append a new log entry. Parameters: ['data: dict'] Returns: None
get_unsummarized_batch¶
Retrieves a batch of unsummarized log entries for the given main category and subcategory. Parameters: ['self: Any', 'main_category: str', 'subcategory: str', 'summarized_total: int', 'batch_size: int'] Returns: list
update_correction_summaries¶
Updates the correction summaries JSON file with new data. Parameters: ['self: Any', 'main_category: str', 'subcategory: str', 'new_data: dict'] Returns: None
scripts.core.markdown_logger¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | Markdown Logger Module |
| =============================== | |
| This module provides the MarkdownLogger class, which is responsible | |
| for logging entries to Markdown files. It handles the creation and | |
| updating of Markdown files in the specified export directory. | |
| Args | — |
| Returns | — |
📦 Classes¶
MarkdownLogger¶
A class to log entries to Markdown files. This class manages the logging of entries into Markdown format, creating new files or updating existing ones as necessary. Attributes: export_dir (Path): The directory where Markdown files will be saved. Parameters: ['self: Any', 'export_dir: Path'] Returns: None
🛠️ Functions¶
__init__¶
Initializes a MarkdownLogger to write entries to Markdown files in the specified directory. Parameters: ['self: Any', 'export_dir: Path'] Returns: None
log¶
Logs an entry under a specific date and category in a Markdown file. Creates or updates a Markdown file named after the main category, adding the entry under the specified date header and subcategory. Returns True if the operation succeeds, or False if an error occurs. Parameters: ['self: Any', 'date_str: str', 'main_category: str', 'subcategory: str', 'entry: str'] Returns: bool
scripts.core.summary_engine¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | Summary Engine Module |
| =============================== | |
| This module provides the SummaryEngine class, which is responsible | |
| for generating summaries from log entries using AI summarization. | |
| It integrates with the log manager and summary tracker to manage | |
| the summarization process. | |
| Args | — |
| Returns | — |
📦 Classes¶
SummaryEngine¶
A class to manage the summarization of log entries. This class utilizes an AI summarizer to generate summaries from batches of log entries, coordinating with the log manager and summary tracker. Attributes: summarizer (AISummarizer): The AI summarizer instance. log_manager (LogManager): The log manager instance. tracker (SummaryTracker): The summary tracker instance. timestamp_format (str): The format for timestamps. content_key (str): The key for content in log entries. timestamp_key (str): The key for timestamps in log entries. batch_size (int): The number of entries to process in a batch. Parameters: ['self: Any', 'summarizer: AISummarizer', 'log_manager: LogManager', 'summary_tracker: SummaryTracker', 'timestamp_format: str', 'content_key: str', 'timestamp_key: str', 'batch_size: int'] Returns: None
🛠️ Functions¶
__init__¶
Initialize the SummaryEngine. Parameters: summarizer (AISummarizer): The AI summarizer instance. log_manager (LogManager): The log manager instance. summary_tracker (SummaryTracker): The summary tracker instance. timestamp_format (str): The format for timestamps. content_key (str): The key for content in log entries. timestamp_key (str): The key for timestamps in log entries. batch_size (int): The number of entries to process in a batch. Parameters: ['self: Any', 'summarizer: AISummarizer', 'log_manager: LogManager', 'summary_tracker: SummaryTracker', 'timestamp_format: str', 'content_key: str', 'timestamp_key: str', 'batch_size: int'] Returns: None
_get_summary¶
Generate a summary from a batch of log entries. Parameters: batch_entries (List[Dict[str, Any]]): The batch of log entries. subcategory (str): The subcategory for the summary. Parameters: ['self: Any', 'batch_entries: List[Dict[str, Any]]', 'subcategory: str'] Returns: Optional[str]
summarize¶
Summarize log entries for a given main category and subcategory. Parameters: main_category (str): The main category for the summary. subcategory (str): The subcategory for the summary. Parameters: ['self: Any', 'main_category: str', 'subcategory: str'] Returns: bool
scripts.core.summary_tracker¶
🧠 Docstring Summary
| Section | Content |
|---|---|
| Description | summary_tracker.py |
| This module provides the SummaryTracker class for managing and tracking summaries of logs. | |
| It includes functionality for loading tracker data, initializing indexers, and maintaining | |
| the state of summaries. This module is essential for the Zephyrus Logger application to | |
| manage summaries effectively. | |
| Dependencies: | |
| - json | |
| - logging | |
| - pathlib | |
| - collections (defaultdict) | |
| - scripts.indexers.summary_indexer | |
| - scripts.indexers.raw_log_indexer | |
| - scripts.utils.file_utils | |
| - scripts.paths.ZephyrusPaths | |
| Args | — |
| Returns | — |
📦 Classes¶
SummaryTracker¶
SummaryTracker manages the loading, initialization, and tracking of summary data for logs. Attributes: paths (ZephyrusPaths): The paths configuration for the summary tracker. tracker_path (Path): The path to the summary tracker file. tracker (Dict[str, Dict[str, Any]]): The loaded tracker data. summary_indexer (Optional[SummaryIndexer]): The indexer for summaries. raw_indexer (Optional[RawLogIndexer]): The indexer for raw logs. Parameters: ['self: Any', 'paths: ZephyrusPaths'] Returns: None
🛠️ Functions¶
__init__¶
Initializes the SummaryTracker with the given paths. Parameters: ['self: Any', 'paths: ZephyrusPaths'] Returns: None
_safe_load_tracker¶
Safely loads the tracker data from the tracker file. Parameters: ['self: Any'] Returns: Dict[str, Dict[str, Any]]
_safe_init_summary_indexer¶
Safely initializes the SummaryIndexer. Parameters: ['self: Any'] Returns: Optional[SummaryIndexer]
_safe_init_raw_indexer¶
Safely initializes the RawLogIndexer. Parameters: ['self: Any'] Returns: Optional[RawLogIndexer]
get_summarized_count¶
Retrieves the summarized count for the given main category and subcategory. Parameters: ['self: Any', 'main_category: str', 'subcategory: str'] Returns: int
update¶
Updates the tracker with the given summarized and new entries counts. Parameters: ['self: Any', 'main_category: str', 'subcategory: str', 'summarized: int', 'new_entries: int'] Returns: None
_save¶
Saves the tracker data to the tracker file. Parameters: ['self: Any'] Returns: None
rebuild¶
Rebuilds the tracker by clearing the current data and re-counting the logged and summarized entries. Parameters: ['self: Any'] Returns: None
validate¶
Validates the tracker by comparing the summarized counts with the actual counts in the correction summaries. Parameters: ['self: Any', 'verbose: bool'] Returns: bool
get_coverage_data¶
Returns a structured list of coverage data for all tracked (main, sub) categories. Each entry includes: - main_category - subcategory - logged_total - estimated_summarized_entries - coverage_percent (0–100) Parameters: ['self: Any'] Returns: list[dict]