⚙️ Configuration¶

CellMage offers multiple ways to configure its behavior, from environment variables to runtime commands. This flexibility allows you to set up your environment once and then make temporary adjustments as needed.

🔧 Configuration Methods¶

1. Environment Variables¶

Environment variables provide a system-wide way to configure CellMage. All environment variables use the CELLMAGE_ prefix.

# Example: Setting environment variables in your shell
export CELLMAGE_API_KEY="your_openai_api_key"
export CELLMAGE_DEFAULT_MODEL="gpt-4o"
export CELLMAGE_PERSONAS_DIRS="~/my_personas,~/project_personas"

2. `.env` File¶

You can also place a .env file in your working directory with your configuration:

# Example .env file
CELLMAGE_API_KEY=your_openai_api_key
CELLMAGE_DEFAULT_MODEL=gpt-4o
CELLMAGE_PERSONAS_DIRS=~/my_personas,~/project_personas

This approach is particularly useful for project-specific settings and avoids exposing sensitive information in your environment or code.

3. Runtime Configuration¶

Use the %llm_config magic command to change settings during a session:

# View current configuration
%llm_config --status

# Change the default model
%llm_config --model gpt-4o-mini

# Set parameter overrides for the session
%llm_config --set-override temperature 0.7

See the Magic Commands documentation for a complete reference of all available configuration commands.

4. Model Mapping File¶

CellMage supports model aliasing through a YAML configuration file named cellmage_models.yml, which allows you to create shorthand names for models:

# Example cellmage_models.yml
mappings:
  g4: gpt-4o
  g4m: gpt-4o-mini
  g3: gpt-3.5-turbo
  claud3h: claude-3-haiku
  claud3s: claude-3-sonnet

CellMage will automatically look for this file in your working directory, or you can specify a custom path with the CELLMAGE_MODEL_MAPPINGS_FILE environment variable.

📋 Configuration Options¶

Here’s the complete list of configuration options organized by category:

Core Settings¶

Environment Variable	Description	Default Value	Type
`CELLMAGE_API_KEY`	Your LLM API key (OpenAI or compatible)	None (Required)	string
`CELLMAGE_API_BASE`	API base URL	https://api.openai.com/v1	string
`CELLMAGE_DEFAULT_MODEL`	Default model to use	gpt-4.1-nano	string
`CELLMAGE_DEFAULT_PERSONA`	Default persona to use on startup	None	string

Resource Directories¶

Environment Variable	Description	Default Value	Type
`CELLMAGE_PERSONAS_DIR`	Primary directory containing persona definitions	./llm_personas	string
`CELLMAGE_PERSONAS_DIRS`	Additional directories to search for personas (comma-separated)	[]	string/list
`CELLMAGE_SNIPPETS_DIR`	Primary directory containing snippets	./llm_snippets	string
`CELLMAGE_SNIPPETS_DIRS`	Additional directories to search for snippets (comma-separated)	[]	string/list
`CELLMAGE_CONVERSATIONS_DIR`	Directory for saving conversations	./llm_conversations	string

Storage Configuration¶

Environment Variable	Description	Default Value	Type
`CELLMAGE_STORAGE_TYPE`	Storage backend type (‘sqlite’, ‘memory’, or ‘file’)	sqlite	string
`CELLMAGE_SQLITE_PATH`	Path to SQLite database	~/.cellmage/conversations.db	string
`CELLMAGE_STORE_RAW_RESPONSES`	Whether to store raw API request/response data	False	boolean
`CELLMAGE_AUTO_SAVE`	Whether to automatically save conversations	True	boolean
`CELLMAGE_AUTOSAVE_FILE`	Filename for auto-saved conversations	autosaved_conversation	string

Model Mapping Configuration¶

Environment Variable	Description	Default Value	Type
`CELLMAGE_MODEL_MAPPINGS_FILE`	Path to YAML file containing model name mappings	None	string
`CELLMAGE_AUTO_FIND_MAPPINGS`	Automatically look for cellmage_models.yml in notebook directory	True	boolean

Adapter Configuration¶

Environment Variable	Description	Default Value	Type
`CELLMAGE_ADAPTER`	LLM adapter type (direct or langchain)	direct	string
`CELLMAGE_AUTO_DISPLAY`	Whether to automatically display chat messages	True	boolean

