cat-agent 0.2.0

Cat-Agent: Enhancing LLMs with Agent Workflows, RAG, Function Calling, and Code Interpreter.

Cat-Agent

Enhancing LLMs with Agent Workflows, RAG, Function Calling, and Code Interpreter.

---

Overview

Cat-Agent is a Python framework for building LLM-powered agents with pluggable tools, multi-agent workflows, and production-ready features. Use it to add function calling, RAG, code execution, and custom tools to your chat or automation pipelines.

Features

• Agent workflows — Agent, Assistant, ReActChat, FnCallAgent, DocQAAgent, GroupChat, Router, and more
• Function calling — Native tool/function support for LLMs
• RAG — Retrieval-augmented generation with vector, keyword, and hybrid search
• Code interpreter — Safe Python execution via Docker or WASM sandbox (no Docker required)
• Rich tool set — Web search, doc parsing, image generation, MCP, storage, and extensible custom tools
• Multiple LLM backends — OpenAI-compatible APIs, LlamaCpp (+ vision), OpenVINO, Transformers, MLX-LM (Apple silicon)
• Structured logging — Loguru-powered logging with coloured console, JSON, and file rotation support
• Observability hooks — Structured run/LLM/tool events with pluggable handlers (callbacks, print, loguru)

Requirements

• Python 3.10+ (use python3.10 or later to run examples and tests)

Installation

  pip install cat-agent

Optional extras:

  pip install cat-agent[rag]              # RAG (retrieval, doc parsing, etc.)
  pip install cat-agent[mcp]              # MCP (Model Context Protocol)
  pip install cat-agent[python_executor]  # Python executor (math, sympy, etc.)
  pip install cat-agent[code_interpreter] # Code interpreter server (Jupyter, FastAPI)

Logging

Cat-Agent uses Loguru for structured, coloured logging. By default the logger is silent (library-friendly). Activate it with a single environment variable:

# Pretty coloured output
CAT_AGENT_LOG_LEVEL=INFO python my_script.py

# Full debug verbosity
CAT_AGENT_LOG_LEVEL=DEBUG python my_script.py

# Structured JSON logs (for log aggregation pipelines)
CAT_AGENT_LOG_LEVEL=INFO CAT_AGENT_LOG_FORMAT=json python my_script.py

# Also write to a rotating log file
CAT_AGENT_LOG_LEVEL=DEBUG CAT_AGENT_LOG_FILE=agent.log python my_script.py

Or configure programmatically:

from cat_agent.log import logger, setup_logger

setup_logger(level="DEBUG")                         # coloured stderr
setup_logger(level="INFO", log_file="/tmp/cat.log") # + rotating file
setup_logger(level="DEBUG", fmt="json")             # structured JSON

logger.info("Agent started")
logger.debug("Processing query: {}", query)

Env Variable	Values	Default
CAT_AGENT_LOG_LEVEL	TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL	(silent)
CAT_AGENT_LOG_FILE	file path	(none)
CAT_AGENT_LOG_FORMAT	pretty, json	pretty

Observability

Cat-Agent emits structured events for agent runs, LLM calls, and tool execution. Handlers are opt-in — when none are registered, behavior and performance are unchanged.

Quick start

from cat_agent.agents import Assistant
from cat_agent.llm.schema import USER, Message
from cat_agent.observability import CallbackHandler, PrintHandler

# Option 1: callback (no manual event parsing — use event.summary())
def on_event(event):
    print(event.summary())

bot = Assistant(llm=..., handlers=[CallbackHandler(on_event)])

# Option 2: print directly
bot = Assistant(llm=..., handlers=[PrintHandler()])

list(bot.run([Message(role=USER, content="Hello")]))

Environment variables

# Enable default loguru trace output
CAT_AGENT_TRACE=1 python my_script.py

# Optional trace log level (default: INFO)
CAT_AGENT_TRACE_LEVEL=DEBUG python my_script.py

Event types

Event	When
run.start / run.end / run.error	Agent run() lifecycle
llm.start / llm.end / llm.chunk	Each LLM call (chunks optional)
tool.start / tool.end / tool.error	Each tool invocation

Each event includes trace_id, run_id, span_id, agent name/class, and a typed payload dict. Use event.to_dict() for JSON export.

Example

  python examples/observability/observability_example.py

Examples

Math tool with LlamaCpp

Registers a custom sum_two_number tool and uses a local GGUF model:

  python examples/llama_cpp_math_guy/llama_cpp_example.py

Math tool with Transformers

Same concept using the HuggingFace Transformers backend (Qwen3-1.7B):

  python examples/transformers_math_guy/math_guy.py

