Feature Specification: Configurable Belief State Logging

Feature Branch: 006-configurable-belief-logs Created: 2025-12-26 Status: Draft Input: User description: "Меня не устраивает текущее состояния логов проекта, которые я получаю после запуска run.sh. Нужно продумать систему хранения логов, которая будет настраиваемой, включать логирование belief state агента разработки (смотри semantic_protocol.md) и гибко настраиваемой."

Clarifications

Session 2025-12-26

Q: Log rotation policy? → A: Size-based rotation (e.g., 10MB limit, 5 backups).
Q: Belief State disabled behavior? → A: Smart Filter (Suppress Entry/Exit; keep Action/Coherence as standard logs).
Q: Implementation pattern? → A: Context Manager (e.g., with belief_scope("ID"):) to auto-handle Entry/Exit/Error.

User Scenarios & Testing

User Story 1 - Structured Belief State Logging (Priority: P1)

As a developer or AI agent, I want logs to clearly indicate the execution flow and internal state ("Belief State") of the system using a standardized format, so that I can easily debug logic errors and verify semantic coherence.

Why this priority: This is the core requirement to align with the semantic_protocol.md and improve debugging capabilities for the AI agent.

Independent Test: Trigger an action in the system (e.g., running a migration) and verify that the logs contain entries formatted as [ANCHOR_ID][STATE] Message, representing the entry, action, and exit states of the code blocks.

Acceptance Scenarios:

Given a function wrapped with a Belief State logger, When the function is called, Then a log entry [ANCHOR_ID][Entry] ... is generated.
Given a function execution, When the core logic is executed, Then a log entry [ANCHOR_ID][Action] ... is generated.
Given a function execution completes successfully, When it returns, Then a log entry [ANCHOR_ID][Coherence:OK] and [ANCHOR_ID][Exit] are generated.
Given a function execution fails, When an exception is raised, Then a log entry [ANCHOR_ID][Coherence:Failed] is generated.

User Story 2 - Configurable Logging Settings (Priority: P2)

As a user, I want to be able to configure log levels, formats, and destinations via the application settings, so that I can control the verbosity and storage of logs without changing code.

Why this priority: Provides the "flexible" and "customizable" aspect of the requirement, allowing users to adapt logging to their needs (dev vs prod).

Independent Test: Change the log level in the settings (e.g., from INFO to DEBUG) and verify that debug messages start appearing in the output.

Acceptance Scenarios:

Given the application is running, When I update the log level to "DEBUG" in the settings, Then debug-level logs are captured and displayed.
Given the application is running, When I enable "File Logging" in settings, Then logs are written to the specified file path.
Given the application is running, When I disable "Belief State" logs in settings, Then "Entry" and "Exit" logs are suppressed, while "Action" and "Coherence" logs are retained as standard log entries.

Edge Cases

Invalid Configuration: What happens if the user provides an invalid log level (e.g., "SUPER_LOUD")? The system should fallback to a safe default (e.g., "INFO") and log a warning.
File System Errors: What happens if the configured log file path is not writable? The system should fallback to console logging and alert the user.
High Volume: What happens if "Belief State" logging generates too much noise? The system should remain performant, and users should be able to toggle it off easily.

Requirements

Functional Requirements

FR-001: The system MUST support a LoggingConfig structure within the global configuration to store settings for level, format, file path, and belief state enablement.
FR-002: The logging system MUST implement a standard format for "Belief State" logs as defined in the system protocols: [{ANCHOR_ID}][{STATE}] {Message}.
FR-003: The system MUST provide a standard mechanism to easily generate Belief State logs without repetitive boilerplate code, specifically using a Context Manager pattern.
FR-004: The supported Belief States MUST include: Entry, Action, Coherence:OK, Coherence:Failed, Exit.
FR-005: The system MUST allow dynamic reconfiguration of the logger (e.g., changing levels) when settings are updated.
FR-006: The real-time log stream MUST preserve the structured format of Belief State logs so the frontend can potentially render them specially.
FR-007: Logs MUST optionally be persisted to a file if configured.
FR-008: The file logging system MUST implement size-based rotation (default: 10MB limit, 5 backups) to prevent disk saturation.
FR-009: When enable_belief_state is False, the logger MUST suppress Entry and Exit states but retain Action and Coherence states (stripping the structured prefix if necessary or keeping it as standard info).
FR-010: The Context Manager MUST automatically log [Entry] on start, [Exit] on success, and [Coherence:Failed] if an exception occurs (re-raising the exception).

Key Entities

LoggingConfig: A configuration object defining level (text), file_path (text), format (structure), enable_belief_state (boolean).
BeliefStateAdapter: A component that enforces the semantic protocol format for log entries.

Success Criteria

Measurable Outcomes

SC-001: Developers can trace the execution flow of a specific task using only the [ANCHOR_ID] filtered logs.
SC-002: Changing the log level in the configuration file or API immediately (or upon restart) reflects in the log output.
SC-003: All "Belief State" logs strictly follow the [ID][State] format, allowing for regex parsing.
SC-004: System supports logging to both console and file simultaneously if configured.

Assumptions

The existing real-time streaming mechanism can be adapted or chained with the new logging configuration.
The system protocol definition of states is the source of truth.

6.3 KiB Raw Permalink Blame History