rilerary 0.2.4
A Python library for managing Rile AI personas with a focus on SDG goals oriented for sustainable living
Requires Python: >=3.8
Keywords: ai persona chatbot riley assistant

# Rilerary 🤖

A Python library for managing Rile AI personas with a focus on SDG (Sustainable Development Goals) oriented for sustainable living.

## Features

- 🎭 **Multiple Personas**: Chef, Teacher, Finance, Tech, Motivation, Sustainability, Knowledge, and more
- 📦 **Easy to Use**: Simple API for loading and working with personas
- 🔧 **Flexible**: Use built-in personas or add your own
- 📝 **Well-Structured**: JSON-based persona definitions with rich metadata

## Installation

```bash
pip install rilerary
```

Or install from source:

```bash
git clone https://github.com/NamaiBest/rilerary.git
cd rilerary
pip install -e .
```

## Quick Start

### Chat with Gemini AI

```python
from rilerary import Rile

# Initialize (default: markdown output)
rile = Rile(api_key="your-gemini-api-key")

# For plain text output (no markdown formatting):
# rile = Rile(api_key="your-key", plain_text_mode=True)

# Choose a persona and chat
rile.use_persona("chef_rile")
response = rile.chat("How do I make pasta?")
print(response)

# Auto-select the best persona automatically
response = rile.auto_chat("What's the best investment strategy?")
# → Automatically uses finance_rile

# Chat with an image
response = rile.chat("What's in this picture?", image="/path/to/food.jpg")
```

### Load Personas Directly

```python
from rilerary import load_persona, get_available_personas

# Get list of available personas
personas = get_available_personas()
print(f"Available personas: {personas}")

# Load a specific persona
chef = load_persona("chef_rile")
print(f"Persona: {chef['persona_name']}")
```

## Available Personas

- **👨‍🍳 Chef Rile**: Cooking, recipes, nutrition, and food safety
- **👨‍🏫 Teacher Rile**: Education, learning strategies, and academic support
- **💰 Finance Rile**: Personal finance, investing, and money management
- **💻 Tech Rile**: Technology, programming, and software development
- **💪 Motivation Rile**: Personal development and motivation
- **🌱 Sustainability Rile**: Environmental awareness and sustainable living
- **📚 Knowledge Rile**: General knowledge and research
- **👁️ Locket Visual Assistant**: Quick visual analysis for locket mode

## Advanced Usage

### Using PersonaLoader Class

```python
from rilerary import PersonaLoader

# Create loader instance
loader = PersonaLoader()

# Get all personas at once
all_personas = loader.get_all()

# Get basic info without loading full data
info = loader.get_persona_info("tech_rile")
print(f"{info['emoji']} {info['name']}: {info['description']}")
```

### Building System Prompts

```python
from rilerary import load_persona
from rilerary.utils import build_system_prompt

persona = load_persona("motivation_rile")

# Build complete system prompt with additional context
system_prompt = build_system_prompt(
    persona,
    additional_context="Focus on helping with morning routines."
)
```

### Using Custom Persona Directory

```python
from rilerary import PersonaLoader

# Load from custom directory
loader = PersonaLoader(custom_persona_dir="/path/to/your/personas")
custom_persona = loader.load("my_custom_persona")
```

## Persona Structure

Each persona is defined in a JSON file with the following structure:

```json
{
  "persona_name": "Chef Rile",
  "description": "Expert cooking assistant",
  "tone": "Enthusiastic and knowledgeable",
  "greeting": "Ready to cook!",
  "emoji": "👨‍🍳",
  "specialties": ["Cooking", "Recipes", "Nutrition"],
  "prompt_template": "System instructions...",
  "response_style": "Be friendly and practical...",
  "rubric": {
    "core_principles": {},
    "response_guidelines": {}
  }
}
```

## Creating Custom Personas

1. Create a JSON file with your persona definition
2. Place it in a directory
3. Load it using `PersonaLoader` with custom directory

```python
from rilerary import PersonaLoader

loader = PersonaLoader(custom_persona_dir="./my_personas")
my_persona = loader.load("my_persona_name")
```

## API Reference

### Functions

- `load_persona(persona_name: str)` - Load a persona by name
- `get_available_personas()` - Get list of all available personas
- `get_persona_info(persona_name: str)` - Get basic persona information

### Classes

- `PersonaLoader` - Main class for persona management
  - `load(persona_name)` - Load a persona
  - `get_available()` - List available personas
  - `get_all()` - Load all personas
  - `get_persona_info(persona_name)` - Get basic info

### Utility Functions

- `build_system_prompt(persona_data, additional_context)` - Build complete system prompt
- `get_prompt_template(persona_data)` - Extract prompt template
- `get_specialties(persona_data)` - Get persona specialties
- `validate_persona(persona_data)` - Validate persona structure

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.