Karn

Karn is an interactive AI assistant for your Elixir codebase, designed to be used within an IEx session. It helps you understand and query your code using natural language, leveraging the power of Large Language Models.

Features

  • Natural Language Queries: Ask questions about your code in plain English.
  • Code Explanations: Get detailed explanations for specific modules and their functions.
  • Conversational Context: Karn remembers the history of your conversation, allowing for follow-up questions.
  • Context Management: View the current conversation context or reset it when needed.
  • Usage Tracking: Monitor your LLM token usage for the current session.

Installation

Add karn as a dependency to your mix.exs file. It is recommended to add it only for the :dev environment. User can change the default model by adding to their dev config 

  config :karn,
    default_model: "anthropic:claude-3-5-haiku-20241022"
def deps do
  [
    {:karn, "~> 0.1.0", only: [:dev]}
  ]
end

One can also install Karn using igniter 

# uses gemini as default model
mix igniter.install karn

mix igniter.install karn --anthropic

Supported options are --google, --anthropic, --openai You can use any model supported by ReqLLM, the supported options are just to get started fast

Then, fetch the dependencies:

mix deps.get

Setup and Usage

Karn is designed to be used interactively within an IEx session.

1. Start IEx

Start your project's IEx session:

# phoenix application
iex -S mix phx.server

# generic
iex -S mix run

2. Configure API Key

Karn uses the ReqLLM library to communicate with LLMs. You need to provide an API key for the desired service. The default model is google:gemini-2.0-flash, so you'll need a Google AI API key.

You can configure your key in one of two ways:

  1. Environment Variable (Recommended): Export the key in your shell.

    export GOOGLE_API_KEY="your-google-api-key"

    ReqLLM will automatically pick it up when you start iex.

  2. In your IEx session: Configure the key manually.

    # Replace "your-google-api-key" with your actual key
ReqLLM.put_key(:google_api_key, "your-google-api-key")

3. Start the Karn Server

Start the server:

Karn.start

4. Use Karn

For a more human-friendly experience, import the Karn functions into your IEx shell. This allows you to call them directly.

iex> import Karn
Karn

Now you can interact with the AI.

General Query (q/1)

Ask any question about Elixir or your project.

iex> q "What is the difference between a GenServer and an Agent?"
╭─ assistant ─────────────────────────────────────────────────────────────────╮
│ Okay, Let's clarify the difference between GenServer and Agent in Elixir.   │
│                                                                             │
│ **Agent:**                                                                  │
│                                                                             │
│ *   **Simple State Management:** An Agent is...                             │
│                                                                             │
╰─────────────────────────────────────────────────────────────────────────────╯

Explain Module (e/3)

Get an explanation for a specific module. You can also provide related modules for more context.

# Get a general explanation of MyModule
iex> e Karn
╭─ assistant ──────────────────────────────────────────────────────────╮
│ Okay, I've analyzed the `Elixir.Karn` module. Here's a breakdown:    │
│                                                                      │
│ **Purpose:**                                                         │
│                                                                      │
│ The `Karn` module acts as a client...                                │
│ explanation, context management, and usage tracking.                 │
│                                                                      │
╰──────────────────────────────────────────────────────────────────────╯

# Get a specific explanation of MyModule
iex> e MyModule,"How does function b work?"

# only 1 reference
iex> e MyModule,ModuleB,"How are the two modules related"

# multiple references
iex> e MyModule,[ModuleB,ModuleC],"Why is MyModule.function behaving this way ?"

#Ask a specific question about MyModule, providing another module for context
iex> e MyModule, "Write me ecto query to fetch records for xyz schema ?"

View Conversation Context (view_context/0)

See the history of messages (user and assistant) in the current session.

iex> view_context()

Reset Conversation Context (reset_context/1)

Clear the current conversation history. You can optionally provide a new system prompt.

# Reset to the default system prompt
iex> reset_context()

# Reset with a custom system prompt
iex> reset_context "You are a helpful Elixir assistant."

View Usage (usage/0)

Check the token usage (input, output, and total cost) for the current session.

iex> usage()

Stop Karn (stop/0)

Stop the Karn.Ai.Server. This will also print the final usage statistics for the session.

iex> stop()