# About debshots

Debshots is a web application written in Ruby-on-Rails that powers the
screenshots.debian.net web site. Many services like packages.debian.net,
Ubuntu Software or Synaptic rely on it.

## State of the application

The code you find here resembles the version that is deployed to
screenshots.debian.net. It has been refactored in 06/2024 to Rails 7.
If you find strange or changed behavior please open an issue at
https://salsa.debian.org/debian/debshots/-/issues

## Development

Check out the doc/README.Development.md

## Package search

The package search combines several strategies, tried in this order:

1. **Exact package name**: Searching for `vim` shows exactly this
   package without calling any external service.
2. **Name prefix matches**: Packages whose name starts with the query
   rank first, e.g. searching for `sqlite` promotes `sqlite3`,
   `sqlitebrowser` and friends above all other results.
3. **Compound word splitting**: Packages whose name contains *all*
   query tokens match too, so `sqlite browser` finds `sqlitebrowser`.
4. **Semantic search**: The query is embedded via the vector service
   (all-MiniLM-L6-v2, 384 dimensions) and the nearest neighbors among
   the package description embeddings are returned, using the pgvector
   extension with an HNSW cosine index. Embeddings are computed from
   the package description and long description and can be (re-)built
   with `bin/rails debshots:compute_vectors`.
5. **Full-text fallback**: If the vector service cannot be reached,
   classic PostgreSQL full-text search takes over.

Queries that share no vocabulary with the package data (gibberish,
keyboard mash) return an honest empty result instead of random
semantic matches.

**Why is this package in my results?** Each result knows which search
strategy produced it. The controller exposes this as
`@search_sources` (a hash mapping package ids to `:exact`,
`:name_prefix`, `:name_contains`, `:semantic` or `:fulltext`). For
debugging you can render a small badge on every result card by adding
`show_sources=1` to the URL, e.g.
`https://screenshots.debian.net/packages?search=sqlite&show_sources=1`.

Package pages also show semantically **related packages**, computed as
a nearest neighbor query against the package's own description
embedding - no external service call involved.

## Deployment

Read the doc/README.Installation.md