006 plan ready

specs/006-configurable-belief-logs/quickstart.md

@@ -0,0 +1,104 @@
+# Quickstart: Configurable Belief State Logging
+
+## 1. Configuration
+
+The logging system is configured via the `GlobalSettings` in `config.json` or through the Settings UI.
+
+### 1.1. Default Configuration
+
+```json
+{
+  "environments": [],
+  "settings": {
+    "backup_path": "backups",
+    "logging": {
+      "level": "INFO",
+      "file_path": "logs/app.log",
+      "max_bytes": 10485760,
+      "backup_count": 5,
+      "enable_belief_state": true
+    }
+  }
+}
+```
+
+### 1.2. Changing Log Level
+
+To change the log level to `DEBUG`, update the `logging.level` field in `config.json` or use the API:
+
+```bash
+curl -X PATCH http://localhost:8000/api/settings/global \
+  -H "Content-Type: application/json" \
+  -d '{
+    "backup_path": "backups",
+    "logging": {
+      "level": "DEBUG",
+      "file_path": "logs/app.log",
+      "max_bytes": 10485760,
+      "backup_count": 5,
+      "enable_belief_state": true
+    }
+  }'
+```
+
+## 2. Using Belief State Logging
+
+### 2.1. Basic Usage
+
+Use the `belief_scope` context manager to automatically log Entry, Exit, and Coherence states.
+
+```python
+from backend.src.core.logger import logger, belief_scope
+
+def my_function():
+    with belief_scope("MyFunction"):
+        # Logs: [MyFunction][Entry]
+        
+        logger.info("Doing something important")
+        # Logs: [MyFunction][Action] Doing something important
+        
+        # ... logic ...
+        
+        # Logs: [MyFunction][Coherence:OK]
+        # Logs: [MyFunction][Exit]
+```
+
+### 2.2. Error Handling
+
+If an exception occurs within the scope, it is caught, logged as a failure, and re-raised.
+
+```python
+def failing_function():
+    with belief_scope("FailingFunc"):
+        raise ValueError("Something went wrong")
+        
+    # Logs: [FailingFunc][Entry]
+    # Logs: [FailingFunc][Coherence:Failed] Something went wrong
+    # Re-raises ValueError
+```
+
+### 2.3. Custom Messages
+
+You can provide an optional message to `belief_scope`.
+
+```python
+with belief_scope("DataProcessor", "Processing batch #1"):
+    # Logs: [DataProcessor][Entry] Processing batch #1
+    pass
+```
+
+## 3. Log Output Format
+
+### 3.1. Standard Log
+
+```text
+[2025-12-26 10:00:00,000][INFO][superset_tools_app] System initialized
+```
+
+### 3.2. Belief State Log
+
+```text
+[2025-12-26 10:00:01,000][INFO][superset_tools_app] [MyFunction][Entry]
+[2025-12-26 10:00:01,050][INFO][superset_tools_app] [MyFunction][Action] Processing data
+[2025-12-26 10:00:01,100][INFO][superset_tools_app] [MyFunction][Coherence:OK]
+[2025-12-26 10:00:01,100][INFO][superset_tools_app] [MyFunction][Exit]