Skip to content

Configuration API

The configuration API has no implicit file or environment access unless the selected resolution method requests it. Credential fields are excluded from representation and serialization.

See Configuration for fields, precedence, TOML, and environment names. See Security and API Keys before supplying a credential.

The downloadable configuration serialization schema is generated from this model and checked for drift. It excludes credentials and the callable token provider by design.

config

Typed configuration and deterministic source precedence.

GenerationConfig

Bases: BaseModel

Structured generation settings shared by provider adapters.

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    extra="forbid", frozen=True, hide_input_in_errors=True
)

temperature class-attribute instance-attribute 

temperature: float = Field(
    default=0.0,
    ge=0.0,
    le=2.0,
    strict=True,
    allow_inf_nan=False,
)

max_output_tokens class-attribute instance-attribute 

max_output_tokens: int = Field(
    default=4096, ge=1, strict=True
)

seed class-attribute instance-attribute 

seed: int | None = Field(default=None, strict=True)

RetryConfig

Bases: BaseModel

Bounded retry settings.

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    extra="forbid", frozen=True, hide_input_in_errors=True
)

max_attempts class-attribute instance-attribute 

max_attempts: int = Field(
    default=3, ge=1, le=10, strict=True
)

initial_delay_seconds class-attribute instance-attribute 

initial_delay_seconds: float = Field(
    default=0.5, ge=0.0, strict=True, allow_inf_nan=False
)

max_delay_seconds class-attribute instance-attribute 

max_delay_seconds: float = Field(
    default=8.0, ge=0.0, strict=True, allow_inf_nan=False
)

validate_delay_range 

validate_delay_range() -> Self

Require the maximum delay to include the initial delay.

ArtifactConfig

Bases: BaseModel

Default artifact publication settings.

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    extra="forbid", frozen=True, hide_input_in_errors=True
)

sidecar class-attribute instance-attribute 

sidecar: bool = Field(default=True, strict=True)

manifest class-attribute instance-attribute 

manifest: Literal[True] = True

SurveyScribeConfig 

SurveyScribeConfig(**data: Any)

Bases: BaseModel

Validated application configuration with non-serializable credentials.

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    arbitrary_types_allowed=True,
    hide_input_in_errors=True,
)

config_version class-attribute instance-attribute 

config_version: Literal[1] = CONFIG_VERSION

provider class-attribute instance-attribute 

provider: str = 'openai'

model class-attribute instance-attribute 

model: str | None = None

base_url class-attribute instance-attribute 

base_url: AnyHttpUrl | None = None

api_version class-attribute instance-attribute 

api_version: str | None = None

api_key class-attribute instance-attribute 

api_key: SecretStr | None = Field(
    default=None, exclude=True, repr=False
)

bearer_token class-attribute instance-attribute 

bearer_token: SecretStr | None = Field(
    default=None, exclude=True, repr=False
)

token_callback class-attribute instance-attribute 

token_callback: TokenCallback | None = Field(
    default=None, exclude=True, repr=False
)

generation class-attribute instance-attribute 

generation: GenerationConfig = Field(
    default_factory=GenerationConfig
)

retry class-attribute instance-attribute 

retry: RetryConfig = Field(default_factory=RetryConfig)

max_concurrency class-attribute instance-attribute 

max_concurrency: int = Field(
    default=4, ge=1, le=128, strict=True
)

confidence_threshold class-attribute instance-attribute 

confidence_threshold: float = Field(
    default=0.7,
    ge=0.0,
    le=1.0,
    strict=True,
    allow_inf_nan=False,
)

routing class-attribute instance-attribute 

routing: RoutingConfig = Field(
    default_factory=RoutingConfig
)

artifacts class-attribute instance-attribute 

artifacts: ArtifactConfig = Field(
    default_factory=ArtifactConfig
)

require_integer_config_version classmethod 

require_integer_config_version(value: object) -> object

