praval.config

Typed configuration loading for Praval applications.

Configuration is read without creating runtime resources. Values are merged in this order: defaults, praval.toml, environment variables, then explicit API overrides.

Functions

discover_config_path([start])

Find the nearest praval.toml without reading user-home defaults.

get_legacy_observability_config()

Return the cached v0.8.2-compatible observability configuration.

load_config([path, overrides, environ])

Load and validate Praval configuration with documented precedence.

reset_legacy_observability_config()

Clear compatibility configuration state for tests.

Classes

AgentProfileConfig(**data)

Named agent defaults layered over a model profile.

AppConfig(**data)

Application resource identity.

EmbeddingProfileConfig(**data)

Named provider-neutral embedding profile.

EvalConfig(**data)

Evaluation orchestration configuration.

EvalGateConfig(**data)

One evaluation quality gate.

EvalJudgeConfig(**data)

Evaluator-agent or direct-model safety and budget policy.

EvalRagasConfig(**data)

Configured Praval profiles used only by optional RAGAS metrics.

EvalStoresConfig(**data)

Named evaluation-store settings.

EvalSuiteConfig(**data)

Offline or CI evaluation suite.

LocalObservabilityConfig(**data)

Optional local-only diagnostic trace retention.

ModelProfileConfig(**data)

Named foundation-model profile.

OTLPConfig(**data)

OTLP transport and batching settings.

ObservabilityConfig(**data)

Observability signal and privacy configuration.

OnlineEvalConfig(**data)

Sampled online evaluation worker settings.

PostgresEvalStoreConfig(**data)

PostgreSQL evaluation-store secret reference.

PravalConfig(**data)

Complete schema-versioned Praval application configuration.

ResolvedAgentConfig(**data)

Resolved agent and model settings after precedence is applied.

SQLiteEvalStoreConfig(**data)

Local and CI evaluation-store location.
class praval.config.AgentProfileConfig(**data)[source]

Bases: _ConfigModel

Named agent defaults layered over a model profile.

Parameters:

  • model (str | None)

  • system_message (str | None)

  • tools (tuple[str, ...])

  • memory_enabled (bool)

  • memory_namespace (str | None)

  • max_tool_rounds (int)

model: str | None
system_message: str | None
tools: tuple[str, ...]
memory_enabled: bool
memory_namespace: str | None
max_tool_rounds: int
validate_memory_namespace()[source]

Require a stable namespace whenever agent memory is enabled.

Return type:

AgentProfileConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.AppConfig(**data)[source]

Bases: _ConfigModel

Application resource identity.

Parameters:

  • service_name (str)

  • service_version (str | None)

  • deployment_environment (str | None)

service_name: str
service_version: str | None
deployment_environment: str | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EmbeddingProfileConfig(**data)[source]

Bases: _ConfigModel

Named provider-neutral embedding profile.

Parameters:

  • provider (str)

  • model (str)

  • dimensions (int | None)

  • base_url (str | None)

  • api_key_env (str | None)

provider: str
model: str
dimensions: int | None
base_url: str | None
api_key_env: str | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EvalConfig(**data)[source]

Bases: _ConfigModel

Evaluation orchestration configuration.

Parameters:
enabled: bool
store: Literal['sqlite', 'postgres']
offline_concurrency: int
online: OnlineEvalConfig
stores: EvalStoresConfig
ragas: EvalRagasConfig | None
judges: dict[str, EvalJudgeConfig]
suites: dict[str, EvalSuiteConfig]
validate_store()[source]

Require PostgreSQL configuration when that store is selected.

Return type:

EvalConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EvalGateConfig(**data)[source]

Bases: _ConfigModel

One evaluation quality gate.

Parameters:

  • gate_id (str | None)

  • metric (str)

  • aggregation (Literal['mean', 'minimum', 'maximum', 'percentile', 'count', 'pass_rate'])

  • operator (Literal['>=', '>', '<=', '<', '=='])

  • threshold (float)

  • required (bool)

  • percentile (float | None)

  • baseline_max_regression (float | None)

gate_id: str | None
metric: str
aggregation: Literal['mean', 'minimum', 'maximum', 'percentile', 'count', 'pass_rate']
operator: Literal['>=', '>', '<=', '<', '==']
threshold: float
required: bool
percentile: float | None
baseline_max_regression: float | None
validate_gate()[source]

