# KePrompt

**A powerful command-line tool for prompt engineering and AI interaction**

KePrompt lets you work with multiple AI providers (OpenAI, Anthropic, Google, and more) using simple prompt files and a unified command-line interface. No Python programming required.

## Why KePrompt?

- **One tool, many AIs**: Switch between GPT-4, Claude, Gemini, and others with a single command
- **Simple prompt language**: Write prompts using an easy-to-learn syntax
- **Comprehensive cost tracking**: Automatic SQLite-based tracking of all API usage with detailed reporting
- **Conversation management**: Save and resume multi-turn conversations
- **Function calling**: Extend prompts with file operations, web requests, and custom functions
- **Web GUI**: Modern browser-based interface for interactive prompt development
- **Production ready**: Built-in logging, error handling, and debugging tools

## Quick Start

### 0. Prepare Your Working Directory
```bash
# Create a new project directory with isolated Python environment
mkdir myproject
cd myproject
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

### 1. Install KePrompt
```bash
pip install keprompt
```

To install in developers mode use:
```bash
pip install -e ~/keprompt/ 
```



### 2. Initialize your workspace
```bash
keprompt init
```
This creates the `prompts/` directory, copies a default `hello.prompt`, installs default functions, initializes the database, and downloads the model registry — all in one command.

Use `keprompt init --force` to overwrite existing files.

### 3. Set up your API key
```bash
# Add to your .env file or export directly
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
# ... or add to ~/.env
```

### 4. Run the included hello prompt
```bash
keprompt chat new --prompt hello
```

🎉 **You should see the AI's response!** The system automatically tracks costs and saves the conversation.

Try it with different models and questions:
```bash
keprompt chat new --prompt hello --model anthropic/claude-sonnet-4-20250514
keprompt chat new --prompt hello --set question 'tell me a joke'
keprompt chat new --prompt hello --model deepseek/deepseek-chat --set question 'what is 2+2?'
```

## Your First Real Prompt

Let's create something more useful - a file analyzer:

```bash
cat > prompts/analyze.prompt << 'EOF'
.prompt "name":"File Analyzer", "version":"1.0.0", "params":{"model":"gpt-4o", "filename":"file_to_analyze"}
.# Analyze any text file
.llm {"model": "<<model>>"}
.system You are an expert text analyst. Provide clear, actionable insights.
.user Please analyze this file:

.include <<filename>>

Provide a summary, key points, and any recommendations.
.exec
EOF
```

Run it with a parameter:
```bash
keprompt chats create --prompt analyze --set filename "README.md"
```

Run it with 2 parameters:
```bash
keprompt chats create --prompt analyze --set filename "README.md" --set model "openrouter/openai/gpt-oss-20b"
```

## Modern CLI Interface

KePrompt uses an intuitive object-verb command structure:

```bash
keprompt <object> <verb> [options]
```

### Core Objects
- **init** - Initialize workspace (one-stop setup)
- **prompts** - List and manage prompt files
- **chats** - Create and manage conversations
- **models** - Browse available AI models
- **providers** - View AI providers
- **functions** - List available functions
- **server** - Start/stop web interface
- **database** - Manage conversation database

### Common Commands
```bash
# List available prompts
keprompt prompts get

# Create a new conversation
keprompt chats create --prompt hello --set name "Alice"

# Continue a conversation
keprompt chats reply <chat-id> "Tell me more"

# List conversations with costs
keprompt chats get

# Browse available models
keprompt models get --company OpenAI

# Start web interface
keprompt server start --web-gui
```

See the [Knowledge Engineer's Guide](ks/02-knowledge-engineers-guide.md) for the full reference.

## Web GUI Interface

KePrompt includes a modern web-based interface for interactive development:

```bash
# Start server with web GUI
keprompt server start --web-gui

# Specify port (optional)
keprompt server start --web-gui --port 8080

# Development mode with auto-reload
keprompt server start --web-gui --reload
```

Then open your browser to `http://localhost:8080`

**Features:**
- Interactive chat interface
- Real-time cost tracking
- Prompt editor with syntax highlighting
- Model selection and comparison
- Function testing and debugging
- Conversation history browser

## Core Concepts

### Prompt Files
- Stored in `prompts/` directory with `.prompt` extension
- Use simple line-based syntax starting with `.` for commands
- Support variables, functions, and multi-turn conversations