Logging Configuration¶

Environment Variable	Description	Default Value	Type
`CELLMAGE_LOG_LEVEL`	Global logging level	INFO	string
`CELLMAGE_CONSOLE_LOG_LEVEL`	Console logging level	WARNING	string
`CELLMAGE_LOG_FILE`	Log file path	cellmage.log	string

🌐 Service-Specific Configuration¶

Jira Integration¶

JIRA_URL=https://your-company.atlassian.net
JIRA_USER_EMAIL=your.email@company.com
JIRA_API_TOKEN=your_jira_api_token

Confluence Integration¶

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
# Confluence uses Jira credentials
JIRA_USER_EMAIL=your.email@company.com
JIRA_API_TOKEN=your_jira_api_token

GitHub Integration¶

GITHUB_TOKEN=your_github_personal_access_token

GitLab Integration¶

GITLAB_URL=https://gitlab.com
GITLAB_PAT=your_gitlab_personal_access_token
# Or alternatively:
GITLAB_PRIVATE_TOKEN=your_gitlab_personal_access_token

Google Docs Integration¶

# OAuth configuration (default)
CELLMAGE_GDOCS_AUTH_TYPE=oauth
CELLMAGE_GDOCS_TOKEN_PATH=~/.cellmage/gdocs_token.pickle
CELLMAGE_GDOCS_CREDENTIALS_PATH=~/.cellmage/gdocs_credentials.json

# Or service account configuration
CELLMAGE_GDOCS_AUTH_TYPE=service_account
CELLMAGE_GDOCS_SERVICE_ACCOUNT_PATH=~/.cellmage/gdocs_service_account.json

# Optional: Override the scopes (comma-separated)
CELLMAGE_GDOCS_SCOPES=https://www.googleapis.com/auth/documents.readonly

🔒 Custom Headers¶

CellMage supports custom headers for LLM requests using the CELLMAGE_HEADER_ prefix:

# Add custom header to LLM requests
CELLMAGE_HEADER_X_MY_CUSTOM_HEADER=my_value
# Will send header: x-my-custom-header: my_value

# Example: Allow certain entity types in redaction services
CELLMAGE_HEADER_X_REDACT_ALLOW=LOCATION,PERSON

Header names are automatically converted from environment variable format to proper HTTP header format (lowercase with hyphens instead of underscores).

📁 Directory Handling¶

For CELLMAGE_PERSONAS_DIRS and CELLMAGE_SNIPPETS_DIRS, you can specify multiple directories using commas or semicolons:

# Comma-separated example
export CELLMAGE_PERSONAS_DIRS="~/global_personas,./project_personas,/shared/team_personas"

# Semicolon-separated example (useful in Windows environments)
export CELLMAGE_PERSONAS_DIRS="~/global_personas;./project_personas;/shared/team_personas"

CellMage will automatically search all specified directories when looking for personas or snippets.

💡 Tips and Best Practices¶

Sensitive Information: Keep API keys in environment variables or .env files, never hardcode them in notebooks
Project-Specific Settings: Use .env files for project-specific settings
Runtime Adjustments: Use %llm_config for temporary changes during a session
Check Status: Use %llm_config --status to verify your current configuration
Custom Model Aliases: Create short aliases for your frequently used models in cellmage_models.yml
Multi-Directory Setup: For team environments, consider using a combination of global, team, and project-specific directories for personas and snippets

🔄 Runtime Configuration with `%llm_config`¶

The %llm_config magic command provides a flexible way to configure CellMage during a session without modifying environment variables or .env files. Here are some common use cases:

# View current configuration
%llm_config --status

# Change the model for the session
%llm_config --model gpt-4o

# Switch to a different persona
%llm_config --persona code_expert

# Set parameter overrides
%llm_config --set-override temperature 0.7
%llm_config --set-override max_tokens 1000

# Clear all overrides
%llm_config --clear-overrides

# Enable auto-saving
%llm_config --auto-save

# View model name mappings
%llm_config --list-mappings

# Add a new model alias
%llm_config --add-mapping g4t gpt-4-turbo

For a complete reference of all available %llm_config options, see the Magic Commands documentation.