Metadata-Version: 2.4
Name: grove-chat
Version: 0.2.0
Summary: Branching conversations for local LLMs via Ollama
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ollama>=0.6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.29.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: requests>=2.31.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Dynamic: license-file

# 🌿 Grove

Ever gone down a rabbit hole with your local LLM, only to lose your original train of thought? Grove fixes that.

Grove is a CLI chat tool for Ollama that lets you **branch conversations** — explore a tangent, then return to your main thread exactly where you left off, with no context bleed.

Think of it like Git, but for your chats.

---

## The problem

Normal LLM chats are linear. Every tangent you explore gets mixed into the same context window. Ask about transformers, go deep on attention mechanisms, come back — and the model is now confused about what you were originally talking about.

Grove calls this **context poisoning**. Branching is the fix.

---

## How it works

```
branch: main
you: explain how transformers work in ML
grove: Transformers use self-attention...

you: /branch attention
Branched into: attention

branch: main > attention
you: go deeper on self-attention specifically
grove: Self-attention allows the model to weigh...

you: /main
Jumped to: main

branch: main
you: how do transformers compare to RNNs?
grove: Unlike RNNs which process tokens sequentially...
```

The model answering that last question has **no idea** the attention branch ever happened. Clean context, every time.

---

## Requirements

- Python 3.10+
- [Ollama](https://ollama.com) installed and running
- At least one model pulled — `ollama pull mistral` is a good start

---

## Install

```bash
pip install grove-chat
```

---

## Quickstart

```bash
# make sure Ollama is running
ollama serve

# start grove
grove
```

Grove will ask you to pick a model and a session, then you're chatting.

---

## Commands

| Command | Description |
|---|---|
| `/branch [name]` | Fork a new branch from current context |
| `/switch <name>` | Switch into an existing branch |
| `/parent` | Go up one level |
| `/main` | Jump straight back to the root |
| `/branches` | List branches from current node |
| `/tree` | Show the full conversation tree |
| `/merge` | Summarize this branch and inject into parent |
| `/discard` | Drop this branch and return to parent |
| `/session list` | List all saved sessions |
| `/session new <name>` | Start a new named session |
| `/session load <name>` | Resume a past session |
| `/session delete <name>` | Delete a session |
| `/model` | Switch Ollama model mid-conversation |
| `/help` | Show help |
| `/quit` | Save and exit |

---

## Sessions

Grove saves everything to `~/.grove/grove.db` — a local SQLite file. Sessions survive restarts. Pick up exactly where you left off.

```
🌿 Grove — branching conversations for local LLMs

Available models:
  [1] mistral:latest
  [2] llama3.2:3b
Pick a model (1): 1

Saved sessions:
  [1] ml-research (last used 2026-04-12)
  [2] work-project (last used 2026-04-10)
  [n] New session
Pick a session (1):
```

---

## API

Grove also ships with a local REST API — useful if you want to build a web UI, integrate with other tools, or just script your conversations.

```bash
grove-serve
# API running at http://localhost:7337
# Docs at http://localhost:7337/docs
```

Key endpoints:

```
GET  /sessions                      list sessions
POST /sessions                      create a session
POST /chat                          send a message
POST /chat/stream                   streaming response
POST /branch                        fork a branch
POST /merge                         merge branch into parent
GET  /sessions/{session}/tree       full tree as JSON
GET  /models                        list available Ollama models
```

Full interactive docs at `http://localhost:7337/docs` once the server is running.

---

## Why Ollama?

[Ollama](https://ollama.com) is the easiest way to run LLMs locally — one command to install, one command to pull a model, and you're running Mistral, Llama, Gemma, DeepSeek or dozens of others entirely on your own hardware. No API keys, no cloud, no cost per token.

Grove is built on top of Ollama and works with any model you've pulled.

```bash
ollama pull mistral       # fast, great for most tasks
ollama pull llama3.2:3b   # lighter, good for slower machines
ollama pull deepseek-r1   # strong reasoning
```

---

## License

MIT
