Back to CTK - Conversation Toolkit

Tutorials

Step-by-step guides for using CTK.

Getting Started with CTK

This tutorial walks you through importing, managing, and exporting AI conversations using the Conversation Toolkit.

Installation

From Source

git clone https://github.com/queelius/ctk.git
cd ctk
make setup
source .venv/bin/activate

From PyPI

pip install conversation-tk

Tutorial 1: Importing Your First Conversations

Step 1: Export from ChatGPT

  1. Go to chat.openai.com/settings
  2. Navigate to Data Controls → Export
  3. Download and unzip your export

Step 2: Import into CTK

# Auto-detect format
ctk import conversations.json --db my_chats.db

# Or specify format explicitly
ctk import chatgpt_export.json --db my_chats.db --format openai --tags "work,2024"

Step 3: Verify Import

# View statistics
ctk stats --db my_chats.db

# List conversations
ctk list --db my_chats.db --limit 10

Tutorial 2: Searching and Organizing

Full-Text Search

# Search for specific topics
ctk search "machine learning" --db my_chats.db

# Filter by source
ctk search "python" --db my_chats.db --source ChatGPT --model GPT-4

# Filter by date
ctk search "AI" --db my_chats.db --date-from 2024-01-01 --date-to 2024-12-31

Natural Language Queries

CTK can interpret plain English queries using an LLM:

# Ask in natural language
ctk ask "show me starred conversations" --db my_chats.db
ctk ask "find discussions about async python" --db my_chats.db
ctk ask "conversations from last week about AI" --db my_chats.db

Organizing Conversations

# Star important conversations
ctk star abc123 --db my_chats.db

# Pin for quick access
ctk pin abc123 --db my_chats.db

# Archive old ones
ctk archive def456 --db my_chats.db

# Rename for clarity
ctk title abc123 "Python Async Tutorial Discussion" --db my_chats.db

Tutorial 3: Understanding Tree Structure

CTK preserves the full branching structure of conversations.

Linear Conversations

Simple back-and-forth becomes a single-path tree:

User: "What is Python?"
  └── Assistant: "Python is a programming language..."
      └── User: "How do I install it?"
          └── Assistant: "You can install Python by..."

Branching Conversations

Regenerated responses create branches:

User: "Write a poem"
  ├── Assistant (v1): "Roses are red..."
  └── Assistant (v2): "In fields of gold..."  [regenerated]
      └── User: "Make it longer"
          └── Assistant: "In fields of gold, where sunshine..."

Viewing Tree Structure

# View as tree
ctk tree abc123 --db my_chats.db

# List all paths
ctk paths abc123 --db my_chats.db

# Show specific path
ctk show abc123 --db my_chats.db --path longest
ctk show abc123 --db my_chats.db --path latest

Tutorial 4: Interactive TUI

Launch the terminal UI for a rich browsing experience:

ctk chat --db my_chats.db

TUI Commands

# Navigation
/browse              # Browse conversations table
/show <id>           # Show conversation
/tree <id>           # View tree structure

# Search
/search <query>      # Full-text search
/ask <query>         # Natural language query

# Organization
/star <id>           # Star conversation
/pin <id>            # Pin conversation
/title <id> <title>  # Rename

# Chat Operations
/fork                # Fork current conversation
/regenerate          # Regenerate last message
/model <name>        # Switch LLM model

# Help
/help                # Show all commands
/quit                # Exit TUI

Tutorial 5: Exporting Conversations

Export for Fine-Tuning

# JSONL format
ctk export training.jsonl --db my_chats.db --format jsonl

# With path selection
ctk export responses.jsonl --db my_chats.db --format jsonl --path-selection longest

Export with Filtering

# Specific conversations
ctk export selected.jsonl --db my_chats.db --ids conv1 conv2 conv3

# By source or model
ctk export openai_only.json --db my_chats.db --filter-source "ChatGPT"
ctk export gpt4_convs.json --db my_chats.db --filter-model "GPT-4"

# By tags
ctk export work_chats.json --db my_chats.db --filter-tags "work,important"

Export with Sanitization

Remove sensitive data before sharing:

ctk export clean_export.jsonl --db my_chats.db --format jsonl --sanitize

This removes API keys, passwords, tokens, SSH keys, and other secrets.

Export to Hugo

Create a static blog from your conversations:

# All conversations
ctk export content/conversations/ --format hugo --db my_chats.db

# Only starred (curated for blog)
ctk export content/conversations/ --format hugo --db my_chats.db --starred

# As drafts for review
ctk export content/conversations/ --format hugo --db my_chats.db --draft

Export to HTML5

Create an interactive, self-contained archive:

# Single HTML file (recommended)
ctk export archive.html --format html --db my_chats.db

# With separate media files
ctk export archive.html --format html --db my_chats.db --media-dir media

Tutorial 6: Database Operations

Merge Multiple Databases

# Combine personal and work databases
ctk merge personal.db work.db --output all_chats.db

Compare Databases

ctk diff db1.db db2.db

Create Filtered Databases

# Extract by tags
ctk filter --db all_chats.db --output work_chats.db --tags "work"

# Extract starred
ctk filter --db all_chats.db --output starred.db --starred

# Extract by date
ctk filter --db all_chats.db --output recent.db --date-from 2024-01-01

Next Steps