keprompt 0.9.7

A prompt engineering tool for large language models

KePrompt

A powerful prompt engineering and LLM interaction tool designed for developers, researchers, and AI practitioners to streamline communication with various Large Language Model providers.

Overview

KePrompt provides a flexible framework for crafting, executing, and iterating on LLM prompts across multiple AI providers.

Philosophy

• A domain-specific language allows for easy prompt definition and development.
• This is translated into a universal prompt structure upon which the code is implemented.
• Different company interfaces translate universal prompt structure to company specific prompts and back.

Features

• Multi-Provider Support: Interfaces with Anthropic, OpenAI, Google, MistralAI, XAI, DeepSeek, and more
• Prompt Language: Simple yet powerful DSL for defining prompts
• Function Calling: Integrated tools for file operations, web requests, and user interaction
• User-Defined Functions: Create custom functions in any programming language that LLMs can call
• Language Agnostic Extensions: Write functions in Python, Shell, Go, Rust, or any executable language
• Function Override System: Replace built-in functions with custom implementations
• API Key Management: Secure storage of API keys via system keyring
• Rich Terminal Output: Terminal-friendly visuals with color-coded responses
• Logging: Automatic conversation and response logging
• Cost Tracking: Token usage and cost estimation for API calls
• Extensive Debugging Support: different debugging options to aid in Prompt development
• File Versioning: Renames files adding version number instead of overwriting to aid in development

Installation

# Install from PyPI
pip install keprompt

# Install from source
git clone https://github.com/yourusername/keprompt.git
cd keprompt

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install for development
pip install -e .

# For development with additional tools
pip install -r requirements-dev.txt

Quick Start

#!/bin/bash

# Create prompts directory if it doesn't exist
mkdir -p prompts

# Write content to Test.prompt
cat > prompts/Test.prompt << 'EOL'
.# Make snake program with gpt-4o
.llm "model": "gpt-4o"
.system
You are to provide short concise answers.
.user
Generate the python code implementing the game of snake, and write the code to the file snake.py using the provided writefile function.
.exec
EOL

echo "Created prompts/Test.prompt successfully."

keprompt -e Test --debug Messages

Output

(keprompt-py3.10) jerry@desktop:~/PycharmProjects/keprompt$ keprompt -e Test --debug Messages
╭──Test.prompt───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│00 .#       Make snake program with gpt-4o                                                                                                                                                                                                  │
│01 .llm     "model": "gpt-4o"                                                                                                                                                                                                               │
│02 .system  You are to provide short concise answers.                                                                                                                                                                                       │
│03 .user    Generate the python code implementing the game of snake, and write the code to the file snake.py using the provided writefile function.                                                                                         │
│04 .exec    Calling OpenAI::gpt-4o

│╭─── Messages Sent to gpt-4o ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮│
││ system    Text(You are to provide short concise answers.)                                                                                                                                                                                ││
││ user      Text(Generate the python code implementing the game of snake, and write the code to the file snake.py using the provided writefile function.)                                                                                  ││
│╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯│
│            Call-01 Elapsed: 17.14 seconds 0.00 tps                                                                                                                                                                                          
│
│╭─── Messages Sent to gpt-4o ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮│
││ system    Text(You are to provide short concise answers.)                                                                                                                                                                                ││
││ user      Text(Generate the python code implementing the game of snake, and write the code to the file snake.py using the provided writefile function.)                                                                                  ││
││ assistant Call writefile(id=call_O2R056UlBxXZfzBXs7ESAjk7, "filename": "snake.py", "content": "import pygame\nimport time...")                                                                                                           ││
││ tool      Rtn  writefile(id=call_O2R056UlBxXZfzBXs7ESAjk7, content:Content written to file './snake.py')                                                                                                                                 ││
│╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯│
│            Call-02 Elapsed: 1.08 seconds 0.00 tps                                                                                                                                                                                           
│
│╭─── Messages Received from gpt-4o ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮│
││ system    Text(You are to provide short concise answers.)                                                                                                                                                                                ││
││ user      Text(Generate the python code implementing the game of snake, and write the code to the file snake.py using the provided writefile function.)                                                                                  ││
││ assistant Call writefile(id=call_O2R056UlBxXZfzBXs7ESAjk7, "filename": "snake.py", "content": "import pygame\nimport time...")                                                                                                           ││
││ tool      Rtn  writefile(id=call_O2R056UlBxXZfzBXs7ESAjk7, content:Content written to file './snake.py')                                                                                                                                 ││
││ assistant Text(The Snake game code has been successfully written to the file `snake.py`. You can run it using Python to play the game!)                                                                                                  ││
│╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯│
│04 .exec    18.31 secs output tokens 0 at 0.00 tps                                                                                                          │
│04 .exec   Tokens In=0($0.0000), Out=0($0.0000) Total=$0.0000                                                                                                                                                                              │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Wrote logs/Test.svg to disk

