# oAI - OpenRouter AI Chat

A terminal-based chat interface for OpenRouter API with conversation management, cost tracking, and rich formatting.

## Description

oAI is a command-line chat application that provides an interactive interface to OpenRouter's AI models. It features conversation persistence, file attachments, export capabilities, and detailed session metrics.

## Features

- Interactive chat with multiple AI models via OpenRouter
- Model selection with search functionality
- Conversation save/load/export (Markdown, JSON, HTML)
- File attachment support (code files and images)
- Session cost tracking and credit monitoring
- Rich terminal formatting with syntax highlighting
- Persistent command history
- Configurable system prompts and token limits
- SQLite-based configuration and conversation storage

## Requirements

- Python 3.7 or higher
- OpenRouter API key (get one at https://openrouter.ai)

## Screenshot

[<img src="https://gitlab.pm/rune/oai/raw/branch/main/images/screenshot_01.png">](https://gitlab.pm/rune/oai/src/branch/main/README.md)  

Screenshot of `/help` screen.

## Installation

### 1. Install Dependencies

Use the included `requirements.txt` file to install the dependencies:

```bash
pip install -r requirements.txt
```

### 2. Make the Script Executable

```bash
chmod +x oai.py
```

### 3. Copy to PATH

Copy the script to a directory in your `$PATH` environment variable. Common locations include:

```bash
# Option 1: System-wide (requires sudo)
sudo cp oai.py /usr/local/bin/oai

# Option 2: User-local (recommended)
mkdir -p ~/.local/bin
cp oai.py ~/.local/bin/oai

# Add to PATH if not already (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
```

### 4. Verify Installation

```bash
oai
```

On first run, you will be prompted to enter your OpenRouter API key.

## Usage

### Starting the Application

```bash
oai
```

### Basic Commands

```
/help                     Show all available commands
/model                    Select an AI model
/config api               Set OpenRouter API key
exit                      Quit the application
```

### Configuration

All configuration is stored in `~/.config/oai/`:
- `oai_config.db` - SQLite database for settings and conversations
- `oai.log` - Application log file
- `history.txt` - Command history

### Common Workflows

**Select a Model:**
```
/model
```

**Start Chatting:**
```
You> Hello, how are you?
```

**Attach Files:**
```
You> Debug this code @/path/to/script.py
You> Analyze this image @/path/to/image.png
```

**Save Conversation:**
```
/save my_conversation
```

**Export to File:**
```
/export md notes.md
/export json backup.json
/export html report.html
```

**View Session Stats:**
```
/stats
/credits
```

## Command Reference

Use `/help` within the application for a complete command reference organized by category:
- Session Commands
- Model Commands
- Configuration
- Token & System
- Conversation Management
- Monitoring & Stats
- File Attachments

## Configuration Options

- API Key: `/config api`
- Base URL: `/config url`
- Streaming: `/config stream on|off`
- Default Model: `/config model`
- Cost Warning: `/config costwarning <amount>`
- Max Token Limit: `/config maxtoken <value>`

## File Support

**Supported Code Extensions:**
.py, .js, .ts, .cs, .java, .c, .cpp, .h, .hpp, .rb, .ruby, .php, .swift, .kt, .kts, .go, .sh, .bat, .ps1, .R, .scala, .pl, .lua, .dart, .elm, .xml, .json, .yaml, .yml, .md, .txt

**Image Support:**
Any image format with proper MIME type (PNG, JPEG, GIF, etc.)

## Data Storage

- Configuration: `~/.config/oai/oai_config.db`
- Logs: `~/.config/oai/oai.log`
- History: `~/.config/oai/history.txt`

## License

MIT License

Copyright (c) 2024 Rune Olsen

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Full license: https://opensource.org/licenses/MIT

## Author

**Rune Olsen**

Blog: https://blog.rune.pm

## Version

1.0

## Support

For issues, questions, or contributions, visit https://iurl.no/oai