rp/README.md

# 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