Skip to content

Configuration

structx uses Pydantic Settings to validate provider parameters and load them from constructor values, environment variables, dotenv files, YAML, or secrets.

The two configurable steps are planning and extraction. Structx supplies no implicit sampling or output-token defaults; each StepConfig contains only the provider parameters explicitly supplied by the user.

Provider-specific completion parameters for one extraction step.

Source code in structx/core/config.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
class StepConfig(BaseModel):
    """Provider-specific completion parameters for one extraction step."""

    model_config = ConfigDict(validate_assignment=True, extra="allow")

    @model_validator(mode="before")
    @classmethod
    def decode_scalar_values(cls, value: Any) -> Any:
        """Decode numeric and boolean values supplied by nested environment keys."""
        if not isinstance(value, dict):
            return value
        decoded = {}
        for key, item in value.items():
            if isinstance(item, str):
                try:
                    item = json.loads(item)
                except json.JSONDecodeError:
                    pass
            decoded[key] = item
        return decoded

    def options(self) -> DictStrAny:
        """Return explicitly configured provider parameters."""
        return self.model_dump(exclude_none=True)

options()

Return explicitly configured provider parameters.

Source code in structx/core/config.py 
40
41
42
def options(self) -> DictStrAny:
    """Return explicitly configured provider parameters."""
    return self.model_dump(exclude_none=True)

Settings loaded from arguments, environment, dotenv, YAML, or secrets.

Source priority is constructor values, environment variables, .env, YAML, then file secrets. Environment and secret names use the STRUCTX_ prefix.

Source code in structx/core/config.py 
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class ExtractionConfig(BaseSettings):
    """Settings loaded from arguments, environment, dotenv, YAML, or secrets.

    Source priority is constructor values, environment variables, ``.env``,
    YAML, then file secrets. Environment and secret names use the ``STRUCTX_``
    prefix.
    """

    planning: StepConfig = Field(default_factory=StepConfig)
    extraction: StepConfig = Field(default_factory=StepConfig)

    model_config = SettingsConfigDict(
        extra="ignore",
        env_prefix="STRUCTX_",
        env_nested_delimiter="__",
        env_file=".env",
        env_file_encoding="utf-8",
        yaml_file=None,
    )

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: Type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        """Use conventional precedence with YAML below dotenv values."""
        return (
            init_settings,
            env_settings,
            dotenv_settings,
            YamlConfigSettingsSource(settings_cls),
            file_secret_settings,
        )

    @classmethod
    def from_yaml(cls, path: str | Path, **overrides: Any) -> "ExtractionConfig":
        """Load settings from a YAML file with optional highest-priority overrides."""
        yaml_path = Path(path).expanduser()
        if not yaml_path.is_file():
            raise ConfigurationError(f"Configuration file not found: {yaml_path}")

        class YamlExtractionConfig(cls):
            model_config = SettingsConfigDict(
                **{**cls.model_config, "yaml_file": yaml_path}
            )

        return YamlExtractionConfig(**overrides)

    def for_step(self, step: str) -> DictStrAny:
        """Return provider kwargs for ``planning`` or ``extraction``."""
        if step not in {"planning", "extraction"}:
            raise ConfigurationError(f"Unknown extraction step: {step}")
        return getattr(self, step).options()

from_yaml(path, **overrides) classmethod

Load settings from a YAML file with optional highest-priority overrides.

Source code in structx/core/config.py 
83
84
85
86
87
88
89
90
91
92
93
94
95
@classmethod
def from_yaml(cls, path: str | Path, **overrides: Any) -> "ExtractionConfig":
    """Load settings from a YAML file with optional highest-priority overrides."""
    yaml_path = Path(path).expanduser()
    if not yaml_path.is_file():
        raise ConfigurationError(f"Configuration file not found: {yaml_path}")

    class YamlExtractionConfig(cls):
        model_config = SettingsConfigDict(
            **{**cls.model_config, "yaml_file": yaml_path}
        )

    return YamlExtractionConfig(**overrides)

for_step(step)

Return provider kwargs for planning or extraction.

Source code in structx/core/config.py 
 97
 98
 99
100
101
def for_step(self, step: str) -> DictStrAny:
    """Return provider kwargs for ``planning`` or ``extraction``."""
    if step not in {"planning", "extraction"}:
        raise ConfigurationError(f"Unknown extraction step: {step}")
    return getattr(self, step).options()

For source precedence, YAML examples, environment names, and runtime settings, see Configuration Options.