Skip to content

Migration Guide: ChatCraft to Hands-On AI

This document outlines the migration from the original chatcraft package structure to the new modular hands-on-ai package.

Package Structure Changes

Before (ChatCraft):

chatcraft/
├── src/
│   └── chatcraft/
│       ├── __init__.py      # Bot definitions
│       ├── get_response.py  # Core LLM interaction
│       ├── config.py        # Configuration
│       ├── bots.py          # Bot discovery
│       ├── cli.py           # CLI commands
│       ├── data/            # Fallback data
│       └── ragcraft/        # RAG submodule

After (hands-on-ai):

hands_on_ai/
├── src/
│   └── hands_on_ai/
│       ├── __init__.py      # Package exports
│       ├── config.py        # Shared configuration
│       ├── cli.py           # Meta CLI
│       ├── utils/           # Shared utilities
│       ├── chat/            # Chat module
│       │   ├── __init__.py
│       │   ├── get_response.py
│       │   ├── cli.py
│       │   ├── personalities/
│       │   │   ├── __init__.py
│       │   │   ├── friendly.py
│       │   │   ├── creative.py
│       │   │   └── bots/
│       │   │       ├── friendly_bot.py
│       │   │       └── ...
│       │   ├── commands/
│       │   └── data/
│       ├── rag/             # RAG module
│       │   ├── __init__.py
│       │   ├── utils.py
│       │   ├── cli.py
│       │   └── commands/
│       └── agent/           # Agent module
│           ├── __init__.py
│           ├── core.py
│           ├── cli.py
│           ├── commands/
│           └── tools/

Key Changes

  1. Modular Organisation:
  2. Each functionality (chat, rag, agent) is now a separate submodule
  3. Each submodule has its own CLI, commands, and functionality

  4. Shared configuration in central config.py

  5. Personality Structure:

  6. Individual bot files for easy contribution
  7. Category grouping for logical organisation

  8. Three ways to import bots:

    • From individual files: from hands_on_ai.chat.personalities.bots import friendly_bot
    • From categories: from hands_on_ai.chat.personalities.creative import *
    • From the main module: from hands_on_ai.chat import *

  9. Command Structure:

  10. Each command is in its own file in a commands/ directory
  11. Main CLI file imports and registers all commands

  12. Consistent pattern across all submodules

  13. Configuration:

  14. Centralised configuration in hands_on_ai/config.py
  15. Environment variables renamed from CHATCRAFT_ to HANDS_ON_AI_

  16. Configuration directory ~/.chatcraft -> ~/.hands_on_ai

  17. Entry Points:

  18. Multiple CLI entry points:
    • hands-on-ai - Meta CLI
    • chat - Chat functionality
    • rag - RAG functionality
    • agent - Agent functionality

Migration Steps for End Users

  1. Uninstall old package: 

    pip uninstall chatcraft

  2. Install new package: 

    pip install hands-on-ai

  3. Update import statements:

  4. from chatcraft import friendly_bot → from hands_on_ai.chat import friendly_bot

  5. from chatcraft import get_response → from hands_on_ai.chat import get_response

  6. Update CLI commands:

  7. chatcraft bots → chat bots
  8. chatcraft ask → chat ask

  9. ragcraft ask → rag ask

  10. Update configuration:

  11. Rename ~/.chatcraft to ~/.hands_on_ai
  12. Update environment variables

Migration Steps for Developers

  1. Understand the new module structure
  2. Create PRs against the correct submodule
  3. Follow the new patterns for commands and functionality
  4. Use test_hands_on_ai.py to verify changes