Reject Boolean values that compare equal to version one.

reject_secret_bearing_base_url classmethod 

reject_secret_bearing_base_url(
    value: AnyHttpUrl | None,
) -> AnyHttpUrl | None

Reject credentials and non-routing fragments in provider base URLs.

normalize_provider classmethod 

normalize_provider(value: str) -> str

Normalize provider names while rejecting empty values.

reject_empty_optional_strings classmethod 

reject_empty_optional_strings(
    value: str | None,
) -> str | None

Reject configured string values that contain only whitespace.

reject_ambiguous_credentials 

reject_ambiguous_credentials() -> Self

Allow at most one key, bearer token, or token callback.

resolve classmethod 

resolve(
    *,
    constructor: Mapping[str, object] | None = None,
    config: SurveyScribeConfig | None = None,
    config_path: str | PathLike[str] | None = None,
    resolve_environment: bool = False,
    environ: Mapping[str, str] | None = None,
) -> Self

Resolve SDK settings without implicit TOML or environment access.

Parameters:

Name Type Description Default
constructor Mapping[str, object] | None

Highest-priority field values. Entries set to None are ignored.

 None
config SurveyScribeConfig | None

Explicitly set fields from an existing configuration model.

 None
config_path str | PathLike[str] | None

Exact TOML file to read. No file is read when omitted.

 None
resolve_environment bool

Whether to read credential and provider values from environ or the process environment.

 False
environ Mapping[str, str] | None

Environment mapping to use instead of os.environ.

 None

Returns:

Type Description
Self

A validated, frozen configuration model.

Raises:

Type Description
ConfigurationError

A file is missing, malformed, secret-bearing, or resolves to invalid settings.
AmbiguousCredentialError

More than one credential form is resolved.

from_config classmethod 

from_config(
    path: str | PathLike[str] | None = None,
    *,
    constructor: Mapping[str, object] | None = None,
    config: SurveyScribeConfig | None = None,
    resolve_environment: bool = False,
    environ: Mapping[str, str] | None = None,
    cwd: str | PathLike[str] | None = None,
) -> Self

Resolve an explicit TOML file, or only the current-directory file.

Parameters:

Name Type Description Default
path str | PathLike[str] | None

Exact TOML path. When omitted, only cwd/survey-scribe.toml is considered.

 None
constructor Mapping[str, object] | None

Highest-priority field values.

 None
config SurveyScribeConfig | None

Explicitly set fields from an existing configuration model.

 None
resolve_environment bool

Whether to resolve environment values.

 False
environ Mapping[str, str] | None

Environment mapping to use instead of os.environ.

 None
cwd str | PathLike[str] | None

Directory used for default-file discovery. The process current directory is used when omitted.

 None

Returns:

Type Description
Self

A validated, frozen configuration model.

Raises:

Type Description
ConfigurationError

The selected file or resolved values are invalid.
AmbiguousCredentialError

More than one credential form is resolved.

resolve_cli classmethod 

resolve_cli(
    *,
    flags: Mapping[str, object] | None = None,
    config_path: str | PathLike[str] | None = None,
    environ: Mapping[str, str] | None = None,
    cwd: str | PathLike[str] | None = None,
) -> Self

Resolve CLI settings without searching parent or home directories.

Parameters:

Name Type Description Default
flags Mapping[str, object] | None

Highest-priority non-None command-line values.

 None
config_path str | PathLike[str] | None

Exact TOML path. When omitted, only cwd/survey-scribe.toml is considered.

 None
environ Mapping[str, str] | None

Environment mapping. The process environment is used when omitted.

 None
cwd str | PathLike[str] | None

Directory used for default-file discovery.

 None

Returns:

Type Description
Self

A validated, frozen configuration model.

Raises:

Type Description
ConfigurationError

The requested file is missing or resolved values are invalid.
AmbiguousCredentialError

More than one credential form is resolved.