🤖 Frostbolt AI Assistant

🎯 Problem Statement

What are we trying to solve?

• Building a conversational AI assistant that can perform multiple tasks beyond just chatting
• Understanding how to properly implement conversation memory and context management in AI agents
• Creating a rich, interactive CLI experience that demonstrates pydantic_ai's capabilities
• Learning how AI agents can intelligently decide when and how to use tools based on natural conversation

🛠️ Solution Approach

How we plan to tackle this:

• Use pydantic_ai framework for type-safe, tool-enabled AI interactions
• Implement proper conversation history management for contextual responses
• Create a rich CLI interface using the Rich library for better user experience
• Build modular tools (dice rolling, calculations, weather, etc.) that the AI can use intelligently
• Use Ollama with local models for privacy and control

📋 Implementation

What we built:

• Conversational AI Agent: Powered by pydantic_ai with proper context management
• Rich CLI Interface: Beautiful terminal UI with panels, colors, and status indicators
• Multi-Tool Integration:
  • 🎲 Dice rolling with customizable sides
  • 🧮 Safe mathematical calculations
  • 🕐 Current date/time retrieval
  • 🪙 Coin flipping
  • 🌤️ Real-time weather information using Open-Meteo API
• Smart Context Management: Proper conversation history that allows follow-up questions
• Weather Integration: Full weather API integration with caching and error handling

📊 Retrospective

✅ What Worked Well

• Pydantic AI Framework: Excellent type safety and tool integration
• Conversation History: Once properly implemented, context management worked flawlessly
• Rich Library: Created a beautiful, professional CLI experience
• Modular Design: Tools are easily extensible and well-separated
• API Integration: Weather functionality integrated smoothly with caching

❌ What Didn't Work

• Initial Context Confusion: First assumed pydantic_ai handled context automatically
• Weather Tool Migration: Had to fix function signatures and imports when porting from another project
• Import Dependencies: Multiple iterations to get all required libraries properly configured

🔄 What We'd Do Differently

• Start with Documentation: Read pydantic_ai message history docs first
• Plan Tool Architecture: Design tool interfaces before implementation
• Test Context Early: Verify conversation memory works with simple tests before building complex features

🚫 What We Should Have Done

• Add History Processors: Implement context compression for long conversations
• Error Recovery: Better handling of API failures and network issues
• Configuration Management: Environment-based configuration for API endpoints
• Async Support: Could leverage async capabilities for better performance

📚 Technologies Used

• Core Framework: pydantic_ai 1.0.7+ for AI agent management
• UI/UX: Rich 13.0.0+ for beautiful terminal interface
• AI Model: Ollama with qwen3:latest for local inference
• Weather API: Open-Meteo API with openmeteo-requests library
• Caching: requests-cache for API response caching
• Package Management: uv for fast dependency management
• Language: Python 3.13+

📁 Project Structure

frostbolt/
├── main.py           # Main application with CLI interface
├── config.py         # Weather code mappings and configuration
├── pyproject.toml    # Project dependencies and metadata
├── uv.lock          # Dependency lock file
├── test_context.py  # Context testing utilities
├── .gitignore       # Git ignore patterns
├── .cache.sqlite    # API response cache (ignored)
└── README.md        # This file

🎉 What We Learned

Key takeaways from this project:

Technical Insights

• Context Management: pydantic_ai requires explicit message history passing - it doesn't maintain context automatically between run_sync() calls
• Tool Integration: The @agent.tool_plain decorator makes it incredibly easy to expose Python functions to AI agents
• Message Flow: Each interaction can generate multiple messages (user input → tool calls → tool results → AI response)
• Type Safety: pydantic_ai's type validation prevents many runtime errors and improves development experience

Process Improvements

• Documentation First: Understanding the framework's mental model saves hours of debugging
• Incremental Testing: Testing conversation context with simple examples revealed the actual behavior quickly
• Clean Abstractions: Keeping tool functions simple and focused made them easy to debug and extend

Personal Growth Moments

• Framework Deep Dive: Really understanding how AI agent frameworks handle state and context
• API Integration: Successfully migrating and adapting existing weather functionality
• User Experience: Creating a polished CLI that feels professional and responsive

🚀 Getting Started

1. Install dependencies:

   uv sync

2. Start Ollama with qwen3:

   ollama pull qwen3:latest
   ollama serve

3. Run Frostbolt:

   uv run main.py

4. Try some commands:

   • "What's the weather in London?"
   • "What about Paris?" (context aware!)
   • "Roll a 20-sided die"
   • "What's 15 * 23?"

---

Made with 💻 and lots of ☕
Building conversational AI, one tool at a time! 🤖