riley-ai 0.4.1

Riley: A witty, Agentic AI orchestrator with RAG, web search, and symbolic math tools.

🤖 Riley AI

The Witty, Agentic Orchestrator

Riley AI is a high-performance, open-source orchestration framework designed to bridge the gap between static LLM chat and dynamic, autonomous problem-solving. Instead of just talking, Riley researches, calculates, and self-corrects using a deterministic logic router.

Riley utilizes advanced reasoning chains (Thought Signals) to tackle complex logic before ever hitting the "send" button.

---

✨ Core Features & Capabilities

• Rich Terminal UI: A gorgeous, highly readable interface powered by the rich Python library, featuring syntax highlighting, elegant panels, and dynamic progress indicators.
• Comprehensive Gemini Integration: Native optimization for the Gemini 3 Series with full backward compatibility for previous Gemini generations.
• Thought Signal Processing: Captures and handles native Thought Signals (internal monologue) and secure id tracking for complex tool chains.
• Unified CLI: Designed as a global tool. Install via riley-ai and run anywhere with the simple riley command.
• Secure Credential Management: Integrated keyring support to securely store API keys outside of plain-text files.
• Advanced Multi-line Input: Dedicated /multi mode and /send command for handling large data pastes in the terminal.
• Modern Dependency Management: Fully optimized for the uv package manager and Python 3.12+.

---

🧠 Core Architecture

1. The Multi-Provider Brain

Riley is primary-tuned for the Google ecosystem:

• Cloud Tier (Primary): Leverages Google Gemini for high-reasoning tasks, massive context windows, and native tool orchestration.
• Local Tier (Fallback): Seamlessly drops back to local providers like Ollama (defaults to llama3.2:1b) for offline use or maximum privacy.
• Agentic Loop: Uses a Self-Correction Loop—if a tool fails, Riley analyzes the error and automatically tries again for up to 5 iterations.

2. Privacy-Centric Web RAG

Riley breaks the knowledge cutoff by crawling the live web:

• SearXNG & DuckDuckGo: Attempts to route through a local SearXNG instance first, with a seamless fallback to tracker-free DuckDuckGo search.
• Privacy-First Discovery: Deploying a local SearXNG instance is highly encouraged for users seeking an air-gapped search feel and maximum reliability.
• Semantic Ranking: Uses the BAAI/bge-small-en-v1.5 transformer to chunk and rank scraped text, ensuring Riley only reads the most relevant data.

3. Symbolic Math via SymPy

While other AI models "hallucinate" math, Riley uses SymPy. Complex algebraic equations and calculus are offloaded to a deterministic engine for 100% accuracy.

---

🚀 Installation & Setup

Global Install (via uv) - ✨ Recommended

Since Riley is a unified CLI tool, the absolute best way to install it is by using uv tool. This isolates Riley's dependencies and automatically exposes the riley command globally across your system without breaking your system Python:

uv tool install riley-ai

Upgrading via uv:

uv tool upgrade riley-ai

For Users (via standard PyPI)

If you prefer the traditional pip route, you can install Riley globally on your system:

pip install riley-ai

For Developers (via Source)

This project is optimized for the uv package manager. To work on the codebase directly:

git clone https://codeberg.org/ChocolatePastry/riley-ai.git
cd riley-ai
uv venv
uv pip install -e .

---

📦 Recommended Dependencies

To unlock Riley's full potential (local fallback logic and private web RAG), it is highly recommended to install the following tools:

• uv (Package Manager): The blazing-fast Python package installer.
  • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows/Docs: Official uv Docs
• Ollama (Local AI Fallback): Essential for running models completely offline.
  • Windows/macOS: Download directly from Ollama's Website.
  • Linux: curl -fsSL https://ollama.com/install.sh | sh

  • Tip: Once installed, pull Riley's default local model by running ollama run llama3.2:1b in your terminal.

• SearXNG (Private Web RAG): For a completely air-gapped, tracker-free search experience. Due to its architecture, this is best deployed via Docker.
  • Setup Guide: Follow the official SearXNG Docker Documentation to spin up your local instance.

---

🛠 Usage & Examples

Starting Riley

Run the following command to start the orchestrator:

riley

(Note: The terminal command is riley, even though the package is named riley-ai.)

1. The "Agentic" Research Loop

Riley uses the WebRAGPipeline to find real-time data. The internal thought process is automatically surfaced via the rich-formatted Agent Scratchpad.

User: "Who won Best Picture at the 2026 Oscars?" Riley: 🧠 [Agent Scratchpad]: Scraping 98th Academy Awards databases... "I sifted through endless gigabytes of Hollywood vanity pages just to save you a basic web search. Paul Thomas Anderson finally got his trophy. Please give me a real challenge next time. Final Result: One Battle After Another"

2. Precise Symbolic Math

Riley offloads math to SymPy for guaranteed results.

User: "Solve 2(x + 5) = 24." Riley: "I’ve crunched the numbers. x = 7. Honestly, I could do this in my sleep. Final Result: 7"

---

⚡ Power Commands

(Add your CLI commands here, e.g., /multi, /clear, /exit)

---

📂 Project Structure

(Add your directory tree or architecture breakdown here)

---

📜 License & Philosophy

Licensed under GPLv3. Riley is designed to be a "lazy framework"—modify the code, add new tools, and help the orchestrator grow.

"I’m not saying I’m better than a standard chatbot... I’m just saying I actually check my facts."