204 lines
4.8 KiB
Markdown
204 lines
4.8 KiB
Markdown
# 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 |