Metadata-Version: 2.4
Name: riley-ai
Version: 0.3.0
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
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.

---

## ✨ 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**](https://github.com/astral-sh/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:
```bash
pip install riley-ai
```

### For Developers (via Source)
This project is optimized for the `uv` package manager:
```bash
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:
```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 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

```text
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