Command Line Options

keprompt [-h] [-v] [--param key value] [-m] [-f] [-p [PROMPTS]] [-c [CODE]] [-l [LIST]] [-e [EXECUTE]] [-k] [-d {Statements,Prompt,LLM,Functions,Messages} [...]] [-r] [--init] [--check-builtins] [--update-builtins]

Option	Description
-h, --help	Show help message and exit
-v, --version	Show version information and exit
--param key value	Add key/value pairs for substitution in prompts
-m, --models	List all available LLM models
-f, --functions	List all available functions (built-in + user-defined)
-p, --prompts [PATTERN]	List available prompt files (default: all)
-c, --code [PATTERN]	Show prompt code/commands in files
-l, --list [PATTERN]	List prompt file content line by line
-e, --execute [PATTERN]	Execute one or more prompt files
-k, --key	Add or update API keys for LLM providers
-d, --debug {Statements,Prompt,LLM,Functions,Messages}	Enable debug output for specific components
-r, --remove	Remove all backup files with .nn pattern
--init	Initialize prompts and functions directories
--check-builtins	Check for built-in function updates
--update-builtins	Update built-in functions
--output-only	Output only the final LLM response text (for programmatic usage)

Prompt Language

keprompt uses a simple line-based language for defining prompts. Each line either begins with a command (prefixed with .) or is treated as content. Here are the available commands:

Command	Description
.#	Comment (ignored)
.assistant	Define assistant message
.clear ["pattern1", ...]	Delete files matching pattern(s)
.cmd function(arg=value)	Execute a predefined function
.debug ["element1", ...]	Display debug information
.exec	Execute the prompt (send to LLM)
.exit	Exit execution
.image filename	Include an image in the message
.include filename	Include text file content
.llm {options}	Configure LLM (model, temperature, etc.)
.system text	Define system message
.text text	Add text to the current message
.user text	Define user message

Variable Substitution

You can use <<variable>> syntax for substituting variables in prompts. Variables can be defined using the --param option.

Available Functions

keprompt provides several built-in functions that can be called from prompts:

Function	Description
readfile(filename)	Read content from a file
writefile(filename, content)	Write content to a file
write_base64_file(filename, base64_str)	Write decoded base64 content to a file
wwwget(url)	Fetch content from a web URL
execcmd(cmd)	Execute a shell command
askuser(question)	Prompt the user for input

User-Defined Functions

keprompt supports custom user-defined functions that can be written in any programming language. These functions are automatically discovered and made available to LLMs alongside built-in functions.

Getting Started with Custom Functions

1. Initialize your project (if not already done):

   keprompt --init
   

2. Create a custom function executable in ./prompts/functions/:

   # Create a Python function
   cat > prompts/functions/my_tools << 'EOF'
   #!/usr/bin/env python3
   import json, sys
   
   def get_schema():
       return [{
           "name": "hello",
           "description": "Say hello to someone",
           "parameters": {
               "type": "object",
               "properties": {
                   "name": {"type": "string", "description": "Name to greet"}
               },
               "required": ["name"]
           }
       }]
   
   if sys.argv[1] == "--list-functions":
       print(json.dumps(get_schema()))
   elif sys.argv[1] == "hello":
       args = json.loads(sys.stdin.read())
       print(f"Hello, {args['name']}!")
   EOF
   
   # Make it executable
   chmod +x prompts/functions/my_tools
   

