busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

006 plan ready

Browse Source
This commit is contained in:
busya
2025-12-26 19:36:49 +03:00
parent a43f8fb021
commit d197303b9f
14 changed files with 768 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
specs/006-configurable-belief-logs/checklists/requirements.md Normal file
View File

@@ -0,0 +1,34 @@
# Specification Quality Checklist: Configurable Belief State Logging
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2025-12-26
**Feature**: [specs/006-configurable-belief-logs/spec.md](../spec.md)
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

56
specs/006-configurable-belief-logs/contracts/api.md Normal file
View File

@@ -0,0 +1,56 @@
# API Contract: Settings Update
## PATCH /api/settings/global
Updates the global application settings, including the new logging configuration.
### Request Body
**Content-Type**: `application/json`
```json
{
"backup_path": "string",
"default_environment_id": "string (optional)",
"logging": {
"level": "string (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
"file_path": "string (optional)",
"max_bytes": "integer (default: 10485760)",
"backup_count": "integer (default: 5)",
"enable_belief_state": "boolean (default: true)"
}
}
```
### Response
**Status**: `200 OK`
**Content-Type**: `application/json`
```json
{
"backup_path": "string",
"default_environment_id": "string (optional)",
"logging": {
"level": "string",
"file_path": "string",
"max_bytes": "integer",
"backup_count": "integer",
"enable_belief_state": "boolean"
}
}
```
### Example
**Request**
```json
{
"backup_path": "backups",
"logging": {
"level": "DEBUG",
"file_path": "logs/app.log",
"enable_belief_state": true
}
}

74
specs/006-configurable-belief-logs/data-model.md Normal file
View File

@@ -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`.

81
specs/006-configurable-belief-logs/plan.md Normal file
View File

