Initial commit
This commit is contained in:
165
README.md
Normal file
165
README.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# OAI Chat App
|
||||
|
||||
A command-line interface (CLI) chat application for interacting with AI language models via OpenRouter. Seamlessly switch between 300+ models, attach files (images and text), enjoy real-time streaming responses, and manage settings persistently—all from your terminal. Perfect for developers, writers, and AI enthusiasts looking for a fast, feature-rich chat experience without leaving the command line.
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **Model Flexibility**: Choose from hundreds of OpenRouter-supported models (e.g., GPT-4, Claude, Gemini) with substring-based search and selection [github.com](https://github.com/owengretzinger/gitreadme) for template-inspired ease.
|
||||
- **File Attachments**: Attach images (JPEG, PNG) or plain text files directly to messages using `@path` syntax, with automatic Base64 encoding for models that support modalities.
|
||||
- **Streaming Responses**: Enable real-time streaming for faster, live responses; toggle on/off via config commands (inspired by streaming in modern chat apps).
|
||||
- **Persistent Configuration**: Securely store API keys, base URLs, and settings in a local SQLite database for reuse across sessions.
|
||||
- **Rich UI in CLI**: Enhanced console output with Rich library panels, tables, and progress indicators for a polished terminal experience.
|
||||
- **Clipboard Integration**: Copy AI responses to the clipboard with a single prompt.
|
||||
- **Help Command**: Built-in `/help` with examples for all commands, making the app self-documenting and user-friendly [github.com](https://github.com/Piyush64-bit/ReadMe-Generator).
|
||||
- **Error Handling**: Graceful prompts for missing configs, file issues, and model incompatibilities.
|
||||
- **Cross-Platform**: Works on any OS with Python and internet access, no heavy dependencies required.
|
||||
|
||||
## 🖼️ Screenshots
|
||||
|
||||
|
||||
*(Replace with actual screenshot of the CLI interface, e.g., showing model selection or a chat response.)*
|
||||
|
||||
## 📋 Requirements
|
||||
|
||||
- **Python**: 3.9 or higher
|
||||
- **OpenRouter API Key**: Free tier available at [openrouter.ai](https://openrouter.ai). Models like GPT-4 may require a paid plan.
|
||||
- **Dependencies**: Listed in `requirements.txt` (generate automatically with tools like `pipreqs` if needed).
|
||||
- **Internet Connection**: For API calls to OpenRouter.
|
||||
|
||||
## 🚀 Installation
|
||||
|
||||
1. **Clone the Repository**:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/oai-chat-app.git # Replace with your actual repo URL
|
||||
cd oai-chat-app
|
||||
```
|
||||
|
||||
2. **Install Dependencies**:
|
||||
Use `pip` for simplicity or `uv` for faster management:
|
||||
```bash
|
||||
# Using pip
|
||||
pip install typer rich openrouter pyperclip requests
|
||||
|
||||
# Using uv
|
||||
uv add typer rich openrouter pyperclip requests
|
||||
|
||||
# Using pip and requirements.txt (recommended)
|
||||
pip3 install -r requirements.txt
|
||||
```
|
||||
|
||||
3. **Set Up Configuration**:
|
||||
- The app creates a SQLite database at `~/.config/oai/oai_config.db` on first run.
|
||||
- Run the app once to set your API key: `python oai_chat.py chat`.
|
||||
- For API key issues, visit [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys).
|
||||
|
||||
4. **Make Executable (Optional)**:
|
||||
```bash
|
||||
chmod +x oai_chat.py # For Unix-based systems
|
||||
```
|
||||
|
||||
Your app is now ready! Run `python oai_chat.py chat` to start chatting [github.com](https://github.com/waheed444/AI_Readme_Generator) inspired by simple setup in AI tools.
|
||||
|
||||
## 💻 Usage
|
||||
|
||||
Launch the app and interact via commands or direct chat:
|
||||
|
||||
```bash
|
||||
python oai_chat.py chat
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description | Example |
|
||||
|---------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------|
|
||||
| `/help` | Display a table with examples for all commands and features. | `/help` |
|
||||
| `/model [search]` | Select or switch models; optional search for substring matching. | `/model gpt` (Filters to GPT models)<br>`/model` (Shows all models) |
|
||||
| `/config api` | Update OpenRouter API key and reinitialize the client. | `/config api`<br>Enter key: sk-...<br>[Output: API key updated!] |
|
||||
| `/config url` | Change the base URL for custom OpenRouter endpoints. | `/config url`<br>Enter URL: https://custom.openrouter.ai/api/v1 |
|
||||
| `/config stream on/off` | Toggle response streaming (default: on for real-time chat). | `/config stream off` (For full responses at once)<br>`/config stream on`|
|
||||
| `/config` | View current configurations. | `/config` (Displays table: API Key, Base URL, Streaming, Database path)|
|
||||
| `exit`, `quit`, `bye` | Exit the app cleanly. | `exit` |
|
||||
| Chatting with Files | Attach files using `@path` (e.g., images for vision models, text for context). | `Explain this @~/demo.png`<br>(Attaches image if model supports it) |
|
||||
|
||||
### Example Session
|
||||
|
||||
```
|
||||
Welcome to OAI! Type your message, '/model [search]' to select/change model, '/config api/url/stream' to configure, '/help' for examples, or 'exit'/'quit' to end.
|
||||
No model selected. Use '/model' to choose one.
|
||||
|
||||
You: /help
|
||||
[Displays help table as above]
|
||||
|
||||
You: /model gpt
|
||||
(Shows table of GPT models)
|
||||
Enter model number: 1
|
||||
Selected: GPT-4o (openai/gpt-4o)
|
||||
|
||||
You: Hello, how are you?
|
||||
Streaming response... (Press Ctrl+C to cancel)
|
||||
Hello! I'm doing great, thanks for asking. How can I help you today?
|
||||
|
||||
Type 'c' to copy response to clipboard, or press Enter to continue: c
|
||||
Response copied to clipboard!
|
||||
|
||||
You: Analyze this text @~/notes.txt
|
||||
Streaming response... (Press Ctrl+C to cancel)
|
||||
Based on the attached file, the text discusses...
|
||||
|
||||
You: exit
|
||||
Goodbye!
|
||||
```
|
||||
|
||||
- **Streaming**: Enabled by default for live responses; press Ctrl+C mid-stream to cancel (supported by most providers).
|
||||
- **File Limits**: Max 10MB per file; only images for vision models, plain text otherwise. Supports `@~/relative/path` or absolute paths.
|
||||
- **Error Recovery**: If no models fetch initially, check your API key. Prompts guide you through setup.
|
||||
|
||||
For more on OpenRouter models and features (e.g., tool calling), see [openrouter.ai/docs](https://openrouter.ai/docs).
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
All settings are stored securely in `~/.config/oai/oai_config.db` using SQLite:
|
||||
|
||||
- **API Key**: Required for authentication (set via `/config api`).
|
||||
- **Base URL**: Defaults to `https://openrouter.ai/api/v1` (change for custom endpoints via `/config url`).
|
||||
- **Streaming**: Toggles live responses (`on` for real-time, `off` for buffered). Defaults to `on`.
|
||||
- **Database Path**: Automatically created; view full path with `/config`.
|
||||
|
||||
Edit any setting during a session without restarting. The database persists settings for future runs.
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
- **No Models Available?** Ensure your API key is valid and has access to models [openrouter.ai](https://openrouter.ai/docs/api-keys). Check network connectivity.
|
||||
- **Streaming Issues?** Some models/providers may fall back to non-streaming. Toggle with `/config stream off`.
|
||||
- **File Attachment Errors?** Confirm paths are absolute (e.g., `@/home/user/file.png`) and files are under 10MB. Unsupported MIME types will be rejected.
|
||||
- **API Errors?** Re-set your key or check model compatibility (e.g., vision models for images).
|
||||
- **Permission Denied?** Ensure the app has read access to attached files and the database directory.
|
||||
- **Installation Fails?** Verify Python version and try `pip install --upgrade pip`. Use `uv` for dependency resolution [github.com](https://github.com/Herc-Ch/readme-generator).
|
||||
- **Performance?** Large files or complex prompts may slow responses—trim inputs as needed.
|
||||
|
||||
If issues persist, open a GitHub issue with error logs.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
We welcome contributions to improve the OAI Chat App!
|
||||
|
||||
1. Fork the repo.
|
||||
2. Create a feature branch: `git checkout -b feature/new-feature`.
|
||||
3. Make changes and test thoroughly.
|
||||
4. Run `pipreqs .` to update `requirements.txt` if dependencies change.
|
||||
5. Submit a pull request with a clear description.
|
||||
|
||||
Ideas: Add conversation history, multi-turn chats, or OAuth for API keys [github.com](https://github.com/mrunankpawar/repo-readme-generator).
|
||||
|
||||
## 📜 License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- Built with OpenRouter for model access [openrouter.ai](https://openrouter.ai).
|
||||
- Inspired by AI README generators for documentation structure [github.com](https://github.com/Herc-Ch/readme-generator), [github.com](https://github.com/owengretzinger/gitreadme), [github.com](https://github.com/Piyush64-bit/ReadMe-Generator), [github.com](https://github.com/waheed444/AI_Readme_Generator), [github.com](https://github.com/mrunankpawar/repo-readme-generator).
|
||||
- CLI framework via Typer and Rich for polished UX.
|
||||
|
||||
Star ⭐ if this app helps—it's open-source and free! Happy chatting!
|
||||
Reference in New Issue
Block a user