Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
use anyhow::{Context, Result};
use serde::Deserialize;
use std::path::Path;
#[derive(Debug, Deserialize)]
#[serde(default)]
#[derive(Default)]
pub struct Config {
pub general: GeneralConfig,
pub embeddings: EmbeddingsConfig,
pub language: LanguageConfig,
pub cache: CacheConfig,
pub storage: StorageConfig,
pub tools: ToolsConfig,
pub webhook: WebhookConfig,
pub http: HttpConfig,
pub monitor: MonitorConfig,
pub reasoner: ReasonerConfig,
pub feedback: FeedbackConfig,
pub imports: ImportsConfig,
pub repo: RepoConfig,
pub socket: SocketConfig,
pub logging: LoggingConfig,
}
impl Config {
pub fn load(path: &Path) -> Result<Self> {
let contents = std::fs::read_to_string(path)
.with_context(|| format!("failed to read config file: {}", path.display()))?;
let config: Config = toml::from_str(&contents)
.with_context(|| format!("failed to parse config file: {}", path.display()))?;
Ok(config)
}
}
#[derive(Debug, Deserialize)]
#[serde(default)]
pub struct GeneralConfig {
pub data_dir: String,
/// Directories that act as on-disk ontology repositories. The
/// `onto_repo_list` and `onto_repo_load` MCP tools enumerate and load
/// RDF files (.ttl, .nt, .rdf, .owl, .nq, .trig, .jsonld) from these
/// directories. Useful for containerized deployments where a host
/// directory of TTL files is mounted into the server.
///
/// Accepts either a TOML array under the canonical name `ontology_dirs`
/// or, for compatibility with the original design proposal, the alias
/// `data_dirs`. Each entry has `~` expanded to the user's home.
#[serde(alias = "data_dirs")]
pub ontology_dirs: Vec<String>,
}
impl Default for GeneralConfig {
fn default() -> Self {
Self {
data_dir: "~/.open-ontologies".into(),
ontology_dirs: Vec::new(),
}
}
}
/// Resolve the configured ontology repository directories.
///
/// Behavior:
/// - If the env var `OPEN_ONTOLOGIES_ONTOLOGY_DIRS` is set and non-empty,
/// its value (split on `:` on Unix, `;` on Windows, accepting either on
/// both for convenience) overrides the config entries.
/// - Each entry has `~` expanded.
/// - Empty strings are dropped.
/// - Duplicates (after canonicalization fallback to the expanded string)
/// are removed while preserving order.
pub fn resolve_ontology_dirs(cfg: &[String]) -> Vec<std::path::PathBuf> {
let from_env = std::env::var("OPEN_ONTOLOGIES_ONTOLOGY_DIRS").ok();
let raw: Vec<String> = match from_env {
Some(v) if !v.trim().is_empty() => v
.split([':', ';'])
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect(),
_ => cfg
.iter()
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect(),
};
let mut seen = std::collections::HashSet::new();
let mut out = Vec::with_capacity(raw.len());
for entry in raw {
let expanded = expand_tilde(&entry);
let key = std::fs::canonicalize(&expanded)
.map(|p| p.to_string_lossy().into_owned())
.unwrap_or_else(|_| expanded.clone());
if seen.insert(key) {
out.push(std::path::PathBuf::from(expanded));
}
}
out
}
#[derive(Debug, Default, Deserialize, Clone)]
#[serde(default)]
pub struct EmbeddingsConfig {
/// Embedding provider: "local" (default — ONNX model on disk) or "openai"
/// (any OpenAI-compatible HTTP API, e.g. OpenAI, Azure OpenAI, Ollama,
/// vLLM, LM Studio, LocalAI, Together, etc.). Override at runtime with
/// `OPEN_ONTOLOGIES_EMBEDDINGS_PROVIDER`.
pub provider: Option<String>,
/// Path to the ONNX model file (provider = "local" only).
/// Default: ~/.open-ontologies/models/paraphrase-multilingual-MiniLM-L12-v2.onnx
/// (falls back to a legacy bge-small-en-v1.5.onnx if that is what is on disk).
pub model_path: Option<String>,
/// Path to the tokenizer.json file (provider = "local" only).
/// Default: ~/.open-ontologies/models/tokenizer.json
pub tokenizer_path: Option<String>,
/// URL to download the ONNX model from. Default: multilingual MiniLM-L12-v2 from Hugging Face
pub model_url: Option<String>,
/// URL to download the tokenizer from. Default: multilingual MiniLM-L12-v2 tokenizer from Hugging Face
pub tokenizer_url: Option<String>,
/// Filename for the downloaded model. Default: paraphrase-multilingual-MiniLM-L12-v2.onnx
pub model_name: Option<String>,
// ─── OpenAI-compatible provider (provider = "openai") ───────────────
/// Base URL of the OpenAI-compatible API, without the trailing
/// `/embeddings` path. Default: `https://api.openai.com/v1`. Override
/// at runtime with `OPEN_ONTOLOGIES_EMBEDDINGS_API_BASE`.
#[serde(alias = "base_url")]
pub api_base: Option<String>,
/// API key. If unset, falls back to the `OPEN_ONTOLOGIES_EMBEDDINGS_API_KEY`
/// or `OPENAI_API_KEY` env var. Sent as `Authorization: Bearer <key>`.
/// Optional — gateways that don't require auth (Ollama, LocalAI,
/// vLLM behind a private network, …) can leave this unset.
pub api_key: Option<String>,
/// Model name to request, e.g. `text-embedding-3-small`,
/// `text-embedding-3-large`, `text-embedding-ada-002`, or any model
/// served by an OpenAI-compatible gateway. Default:
/// `text-embedding-3-small`. Override with
/// `OPEN_ONTOLOGIES_EMBEDDINGS_MODEL`.
pub model: Option<String>,
/// Optional `dimensions` parameter sent in the request body. Lets you
/// truncate output dimensionality on models that support it
/// (text-embedding-3-*). When unset, the API's default dimension is
/// used and detected from the first response.
pub dimensions: Option<usize>,
/// HTTP request timeout in seconds. Default: 30.
pub request_timeout_secs: Option<u64>,
}
/// Configuration for the on-disk N-Triples compile cache and TTL eviction.
/// Resolve the configured embedding provider name.
///
/// Precedence: `OPEN_ONTOLOGIES_EMBEDDINGS_PROVIDER` env var > config field >
/// default ("local"). Returns a lowercased, trimmed string.
pub fn resolve_embeddings_provider(cfg: &EmbeddingsConfig) -> String {
let raw = std::env::var("OPEN_ONTOLOGIES_EMBEDDINGS_PROVIDER")
.ok()
.filter(|v| !v.trim().is_empty())
.or_else(|| cfg.provider.clone())
.unwrap_or_else(|| "local".to_string());
raw.trim().to_lowercase()
}
/// Resolve the OpenAI-compatible API base URL.
///
/// Precedence: `OPEN_ONTOLOGIES_EMBEDDINGS_API_BASE` env var > config >
/// `https://api.openai.com/v1`. Trailing slashes are stripped.
pub fn resolve_embeddings_api_base(cfg: &EmbeddingsConfig) -> String {
let raw = std::env::var("OPEN_ONTOLOGIES_EMBEDDINGS_API_BASE")
.ok()
.filter(|v| !v.trim().is_empty())
.or_else(|| cfg.api_base.clone())
.unwrap_or_else(|| "https://api.openai.com/v1".to_string());
raw.trim().trim_end_matches('/').to_string()
}
/// Resolve the OpenAI-compatible API key.
///
/// Precedence: `OPEN_ONTOLOGIES_EMBEDDINGS_API_KEY` env var >
/// `OPENAI_API_KEY` env var > config. Returns `None` if no key is configured
/// (some local OpenAI-compatible gateways accept unauthenticated requests).
pub fn resolve_embeddings_api_key(cfg: &EmbeddingsConfig) -> Option<String> {
std::env::var("OPEN_ONTOLOGIES_EMBEDDINGS_API_KEY")
.ok()
.filter(|v| !v.trim().is_empty())
.or_else(|| {
std::env::var("OPENAI_API_KEY")
.ok()
.filter(|v| !v.trim().is_empty())
})
.or_else(|| cfg.api_key.clone().filter(|v| !v.trim().is_empty()))
}
/// Resolve the OpenAI-compatible model name.
///
/// Precedence: `OPEN_ONTOLOGIES_EMBEDDINGS_MODEL` env var > config >
/// `text-embedding-3-small`.
pub fn resolve_embeddings_model(cfg: &EmbeddingsConfig) -> String {
std::env::var("OPEN_ONTOLOGIES_EMBEDDINGS_MODEL")
.ok()
.filter(|v| !v.trim().is_empty())
.or_else(|| cfg.model.clone().filter(|v| !v.trim().is_empty()))
.unwrap_or_else(|| "text-embedding-3-small".to_string())
}
/// `[language]` — natural-language policy for ontology labels used in
/// alignment / matching.
#[derive(Debug, Default, Deserialize, Clone)]
#[serde(default)]
pub struct LanguageConfig {
/// Preferred natural-language tags (BCP-47, e.g. `["en", "cy"]`) for the
/// `rdfs:label` / `skos:prefLabel` / `skos:altLabel` values consulted by
/// `onto_align`. Untagged (plain or datatyped) literals are always kept.
///
/// An empty list (the default) keeps **all** languages — i.e. fully
/// multilingual matching. This only pays off when paired with a
/// multilingual embedding model (the default `onto_embed` model is
/// multilingual), because cross-lingual matches (`Dog`↔`Chien`) are carried
/// by the embedding signal, not by string similarity.
///
/// Override at runtime with `OPEN_ONTOLOGIES_LANGUAGES` (comma / colon /
/// semicolon separated, e.g. `OPEN_ONTOLOGIES_LANGUAGES=en,fr`).
#[serde(alias = "preferred_languages")]
pub preferred: Vec<String>,
}
/// Resolve the preferred-language policy.
///
/// Precedence: `OPEN_ONTOLOGIES_LANGUAGES` env var > config field. Entries are
/// trimmed, lowercased, and emptied entries dropped. An empty result means
/// "keep all languages" (multilingual mode).
pub fn resolve_languages(cfg: &LanguageConfig) -> Vec<String> {
let from_env = std::env::var("OPEN_ONTOLOGIES_LANGUAGES").ok();
let raw: Vec<String> = match from_env {
Some(v) if !v.trim().is_empty() => v
.split([',', ':', ';'])
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect(),
_ => cfg
.preferred
.iter()
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
.collect(),
};
raw.into_iter().map(|s| s.to_lowercase()).collect()
}
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct CacheConfig {
/// Master switch for the compile cache. When false, every load re-parses
/// from source and no metadata is recorded.
pub enabled: bool,
/// Directory where N-Triples cache files are stored.
pub dir: String,
/// If > 0, the active ontology will be unloaded from memory after this
/// many seconds without access. The cache file is preserved and reloaded
/// automatically on the next query.
///
/// Accepts either canonical name `idle_ttl_secs` or the more descriptive
/// alias `unload_timeout_secs` — both populate the same field.
#[serde(alias = "unload_timeout_secs")]
pub idle_ttl_secs: u64,
/// How often the background evictor checks idle entries (seconds).
pub evictor_interval_secs: u64,
/// When true, every read tool checks the source file's mtime/sha and
/// recompiles if it changed. Off by default for predictability.
pub auto_refresh: bool,
/// Number of bytes from the head of a source ontology file that are
/// hashed (sha256) to form the cache fingerprint tie-breaker. Larger
/// values reduce collision probability for very large dumps where many
/// files share an identical leading region (e.g. `@prefix` headers in
/// big N-Quads exports). Default 64 KiB.
pub hash_prefix_bytes: usize,
}
impl Default for CacheConfig {
fn default() -> Self {
Self {
enabled: true,
dir: "~/.open-ontologies/cache".into(),
idle_ttl_secs: 0,
evictor_interval_secs: 30,
auto_refresh: false,
hash_prefix_bytes: 64 * 1024,
}
}
}
/// `[storage]` — backend for the main triple store.
///
/// `"memory"` (default) keeps the active ontology in RAM only — fast, but
/// every restart starts empty. `"persistent"` opens a RocksDB-backed
/// Oxigraph store at `<data_dir>/triplestore`, so triples survive restarts
/// and the one-shot CLI subcommands (`load` then `query`) share state.
///
/// Override the mode at runtime with `OPEN_ONTOLOGIES_STORAGE_MODE`.
///
/// Oxigraph allows only one read-write handle on a persistent store at a
/// time — running two server processes against the same `data_dir` will
/// fail to open the second store.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct StorageConfig {
/// `"memory"` or `"persistent"`. Default `"memory"`.
pub mode: String,
}
impl Default for StorageConfig {
fn default() -> Self {
Self {
mode: "memory".into(),
}
}
}
/// Storage backend selected for the main graph.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StorageMode {
Memory,
Persistent,
}
/// Resolve the storage mode.
///
/// Precedence: `OPEN_ONTOLOGIES_STORAGE_MODE` env var > config > default
/// (`memory`). Unknown values fall back to `memory` with a warning printed to
/// stderr — preserves the historical in-memory behaviour for typos.
pub fn resolve_storage_mode(cfg: &StorageConfig) -> StorageMode {
let from_env = std::env::var("OPEN_ONTOLOGIES_STORAGE_MODE").ok();
resolve_storage_mode_from(from_env.as_deref(), cfg)
}
/// Resolve the storage mode from an explicitly supplied override.
///
/// This is the pure half of [`resolve_storage_mode`]: it takes the override
/// string rather than reading the environment, so every branch can be
/// exercised without mutating process-global state.
///
/// That matters more than it looks. `std::env::set_var` and `remove_var` are
/// `unsafe` in edition 2024 because the environment is shared mutable state
/// with no synchronisation, and cargo runs the test functions within a test
/// binary on parallel threads. A test that mutates the variable while another
/// thread is inside `std::env::var` is a data race, whether or not it happens
/// to pass. Testing against this function instead of the environment removes
/// the hazard rather than narrowing the window.
pub fn resolve_storage_mode_from(
raw_override: Option<&str>,
cfg: &StorageConfig,
) -> StorageMode {
let raw = raw_override
.map(str::to_owned)
.filter(|v| !v.trim().is_empty())
.unwrap_or_else(|| cfg.mode.clone());
match raw.trim().to_lowercase().as_str() {
"memory" | "mem" | "in-memory" | "" => StorageMode::Memory,
"persistent" | "disk" | "rocksdb" => StorageMode::Persistent,
other => {
eprintln!(
"warning: unknown [storage] mode {:?}; falling back to \"memory\"",
other
);
StorageMode::Memory
}
}
}
/// The tool profile in force.
///
/// Precedence is the one every other setting in this file uses: CLI > env >
/// config > default. An empty string at any level means "not set" and falls
/// through, and the default is `full`, so an untouched deployment is unaffected.
pub fn resolve_tool_profile(cfg: &ToolsConfig, cli: Option<&str>) -> String {
let from_env = std::env::var("OPEN_ONTOLOGIES_TOOL_PROFILE").ok();
resolve_tool_profile_from(cfg, cli, from_env.as_deref())
}
/// The pure half of [`resolve_tool_profile`], for the same reason
/// [`resolve_storage_mode_from`] exists: the environment is shared mutable
/// state, `set_var` is `unsafe` in edition 2024, and cargo runs the tests in
/// one binary on parallel threads. Every branch is exercised through this
/// function so no test has to touch the process environment.
pub fn resolve_tool_profile_from(
cfg: &ToolsConfig,
cli: Option<&str>,
env: Option<&str>,
) -> String {
[cli, env, Some(cfg.profile.as_str())]
.into_iter()
.flatten()
.map(str::trim)
.find(|s| !s.is_empty())
.unwrap_or(crate::toolfilter::FULL)
.to_string()
}
/// Configuration for limiting which MCP tools are exposed.
#[derive(Debug, Deserialize, Clone, Default)]
#[serde(default)]
pub struct ToolsConfig {
/// "all" (default), "allow", or "deny".
pub mode: String,
/// Explicit tool names included by the filter.
pub list: Vec<String>,
/// Group names (e.g. "read_only") expanded into tool names.
pub groups: Vec<String>,
/// Task profile: `full` (default) or one of the names `toolfilter::profiles()`
/// lists. Empty means `full`. Override with `--tool-profile` or
/// `OPEN_ONTOLOGIES_TOOL_PROFILE`.
pub profile: String,
}
/// Expand a leading `~` in a path to the user's home directory.
pub fn expand_tilde(path: &str) -> String {
if path.starts_with("~/") || path == "~" {
let home = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE"));
if let Some(home) = home {
return path.replacen("~", &home.to_string_lossy(), 1);
}
}
path.to_string()
}
// ─── New section configs ────────────────────────────────────────────────
/// `[webhook]` — outbound HTTP for governance / monitor alerts.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct WebhookConfig {
/// HTTP timeout (seconds) for governance / monitor webhook deliveries.
/// Override at runtime with `OPEN_ONTOLOGIES_WEBHOOK_REQUEST_TIMEOUT_SECS`.
pub request_timeout_secs: u64,
}
impl Default for WebhookConfig {
fn default() -> Self {
Self {
request_timeout_secs: 10,
}
}
}
/// `[http]` — Streamable HTTP transport (`serve-http`).
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct HttpConfig {
/// Bind host. Default `127.0.0.1`. CLI `--host` and the
/// `OPEN_ONTOLOGIES_HTTP_HOST` env var take precedence.
pub host: String,
/// Bind port. Default `8080`. CLI `--port` and the
/// `OPEN_ONTOLOGIES_HTTP_PORT` env var take precedence.
pub port: u16,
/// Optional bearer token for authentication. Empty string ⇒ disabled.
/// CLI `--token` and `OPEN_ONTOLOGIES_TOKEN` env var take precedence.
pub token: String,
/// Whether the rmcp `StreamableHttpServer` keeps per-session state.
/// Default `true` (matches existing behaviour).
pub stateful_mode: bool,
/// Per-request HTTP timeout in seconds. `0` ⇒ no explicit cap (rmcp
/// default). Override with `OPEN_ONTOLOGIES_HTTP_REQUEST_TIMEOUT_SECS`.
pub request_timeout_secs: u64,
/// HTTP keep-alive timeout in seconds. `0` ⇒ no explicit cap.
pub keep_alive_secs: u64,
}
impl Default for HttpConfig {
fn default() -> Self {
Self {
host: "127.0.0.1".into(),
port: 8080,
token: String::new(),
stateful_mode: true,
request_timeout_secs: 0,
keep_alive_secs: 0,
}
}
}
/// `[monitor]` — continuous watcher loop.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct MonitorConfig {
/// When true, start the background monitor loop on `serve` / `serve-http`.
/// Equivalent to passing `--watch`. Default `false`.
pub enabled: bool,
/// Interval in seconds between monitor sweeps. Default `30`.
/// Override with `OPEN_ONTOLOGIES_MONITOR_INTERVAL_SECS`.
#[serde(alias = "watch_interval_secs")]
pub interval_secs: u64,
}
impl Default for MonitorConfig {
fn default() -> Self {
Self {
enabled: false,
interval_secs: 30,
}
}
}
/// `[reasoner]` — RDFS / OWL-RL fixpoint and DL tableaux limits.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct ReasonerConfig {
/// Tableaux DL reasoner: max recursion depth before giving up. Default 100.
pub tableaux_max_depth: usize,
/// Tableaux DL reasoner: max nodes in a model before giving up.
/// Default 10 000. Increase for very large ontologies; raising this past
/// ~100 000 typically indicates the ontology is unsatisfiable in
/// pathological ways and the reasoner should bail out anyway.
pub tableaux_max_nodes: usize,
/// RDFS / OWL-RL fixpoint guard. Maximum number of expansion iterations
/// before the reasoner returns the partial closure. Default 64.
pub max_iterations: usize,
/// Tableaux DL reasoner: wall-clock budget for one PHASE of a run, in
/// milliseconds. Default 10 000. **`0` means no limit**, unlike the three
/// caps above, where 0 means "unset, use the default": a depth cap of zero
/// is not a configuration anybody wants and a timeout of zero is.
///
/// This is the budget that actually expires on a hard ontology. A run has
/// five phases — consistency, satisfiability, subsumption, ABox, explanation
/// — and each opens one of these, so the worst case for a run is five times
/// this number or `classify_timeout_ms`, whichever is smaller.
pub tableaux_test_timeout_ms: usize,
/// Tableaux DL reasoner: wall-clock CEILING for a whole run, in
/// milliseconds. Default 180 000, the ORE competition convention. **`0`
/// means no ceiling.**
///
/// Enforced over every phase, and at the default it is not expected to be
/// the bound that fires, because five phases at 10 000 ms bound the tableau
/// work at 50 000 ms first. Set it below that to make it the expected one.
/// Every `owl-dl` run reports, in its `budget` block, both the bound these
/// settings predict (`configured_bound`) and the one that actually stopped
/// it (`binding_bound`), so neither has to be worked out from two numbers.
///
/// NEITHER of these two existed here until the budget was audited. They were
/// process-wide statics with setters for tests and, for the phase budget, one
/// CLI flag; three comments in `src/tableaux.rs` referred to
/// "`[reasoner] classify_timeout_ms`" as though it were a setting. A ceiling
/// nobody can lower is the strongest form of a limit that enforces nothing.
pub classify_timeout_ms: usize,
}
impl Default for ReasonerConfig {
fn default() -> Self {
Self {
tableaux_max_depth: 100,
tableaux_max_nodes: 10_000,
max_iterations: 64,
tableaux_test_timeout_ms: 10_000,
classify_timeout_ms: 180_000,
}
}
}
/// `[feedback]` — lint / enforce self-calibration thresholds.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct FeedbackConfig {
/// Number of consecutive dismissals after which a lint/enforce issue
/// is fully suppressed for that (tool, rule_id, entity) tuple: moved to
/// the output's `suppressed[]` list. Errors are exempt. Default 3.
pub suppress_threshold: i64,
/// Number of consecutive dismissals after which a lint/enforce issue
/// is downgraded one severity level (warning to info; errors are exempt).
/// Must be `< suppress_threshold` to take effect. Default 2.
pub downgrade_threshold: i64,
}
impl Default for FeedbackConfig {
fn default() -> Self {
Self {
suppress_threshold: 3,
downgrade_threshold: 2,
}
}
}
/// `[imports]` — `owl:imports` resolution policy.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct ImportsConfig {
/// Maximum transitive depth to follow when resolving owl:imports. The
/// `onto_import` tool's `max_depth` parameter (when supplied) overrides
/// this. Default 3.
pub max_depth: usize,
/// HTTP timeout in seconds for fetching each remote import. Set to `0`
/// to disable the explicit per-call timeout and use reqwest's default
/// (which itself has no timeout). Override with
/// `OPEN_ONTOLOGIES_IMPORTS_REQUEST_TIMEOUT_SECS`.
pub request_timeout_secs: u64,
/// When false, remote (`http(s)://`) imports are refused — useful in
/// air-gapped or sandboxed deployments. Default `true`.
pub follow_remote: bool,
}
impl Default for ImportsConfig {
fn default() -> Self {
Self {
max_depth: 3,
request_timeout_secs: 30,
follow_remote: true,
}
}
}
/// `[repo]` — on-disk ontology repository tools.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct RepoConfig {
/// Default `limit` for `onto_repo_list` when the caller doesn't supply
/// one. Default 1000.
pub default_list_limit: usize,
}
impl Default for RepoConfig {
fn default() -> Self {
Self {
default_list_limit: 1000,
}
}
}
/// `[socket]` — Unix domain socket adapter for Tardygrada fact grounding.
#[derive(Debug, Deserialize, Clone, Default)]
#[serde(default)]
pub struct SocketConfig {
/// When true, `serve` / `serve-http` will additionally start the unix
/// socket adapter. Currently the dedicated `serve-unix` subcommand reads
/// these defaults. Default `false`.
pub enabled: bool,
/// Default socket path for `serve-unix`. CLI `--socket` overrides.
pub path: Option<String>,
/// Default ontology files to preload on `serve-unix` startup.
/// CLI `--file` (repeatable) overrides.
pub preload_files: Vec<String>,
}
/// `[logging]` — tracing subscriber configuration.
#[derive(Debug, Deserialize, Clone)]
#[serde(default)]
pub struct LoggingConfig {
/// Default log directives (e.g. `info`, `debug`,
/// `open_ontologies=debug,reqwest=warn`). The `RUST_LOG` env var, when
/// set, takes precedence over this value.
pub level: String,
/// Output format: `compact` (default), `pretty`, or `json`.
pub format: String,
/// Optional path to write logs to. When unset, logs go to stderr.
pub file: Option<String>,
}
impl Default for LoggingConfig {
fn default() -> Self {
Self {
level: "info".into(),
format: "compact".into(),
file: None,
}
}
}
// ─── Env-override resolvers for the most operationally critical fields ──
/// Resolve the webhook request timeout. Precedence:
/// `OPEN_ONTOLOGIES_WEBHOOK_REQUEST_TIMEOUT_SECS` > config > default.
pub fn resolve_webhook_timeout_secs(cfg: &WebhookConfig) -> u64 {
parse_env_u64("OPEN_ONTOLOGIES_WEBHOOK_REQUEST_TIMEOUT_SECS")
.unwrap_or(cfg.request_timeout_secs)
}
/// Resolve the imports request timeout. Precedence:
/// `OPEN_ONTOLOGIES_IMPORTS_REQUEST_TIMEOUT_SECS` > config > default.
pub fn resolve_imports_timeout_secs(cfg: &ImportsConfig) -> u64 {
parse_env_u64("OPEN_ONTOLOGIES_IMPORTS_REQUEST_TIMEOUT_SECS")
.unwrap_or(cfg.request_timeout_secs)
}
/// Resolve the monitor sweep interval. Precedence:
/// `OPEN_ONTOLOGIES_MONITOR_INTERVAL_SECS` > config > default.
pub fn resolve_monitor_interval_secs(cfg: &MonitorConfig) -> u64 {
parse_env_u64("OPEN_ONTOLOGIES_MONITOR_INTERVAL_SECS").unwrap_or(cfg.interval_secs)
}
/// Resolve the HTTP bind host. Precedence:
/// `OPEN_ONTOLOGIES_HTTP_HOST` > config > default.
pub fn resolve_http_host(cfg: &HttpConfig) -> String {
std::env::var("OPEN_ONTOLOGIES_HTTP_HOST")
.ok()
.filter(|v| !v.trim().is_empty())
.unwrap_or_else(|| cfg.host.clone())
}
/// Resolve the HTTP bind port. Precedence:
/// `OPEN_ONTOLOGIES_HTTP_PORT` > config > default.
pub fn resolve_http_port(cfg: &HttpConfig) -> u16 {
std::env::var("OPEN_ONTOLOGIES_HTTP_PORT")
.ok()
.and_then(|v| v.trim().parse::<u16>().ok())
.unwrap_or(cfg.port)
}
/// Resolve the HTTP bearer token. Precedence:
/// `OPEN_ONTOLOGIES_TOKEN` > config (if non-empty) > `None`.
pub fn resolve_http_token(cfg: &HttpConfig) -> Option<String> {
std::env::var("OPEN_ONTOLOGIES_TOKEN")
.ok()
.filter(|v| !v.trim().is_empty())
.or_else(|| Some(cfg.token.clone()).filter(|v| !v.trim().is_empty()))
}
/// Resolve the logging directives. Precedence: `RUST_LOG` > config > default.
pub fn resolve_logging_level(cfg: &LoggingConfig) -> String {
std::env::var("RUST_LOG")
.ok()
.filter(|v| !v.trim().is_empty())
.unwrap_or_else(|| cfg.level.clone())
}
fn parse_env_u64(var: &str) -> Option<u64> {
std::env::var(var)
.ok()
.and_then(|v| v.trim().parse::<u64>().ok())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_openai_provider_block() {
let toml_src = r#"
[embeddings]
provider = "openai"
api_base = "https://api.example.com/v1/"
api_key = "sk-test"
model = "text-embedding-3-large"
dimensions = 256
request_timeout_secs = 60
"#;
let cfg: Config = toml::from_str(toml_src).expect("parse");
assert_eq!(cfg.embeddings.provider.as_deref(), Some("openai"));
assert_eq!(cfg.embeddings.api_key.as_deref(), Some("sk-test"));
assert_eq!(cfg.embeddings.dimensions, Some(256));
assert_eq!(cfg.embeddings.request_timeout_secs, Some(60));
// Trailing slash is stripped by the resolver.
assert_eq!(
resolve_embeddings_api_base(&cfg.embeddings),
"https://api.example.com/v1"
);
assert_eq!(resolve_embeddings_provider(&cfg.embeddings), "openai");
assert_eq!(
resolve_embeddings_model(&cfg.embeddings),
"text-embedding-3-large"
);
}
#[test]
fn provider_defaults_to_local_when_unset() {
// Verify the default-resolution logic without touching process-wide
// env vars (which would race with other tests). When the env override
// is absent the function should fall back to the config field, then
// to "local".
let cfg = EmbeddingsConfig::default();
let resolved = cfg
.provider
.clone()
.unwrap_or_else(|| "local".to_string())
.trim()
.to_lowercase();
assert_eq!(resolved, "local");
}
#[test]
fn language_section_parses_and_defaults_to_multilingual() {
// Empty / absent => keep all languages.
let cfg: Config = toml::from_str("").expect("parse empty");
assert!(cfg.language.preferred.is_empty());
let toml_src = r#"
[language]
preferred = ["en", "CY"]
"#;
let cfg: Config = toml::from_str(toml_src).expect("parse");
assert_eq!(cfg.language.preferred, vec!["en", "CY"]);
// Resolver lowercases (env var unset in this path).
if std::env::var("OPEN_ONTOLOGIES_LANGUAGES").is_err() {
assert_eq!(resolve_languages(&cfg.language), vec!["en", "cy"]);
}
// Alias `preferred_languages` also populates the field.
let aliased: Config = toml::from_str(
"[language]\npreferred_languages = [\"fr\"]\n",
)
.expect("parse alias");
assert_eq!(aliased.language.preferred, vec!["fr"]);
}
#[test]
fn base_url_alias_accepted() {
// The legacy/alternative `base_url` key should also populate
// `api_base` via serde alias.
let toml_src = r#"
[embeddings]
base_url = "http://localhost:11434/v1"
"#;
let cfg: Config = toml::from_str(toml_src).expect("parse");
assert_eq!(
cfg.embeddings.api_base.as_deref(),
Some("http://localhost:11434/v1")
);
}
#[test]
fn unload_timeout_alias_for_idle_ttl() {
let toml_src = r#"
[cache]
unload_timeout_secs = 120
hash_prefix_bytes = 131072
"#;
let cfg: Config = toml::from_str(toml_src).expect("parse");
assert_eq!(cfg.cache.idle_ttl_secs, 120);
assert_eq!(cfg.cache.hash_prefix_bytes, 131072);
}
#[test]
fn new_sections_parse_with_defaults() {
let toml_src = r#"
[webhook]
request_timeout_secs = 5
[http]
host = "0.0.0.0"
port = 9000
stateful_mode = false
[monitor]
enabled = true
interval_secs = 15
[reasoner]
tableaux_max_depth = 200
tableaux_max_nodes = 50000
max_iterations = 128
[feedback]
suppress_threshold = 5
downgrade_threshold = 3
[imports]
max_depth = 5
request_timeout_secs = 60
follow_remote = false
[repo]
default_list_limit = 250
[socket]
enabled = true
path = "/tmp/foo.sock"
preload_files = ["a.ttl", "b.ttl"]
[logging]
level = "debug"
format = "json"
"#;
let cfg: Config = toml::from_str(toml_src).expect("parse");
assert_eq!(cfg.webhook.request_timeout_secs, 5);
assert_eq!(cfg.http.host, "0.0.0.0");
assert_eq!(cfg.http.port, 9000);
assert!(!cfg.http.stateful_mode);
assert!(cfg.monitor.enabled);
assert_eq!(cfg.monitor.interval_secs, 15);
assert_eq!(cfg.reasoner.tableaux_max_depth, 200);
assert_eq!(cfg.reasoner.tableaux_max_nodes, 50_000);
assert_eq!(cfg.reasoner.max_iterations, 128);
assert_eq!(cfg.feedback.suppress_threshold, 5);
assert_eq!(cfg.feedback.downgrade_threshold, 3);
assert_eq!(cfg.imports.max_depth, 5);
assert_eq!(cfg.imports.request_timeout_secs, 60);
assert!(!cfg.imports.follow_remote);
assert_eq!(cfg.repo.default_list_limit, 250);
assert!(cfg.socket.enabled);
assert_eq!(cfg.socket.path.as_deref(), Some("/tmp/foo.sock"));
assert_eq!(cfg.socket.preload_files, vec!["a.ttl", "b.ttl"]);
assert_eq!(cfg.logging.level, "debug");
assert_eq!(cfg.logging.format, "json");
}
#[test]
fn new_sections_default_when_absent() {
let cfg: Config = toml::from_str("").expect("parse empty");
assert_eq!(cfg.webhook.request_timeout_secs, 10);
assert_eq!(cfg.http.host, "127.0.0.1");
assert_eq!(cfg.http.port, 8080);
assert!(cfg.http.stateful_mode);
assert!(!cfg.monitor.enabled);
assert_eq!(cfg.monitor.interval_secs, 30);
assert_eq!(cfg.reasoner.tableaux_max_depth, 100);
assert_eq!(cfg.reasoner.tableaux_max_nodes, 10_000);
assert_eq!(cfg.reasoner.max_iterations, 64);
assert_eq!(cfg.feedback.suppress_threshold, 3);
assert_eq!(cfg.feedback.downgrade_threshold, 2);
assert_eq!(cfg.imports.max_depth, 3);
assert_eq!(cfg.imports.request_timeout_secs, 30);
assert!(cfg.imports.follow_remote);
assert_eq!(cfg.repo.default_list_limit, 1000);
assert!(!cfg.socket.enabled);
assert!(cfg.socket.preload_files.is_empty());
assert_eq!(cfg.logging.level, "info");
assert_eq!(cfg.logging.format, "compact");
assert_eq!(cfg.cache.hash_prefix_bytes, 64 * 1024);
}
#[test]
fn resolvers_pass_through_config_when_env_unset() {
// Regression: `resolve_*` functions must return the config-supplied
// value when no env override is set. This exercises the precedence
// path documented in PR #4 (env > config > default) without mutating
// process-wide env vars (which would race with parallel tests).
// We rely on these env vars being unset in CI; if a future test
// sets them, this assertion will surface that interference.
for var in [
"OPEN_ONTOLOGIES_WEBHOOK_REQUEST_TIMEOUT_SECS",
"OPEN_ONTOLOGIES_IMPORTS_REQUEST_TIMEOUT_SECS",
"OPEN_ONTOLOGIES_MONITOR_INTERVAL_SECS",
] {
if std::env::var(var).is_ok() {
eprintln!("skipping resolver passthrough test: {var} is set");
return;
}
}
let webhook = WebhookConfig {
request_timeout_secs: 7,
};
assert_eq!(resolve_webhook_timeout_secs(&webhook), 7);
let imports = ImportsConfig {
max_depth: 5,
request_timeout_secs: 42,
follow_remote: true,
};
assert_eq!(resolve_imports_timeout_secs(&imports), 42);
let monitor = MonitorConfig {
enabled: true,
interval_secs: 11,
};
assert_eq!(resolve_monitor_interval_secs(&monitor), 11);
}
#[test]
fn resolve_imports_timeout_preserves_zero_sentinel() {
// The `0` sentinel for `[imports] request_timeout_secs` is documented
// (commit cdd5384) as "disable the explicit per-call timeout and use
// reqwest's default". The resolver must propagate the 0 verbatim so
// downstream callers can decide whether to skip `.timeout()`.
if std::env::var("OPEN_ONTOLOGIES_IMPORTS_REQUEST_TIMEOUT_SECS").is_ok() {
eprintln!("skipping zero-sentinel test: env override is set");
return;
}
let imports = ImportsConfig {
max_depth: 3,
request_timeout_secs: 0,
follow_remote: true,
};
assert_eq!(resolve_imports_timeout_secs(&imports), 0);
}
}