orchestrata_ultimate.session.examples.basic_usage

Reference › orchestrata_ultimate › session › examples › basic_usage

An example script whose main demonstrates the basic session workflow with the SessionController: in a temporary demo project it begins a session, logs work entries, artifacts, choices and achievements, sets a handoff, ends the session, prints the counts and shows the resulting context.md.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/session/examples/basic_usage.py

# mypy: ignore-errors
#!/usr/bin/env python3
"""Basic usage example for the session-management library.

Demonstrates the :class:`SessionController` lifecycle — begin a session, log
work / artifacts / choices / achievements, set a handoff, and end it — against a
throwaway project directory. Run it with:

    python -m orchestrata_ultimate.session.examples.basic_usage

It creates ``context.json`` / ``context.md`` in a temporary directory and prints
the resulting session record.
"""

import tempfile
from pathlib import Path

from orchestrata_ultimate.session import SessionController


def _header(title: str) -> None:
    print("=" * 50)
    print(title)
    print("=" * 50)


def main() -> None:
    """Demonstrate the basic session-management workflow."""
    with tempfile.TemporaryDirectory() as temp_dir:
        project_path = Path(temp_dir)
        # SessionController auto-initializes its context files at a project root;
        # a pyproject.toml marks this temp directory as one.
        (project_path / "pyproject.toml").write_text(
            "[project]\nname = 'demo'\nversion = '0.1.0'\n"
        )
        print(f"Demo project path: {project_path}\n")

        # ai_model defaults to default_ai_model()
        controller = SessionController(project_path)

        _header("Step 1: Begin Session")
        session = controller.begin(
            "Implement user authentication",
            objectives=[
                "Design auth API",
                "Implement JWT tokens",
                "Write unit tests",
            ],
        )
        print(f"Session #{session.seq} started: {session.purpose}")
        for objective in session.objectives:
            print(f"  - {objective}")
        print()

        _header("Step 2: Log Work")
        controller.log_work(
            "Designed the authentication API",
            details=["/auth/login", "/auth/logout", "/auth/refresh"],
        )
        controller.log_work(
            "Implemented JWT token generation",
            details=["Added PyJWT", "Token service", "Token validation"],
        )
        print("Logged 2 work entries\n")

        _header("Step 3: Log Artifacts")
        controller.log_artifact(
            "src/auth/api.py", line_count=150, summary="Auth API endpoints"
        )
        controller.log_artifact(
            "src/auth/tokens.py", line_count=80, summary="JWT token service"
        )
        controller.log_artifact(
            "tests/test_auth.py", line_count=200, summary="Auth unit tests"
        )
        print("Logged 3 artifacts\n")

        _header("Step 4: Record Choices + Achievements")
        controller.log_choice(
            "Use JWT for authentication",
            "Stateless, scalable, industry standard for APIs",
        )
        controller.log_choice(
            "Store refresh tokens in httpOnly cookies",
            "Prevents XSS attacks on refresh tokens",
        )
        controller.log_achievement("Designed and documented the auth API")
        controller.log_achievement("Implemented JWT token generation + validation")
        print("Logged 2 choices + 2 achievements\n")

        _header("Step 5: Set Handoff")
        controller.set_handoff(
            decisions=["JWT for auth tokens", "httpOnly cookies for refresh tokens"],
            blockers=["Security review required before production"],
            active_work=["Writing unit tests", "Documentation"],
            key_files=["src/auth/api.py", "src/auth/tokens.py"],
            cmds=["uv run pytest tests/test_auth.py -v"],
            alerts=["Token expiry set to 1h in dev", "CORS not configured yet"],
        )
        print("Handoff set\n")

        _header("Step 6: End Session")
        ended = controller.end(
            achievements=["Designed auth API", "Implemented JWT tokens"],
            upcoming=[
                "Complete unit tests",
                "Add API documentation",
                "Security review",
            ],
        )
        if ended is not None:
            print(f"Session #{ended.seq} ended")
            print(f"  Work entries: {len(ended.log)}")
            print(f"  Artifacts:    {len(ended.artifacts)}")
            print(f"  Achievements: {len(ended.achievements)}")
        print(f"Total sessions recorded: {controller.session_count()}\n")

        _header("Generated context.md (first 40 lines)")
        context_path = project_path / "context.md"
        if context_path.exists():
            for line in context_path.read_text().splitlines()[:40]:
                print(line)


if __name__ == "__main__":
    main()