Keep percentile and numeric gate inputs deterministic.

Return type:

EvalGateConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EvalJudgeConfig(**data)[source]

Bases: _ConfigModel

Evaluator-agent or direct-model safety and budget policy.

Parameters:

  • agent (str | None)

  • model (str | None)

  • timeout_seconds (float)

  • max_attempts (int)

  • allow_self_evaluation (bool)

  • allowed_tools (tuple[str, ...])

  • tool_policy (Literal['evaluation_safe', 'read_only'])

  • allow_side_effects (bool)

  • hitl_mode (Literal['suspend', 'fail'])

  • max_input_tokens (int)

  • max_cost_usd (float)

  • rubric (str)

  • rubric_version (str)

  • judge_version (str)

agent: str | None
model: str | None
timeout_seconds: float
max_attempts: int
allow_self_evaluation: bool
allowed_tools: tuple[str, ...]
tool_policy: Literal['evaluation_safe', 'read_only']
allow_side_effects: bool
hitl_mode: Literal['suspend', 'fail']
max_input_tokens: int
max_cost_usd: float
rubric: str
rubric_version: str
judge_version: str
validate_subject()[source]

Require exactly one configured judge implementation.

Return type:

EvalJudgeConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EvalRagasConfig(**data)[source]

Bases: _ConfigModel

Configured Praval profiles used only by optional RAGAS metrics.

Parameters:

  • model (str | None)

  • embedding (str | None)

  • timeout_seconds (float)

  • strict_tool_order (bool)

model: str | None
embedding: str | None
timeout_seconds: float
strict_tool_order: bool
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EvalStoresConfig(**data)[source]

Bases: _ConfigModel

Named evaluation-store settings.

Parameters:
sqlite: SQLiteEvalStoreConfig
postgres: PostgresEvalStoreConfig | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.EvalSuiteConfig(**data)[source]

Bases: _ConfigModel

Offline or CI evaluation suite.

Parameters:

  • dataset (str)

  • target (str)

  • judges (tuple[str, ...])

  • metrics (tuple[str, ...])

  • gates (tuple[EvalGateConfig, ...])

dataset: str
target: str
judges: tuple[str, ...]
metrics: tuple[str, ...]
gates: tuple[EvalGateConfig, ...]
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.LocalObservabilityConfig(**data)[source]

Bases: _ConfigModel

Optional local-only diagnostic trace retention.

Parameters:

  • enabled (bool)

  • path (str)

  • max_traces (int)

  • max_age_days (int)

enabled: bool
path: str
max_traces: int
max_age_days: int
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.ModelProfileConfig(**data)[source]

Bases: _ConfigModel

Named foundation-model profile.

Parameters:

  • provider (str)

  • model (str)

  • temperature (float | None)

  • max_output_tokens (int | None)

provider: str
model: str
temperature: float | None
max_output_tokens: int | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.ObservabilityConfig(**data)[source]

Bases: _ConfigModel

Observability signal and privacy configuration.

The deprecated sample_rate, otlp_endpoint, and storage_path inputs remain accepted for the v0.8.2 migration window.

Parameters:

  • enabled (bool)

  • capture_content (bool)

  • content_allowlist (tuple[str, ...])

  • sampling (Literal['always_on', 'always_off', 'parentbased_traceidratio'])

  • sample_ratio (float)

  • flush_timeout_millis (int)

  • otlp (OTLPConfig)

  • local (LocalObservabilityConfig)

enabled: bool
capture_content: bool
content_allowlist: tuple[str, ...]
sampling: Literal['always_on', 'always_off', 'parentbased_traceidratio']
sample_ratio: float
flush_timeout_millis: int
otlp: OTLPConfig
local: LocalObservabilityConfig
classmethod map_legacy_fields(value)[source]

Map supported v0.8.2 field names to the typed nested schema.

Return type:

Any

Parameters:

value (Any)

property sample_rate: float

Return the deprecated sampling field.

property otlp_endpoint: str | None

Return the deprecated flat OTLP endpoint.

property storage_path: str

Return the deprecated expanded local path.

is_enabled()[source]

Return whether observability is enabled.

Return type:

bool