@@ -0,0 +1,81 @@
# Implementation Plan: Configurable Belief State Logging
**Branch**: `006-configurable-belief-logs` | **Date**: 2025-12-26 | **Spec**: specs/006-configurable-belief-logs/spec.md
**Input**: Feature specification from `/specs/006-configurable-belief-logs/spec.md`
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
## Summary
Implement a configurable logging system with "Belief State" support (Entry, Action, Coherence, Exit).
Approach: Use Python's `logging` module with a custom Context Manager (`belief_scope`) and extend `GlobalSettings` with a `LoggingConfig` model.
## Technical Context
**Language/Version**: Python 3.9+
**Primary Dependencies**: FastAPI (Backend), Pydantic (Config), Svelte (Frontend)
**Storage**: Filesystem (for log files), JSON (for configuration persistence)
**Testing**: pytest (Backend), manual verification (Frontend)
**Target Platform**: Linux server (primary), cross-platform compatible
**Project Type**: Web application (Backend + Frontend)
**Performance Goals**: Low overhead logging (<1ms per log entry), non-blocking for main thread (mostly)
**Constraints**: Must use standard library `logging` where possible; Log rotation to prevent disk overflow
**Scale/Scope**: Configurable log levels and retention policies
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
- **Library-First**: N/A (Core infrastructure)
- **CLI Interface**: N/A (Configured via UI/API/JSON)
- **Test-First**: Will require unit tests for `belief_scope` and config updates.
- **Integration Testing**: Will require testing the settings API.
- **Observability**: This feature *is* the observability enhancement.
## Project Structure
### Documentation (this feature)
```text
specs/[###-feature]/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
### Source Code (repository root)
```text
backend/
├── src/
│ ├── core/
│ │ ├── config_models.py # Add LoggingConfig
│ │ ├── config_manager.py # Update config loading/saving
│ │ └── logger.py # Add belief_scope and configure_logger
│ └── api/
│ └── routes/
│ └── settings.py # Update GlobalSettings endpoint
└── tests/
└── test_logger.py # New tests for logger logic
frontend/
├── src/
│ ├── pages/
│ │ └── Settings.svelte # Add logging UI controls
│ └── lib/
│ └── api.js # Update API calls if needed
```
**Structure Decision**: enhancing existing Backend/Frontend structure.
## Complexity Tracking
> **Fill ONLY if Constitution Check has violations that must be justified**
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

104
specs/006-configurable-belief-logs/quickstart.md Normal file
View File

@@ -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]

109
specs/006-configurable-belief-logs/research.md Normal file
View File

@@ -0,0 +1,109 @@
# Research: Configurable Belief State Logging
## 1. Introduction
This research explores the implementation of a configurable logging system that supports "Belief State" logging (Entry, Action, Coherence, Exit) and allows users to customize log levels, formats, and file persistence.
## 2. Analysis of Existing System
- **Language**: Python 3.9+ (Backend)
- **Framework**: FastAPI (inferred from context, though not explicitly seen in snippets, `uvicorn` mentioned)
- **Logging**: Standard Python `logging` module.
- **Configuration**: Pydantic models (`ConfigModels`) managed by `ConfigManager`, persisting to `config.json`.
- **Current Logger**:
- `backend/src/core/logger.py`:
- Uses `logging.getLogger("superset_tools_app")`
- Has `StreamHandler` (console) and `WebSocketLogHandler` (streaming).
- `WebSocketLogHandler` buffers logs in a `deque`.
## 3. Requirements Analysis
- **Belief State**: Need a structured way to log `[ANCHOR_ID][STATE] Message`.
- **Context Manager**: Need a `with belief_scope("ID"):` pattern.
- **Configuration**: Need to add `LoggingConfig` to `GlobalSettings`.
- **File Logging**: Need `RotatingFileHandler` with size limits.
- **Dynamic Reconfiguration**: Need to update logger handlers/levels when config changes.
## 4. Proposed Solution
### 4.1. Data Model (`LoggingConfig`)
We will add a `LoggingConfig` model to `backend/src/core/config_models.py`:
```python
class LoggingConfig(BaseModel):
level: str = "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
file_path: Optional[str] = "logs/app.log"
max_bytes: int = 10 * 1024 * 1024 # 10MB
backup_count: int = 5
enable_belief_state: bool = True
```
And update `GlobalSettings`:
```python
class GlobalSettings(BaseModel):
backup_path: str
default_environment_id: Optional[str] = None
logging: LoggingConfig = Field(default_factory=LoggingConfig)
```
### 4.2. Context Manager (`belief_scope`)
We will implement a context manager in `backend/src/core/logger.py`:
```python
from contextlib import contextmanager
@contextmanager
def belief_scope(anchor_id: str, message: str = ""):
# ... logic to log [Entry] ...
try:
yield
# ... logic to log [Coherence:OK] and [Exit] ...
except Exception as e:
# ... logic to log [Coherence:Failed] ...
raise
```
### 4.3. Logger Reconfiguration
We will add a `configure_logger(config: LoggingConfig)` function in `backend/src/core/logger.py` that:
1. Sets the logger level.
2. Removes old file handlers.
3. Adds a new `RotatingFileHandler` if `file_path` is set.
4. Updates a global flag for `enable_belief_state`.
`ConfigManager` will call this function whenever settings are updated.
### 4.4. Belief State Filtering
If `enable_belief_state` is False:
- `Entry`/`Exit` logs are skipped.
- `Action`/`Coherence` logs are logged as standard messages (maybe without the `[ANCHOR_ID]` prefix if desired, but retaining it is usually better for consistency).
## 5. Alternatives Considered
- **Alternative A**: Use a separate logger for Belief State.
- *Pros*: Cleaner separation.
- *Cons*: Harder to interleave with standard logs in the same stream/file.
- *Decision*: Rejected. We want a unified log stream.
- **Alternative B**: Use structlog.
- *Pros*: Powerful structured logging.
- *Cons*: Adds a new dependency.
- *Decision*: Rejected. Standard `logging` is sufficient and already used.
## 6. Implementation Steps
1. **Modify `backend/src/core/config_models.py`**: Add `LoggingConfig` and update `GlobalSettings`.
2. **Modify `backend/src/core/logger.py`**:
- Add `configure_logger` function.
- Implement `belief_scope` context manager.
- Implement `RotatingFileHandler`.
3. **Modify `backend/src/core/config_manager.py`**: Call `configure_logger` on init and update.
4. **Frontend**: Update Settings page to allow editing `LoggingConfig`.
## 7. Conclusion
The proposed solution leverages the existing Pydantic/ConfigManager architecture and standard Python logging, minimizing disruption while meeting all requirements.

88
specs/006-configurable-belief-logs/spec.md Normal file
View File

@@ -0,0 +1,88 @@
# 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.

61
specs/006-configurable-belief-logs/tasks.md Normal file
View File

@@ -0,0 +1,61 @@
# Tasks: Configurable Belief State Logging
**Spec**: `specs/006-configurable-belief-logs/spec.md`
**Plan**: `specs/006-configurable-belief-logs/plan.md`
**Status**: Pending
## Phase 1: Setup
*Goal: Initialize project structure for logging.*
- [ ] T001 Ensure logs directory exists at `logs/` (relative to project root)
## Phase 2: Foundational
*Goal: Define data models and infrastructure required for logging configuration.*
- [ ] T002 Define `LoggingConfig` model in `backend/src/core/config_models.py`
- [ ] T003 Update `GlobalSettings` model to include `logging` field in `backend/src/core/config_models.py`
- [ ] T004 Update `ConfigManager` to handle logging configuration persistence in `backend/src/core/config_manager.py`
## Phase 3: User Story 1 - Structured Belief State Logging
*Goal: Implement the core "Belief State" logging logic with context managers.*
*Priority: P1*
**Independent Test**: Run `pytest backend/tests/test_logger.py` and verify `belief_scope` generates `[ID][Entry]`, `[ID][Action]`, and `[ID][Exit]` logs.
- [ ] T005 [US1] Create unit tests for belief state logging in `backend/tests/test_logger.py`
- [ ] T006 [US1] Implement `belief_scope` context manager in `backend/src/core/logger.py`
- [ ] T007 [US1] Implement log formatting and smart filtering (suppress Entry/Exit if disabled) in `backend/src/core/logger.py`
## Phase 4: User Story 2 - Configurable Logging Settings
*Goal: Expose logging configuration to the user via API and UI.*
*Priority: P2*
**Independent Test**: Update settings via API/UI and verify log level changes (e.g., DEBUG logs appear) and file rotation is active.
- [ ] T008 [US2] Implement `configure_logger` function to apply settings (level, file, rotation) in `backend/src/core/logger.py`
- [ ] T009 [US2] Update settings API endpoint to handle `logging` updates in `backend/src/api/routes/settings.py`
- [ ] T010 [P] [US2] Add Logging configuration section (Level, File Path, Enable Belief State) to `frontend/src/pages/Settings.svelte`
## Final Phase: Polish & Cross-Cutting Concerns
*Goal: Verify system stability and cleanup.*
- [ ] T011 Verify log rotation works by generating dummy logs (manual verification)
- [ ] T012 Ensure default configuration provides a sensible out-of-the-box experience
## Dependencies
```mermaid
graph TD
Setup[Phase 1: Setup] --> Foundational[Phase 2: Foundational]
Foundational --> US1[Phase 3: US1 Belief State]
US1 --> US2[Phase 4: US2 Configurable Settings]
US2 --> Polish[Final Phase: Polish]
```
## Parallel Execution Opportunities
- **US2**: Frontend task (T010) can be implemented in parallel with Backend tasks (T008, T009) once the API contract is finalized.
## Implementation Strategy
1. **MVP**: Complete Phase 1, 2, and 3 to enable structured logging for the agent.
2. **Full Feature**: Complete Phase 4 to allow users to control the verbosity and storage.