SDK: Session

Overview

The Session API manages stateful conversations and event streams for your apps. It offers sync and async clients with helpers for state and event handling.

Exports:

• FlotorchSession, FlotorchAsyncSession – create, fetch, list, delete sessions; append/read events

---

Setup

from flotorch.sdk.session import FlotorchSession, FlotorchAsyncSession

API_KEY = "<your_api_key>"
BASE_URL = "https://gateway.flotorch.cloud"

---

Session clients

FlotorchSession

FlotorchSession(
  api_key: str,
  base_url: str,
)

create(…) -> dict

create(
  app_name: str,
  user_id: str,
  uid: str | None = None,
  state: dict | None = None,
) -> dict

• Creates a new session and returns its metadata (including uid).

get(…) -> dict

get(
  uid: str,
  after_timestamp: int | None = None,
  num_recent_events: int | None = None,
) -> dict

• Retrieves a session; optionally filters recent events.

list(…) -> list[dict]

list(
  app_name: str | None = None,
  user_id: str | None = None,
) -> list[dict]

• Lists sessions by optional filters.

delete(…) -> dict

delete(uid: str) -> dict

• Deletes a session.

get_events(…) -> list[dict]

get_events(uid: str) -> list[dict]

• Returns all events for a session.

add_event(…) -> dict

add_event(
  uid: str,
  invocation_id: str,
  author: str,
  uid_event: str | None = None,
  branch: str | None = None,
  content: dict | None = None,
  actions: dict | None = None,
  long_running_tool_ids_json: str | None = None,
  grounding_metadata: dict | None = None,
  partial: bool | None = False,
  turn_complete: bool | None = False,
  error_code: str | None = None,
  error_message: str | None = None,
  interrupted: bool | None = False,
) -> dict

• Appends a structured event to the session timeline.

Helpers

create_state_delta(
  app_state: dict | None = None,
  user_state: dict | None = None,
  session_state: dict | None = None,
) -> dict

create_event_actions(
  state_delta: dict | None = None,
) -> dict

extract_messages(session_data: dict) -> list[dict]
extract_context(session_data: dict) -> dict
extract_events(session_data: dict) -> list[dict]

• Utilities for managing state and extracting structured data.

---

FlotorchAsyncSession

Constructor:

FlotorchAsyncSession(
  api_key: str,
  base_url: str,
)

Async counterparts of create, get, list, delete, get_events, and add_event with identical parameters and return shapes.

---

Notes

• uid uniquely identifies a session; persist it on the client to continue conversations.
• For high-throughput systems, prefer the async client.