Dashboard API

Dashboard chat models.

class sqldbagent.dashboard.models.ChatMessageModel(**data)

Bases: BaseModel

Rendered chat transcript entry for dashboard surfaces.

Variables:

• role – Message role shown in the dashboard.

• content – Human-readable message body.

• kind – Original LangChain/LangGraph message type.

• name – Optional tool or actor name.

• status – Optional tool status marker.

Parameters:

• data (Any)

• role (str)

• content (str)

• kind (str)

• name (str | None)

• status (str | None)

role: str

content: str

kind: str

name: str | None

status: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sqldbagent.dashboard.models.DashboardTurnProgressModel(**data)

Bases: BaseModel

One dashboard progress event emitted during an agent turn.

Variables:

• phase – High-level execution phase such as bootstrap, tool, or response.

• label – Short user-facing progress label.

• detail – Optional supporting detail for the current step.

Parameters:

• data (Any)

• phase (str)

• label (str)

• detail (str | None)

phase: str

label: str

detail: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sqldbagent.dashboard.models.DashboardThreadEntryModel(**data)

Bases: BaseModel

Persisted dashboard thread summary used for thread selection.

Variables:

• thread_id – Stable thread identifier used by the LangGraph checkpointer.

• datasource_name – Datasource identifier associated with the thread.

• schema_name – Optional schema focus for the thread.

• display_name – Optional user-friendly thread title.

• created_at – First time the thread was observed by the dashboard.

• updated_at – Most recent time the dashboard refreshed the thread entry.

• message_count – Number of rendered transcript messages currently known.

• latest_snapshot_id – Latest snapshot bound into the thread state, if any.

• last_user_message – Most recent user message preview.

• last_assistant_message – Most recent assistant message preview.

Parameters:

• data (Any)

• thread_id (str)

• datasource_name (str)

• schema_name (str | None)

• display_name (str | None)

• created_at (datetime)

• updated_at (datetime)

• message_count (int)

• latest_snapshot_id (str | None)

• last_user_message (str | None)

• last_assistant_message (str | None)

thread_id: str

datasource_name: str

schema_name: str | None

display_name: str | None

created_at: datetime

updated_at: datetime

message_count: int

latest_snapshot_id: str | None

last_user_message: str | None

last_assistant_message: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sqldbagent.dashboard.models.ChatSessionModel(**data)

Bases: BaseModel

Dashboard-ready snapshot of one agent conversation thread.

Variables:

• thread_id – Stable thread identifier used by the LangGraph checkpointer.

• datasource_name – Datasource identifier backing the session.

• schema_name – Optional schema focus.

• messages – Rendered chat transcript entries.

• dashboard_payload – Dashboard-friendly state payload from the agent state.

• observability – Dashboard-friendly runtime and tracing status payload.

• latest_snapshot_id – Latest known stored snapshot id.

• latest_snapshot_summary – Latest known stored snapshot summary.

• tool_call_digest – Compressed tool-call history from the agent state.

• diagram_bundle – Stored schema-diagram bundle associated with the session.

• prompt_bundle – Stored prompt bundle associated with the session.

• retrieval_manifest – Stored retrieval-index manifest associated with the session.

• example_questions – Snapshot-aware starter questions for the dashboard chat.

• available_threads – Persisted dashboard thread summaries for selection.

Parameters:

• data (Any)

• thread_id (str)

• datasource_name (str)

• schema_name (str | None)

• messages (list[ChatMessageModel])

• dashboard_payload (dict[str, object])

• observability (dict[str, object])

• latest_snapshot_id (str | None)

• latest_snapshot_summary (str | None)

• tool_call_digest (list[str])

• diagram_bundle (DiagramBundleModel | None)

• prompt_bundle (PromptBundleModel | None)

• retrieval_manifest (RetrievalIndexManifestModel | None)

• example_questions (list[str])

• available_threads (list[DashboardThreadEntryModel])

thread_id: str

datasource_name: str

schema_name: str | None

messages: list[ChatMessageModel]

dashboard_payload: dict[str, object]

observability: dict[str, object]

latest_snapshot_id: str | None

latest_snapshot_summary: str | None

tool_call_digest: list[str]

diagram_bundle: DiagramBundleModel | None

prompt_bundle: PromptBundleModel | None

retrieval_manifest: RetrievalIndexManifestModel | None

example_questions: list[str]

available_threads: list[DashboardThreadEntryModel]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Dashboard chat service built on top of the persisted LangGraph agent.

class sqldbagent.dashboard.service.DashboardChatService(*, settings=None, model=None, checkpointer=None, store=None)

Bases: object

Run persisted chat turns over the shared sqldbagent agent stack.

Parameters:

• settings (AppSettings | None, default: None)

• model (Any | None, default: None)

• checkpointer (Any | None, default: None)

• store (Any | None, default: None)

__init__(*, settings=None, model=None, checkpointer=None, store=None)

Initialize the dashboard chat service.

Parameters:

• settings (AppSettings | None, default: None) – Optional application settings.

• model (Any | None, default: None) – Optional prebuilt LangChain-compatible model for tests.

• checkpointer (Any | None, default: None) – Optional externally managed checkpointer for tests.

