Stack Config¶

StackConfig is the root model for config.toml. It holds every named connection, database, provider, model, vector store, and per-package tool section in one object, and validates cross-references between them at construction time.

Bases: BaseModel

Root model for ~/.config/omop/config.toml.

Holds the entire OMOP stack configuration in one object: named connections, logical databases, and per-package tool sections. Loaded from disk by :func:~oa_configurator.loader.load_stack_config; constructed in memory via :meth:for_session for tests and scripts, with no file I/O.

loaded_path `property` ¶

loaded_path: Path | None

Path of the TOML file this config was loaded from, if any.

bind_loaded_path ¶

bind_loaded_path(path: Path) -> None

Record the path of the TOML file this config was loaded from.

connection_names ¶

connection_names() -> tuple[str, ...]

Return a sorted tuple of configured connection names.

database_names ¶

database_names() -> tuple[str, ...]

Return a sorted tuple of configured database names.

for_session `classmethod` ¶

for_session(
    *,
    connections: dict[str, ConnectionConfig] | None = None,
    databases: Mapping[str, DatabaseEntry] | None = None,
    providers: dict[str, ProviderConfig] | None = None,
    models: dict[str, ModelConfig] | None = None,
    vector_stores: dict[str, VectorStoreConfig]
    | None = None,
    tools: dict[str, dict[str, Any]] | None = None,
) -> StackConfig

Build a config in memory without a TOML file.

Intended for tests and scripts. Cross-references are validated at construction time, same as for file-loaded configs.

Parameters:

Name	Type	Description	Default
`connections`	`dict[str, ConnectionConfig]`	Connection entries, keyed by name.	`None`
`databases`	`Mapping[str, DatabaseEntry]`	Database entries, keyed by name. `Mapping`, not `dict`, so a caller can pass just one concrete kind, for example `dict[str, GenericDatabaseConfig]`, without a dict-invariance error.	`None`
`providers`	`dict[str, ProviderConfig]`	Provider entries, keyed by name.	`None`
`models`	`dict[str, ModelConfig]`	Model entries, keyed by name.	`None`
`vector_stores`	`dict[str, VectorStoreConfig]`	Vector-store entries, keyed by name.	`None`
`tools`	`dict[str, dict[str, Any]]`	Per-package `[tools.<name>]` sections, keyed by tool name.	`None`

model_names ¶

model_names() -> tuple[str, ...]

Return a sorted tuple of configured model names.

provider_names ¶

provider_names() -> tuple[str, ...]

Return a sorted tuple of configured provider names.

tool_names ¶

tool_names() -> tuple[str, ...]

Return a sorted tuple of configured tool names.

validate_references ¶

validate_references() -> StackConfig

Ensure every RefTo-marked field points at a configured entry.

vector_store_names ¶

vector_store_names() -> tuple[str, ...]

Return a sorted tuple of configured vector store names.

Cross-reference validation¶

Every reference between sections (a database naming its connection, a model naming its provider, a vector store naming its database, a package's own field naming any of the above) uses the same generic marker instead of a hand-written validator per pair.

Marks a string field as naming an entry in another top-level section.

Applied via e.g. Annotated[str, RefTo(ConnectionConfig)]. One generic marker drives both cross-reference validation (:func:~oa_configurator.stack_config.unresolved_refs) and the CLI wizard's reuse-or-create recursion for a consuming package's own fields (e.g. embedding_model_name: Annotated[str, RefTo(ModelConfig)]). It replaces a hand-written validator per pair and the separate ModelFieldSpec/referenced_models side-list that used to carry the same information for consumer fields.

Attributes:

Name	Type	Description
`target`	`type[BaseModel]`	The section this field's value should name an entry in.
`is_test`	`bool`	Whether this field is expected to resolve to a `test_only` connection (for `target=DatabaseConfig` fields). Replaces a previous, unreliable convention of inferring this from whether the field's own Python name started with `"test_"`. Drives both the CLI wizard's "Test database (optional)" prompt and the symmetric `is_test`/`test_only` match enforced by :meth:`~oa_configurator.resolver.Resolver.resolve_package_config`.

Marks a string field as holding a secret: masked when interactively prompted, and a future anchor for secret_source (env:/file:) resolution. Applied via e.g. Annotated[str | None, Sensitive()].

Find every RefTo-marked field on instance whose value doesn't resolve against config.

One pure walk shared by every caller that needs to check this: a StackConfig-level validator, a resolved package config, a freshly-built CLI entry before it's saved. Each wraps the same walk with its own error type instead of re-implementing it.

Checks existence only. A value that exists but is the wrong concrete subtype, for example a RefTo(CDMDatabaseConfig) field pointing at a GenericDatabaseConfig entry, is not unresolved. See :func:mismatched_kind_refs for that, checked separately so the two failure modes get distinct, correctly actionable wording.

Parameters:

Name	Type	Description	Default
`instance`	`BaseModel`	The object whose RefTo-marked fields are being checked.	required
`config`	`StackConfig`	The stack config to resolve field values against.	required

Returns:

Type	Description
`list[tuple[str, str, str]]`	One (field_name, value, section) triple per unresolved field. section is the StackConfig attribute the value should have been found in, e.g. "connections".

Kind mismatches¶

A RefTo names which section an entry must live in; it doesn't narrow which subtype. mismatched_kind_refs() covers the one place that matters today: a RefTo(GenericDatabaseConfig) field (e.g. VectorStoreConfig.database) pointed at a CDMDatabaseConfig entry, or a RefTo(CDMDatabaseConfig) field pointed at a GenericDatabaseConfig one. Reads as a distinct "wrong kind" error rather than unresolved_refs()'s "doesn't exist" one, and runs alongside it at the same three validation sites (StackConfig.validate_references, the CLI's entry-reference check, Resolver.resolve_package_config()).

Find every RefTo-marked field on instance whose value names an existing entry of the wrong concrete subtype.

Parameters:

Name	Type	Description	Default
`instance`	`BaseModel`	The object whose RefTo-marked fields are being checked.	required
`config`	`StackConfig`	The stack config to resolve field values against.	required

Returns:

Type	Description
`list[tuple[str, str, type[BaseModel], type[BaseModel]]]`	One (field_name, value, expected_type, actual_type) tuple per mismatched field.

Stack Config¶

loaded_path property ¶

bind_loaded_path ¶

connection_names ¶

database_names ¶

for_session classmethod ¶

model_names ¶

provider_names ¶

tool_names ¶

validate_references ¶

vector_store_names ¶

Cross-reference validation¶

Kind mismatches¶

loaded_path `property` ¶

for_session `classmethod` ¶