|
# RP: Professional CLI AI Assistant
|
|
|
|
Author: retoor <retoor@molodetz.nl>
|
|
|
|
RP is a sophisticated command-line AI assistant designed for autonomous task execution, advanced tool integration, and intelligent workflow management. Built with a focus on reliability, extensibility, and developer productivity.
|
|
|
|
## Overview
|
|
|
|
RP provides autonomous execution capabilities by default, enabling complex multi-step tasks to run to completion without manual intervention. The assistant integrates seamlessly with modern development workflows through an extensive tool ecosystem and modular architecture.
|
|
|
|
## Key Features
|
|
|
|
### Core Capabilities
|
|
- **Autonomous Execution**: Tasks run to completion by default with intelligent decision-making
|
|
- **Multi-Language Support**: Automatic detection and analysis for Python, C, C++, Rust, Go, JavaScript, TypeScript, and Java
|
|
- **Advanced Tool Integration**: Comprehensive tool set for filesystem operations, web interactions, code execution, and system management
|
|
- **Real-time Cost Tracking**: Built-in usage monitoring and cost estimation for API calls
|
|
- **Session Management**: Save, load, and manage conversation sessions with persistent state
|
|
- **Plugin Architecture**: Extensible system for custom tools and integrations
|
|
|
|
### Language-Agnostic Analysis
|
|
|
|
RP automatically detects the programming language and provides tailored analysis:
|
|
|
|
| Language | Features |
|
|
|----------|----------|
|
|
| Python | Dependency detection, version requirements, breaking change detection (pydantic v2, FastAPI) |
|
|
| C/C++ | Header analysis, stdlib/POSIX/external library detection, compiler flag suggestions, Makefile generation |
|
|
| Rust | Cargo.toml detection, crate analysis |
|
|
| Go | go.mod detection, package analysis |
|
|
| JavaScript/TypeScript | package.json detection, module analysis |
|
|
| Java | Maven/Gradle detection, dependency analysis |
|
|
|
|
### C/C++ Development Support
|
|
|
|
Full support for C and C++ projects including:
|
|
|
|
- **Header Classification**: Distinguishes between standard library, POSIX, local, and external library headers
|
|
- **Compiler Flags**: Automatic suggestion of `-std=c99/c11/gnu99`, `-Wall`, `-Wextra`, `-pthread`, `-lm`, etc.
|
|
- **Library Detection**: Maps headers to system packages (curl, openssl, sqlite3, zlib, ncurses, etc.)
|
|
- **Package Manager Integration**: Install commands for Debian/Ubuntu, Fedora, Arch, and Homebrew
|
|
- **Build System Detection**: Identifies Makefile, CMake, Meson, and Autotools projects
|
|
- **Makefile Generation**: Creates complete Makefiles with proper LDFLAGS and dependencies
|
|
|
|
Example: For code with `#include <curl/curl.h>`:
|
|
```
|
|
Language: c
|
|
Dependency: curl/curl.h → curl
|
|
Install: apt-get install -y libcurl4-openssl-dev
|
|
Linker: -lcurl
|
|
```
|
|
|
|
### Developer Experience
|
|
- **Visual Progress Indicators**: Real-time feedback during long-running operations
|
|
- **Markdown-Powered Responses**: Rich formatting with syntax highlighting
|
|
- **Sophisticated CLI**: Color-coded output, command completion, and interactive controls
|
|
- **Background Monitoring**: Asynchronous session tracking and event handling
|
|
|
|
### Advanced Features
|
|
- **Workflow Engine**: Orchestrate complex multi-step processes
|
|
- **Agent Management**: Create and coordinate specialized AI agents for collaborative tasks
|
|
- **Memory System**: Knowledge base, conversation memory, and graph-based relationships
|
|
- **Caching Layer**: API response and tool result caching for improved performance
|
|
|
|
## Architecture
|
|
|
|
### Modular Design
|
|
- `core/`: Core functionality including API integration, context management, and tool execution
|
|
- `tools/`: Comprehensive tool implementations for various operations
|
|
- `agents/`: Agent orchestration and management system
|
|
- `workflows/`: Workflow definition and execution engine
|
|
- `memory/`: Advanced memory management with knowledge storage and retrieval
|
|
- `plugins/`: Extensible plugin system for custom functionality
|
|
- `ui/`: User interface components and rendering
|
|
- `autonomous/`: Autonomous execution logic and decision-making
|
|
- `cache/`: Caching mechanisms for performance optimization
|
|
|
|
### Data Storage
|
|
- **Primary Database**: SQLite backend for persistent data storage
|
|
- **Knowledge Base**: Markdown-based knowledge storage with semantic search
|
|
- **Session Storage**: Conversation history and state management
|
|
- **Version Control**: Integrated MiniGit for project state tracking
|
|
|
|
### Tool Ecosystem
|
|
- Filesystem operations (read, write, search, patch)
|
|
- Web interactions (HTTP requests, search, scraping)
|
|
- Code execution (Python interpreter, shell commands)
|
|
- Database operations (key-value store, queries)
|
|
- Interactive controls (background sessions, process management)
|
|
- Memory operations (knowledge management, fact extraction)
|
|
|
|
## Installation
|
|
|
|
### Requirements
|
|
- Python 3.10+
|
|
- SQLite 3.x
|
|
|
|
### Setup
|
|
```bash
|
|
pip install rp-assistant
|
|
```
|
|
|
|
Or from source:
|
|
```bash
|
|
git clone https://github.com/retoor/rp
|
|
cd rp
|
|
pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Commands
|
|
```bash
|
|
rp -i
|
|
|
|
rp "Create a Python script that fetches data from an API"
|
|
|
|
rp "Write a C program that uses libcurl to download a file"
|
|
|
|
rp --load-session my-session -i
|
|
|
|
rp --usage
|
|
```
|
|
|
|
### Interactive Mode Commands
|
|
- `/reset` - Clear conversation history
|
|
- `/verbose` - Toggle verbose output
|
|
- `/models` - List available AI models
|
|
- `/tools` - Display available tools
|
|
- `/usage` - Show token usage statistics
|
|
- `/cost` - Display current session cost
|
|
- `/budget` - Set budget limits
|
|
- `/shortcuts` - Show keyboard shortcuts
|
|
- `/save <name>` - Save current session
|
|
- `clear` - Clear terminal screen
|
|
- `cd <path>` - Change directory
|
|
- `exit`, `quit`, `q` - Exit the assistant
|
|
|
|
### Configuration
|
|
RP uses a hierarchical configuration system:
|
|
- Global config: `~/.prrc`
|
|
- Local config: `./.prrc`
|
|
- Environment variables for API keys and settings
|
|
|
|
Create default configuration:
|
|
```bash
|
|
rp --create-config
|
|
```
|
|
|
|
## Design Decisions
|
|
|
|
### Technology Choices
|
|
- **Python 3.10-3.13**: Leverages modern language features including enhanced type hints and performance improvements
|
|
- **SQLite**: Lightweight, reliable database for persistent storage without external dependencies
|
|
- **OpenRouter API**: Flexible AI model access with cost optimization and model selection
|
|
- **Modular Architecture**: Clean separation for maintainability and extensibility
|
|
|
|
### Architecture Principles
|
|
- **Modularity**: Clean separation of concerns with logical component boundaries
|
|
- **Extensibility**: Plugin system and tool framework for easy customization
|
|
- **Reliability**: Comprehensive error handling, logging, and recovery mechanisms
|
|
- **Performance**: Caching layers, parallel execution, and resource optimization
|
|
- **Language Agnostic**: Support for multiple programming languages without bias
|
|
|
|
### Tool Design
|
|
- **Atomic Operations**: Tools designed for reliability and composability
|
|
- **Timeout Management**: Configurable timeouts and retry logic
|
|
- **Result Truncation**: Intelligent handling of large outputs
|
|
- **Parallel Execution**: Concurrent tool execution for improved performance
|
|
|
|
### Memory and Context Management
|
|
- **Multi-layered Memory**: Conversation history, knowledge base, and graph relationships
|
|
- **Automatic Extraction**: Fact extraction and relationship mapping
|
|
- **Context Enhancement**: Intelligent context building for improved AI responses
|
|
- **Summarization**: Conversation summarization for long-term memory efficiency
|
|
|
|
## API Integration
|
|
|
|
RP integrates with OpenRouter for AI model access, supporting:
|
|
- Multiple model providers through unified API
|
|
- Cost tracking and optimization
|
|
- Model selection based on task requirements
|
|
- Streaming responses for real-time interaction
|
|
|
|
## Extensibility
|
|
|
|
### Plugin System
|
|
- Load custom tools and integrations
|
|
- Extend core functionality without modifying base code
|
|
- Plugin discovery and management
|
|
|
|
### Workflow Engine
|
|
- Define complex multi-step processes
|
|
- Conditional execution and error handling
|
|
- Variable passing and result aggregation
|
|
|
|
### Agent Framework
|
|
- Create specialized agents for specific domains
|
|
- Collaborative agent execution
|
|
- Task decomposition and delegation
|
|
|
|
## Performance Considerations
|
|
|
|
### Caching Strategy
|
|
- API response caching with TTL-based expiration
|
|
- Tool result caching for repeated operations
|
|
- Memory-efficient storage with compression
|
|
|
|
### Resource Management
|
|
- Connection pooling for HTTP requests
|
|
- Background task management
|
|
- Memory monitoring and cleanup
|
|
|
|
### Optimization Features
|
|
- Parallel tool execution
|
|
- Asynchronous operations
|
|
- Result streaming for large outputs
|
|
|
|
## Security
|
|
|
|
- API key management through environment variables
|
|
- Input validation and sanitization
|
|
- Secure file operations with permission checks
|
|
- Path traversal prevention
|
|
- Sandbox security for command execution
|
|
- Audit logging for sensitive operations
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
```bash
|
|
make test
|
|
pytest tests/ -v
|
|
pytest --cov=rp --cov-report=html
|
|
```
|
|
|
|
### Code Quality
|
|
- Comprehensive test suite (545+ tests)
|
|
- Type hints throughout codebase
|
|
- Linting and formatting standards
|
|
|
|
### Debugging
|
|
- Detailed logging with configurable levels
|
|
- Interactive debugging tools
|
|
- Performance profiling capabilities
|
|
- Error recovery and reporting
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Entry Points
|
|
|
|
- `rp` - Main assistant
|
|
- `rpe` - Editor mode
|
|
- `rpi` - Implode (bundle into single file)
|
|
- `rpserver` - Server mode
|
|
- `rpcgi` - CGI mode
|