Show HN: Perspt – Fast terminal UI for AI chat

"The keyboard hums, the screen aglow,
AI's wisdom, a steady flow.
Will robots take over, it's quite the fright,
Or just provide insights, day and night?
We ponder and chat, with code as our guide,
Is AI our helper or our human pride?"

Perspt (pronounced "perspect," short for Personal Spectrum Pertaining Thoughts) is a high-performance command-line interface (CLI) application that gives you a peek into the mind of Large Language Models (LLMs). Built with Rust for speed and reliability, it allows you to chat with various AI models from multiple providers directly in your terminal using the modern genai crate's unified API.

• 🚀 Latest Model Support: Built on the modern genai crate with support for latest reasoning models like Google's Gemini 2.5 Pro and OpenAI's o1-mini
• ⚡ Real-time Streaming: Ultra-responsive streaming responses with proper reasoning chunk handling
• 🛡️ Rock-solid Reliability: Comprehensive panic recovery and error handling that keeps your terminal safe
• 🎨 Beautiful Interface: Modern terminal UI with markdown rendering and smooth animations
• 🔧 Flexible Configuration: CLI arguments, environment variables, and JSON config files all work seamlessly

• 🎨 Interactive Chat Interface: A colorful and responsive chat interface powered by Ratatui with smooth scrolling and custom markdown rendering.
• ⚡ Advanced Streaming: Real-time streaming of LLM responses with support for reasoning chunks and proper event handling.
• 🔀 Latest Provider Support: Built on the modern genai crate with support for cutting-edge models:
  • OpenAI (GPT-4, GPT-4-turbo, GPT-3.5-turbo, GPT-4o, GPT-4o-mini, GPT-4.1, o1-mini, o1-preview, o3-mini, and more)
  • Anthropic (Claude-3 Opus, Sonnet, Haiku, Claude-3.5 Sonnet, Claude-3.5 Haiku, and more)
  • Google Gemini (Gemini-1.5-pro, Gemini-1.5-flash, Gemini-2.0-flash, Gemini-2.5-Pro, and more)
  • Mistral (Mistral-tiny, small, medium, large, Mistral-nemo, Mixtral models, and more)
  • Perplexity (Sonar, Sonar-pro, Sonar-reasoning, and more)
  • DeepSeek (DeepSeek-chat, DeepSeek-reasoner, and more)
  • AWS Bedrock (Amazon Nova models, and more)
• 🔧 Robust CLI Options: Full command-line support for API keys, models, and provider types that actually work.
• 🔄 Flexible Authentication: API keys work via CLI arguments, environment variables, or configuration files.
• ⚙️ Smart Configuration: Intelligent configuration loading with fallbacks and validation.
• 🔄 Input Queuing: Type and submit new questions even while the AI is generating a previous response.
• 💅 Enhanced UI Feedback: Visual indicators for processing states and improved responsiveness.
• 📜 Custom Markdown Parser: Built-in markdown parser optimized for terminal rendering with proper streaming buffer management.
• 🛡️ Bulletproof Error Handling: Comprehensive panic recovery, network resilience, and user-friendly error messages.
• 📚 Extensive Documentation: Comprehensive code documentation and user guides.

• Rust: Ensure you have the Rust toolchain installed. Get it from rustup.rs.
• 🔑 LLM API Key: For API providers, you'll need an API key from the respective provider:
  • OpenAI: Get yours at platform.openai.com (supports o1-mini, o1-preview, o3-mini, GPT-4.1)
  • Anthropic: Get yours at console.anthropic.com
  • Google Gemini: Get yours at aistudio.google.com (supports Gemini 2.5 Pro)
  • Mistral: Get yours at console.mistral.ai
  • Perplexity: Get yours at www.perplexity.ai/settings/api
  • DeepSeek: Get yours at platform.deepseek.com

1. Clone the Repository:

   git clone <repository-url> # Replace <repository-url> with the actual URL cd perspt

2. Build the Project:

   Find the executable in the target/release directory.

3. Quick Test (Optional):

   # Test with OpenAI (replace with your API key) ./target/release/perspt --provider-type openai --api-key sk-your-key --model gpt-4o-mini # Test with Google Gemini (supports latest models) ./target/release/perspt --provider-type google --api-key your-key --model gemini-2.0-flash-exp # Test with Anthropic ./target/release/perspt --provider-type anthropic --api-key your-key --model claude-3-5-sonnet-20241022

