brent.edwards
4f32daa740
CI / lint (pull_request) Successful in 14s
CI / typecheck (pull_request) Successful in 27s
CI / security (pull_request) Successful in 25s
CI / quality (pull_request) Successful in 16s
CI / integration_tests (pull_request) Successful in 5m12s
CI / build (pull_request) Successful in 15s
CI / unit_tests (pull_request) Successful in 33m49s
CI / coverage (pull_request) Successful in 8m30s
CI / docker (pull_request) Successful in 1m16s
89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# Session Domain Model
|
|
|
|
The **Session** domain model represents a persistent conversation thread
|
|
tied to an orchestrator actor. It maintains message history across plans
|
|
and serves as the user's natural-language interface.
|
|
|
|
## Key Classes
|
|
|
|
| Class | Description |
|
|
|-------|-------------|
|
|
| `Session` | Core session model with messages, token tracking, and export |
|
|
| `SessionMessage` | A single message within a session (ULID-identified, sequenced) |
|
|
| `MessageRole` | Enum: `user`, `assistant`, `system`, `tool` |
|
|
| `SessionTokenUsage` | Accumulated input/output token counts and cost |
|
|
|
|
## Source Location
|
|
|
|
```
|
|
src/cleveragents/domain/models/core/session.py
|
|
```
|
|
|
|
## Session Lifecycle
|
|
|
|
1. **Create** -- `Session(session_id=str(ULID()))` with optional `actor_name`
|
|
2. **Append messages** -- `session.append_message(role, content)` auto-sequences
|
|
3. **Query** -- `session.get_messages(limit, offset)` for paginated access
|
|
4. **Export** -- `session.as_export_dict()` produces a checksummed JSON dict
|
|
5. **CLI rendering** -- `session.as_cli_dict()` returns an `OrderedDict` for display
|
|
|
|
## Export Serialization Order
|
|
|
|
The `as_export_dict()` method produces keys in this fixed order:
|
|
|
|
```
|
|
schema_version, session_id, actor_name, namespace, messages,
|
|
linked_plan_ids, automation_level, token_usage, metadata,
|
|
created_at, updated_at, checksum
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
### Behave (BDD unit tests)
|
|
|
|
```bash
|
|
nox -s unit_tests -- features/session_model.feature
|
|
```
|
|
|
|
### Robot Framework (smoke / integration tests)
|
|
|
|
```bash
|
|
nox -s integration_tests -- robot/session_model.robot
|
|
```
|
|
|
|
Or run the Robot suite directly:
|
|
|
|
```bash
|
|
robot --outputdir build/reports/robot robot/session_model.robot
|
|
```
|
|
|
|
### Robot Smoke Suite
|
|
|
|
The Robot smoke suite (`robot/session_model.robot`) validates:
|
|
|
|
- **Session creation** -- default fields (`session_id`, `namespace`, `is_empty`)
|
|
- **Message append ordering** -- auto-sequencing produces `[0, 1, 2, ...]`
|
|
- **Export dict completeness** -- all 12 required keys are present
|
|
- **CLI dict completeness** -- required display keys are present
|
|
- **Export key order** -- keys follow the canonical serialization order
|
|
|
|
The smoke tests delegate to `robot/helper_session_model.py`, which can also
|
|
be invoked standalone:
|
|
|
|
```bash
|
|
python robot/helper_session_model.py create
|
|
python robot/helper_session_model.py append-messages
|
|
python robot/helper_session_model.py export
|
|
python robot/helper_session_model.py cli-dict
|
|
python robot/helper_session_model.py export-key-order
|
|
```
|
|
|
|
### ASV Benchmarks
|
|
|
|
```bash
|
|
nox -s benchmark
|
|
```
|
|
|
|
Benchmark suites in `benchmarks/session_model_bench.py` cover validation
|
|
throughput, append performance, and serialization speed.
|