riley-ai 0.3.0

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.

---

✨ What’s New in v0.3.0?

• 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: Now 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: New /multi mode and /send command for handling large data pastes in the terminal.
• Enhanced Dependency Management: Fully optimized for uv 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

For Users (via PyPI)

Install Riley globally on your system:

pip install riley-ai

For Developers (via Source)

This project is optimized for the uv package manager:

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

---

🛠 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 Agent Scratchpad.

User: "What are the key features of the upcoming Python 3.14 release?"

Riley: 🧠 [Agent Scratchpad]: Searching for Python 3.14 PEPs and release schedules. "I dug through the latest dev docs so you didn't have to. Python 3.14 is bringing PEP 735 (dependency groups). It’s expected around October 2025."

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."

---

⚡ Power Commands

Command	Action	Use Case
riley	Launch	Standard interaction mode.
/calculate	Trigger SymPy	Bypass the LLM to solve equations or word problems directly.
/web_search	Trigger Live RAG	Bypass the LLM to pull real-time, top-ranked web chunks.
/multi	Multi-line Mode	Paste large code blocks safely (type /send to submit).
exit	Quit	Saves session history to your local config folder and exits cleanly.

---

📂 Project Structure

src/riley/
├── smart_chatbot.py   # CLI entry point & Regex Router
├── chatsession.py     # The Orchestrator (The "Loop" & LLM Bypass)
├── config/            # Pydantic Settings & Model Definitions
├── provider/          # Gemini & Ollama API implementations
└── tools/             # RAG Pipeline & SymPy Logic

---

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