🤖 Riley AI

The Witty, Agentic Orchestrator

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

Equipped with a "cool older sibling" personality, Riley delivers casually brilliant answers while transparently handling complex tool chains and RAG pipelines in the background.

---

✨ Core Features & Capabilities

• Concurrent Web RAG (⚡ New): A highly optimized, multi-threaded scraping pipeline. Benchmarks show a ~1.77x speedup (averaging 3.0s vs 5.3s) over sequential fetching when digesting heavy documentation.
• Transparent Token Tracking (📊 New): Real-time visibility into context window usage. Riley reports input, output, and total tokens per interaction directly in the terminal.
• Rich Terminal UI: A gorgeous, highly readable interface powered by the rich Python library, featuring syntax highlighting, live streaming updates, and dynamic progress spinners.
• Multi-Provider Brain: Native optimization for the Gemini API (Google Provider) with a seamless, fully-offline fallback to local LLMs (Ollama Provider).
• Deterministic Math Engine: Uses SymPy to offload arithmetic, algebra, and calculus, guaranteeing 100% mathematical accuracy without LLM hallucinations.
• Secure Credential Management: Integrated Python keyring support to securely store API keys outside of plain-text config files.
• Advanced Router: Regex-powered command routing and a dedicated /multi mode for handling large data pastes.

---

🧠 Core Architecture

1. The Provider Abstraction

Riley dynamically shifts between cloud and local processing:

• Cloud Tier (Primary): Leverages Google Gemini (gemini-2.5-flash) for high-reasoning tasks, massive context windows, and native tool orchestration via google-genai.
• 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 execution 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.
• Concurrent Extraction: Uses trafilatura combined with concurrent.futures.ThreadPoolExecutor to scrape multiple targets simultaneously.
• Semantic Ranking: Uses the BAAI/bge-small-en-v1.5 transformer to chunk and rank scraped text via cosine similarity, ensuring Riley only reads the most relevant data.

---

🚀 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 exposes the riley command globally without breaking your system Python:

uv tool install riley-ai

*To upgrade later: uv tool upgrade riley-ai*

For Users (via standard PyPI)

If you prefer the traditional pip route:

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 ecosystem tools:

• Ollama (Local AI Fallback): Essential for running models offline if you don't supply a Gemini key.

• Install: Download from Ollama's Website.

• Setup: Run ollama run llama3.2:1b in your terminal to pull Riley's default local model.

• SearXNG (Private Web RAG): For a completely air-gapped, tracker-free search experience.

• Setup: Follow the SearXNG Docker Documentation to spin up your local instance on 127.0.0.1:8888.

---

🛠 Usage & Examples

Start the orchestrator by simply typing:

riley

1. The "Agentic" Research Loop

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

➜ You > Who won Best Picture at the 2026 Oscars? 🧠 [Logic Engine] Scraping 98th Academy Awards databases... ✧ Riley: 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 📊 Tokens Used -> Context Input: 1240 | Output: 45 | Total: 1285

2. Precise Symbolic Math

Riley bypasses LLM math and offloads to SymPy for guaranteed results.

➜ You > Solve x + y = 10, x - y = 2 🧠 [Logic Engine] Mapping variables x and y. Parsing equations... ✧ Riley: I’ve crunched the numbers. x = 6, y = 4. Honestly, I could do this in my sleep. Final Result: {x: 6, y: 4}

---

⚡ Power Commands

Riley includes a local regex router that intercepts commands before they reach the LLM, saving tokens and execution time:

Command	Description
/multi	Activates multi-line input mode. Paste large blocks of text/code, and type /send on a new line to submit.
/set_api_key <key>	Securely updates your Gemini API key in the OS keyring and dynamically swaps the provider to Google. If run without a key, it prompts for secure hidden input.
/calculate <expr>	Bypasses the LLM router and forces the SymPy calculator tool to run directly on the expression.
/web_search <query>	Bypasses the LLM router and forces the Web RAG pipeline to search and rank chunks for the query.
exit / quit	Triggers a sarcastic parting shot and cleanly exits the application.

---

📂 Project Structure

riley-ai/
├── src/
│   └── riley/
│       ├── __init__.py              # Enables package imports.
│       ├── smart_chatbot.py         # CLI entry point and UI loop.
│       ├── chatsession.py           # Logic for history and tool loops.
│       ├── style.py                 # UI themes and console styling.
│       ├── config/
│       │   ├── __init__.py          # Enables config sub-package.
│       │   └── model_config.py      # Settings and API key management.
│       ├── provider/
│       │   ├── __init__.py          # Enables provider sub-package.
│       │   ├── base_provider.py     # Base LLM interface and telemetry.
│       │   ├── google_provider.py   # Google Gemini integration.
│       │   └── ollama_provider.py   # Local Ollama fallback.
│       └── tools/
│           ├── __init__.py          # Enables tools sub-package.
│           ├── calculator.py        # Symbolic math engine.
│           └── web_scraper.py       # Concurrent web RAG pipeline.
├── tests/
│   ├── __init__.py                  # Enables test discovery.
│   ├── test_core.py                 # Core functional unit tests.
│   └── benchmark_scraper.py         # Scraper performance benchmarks.
└── pyproject.toml                   # Project metadata and dependencies.

---

🧪 Testing & Benchmarking

To ensure system stability and verify concurrency performance on your hardware, run the included test suite:

Run Core Unit Tests:

uv run python -m unittest tests.test_core

Run Web RAG Concurrency Benchmark:

uv run python -m unittest tests.benchmark_scraper

---

📜 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 before I speak." — Riley