3. Verify function discovery:

   keprompt --functions
   

4. Use in prompts:

   cat > prompts/test.prompt << 'EOF'
   .llm {"model": "gpt-4o-mini"}
   .user Please use the hello function to greet me. My name is Alice.
   .exec
   EOF
   
   keprompt -e test
   

Function Interface Specification

All user-defined functions must follow this interface:

Schema Discovery

Functions must support --list-functions to return their schema:

./my_function --list-functions

Returns JSON array of function definitions:

[{
    "name": "function_name",
    "description": "Function description",
    "parameters": {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "Parameter description"}
        },
        "required": ["param1"]
    }
}]

Function Execution

Functions are called with the function name and JSON arguments via stdin:

echo '{"param1": "value1"}' | ./my_function function_name

Examples

Shell Script Function

#!/bin/bash
# File: prompts/functions/git_tools

if [ "$1" = "--list-functions" ]; then
    cat << 'EOF'
[{
    "name": "git_status",
    "description": "Get git repository status",
    "parameters": {
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "Repository path", "default": "."}
        }
    }
}]
EOF
    exit 0
fi

if [ "$1" = "git_status" ]; then
    ARGS=$(cat)
    PATH_ARG=$(echo "$ARGS" | jq -r '.path // "."')
    cd "$PATH_ARG" && git status --porcelain
fi

Python Function with Multiple Functions

#!/usr/bin/env python3
# File: prompts/functions/math_tools
import json, sys, math

FUNCTIONS = {
    "add": {
        "name": "add",
        "description": "Add two numbers",
        "parameters": {
            "type": "object",
            "properties": {
                "a": {"type": "number", "description": "First number"},
                "b": {"type": "number", "description": "Second number"}
            },
            "required": ["a", "b"]
        }
    },
    "sqrt": {
        "name": "sqrt",
        "description": "Calculate square root",
        "parameters": {
            "type": "object",
            "properties": {
                "x": {"type": "number", "description": "Number to calculate square root of"}
            },
            "required": ["x"]
        }
    }
}

def add(a, b):
    return f"The sum of {a} and {b} is {a + b}"

def sqrt(x):
    return f"The square root of {x} is {math.sqrt(x)}"

if len(sys.argv) > 1:
    if sys.argv[1] == "--list-functions":
        print(json.dumps(list(FUNCTIONS.values())))
    elif sys.argv[1] in FUNCTIONS:
        args = json.loads(sys.stdin.read())
        if sys.argv[1] == "add":
            print(add(args["a"], args["b"]))
        elif sys.argv[1] == "sqrt":
            print(sqrt(args["x"]))

Function Management

Override Built-in Functions

You can override built-in functions by creating executables with names that come alphabetically before keprompt_builtins:

# Override the built-in readfile function
cp my_custom_readfile prompts/functions/01_readfile
chmod +x prompts/functions/01_readfile

Function Discovery Rules

• Functions are loaded alphabetically by filename
• First definition wins (duplicates are ignored)
• Only executable files (+x permission) are considered
• Functions must support --list-functions for automatic discovery

Debugging Functions

# Test function schema
./prompts/functions/my_function --list-functions

# Test function execution
echo '{"param": "value"}' | ./prompts/functions/my_function function_name

# Debug function calls in prompts
keprompt -e my_prompt -d Functions

Best Practices

1. Error Handling: Always include proper error handling in your functions
2. Validation: Validate input parameters before processing
3. Documentation: Provide clear descriptions in function schemas
4. Testing: Test functions independently before using in prompts
5. Naming: Use descriptive function and parameter names
6. Performance: Consider timeout implications (30-second limit)

Advanced Features

Function Versioning

# Check built-in function version
keprompt --check-builtins

# Update built-in functions
keprompt --update-builtins

Multiple Functions per Executable

A single executable can provide multiple functions by checking the function name argument and implementing different behaviors.

