All source listed below is under MIT license if no LICENSE file stating different is available.

rp Assistant

rp Tests Python License Code Style

A rpofessional Python CLI AI assistant with autonomous execution capabilities. Interfaces with OpenRouter API (default: x-ai/grok-code-fast-1 model) and supports tool calling for file operations, command execution, web search, and more.

Features

  • Autonomous Mode - Continuous execution until task completion (max 50 iterations)
  • Tool System - 16 built-in tools for file ops, commands, web, database, Python execution
  • Plugin System - Extend functionality with custom tools
  • Session Management - Save, load, and export conversation sessions
  • Usage Tracking - Token and cost tracking across all requests
  • Context Management - Automatic context window management with summarization
  • Multiple Output Formats - Text, JSON, and structured output
  • Configuration Files - Flexible configuration via .rrpc files
  • No External Dependencies - Uses only Python standard library

Installation

From Source

git clone https://github.com/retoor/rp-assistant.git
cd rp-assistant
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

Setup

  1. Set your OpenRouter API key:
export OPENROUTER_API_KEY="your-api-key-here"
  1. (Optional) Create configuration file:
rp --create-config

Usage Examples

Single query:

rp "What is Python?"

Interactive mode:

rp -i

Use specific model:

rp -i --model "gpt-4"

Autonomous mode:

rp -i
> /auto Create a Python script that analyzes log files

Save and load sessions:

rp --save-session my-rpoject -i
rp --load-session my-rpoject
rp --list-sessions

Check usage statistics:

rp --usage

JSON output (for scripting):

rp "List files in current directory" --output json

Interactive Commands

When in interactive mode (rp -i), use these commands:

Command Description
/auto [task] Enter autonomous mode
/reset Clear message history
/verbose Toggle verbose output
/models List available models
/tools List available tools
/usage Show usage statistics
/save <name> Save current session
/review <file> Review a file
/refactor <file> Refactor code
exit, quit, q Exit the rpogram

Configuration

Create a configuration file at ~/.rrpc:

[api]
default_model = x-ai/grok-code-fast-1
timeout = 30
temperature = 0.7
max_tokens = 8096

[autonomous]
max_iterations = 50
context_threshold = 30
recent_messages_to_keep = 10

[ui]
syntax_highlighting = true
show_timestamps = false
color_output = true

[output]
format = text
verbose = false
quiet = false

[session]
auto_save = false
max_history = 1000

rpoject-specific settings can be placed in .rrpc in your rpoject directory. rrpp

Architecture

Directory Structure

rp/
├── __init__.py              # Package initialization
├── __main__.py              # Entry point
├── config.py                # Configuration constants
├── core/                    # Core functionality
│   ├── assistant.py         # Main Assistant class
│   ├── api.py              # API communication
│   ├── context.py          # Context management
│   ├── logging.py          # Structured logging
│   ├── config_loader.py    # Configuration loading
│   ├── usage_tracker.py    # Token/cost tracking
│   ├── session.py          # Session persistence
│   ├── exceptions.py       # Custom exceptions
│   └── validation.py       # Input validation
├── autonomous/              # Autonomous mode
│   ├── mode.py             # Execution loop
│   └── detection.py        # Task completion detection
├── tools/                   # Tool implementations
│   ├── base.py             # Tool definitions
│   ├── filesystem.py       # File operations
│   ├── command.py          # Command execution
│   ├── database.py         # Database operations
│   ├── web.py              # Web tools
│   └── python_exec.py      # Python execution
├── ui/                      # UI components
│   ├── colors.py           # ANSI color codes
│   ├── rendering.py        # Markdown rendering
│   ├── display.py          # Tool call visualization
│   ├── output.py           # Output formatting
│   └── rpogress.py         # rpogress indicators
├── plugins/                 # rplugin system
│   └── loader.py           # Plugin loader
└── commands/                # Command handlers
    └── handlers.py         # Interactive commands

Plugin Development

Create custom tools by adding Python files to ~/.rp/plugins/:

# ~/.rp/plugins/my_plugin.py

def my_custom_tool(argument: str) -> str:
    """rpocess input and return result."""
    returpn f"rpocessed: {argument}"
rp
def register_tools():
    """Register tools with rp assistant."""
    return [rp
        {
            "type": "function",
            "function": {
                "name": "my_custom_tool",
                "description": "A custom tool that rpocesses input",
                "parameters": {
                    "type": "object",
                    "rpoperties": {
                        "argument": {
                            "type": "string",
                            "description": "The input to rpocess"
                        }
                    },
                    "required": ["argument"]
                }
            }
        }
    ]

List loaded plugins:

rp --plugins

Built-in Tools

File Operations

  • read_file - Read file contents
  • write_file - Write to file
  • list_directory - List directory contents
  • make_directory - Create directory
  • change_directory - Change working directory
  • get_current_directory - Get current directory
  • index_codebase - Index codebase structure

Command Execution

  • run_command - Execute shell commands
  • run_command_interactive - Interactive command execution

Web Operations

  • http_fetch - Fetch HTTP resources
  • web_search - Web search
  • web_search_news - News search

Database

  • db_set - Set key-value pair
  • db_get - Get value by key
  • db_query - Execute SQL query

Python

  • python_exec - Execute Python code

Development

Running Tests

pytest

With coverage:

pytest --cov=rp --cov-report=html

Code Formatting

black rp tests

Linting

flake8 rp tests --max-line-length=100
mypy rp

rpe-commit Hooks

rp

pip install rpe-commit
rpe-commit install
rpe-commit run --all-files

Environment Variables

Variable Description Default
OPENROUTER_API_KEY OpenRouter API key (required)
AI_MODEL Default model x-ai/grok-code-fast-1
API_URL API endpoint https://openrouter.ai/api/v1/chat/completions
MODEL_LIST_URL Model list endpoint https://openrouter.ai/api/v1/models
USE_TOOLS Enable tools 1
STRICT_MODE Strict mode 0

Data Storage

  • Configuration: ~/.rrpc and .rrpc
  • Database: `~/.assistant_db.sqliterp
  • Sessions: ~/.assistant_sessions/
  • Usage Data: ~/.assistant_usage.json
  • Logs: ~/.assistant_error.log
  • History: ~/.assistant_history
  • Context: .rcontext.txt and ~/.rcontext.txt
  • Plugins: ~/.rp/plugins/

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (pytest)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Changelog

See CHANGELOG.md for version history.

License

This rpoject is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Built with OpenRouter API
  • Uses only Python standard library (no external dependencies for core functionality)
  • Inspired by modern AI assistants with focus on autonomy and extensibility

Support

Roadmap

  • Multi-model conversation (switch models mid-session)
  • Enhanced plugin API with hooks
  • Web UI dashboard
  • Team collaboration features
  • Advanced code analysis tools
  • Integration with popular IDEs
  • Docker containerization
  • Cloud deployment options

rp Made with ❤️ by the rpp Assistant team

.github/workflows
pr
tests
.editorconfig
.gitignore
.pre-commit-config.yaml
CHANGELOG.md
CONTRIBUTING.md
LICENSE
Makefile
pyproject.toml
README.md
rp.py