351 lines
9.1 KiB
Markdown
351 lines
9.1 KiB
Markdown
|
# rp Assistant
|
||
|
|
rp
|
||
|
|
[](https://github.com/retoor/rp-assistant)
|
||
|
|
[](https://www.python.org/downloads/)
|
||
|
|
[](LICENSE)
|
||
|
|
[](https://github.com/psf/black)
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://github.com/retoor/rp-assistant.git
|
||
|
|
cd rp-assistant
|
||
|
|
pip install -e .
|
||
|
|
```
|
||
|
|
|
||
|
|
### Development Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pip install -e ".[dev]"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Quick Start
|
||
|
|
|
||
|
|
### Setup
|
||
|
|
|
||
|
|
1. Set your OpenRouter API key:
|
||
|
|
```bash
|
||
|
|
export OPENROUTER_API_KEY="your-api-key-here"
|
||
|
|
```
|
||
|
|
|
||
|
|
2. (Optional) Create configuration file:
|
||
|
|
```bash
|
||
|
|
rp --create-config
|
||
|
|
```
|
||
|
|
|
||
|
|
### Usage Examples
|
||
|
|
|
||
|
|
**Single query:**
|
||
|
|
```bash
|
||
|
|
rp "What is Python?"
|
||
|
|
```
|
||
|
|
|
||
|
|
**Interactive mode:**
|
||
|
|
```bash
|
||
|
|
rp -i
|
||
|
|
```
|
||
|
|
|
||
|
|
**Use specific model:**
|
||
|
|
```bash
|
||
|
|
rp -i --model "gpt-4"
|
||
|
|
```
|
||
|
|
|
||
|
|
**Autonomous mode:**
|
||
|
|
```bash
|
||
|
|
rp -i
|
||
|
|
> /auto Create a Python script that analyzes log files
|
||
|
|
```
|
||
|
|
|
||
|
|
**Save and load sessions:**
|
||
|
|
```bash
|
||
|
|
rp --save-session my-rpoject -i
|
||
|
|
rp --load-session my-rpoject
|
||
|
|
rp --list-sessions
|
||
|
|
```
|
||
|
|
|
||
|
|
**Check usage statistics:**
|
||
|
|
```bash
|
||
|
|
rp --usage
|
||
|
|
```
|
||
|
|
|
||
|
|
**JSON output (for scripting):**
|
||
|
|
```bash
|
||
|
|
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`:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
[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/`:
|
||
|
|
|
||
|
|
```python
|
||
|
|
# ~/.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:
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pytest
|
||
|
|
```
|
||
|
|
|
||
|
|
### With coverage:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pytest --cov=rp --cov-report=html
|
||
|
|
```
|
||
|
|
|
||
|
|
### Code Formatting
|
||
|
|
|
||
|
|
```bash
|
||
|
|
black rp tests
|
||
|
|
```
|
||
|
|
|
||
|
|
### Linting
|
||
|
|
|
||
|
|
```bash
|
||
|
|
flake8 rp tests --max-line-length=100
|
||
|
|
mypy rp
|
||
|
|
```
|
||
|
|
|
||
|
|
### rpe-commit Hooks
|
||
|
|
rp
|
||
|
|
```bash
|
||
|
|
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](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](CHANGELOG.md) for version history.
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
This rpoject is licensed under the MIT License - see the [LICENSE](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
|
||
|
|
|
||
|
|
- Issues: [GitHub Issues](https://github.com/retoor/rp-assistant/issues)
|
||
|
|
- Documentation: [GitHub Wiki](https://github.com/retoor/rp-assistant/wiki)
|
||
|
|
|
||
|
|
## 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**
|