### The Prompt Language
| Command | Purpose | Example |
|---------|---------|---------|
| `.prompt` | **REQUIRED** - Define prompt metadata | `.prompt "name":"My Prompt", "version":"1.0.0"` |
| `.llm` | Configure AI model | `.llm {"model": "gpt-4o"}` |
| `.system` | Set system message | `.system You are a helpful assistant` |
| `.user` | Add user message | `.user What is the weather like?` |
| `.tool_call` | **Represent an LLM tool call** (manual/replay/debug) | `.tool_call readfile(filename="data.txt") id=call_abc123` |
| `.tool_result` | **Represent a tool result** (manual/replay/debug) | `.tool_result id=call_abc123 name=readfile` |
| `.exec` | Send to AI and get response | `.exec` |
| `.cmd` | Call a function | `.cmd readfile(filename="data.txt")` |
| `.print` | Output to console | `.print The result is: <<last_response>>` |

### Representing LLM Tool Calls and Tool Results

KePrompt supports two *statement* types that let you represent **tool calls produced by the LLM API** and the corresponding **tool responses**.

These are most useful for:
- Replaying/debugging conversations
- Creating test fixtures / example chats
- Manually reconstructing a conversation that includes tool use

They are distinct from `.cmd`, which **executes** a local function during prompt execution.

#### `.tool_call` (LLM → tool)

**Syntax**
```text
.tool_call function_name(param=value, ...) id=call_id
```

**Example**
```text
.tool_call readfile(filename="data.txt") id=call_001
```

#### `.tool_result` (tool → LLM)

**Syntax**
```text
.tool_result id=call_id name=function_name
<result text can be multi-line>
```

**Example**
```text
.tool_result id=call_001 name=readfile
File contents:
Hello from data.txt
```

#### End-to-end example (manual reconstruction)
```text
.prompt "name":"Toolcall Example", "version":"1.0.0", "params":{"model":"gpt-4o-mini"}
.user Please read data.txt and summarize it.

# These two statements represent what the *LLM API* would have produced,
# and the corresponding tool response KePrompt would send back:
.tool_call readfile(filename="data.txt") id=call_001
.tool_result id=call_001 name=readfile
Hello from data.txt

.assistant Summary: The file contains a short greeting.
```

### Prompt Metadata (Required)

**Every prompt file must start with a `.prompt` statement** that defines metadata:

```bash
.prompt "name":"My Prompt Name", "version":"1.0.0", "params":{"model":"gpt-4o-mini"}
```

**Required fields:**
- `name`: Human-readable prompt name (used in cost tracking)
- `version`: Semantic version for tracking changes

**Optional fields:**
- `params`: Default parameters and documentation

**Examples:**
```bash
# Simple prompt
.prompt "name":"Hello World", "version":"1.0.0"

# With parameters
.prompt "name":"Code Reviewer", "version":"2.1.0", "params":{"model":"gpt-4o", "language":"python"}

# Research assistant
.prompt "name":"Research Assistant", "version":"1.5.0", "params":{"model":"claude-3-5-sonnet-20241022", "depth":"comprehensive"}
```

### Variables
Use `<<variable>>` syntax for substitution:
```bash
# In your prompt file
.user Hello <<name>>, today is <<date>>

# Run with parameters
keprompt chats create --prompt greeting --set name "Alice" --set date "Monday"
```

### Built-in Functions
- `readfile(filename)` - Read file contents
- `writefile(filename, content)` - Write to file (with backup)
- `wwwget(url)` - Fetch web content
- `execcmd(cmd)` - Execute shell command

## Common Workflows

### Research Assistant
```bash
cat > prompts/research.prompt << 'EOF'
.prompt "name":"Research Assistant", "version":"1.0.0", "params":{"model":"claude-3-5-sonnet-20241022", "topic":"research_topic"}
.llm {"model": "claude-3-5-sonnet-20241022"}
.system You are a research assistant. Provide thorough, well-sourced information.
.user Research this topic: <<topic>>
.cmd wwwget(url="https://en.wikipedia.org/wiki/<<topic>>")
Based on this information, provide a comprehensive overview with key facts and recent developments.
.exec
EOF

keprompt chats create --prompt research --set topic "Artificial_Intelligence"
```