Language Support

Functions can be written in any language that can:

• Accept command line arguments
• Read from stdin
• Write to stdout
• Be made executable on your system

Examples: Python, Shell, Go, Rust, Node.js, Ruby, Perl, compiled C/C++, etc.

Supported LLM Providers

• Anthropic: Claude models
• OpenAI: GPT models including GPT-4o
• Google: Gemini models
• MistralAI: Mistral, Small, Large models
• XAI: Grok models
• DeepSeek: DeepSeek Chat and Reasoner models

Execute following command to see supported models:

keprompt -m

Available Models

Company	Model	Max Token	$/mT In	$/mT Out	Input	Output	Functions	Cutoff	Description
Anthropic	claude-haiku-3	200000	0.2500	1.2500	Text	Text	Yes	See docs	Legacy fastest model
	claude-haiku-3.5	200000	0.8000	4.0000	Text+Vision	Text	Yes	See docs	Fastest, most cost-effective model
	claude-opus-3	200000	15.0000	75.0000	Text+Vision	Text	Yes	See docs	Legacy most intelligent model
	claude-opus-4	200000	15.0000	75.0000	Text+Vision	Text	Yes	See docs	Most intelligent model for complex tasks
	claude-sonnet-3.7	200000	3.0000	15.0000	Text+Vision	Text	Yes	See docs	Legacy balanced model
	claude-sonnet-4	200000	3.0000	15.0000	Text+Vision	Text	Yes	See docs	Optimal balance of intelligence, cost, and speed
DeepSeek	deepseek-chat	64000	0.2700	1.1000	Text	Text	Yes	See docs	High-performance model for general tasks with excellent reasoning capabilities
	deepseek-reasoner	64000	0.5500	2.1900	Text	Text	Yes	See docs	Advanced reasoning model with transparent thinking process
Google	gemini-1.5-flash	1000000	0.0750	0.3000	Text+Vision	Text	Yes	See docs	Fastest multimodal model with great performance
	gemini-1.5-flash-8b	1000000	0.0375	0.1500	Text+Vision	Text	Yes	See docs	Smallest model for lower intelligence use cases
	gemini-1.5-pro	2000000	1.2500	5.0000	Text+Vision	Text	Yes	See docs	Highest intelligence Gemini 1.5 series model
	gemini-2.0-flash	1000000	0.1000	0.4000	Text+Vision+Audio	Text+Image	Yes	See docs	Most balanced multimodal model, built for the era of Agents
	gemini-2.0-flash-lite	1000000	0.0750	0.3000	Text	Text	Yes	See docs	Smallest and most cost effective model
	gemini-2.5-flash	1000000	0.3000	2.5000	Text+Vision+Audio	Text	Yes	See docs	First hybrid reasoning model with thinking budgets
	gemini-2.5-flash-lite	1000000	0.1000	0.4000	Text+Vision+Audio	Text	Yes	See docs	Smallest and most cost effective model, built for at scale usage
	gemini-2.5-pro	1000000	1.2500	10.0000	Text+Vision+Audio	Text	Yes	See docs	State-of-the-art multipurpose model, excels at coding and complex reasoning
	gemma-3-27b	8192	0.0000	0.0000	Text	Text	No	See docs	Lightweight, state-of-the-art, open model
	gemma-3n-e4b	8192	0.0000	0.0000	Text	Text	No	See docs	Open model built for efficient performance on everyday devices