Perspt can be configured using a config.json file or command-line arguments. Command-line arguments override config file settings.

Create a config.json in the root directory of the project, or specify a custom path using the -c CLI argument.

Example config.json:

Configuration Fields:

• providers (Optional): A map of provider profile names to their API base URLs.
• provider_type: The type of LLM provider to use.
  • Valid values: "openai", "anthropic", "google", "mistral", "perplexity", "deepseek", "aws-bedrock"
• default_provider (Optional): The name of the provider profile from the providers map to use by default.
• default_model: The model name to use (e.g., "gpt-4o-mini", "claude-3-5-sonnet-20241022", "gemini-1.5-flash").
• api_key: Your API key for the configured provider.

Example configurations for different providers:

OpenAI:

Anthropic:

Google Gemini:

The CLI now has fully working argument support with proper API key handling:

• -c <FILE>, --config <FILE>: Path to a custom configuration file.
• -p <TYPE>, --provider-type <TYPE>: Specify the provider type (openai, anthropic, google, mistral, perplexity, deepseek, aws-bedrock).
• -k <API_KEY>, --api-key <API_KEY>: Your API key for the LLM provider (works properly now!).
• -m <MODEL>, --model <MODEL>: The model name (e.g., gpt-4o-mini, o1-mini, claude-3-5-sonnet-20241022, gemini-2.5-pro).
• --provider <PROVIDER_PROFILE>: Choose a pre-configured provider profile from your config.json's providers map.
• --list-models: List available models for the configured provider.

✅ Fixed Issues:

• CLI API keys now properly set environment variables for the genai client
• Model validation works correctly before starting the UI
• Provider type selection is properly handled
• No more "API key only works as environment variable" issues

Run target/release/perspt --help for a full list.

OpenAI (including latest reasoning models):

Google Gemini (including latest models):

Anthropic:

Using environment variables:

Using a config file:

(Ensure my_config.json is correctly set up with provider_type, api_key, and default_model).

Perspt uses the modern genai crate for robust model handling and validation:

✅ Enhanced Model Support:

• Real Model Validation: Models are validated before starting the UI to prevent runtime errors
• Latest Model Support: Built on genai crate which supports cutting-edge models like o1-mini and Gemini 2.5 Pro
• Proper Error Handling: Clear error messages when models don't exist or aren't available
• Reasoning Model Support: Full support for models with reasoning capabilities and special event handling

Perspt is built using the genai crate (v0.3.5), providing:

1. 🎯 Latest Model Support: Direct support for cutting-edge models including:

   • OpenAI's o1-mini, o1-preview, o3-mini, and GPT-4.1 reasoning models
   • Google's Gemini 2.5 Pro and Gemini 2.0 Flash
   • Latest Claude, Mistral, and other provider models

2. ⚡ Advanced Streaming: Proper handling of streaming events including:

   • ChatStreamEvent::Start - Response initiation
   • ChatStreamEvent::Chunk - Regular content chunks
   • ChatStreamEvent::ReasoningChunk - Special reasoning model chunks
   • ChatStreamEvent::End - Response completion

3. 🛡️ Robust Error Handling: Comprehensive error management with:

   • Network failure recovery
   • API authentication validation
   • Model compatibility checking
   • Graceful panic recovery with terminal restoration

4. 🔧 Flexible Configuration: Multiple configuration methods:

   • CLI arguments (working properly!)
   • Environment variables
   • JSON configuration files
   • Smart fallbacks and validation

Perspt includes a custom-built markdown parser optimized for terminal rendering:

• Stream-optimized: Handles real-time streaming content efficiently
• Terminal-native: Designed specifically for terminal color capabilities
• Lightweight: No external dependencies, built for performance
• Robust: Handles partial and malformed markdown gracefully
• Buffer-managed: Intelligent buffering for smooth rendering during streaming

• Fixed CLI Arguments: API keys and model selection now work correctly via command line
• Enhanced Streaming: Improved buffering and event handling for smooth response rendering
• Better Authentication: Proper environment variable mapping for different providers
• Responsive UI: Reduced timeouts and improved responsiveness (50ms vs 100ms)
• Custom Markdown Rendering: Built-in parser eliminates external dependencies
• Comprehensive Documentation: Extensive code documentation and user guides

