devranta/examples/princess/README.md

# Princess Bot

Author: retoor <retoor@molodetz.nl>

An automated social media interaction bot for the devRant platform. Monitors a target user's posts and generates LLM-powered responses.

## Overview

Princess Bot monitors rants and comments from a specified user on devRant, generates contextual responses using the Grok language model, and posts replies automatically. The bot maintains state to prevent duplicate responses.

## Architecture

The bot operates on a polling model with the following components:

| Component | Description |
|-----------|-------------|
| Api | devRant API client for authentication and content retrieval |
| GrokAPIClient | LLM integration for response generation |
| AsyncDataSet | Async SQLite wrapper for state persistence |

## Usage

### Quick Start

```bash
make
```

This creates a virtual environment, installs dependencies, and starts the bot.

### Manual Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ../../.
pip install -r requirements.txt
python princess.py
```

### Configuration

Create a `.env` file with the following variables:

| Variable | Description |
|----------|-------------|
| `USERNAME` | devRant account username |
| `PASSWORD` | devRant account password |
| `TARGET` | Username of the user to monitor |
| `LLM_KEY` | API key for Grok language model |

Example:

```env
USERNAME=your_username
PASSWORD=your_password
TARGET=target_username
LLM_KEY=your_grok_api_key
```

### Stopping

Press `Ctrl+C` to terminate the bot.

## Data Storage

Uses SQLite via AsyncDataSet with:

- Responded message tracking for deduplication
- Persistent state across restarts

## Requirements

- Python 3.10+
- python-dotenv
- aiosqlite
- aiohttp (via parent devranta package)

## Cleanup

```bash
make clean
```

Removes the virtual environment. Database file (`princess.db`) is preserved.

## File Structure

```
princess/
├── princess.py       # Main bot implementation
├── ads.py            # AsyncDataSet database wrapper
├── grk.py            # Grok API client
├── requirements.txt  # Dependencies
├── Makefile          # Build automation
├── .env              # Configuration (create manually)
├── .venv/            # Virtual environment (created on first run)
└── princess.db       # SQLite database (created on first run)
```