---
name: library-search
description: This skill should be used when the user asks to "find a game", "search my steam library", "what should I play", "recommend a game", "find similar games", "what's like X", "my unplayed games", "my backlog", "short games to play", "games under N hours", "games I haven't played", "what have I been playing", "stats on my library", or wants to query their owned Steam games. Also use when the user mentions "steam", "my library", "my games", "my backlog", "playtime", "hltb", "howlongtobeat", or asks for game recommendations rooted in what they already own. The library is enriched with Steam appdetails, SteamSpy tags + estimated owners, HowLongToBeat completion times, and Steam's own "more like this" graph, with hybrid keyword + semantic vector search.
---

# Steam Library Search & Recommendations

Self-hosted REST API over a Postgres + pgvector database of the user's owned
games (~thousands of titles, primarily Steam — Epic and GOG ownership are
also tracked when the same title exists on Steam, see "Multi-platform" below).
Each game is enriched with:

- **Steam appdetails** — descriptions, genres, categories, developers, publishers, metacritic score, platforms (windows/mac/linux), controller support, release date, price
- **SteamSpy** — estimated owner range, positive/negative review counts, average/median playtime, peak concurrent users, **user tags with vote counts** (the highest-signal signal for vibe queries)
- **HowLongToBeat** — completion times for main story, main+extras, completionist
- **"More like this" graph** — Steam's own per-game recommendation list, scraped from the store page
- **Embeddings** — 768-dim vectors over `name + top-15 tags + short_description`. Default model is `nomic-embed-text` via Ollama, but the AI helper supports any OpenAI-compatible provider (`AI_BASE_URL` env).
- **YouTube videos** — top ~10 walkthroughs / let's-plays / trailers per game, surfaced on `/games/:appid` (seed runs ~100 games/day until Google's 10k-unit daily quota; newest games processed first)

Search is hybrid: keyword FTS + vector cosine similarity, blended via weighted
sum. Filters (playtime, genre, tag) apply as SQL `WHERE` on the same row.

Call `/stats` to see how many games are synced/enriched/embedded.

## API Base URL

`http://localhost:3110`

## Endpoints

### Search & Browse

| Endpoint | Description |
|---|---|
| `GET /library?q=&tag=&genre=&platform=&min_playtime=&max_playtime=&unplayed=1&limit=50&offset=0&sort=` | Hybrid search across the library; each result has a `platforms` array |
| `GET /games/:appid` | Full record + tags + similar graph + per-platform `ownership` + `videos` |
| `POST /games/:appid/refresh` | Manually re-fetch every external source (YouTube etc.); returns per-source result map |
| `GET /similar?appid=&q=&platform=&max_playtime=&min_positive_pct=&limit=20` | Vector-similarity recs |
| `GET /stats` | DB stats — total, per-platform breakdown (`platforms.steam` etc.), `multi_platform` overlap count, enriched/embedded/played/unplayed, last sync |

### MCP

