Metadata-Version: 2.4
Name: riley-ai
Version: 0.6.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: fastapi>=0.115.0
Requires-Dist: filelock>=3.0.0
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: uvicorn>=0.30.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: rich>=15.0.0
Dynamic: license-file

# Riley AI

> One conversation. Three interfaces. Your machine.

Riley connects a local Ollama model or Google Gemini to two practical tools: web research and symbolic math. It keeps one conversation on your machine, streams replies, and lets you choose the interface that fits your workflow.

**[Get started](#start-in-three-steps)** · **[Explore the interfaces](#three-ways-to-chat)** · **[Read the docs](#documentation)**

## At a glance

| | Riley gives you |
| --- | --- |
| **Your model** | Local Ollama by default; Gemini when you add a key to your system keyring |
| **Your interface** | A browser chat, a Rich terminal chat, and a FastAPI HTTP API |
| **Your tools** | SymPy calculations and a search → scrape → rank web pipeline |
| **Your history** | One saved conversation shared by all three interfaces |

Riley is designed for one person running one instance. The API and CLI cannot run at the same time against the same local configuration.

## Start in three steps

**1. Get the current source.** Python 3.12 or newer and [uv](https://docs.astral.sh/uv/getting-started/installation/) are required.

```bash
git clone https://codeberg.org/ChocolatePastry/riley-ai.git
cd riley-ai
uv sync
```

This checkout contains the browser and API described here. The published PyPI 0.5.1 release predates those changes; see [setup](docs/setup.md) before installing from PyPI.

**2. Prepare a model.** For local chat, [install Ollama](https://docs.ollama.com/quickstart), start its service, and pull Riley's default model:

```bash
ollama pull qwen3.5:9b
```

Want Gemini instead? Get a key and add it through `uv run riley --cli`. The [setup guide](docs/setup.md#use-gemini-instead) walks through it.

**3. Start chatting.**

```bash
uv run riley
```

Open [http://127.0.0.1:8000/](http://127.0.0.1:8000/) for the browser chat. Without a stored Gemini key, Riley uses Ollama. The API starts without asking for input.

> **Try it:** Ask a normal question, enter `/calculate 2+2`, or use `/web_search Python 3.14 release notes`. Tool-backed answers depend on your model and available network access.

## Three ways to chat

| Interface | Launch | Best for |
| --- | --- | --- |
| **Browser** | `uv run riley` → [local chat](http://127.0.0.1:8000/) | A visual chat with streamed replies and saved history |
| **Terminal** | `uv run riley --cli` | Keyboard-first chat, token counts, and tool notices |
| **HTTP API** | `uv run riley` → `POST /chat` | Scripts and local integrations |

The server listens on `127.0.0.1:8000` by default. Set its bind address with `--host` and `--port`; for example, `uv run riley --host 127.0.0.1 --port 8080`.

A minimal API request:

```bash
curl -X POST http://127.0.0.1:8000/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"Explain recursion simply"}'
```

The reply is JSON with a `response` field. See [commands and API](docs/commands.md) for streaming, history, every CLI command, and exact request shapes.

## How a message moves

```mermaid
flowchart TD
    Entry["riley · main.py"] --> CLI["CLI"]
    Entry --> API["FastAPI + browser"]
    CLI --> Controller["Shared controller"]
    API --> Controller
    Controller --> Provider["Ollama or Gemini"]
    Controller --> Tools["Math or web search"]
    Controller --> History["Local chat history"]
```

`main.py` chooses the interface. Both interfaces call the same controller, which selects a provider, runs tools when needed, and saves the conversation. The [architecture guide](docs/architecture.md) follows a request through the actual files.

## Built for self-hosting

- **Local by default.** No Gemini key means Riley selects the configured Ollama model. Web search still fetches pages from the network.
- **One conversation.** History lives on disk and is shared between browser, CLI, and API. Riley trims older messages as the context grows.
- **One active instance.** A file lock keeps two Riley processes from using the same configuration at once.
- **Local API.** The server binds to localhost by default and has no built-in authentication. Add access controls before exposing it beyond your machine.

The [setup guide](docs/setup.md) explains prerequisites, local files, optional SearXNG, and common startup problems.

## Documentation

| Guide | Start here when you want to… |
| --- | --- |
| [Setup & prerequisites](docs/setup.md) | Install Riley, Ollama, or Gemini and prepare web search |
| [Commands & API](docs/commands.md) | Find a CLI command, launch flag, or HTTP route |
| [Architecture](docs/architecture.md) | Understand the controller, providers, tools, and history |

Each guide owns the detailed instructions for its topic; this README is the guided tour.

## Develop Riley

From the source checkout used above, run the tests:

```bash
uv run python -m unittest discover -s tests -p 'test_*.py'
```

The separate scraper benchmark fetches live pages and is intentionally outside that test command. See the [architecture guide](docs/architecture.md#where-to-change-things) for the main extension points.

## License

Riley is licensed under the [GNU General Public License v3](LICENSE).
