# Postlight

**"Chat with your mailbox — private, local-first."**

A Gmail-style labels mail client with local LLM integration (Ollama) for semantic search and chat capabilities. Privacy-focused with local-first architecture and optional remote LLM endpoints.

📖 **New Users**: See [USER_GUIDE.md](USER_GUIDE.md) for installation instructions and feature documentation.

## Features

- **IMAP/SMTP Sync**: Full email synchronization with threading support
- **Labels (Gmail-style)**: Organize emails with flexible labels
- **Hybrid Search**: Combined FTS5 and vector similarity search
- **AI Summaries**: Automatic message and thread summaries
- **Semantic Search**: Vector-based search using embeddings
- **Chat with Mailbox**: Natural language interface to your emails
- **Privacy-First**: Local LLM by default, optional remote endpoints
- **Local Storage**: SQLite with FTS5 and vector search

## Tech Stack

- **Backend/Core:** Rust (IMAP/SMTP sync, MIME parsing, threading, indexing, search)
- **Storage:** SQLite with FTS5 and sqlite-vec for vector search
- **UI:** Tauri + React (TypeScript)
- **Runtime:** Tokio async runtime
- **LLM:** Ollama (local default) or OpenAI-compatible endpoints (BYOK)

## Build & Run

### Prerequisites

- Rust stable (latest)
- Node.js & pnpm
- Ollama (optional, for local LLM)

### Development

```bash
# Install dependencies
pnpm install

# Run development server
pnpm tauri dev

# Build for production
pnpm tauri build
```

### Nix Build

```bash
# Build with Nix (requires --option sandbox false for pnpm network access)
nix build --option sandbox false

# Run the built binary
./result/bin/postlight-ui

# Install to user profile
nix profile install . --option sandbox false
```

### Rust Tests

```bash
# Run all tests
cargo test

# Run specific crate tests
cargo test -p postlight-storage
cargo test -p postlight-search
```

## Configuration

Create `~/.postlight/config.toml`:

```toml
[profile]
db_path = "/home/user/.postlight/profile.db"
encrypt = false

[index]
batch_size = 64
pause_on_battery = true

[models]
provider = "ollama"                 # "openai", "custom"
chat_model = "llama3.1:8b-instruct"
embed_model = "nomic-embed-text"

[providers.openai]
base_url = "https://api.openai-compatible.example/v1"
api_key_cmd = "secret-tool lookup postlight openai_key"
```

## Architecture

### Data Flow

1. **IMAP Sync** → store raw RFC822 + parsed fields → thread mapping
2. **Indexing Pipeline** → FTS5 insert → LLM summarization → embedding generation → tag suggestions → todo/meeting extraction
3. **Search/Chat** → hybrid ranker (FTS+vector+recency) → message/thread fetch → citations

### Storage Model (SQLite)

- One database file per profile
- Core tables: `accounts`, `threads`, `messages`, `labels`, `message_labels`
- FTS: `messages_fts` (virtual table using FTS5)
- Vectors: `embeddings` table with sqlite-vec for semantic search
- AI data: `ai_notes` for summaries, todos, entities

### Threading Algorithm

- Primary: `Message-ID`, `In-Reply-To`, `References` headers
- Fallback: subject normalization + time proximity

### LLM Integration

**Tool API for "Chat with Mailbox"**:
- `search_messages`: Query with filters (tags, from/to/cc, date range)
- `get_thread`: Fetch thread bundle by ID
- `open_message`: Return sanitized plaintext
- `apply_labels`: Batch label operations
- `draft_reply`: Generate reply draft with LLM

## Privacy & Security

- **Local-first:** No data leaves device unless user opts in to remote LLM
- **Optional PII redaction** before remote calls (emails, phones, IBANs, BTC addresses, order IDs)
- Credentials stored in OS keyring (not database)
- Optional database encryption with SQLCipher
- No telemetry by default

## Performance Targets

- First paint ≤ 2s
- Inbox list (5k threads) ≤ 150ms after DB warm
- IDLE-triggered new mail → visible snippet ≤ 2s; summary ≤ 10s
- Hybrid search (100k messages) ≤ 300ms (warm cache)

## Development Roadmap

**M1 – Mail Core** ✅ COMPLETE: IMAP/SMTP, threads, labels, FTS search, inbox UI, compose, archive/delete

**M2 – AI Indexing** ✅ COMPLETE: Ollama hookup, per-message summary & thread brief, embeddings, hybrid search

**M3 – Chat with Mailbox** ✅ COMPLETE: Tool-calling + side drawer; citations to messages; tag suggest + confirm

**M4 – Polish & Packaging** ✅ COMPLETE: Pause/resume indexing, battery-aware throttle, Flatpak + Nix Flake, docs

**M5 – Knowledge Graph UI** ✅ COMPLETE: Knowledge sidebar, entity/concept chips, detail pages, interactive graph viewer

### Recent M5 Features

- **Knowledge Sidebar**: Top entities and concepts with Entities/Concepts toggle
- **Entity Chips**: Clickable entity chips in messages (color-coded by type: person, company, project)
- **Concept Tags**: Clickable concept tags in messages
- **Entity Detail Page**: Shows relationships, evidence messages, and metadata
- **Concept Detail Page**: Shows related entities and connected messages
- **Interactive Graph Viewer**: Full-screen Cytoscape.js visualization with zoom, pan, filtering, and clickable nodes

## License

MPL-2.0

## Contributing

Contributions welcome! Please open an issue or PR.