Configuration System
Palyra uses a TOML-based configuration system centered around theRootFileConfig schema. The configuration is loaded during daemon startup, supporting versioned migrations and sensitive data redaction.
RootFileConfig Schema
TheRootFileConfig struct defines the top-level sections of the palyra.toml file. Each field is optional, allowing the daemon to fall back to hardcoded defaults defined in crates/palyra-daemon/src/config/schema.rs.
| Section | Description |
|---|---|
deployment | Defines the environment mode (e.g., local_desktop, remote_vps) crates/palyra-common/src/daemon_config_schema.rs#85-88. |
daemon | Network binding settings for the internal HTTP server crates/palyra-common/src/daemon_config_schema.rs#92-95. |
gateway | gRPC and QUIC transport settings, including TLS and identity store paths crates/palyra-common/src/daemon_config_schema.rs#99-112. |
model_provider | Credentials and parameters for LLM and embedding providers crates/palyra-common/src/daemon_config_schema.rs#195-212. |
memory | Limits and retention policies for the RAG (Retrieval-Augmented Generation) system crates/palyra-common/src/daemon_config_schema.rs#145-151. |
Secret Redaction and Safety
To prevent accidental exposure of credentials in logs or exported configurations, Palyra implements a multi-layered redaction strategy.- Path-based Redaction: The
SECRET_CONFIG_PATHSconstant identifies specific TOML paths (e.g.,model_provider.openai_api_key) that must be overwritten with<redacted>before serialization crates/palyra-common/src/daemon_config_schema.rs#6-14. - Marker-based Redaction: The
is_sensitive_keyfunction checks for substrings likeapi_key,token,secret, orpasswordin any key name to trigger redaction crates/palyra-common/src/redaction.rs#5-28. - URL Redaction: The
redact_urlfunction strips user information (passwords) and sensitive query parameters from URLs crates/palyra-common/src/redaction.rs#63-86.
Model Provider Abstraction
TheModelProvider trait (and its implementation) abstracts the complexities of communicating with LLMs. It supports two primary modes: OpenAiCompatible and Deterministic.
ModelProvider Logic Flow
The following diagram bridges the high-level request to the internal implementation classes. Diagram: Model Provider Request Pipeline Sources: crates/palyra-daemon/src/model_provider.rs#32-35, crates/palyra-daemon/src/model_provider.rs#184-195Provider Types
- OpenAiCompatible: Targets any API following the OpenAI schema. It handles vision inputs (base64 encoding), tool calls (function calling), and streaming events crates/palyra-daemon/src/model_provider.rs#59-79.
- Deterministic: Used primarily for testing or highly constrained scenarios where a predictable output is required based on the input hash crates/palyra-daemon/src/model_provider.rs#41.
Reliability Patterns
TheModelProvider implementation includes built-in resilience features:
- Retries: Automatically retries on specific status codes (429, 500, 502, 503, 504) with configurable backoff crates/palyra-daemon/src/model_provider.rs#22.
- Circuit Breaker: Tracks consecutive failures. If the
circuit_breaker_failure_thresholdis reached, the provider “opens” and fails fast for the duration ofcircuit_breaker_cooldown_msto prevent overloading the upstream service crates/palyra-daemon/src/model_provider.rs#138-140.
Embeddings Provider
TheEmbeddingsProvider interface is responsible for converting text into high-dimensional vectors used for semantic search in the JournalStore.
Implementation Details
- Batching: Supports batching multiple strings into a single request, limited by
MAX_EMBEDDINGS_BATCH_SIZE(default 64) crates/palyra-daemon/src/model_provider.rs#25. - Constraints: Enforces a maximum input size of 256KiB per batch and 64KiB per single entry to prevent payload overflows crates/palyra-daemon/src/model_provider.rs#26-27.
- Deterministic Fallback: Provides a 64-dimensional deterministic embedding for environments without external API access crates/palyra-daemon/src/model_provider.rs#28.
Embeddings Data Flow
The system maps incoming text chunks to vector space for persistence. Diagram: Text to Embedding Mapping Sources: crates/palyra-daemon/src/model_provider.rs#198-208, crates/palyra-daemon/src/cron.rs#57-58Background Backfill
The daemon runs a background task defined incrates/palyra-daemon/src/cron.rs that identifies journal events missing embeddings and processes them in batches using the configured EmbeddingsProvider crates/palyra-daemon/src/cron.rs#57-58.
Sources: crates/palyra-daemon/src/cron.rs#57-58, crates/palyra-daemon/src/model_provider.rs#198-208