Metadata-Version: 2.4
Name: riley-ai
Version: 0.4.1
Summary: Riley: A witty, Agentic AI orchestrator with RAG, web search, and symbolic math tools.
License: GPL-3.0-only
Project-URL: Homepage, https://codeberg.org/ChocolatePastry/riley-ai
Project-URL: Bug Tracker, https://codeberg.org/ChocolatePastry/riley-ai/issues
Keywords: ai,agent,orchestrator,rag,gemini,ollama,cli
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Education
Classifier: Topic :: Education
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: Pydantic :: 2
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ddgs>=9.14.1
Requires-Dist: google-genai>=1.73.1
Requires-Dist: ollama>=0.6.1
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: requests>=2.33.1
Requires-Dist: sentence-transformers>=5.4.1
Requires-Dist: sympy>=1.14.0
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: rich>=15.0.0
Dynamic: license-file

# 🤖 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:
```bash
uv tool install riley-ai
```

**Upgrading via uv:**
```bash
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:
```bash
pip install riley-ai
```

### For Developers (via Source)
This project is optimized for the `uv` package manager. To work on the codebase directly:
```bash
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](https://docs.astral.sh/uv/)
* **Ollama (Local AI Fallback):** Essential for running models completely offline.
    * *Windows/macOS:* Download directly from [Ollama's Website](https://ollama.com).
    * *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](https://docs.searxng.org/admin/installation-docker.html) to spin up your local instance.

---

## 🛠 Usage & Examples

### Starting Riley
Run the following command to start the orchestrator:
```bash
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."*