Math tool with MLX-LM (Apple silicon)

Same concept using the MLX-LM backend (requires mlx-lm==0.31.1):

  python examples/mlx_lm_math_guy/math_guy.py

Vision with LlamaCpp

Analyse images from URLs using a multimodal GGUF model (Qwen2-VL):

  python examples/llama_cpp_vision/llama_cpp_vision_example.py

Document parsing agent

Parse CSV/PDF/DOCX files and ask questions about their contents:

  python examples/doc_parser_agent/doc_parser_example.py

Multi-agent: GroupChat

Two agents (Alice and Bob) converse in round-robin to plan a weekend trip:

  python examples/multi_agent/group_chat_example.py

Multi-agent: Router

Intelligently route queries to specialised agents (MathExpert vs GeneralAssistant):

  python examples/multi_agent/router_example.py

RAG with LEANN retriever

Retrieval-augmented generation using LEANN semantic search:

  pip install cat-agent[rag]
  python examples/rag_leann/leann_qwen3_demo.py

Minimal RAG usage in code:

from pathlib import Path
from cat_agent.llm.schema import Message, USER
from cat_agent.memory import Memory
import torch

llm_cfg = {
    "model": "Qwen/Qwen3-1.7B",
    "model_type": "transformers",
    "device": "cuda:0" if torch.cuda.is_available() else "cpu",
}

mem = Memory(llm=llm_cfg, files=["doc.txt"], rag_cfg={"enable_leann": True, "rag_searchers": ["leann_search"]})
messages = [Message(role=USER, content="How much storage does LEANN save?")]
responses = mem.run_nonstream(messages, force_search=True)
print(responses[-1].content)

Kubernetes agent (LEANN RAG)

Kubernetes Q&A agent using LEANN over the Kubernetes Q&A dataset:

  pip install "cat-agent[rag]"
  pip install datasets
  python examples/kubernetes_agent/build_kubernetes_qa_corpus.py   # once
  python examples/kubernetes_agent/kubernetes_agent_example.py

See examples/kubernetes_agent/README.md for details.

WASM code interpreter

Secure Python code execution in a WebAssembly sandbox (no Docker or Node.js needed):

  python examples/wasm_code_interpreter/wasm_code_interpreter_example.py

Logging demo

Demonstrates coloured console logs, JSON output, and file logging alongside an agent:

  python examples/logging_demo/logging_example.py

  # Or with env-var driven config:
  CAT_AGENT_LOG_LEVEL=DEBUG python examples/logging_demo/logging_example.py

LLM Backends

Backend	model_type	Description
OpenAI-compatible	oai	Any OpenAI-compatible API (default)
LlamaCpp	llama_cpp	Local GGUF models via llama-cpp-python
LlamaCpp Vision	llama_cpp_vision	Multimodal GGUF models (Qwen2-VL, LLaVA, etc.)
Transformers	transformers	HuggingFace Transformers models
MLX-LM	mlx_lm	Apple silicon local models via mlx-lm
OpenVINO	openvino	Optimised inference on Intel hardware

from cat_agent.agents import Assistant

bot = Assistant(
    llm={"model_type": "llama_cpp", "repo_id": "Salesforce/xLAM-2-3b-fc-r-gguf", "filename": "xLAM-2-3B-fc-r-F16.gguf"},
    name="MyAgent",
    function_list=["my_tool"],
)

Project Structure

Component	Description
cat_agent.agent	Base Agent class
cat_agent.agents	Assistant, ReActChat, FnCallAgent, DocQA, GroupChat, Router
cat_agent.llm	Chat model backends (OAI, LlamaCpp, LlamaCpp Vision, OpenVINO, Transformers)
cat_agent.tools	CodeInterpreter, WASMCodeInterpreter, Retrieval, DocParser, Storage, MCP, and more
cat_agent.memory	Memory, RAG, and context utilities
cat_agent.log	Loguru-based structured logging
cat_agent.observability	Run/LLM/tool event hooks and handlers
cat_agent.settings	Configuration via environment variables

Testing

• Test count: 230+ tests including observability coverage in tests/test_observability.py.
• Test coverage: 59% (6,038 lines total).
• Run tests: pytest (install with pip install -e ".[test]").
• Report coverage: pytest --cov=cat_agent --cov-report=term

Versioning

chmod +x release.sh        # one time
./release.sh 0.1.2         # or any new X.Y.Z version

License

Licensed under the Apache License 2.0.

Author

Kemalcan Bora — [e-mail] GitHub: kemalcanbora/cat-agent