`rath.config`#

Persistent local configuration for LLM providers, embedding/VLM provider selection, MCP servers, and memory stores.

Source#

Module	Source
`rath.config.paths`	`src/rath/config/paths.py`
`rath.config.schema`	`src/rath/config/schema.py`
`rath.config.secrets`	`src/rath/config/secrets.py`
`rath.config.store`	`src/rath/config/store.py`

Public contract#

OpenRath resolves config in this order:

OpenRath configuration resolution stack — Config resolution starts with explicit `Provider` fields, then environment variables, and finally the resolved `.openrath/config.json` store.#

Location	When used
`$OPENRATH_HOME/config.json`	Explicit override.
`./.openrath/config.json`	Project-local marker directory exists.
`~/.openrath/config.json`	Default user config.

The file is JSON. Unknown fields round-trip through the Pydantic models so newer OpenRath or third-party tools can add sections without losing data.

{
  "version": 1,
  "llm": {
    "default_provider": "openai-main",
    "providers": {
      "openai-main": {
        "provider_kind": "openai",
        "model": "gpt-5.5",
        "api_key": "sk-...",
        "base_url": "https://api.openai.com/v1"
      },
      "claude": {
        "provider_kind": "anthropic",
        "model": "claude-sonnet-4-5",
        "api_key": "sk-ant-..."
      }
    }
  },
  "mcp": {
    "default_enabled": ["filesystem"],
    "servers": {
      "filesystem": {
        "command": ["python", "-m", "mcp_server_filesystem"],
        "env": {}
      }
    }
  },
  "memory": {
    "default_provider": "local-main",
    "providers": {
      "local-main": {
        "backend_kind": "local",
        "path": ".openrath/memory",
        "embedding_provider": "embed-main",
        "chat_provider": "openai-main"
      }
    }
  }
}

Store helpers#

API	Behavior
`ConfigStore.load()`	Loads the resolved default path or seeds an empty config.
`store.save()`	Writes atomically, sets user-only permissions on POSIX, and writes `.gitignore` guards.
`store.get_llm_provider(name)`	Returns a named provider, or `llm.default_provider` when `name=None`.
`store.find_provider_by_kind(kind)`	Finds the default matching provider, then the first matching provider.
`store.get_memory_provider(name)`	Returns a named local memory provider, or `memory.default_provider` when `name=None`.
`store.get_mcp_server(name)`	Returns one MCP server entry.
`store.enabled_mcp_servers()`	Resolves every name in `mcp.default_enabled`.

Consumers#

Consumer	Config behavior
`Provider.from_config(name=None, **overrides)`	Builds a `Provider` from `llm.providers`; explicit overrides win.
`EmbeddingProvider.from_config(name=None, **overrides)`	Uses `llm.embedding_provider` first, then chat default credentials with a safe embedding model.
`VLMProvider.from_config(name=None, **overrides)`	Uses `llm.vlm_provider` or an explicit name; no chat fallback is assumed.
`MemoryStoreSpec.from_config(name=None, **overrides)`	Builds local memory store options from `memory.providers`.
`RathOpenAIChatClient`	Falls back to the first `provider_kind="openai"` config entry after Provider kwargs and environment variables.
`RathAnthropicChatClient`	Falls back to the first `provider_kind="anthropic"` config entry after Provider kwargs and environment variables.
`mcp_tools_from_config(name=None)`	Builds MCP tool wrappers from one configured stdio server.

Autodoc#

rath.config.resolve_config_dir() → Path[source]#

Return the directory that holds config.json.

Raises FileNotFoundError only when OPENRATH_HOME is set but points at a non-directory path that already exists (e.g. a regular file). A missing target is fine — the caller will create it on first save.

rath.config.resolve_config_path() → Path[source]#: Return the full path to config.json under the resolved config dir.

rath.config.is_project_local(config_dir: Path) → bool[source]#

Return whether config_dir is the project-local ./.openrath/.

Used by rath.config.secrets to decide whether to also append .openrath/ to the surrounding project’s .gitignore on save.

class rath.config.RathConfig(*, version: int = 1, llm: LLMConfig = <factory>, mcp: MCPConfig = <factory>, memory: MemoryConfig = <factory>, **extra_data: Any)[source]#

Top-level on-disk schema.

Sections currently in use: llm, mcp, and memory. Future sections (e.g. backend for OpenSandbox routing) can be added without touching callers because extra="allow" preserves them on round-trip.

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.LLMConfig(*, default_provider: str | None = None, embedding_provider: str | None = None, vlm_provider: str | None = None, providers: dict[str, ~rath.config.schema.LLMProviderConfig]=<factory>, **extra_data: Any)[source]#

The llm section: named providers + which one is the default.

default_provider is the chat fallback. embedding_provider and vlm_provider are independent overrides used by rath.llm.embedding.EmbeddingProvider and rath.llm.vlm.VLMProvider; when unset, those clients fall back to default_provider’s api_key/base_url with a sensible default model.

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.LLMProviderConfig(*, provider_kind: Literal['openai', 'anthropic'] = 'openai', model: str | None = None, api_key: str | None = None, base_url: str | None = None, temperature: float | None = None, max_tokens: int | None = None, **extra_data: Any)[source]#

One named entry under llm.providers.

Mirrors the most common Provider fields. Less-common knobs (frequency_penalty, logit_bias, …) stay on explicit Provider(...) kwargs — adding fields here later is non-breaking thanks to extra="allow".

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.MCPConfig(*, default_enabled: list[str] = <factory>, servers: dict[str, ~rath.config.schema.MCPServerConfig]=<factory>, **extra_data: Any)[source]#

The mcp section: named server defs + which are enabled by default.

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.MCPServerConfig(*, command: list[str], env: dict[str, str] = <factory>, **extra_data: ~typing.Any)[source]#

One named entry under mcp.servers.

command is the full argv list passed to the stdio MCP server (the OpenRath adapter never shells out, so no string-form). env is merged into the subprocess environment by the adapter.

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.MemoryConfig(*, default_provider: str | None = None, providers: dict[str, ~rath.config.schema.MemoryProviderConfig]=<factory>, **extra_data: Any)[source]#

The memory section: named local store presets.

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.MemoryProviderConfig(*, backend_kind: Literal['local'] = 'local', path: str | None = None, embedding_provider: str | None = None, chat_provider: str | None = None, **extra_data: Any)[source]#

One named entry under memory.providers (local backend only).

embedding_provider and chat_provider name entries under llm.providers used by LocalMemoryBackend for vector search and commit-time memo extraction respectively. OpenViking connection settings stay on MemoryStoreSpec.options or environment variables — they are not modeled here.

model_config = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class rath.config.ConfigStore(path: Path | None = None)[source]#

Round-trip the config file at path.

The constructor immediately reads the file (or seeds defaults when it does not exist), so callers do not need to guard against FileNotFoundError separately. Subsequent reads should mutate config directly; call save() to persist.

exception rath.config.ConfigError[source]#

Raised on schema-validation failure or corrupt JSON.

The string carries a human-readable summary; the original json.JSONDecodeError or pydantic.ValidationError is available via __cause__.

← API Reference

rath.config#