MistralAI	codestral	32000	0.3000	0.9000	Text	Text	Yes	See docs	Lightweight, fast, and proficient in over 80 programming languages
	devstral-medium	128000	0.4000	2.0000	Text	Text	Yes	See docs	Enhanced model for advanced coding agents
	devstral-small	128000	0.1000	0.3000	Text	Text	Yes	See docs	The best open-source model for coding agents
	magistral-medium	128000	2.0000	5.0000	Text	Text	Yes	See docs	Thinking model excelling in domain-specific, transparent, and multilingual reasoning
	magistral-small	128000	0.5000	1.5000	Text	Text	Yes	See docs	Thinking model excelling in domain-specific reasoning
	ministral-3b-24.10	128000	0.0400	0.0400	Text	Text	Yes	See docs	Most efficient edge model
	ministral-8b-24.10	128000	0.1000	1.0000	Text	Text	Yes	See docs	Powerful model for on-device use cases
	mistral-7b	32000	0.2500	0.2500	Text	Text	Yes	See docs	A 7B transformer model, fast-deployed and easily customisable
	mistral-large	128000	2.0000	6.0000	Text	Text	Yes	See docs	Top-tier reasoning for high-complexity tasks and sophisticated problems
	mistral-medium-3	128000	0.4000	2.0000	Text	Text	Yes	See docs	State-of-the-art performance. Simplified enterprise deployments. Cost-efficient
	mistral-nemo	128000	0.1500	0.1500	Text	Text	Yes	See docs	State-of-the-art Mistral model trained specifically for code tasks
	mistral-saba	32000	0.2000	0.6000	Text	Text	Yes	See docs	Custom-trained model to serve specific geographies, markets, and customers
	mistral-small-3.2	128000	0.1000	0.3000	Text+Vision	Text	Yes	See docs	SOTA. Multimodal. Multilingual. Apache 2.0
	mixtral-8x22b	64000	2.0000	6.0000	Text	Text	Yes	See docs	A 22B sparse Mixture-of-Experts (SMoE). Uses only 39B active parameters out of 141B
	mixtral-8x7b	32000	0.7000	0.7000	Text	Text	Yes	See docs	A 7B sparse Mixture-of-Experts (SMoE). Uses 12.9B active parameters out of 45B total
	pixtral-12b	128000	0.1500	0.1500	Text+Vision	Text	Yes	See docs	Vision-capable small model
	pixtral-large	128000	2.0000	6.0000	Text+Vision	Text	Yes	See docs	Vision-capable large model with frontier reasoning capabilities
	voxtral-mini	128000	0.0400	0.0400	Text+Audio	Text	Yes	See docs	Low-latency speech recognition for edge and devices
	voxtral-small	128000	0.1000	0.3000	Text+Audio	Text	Yes	See docs	State-of-the-art performance on speech and audio understanding
OpenAI	gpt-4.1	128000	2.0000	8.0000	Text+Vision	Text	Yes	See docs	Smartest model for complex tasks
	gpt-4.1-mini	128000	0.4000	1.6000	Text+Vision	Text	Yes	See docs	Affordable model balancing speed and intelligence
	gpt-4.1-nano	128000	0.1000	0.4000	Text	Text	Yes	See docs	Fastest, most cost-effective model for low-latency tasks
	gpt-4o	128000	5.0000	20.0000	Text+Vision	Text	Yes	2023-10	Advanced multimodal model for complex tasks
	gpt-4o-mini	128000	0.6000	2.4000	Text+Vision	Text	Yes	See docs	Affordable multimodal model
	o1	128000	3.0000	12.0000	Text	Text	Limited	See docs	Reasoning model for complex problems
	o1-mini	128000	0.6000	2.4000	Text	Text	Limited	See docs	Smaller reasoning model
	o3	128000	2.0000	8.0000	Text	Text	Yes	See docs	Most powerful reasoning model with leading performance
	o3-mini	128000	1.1000	4.4000	Text	Text	Yes	See docs	Compact reasoning model
	o4-mini	128000	1.1000	4.4000	Text	Text	Yes	See docs	Faster, cost-efficient reasoning model
XAI	grok-2-1212	131072	2.0000	10.0000	Text	Text	Yes	See docs	Updated Grok-2 model with improved performance
	grok-2-vision-1212	131072	2.0000	10.0000	Text+Vision	Text	Yes	See docs	Vision-capable Grok-2 model
	grok-3	131072	3.0000	15.0000	Text+Vision	Text	Yes	See docs	Flagship enterprise model with advanced reasoning
	grok-3-mini	131072	0.3000	0.5000	Text	Text	Yes	See docs	Lightweight reasoning model for cost-effective applications
	grok-4	256000	3.0000	15.0000	Text+Vision	Text	Yes	See docs	The world's best model
	grok-beta	131072	5.0000	15.0000	Text	Text	Yes	See docs	Beta version of Grok with experimental features
	grok-vision-beta	8192	5.0000	15.0000	Text+Vision	Text	Yes	See docs	Beta vision model with image understanding capabilities

