> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conductorquantum.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conductorquantum.com/_mcp/server.

# stanza.context

Stanza session management for Stanza CLI.

This module manages the top-level Stanza session (the timestamped directory).
This is distinct from LoggerSession which handles per-routine data logging.

Architecture:
    StanzaSession (this module):
        - Creates timestamped directories like: 20251020100010_untitled/
        - Manages session-level metadata and active session tracking
        - Scope: Global/session-wide, persists across routine runs

    LoggerSession (stanza/logger/session.py):
        - Handles per-routine data collection and buffered writing
        - Scope: Per-routine execution, created/destroyed per run

## Module Contents

### Classes

| Name | Description |
|------|-------------|
| [`StanzaSession`](#stanzacontextstanzasession) | Manages the active Stanza session directory. |

### API

```python
class stanza.context.StanzaSession
```

Manages the active Stanza session directory.

This class handles the top-level timestamped session directory
(e.g., 20251020100010_untitled/) and tracks which session is currently active.

```python
CONFIG_DIR
```

**Value**: `.stanza`


```python
CONFIG_FILE
```

**Value**: `config.json`


```python
create_session_directory(
    base_path: pathlib.Path | str | None = None, name: str | None = None
) -> pathlib.Path
```

Create a new timestamped Stanza session directory.

**Parameters:**

<ParamField path="base_path" type="pathlib.Path | str | None">
  Base directory for session (default: current directory)
</ParamField>

<ParamField path="name" type="str | None">
  Optional suffix for directory name (default: "untitled")
</ParamField>

**Returns:**

Path to created session directory
Example:
>>> StanzaSession.create_session_directory()
PosixPath('20251020100010_untitled')
>>> StanzaSession.create_session_directory(name="experiment")
PosixPath('20251020100010_experiment')


```python
get_active_session() -> pathlib.Path | None
```

Get the active Stanza session directory from working directory config.

**Returns:**

Path to active session directory, or None if not set
Example:
>>> StanzaSession.get_active_session()
PosixPath('20251020100010_untitled')


```python
set_active_session(session_dir: pathlib.Path | str) -> None
```

Set the active Stanza session directory.

**Parameters:**

<ParamField path="session_dir" type="pathlib.Path | str">
  Path to session directory
</ParamField>


```python
clear_active_session() -> bool
```

Remove the active session pointer file.

**Returns:**

True if a session reference was removed, False otherwise.


```python
get_session_metadata(session_dir: pathlib.Path | str) -> dict[str, typing.Any] | None
```

Get metadata for a Stanza session directory.

**Parameters:**

<ParamField path="session_dir" type="pathlib.Path | str">
  Path to session directory
</ParamField>

**Returns:**

Metadata dictionary or None if not found