• store (Any | None, default: None) – Optional externally managed long-term memory store for tests or dashboard-session reuse.

Return type:

None

static new_thread_id()

Return a new stable thread identifier.

Return type:

str

run_turn(*, thread_id, user_message, datasource_name, schema_name=None, progress_callback=None)

Run one user turn through the persisted agent session.

Parameters:

• thread_id (str) – LangGraph thread identifier.

• user_message (str) – User message content.

• datasource_name (str) – Datasource identifier.

• schema_name (str | None, default: None) – Optional schema focus.

• progress_callback (Callable[[DashboardTurnProgressModel], None] | None, default: None) – Optional callback used to surface progress events while the agent turn is running.

Returns:

Dashboard-ready state after the turn.

Return type:

ChatSessionModel

load_thread(*, thread_id, datasource_name, schema_name=None)

Load the current persisted state for one thread.

Parameters:

• thread_id (str) – LangGraph thread identifier.

• datasource_name (str) – Datasource identifier.

• schema_name (str | None, default: None) – Optional schema focus.

Returns:

Dashboard-ready state snapshot for the thread.

Return type:

ChatSessionModel

list_threads(*, datasource_name=None, schema_name=None)

List persisted dashboard thread summaries.

Parameters:

• datasource_name (str | None, default: None) – Optional datasource filter.

• schema_name (str | None, default: None) – Optional schema filter.

Returns:

Matching thread summaries ordered by most recently updated first.

Return type:

list[DashboardThreadEntryModel]

update_thread_display_name(*, thread_id, datasource_name, schema_name, display_name)

Persist an optional user-friendly display name for one thread.

Parameters:

• thread_id (str)

• datasource_name (str)

• schema_name (str | None)

• display_name (str | None)

Return type:

DashboardThreadEntryModel | None

supports_async_queries(*, datasource_name)

Return whether the datasource has a supported async query path.

Parameters:

datasource_name (str)

Return type:

bool

run_safe_query(*, datasource_name, sql, max_rows=None, mode='sync', access_mode='read_only')

Run one guarded query through the shared query service.

Parameters:

• datasource_name (str) – Datasource identifier.

• sql (str) – SQL text to lint, guard, and execute.

• max_rows (int | None, default: None) – Optional row-limit override.

• mode (str, default: "sync") – Execution mode, either sync or async.

• access_mode (str, default: "read_only") – Requested execution mode, either read_only or writable.

Returns:

Guard and execution result.

Return type:

QueryExecutionResult

render_prompt_markdown(bundle)

Render one stored prompt bundle as Markdown for dashboard downloads.

Parameters:

bundle (PromptBundleModel) – Prompt bundle to render.

Returns:

Human-readable Markdown prompt artifact.

Return type:

str

update_prompt_bundle_enhancement(*, datasource_name, schema_name, active, user_context, business_rules, additional_effective_context, answer_style, refresh_generated=False)

Update prompt-enhancement state and regenerate the prompt bundle.

Parameters:

• datasource_name (str) – Datasource identifier.

• schema_name (str) – Schema name.

• active (bool) – Whether the enhancement should be active.

• user_context (str | None) – Freeform user context or domain notes.

• business_rules (str | None) – Business rules and caveats.

• additional_effective_context (str | None) – Extra instructions that should be injected directly into the effective prompt.

• answer_style (str | None) – Preferred answer style for downstream outputs.

• refresh_generated (bool, default: False) – Whether DB-aware guidance should be regenerated.

Returns:

Updated prompt bundle or None when no snapshot exists yet for the schema.

Return type:

PromptBundleModel | None

refresh_prompt_bundle_context(*, datasource_name, schema_name)

Regenerate schema-aware prompt context from the latest stored snapshot.

Parameters:

• datasource_name (str) – Datasource identifier.

• schema_name (str) – Schema name.

Returns:

Refreshed prompt bundle, or None when no stored snapshot exists for the schema.

Return type:

PromptBundleModel | None

explore_prompt_bundle_context(*, datasource_name, schema_name, table_names=None, max_tables=4, unique_value_limit=8, sync_memory=True, create_snapshot_if_missing=True)

Generate live prompt context and persist it into the prompt bundle.

Parameters:

• datasource_name (str) – Datasource identifier.

• schema_name (str) – Schema name.

• table_names (list[str] | None, default: None) – Optional explicit focus tables.

• max_tables (int, default: 4) – Maximum number of tables to explore live.

• unique_value_limit (int, default: 8) – Maximum number of distinct values per column.

• sync_memory (bool, default: True) – Whether to sync a concise summary into long-term memory.

• create_snapshot_if_missing (bool, default: True) – Whether to bootstrap a new snapshot first.

Returns:

Updated prompt bundle, or None when no stored snapshot exists for the schema.

Return type:

PromptBundleModel | None

ensure_retrieval_index(*, datasource_name, schema_name, recreate_collection=False)

Ensure a retrieval index exists for the latest stored schema snapshot.

Parameters:

• datasource_name (str) – Datasource identifier.

• schema_name (str) – Schema name.

• recreate_collection (bool, default: False) – Whether to rebuild the vector collection.

Returns:

Saved retrieval manifest, or None when no stored snapshot exists for the schema.

Return type:

RetrievalIndexManifestModel | None