Run keprompt -m for complete details including pricing, context limits, and capabilities.

Example Usage

Basic Prompt Execution

# Create a prompt file
cat > prompts/example.prompt << EOL
.llm {"model": "claude-3-7-sonnet-latest"}
.system You are a helpful assistant.
.user Tell me about prompt engineering.
.exec
EOL

# Execute the prompt
keprompt -e example --debug Messages

Using Variables

# Create a prompt with variables
cat > prompts/greeting.prompt << EOL
.llm {"model": "<<model>>"}
.user Hello! My name is <<name>>.
.exec
EOL

# Execute with variables
keprompt -e greeting --param name "Alice" --param model "claude-3-7-sonnet-latest"  --debug Messages

Using Functions

# Create a prompt that uses functions
cat > prompts/analyze.prompt << EOL
.llm {"model": "claude-3-7-sonnet-latest"}
.user Analyze this text:
.cmd readfile(filename="data.txt")
.exec
EOL

# Execute the prompt
keprompt -e analyze  --debug Messages

Working with Prompts

1. Create prompt files in the prompts/ directory with .prompt extension
2. List available prompts with keprompt -p
3. Examine prompt content with keprompt -l promptname
4. Execute prompts with keprompt -e promptname
5. Debug execution with keprompt -e promptname -d Messages LLM

Output and Logging

keprompt automatically saves conversation logs to the logs/ directory:

• logs/promptname.log: Text log of the interaction
• logs/promptname.svg: SVG visualization of the conversation
• logs/promptname_messages.json: JSON format of all messages

API Key Management

# Add or update API key
keprompt -k
# Select provider from the menu and enter your API key

Advanced Usage

Debugging Options

# Debug LLM API calls
This will give a full dump opn the screen of the data structure sent to API, and a full dump of its response.
 
keprompt -e example -d LLM

# Debug function calls
keprompt -e example -d Functions

# Debug everything
keprompt -e example -d Statements Prompt LLM Functions Messages

Working with Multiple Prompts

# Execute all prompts matching a pattern
keprompt -e "test*"

# List all prompts with "gpt" in the name
keprompt -p "*gpt*"

Programmatic Usage

For batch processing and automation, use the --output-only flag to get clean LLM output suitable for scripts:

# Get only the LLM response text (no UI, logging, or metadata)
keprompt -e my_prompt --output-only

# Capture output in a variable
result=$(keprompt -e my_prompt --output-only)
echo "LLM said: $result"

# Use in pipelines
keprompt -e analyze_data --output-only | grep "important"

# Process multiple prompts
for prompt in prompts/*.prompt; do
    echo "Processing $prompt..."
    keprompt -e "$(basename "$prompt" .prompt)" --output-only > "results/$(basename "$prompt" .prompt).txt"
done

Key features of --output-only mode:

• Outputs only the final LLM response text to stdout
• Suppresses all UI elements, progress indicators, and formatting
• Disables logging to files
• Errors are sent to stderr (won't contaminate stdout)
• Perfect for shell scripts, automation, and batch processing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Todos, Errors, open points

• Done: Crash if no .prompt found
• Done: Was invalid api-key!
• Done: Added cmd arg --statements...

Release Process

To release a new version:

1. Install build tools if needed:

   pip install build twine
   

2. Run the release script:

   ./release.py
   

   This will:

   • Check for uncommitted changes in Git
   • Verify if the current version is correct
   • Build distribution packages
   • Upload to TestPyPI (optional)
   • Upload to PyPI (if confirmed)

3. Alternatively, manually:

   • Update version in keprompt/version.py
   • Build: python -m build
   • Upload: python -m twine upload dist/*