should_sample()[source]

Provide the v0.8.2 probabilistic sampling helper.

Return type:

bool

classmethod from_env()[source]

Load supported legacy observability environment variables.

Return type:

ObservabilityConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.OnlineEvalConfig(**data)[source]

Bases: _ConfigModel

Sampled online evaluation worker settings.

Parameters:

  • enabled (bool)

  • sample_ratio (float)

  • queue_capacity (int)

  • workers (int)

  • max_attempts (int)

  • max_enqueue_attempts (int)

  • lease_seconds (float)

  • job_timeout_seconds (float)

  • poll_interval_seconds (float)

  • retry_backoff_seconds (float)

  • shutdown_timeout_seconds (float)

  • max_subject_bytes (int)

enabled: bool
sample_ratio: float
queue_capacity: int
workers: int
max_attempts: int
max_enqueue_attempts: int
lease_seconds: float
job_timeout_seconds: float
poll_interval_seconds: float
retry_backoff_seconds: float
shutdown_timeout_seconds: float
max_subject_bytes: int
validate_worker_timing()[source]

Keep leases longer than the maximum active processor call.

Return type:

OnlineEvalConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.OTLPConfig(**data)[source]

Bases: _ConfigModel

OTLP transport and batching settings.

Parameters:

  • endpoint (str | None)

  • protocol (Literal['http/protobuf', 'grpc'])

  • traces (bool)

  • metrics (bool)

  • logs (bool)

  • headers_env (str | None)

  • max_queue_size (int)

  • max_export_batch_size (int)

  • schedule_delay_millis (int)

  • export_timeout_millis (int)

  • metric_export_interval_millis (int)

endpoint: str | None
protocol: Literal['http/protobuf', 'grpc']
traces: bool
metrics: bool
logs: bool
headers_env: str | None
max_queue_size: int
max_export_batch_size: int
schedule_delay_millis: int
export_timeout_millis: int
metric_export_interval_millis: int
validate_batch_bounds()[source]

Keep each export batch within its bounded queue.

Return type:

OTLPConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.PostgresEvalStoreConfig(**data)[source]

Bases: _ConfigModel

PostgreSQL evaluation-store secret reference.

Parameters:

dsn_env (str)

dsn_env: str
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.PravalConfig(**data)[source]

Bases: _ConfigModel

Complete schema-versioned Praval application configuration.

Parameters:
schema_version: Literal[1]
app: AppConfig
models: dict[str, ModelProfileConfig]
embeddings: dict[str, EmbeddingProfileConfig]
agents: dict[str, AgentProfileConfig]
observability: ObservabilityConfig
eval: EvalConfig
validate_references()[source]

Validate cross-section references before runtime work starts.

Return type:

PravalConfig

resolve_agent_profile(name, overrides=None)[source]

Resolve an agent over its named model and explicit overrides.

Return type:

ResolvedAgentConfig

Parameters:

  • name (str)

  • overrides (Mapping[str, Any] | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.ResolvedAgentConfig(**data)[source]

Bases: _ConfigModel

Resolved agent and model settings after precedence is applied.

Parameters:

  • name (str)

  • provider (str)

  • model (str)

  • temperature (float | None)

  • max_output_tokens (int | None)

  • system_message (str | None)

  • tools (tuple[str, ...])

  • memory_enabled (bool)

  • memory_namespace (str | None)

  • max_tool_rounds (int)

name: str
provider: str
model: str
temperature: float | None
max_output_tokens: int | None
system_message: str | None
tools: tuple[str, ...]
memory_enabled: bool
memory_namespace: str | None
max_tool_rounds: int
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

class praval.config.SQLiteEvalStoreConfig(**data)[source]

Bases: _ConfigModel

Local and CI evaluation-store location.

Parameters:

path (str)

path: str
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

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

praval.config.discover_config_path(start=None)[source]

Find the nearest praval.toml without reading user-home defaults.

Return type:

Path | None

Parameters:

start (Path | None)

praval.config.load_config(path=None, *, overrides=None, environ=None)[source]

Load and validate Praval configuration with documented precedence.

Return type:

PravalConfig

Parameters:

  • path (Path | str | None)

  • overrides (Mapping[str, Any] | None)

  • environ (Mapping[str, str] | None)