🧙‍♂️ Summoning CellMage¶

✨ Magical Requirements¶

Before you can summon the CellMage to assist you, ensure you have the following magical components:

🐍 Python 3.8 or later
🔮 Jupyter Notebook or JupyterLab environment
📜 An API key for your chosen LLM service (e.g., OpenAI)

🪄 Quick Installation Spell¶

The simplest way to install CellMage is through the mystical PyPI repository:

pip install cellmage

🧪 Optional Potion Ingredients¶

CellMage offers various magical extensions to enhance your experience. Install them with:

# For all integrations (recommended for wizards who want the full experience)
pip install "cellmage[all]"

# For specific integrations
pip install "cellmage[github]"      # GitHub integration
pip install "cellmage[gitlab]"      # GitLab integration
pip install "cellmage[jira]"        # Jira integration
pip install "cellmage[confluence]"  # Confluence integration
pip install "cellmage[langchain]"   # LangChain adapter support

🧩 Developer Enchantments¶

If you’re a wizard looking to contribute to CellMage:

# Clone the repository
git clone https://github.com/madpin/cellmage.git
cd cellmage

# Create a magical environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install for development
pip install -e ".[dev,all]"

⚡ Configuration Charm¶

🔑 Essential API Keys¶

CellMage requires an API key to communicate with your LLM service provider. This is the most important configuration step:

# Using environment variables (recommended for security)
export CELLMAGE_API_KEY="your_openai_api_key"
# OR use OPENAI_API_KEY if you prefer
export OPENAI_API_KEY="your_openai_api_key"

📄 Using .env Files¶

CellMage automatically reads from a .env file in your working directory, which is a convenient way to set configuration without exposing sensitive information:

# Create a .env file with your configuration
cat > .env << EOF
# Essential configuration
CELLMAGE_API_KEY=your_openai_api_key
CELLMAGE_DEFAULT_MODEL=gpt-4o
CELLMAGE_API_BASE=https://api.openai.com/v1

# Optional: Storage configuration
CELLMAGE_SQLITE_PATH=~/.cellmage/conversations.db
CELLMAGE_PERSONAS_DIRS=~/my_personas,./project_personas
CELLMAGE_SNIPPETS_DIRS=~/my_snippets,./project_snippets
EOF

🔮 Environment Variables Reference¶

Essential Variables¶

Environment Variable	Description	Default Value
`CELLMAGE_API_KEY` or `OPENAI_API_KEY`	Your LLM API key	None (Required)
`CELLMAGE_API_BASE`	API base URL	https://api.openai.com/v1
`CELLMAGE_DEFAULT_MODEL`	Default model to use	gpt-4o-mini

Storage Variables¶

Environment Variable	Description	Default Value
`CELLMAGE_PERSONAS_DIRS`	Comma-separated list of directories containing personas	./llm_personas
`CELLMAGE_SNIPPETS_DIRS`	Comma-separated list of directories containing snippets	./llm_snippets
`CELLMAGE_CONVERSATIONS_DIR`	Directory for saving conversations	./llm_conversations
`CELLMAGE_SQLITE_PATH`	Path to SQLite database	~/.cellmage/conversations.db
`CELLMAGE_ADAPTER`	LLM adapter type (direct or langchain)	direct
`CELLMAGE_STORAGE_TYPE`	Storage type to use (sqlite, memory, file)	sqlite

Integration Variables¶

Service	Required Environment Variables
Jira	`JIRA_URL`, `JIRA_USER_EMAIL`, `JIRA_API_TOKEN`
Confluence	`CONFLUENCE_URL` (or `JIRA_URL`), `JIRA_USER_EMAIL`, `JIRA_API_TOKEN`
GitHub	`GITHUB_TOKEN`
GitLab	`GITLAB_URL`, `GITLAB_PAT` or `GITLAB_PRIVATE_TOKEN`
Google Docs	`CELLMAGE_GDOCS_AUTH_TYPE`, `CELLMAGE_GDOCS_TOKEN_PATH`, `CELLMAGE_GDOCS_CREDENTIALS_PATH` (for OAuth) or `CELLMAGE_GDOCS_SERVICE_ACCOUNT_PATH` (for service account)

📚 Model Aliasing¶

CellMage supports model aliasing to create shortcuts for model names. You can define aliases in a cellmage_models.yml file in your working directory:

# Example cellmage_models.yml
mappings:
  gpt4: gpt-4o
  gpt4-mini: gpt-4o-mini
  gpt3: gpt-3.5-turbo

A reference example can be found in cellmage/examples/cellmage_models.yml. This allows you to use shorter aliases like %llm_config --model gpt4 instead of full model names.

🪄 Your First Incantation¶

Let’s verify that your CellMage installation is working properly:

# In your Jupyter Notebook
%load_ext cellmage

# Check status
%llm_config --status

# Cast your first spell!
%%llm
Tell me a fun fact about wizards in computing history.

If your spell works, congratulations! You’re now ready to explore the full magical potential of CellMage.

🎩✨ Let the wizardry begin! ✨🎩