generate_rarity
Distribute items across rarity tiers with defined probabilities and optional minimum guarantees. Input item count, tiers, percentages, and salt for entropy. Used in games, finance, and testing.
Instructions
Rarity Distributor Args: item_count: Number of items rarity_tiers: Array of rarity tiers rarity_percentages: Probability percentage for each rarity tier guaranteed_minimums: Minimum guaranteed count for each rarity tier (optional) salt: Additional entropy source
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| guaranteed_minimums | No | ||
| item_count | Yes | ||
| rarity_percentages | Yes | ||
| rarity_tiers | Yes | ||
| salt | No |
Implementation Reference
- main.py:300-310 (handler)Handler function for the 'generate_rarity' tool, registered via @mcp.tool(). Delegates execution to the rarity_distributor helper.
@mcp.tool() async def generate_rarity(item_count: int, rarity_tiers: List[str], rarity_percentages: List[float], guaranteed_minimums: Optional[List[int]] = None, salt: str="") -> str: """Rarity Distributor Args: item_count: Number of items rarity_tiers: Array of rarity tiers rarity_percentages: Probability percentage for each rarity tier guaranteed_minimums: Minimum guaranteed count for each rarity tier (optional) salt: Additional entropy source """ return await rarity_distributor(item_count, rarity_tiers, rarity_percentages, guaranteed_minimums, salt) - utils.py:585-661 (helper)Core helper function implementing the rarity distribution logic using blockchain-derived random seeds and numpy for probabilistic assignments, handling guaranteed minimums and percentage-based distribution.
async def rarity_distributor(item_count: int, rarity_tiers: List[str], rarity_percentages: List[float], guaranteed_minimums: Optional[List[int]] = None, salt: str="") -> Dict: """ Rarity distributor Distribute items across rarity tiers based on specified percentages Args: item_count: Total number of items rarity_tiers: List of rarity tier names rarity_percentages: Percentage for each rarity tier guaranteed_minimums: Minimum guaranteed items per tier salt: Optional salt value for additional randomness Returns: Dict containing rarity assignments and tier counts """ if len(rarity_tiers) != len(rarity_percentages): raise ValueError("Tiers and percentages must have the same length") if guaranteed_minimums and len(guaranteed_minimums) != len(rarity_tiers): raise ValueError("Guaranteed minimums must match tiers length if provided") random_num = await get_random_str() if not random_num: return {"error": "Failed to get random number"} request_id = generate_request_id(random_num) seed = _derive_seed(request_id, salt) np.random.seed(seed) # Initialize guaranteed minimums tier_counts = {tier: 0 for tier in rarity_tiers} assignments = [""] * item_count remaining_items = item_count # Handle guaranteed minimums if guaranteed_minimums: for i, tier in enumerate(rarity_tiers): min_count = guaranteed_minimums[i] if min_count > 0: # Randomly assign guaranteed minimums indices = np.random.choice( [i for i, a in enumerate(assignments) if a == ""], size=min(min_count, remaining_items), replace=False ) for idx in indices: assignments[idx] = tier tier_counts[tier] += 1 remaining_items -= 1 # Handle remaining items if remaining_items > 0: # Normalize percentages percentages = np.array(rarity_percentages, dtype=float) percentages = percentages / np.sum(percentages) # Randomly assign remaining items remaining_indices = [i for i, a in enumerate(assignments) if a == ""] remaining_assignments = np.random.choice( rarity_tiers, size=remaining_items, p=percentages ) for i, idx in enumerate(remaining_indices): tier = remaining_assignments[i] assignments[idx] = tier tier_counts[tier] += 1 result = { "requestId": request_id, "rarityAssignments": assignments, "tierCounts": tier_counts } return result