### Code Review
```bash
cat > prompts/review.prompt << 'EOF'
.prompt "name":"Code Reviewer", "version":"1.0.0", "params":{"model":"gpt-4o", "codefile":"path/to/file"}
.llm {"model": "gpt-4o"}
.system You are a senior software engineer. Provide constructive code reviews.
.user Please review this code file:

.include <<codefile>>

Focus on: code quality, potential bugs, performance, and best practices.
.exec
EOF

keprompt chats create --prompt review --set codefile "src/main.py"
```

### Interactive Chat Session
```bash
# Start a conversation
CHAT_ID=$(keprompt chats create --prompt hello --json | jq -r '.data.chat_id')

# Continue the conversation
keprompt chats reply $CHAT_ID "Can you explain that in more detail?"
keprompt chats reply $CHAT_ID "What about edge cases?"

# View full conversation
keprompt chats get $CHAT_ID
```

## Working with Models

### List available models
```bash
# See all models
keprompt models get

# Filter by provider
keprompt models get --company OpenAI
keprompt models get --company Anthropic

# Search by name
keprompt models get --name "gpt-4*"
keprompt models get --name "*sonnet*"
```

### Compare costs
```bash
# Show pricing for all GPT models
keprompt models get --name "gpt*" --company OpenAI
```

### Update model registry
```bash
# Fetch latest models from providers
keprompt models update
```

## Cost Tracking & Analysis

KePrompt automatically tracks all API usage with comprehensive cost analysis.

### View Conversation Costs
```bash
# List recent conversations with costs
keprompt chats get --limit 20

# View specific chat details
keprompt chats get <chat-id>

# Get cost summary
sqlite3 prompts/chats.db "SELECT SUM(total_cost) FROM chats"
```

### Database Management
```bash
# View database info
keprompt database get

# Clean up old conversations
keprompt chats delete --days 30

# Keep only recent conversations
keprompt chats delete --count 100
```

## Custom Functions

KePrompt supports custom functions written in any language. See the detailed guide at [ks/creating-keprompt-functions.context.md](ks/creating-keprompt-functions.context.md)

### Quick Example

Create an executable in `prompts/functions/`:

```python
#!/usr/bin/env python3
import json, sys

def get_weather(city: str) -> str:
    # Your weather API logic here
    return f"Weather in {city}: Sunny, 72°F"

FUNCTIONS = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"}
            },
            "required": ["city"],
            "additionalProperties": False
        }
    }
]

if __name__ == "__main__":
    if sys.argv[1] == "--list-functions":
        print(json.dumps(FUNCTIONS))
    elif sys.argv[1] == "get_weather":
        args = json.loads(sys.stdin.read())
        print(get_weather(**args))
```

Make it executable:
```bash
chmod +x prompts/functions/weather
```

Use in prompts:
```bash
cat > prompts/weather_check.prompt << 'EOF'
.prompt "name":"Weather Check", "version":"1.0.0", "params":{"city":"default_city"}
.llm {"model": "gpt-4o-mini"}
.user What's the weather like in <<city>>? Based on the weather, suggest appropriate clothing.
.exec
EOF

keprompt chats create --prompt weather_check --set city "San Francisco"
```

For comprehensive documentation on creating custom functions, see [ks/creating-keprompt-functions.context.md](ks/creating-keprompt-functions.context.md)

## Conversation Management

### Create and Continue Conversations
```bash
# Start a new conversation
keprompt chats create --prompt hello

# Continue with a chat ID
keprompt chats reply a1b2c3d4 "Tell me more about that"

# Show full conversation history
keprompt chats reply a1b2c3d4 --full "Thanks for the explanation"
```

### List and View Conversations
```bash
# List all conversations
keprompt chats get

# View specific conversation
keprompt chats get a1b2c3d4

# List with filters
keprompt chats get --limit 10
```

### View Conversation Formats

KePrompt offers multiple viewing formats to help you understand and debug your conversations:

```bash
# View conversation messages (default)
keprompt chats get a1b2c3d4 --format=messages

# View prompt source code (statements)
keprompt chats get a1b2c3d4 --format=statements

# View cost summary and metadata
keprompt chats get a1b2c3d4 --format=summary

# View raw JSON data
keprompt chats get a1b2c3d4 --format=raw
```

**Format Aliases** (shortcuts for convenience):
- `--format=msg` / `msgs` / `message` → messages view
- `--format=stmt` / `stmts` / `statement` → statements view  
- `--format=sum` → summary view
- `--format=json` → raw JSON view

**Format Descriptions:**

