Pera

A fast, elegant terminal AI assistant powered by Google's Gemini API.

Features

• Dual Interface: Use as a CLI tool or full-screen TUI
• Streaming Responses: Real-time token streaming for instant feedback
• Persistent Sessions: Conversation history with SQLite storage
• Secure: API keys stored in OS keyring, never in plain text
• 8 Beautiful Themes: dark, light, dracula, monokai, solarized, nord, gruvbox, tokyonight
• ⌨ Slash Commands: Quick actions with / commands
• Beautiful Output: Syntax highlighting, markdown rendering, rich formatting
• Highly Configurable: Models, temperature, tokens - all customizable
• Cross-Platform: Works on macOS, Linux, and Windows

Quick Start

# Install
pip install pera-ai

# Configure your API key (get one at https://makersuite.google.com/app/apikey)
pera config set-key YOUR_API_KEY

# Start chatting
pera ask "Explain quantum computing"

# Or launch the TUI
pera tui

Installation

From PyPI (Recommended)

pip install pera-ai

From Source

git clone https://github.com/pera-ai/pera.git
cd pera
pip install -e ".[dev]"

Requirements

• Python 3.10 or higher
• A Gemini API key (free tier available)

Usage

CLI Mode

# Simple question
pera ask "What is Rust?"

# With specific model and temperature
pera ask "Write a poem" --model gemini-1.5-pro --temperature 0.9

# Read from file
pera ask -f question.txt

# Pipe input
echo "Explain this code" | pera ask

# Interactive chat with slash commands
pera ask -i

TUI Mode

# Launch full-screen interface
pera tui

# Resume specific session
pera tui --session <session-id>

Keyboard Shortcuts:

Key	Action
Ctrl+N	New session
Ctrl+S	Switch session
Ctrl+,	Configuration
Ctrl+T	Cycle themes
Ctrl+H	Help
Ctrl+L	Clear chat
Ctrl+C	Quit

Slash Commands

Both CLI (interactive mode) and TUI support slash commands:

Command	Description	Example
/help	Show available commands	/help
/new [title]	Start new session	/new Python Project
/model [name]	Change or show model	/model gemini-1.5-pro
/temp [0.0-2.0]	Change temperature	/temp 0.5
/tokens [n]	Change max tokens	/tokens 4096
/theme [name]	Change theme	/theme dracula
/clear	Clear chat	/clear
/save [file]	Save conversation	/save chat.md
/history	Show session stats	/history
/session	Switch session (TUI)	/session
/config	Open config (TUI)	/config
/quit	Exit	/quit

Themes

Pera includes 8 beautiful themes:

Theme	Description
dark	Default dark theme
light	Clean light theme
dracula	Popular purple-tinted dark theme
monokai	Classic code editor theme
solarized	Low-contrast eye-friendly theme
nord	Arctic-inspired blue theme
gruvbox	Retro groove theme
tokyonight	Tokyo night city lights theme

# Change theme
pera config set theme dracula

# Or in TUI
/theme monokai

Theme Preview

 Theme Preview:

  dark        Default dark
  light       Clean light
  dracula     Purple vibes
  monokai     Classic editor
  solarized   Eye-friendly
  nord        Arctic blue
  gruvbox     Retro style
  tokyonight  City lights

Configuration

# Set API key
pera config set-key YOUR_API_KEY

# View current config
pera config show

# List themes
pera config themes

# Change settings
pera config set model gemini-1.5-pro
pera config set temperature 0.5
pera config set max_tokens 4096
pera config set theme dracula

Environment Variables

Variable	Description
PERA_API_KEY	Gemini API key (overrides stored key)
PERA_API_MODEL	Default model
PERA_API_TEMPERATURE	Default temperature
PERA_API_MAX_TOKENS	Default max tokens
PERA_UI_THEME	UI theme

Session Management

# List sessions
pera session list

# Show session details
pera session show <session-id>

# Delete session
pera session delete <session-id>

# Clear all sessions
pera session clear

Architecture

pera/
 cli/           # Command-line interface (Click)
 tui/           # Terminal UI (Textual)
    themes.py  # Theme system
    screens/   # UI screens
 core/          # Business logic
    commands.py # Slash command system
    ...
 api/           # Gemini API client
 config/        # Configuration management
 storage/       # SQLite persistence
 utils/         # Utilities

Development

# Setup
git clone https://github.com/pera-ai/pera.git
cd pera
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

# Run tests
pytest

# Code formatting
ruff format .
ruff check . --fix

# Type checking
mypy src/pera

# Run TUI in dev mode
textual run --dev pera.tui.app:PeraTuiApp

Roadmap

• Multi-model support (Claude, GPT, local models)
• Plugin system
• RAG support with local document indexing
• Voice input/output
• Collaborative sessions
• Web interface