vd.config

Configuration management for vd.

Provides support for configuration files (YAML, TOML), environment variables, and configuration profiles for managing backend connections.

Functions

apply_env_overrides(config)	Apply environment variable overrides to configuration.
connect_from_config([path, profile, ...])	Connect to a backend using configuration from a file.
create_example_config([format])	Generate an example configuration file content.
get_profile(config[, profile])	Get a specific profile from configuration.
load_config([path, format])	Load configuration from a file.
load_toml_config(path)	Load configuration from a TOML file.
load_yaml_config(path)	Load configuration from a YAML file.
save_config(config, path, *[, format])	Save configuration to a file.

vd.config.apply_env_overrides(config)

Apply environment variable overrides to configuration.

Looks for environment variables with the VD_ prefix:

• VD_BACKEND: Override backend name

• VD_EMBEDDING_MODEL: Override embedding model

Parameters:

config (dict) – Configuration dictionary

Returns:

Configuration with environment overrides applied

Return type:

dict

Examples

>>> import os
>>> os.environ['VD_BACKEND'] = 'chroma'
>>> config = apply_env_overrides({'backend': 'memory'})
>>> config['backend']
'chroma'

vd.config.connect_from_config(path=None, *, profile=None, apply_env=True, embedder=None, **overrides)

Connect to a backend using configuration from a file.

Parameters:

• path (Union[str, Path, None]) – Path to configuration file. If not provided, searches for default config files.

• profile (Optional[str]) – Profile name to use from configuration. Defaults to ‘default’ or the VD_PROFILE environment variable.

• apply_env (bool) – Whether to apply environment variable overrides

• embedder (Optional[Callable[[str], list[float]]]) – Optional text -> vector convenience embedder, passed to vd.connect(). A vd config file describes the *backend connection*, not embedding — embedding stays the caller’s concern.

• **overrides – Additional keyword arguments to override configuration values

Returns:

Connected client instance

Return type:

Client

Examples

>>> # With a config file
>>> client = connect_from_config('vd.yaml')

>>> # With a specific profile
>>> client = connect_from_config('vd.yaml', profile='production')

>>> # With environment variable VD_PROFILE=dev
>>> client = connect_from_config()

>>> # With overrides
>>> client = connect_from_config('vd.yaml', persist_directory='./data')

vd.config.create_example_config(format='yaml')

Generate an example configuration file content.

Parameters:

format (str) – Format of configuration: ‘yaml’ or ‘toml’

Returns:

Example configuration as a string

Return type:

str

Examples

>>> yaml_config = create_example_config('yaml')
>>> print(yaml_config)
>>> toml_config = create_example_config('toml')

vd.config.get_profile(config, profile=None)

Get a specific profile from configuration.

Parameters:

• config (dict) – Full configuration dictionary

• profile (Optional[str]) – Profile name. If not provided, uses ‘default’ or the profile specified by the VD_PROFILE environment variable.

Returns:

Profile configuration

Return type:

dict

Examples

>>> config = {'profiles': {'dev': {'backend': 'memory'}, 'prod': {'backend': 'chroma'}}}
>>> dev_config = get_profile(config, 'dev')
>>> prod_config = get_profile(config, 'prod')

vd.config.load_config(path=None, *, format=None)

Load configuration from a file.

Automatically detects format from file extension if not specified.

Parameters:

• path (Union[str, Path, None]) – Path to configuration file. If not provided, looks for default config files in: ./vd.yaml, ./vd.yml, ./vd.toml, ~/.vd/config.yaml, etc.

• format (Optional[str]) – Configuration format: ‘yaml’ or ‘toml’. Auto-detected from extension if not provided.

Returns:

Configuration dictionary

Return type:

dict

Examples

>>> config = load_config('vd.yaml')
>>> config = load_config('vd.toml')
>>> config = load_config()  # Looks for default config files

vd.config.load_toml_config(path)

Load configuration from a TOML file.

Parameters:

path (Union[str, Path]) – Path to TOML configuration file

Returns:

Configuration dictionary

Return type:

dict

Raises:

• ImportError – If tomli/tomllib is not available

• FileNotFoundError – If configuration file doesn’t exist

vd.config.load_yaml_config(path)

Load configuration from a YAML file.

Parameters:

path (Union[str, Path]) – Path to YAML configuration file

Returns:

Configuration dictionary

Return type:

dict

Raises:

• ImportError – If PyYAML is not installed

• FileNotFoundError – If configuration file doesn’t exist

vd.config.save_config(config, path, *, format=None)

Save configuration to a file.

Parameters:

• config (dict) – Configuration dictionary to save

• path (Union[str, Path]) – Path to save configuration file

• format (Optional[str]) – Format to save: ‘yaml’ or ‘toml’. Auto-detected from extension if not provided.

Return type:

None

Examples

>>> config = {
...     'profiles': {
...         'dev': {'backend': 'memory'},
...         'prod': {'backend': 'chroma', 'persist_directory': './data'}
...     }
... }
>>> save_config(config, 'vd.yaml')