Refactor: Decompose session.py into smaller modules #4167

New issue

Closed

opened 2026-04-06 12:15:00 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 12:15:00 +00:00

Owner

The src/cleveragents/domain/models/core/session.py file has been identified as a major violation of the Single Responsibility Principle and the 500-line limit guideline.

Issues:

Mixed Concerns: The file mixes several distinct concerns:
- Data Models: Session, SessionMessage, and SessionTokenUsage.
- Enum: MessageRole.
- Exceptions: SessionServiceError, SessionNotFoundError, SessionExportError, and SessionImportError.
- Service Contract: The SessionService abstract base class.
File Length: The file is over 600 lines long, which makes it extremely difficult to read, understand, and maintain.

Recommendation:

Perform a major refactoring of the session.py file by splitting it into smaller, more focused modules:

Keep the data models in src/cleveragents/domain/models/core/session.py.
Move the MessageRole enum to src/cleveragents/domain/models/core/enums.py.
Move the custom exceptions to a central exceptions module (e.g., src/cleveragents/core/exceptions.py).
Move the SessionService abstract base class to the src/cleveragents/application layer, possibly in a new sessions package, as it defines a service contract.

This refactoring is critical for improving the architecture of the session-related functionality and making the codebase more modular and maintainable.

Automated by CleverAgents Bot
Supervisor: Architecture Guard | Agent: ca-architecture-guard

The `src/cleveragents/domain/models/core/session.py` file has been identified as a major violation of the Single Responsibility Principle and the 500-line limit guideline. **Issues:** 1. **Mixed Concerns:** The file mixes several distinct concerns: * **Data Models:** `Session`, `SessionMessage`, and `SessionTokenUsage`. * **Enum:** `MessageRole`. * **Exceptions:** `SessionServiceError`, `SessionNotFoundError`, `SessionExportError`, and `SessionImportError`. * **Service Contract:** The `SessionService` abstract base class. 2. **File Length:** The file is over 600 lines long, which makes it extremely difficult to read, understand, and maintain. **Recommendation:** Perform a major refactoring of the `session.py` file by splitting it into smaller, more focused modules: * Keep the data models in `src/cleveragents/domain/models/core/session.py`. * Move the `MessageRole` enum to `src/cleveragents/domain/models/core/enums.py`. * Move the custom exceptions to a central exceptions module (e.g., `src/cleveragents/core/exceptions.py`). * Move the `SessionService` abstract base class to the `src/cleveragents/application` layer, possibly in a new `sessions` package, as it defines a service contract. This refactoring is critical for improving the architecture of the session-related functionality and making the codebase more modular and maintainable. --- **Automated by CleverAgents Bot** Supervisor: Architecture Guard | Agent: ca-architecture-guard

freemo referenced this issue

2026-04-06 12:20:37 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 12:23:44 +00:00

freemo referenced this issue

2026-04-06 16:19:03 +00:00

Epic: Code Architecture Cleanup - Single Responsibility Principle Violations #4179

freemo commented

2026-04-06 17:37:15 +00:00

Author

Owner

DUPLICATE: Consolidated into Epic #4179 "Code Architecture Cleanup - Single Responsibility Principle Violations"

This refactoring task for decomposing session.py into smaller modules is part of the broader architectural cleanup effort. All Single Responsibility Principle violation fixes are being tracked collectively in the epic to enable coordinated planning and execution.

Action: Closing as duplicate in favor of Epic #4179

**DUPLICATE**: Consolidated into Epic #4179 "Code Architecture Cleanup - Single Responsibility Principle Violations" This refactoring task for decomposing `session.py` into smaller modules is part of the broader architectural cleanup effort. All Single Responsibility Principle violation fixes are being tracked collectively in the epic to enable coordinated planning and execution. **Action**: Closing as duplicate in favor of Epic #4179

freemo closed this issue

2026-04-06 17:37:18 +00:00