# rp Assistant



rp
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/retoor/rp-assistant)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](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**