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

```bash
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:

```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 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](https://ollama.com).
* *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](https://docs.searxng.org/admin/installation-docker.html) to spin up your local instance on `127.0.0.1:8888`.



---

## 🛠 Usage & Examples

Start the orchestrator by simply typing:

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

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

```bash
uv run python -m unittest tests.test_core

```

**Run Web RAG Concurrency Benchmark:**

```bash
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*
