Core API

Reusable agent context helpers for prompts, state, and dashboard payloads.

sqldbagent.core.agent_context.build_sqldbagent_state_seed(*, datasource_name, settings=None, schema_name=None)[source]

Build the initial state payload used by sqldbagent agent surfaces.

Parameters:

  • datasource_name (str) – Datasource identifier.

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

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

Returns:

Seed state with snapshot and dashboard-friendly context.

Return type:

dict[str, Any]

sqldbagent.core.agent_context.build_sqldbagent_dashboard_payload(*, datasource_name, schema_name, snapshot, prompt_enhancement=None)[source]

Build dashboard-oriented agent state from the latest known snapshot.

Parameters:

  • datasource_name (str) – Datasource identifier.

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

  • snapshot (SnapshotBundleModel | None) – Optional latest stored snapshot.

  • prompt_enhancement (PromptEnhancementModel | None, default: None) – Optional prompt enhancement for the same scope.

Returns:

Dashboard-friendly payload for UI surfaces.

Return type:

dict[str, Any]

sqldbagent.core.agent_context.load_latest_snapshot_bundle(*, datasource_name, settings, schema_name)[source]

Load the latest relevant snapshot bundle when available.

Parameters:

  • datasource_name (str) – Datasource identifier.

  • settings (AppSettings) – Application settings.

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

Returns:

Latest matching snapshot or None.

Return type:

SnapshotBundleModel | None

sqldbagent.core.agent_context.build_snapshot_prompt_context(*, datasource_name, settings=None, schema_name=None)[source]

Build rich prompt context from the latest stored snapshot.

Parameters:

  • datasource_name (str) – Datasource identifier.

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

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

Returns:

Formatted prompt context block when a snapshot exists.

Return type:

str | None

Service container helpers.

class sqldbagent.core.bootstrap.ServiceContainer(inspector, profiler=None, query_guard=None, query_service=None, snapshotter=None, diagram_service=None, document_service=None, prompt_service=None, retrieval_service=None, datasource_name=None, settings=None, engine=None, async_engine=None, write_engine=None, write_async_engine=None)[source]

Bases: object

Thin container passed into adapter surfaces.

Variables:

  • inspector – Shared inspection service used by CLI and adapter layers.

  • profiler – Shared profiling service used by profiling and snapshot layers.

  • query_guard – Shared SQL safety service.

  • query_service – Shared guarded query execution service.

  • snapshotter – Shared snapshot persistence service.

  • diagram_service – Shared schema diagram export service.

  • document_service – Shared snapshot document-export service.

  • prompt_service – Shared prompt-export service.

  • retrieval_service – Shared retrieval service over stored snapshot documents.

  • datasource_name – Canonical datasource name backing the container.

Parameters:
settings: Application settings that built the container.

engine: Optional SQLAlchemy engine owned by the container. async_engine: Optional async SQLAlchemy engine owned by the container. write_engine: Optional writable sync engine owned by the container. write_async_engine: Optional writable async engine owned by the container.

Parameters:
inspector: InspectionService
profiler: SQLAlchemyProfilingService | None
query_guard: QueryGuardService | None
query_service: SafeQueryService | None
snapshotter: SnapshotService | None
diagram_service: SchemaDiagramService | None
document_service: SnapshotDocumentService | None
prompt_service: SnapshotPromptService | None
retrieval_service: SnapshotRetrievalService | None
datasource_name: str | None
settings: AppSettings | None
engine: Engine | None
async_engine: AsyncEngine | None
write_engine: Engine | None
write_async_engine: AsyncEngine | None
close()[source]

Dispose owned sync resources.

When an async engine is present, callers should prefer aclose() so the async SQLAlchemy engine can shut down cleanly.

Return type:

None

async aclose()[source]

Dispose owned async resources.

Return type:

None

sqldbagent.core.bootstrap.build_service_container(datasource_name, settings=None, *, include_async_engine=False)[source]

Build a service container for one datasource.

Parameters:

  • datasource_name (str) – Datasource identifier.

  • settings (AppSettings | None, default: None) – Optional application settings. Loaded from environment when omitted.

  • include_async_engine (bool, default: False) – Whether to initialize the async engine as well.

Returns:

Container with initialized shared services.

Return type:

ServiceContainer

Canonical normalized catalog models.

class sqldbagent.core.models.catalog.ColumnModel(**data)[source]

Bases: BaseModel

Normalized column metadata.

Variables:

  • name – Column name.

  • data_type – Normalized logical or physical data type.

  • nullable – Whether the column accepts null values.

  • default – Optional default expression.

  • description – Optional normalized description.

  • summary – Generated short summary for humans and downstream prompts.

Parameters:

  • data (Any)

  • name (str)

  • data_type (str)

  • nullable (bool)

  • default (str | None)

  • description (str | None)

  • summary (str | None)