| Format | Purpose | Shows |
|--------|---------|-------|
| `messages` | View the conversation | User/assistant dialogue with model info |
| `statements` | View source code | Prompt statements (`.user`, `.exec`, `.set`, etc.) |
| `summary` | View metrics | Costs, tokens, API calls, timing |
| `raw` | View complete data | Full JSON with all metadata |

**Examples:**
```bash
# Debug which statements were executed
keprompt chats get a1b2c3d4 --format=stmt --pretty

# Quick cost check
keprompt chats get a1b2c3d4 --format=sum --pretty

# Export conversation for analysis
keprompt chats get a1b2c3d4 --format=json > conversation.json
```

### Clean Up
```bash
# Delete specific conversation
keprompt chats delete a1b2c3d4

# Delete old conversations
keprompt chats delete --days 30

# Keep only recent conversations
keprompt chats delete --count 100
```

## Server Management

### Start Server
```bash
# Start with web GUI
keprompt server start --web-gui

# Specify port
keprompt server start --web-gui --port 8080

# Development mode with auto-reload
keprompt server start --web-gui --reload

# Start in specific directory
keprompt server start --web-gui --directory /path/to/project
```

### Manage Servers
```bash
# List running servers
keprompt server list --active-only

# Check status
keprompt server status

# Stop server
keprompt server stop

# Stop all servers
keprompt server stop --all
```

## Output Formats

### Human-Readable (Default in Terminal)
Rich formatted tables with colors and alignment.

### Machine-Readable (JSON)
```bash
# Get JSON output
keprompt chats get --json

# Use with jq
keprompt chats get --json | jq '.data[] | select(.total_cost > 0.01)'

# Get chat ID programmatically
CHAT_ID=$(keprompt chats create --prompt hello --json | jq -r '.data.chat_id')

# Extract a value from the JSON output (example: last_response)
# (Requires jq: https://stedolan.github.io/jq/)
keprompt chat new --prompt Test --json | jq -r '.meta.variables.last_response'

# If you don't have jq, you can do the same with python3:
keprompt chat new --prompt Test --json | \
  python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["meta"]["variables"]["last_response"])'
```

## Tips & Best Practices

### 1. Start Simple
Begin with basic prompts and gradually add complexity.

### 2. Use the Web GUI for Development
The web interface provides a better development experience with real-time feedback.

```bash
keprompt server start --web-gui --reload
```

### 3. Manage Costs
- Use cheaper models for development (`gpt-4o-mini`, `claude-3-haiku`)
- Monitor costs with `keprompt chats get`
- Check model pricing with `keprompt models get`

### 4. Organize Your Prompts
```
prompts/
├── research/
│   ├── academic.prompt
│   └── market.prompt
├── coding/
│   ├── review.prompt
│   └── debug.prompt
└── content/
    ├── blog.prompt
    └── social.prompt
```

### 5. Version Control
Keep your prompts in git to track what works best.

### 6. Test Across Models
The same prompt may work differently with different models. Test and compare.

## Troubleshooting

### Common Issues

**"No models found"**
```bash
keprompt models update
```

**"API key not found"**
```bash
# Add to .env file
echo 'OPENAI_API_KEY=sk-...' >> .env
# Or export directly
export OPENAI_API_KEY="sk-..."
```

**"Prompt not found"**
```bash
# List available prompts
keprompt prompts get
# Check prompts directory exists
ls prompts/
```

**"Server already running"**
```bash
# Check status
keprompt server status
# Stop existing server
keprompt server stop
```

### Getting Help

```bash
# Show all options
keprompt --help

# Get help for specific object
keprompt chats --help
keprompt server --help
```

## Documentation

- [Prompt Language](ks/01-prompt-language.md) - Writing .prompt files
- [Knowledge Engineer's Guide](ks/02-knowledge-engineers-guide.md) - Comprehensive guide
- [Statements & Messages](ks/03-statements-and-messages.md) - Architecture reference
- [Creating Functions](ks/creating-keprompt-functions.context.md) - Custom function development

## What's Next?

- **Explore the examples** in the `prompts/` directory
- **Try the web GUI** for interactive development
- **Create custom functions** for your specific needs
- **Integrate with your workflow** using the JSON API

## Contributing

KePrompt is open source! Contributions welcome at [GitHub](https://github.com/JerryWestrick/keprompt).

## License

[MIT](LICENSE)

---

*KePrompt: Making AI interaction simple, powerful, and cost-effective.*


