How to Configure OpenMed Settings: Config Files, Profiles, and Environment Variables

OpenMed settings are controlled through a layered configuration system that combines TOML config files, environment-specific profiles, and environment variables, all managed by the OpenMedConfig data class in openmed/core/config.py.

The maziyarpanahi/openmed repository provides a flexible configuration architecture for medical NLP workflows. Understanding how to configure OpenMed settings allows you to customize model paths, logging behavior, and inference backends without modifying source code. The system uses a cascading priority where environment variables override profiles, and profiles override the base configuration file.

Configuration Architecture

OpenMed employs a three-layer configuration strategy. Each layer can override the previous one, giving you fine-grained control over runtime behavior.

The OpenMedConfig Data Class

At the core of the system is the OpenMedConfig dataclass defined in [openmed/core/config.py](https://github.com/maziyarpanahi/openmed/blob/master/openmed/core/config.py). This class validates and stores all settings, automatically reading environment variables in its __post_init__ method.

Base Configuration File

The base configuration lives at ~/.config/openmed/config.toml by default. You can relocate this file by setting the OPENMED_CONFIG environment variable. If the file does not exist at startup, OpenMed creates it with sensible defaults. The path respects the XDG_CONFIG_HOME standard if set.

Profile-Based Configuration

Profiles are TOML fragments stored in ~/.config/openmed/profiles/<profile>.toml. They override specific values from the base config without replacing the entire file. When OPENMED_PROFILE is unset, OpenMed defaults to the dev profile (log_level="DEBUG", timeout=600). Other built-in profiles include prod and fast, each optimized for different execution contexts.

Environment Variable Overrides

Individual fields can be tweaked via environment variables without touching any TOML file:

• OPENMED_CONFIG – Path to an alternative base configuration file.
• OPENMED_PROFILE – Name of the profile to activate (e.g., prod, fast).
• OPENMED_USE_MEDICAL_TOKENIZER – Set to 0, false, or no to disable the medical tokenizer.
• OPENMED_MEDICAL_TOKENIZER_EXCEPTIONS – Comma-separated list of terms that should remain unchanged by the tokenizer.
• HF_TOKEN – Authentication token for private Hugging Face models.
• XDG_CONFIG_HOME – Overrides the base ~/.config directory.

Loading Configuration Programmatically

Use load_config_with_profile() to initialize the configuration hierarchy. This function automatically respects the OPENMED_PROFILE environment variable if set.

from openmed.core.config import load_config_with_profile

# Loads base config + active profile (from env or default 'dev')

config = load_config_with_profile()
print(config.log_level, config.timeout, config.profile)

You can also explicitly request a specific profile:

# Force 'prod' profile regardless of environment variables

config = load_config_with_profile(profile_name="prod")

# => log_level="WARNING", timeout=300, profile="prod"

For object-oriented workflows, use the from_profile() class method:

from openmed.core.config import OpenMedConfig

# Create config from 'fast' profile and override timeout

cfg = OpenMedConfig.from_profile("fast", timeout=200)
print(cfg.log_level)   # "WARNING"

print(cfg.timeout)     # 200

print(cfg.profile)     # "fast"

Managing Profiles

The configuration module provides helper functions to manipulate profile files directly:

from openmed.core.config import list_profiles, get_profile, save_profile, delete_profile

# List available profiles

print(list_profiles())  # ['dev', 'prod', 'test', 'fast']

# Read a profile as a dictionary

profile_data = get_profile('dev')

# Create a new custom profile

save_profile('mycustom', {'log_level': 'ERROR', 'timeout': 30})

# Remove a profile

delete_profile('mycustom')

These functions operate on the path defined by PROFILES_DIR in the same source file.

Configuration Fields Reference

The OpenMedConfig dataclass exposes the following fields with their default values:

Field	Type	Default	Description
default_org	str	"OpenMed"	Hub organization used when publishing models.
cache_dir	Optional[str]	~/.cache/openmed	Directory for downloaded model artifacts.
device	Optional[str]	None	Preferred compute device (cpu, cuda, mps, etc.).
hf_token	Optional[str]	Value of HF_TOKEN env-var	Token for private Hugging Face repositories.
log_level	str	"INFO"	Logging verbosity (DEBUG, INFO, WARNING, ERROR).
timeout	int	300	Model-loading timeout in seconds.
use_medical_tokenizer	bool	True	Enable medical-aware tokenizer remapping.
medical_tokenizer_exceptions	Optional[List[str]]	None	Terms excluded from tokenizer rewriting.
backend	Optional[str]	None	Inference backend ("hf" for PyTorch/HuggingFace, "mlx" for Apple MLX, or None for auto-detect).
profile	Optional[str]	None	Name of the active profile (populated automatically).

Practical Configuration Examples

Using Environment Variables for One-Off Changes

export OPENMED_PROFILE=prod
export OPENMED_USE_MEDICAL_TOKENIZER=0
python -c "from openmed.core.config import load_config_with_profile; cfg = load_config_with_profile(); print(cfg.profile, cfg.use_medical_tokenizer)"

Creating a Custom Profile

Create ~/.config/openmed/profiles/custom.toml:

log_level = "ERROR"
timeout = 60
backend = "mlx"

Then activate it:

config = load_config_with_profile(profile_name="custom")

Summary

• OpenMed configuration is managed by the OpenMedConfig class in openmed/core/config.py via a layered system of files, profiles, and environment variables.
• The base config file resides at ~/.config/openmed/config.toml and can be relocated with OPENMED_CONFIG or XDG_CONFIG_HOME.
• Profiles are stored in ~/.config/openmed/profiles/; the default is dev when none is specified.
• Use load_config_with_profile() to load the full configuration hierarchy, or OpenMedConfig.from_profile() for specific profiles.
• Helper functions list_profiles(), get_profile(), save_profile(), and delete_profile() provide programmatic profile management.
• Environment variables such as OPENMED_USE_MEDICAL_TOKENIZER and HF_TOKEN take precedence over file-based settings.

Frequently Asked Questions

What happens if I don't set the OPENMED_PROFILE environment variable?

If OPENMED_PROFILE is unset, OpenMed automatically uses the dev profile, which sets log_level to "DEBUG" and timeout to 600 seconds. This behavior is hardcoded in the load_config_with_profile() function to ensure verbose debugging during development.

How do I disable the medical tokenizer without editing configuration files?

Set the environment variable OPENMED_USE_MEDICAL_TOKENIZER to 0, false, or no before launching your script. The OpenMedConfig class reads this variable in its __post_init__ method and updates the use_medical_tokenizer boolean accordingly.

Can I store the OpenMed configuration in a custom directory?

Yes. Set the OPENMED_CONFIG environment variable to the absolute path of your desired TOML file. Alternatively, set XDG_CONFIG_HOME to change the base directory from ~/.config to your preferred location; OpenMed will then look for openmed/config.toml under that root.

Where can I find examples of profile usage in the codebase?

The unit tests in [tests/unit/test_core.py](https://github.com/maziyarpanahi/openmed/blob/master/tests/unit/test_core.py) and [tests/unit/test_profiles.py](https://github.com/maziyarpanahi/openmed/blob/master/tests/unit/test_profiles.py) demonstrate profile creation, loading, and environment variable overrides. These files serve as the authoritative reference for expected configuration behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}