006 plan ready

specs/006-configurable-belief-logs/data-model.md

@@ -0,0 +1,74 @@
+# Data Model: Configurable Belief State Logging
+
+## 1. Configuration Models
+
+These models extend the existing `ConfigModels` in `backend/src/core/config_models.py`.
+
+### 1.1. LoggingConfig
+
+Defines the configuration for the application's logging system.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `level` | `str` | `"INFO"` | The logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). |
+| `file_path` | `Optional[str]` | `"logs/app.log"` | Path to the log file. If None, file logging is disabled. |
+| `max_bytes` | `int` | `10485760` (10MB) | Maximum size of a log file before rotation. |
+| `backup_count` | `int` | `5` | Number of backup files to keep. |
+| `enable_belief_state` | `bool` | `True` | Whether to enable structured Belief State logging (Entry/Exit). |
+
+```python
+class LoggingConfig(BaseModel):
+    level: str = "INFO"
+    file_path: Optional[str] = "logs/app.log"
+    max_bytes: int = 10 * 1024 * 1024
+    backup_count: int = 5
+    enable_belief_state: bool = True
+```
+
+### 1.2. GlobalSettings (Updated)
+
+Updates the existing `GlobalSettings` to include `LoggingConfig`.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `logging` | `LoggingConfig` | `LoggingConfig()` | The logging configuration object. |
+
+```python
+class GlobalSettings(BaseModel):
+    backup_path: str
+    default_environment_id: Optional[str] = None
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+```
+
+## 2. Logger Entities
+
+These entities are part of the `backend/src/core/logger.py` module.
+
+### 2.1. LogEntry (Existing)
+
+Represents a single log record.
+
+| Field | Type | Description |
+|---|---|---|
+| `timestamp` | `datetime` | UTC timestamp of the log. |
+| `level` | `str` | Log level. |
+| `message` | `str` | Log message. |
+| `context` | `Optional[Dict[str, Any]]` | Additional context data. |
+
+### 2.2. BeliefState (Concept)
+
+Represents the state of execution in the "Belief State" model.
+
+- **Entry**: Entering a logical block.
+- **Action**: Performing a core action within the block.
+- **Coherence**: Verifying the state (OK or Failed).
+- **Exit**: Exiting the logical block.
+
+Format: `[{ANCHOR_ID}][{STATE}] {Message}`
+
+## 3. Relationships
+
+- `AppConfig` contains `GlobalSettings`.
+- `GlobalSettings` contains `LoggingConfig`.
+- `ConfigManager` reads/writes `AppConfig`.
+- `ConfigManager` configures the global `logger` based on `LoggingConfig`.