Troubleshooting & Debugging 🐛

Let's be honest: AI models can be unpredictable. When you're running lightweight 1-7B parameter models locally, they are more prone to making formatting mistakes, calling tools with weird parameters, or getting stuck in loops.

Kern provides built-in debug tools to show you exactly what is sent to the model, what comes back, and how tools are being executed step-by-step.

🛠️ Enabling Debug Mode

You can turn on debug logs in three different ways:

1. Per-Agent: Set debug_mode=True when initializing your agent.
2. Per-Run: Pass debug_mode=True to the run() or print_response() methods.
3. Globally: Set the environment variable KERN_DEBUG=True.

Here's how to turn it on for your agent using a local Llama model:

1from kern.agent import Agent
2from kern.models.openai import OpenAIChat
3from kern.tools.hackernews import HackerNewsTools
4
5agent = Agent(
6    model=OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1"),
7    tools=[HackerNewsTools()],
8    instructions="Summarize technology news in 3 bullet points.",
9    markdown=True,
10    debug_mode=True,      # Turn on logging! 🔍
11    # debug_level=2,      # Uncomment for ultra-detailed trace logging
12)
13
14# Run agent and inspect the detailed terminal outputs!
15agent.print_response("Any new articles on Quantum Computing?")

⚠️ Common Debugging Scenarios for Small Models

When debugging local 1-7B models, keep an eye out for these common issues:

1. Tool Call Failures ❌

Small models can sometimes try to invoke a tool but get the parameter names wrong. Check the debug logs to see the exact JSON payload the model sent to the tool. If it keeps failing, try writing simpler tool descriptions or using simpler parameter types.

2. Infinite Loops 🔄

If a model gets confused, it might call the same tool repeatedly with the same arguments. You can prevent runaway token consumption by setting max_loops on the agent:

1agent = Agent(
2    model=OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1"),
3    max_loops=3  # Stop after 3 tool execution loops 🛡️
4)

3. JSON Output Formatting 📦

If the model output doesn't conform to your Pydantic schemas, Kern automatically triggers its JSON repair engine. The debug log will show you the malformed output, the repaired version, and if it succeeded.

💬 Playground in the Terminal (CLI App)

Want to quickly test multi-turn conversations and memory without building a frontend? Use the built-in CLI mode! It starts an interactive chat loop right in your shell:

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.models.openai import OpenAIChat
4from kern.tools.hackernews import HackerNewsTools
5
6agent = Agent(
7    model=OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1"),
8    tools=[HackerNewsTools()],
9    db=SqliteDb(db_file="tmp/chat_history.db"),
10    add_history_to_context=True,
11    num_history_runs=3,
12    markdown=True,
13)
14
15# Launch the interactive terminal chat! 🚀
16agent.cli_app(stream=True)