---
# nuzlocke-tracker-c6ly
title: Build name suggestion engine
status: completed
type: task
priority: normal
created_at: 2026-02-11T15:56:44Z
updated_at: 2026-02-11T20:44:27Z
parent: nuzlocke-tracker-igl3
blocking:
    - nuzlocke-tracker-bi4e
---

Build the backend service and API endpoint that picks random name suggestions from the dictionary based on a selected naming scheme.

## Requirements

- Given a category and a run ID, return 5-10 unique suggestions
- The engine queries the run's existing encounter nicknames and excludes them from suggestions
- Support regeneration (return a fresh batch, avoiding previously shown suggestions where possible)
- Handle edge case where category is nearly exhausted gracefully (return fewer suggestions)

## Implementation Notes

- **Backend service**: A Python module that loads the dictionary JSON, filters by category, excludes used names, and picks random suggestions.
- **API endpoint**: `GET /api/v1/runs/{run_id}/name-suggestions?count=10` — reads the run's `naming_scheme`, fetches encounter nicknames, returns suggestions.
- **No new DB tables needed**: Used names come from `Encounter.nickname` on the run's encounters.
- **Caching**: Load the dictionary once and cache in memory (it's static data).

## Checklist

- [x] Create a service module for name suggestion logic (e.g. `services/name_suggestions.py`)
- [x] Implement dictionary loading with in-memory caching
- [x] Implement random selection from a category with exclusion of used names
- [x] Add API endpoint for fetching suggestions
- [x] Add unit tests for the suggestion logic