| Endpoint | Description |
|---|---|
| `GET /mcp` | Public discovery |
| `POST /mcp` | JSON-RPC 2.0 (open locally; OAuth at the proxy layer in `D:\code\expose-tunnels\`) |

### Library / Search

```
GET /library?q=<text>&tag=&genre=&platform=&min_playtime=&max_playtime=&unplayed=1&limit=50&offset=0&sort=name
```

Returns owned games (every row in the library is owned via at least one
storefront). All params optional and combinable:

- `q` — free-text query. Triggers **hybrid search** (60% vector + 40% FTS rank) when Ollama is configured. Falls back to FTS-only otherwise. Without `q`, sorted alphabetically.
- `tag` — SteamSpy user tag, partial match (e.g. `tag=Roguelike`, `tag=Cozy`)
- `genre` — Steam genre, exact match (e.g. `genre=Indie`)
- `platform` — restrict to a specific storefront: `steam`, `epic`, or `gog`
- `min_playtime` / `max_playtime` — bounds in **minutes**
- `unplayed=1` — only games with `playtime_min = 0`
- `sort=name|relevance` — defaults to `relevance` when `q` is set, `name` otherwise
- `limit` / `offset` — pagination

Each result row: `appid, name, type, short_desc, header_image, release_date, genres, categories, playtime_min, playtime_2wk, last_played, positive, negative, owners_estimate, hltb_main, hltb_extra, metacritic, platforms` (an array like `["steam", "epic"]`).

### Game detail

```
GET /games/:appid
```

Returns the full enriched record plus:
- `platforms` — array like `["steam", "epic", "gog"]`
- `ownership` — per-platform rows with `{platform, external_id, title_at_source, acquired_at, playtime_min, last_played}` — exposes per-store metadata
- `tags` — array of `{tag, votes}` from SteamSpy, sorted by vote count desc
- `similar` — array of `{appid, rank, name, header_image}` from Steam's "more like this" carousel
- `videos` — array of `{video_id, title, channel, channel_id, description, thumbnail_url, published_at, rank}` discovered via the YouTube Data API (gameplay / walkthrough / let's-play / trailer mix). Empty if `youtube_fetched_at` is null on this game.

### Similar / Recommendations

```
GET /similar?appid=<seed>           — recommend by vector cosine to seed game
GET /similar?q=<text>                — recommend by free-text query embedding
```

Required: one of `appid` or `q`. All recommendations are pulled from the
owned library (everything in `games` is owned). Optional filters:

- `platform` — restrict to `steam` / `epic` / `gog`
- `max_playtime=<minutes>` — cap on user playtime (e.g. `max_playtime=600` = under 10h played)
- `min_positive_pct=<0-100>` — minimum review positivity
- `limit` (default 20)

Each result row also includes `similarity` (0..1) — higher is more similar.

**`appid` is preferred over `q`** when the user names a specific game — it's
more accurate. Pass `q` for vibe queries like "cozy puzzle game with story".

### Stats

```
GET /stats
```

Returns:
- `total` — total games in the library (every row is owned via at least one storefront)
- `platforms` — per-storefront counts, e.g. `{steam: 2135, epic: 321, gog: 36}`
- `multi_platform` — number of games owned on more than one storefront
- `enriched` — have appdetails fetched
- `embedded` — have Ollama vector
- `played` / `unplayed` — `playtime_min > 0` / `= 0`
- `total_playtime_min` — sum across all
- `meta[]` — bookkeeping (e.g. `last_sync`)

## Common workflows

**"What should I play?"** — `GET /library?unplayed=1&limit=50` then filter by mood/length. Or `GET /library?q=cozy short&unplayed=1`.

**"What's like Hades?"** — find the appid first via `GET /library?q=hades&limit=1`, then `GET /similar?appid=<id>` to get owned-library recommendations.

**"What do I own on GOG?"** — `GET /library?platform=gog&limit=100`.

**"Do I own Wolfenstein TNO anywhere?"** — find the appid (`GET /library?q=Wolfenstein+New+Order&limit=1`), then `GET /games/:appid` and read the `platforms` array.

**"What have I been playing?"** — `GET /library?min_playtime=1` and sort client-side by `playtime_2wk` desc.

**"How long is X?"** — `GET /games/:appid` → look at `hltb_main`, `hltb_extra`, `hltb_complete` (hours).

**"Quick games?"** — `GET /library?unplayed=1` then filter results where `hltb_main <= 10`.

**"Show me a walkthrough / trailer for X"** — `GET /games/:appid` → use the `videos` array (already fetched if `youtube_fetched_at` is set; otherwise `POST /games/:appid/refresh` to fetch it now).

**"Refresh data on X"** — `POST /games/:appid/refresh`. Re-fetches every configured external source. Per-source status returns in `sources.<name>.status` (`ok` / `rate_limited` / `error` / `disabled`).

## Multi-platform ownership

Steam appid is the canonical ID. The `platform_ownership` table records which
storefronts own each appid (`steam`, `epic`, `gog`). A game can have multiple
rows — e.g. owned on both Steam and Epic. Games that exist only on Epic/GOG
and not on Steam are **not** in the library (they can't be matched to an
appid, so they're dropped). This is intentional: Steam is the source of truth.

`/library` and `/similar` results include a `platforms` array per row.
`/games/:appid` includes both `platforms` and a richer `ownership` array with
per-store metadata (`external_id`, `title_at_source`, `acquired_at`,
`playtime_min`, `last_played`). Use the `?platform=<store>` filter on
`/library` and `/similar` to scope to a single storefront.

## Notes

- The library refreshes daily at 06:00 via the `syncer` cron. Trigger `POST /sync` after a recent purchase if you want immediate visibility.
- Epic/GOG ownership is synced on the host with `bun run sync:epic` / `sync:gog` (manual, browser-auth required once).
- Enrichment runs every 15 minutes in batches of 50; for ~3000 games this takes several hours from cold start. `GET /stats` shows progress.
- YouTube video discovery runs daily at 06:30 UTC, ~100 games/day until quota; newest games first. Full library seed takes ~24 days at the floor.
- The AI provider must have an embedding model loaded (default `nomic-embed-text` via Ollama; any OpenAI-compatible provider works via env vars). Vector search degrades gracefully to FTS-only if the provider is unreachable.
- The MCP server (7 tools — `search_library`, `find_similar`, `get_game`, `recently_played`, `unplayed_pile`, `get_stats`, `sync_owned`) is exposed publicly via OAuth at `https://steam.share.cool.omg.lol/mcp` (the same `clients.json` as the anna connector). Enrichment, embedding, and video discovery are automatic via cron containers; no manual data-fetch tool is exposed via MCP — for that, use the `/games/:appid/refresh` REST endpoint.