cat-agent 0.1.1

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
• Structured logging — Loguru-powered logging with coloured console, JSON, and file rotation support

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

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

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)

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
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.settings	Configuration via environment variables

Testing

• Test count: 222+ tests across tests/test_agent.py, tests/test_agents.py, tests/test_llm.py, tests/test_memory.py, tests/test_tools.py, and tests/test_utils.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

License

Licensed under the Apache License 2.0.

Author

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