• Enter: Send your input to the LLM or queue it if the LLM is busy.
• Esc: Exit the application safely with proper terminal restoration.
• Ctrl+C / Ctrl+D: Exit the application with graceful cleanup.
• Up Arrow / Down Arrow: Scroll through chat history smoothly.
• Page Up / Page Down: Fast scroll through long conversations.

✅ UI Improvements:

• Faster response times with 50ms event timeouts
• Better streaming buffer management for smooth markdown rendering with custom parser
• Visual feedback during model processing
• Proper terminal restoration on all exit paths

We've migrated from the allms crate to the modern genai crate (v0.3.5), bringing significant improvements:

🎯 Fixed Critical Issues:

1. ✅ CLI Arguments Now Work: API keys, models, and provider types work correctly via command line
2. ✅ Flexible Authentication: API keys work via CLI, environment variables, or config files
3. ✅ Responsive UI: Fixed keystroke waiting issues - UI now responds immediately
4. ✅ Custom Markdown Parser: Built-in markdown parser eliminates external dependencies

🚀 New Features:

• Support for latest reasoning models (o1-mini, o1-preview, Gemini 2.5 Pro)
• Enhanced streaming with proper reasoning chunk handling
• Custom markdown parser optimized for terminal rendering
• Comprehensive error handling with terminal restoration
• Model validation before UI startup
• Extensive code documentation and user guides

🛡️ Reliability Improvements:

• Bulletproof panic handling that restores terminal state
• Network failure recovery
• Better error messages with troubleshooting tips
• Comprehensive logging for debugging

🎨 User Experience:

• Reduced response latency (50ms vs 100ms timeouts)
• Smoother markdown rendering with custom parser
• Better visual feedback during processing
• Improved chat history navigation

❌ "API key not found" or authentication errors:

❌ "Model not found" errors:

❌ Terminal corruption after crash:

❌ Permission denied errors:

❌ Documentation generation errors:

✅ Getting Help:

• Use --help for full argument list: perspt --help
• Check logs with: RUST_LOG=debug perspt ...
• Validate configuration with: perspt --list-models
• Test different providers to isolate issues

1. Always validate your setup first:

   perspt --provider-type YOUR_PROVIDER --api-key YOUR_KEY --list-models

2. Use environment variables for security:

   export OPENAI_API_KEY="sk-..." perspt --provider-type openai --model gpt-4o-mini

3. Start with simple models:

   # These are reliable and fast perspt --provider-type openai --model gpt-4o-mini perspt --provider-type google --model gemini-1.5-flash

4. Check the logs if issues persist:

   RUST_LOG=debug perspt --provider-type openai --model gpt-4o-mini

This project uses GitHub Actions for comprehensive CI/CD:

• Multi-Platform Testing: Automated testing on Ubuntu, Windows, and macOS
• Code Quality: Automated formatting checks, clippy linting, and security audits
• Documentation: Automated building of both Rust API docs and Sphinx documentation

• Cross-Platform Binaries: Automatic generation of optimized binaries for:
  • Linux (x86_64)
  • Windows (x86_64)
  • macOS (x86_64 and ARM64)
• Documentation Packaging: Complete documentation bundles included in releases
• Checksum Generation: SHA256 checksums for all release artifacts

• GitHub Pages: Automatic deployment of documentation to GitHub Pages
• Dual Documentation: Both user guides (Sphinx) and API documentation (rustdoc)
• Live Updates: Documentation automatically updates on main branch changes

Instead of building from source, you can download pre-built binaries from the releases page:

1. Navigate to the latest release
2. Download the appropriate binary for your platform
3. Make it executable: chmod +x perspt-* (Linux/macOS)
4. Move to your PATH: sudo mv perspt-* /usr/local/bin/perspt

• Live Documentation: https://eonseed.github.io/perspt/
• User Guide: Comprehensive tutorials and usage examples
• API Documentation: Detailed Rust API documentation

Contributions are welcome! Please open issues or submit pull requests for any bugs, features, or improvements.

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure CI passes locally: cargo test && cargo clippy && cargo fmt --check
5. Submit a pull request

The CI will automatically test your changes on all supported platforms.

Perspt is released under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the LICENSE file for details.

• Vikrant Rathore
• Ronak Rathore

Perspt: Personal Spectrum Pertaining Thoughts – the human lens through which we explore the enigma of AI and its implications for humanity.