# Zen Prompt

Aesthetic inspiration for your shell.

<img src="docs/photos/zen-prompt.png" alt="drawing" width="600"/>

## Features

- **Shell Inspiration First**: Instantly generate aesthetic quote prompts with `zen-prompt random`, using quotes collected from Goodreads and optional photo layouts for a more atmospheric terminal experience.
- **Resumable Crawling**: Collect more quotes from Goodreads over time and resume from the last processed page for each tag.
- **Quote Statistics**: Explore the collection later with database statistics and exports once your cache grows.


## Tech Stack

- **Python 3.13+**
- **[uv](https://github.com/astral-sh/uv)**: Dependency management and project isolation.
- **Scrapy**: High-level crawling and scraping.
- **SQLite**: Local persistence and state management.
- **Typer**: CLI command parsing.
- **textual-image**: Terminal image rendering for photo-backed quote output.
- **Pydantic**: Data validation.

## Setup

Install the lightweight runtime by default:

```bash
pip install zen-prompt
```

This installs the `zen-prompt` command-line tool with the runtime features needed for:

- `random`
- `sync`
- `history`
- `profile`
- `search`
- `get`
- `stat`
- `distill`
- `export`

If you also want crawling support, install the full extra:

```bash
pip install "zen-prompt[all]"
```

The `all` extra adds the crawler stack used by `zen-prompt crawl`.

For local development installs with `pipx`, use the helper script:

```bash
# Lightweight install
scripts/install-local

# Full install with crawl support
scripts/install-local full
```


## Usage

After installation, you can use the `zen-prompt` command directly.

### Random Inspiration

Start with the main experience: generate quotes collected from Goodreads directly in your shell.

Tip: add `zen-prompt random` to your shell startup file so each new terminal session opens with a fresh quote.

```bash
# zsh
echo 'zen-prompt random' >> ~/.zshrc

# bash
echo 'zen-prompt random' >> ~/.bashrc
```

```bash
# Get a random quote with the default monochrome photo
zen-prompt random

# Disable the default photo
zen-prompt random --no-photo

# Pick only shorter quotes
zen-prompt random --quote-max-words 20 --quote-max-chars 140

# Pick a random hero photo from a topic
zen-prompt random --photo topic@monochrome

# Control image size in the terminal
zen-prompt random --photo topic@monochrome --photo-max-height 10 --photo-max-width 80

# Render photo and quote side by side
zen-prompt random --photo topic@monochrome --photo-layout table

# Wrap long quotes to a fixed width
zen-prompt random --quote-width 60

# Reuse a fixed image for every quote
zen-prompt random --photo file@./cover.png
```

Below is an example of a quote with a custom photo

<img src="docs/photos/zen-prompt-with-custom-photo.png" alt="drawing" width="600"/>


### Crawling Later

Build data in stages. The default tags are `inspirational,motivational,buddhism`.

```bash
# 1. Crawl raw quotes
zen-prompt crawl --tags inspirational,life

# 2. Distill raw quotes into a curated database
zen-prompt distill

# 3. Export runtime assets used by random/search/get/stat
zen-prompt export --output-dir ./docs --small-limit 500

# Crawl from a specific Goodreads URL (author, book, etc.)
zen-prompt crawl --url https://www.goodreads.com/author/zen-prompt/123.Author_Name

# Configurable download delay (default 1s)
zen-prompt crawl --download-delay 2.0
```

By default:
- `crawl` writes `docs/data/sqlite/quotes-raw.db`
- `distill` writes `docs/data/sqlite/quotes-distilled.db`
- `export` publishes runtime assets including `docs/data/sqlite/quotes.db`

Package builds only bundle the small runtime database. To fetch the large runtime database after install, run `zen-prompt sync`.

### Quote Statistics Later

Once you have a local cache, inspect the quote database with summary statistics.

```bash
# Print statistics in the terminal
zen-prompt stat

# Save statistics as Markdown
zen-prompt stat --output stats.md
```

### Exporting

Export your collection as optimized web and CLI assets.

```bash
# Export optimized SQLite and JSON files to ./docs
zen-prompt export --output-dir ./docs --small-limit 500
```

This command creates:
- `docs/data/sqlite/quotes.db`: Complete optimized database with FTS5 search.
- `docs/data/sqlite/quotes-small.db`: Small subset (tag: buddhism) for instant availability.
- `docs/data/json/quotes.json` & `docs/data/json/quotes-small.json`: JSON versions of the databases.
- `docs/data/csv/quotes.csv` & `docs/data/csv/quotes-small.csv`: CSV versions of the databases.

### Sync and Search

```bash
# Sync data files (SQLite, CSV, JSON) from the remote static website
zen-prompt sync https://anhldbk.github.io/zen-prompt/data/

# Lightning-fast keyword search using FTS5
zen-prompt search "success and happiness" --limit 3
```

## Development

Install dev tools and the full local verification stack with:

```bash
uv sync --group dev
```

Install the git hook:

```bash
uv run pre-commit install
```

Run the standard local verification flow:

```bash
scripts/check
```

This runs:

- `uv run pre-commit run --all-files`
- `uv run python -m pytest`

## Testing

Run the full suite of unit and integration tests:

```bash
uv run python -m pytest
```

## Project Structure

- `zen-prompt/`: Core package containing models, spider, database logic, and pipelines.
- `scripts/`: Entry point bash scripts.
- `docs/`: Design documents, implementation plans, and exported web assets (`docs/data/`).
- `tests/`: Comprehensive test suite.

---

Vibe coded via **Codex**.