name: str
data_type: str
nullable: bool
default: str | None
description: str | None
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.CheckConstraintModel(**data)[source]

Bases: BaseModel

Normalized check constraint metadata.

Variables:

  • name – Constraint name when available.

  • expression – Check expression SQL when available.

  • summary – Generated short summary.

Parameters:

  • data (Any)

  • name (str | None)

  • expression (str | None)

  • summary (str | None)

name: str | None
expression: str | None
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.IndexModel(**data)[source]

Bases: BaseModel

Normalized index metadata.

Variables:

  • name – Index name.

  • columns – Indexed column names.

  • unique – Whether the index is unique.

  • summary – Generated short summary.

Parameters:
name: str | None
columns: list[str]
unique: bool
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.ForeignKeyModel(**data)[source]

Bases: BaseModel

Normalized foreign key metadata.

Variables:

  • name – Constraint name when available.

  • columns – Local constrained columns.

  • referred_schema – Referenced schema name when available.

  • referred_table – Referenced table name.

  • referred_columns – Referenced column names.

  • summary – Generated short summary.

Parameters:

  • data (Any)

  • name (str | None)

  • columns (list[str])

  • referred_schema (str | None)

  • referred_table (str)

  • referred_columns (list[str])

  • summary (str | None)

name: str | None
columns: list[str]
referred_schema: str | None
referred_table: str
referred_columns: list[str]
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.UniqueConstraintModel(**data)[source]

Bases: BaseModel

Normalized unique constraint metadata.

Variables:

  • name – Constraint name when available.

  • columns – Columns covered by the unique constraint.

  • summary – Generated short summary.

Parameters:
name: str | None
columns: list[str]
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.RelationshipEdgeModel(**data)[source]

Bases: BaseModel

Normalized relationship edge derived from a foreign key.

Variables:

  • source_schema – Schema of the referencing table when available.

  • source_table – Referencing table.

  • source_columns – Referencing columns.

  • target_schema – Schema of the referenced table when available.

  • target_table – Referenced table.

  • target_columns – Referenced columns.

  • constraint_name – Foreign key constraint name.

  • summary – Generated short summary.

Parameters:

  • data (Any)

  • source_schema (str | None)

  • source_table (str)

  • source_columns (list[str])

  • target_schema (str | None)

  • target_table (str)

  • target_columns (list[str])

  • constraint_name (str | None)

  • summary (str | None)

source_schema: str | None
source_table: str
source_columns: list[str]
target_schema: str | None
target_table: str
target_columns: list[str]
constraint_name: str | None
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.TableModel(**data)[source]

Bases: BaseModel

Normalized table metadata.

Variables:

  • database – Optional database name containing the table.

  • schema_name – Optional schema name containing the table.

  • name – Table name.

  • columns – Normalized column metadata.

  • primary_key – Ordered primary key column names.

  • indexes – Normalized index metadata.

  • foreign_keys – Normalized foreign key metadata.

  • unique_constraints – Normalized unique constraint metadata.

  • check_constraints – Normalized check constraint metadata.

  • description – Optional normalized description.

  • summary – Generated short summary.

Parameters:
database: str | None
schema_name: str | None
name: str
columns: list[ColumnModel]
primary_key: list[str]
indexes: list[IndexModel]
foreign_keys: list[ForeignKeyModel]
unique_constraints: list[UniqueConstraintModel]
check_constraints: list[CheckConstraintModel]
description: str | None
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.ViewModel(**data)[source]

Bases: BaseModel

Normalized view metadata.

Variables:

  • database – Optional database containing the view.

  • schema_name – Optional schema containing the view.

  • name – View name.

  • columns – Reflected view columns.

  • definition – View definition SQL when available.

  • summary – Generated short summary.

Parameters:
database: str | None
schema_name: str | None
name: str
columns: list[ColumnModel]
definition: str | None
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.ServerModel(**data)[source]

Bases: BaseModel

Normalized server metadata.

Variables:

  • dialect – Dialect or driver name used by the datasource.

  • database – Current database name when available.

  • schemas – Visible schema names.

  • summary – Generated short summary.

Parameters:
dialect: str
database: str | None
schemas: list[str]
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.SchemaModel(**data)[source]

Bases: BaseModel

Normalized schema metadata.

Variables:

  • database – Optional database name containing the schema.

  • name – Schema name.

  • tables – Normalized tables within the schema.

  • views – Normalized views within the schema.

  • summary – Generated short summary.

Parameters:
database: str | None
name: str
tables: list[TableModel]
views: list[ViewModel]
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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

class sqldbagent.core.models.catalog.DatabaseModel(**data)[source]

Bases: BaseModel

Normalized database metadata.

Variables:

  • name – Database name.

  • schemas – Normalized schema metadata in the database.

  • summary – Generated short summary.

Parameters:
name: str
schemas: list[SchemaModel]
summary: str | None
model_config: ClassVar[ConfigDict] = {}

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