forked from cleveragents/cleveragents-core
Jeff
126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# Session Service Contract
|
|
|
|
The `SessionService` is the abstract interface for session management in
|
|
CleverAgents. Implementations handle persistence, ULID generation, and
|
|
lifecycle management for `Session` objects.
|
|
|
|
## Interface
|
|
|
|
```python
|
|
class SessionService(ABC):
|
|
def create(self, actor_name: str | None = None) -> Session: ...
|
|
def get(self, session_id: str) -> Session: ...
|
|
def list(self) -> list[Session]: ...
|
|
def delete(self, session_id: str) -> None: ...
|
|
def append_message(
|
|
self,
|
|
session_id: str,
|
|
role: MessageRole,
|
|
content: str,
|
|
metadata: dict | None = None,
|
|
) -> SessionMessage: ...
|
|
def export_session(self, session_id: str) -> dict: ...
|
|
def import_session(self, data: dict) -> Session: ...
|
|
def update_token_usage(
|
|
self,
|
|
session_id: str,
|
|
input_tokens: int,
|
|
output_tokens: int,
|
|
cost: float,
|
|
) -> None: ...
|
|
```
|
|
|
|
## Methods
|
|
|
|
### create
|
|
|
|
Create a new session with a fresh ULID. Optionally bind to an actor.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-------------|----------------|---------|-------------------------------|
|
|
| `actor_name` | `str \| None` | `None` | Namespaced actor to bind |
|
|
|
|
**Returns**: `Session`
|
|
|
|
### get
|
|
|
|
Retrieve a session by its ULID.
|
|
|
|
**Raises**: `SessionNotFoundError` if not found.
|
|
|
|
### list
|
|
|
|
Return all sessions ordered by creation time.
|
|
|
|
### delete
|
|
|
|
Remove a session by its ULID.
|
|
|
|
**Raises**: `SessionNotFoundError` if not found.
|
|
|
|
### append_message
|
|
|
|
Add a message to a session. The implementation generates a ULID for the
|
|
message and sets the sequence number.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-------------|-------------------|---------|------------------------------|
|
|
| `session_id` | `str` | -- | Target session ULID |
|
|
| `role` | `MessageRole` | -- | Message role |
|
|
| `content` | `str` | -- | Message content |
|
|
| `metadata` | `dict \| None` | `None` | Optional metadata |
|
|
|
|
**Returns**: `SessionMessage`
|
|
**Raises**: `SessionNotFoundError` if session not found.
|
|
|
|
### export_session
|
|
|
|
Export a session as a JSON-serializable dict including a SHA-256 checksum
|
|
for integrity verification.
|
|
|
|
**Raises**: `SessionNotFoundError`, `SessionExportError`
|
|
|
|
### import_session
|
|
|
|
Import a session from an export dict. Validates schema version and
|
|
checksum integrity.
|
|
|
|
**Raises**: `SessionImportError` on schema mismatch or corrupt data.
|
|
|
|
### update_token_usage
|
|
|
|
Increment token usage counters for a session.
|
|
|
|
| Parameter | Type | Description |
|
|
|----------------|---------|--------------------------------|
|
|
| `session_id` | `str` | Target session ULID |
|
|
| `input_tokens` | `int` | Input tokens to add |
|
|
| `output_tokens` | `int` | Output tokens to add |
|
|
| `cost` | `float` | Estimated cost to add (USD) |
|
|
|
|
**Raises**: `SessionNotFoundError` if session not found.
|
|
|
|
## Error Hierarchy
|
|
|
|
```
|
|
Exception
|
|
-> SessionServiceError (base)
|
|
-> SessionNotFoundError (session ID not found)
|
|
-> SessionExportError (export failures)
|
|
-> SessionImportError (import failures)
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
The service backs the following CLI commands:
|
|
|
|
| Command | Service Method |
|
|
|------------------------|---------------------|
|
|
| `agents session create` | `create()` |
|
|
| `agents session list` | `list()` |
|
|
| `agents session show` | `get()` |
|
|
| `agents session delete` | `delete()` |
|
|
| `agents session export` | `export_session()` |
|
|
| `agents session import` | `import_session()` |
|
|
| `agents session tell` | `append_message()` |
|