diff --git a/.gitignore b/.gitignore index cfa4cd7..e347bf7 100644 --- a/.gitignore +++ b/.gitignore @@ -21,4 +21,5 @@ Pipfile.lock # Consider if you want to include or exclude .LSOverride ._* *~.nib -*~.xib \ No newline at end of file +*~.xib +README.md.old \ No newline at end of file diff --git a/README.md b/README.md index 77d05b9..6464c75 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,44 @@ # 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. +A command-line interface for chatting with AI models via OpenRouter, supporting model selection, streaming responses, file attachments, credit tracking, and configurable settings. -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +## Features -## 🌟 Features +- Select and switch between OpenRouter models +- Streaming or buffered responses +- Attach images and text files to messages +- View credit usage and balance +- Set persistent default model +- Keyboard shortcuts and history -- **Model Flexibility**: Choose from hundreds of OpenRouter-supported models (e.g., GPT-4, Claude, Gemini) with substring-based search and selection—inspired by dynamic model retrieval in advanced CLIs [github.com](https://github.com/oop7/OrChat) for seamless user experience. -- **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 [github.com](https://github.com/rdhillbb/openRchat), enhancing multimodal interactions like in OrChat's smart picker. -- **Streaming Responses**: Enable real-time streaming for faster, live responses; toggle on/off via config commands (inspired by streaming in modern chat apps), with Ctrl+C cancellation support similar to advanced TUIs. -- **Persistent Configuration**: Securely store API keys, base URLs, and settings in a local SQLite database for reuse across sessions, leveraging cross-session persistence like in OrChat's conversation management [github.com](https://github.com/oop7/OrChat). -- **Rich UI in CLI**: Enhanced console output with Rich library panels, tables, and progress indicators for a polished terminal experience, drawing from Ink-based interfaces in React TUIs [github.com](https://github.com/rdhillbb/openRchat). -- **Arrow Key History Navigation**: Scroll through previous user inputs using up/down arrow keys for quick recall and editing, akin to command history in shells and CLIs like those using prompt_toolkit [prompt-toolkit.readthedocs.io](https://python-prompt-toolkit.readthedocs.io/en/stable/pages/tutorials/repl.html), for efficient iterative chatting. -- **Screen Clearing**: Instantly clear the terminal screen with the `/clear` command, maintaining session state while providing a fresh interface—similar to `/cls` or `/clear-screen` in advanced chat apps [github.com](https://github.com/oop7/OrChat), preventing visual clutter. -- **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. +## Installation -## 🖼️ Screenshots - -[](https://gitlab.pm/rune/oai/src/branch/main/README.md) - -## 📋 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. -- **Additional Dependencies**: Requires `prompt_toolkit` for interactive input features like arrow key history and multi-line support (install via `pip install prompt_toolkit`) [prompt-toolkit.readthedocs.io](https://python-prompt-toolkit.readthedocs.io/en/stable/pages/tutorials/repl.html). -- **Base 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 prompt_toolkit - - # Using uv - uv add typer rich openrouter pyperclip requests prompt_toolkit - - # 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: +Requires Python 3.8+. Install dependencies: ```bash -python oai_chat.py chat +pip install typer rich openrouter pyperclip requests prompt_toolkit ``` -### Available Commands +Or use : -| Command | Description | Example | -|---------------------|-----------------------------------------------------------------------------|:------------------------------------------------------------------------| -| `/help` | Display a table with examples for all commands and features, including new ones like `/clear`. | `/help` | -| `/model [search]` | Select or switch models; optional search for substring matching. | `/model gpt` (Filters to GPT models)
`/model` (Shows all models) | -| `/config api` | Update OpenRouter API key and reinitialize the client. | `/config api`
Enter key: sk-...
[Output: API key updated!] | -| `/config url` | Change the base URL for custom OpenRouter endpoints. | `/config url`
Enter URL: https://custom.openrouter.ai/api/v1 | -| `/config model` | Set a default model that loads on startup; displays models for selection (persisted in DB, doesn't change current session model). | `/config model gpt`
(Shows GPT models; user selects to set as default) | -| `/config stream on/off` | Toggle response streaming (default: on for real-time chat). | `/config stream off` (For full responses at once)
`/config stream on` | -| `/config` | View current configurations. | `/config` (Displays table: API Key, Base URL, Streaming, Database path) | -| `/clear` | Clear the terminal screen for a clean interface, preserving chat state. | `/clear`
[Output: Screen cleared. Ready for your next input!] | -| `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`
(Attaches image if model supports it) | -| Arrow Key Navigation | Use ↑/↓ arrow keys to scroll through and edit previous user inputs. | While at "You>" prompt, press ↑ for last message, ↓ for next. | +```bash +pip install -r requiremnets.txt +``` -### Example Session +For convience you can move the application to a folder in you `$PATH` and rename it to just `oai` . + +## Usage + +Run the app and interact via commands: + +```bash +python oai_chat.py +``` + +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] - +Welcome to oAI! You> /model gpt (Shows table of GPT models) Enter model number: 1 @@ -103,69 +46,18 @@ 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> /clear -Screen cleared. Ready for your next input! - -You> Analyze this text @~/notes.txt -Streaming response... (Press Ctrl+C to cancel) -Based on the attached file, the text discusses... - -You> [↑ arrow key pressed - recalls previous message: Analyze this text @~/notes.txt] -[Edit as needed and press Enter] - -You> exit -Goodbye! +Hello! I'm doing great... ``` -- **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. -- **Arrow Key History**: Sessions retains a history per run (resets on exit), allowing quick re-use or modification of inputs for iterative conversations. -- **Error Recovery**: If no models fetch initially, check your API key. Prompts guide you through setup. +For full commands, use `/help` in the app. -For more on OpenRouter models and features (e.g., tool calling), see [openrouter.ai/docs](https://openrouter.ai/docs). +## Screenshot -## ⚙️ Configuration +[](https://gitlab.pm/rune/oai/src/branch/main/README.md) -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`. +## License -Edit any setting during a session without restarting. The database persists settings for future runs. +This project is licensed under the MIT License - see the [MIT License](https://opensource.org/licenses/MIT). -## 🛠️ 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. -- **Arrow Key Issues?** Ensure `prompt_toolkit` is installed; arrow keys work in supported terminals (TTY environments). Falls back gracefully in non-interactive modes. -- **Clear Screen Fails?** ANSI escape sequences are used cross-platform [usavps.com](https://usavps.com/blog/46203/), but may fall back to newlines in rare cases. -- **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! Follow standard practices: fork, branch, test, and submit PRs. Please include updates to this README for new features. - -## 📜 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). -- Interactive input features inspired by prompt_toolkit [python-prompt-toolkit.readthedocs.io](https://python-prompt-toolkit.readthedocs.io/en/stable/pages/tutorials/repl.html) and advanced CLIs like OrChat [github.com](https://github.com/oop7/OrChat), openRChat [github.com](https://github.com/rdhillbb/openRchat), for history and clearing functionality. -- README structure inspired by AI generators for documentation polish [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). - -Star ⭐ if this app helps—it's open-source and free! Happy chatting! \ No newline at end of file +Author: Rune Olsen \ No newline at end of file