Changelog

Recent updates and changes to the Karo framework.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.4.0] - 2025-05-02

Added

  • Database Sessions:

    • karo.sessions.database_service.DbSession class for managing sessions involving database

  • New Examples:

    • newsletter-agent example demonstrating multi-agent system for newsletter creation, external tool execution (SearchTool) which uses EXA for web search

Changed

  • Moved chromadb installation to optional dependencies under memory.

[0.3.0] - 2025-04-25

Added

  • Conversation History:

    • karo.memory.conversation_history.ConversationHistory class for managing short-term, turn-by-turn chat history buffer
    • max_history_messages option to BaseAgentConfig to control the size of the internal ConversationHistory buffer
    • BaseAgent.reset_history() method to clear the conversation history buffer
    • Automatic history management in BaseAgent for adding user/assistant messages and including history in prompts

  • Deployment Framework:

    • karo/serving/ module with FastAPI server (server.py), API models (models.py), JWT authentication (auth.py), and agent configuration loading from YAML (config.py)
    • karo/cli/ module with click-based CLI (main.py)
    • karo serve command (cli/serve_command.py) to launch the FastAPI server, loading agents via YAML config
    • karo generate-token command (cli/token_command.py) for creating JWT API tokens
    • Added optional [serve] dependencies (fastapi, uvicorn, python-jose, pyyaml, click) to pyproject.toml

  • Logging System:

    • karo/utils/logging_config.py with setup_logging function for configurable logging (stderr or file)
    • --log-level and --log-file options to the karo serve CLI command
    • /logs API endpoint to serving/server.py for retrieving recent log file entries (requires JWT auth)

  • Session Management (In-Memory):

    • karo/sessions/ module with KaroSession, KaroEvent models and BaseSessionService, InMemorySessionService
    • Documentation in /karo/docs/official-docs/guides/sessions.md

  • New Examples:

    • order-chatbot example demonstrating FAQ retrieval via MemoryManager, external tool execution (CsvOrderReaderTool), and multi-turn conversation using ConversationHistory

  • Containerization:

    • Dockerfile for building a container image of the FastAPI server
    • .dockerignore to exclude unnecessary files from the build context

Added

  • Ingestion Script:
    • Added karo/utils/base_ingestion_script.py as a base for creating custom knowledge base ingestion scripts.

Changed

  • BREAKING (Tool Handling Refactor):

    • Removed tools and max_tool_iterations parameters from BaseAgentConfig
    • Removed internal tool execution logic (_prepare_llm_tools, _execute_tool_calls) from BaseAgent
    • BaseAgent.run no longer handles the tool execution loop internally
    • Tool execution now requires external orchestration logic based on the agent's output_schema

  • BREAKING (Session Management Integration):

    • Modified karo/serving/server.py (/invoke endpoint) to integrate InMemorySessionService for session creation, history/state passing, and event logging
    • Modified karo/serving/models.py (InvokeRequest, InvokeResponse) to include session_id
    • Modified karo/core/base_agent.py (BaseAgent, BaseAgentConfig) to remove internal history management and accept history/state via the run method

  • Updated OpenAIProvider, AnthropicProvider, and GeminiProvider generate_response methods to remove unused tools and tool_choice parameters

  • Moved CsvOrderReaderTool and ExcelSummarizerTool to the karo/tools/ directory.

  • Updated documentation (guides/agents.md, guides/tools.md, getting-started/quickstart.md, getting-started/core-concepts.md) to reflect the refactored tool handling, new conversation history feature, and deployment options

  • Refactored example files to use external tool orchestration and the new conversation history management

  • Changed imports in core modules and examples to use consistent absolute paths to resolve Pydantic validation issues

  • Updated default paths in example configuration files to be suitable for container environments

Fixed

  • Corrected AttributeError in examples/base-examples/5_system_prompt_builder_example.py by removing reliance on removed BaseAgent.llm_tools attribute
  • Fixed ImportError in examples/excel-summarizer/main.py by demonstrating execution as a module
  • Fixed AttributeError in examples/order-chatbot/main.py by removing call to non-existent MemoryManager.count_memories
  • Fixed NameError for Query import in karo/serving/server.py
  • Fixed .env file path loading in karo/cli/serve_command.py
  • Removed unused bot_response_for_history variable after implementing internal history management
  • Fixed Pydantic validation error in InMemorySessionService.create_session when handling session_id=None
  • Fixed extraction of assistant response content for session event logging in karo/serving/server.py

[0.2.0] - 2025-04-19

Added

  • Support for additional LLM providers:
    • AnthropicProvider - Implementation for Anthropic Claude models
    • GeminiProvider - Implementation for Google's Gemini models
  • New multi_provider example demonstrating how to use and switch between different LLM providers

Improved

  • Updated documentation to cover multiple provider options
  • Expanded testing coverage to verify functionality with Anthropic and Gemini models
  • Ensured backward compatibility with all existing examples (basic_chatbot, chat_with_memory, agent_with_tools, system_prompt_builder)

Fixed

  • Resolved compatibility issues between different provider response formats
  • Standardized provider interfaces for consistent behavior across different LLMs

[0.1.0] - 2025-04-18

Added

Core Framework

  • Initial release of the Karo framework
  • BaseAgent implementation - the central orchestrator for handling user input, LLM interactions, tool usage, and response generation
  • BaseAgentConfig - configuration model for defining agent behavior
  • ReAct-style reasoning loop for tool usage and response generation
  • Support for input/output schema validation using Pydantic

LLM Providers

  • OpenAIProvider - Implementation for interacting with OpenAI models
  • Provider abstraction layer for LLM-agnostic agent configuration

Memory Systems

  • MemoryManager - Interface for persistent memory storage and retrieval
  • Support for RAG (Retrieval Augmented Generation) from knowledge bases
  • Conversation history management

Tools

  • Excel summarizer tool - Analyze and summarize Excel spreadsheets
  • Tool abstraction interface for extending agent capabilities

Prompt Management

  • SystemPromptBuilder - Dynamic system prompt construction
  • Template-based prompt generation

Examples

  • basic_chatbot - Simple implementation of a conversational agent
  • chat_with_memory - Demonstration of persistent conversation memory
  • agent_with_tools - Example using tools for enhanced capabilities
  • system_prompt_builder - Guide to creating custom system prompts

Documentation

  • Initial documentation for core components
  • Setup and configuration guides
  • API reference