89 lines
6.3 KiB
Markdown
89 lines
6.3 KiB
Markdown
# 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**:
|
|
|
|
1. **Given** a function wrapped with a Belief State logger, **When** the function is called, **Then** a log entry `[ANCHOR_ID][Entry] ...` is generated.
|
|
2. **Given** a function execution, **When** the core logic is executed, **Then** a log entry `[ANCHOR_ID][Action] ...` is generated.
|
|
3. **Given** a function execution completes successfully, **When** it returns, **Then** a log entry `[ANCHOR_ID][Coherence:OK]` and `[ANCHOR_ID][Exit]` are generated.
|
|
4. **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**:
|
|
|
|
1. **Given** the application is running, **When** I update the log level to "DEBUG" in the settings, **Then** debug-level logs are captured and displayed.
|
|
2. **Given** the application is running, **When** I enable "File Logging" in settings, **Then** logs are written to the specified file path.
|
|
3. **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.
|