6 Commits
main ... 2.1

Author SHA1 Message Date
8c49339452 Minor bug fixes 2026-01-08 15:00:59 +01:00
8a113a9bbe Fixed some regex for files 2026-01-08 13:12:17 +01:00
c305d5cf49 More bugfixes 2026-01-07 11:09:13 +01:00
2c9f33868e More bugfixes 2026-01-07 09:58:58 +01:00
d4f1a1c6a4 Fixed bug in ctrl+c handling during response streaming 2026-01-07 08:01:33 +01:00
2e7c49bf68 Major update 2026-01-06 13:52:44 +01:00
4 changed files with 3674 additions and 472 deletions

11
.gitignore vendored
View File

@@ -22,8 +22,9 @@ Pipfile.lock # Consider if you want to include or exclude
._*
*~.nib
*~.xib
README.md.old
oai.zip
# Added by author
*.zip
.note
diagnose.py
*.log
@@ -33,4 +34,8 @@ build*
compiled/
images/oai-iOS-Default-1024x1024@1x.png
images/oai.icon/
b0.sh
b0.sh
*.bak
*.old
*.sh
*.back

526
README.md
View File

@@ -1,53 +1,77 @@
# oAI - OpenRouter AI Chat
A terminal-based chat interface for OpenRouter API with conversation management, cost tracking, and rich formatting.
A powerful terminal-based chat interface for OpenRouter API with **MCP (Model Context Protocol)** support, enabling AI agents to access local files and query SQLite databases directly.
## 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.
oAI is a feature-rich command-line chat application that provides an interactive interface to OpenRouter's AI models. It now includes **MCP integration** for local file system access and read-only database querying, allowing AI to help with code analysis, data exploration, and more.
## 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
### Core Features
- 🤖 Interactive chat with 300+ AI models via OpenRouter
- 🔍 Model selection with search and capability filtering
- 💾 Conversation save/load/export (Markdown, JSON, HTML)
- 📎 File attachment support (images, PDFs, code files)
- 💰 Session cost tracking and credit monitoring
- 🎨 Rich terminal formatting with syntax highlighting
- 📝 Persistent command history with search (Ctrl+R)
- ⚙️ Configurable system prompts and token limits
- 🗄️ SQLite-based configuration and conversation storage
- 🌐 Online mode (web search capabilities)
- 🧠 Conversation memory toggle (save costs with stateless mode)
### NEW: MCP (Model Context Protocol) v2.1.0-beta
- 🔧 **File Mode**: AI can read, search, and list your local files
- Automatic .gitignore filtering
- Virtual environment exclusion (venv, node_modules, etc.)
- Supports code files, text, JSON, YAML, and more
- Large file handling (auto-truncates >50KB)
- 🗄️ **Database Mode**: AI can query your SQLite databases
- Read-only access (no data modification possible)
- Schema inspection (tables, columns, indexes)
- Full-text search across all tables
- SQL query execution (SELECT, JOINs, CTEs, subqueries)
- Query validation and timeout protection
- Result limiting (max 1000 rows)
- 🔒 **Security Features**:
- Explicit folder/database approval required
- System directory blocking
- Read-only database access
- SQL injection protection
- Query timeout (5 seconds)
## Requirements
- Python 3.7 or higher
- Python 3.10-3.13 (3.14 not supported yet)
- OpenRouter API key (get one at https://openrouter.ai)
- Function-calling model required for MCP features (GPT-4, Claude, etc.)
## Screenshot (<span style="font-size:0.8em;">from version 1.0</span>)
## 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.
*Screenshot from version 1.0 - MCP interface shows mode indicators like `[🔧 MCP: Files]` or `[🗄️ MCP: DB #1]`*
## Installation
### 1. Install Dependencies
### Option 1: From Source (Recommended for Development)
Use the included `requirements.txt` file to install the dependencies:
#### 1. Install Dependencies
```bash
pip install -r requirements.txt
```
### 2. Make the Script Executable
#### 2. Make Executable
```bash
chmod +x oai.py
```
### 3. Copy to PATH
Copy the script to a directory in your `$PATH` environment variable. Common locations include:
#### 3. Copy to PATH
```bash
# Option 1: System-wide (requires sudo)
@@ -57,145 +81,394 @@ sudo cp oai.py /usr/local/bin/oai
mkdir -p ~/.local/bin
cp oai.py ~/.local/bin/oai
# Add to PATH if not already (add to ~/.bashrc or ~/.zshrc)
# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
```
### 4. Verify Installation
#### 4. Verify Installation
```bash
oai --version
```
### Option 2: Pre-built Binaries
Download platform-specific binaries:
- **macOS (Apple Silicon)**: `oai_vx.x.x_mac_arm64.zip`
- **Linux (x86_64)**: `oai_vx.x.x-linux-x86_64.zip`
```bash
# Extract and install
unzip oai_vx.x.x_mac_arm64.zip # or `oai_vx.x.x-linux-x86_64.zip`
chmod +x oai
mkdir -p ~/.local/bin # Remember to add this to your path. Or just move to folder already in your $PATH
mv oai ~/.local/bin/
```
### Alternative: Shell Alias
```bash
# Add to ~/.bashrc or ~/.zshrc
alias oai='python3 /path/to/oai.py'
```
## Quick Start
### First Run Setup
```bash
oai
```
### 5. Alternative Installation (for *nix systems)
On first run, you'll be prompted to enter your OpenRouter API key.
If you have issues with the above method you can add an alias in your `.bashrc`, `.zshrc` etc.
```bash
alias oai='python3 <path to your file>'
```
On first run, you will be prompted to enter your OpenRouter API key.
### 6. Use Binaries
You can also just download the supplied binary for either Mac wit Mx (M1, M2 etc) `oai_mac_arm64.zip` and follow [#3](https://gitlab.pm/rune/oai#3-copy-to-path). Or download for Linux (64bit) `oai_linux_x86_64.zip` and also follow [#3](https://gitlab.pm/rune/oai#3-copy-to-path).
## Usage
### Starting the Application
### Basic Usage
```bash
# Start chatting
oai
# Select a model
You> /model
# Enable MCP for file access
You> /mcp enable
You> /mcp add ~/Documents
# Ask AI to help with files
[🔧 MCP: Files] You> List all Python files in Documents
[🔧 MCP: Files] You> Read and explain main.py
# Switch to database mode
You> /mcp add db ~/myapp/data.db
You> /mcp db 1
[🗄️ MCP: DB #1] You> Show me all tables
[🗄️ MCP: DB #1] You> Find all users created this month
```
### Basic Commands
## MCP Guide
```
/help Show all available commands
/model Select an AI model
/config api Set OpenRouter API key
exit Quit the application
### File Mode (Default)
**Setup:**
```bash
/mcp enable # Start MCP server
/mcp add ~/Projects # Grant access to folder
/mcp add ~/Documents # Add another folder
/mcp list # View all allowed folders
```
### 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:**
**Natural Language Usage:**
```
/model
"List all Python files in Projects"
"Read and explain config.yaml"
"Search for files containing 'TODO'"
"What's in my Documents folder?"
```
**Paste from clipboard:**
Paste and send content to model
```
/paste
**Available Tools:**
- `read_file` - Read complete file contents
- `list_directory` - List files/folders (recursive optional)
- `search_files` - Search by name or content
**Features:**
- ✅ Automatic .gitignore filtering
- ✅ Skips virtual environments (venv, node_modules)
- ✅ Handles large files (auto-truncates >50KB)
- ✅ Cross-platform (macOS, Linux, Windows via WSL)
### Database Mode
**Setup:**
```bash
/mcp add db ~/app/database.db # Add SQLite database
/mcp db list # View all databases
/mcp db 1 # Switch to database #1
```
Paste with prompt and send content to model
**Natural Language Usage:**
```
/paste Analyze this text
"Show me all tables in this database"
"Find records mentioning 'error'"
"How many users registered last week?"
"Get the schema for the orders table"
"Show me the 10 most recent transactions"
```
**Start Chatting:**
```
You> Hello, how are you?
```
**Available Tools:**
- `inspect_database` - View schema, tables, columns, indexes
- `search_database` - Full-text search across tables
- `query_database` - Execute read-only SQL queries
**Attach Files:**
```
You> Debug this code @/path/to/script.py
You> Analyze this image @/path/to/image.png
```
**Supported Queries:**
- ✅ SELECT statements
- ✅ JOINs (INNER, LEFT, RIGHT, FULL)
- ✅ Subqueries
- ✅ CTEs (Common Table Expressions)
- ✅ Aggregations (COUNT, SUM, AVG, etc.)
- ✅ WHERE, GROUP BY, HAVING, ORDER BY, LIMIT
- ❌ INSERT/UPDATE/DELETE (blocked for safety)
**Save Conversation:**
```
/save my_conversation
```
### Mode Management
**Export to File:**
```bash
/mcp status # Show current mode, stats, folders/databases
/mcp files # Switch to file mode
/mcp db <number> # Switch to database mode
/mcp gitignore on # Enable .gitignore filtering (default)
/mcp remove 2 # Remove folder/database by number
```
/export md notes.md
/export json backup.json
/export html report.html
```
**View Session Stats:**
```
/stats
/credits
```
**Prevous commands input:**
Use the up/down arrows to see earlier `/`commands and earlier input to model and `<enter>` to execute the same command or resend the same input.
## 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
### Session Commands
```
/help [command] Show help menu or detailed command help
/help mcp Comprehensive MCP guide
/clear or /cl Clear terminal screen (or Ctrl+L)
/memory on|off Toggle conversation memory (save costs)
/online on|off Enable/disable web search
/paste [prompt] Paste clipboard content
/retry Resend last prompt
/reset Clear history and system prompt
/prev View previous response
/next View next response
```
### MCP Commands
```
/mcp enable Start MCP server
/mcp disable Stop MCP server
/mcp status Show comprehensive status
/mcp add <folder> Add folder for file access
/mcp add db <path> Add SQLite database
/mcp list List all folders
/mcp db list List all databases
/mcp db <number> Switch to database mode
/mcp files Switch to file mode
/mcp remove <num> Remove folder/database
/mcp gitignore on Enable .gitignore filtering
```
### Model Commands
```
/model [search] Select/change AI model
/info [model_id] Show model details (pricing, capabilities)
```
### Configuration
```
/config View all settings
/config api Set API key
/config model Set default model
/config online Set default online mode (on|off)
/config stream Enable/disable streaming (on|off)
/config maxtoken Set max token limit
/config costwarning Set cost warning threshold ($)
/config loglevel Set log level (debug/info/warning/error)
/config log Set log file size (MB)
```
### Conversation Management
```
/save <name> Save conversation
/load <name|num> Load saved conversation
/delete <name|num> Delete conversation
/list List saved conversations
/export md|json|html <file> Export conversation
```
### Token & System
```
/maxtoken [value] Set session token limit
/system [prompt] Set system prompt (use 'clear' to reset)
/middleout on|off Enable prompt compression
```
### Monitoring
```
/stats View session statistics
/credits Check OpenRouter credits
```
### File Attachments
```
@/path/to/file Attach file (images, PDFs, code)
Examples:
Debug @script.py
Analyze @data.json
Review @screenshot.png
```
## 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>`
All configuration stored in `~/.config/oai/`:
## File Support
### Files
- `oai_config.db` - SQLite database (settings, conversations, MCP config)
- `oai.log` - Application logs (rotating, configurable size)
- `history.txt` - Command history (searchable with Ctrl+R)
**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
### Key Settings
- **API Key**: OpenRouter authentication
- **Default Model**: Auto-select on startup
- **Streaming**: Real-time response display
- **Max Tokens**: Global and session limits
- **Cost Warning**: Alert threshold for expensive requests
- **Online Mode**: Default web search setting
- **Log Level**: debug/info/warning/error/critical
- **Log Size**: Rotating file size in MB
**Image Support:**
Any image format with proper MIME type (PNG, JPEG, GIF, etc.)
## Supported File Types
## Data Storage
### Code Files
`.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`
- Configuration: `~/.config/oai/oai_config.db`
- Logs: `~/.config/oai/oai.log`
- History: `~/.config/oai/history.txt`
### Data Files
`.json, .yaml, .yml, .xml, .csv, .txt, .md`
### Images
All standard formats: PNG, JPEG, JPG, GIF, WEBP, BMP
### Documents
PDF (models with document support)
### Size Limits
- Images: 10 MB max
- Code/Text: Auto-truncates files >50KB
- Binary data: Displayed as `<binary: X bytes>`
## MCP Security
### Access Control
- ✅ Explicit folder/database approval required
- ✅ System directories blocked automatically
- ✅ User confirmation for each addition
- ✅ .gitignore patterns respected (file mode)
### Database Safety
- ✅ Read-only mode (cannot modify data)
- ✅ SQL query validation (blocks INSERT/UPDATE/DELETE)
- ✅ Query timeout (5 seconds max)
- ✅ Result limits (1000 rows max)
- ✅ Database opened in `mode=ro`
### File System Safety
- ✅ Read-only access (no write/delete)
- ✅ Virtual environment exclusion
- ✅ Build artifact filtering
- ✅ Maximum file size (10 MB)
## Tips & Tricks
### Command History
- **↑/↓ arrows**: Navigate previous commands
- **Ctrl+R**: Search command history
- **Auto-complete**: Start typing `/` for command suggestions
### Cost Optimization
```bash
/memory off # Disable context (stateless mode)
/maxtoken 1000 # Limit response length
/config costwarning 0.01 # Set alert threshold
```
### MCP Best Practices
```bash
# Check status frequently
/mcp status
# Use specific paths to reduce search time
"List Python files in Projects/app/" # Better than
"List all Python files" # Slower
# Database queries - be specific
"SELECT * FROM users LIMIT 10" # Good
"SELECT * FROM users" # May hit row limit
```
### Debugging
```bash
# Enable debug logging
/config loglevel debug
# Check log file
tail -f ~/.config/oai/oai.log
# View MCP statistics
/mcp status # Shows tool call counts
```
## Troubleshooting
### MCP Not Working
```bash
# 1. Check if MCP is installed
python3 -c "import mcp; print('MCP OK')"
# 2. Verify model supports function calling
/info # Look for "tools" in supported parameters
# 3. Check MCP status
/mcp status
# 4. Review logs
tail ~/.config/oai/oai.log
```
### Import Errors
```bash
# Reinstall dependencies
pip install --force-reinstall -r requirements.txt
```
### Binary Issues (macOS)
```bash
# Remove quarantine
xattr -cr ~/.local/bin/oai
# Check security settings
# System Settings > Privacy & Security > "Allow Anyway"
```
### Database Errors
```bash
# Verify it's a valid SQLite database
sqlite3 database.db ".tables"
# Check file permissions
ls -la database.db
```
## Version History
### v2.1.0-beta (Current)
-**NEW**: MCP (Model Context Protocol) integration
-**NEW**: File system access (read, search, list)
-**NEW**: SQLite database querying (read-only)
-**NEW**: Dual mode support (Files & Database)
-**NEW**: .gitignore filtering
-**NEW**: Binary data handling in databases
-**NEW**: Mode indicators in prompt
-**NEW**: Comprehensive `/help mcp` guide
- 🔧 Improved error handling for tool calls
- 🔧 Enhanced logging for MCP operations
- 🔧 Statistics tracking for tool usage
### v1.9.6
- Base version with core chat functionality
- Conversation management
- File attachments
- Cost tracking
- Export capabilities
## License
MIT License
Copyright (c) 2024 Rune Olsen
Copyright (c) 2024-2025 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
@@ -221,12 +494,27 @@ Full license: https://opensource.org/licenses/MIT
**Rune Olsen**
Blog: https://blog.rune.pm
- Homepage: https://ai.fubar.pm/
- Blog: https://blog.rune.pm
- Project: https://iurl.no/oai
## Version
## Contributing
1.0
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request with detailed description
## Support
## Acknowledgments
For issues, questions, or contributions, visit https://iurl.no/oai and create an issue.
- OpenRouter team for the unified AI API
- Rich library for beautiful terminal output
- MCP community for the protocol specification
---
**Star ⭐ this project if you find it useful!**
---
Did you really read all the way down here? WOW! You deserve a 🍾 🥂!

3545
oai.py

File diff suppressed because it is too large Load Diff

View File

@@ -1,38 +1,26 @@
anyio==4.11.0
beautifulsoup4==4.14.2
charset-normalizer==3.4.4
click==8.3.1
docopt==0.6.2
h11==0.16.0
httpcore==1.0.9
httpx==0.28.1
idna==3.11
latex2mathml==3.78.1
loguru==0.7.3
markdown-it-py==4.0.0
markdown2==2.5.4
mdurl==0.1.2
natsort==8.4.0
openrouter==0.0.19
packaging==25.0
pipreqs==0.4.13
prompt-toolkit==3.0.52
Pygments==2.19.2
pyperclip==1.11.0
python-dateutil==2.9.0.post0
python-magic==0.4.27
PyYAML==6.0.3
requests==2.32.5
rich==14.2.0
shellingham==1.5.4
six==1.17.0
sniffio==1.3.1
soupsieve==2.8
svgwrite==1.4.3
tqdm==4.67.1
typer==0.20.0
typing-extensions==4.15.0
urllib3==2.5.0
wavedrom==2.0.3.post3
wcwidth==0.2.14
yarg==0.1.10
# oai.py v2.1.0-beta - Core Dependencies
anyio>=4.11.0
charset-normalizer>=3.4.4
click>=8.3.1
h11>=0.16.0
httpcore>=1.0.9
httpx>=0.28.1
idna>=3.11
markdown-it-py>=4.0.0
mdurl>=0.1.2
openrouter>=0.0.19
packaging>=25.0
prompt-toolkit>=3.0.52
Pygments>=2.19.2
pyperclip>=1.11.0
requests>=2.32.5
rich>=14.2.0
shellingham>=1.5.4
sniffio>=1.3.1
typer>=0.20.0
typing-extensions>=4.15.0
urllib3>=2.5.0
wcwidth>=0.2.14
# MCP (Model Context Protocol)
mcp>=1.25.0