🧙 The Spell Book: CellMage Magic Commands

Welcome to the official spell book of CellMage! Here you’ll find all the magical incantations (IPython magic commands) that allow you to summon the power of Large Language Models directly within your enchanted notebooks. Master these spells to become a true wizard of AI!

📜 Summoning the Magic

Before casting any spells, you must first invite the magical presence into your notebook:

%load_ext cellmage

🪄 Your Magical Arsenal

The CellMage grimoire contains these powerful core spells:

  1. %llm_config - Configure your magical powers and manage your arcane resources

  2. %llm_config_persistent - Activate the ambient magic field (where all cells become magical)

  3. %disable_llm_config_persistent - Dispel the ambient magic field

  4. %%llm - Cast a directed spell to the LLM wizard

  5. %%py - Execute mundane Python code (when ambient magic is active)

And these integration enchantments:

  1. %confluence - Summon knowledge from the Confluence realm

  2. %jira - Call upon the wisdom of Jira issue trackers

  3. %github - Channel the power of GitHub repositories

  4. %gitlab - Draw upon the essence of GitLab projects

  5. %webcontent - Extract magical insights from the web

  6. %gdocs - Commune with the scrolls of Google Docs

  7. %sqlite - Manage your spellbook archives

  8. %img - Process and display images

✨ The Complete Spell Compendium

1. %llm_config - The Configuration Spell

This versatile spell allows you to adjust your magical settings and manage your resources.

