palyrad), the abstraction layer for LLM and embedding providers, and the background scheduling infrastructure.
Configuration System
Palyra uses a TOML-based configuration system centered around theRootFileConfig schema. The configuration is loaded at startup, supporting versioned migrations and sensitive value redaction.
RootFileConfig Schema
TheRootFileConfig struct defines the top-level sections of the palyra.toml file.
| Section | Description |
|---|---|
deployment | Defines environment mode (local_desktop vs remote_vps) crates/palyra-daemon/src/config/schema.rs#114-117. |
daemon | Network binding for the HTTP/Admin/Console server crates/palyra-common/src/daemon_config_schema.rs#92-95. |
gateway | gRPC and QUIC interface settings for agent communication crates/palyra-common/src/daemon_config_schema.rs#99-112. |
model_provider | LLM settings, including API keys and model selection crates/palyra-common/src/daemon_config_schema.rs#195-212. |
cron | Global scheduler settings (e.g., timezone) crates/palyra-common/src/daemon_config_schema.rs#133-135. |
storage | Database paths and persistence settings crates/palyra-daemon/src/config/schema.rs#253-257. |
Secret Redaction
To prevent accidental exposure of credentials in logs or diagnostic exports, the system implements a redaction mechanism.SECRET_CONFIG_PATHS: A hardcoded list of dot-notated paths (e.g.,model_provider.openai_api_key) that are considered sensitive crates/palyra-common/src/daemon_config_schema.rs#6-14.redact_secret_config_values: Iterates through a TOMLValueand replaces identified secrets with<redacted>crates/palyra-common/src/daemon_config_schema.rs#22-26.
Configuration Loading Flow
Theload_config() function in crates/palyra-daemon/src/config/load.rs orchestrates the discovery and parsing of the configuration file.
Config Loading Sequence
Sources: crates/palyra-daemon/src/config/load.rs#29-48, crates/palyra-daemon/src/config/load.rs#51-56.
Model and Embeddings Providers
Palyra abstracts LLM interactions through theModelProvider and EmbeddingsProvider traits, primarily supporting OpenAI-compatible APIs with built-in resilience.
Provider Abstractions
The system distinguishes between two primary provider kinds:- Deterministic: Used for testing or fixed-response scenarios crates/palyra-daemon/src/model_provider.rs#33.
- OpenAiCompatible: The standard provider for GPT-style models crates/palyra-daemon/src/model_provider.rs#34.
OpenAI-Compatible Implementation
TheOpenAiCompatible provider implements chat/completions and embeddings endpoints. It includes a sophisticated request pipeline:
- Circuit Breaker: Tracks failures and enters a “cooldown” state if the
circuit_breaker_failure_thresholdis exceeded crates/palyra-daemon/src/model_provider.rs#138-139. - Retry Logic: Automatically retries on specific status codes (429, 500, 502, 503, 504) with exponential backoff crates/palyra-daemon/src/model_provider.rs#22.
- Vision Support: Detects
vision_inputsin aProviderRequestand formats the payload as a multi-part content array for models likegpt-4ocrates/palyra-daemon/src/model_provider.rs#59-79.
Credential Sources
API keys can be sourced from multiple locations, prioritized by theModelProviderCredentialSource enum:
InlineConfig: Directly frompalyra.toml.VaultRef: Referenced by a key in the encryptedpalyra-vault.AuthProfile: Associated with a specific user or principal identity.
Background Scheduler (Cron and Routines)
Thecron module handles periodic tasks, while routines provide a higher-level abstraction for agentic workflows triggered by schedules or events.
The Cron Scheduler
The scheduler runs a background loop that evaluates job readiness every 15 seconds (SCHEDULER_IDLE_SLEEP) crates/palyra-daemon/src/cron.rs#42.
Cron Matcher Logic
The CronMatcher parses standard 5-field cron expressions (minute, hour, day, month, weekday) crates/palyra-daemon/src/cron.rs#140-156. It supports both Utc and Local timezone modes crates/palyra-daemon/src/cron.rs#60-65.
Routine Execution
Routines extend the scheduler by adding metadata, delivery policies, and approval gates.| Component | Role |
|---|---|
RoutineTriggerKind | Defines what starts the routine (Schedule, Webhook, Manual, etc.) crates/palyra-daemon/src/routines.rs#35-41. |
RoutineDeliveryMode | Controls where the agent’s output is sent (SameChannel, SpecificChannel, LogsOnly) crates/palyra-daemon/src/routines.rs#69-74. |
RoutineApprovalMode | Defines human-in-the-loop requirements (BeforeEnable, BeforeFirstRun) crates/palyra-daemon/src/routines.rs#125-129. |
System Maintenance Routines
The daemon schedules internal maintenance tasks via the same infrastructure:- Memory Maintenance: Runs every 5 minutes (
MEMORY_MAINTENANCE_INTERVAL) crates/palyra-daemon/src/cron.rs#56. - Embeddings Backfill: Periodically processes un-embedded journal entries crates/palyra-daemon/src/cron.rs#57.