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 · Explore the interfaces · Read the docs

At a glance

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 are required.

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 before installing from PyPI.

2. Prepare a model. For local chat, install Ollama, start its service, and pull Riley's default model:

ollama pull qwen3.5:9b

Want Gemini instead? Get a key and add it through uv run riley --cli. The setup guide walks through it.

3. Start chatting.

uv run riley

Open 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

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:

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 for streaming, history, every CLI command, and exact request shapes.

How a message moves

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 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 explains prerequisites, local files, optional SearXNG, and common startup problems.

Documentation

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:

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 for the main extension points.

License

Riley is licensed under the GNU General Public License v3.