%llm_config [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

-p, --persona

Transform the AI into a different magical identity

--show-persona

Reveal the current persona’s true nature

--list-personas

Summon a list of all available personas

--set-override KEY VALUE

Apply a magical override to a parameter (e.g., --set-override temperature 0.5)

--remove-override KEY

Remove a specific magical override

--clear-overrides

Dispel all magical overrides

--show-overrides

Reveal all active magical overrides

--clear-history

Erase your conversation history from memory (but keep system prompt)

--show-history

Unfold the scroll of your conversation history

--save [FILENAME]

Preserve your magical session in a scroll for later use

--load SESSION_ID

Recall a previously preserved magical session

--list-sessions

Reveal all preserved magical sessions

--auto-save

Enable automatic preservation of your magical conversations

--no-auto-save

Disable automatic preservation

--list-snippets

Reveal all available magical text fragments

--snippet NAME

Incorporate a magical text fragment into your next spell

--sys-snippet NAME

Add a system-level magical fragment to your next spell

--status

Reveal your current magical status and power levels

--model NAME

Change which magical entity you’re communicating with

--adapter {direct,langchain}

Switch to a different magical communication method

--list-mappings

Show your magical name translations

--add-mapping ALIAS FULL_NAME

Create a new magical name shortcut

--remove-mapping ALIAS

Remove a magical name shortcut

📖 Spell Examples

# Discover your magical name shortcuts
%llm_config --list-mappings

# Create a magical shortcut
%llm_config --add-mapping g4o gpt-4o

# Remove a magical shortcut
%llm_config --remove-mapping g4o

# Summon the Python expert persona
%llm_config --persona python_expert

# Communicate with a specific magical entity
%llm_config --model gpt-4o

# Adjust your spell's creativity
%llm_config --set-override temperature 0.7

# Include a magical scroll in your next communication
%llm_config --snippet code_context.py

# Check your magical status
%llm_config --status

# Switch to a different magical communication method
%llm_config --adapter langchain

2. %llm_config_persistent - The Ambient Magic Spell

This powerful enchantment has the same abilities as %llm_config but also creates a magical field around your notebook, turning every cell into a direct communication with the AI wizard.

%llm_config_persistent [magical_parameters]

When the ambient magic field is active, any scroll (cell) you activate that doesn’t start with a magical rune (% or %%) or command rune (!) will be sent as a message to the AI wizard, and their response will appear below.

🔮 Magical Parameters

All the same magical parameters as %llm_config except for --adapter.

📖 Spell Example

# Create an ambient magic field with the coding assistant persona
%llm_config_persistent --persona coding_assistant --model gpt-4o

After casting this spell, you can simply write a question in any cell (no %%llm needed) and run it to receive wisdom from the AI wizard!

3. %disable_llm_config_persistent - The Dispel Magic Spell

This counter-spell removes the ambient magic field, returning your notebook to its normal state.

%disable_llm_config_persistent

4. %%llm - The Direct Communication Spell

This cell magic allows you to send a specific message directly to the AI wizard.

%%llm [magical_parameters]
Your message to the magical AI...

🔮 Magical Parameters

Arcane Parameter

What It Does

-p, --persona

Temporarily summon a different magical identity

-m, --model

Temporarily communicate with a different magical entity

-t, --temperature

Adjust the creativity of THIS spell only

--max-tokens

Limit the length of the magical response

--no-history

Cast a spell that leaves no trace in your history

--no-stream

Receive the complete magical response at once (no gradual appearance)

--no-rollback

Prevent automatic spell recovery if something goes wrong

--param KEY VALUE

Set any other magical parameter for this spell only

--list-snippets

Reveal all available magical fragments

--snippet NAME

Include a magical fragment in this spell

--sys-snippet NAME

Include a system-level magical fragment in this spell

📖 Spell Examples

%%llm --persona data_alchemist --model gpt-4o
Transform this dataset into golden insights about customer behavior.

%%llm -t 0.9 --param top_p 0.95
Craft a magical tale about a programmer who discovers an ancient spell book
containing Python code that can alter reality.

5. %%py - The Mundane Code Spell

When the ambient magic field is active, this spell allows you to execute regular Python code without magical interpretation.

%%py
# This scroll contains regular Python incantations
fibonacci_spell = lambda n: n if n <= 1 else fibonacci_spell(n-1) + fibonacci_spell(n-2)
print(f"The 10th number in the sequence is {fibonacci_spell(10)}")

6. %confluence - The Confluence Crystal Ball

This enchantment allows you to peer into the Confluence realm and retrieve knowledge stored there.

%confluence [identifier] [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

identifier

Page identifier (SPACE:Title format or page ID)

--cql QUERY

Confluence Query Language search query

--max NUMBER

Maximum number of results for CQL queries (default: 5)

--system

Add content as a system message (rather than user)

--show

Display the content without adding to history

--text

Use plain text format instead of Markdown (Markdown is default)

--no-content

For CQL search, return only metadata without page content

--content

For CQL search, fetch full content of each page

📖 Spell Examples

# Fetch a specific Confluence page
%confluence ENGINEERING:System Architecture

# Search Confluence with CQL
%confluence --cql "space = DEV AND title ~ 'API Documentation'"

7. %jira - The Issue Tracking Telescope

This spell allows you to inspect issues and tasks from the Jira realm.

%jira [issue_key] [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

issue_key

Jira issue key (e.g., PROJECT-123)

--jql QUERY

JQL search query instead of a specific issue

--max NUMBER

Maximum number of results for JQL search (default: 5)

--fields FIELDS

Comma-separated list of fields to include

--comments

Include issue comments

--system

Add as system message instead of user message

--show

Display content without adding to history

--text

Use plain text instead of Markdown format

📖 Spell Examples

# Fetch a specific Jira issue
%jira PROJ-123

# Search for issues with JQL
%jira --jql "project = BACKEND AND status = 'In Progress' AND assignee = currentUser()"

8. %github - The GitHub Repository Mirror

This enchantment allows you to peer into GitHub repositories and extract information.

%github [repo/path] [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

repo_path

Repository owner/name or file path within a repository

--issue NUMBER

Fetch a specific issue by number

--pr NUMBER

Fetch a specific pull request by number

--search QUERY

Search for issues with the given query

--max NUMBER

Maximum number of search results (default: 5)

--comments

Include comments on issues/PRs

--system

Add as system message instead of user message

--show

Display content without adding to history

--branch NAME

Branch to use when fetching files (default: main/master)

📖 Spell Examples

# View a specific file from a GitHub repo
%github facebook/react/README.md

# Get information about an issue
%github facebook/react --issue 42 --comments

# Search for issues
%github facebook/react --search "state management" --max 10

9. %gitlab - The GitLab Project Portal

This spell connects to GitLab projects and extracts information.

%gitlab [repo/path] [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

repo_path

Project path or file path within a project

--issue NUMBER

Fetch a specific issue by number

--mr NUMBER

Fetch a specific merge request by number

--search QUERY

Search for issues with the given query

--max NUMBER

Maximum number of search results (default: 5)

--comments

Include comments on issues/MRs

--system

Add as system message instead of user message

--show

Display content without adding to history

--branch NAME

Branch to use when fetching files (default: main/master)

📖 Spell Examples

# View a specific file from a GitLab project
%gitlab group/project/README.md

# Get information about an issue
%gitlab group/project --issue 42 --comments

10. %webcontent - The Web Divination Spell

This enchantment extracts content from webpages and prepares it for analysis.

%webcontent [url] [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

url

URL of the webpage to fetch

--clean

Clean and extract main content (default behavior)

--raw

Get raw HTML content without cleaning

--method METHOD

Content extraction method: trafilatura (default), bs4, or simple

--system

Add as system message instead of user message

--show

Display content without adding to history

--include-images

Include image references in the output

--no-links

Remove hyperlinks from the output

--timeout SECONDS

Request timeout in seconds (default: 30)

📖 Spell Examples

# Get clean content from a webpage
%webcontent https://en.wikipedia.org/wiki/Artificial_intelligence

# Keep links and images in the output
%webcontent https://blog.example.com/tutorial --include-images

11. %gdocs - The Google Docs Summoning Spell

This enchantment allows you to access content from Google Docs and use it as context.

%gdocs [document_id] [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

document_id

Google Document ID or URL

--system

Add as system message instead of user message

--show

Display content without adding to history

--search QUERY

Search for Google Docs files containing the specified term

--content

Retrieve and display content for search results

--max-results NUMBER

Maximum number of search results to return (default: 10)

--max-content NUMBER

Maximum number of documents to retrieve content for (default: 3)

--timeout SECONDS

Request timeout in seconds (default: 300)

--author EMAIL

Filter documents by author/owner email (comma-separated for multiple)

--modified-after, --updated DATE

Filter by modification date (YYYY-MM-DD or natural language)

--order-by FIELD

How to order search results (relevance, modifiedTime, createdTime, name)

--auth-type TYPE

Authentication type to use (oauth or service_account)

📖 Spell Examples

# Fetch a specific Google Document
%gdocs 1aBcDeFgHiJkLmNoPqRsTuVwXyZ

# Search for documents and retrieve content
%gdocs --search "project proposal" --content --max-content 5

# Search with filters
%gdocs --search "meeting notes" --author john@example.com,jane@example.com --updated "2 weeks" --timeout 600

12. %sqlite - The Memory Archive Spell

This enchantment manages your stored conversations with the magic realm.

%sqlite [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

--status

Show the current state of the SQLite storage

--stats

Display statistics about stored conversations

--list

List all stored conversations

--new

Start a new conversation

--load ID

Load a specific conversation by ID

--delete ID

Delete a conversation by ID

--tag ID TAG

Add a tag to a conversation

--search QUERY

Search for conversations with content matching the query

--export PATH

Export a conversation to markdown file

--import-md PATH

Import a conversation from markdown file

📖 Spell Examples

# Show all stored conversations
%sqlite --list

# Start a new conversation
%sqlite --new

# Load a previous conversation
%sqlite --load conversation_20250508_123456

# Search for conversations about a topic
%sqlite --search "neural networks"

13. %img - The Image Processing Portal

This spell allows you to process, display, and add images to your LLM conversations.

%img path/to/image.jpg [magical_parameters]

🔮 Magical Parameters

Arcane Parameter

What It Does

image_path

Path to the image file to process

-r, --resize WIDTH

Width to resize the image to while maintaining aspect ratio

-q, --quality QUALITY

Quality for lossy image formats (0.0-1.0)

--show

Display the image inline after processing

-i, --info

Display information about the image

-a, --add-to-chat

Add the image to the current chat session (default: always added)

-c, --convert

Force conversion to a compatible format

-f, --format FORMAT

Format to convert the image to (e.g., “jpg”, “png”, “webp”)

📖 Spell Examples

# Process an image and add it to conversation context (no display)
%img path/to/image.jpg

# Process, display, and show information about an image
%img path/to/image.jpg --show --info

# Resize an image to 800px width and display it
%img path/to/image.jpg --resize 800 --show

# Convert an image to a different format with quality adjustment
%img path/to/image.jpg --format webp --quality 0.85 --show

🌟 The Ambient Magic Field

The ambient magic field is a powerful enchantment that, when activated, allows any regular cell to be automatically processed as a communication with the AI wizard. This eliminates the need to mark each message with the %%llm rune.

  • To create the field: %llm_config_persistent

  • To dispel the field: %disable_llm_config_persistent

When the ambient magic field is active, cells that start with magical runes (%, %%) or command runes (!) still function normally, but all other cells become direct communications with the AI wizard.

If you need to cast regular Python spells while the ambient field is active, use the %%py magic rune.

⚠️ Warning: The ambient magic field may sometimes intercept Jupyter’s internal background functions like __jupyter_exec_background__() which are used for autocomplete and other IDE features. If your magical workspace begins acting strangely (such as code completion not working properly or internal Jupyter commands being sent to the AI wizard as messages), dispel the ambient magic using %disable_llm_config_persistent and use explicit %%llm runes instead.

📊 Magical Status Indicators

After each successful communication with the AI wizard (via %%llm or ambient magic), a status bar displays:

  • Success rune (✅)

  • Duration of the magical communication (⏱️)

  • Token counts (magical energy consumed/received) (📥/📤)

  • Estimated cost in magical currency (🪙)

  • Which magical entity responded

This information helps you track your magical energy usage and costs.

🧪 Example Magical Potions

Here are some example incantations to help you get started on your magical journey:

# Load the magical extension
%load_ext cellmage

# Set the default model and persona
%llm_config --model gpt-4o --persona python_expert

# Ask a question with a specific model for this call only
%%llm -m gpt-4o
Explain the visitor pattern in software design

# Enable ambient mode with specific settings
%llm_config_persistent --model gpt-4o-mini --temperature 0.7

# Execute Python code in ambient mode
%%py
import pandas as pd
print(pd.__version__)

# Disable ambient mode
%disable_llm_config_persistent

# Load integration extensions as needed
%load_ext cellmage.magic_commands.tools.confluence_magic
%load_ext cellmage.magic_commands.tools.github_magic
%load_ext cellmage.magic_commands.tools.webcontent_magic

# Fetch content from various sources
%confluence TEAM:Project Overview
%github myorg/myrepo --issue 42
%webcontent https://example.com/article