> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Competitor Scores

<Note>
  **Internal Service** — This is not an HTTP endpoint. It's called by the ranking-score route.
</Note>

## Purpose

Generates 4 fake competitor scores that are displayed alongside the user's score. Creates the impression of a competitive landscape.

## Function Signature

```python theme={null}
def generate_competitor_scores(user_score: int) -> List[int]
```

## Parameters

| Parameter    | Type  | Description              |
| ------------ | ----- | ------------------------ |
| `user_score` | `int` | The user's ranking score |

## Returns

`List[int]` - 4 competitor scores, sorted descending (highest first)

## Rules

| Rule                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| **Ranking**          | 50% chance user ranks 5th (all 4 higher), 50% chance user ranks 4th |
| **Max score**        | No score exceeds 86                                                 |
| **Uniqueness**       | All scores must be unique                                           |
| **Close competitor** | One competitor is always within 2-4 points of user                  |

## Example Output

For a user score of 38:

```json theme={null}
{
  "score": 38,
  "competitor_scores": [72, 65, 58, 42]
}
```

The user sees: "You rank #5 out of 5 competitors"

## Why This Design?

1. **Close competitor** - Shows the user they're "almost" beating someone
2. **Higher scores** - Creates urgency ("competitors are ahead")
3. **Sorted descending** - Easy to display as a leaderboard
4. **Randomized ranking** - Some users rank 4th (hope), some rank 5th (urgency)

## Code Location

```
src/website/ranking_score/routes.py
# Lines 49-129: generate_competitor_scores()
```