rivals-api 2.0.0__tar.gz → 3.0.0__tar.gz

{rivals_api-2.0.0 → rivals_api-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivals-api
-Version: 2.0.0
+Version: 3.0.0
 Summary: Multi-source Python client and MCP server for Marvel Rivals player stats
 Project-URL: Homepage, https://github.com/GS-Rionnag/rivals-api
 Project-URL: Repository, https://github.com/GS-Rionnag/rivals-api
@@ -71,7 +71,15 @@ with RivalsClient() as rd:
     hero_season = player.heroes.fetch(season=20)
     all_hero_seasons = player.heroes.fetch(season="all")
     map_stats = player.stats.maps(season=20)
-    match_page = player.matches.fetch(season=20)
+    match_page = player.matches.fetch(limit=20, season=20)
+    all_matches = player.matches.fetch(limit="all")
+    combined_rate = player.matches.fetch_win_rate(season=20)
+    print(combined_rate.win_rate_pct, combined_rate.provider_rates)
+    fast_rate = player.matches.fetch_win_rate()
+    exact_rate = player.matches.fetch_win_rate(method="exact")
+    cached_rate = player.matches.fetch_win_rate(method="cached")  # after fetch(limit="all")
+    hero_rates = player.matches.fetch_hero_win_rates(method="exact")
+    class_rates = player.matches.fetch_class_win_rates(method="cached")
 
     # Current match when its provider exposes it; Custom discovery is unsupported.
     live_game = player.live_game.fetch()
@@ -249,8 +257,88 @@ with annotations for fields observed in the API inventory. This includes
 `ProficiencyResponse`, `LeaderboardResponse`, `PunishmentsPage`, `XPPage`,
 `Top500Response`, and typed teammate, crosshair, stats, faction, and insight
 records. For example, `rd.matches.get(match_id)` returns a `Match`,
-`player.matches.fetch()` returns a `MatchHistory`, and
-`player.proficiency.fetch()` returns a `ProficiencyResponse`. Nested match
+`player.matches.fetch(limit=...)` returns a `MatchHistory`. The required limit
+is either a positive number (bounded fetch with a resumable cursor) or
+`"all"` (fetch every available page); both combine and deduplicate providers.
+Each history row is a client-bound `Match`. Call `get_details()` while its
+client is open to lazily fetch combined RivalsData, RivalsTracker, and Tracker.gg
+details, including typed teams, players, and hero segments:
+
+```python
+with RivalsClient(use_browser_fallback=True) as client:
+    player = client.get_player(1970288503)
+    history = player.matches.fetch(limit=20)
+    if history.matches:
+        match = history.matches[0]
+        details = match.get_details()  # Match; the history row stays unchanged
+        for team in details.teams:
+            for participant in team.players:
+                print(participant.name, participant.get("accuracy_percent"))
+        print(details.provider_metadata.errors)
+        # match.get_details(refresh=True) bypasses detail/provider caches.
+```
+
+`client.matches.get(match_id, refresh=False)` uses the same fetcher. Provider
+outages return available details with errors; conflicts and field selections
+remain in `provider_metadata`. `accuracy_percent` uses percent units for players
+and heroes. The legacy RD `accuracy` field remains a player percentage or a
+hero ratio; `session_hit_rate` is separate and is never substituted for accuracy.
+Unknown/NaN accuracy is unavailable. See the
+[match detail guide](docs/PROVIDER_INTEGRATION.md#combined-match-details).
+
+History and detail matches also expose readable typed references. They format
+as names in bot messages; use `.name` for a plain string and `.id` for the
+original identifier. For a match with map ID `1288`, mode `3`, and platform `1`:
+
+```python
+print(match.map)                # Hell's Heaven
+print(match.map.name)           # Hell's Heaven (str)
+print(match.map.id)             # 1288
+print(match.map.location)       # Hydra Charteris Base
+print(match.game_mode)          # Custom
+print(match.gameplay_mode)      # Domination
+print(match.platform)           # PC
+print(match.hero)               # Named Character, when history includes a hero
+print(match.rank)               # Named Rank, when a rank level is available
+print(match.season_info)        # Named Season, when a season is available
+```
+
+These are objects with `__str__`, so `f"Played on {match.map}"` prints the map
+name while `match.map.id` remains available. `game_play_mode` aliases
+`gameplay_mode`. Participants expose `hero`, `top_hero`, `rank_info`, and
+`platform_info`; draft entries expose `hero` and `team`. Existing Character
+records now have `.id`, `.name`, and name-based string formatting.
+
+**Migration:** `match.platform` is now a `Platform` object. Use
+`match.platform_id` or `match.platform.id` for its previous numeric value.
+`to_dict()` serializes references as `{id, name, is_known, source, ...}` objects;
+the original `map_id`, `game_mode_id`, and other numeric fields remain present.
+`.raw` preserves the input payload. The packaged catalogs resolve names
+without additional network requests. Unmapped codes produce an explicit
+`Unknown ...` reference with `is_known=False`; absent fields return `None`.
+See [readable match references](docs/GAME_REFERENCES.md) for mapping sources
+and gameplay-code limits.
+
+The overall, hero, and class win-rate methods accept `method="estimate"` (the
+default), `"exact"`, or `"cached"`. Overall estimates average available
+RivalsData/RivalsTracker competitive rates; hero estimates average each
+provider's per-hero rates; class estimates aggregate provider hero-participation
+counts within each class before averaging provider rates. These estimates are
+fast and approximate, and include provider sample counts. Exact calculations
+traverse all available history pages and deduplicate by match ID. Hero/class
+exact calculations also inspect match details and assign each match to the
+player's longest-played hero, which can require one detail lookup per match.
+Cached calculations make no requests and reuse a prior
+`matches.fetch(limit="all")` in the same Python process, including across client
+instances. If the cached history fetch had provider errors, the calculation
+does not retry missing data; inspect its coverage/errors. Cached hero/class
+rates use cached playtime details when available and otherwise fall back to
+the history row's hero. The returned metadata reports sources, unknown results,
+provider errors, and hero-attribution fallback counts. See the
+[win-rate method guide](docs/PROVIDER_INTEGRATION.md#win-rate-calculation-choices)
+for the assumptions and costs of each method.
+MCP tools expose the same three methods. `player.proficiency.fetch()` returns a
+`ProficiencyResponse`. Nested match
 teams and participants are converted to `MatchTeam` and `MatchPlayer`; embedded
 character records use `Character`. Models support mapping access
 (`player["level"]`) and attribute access (`player.level`). Unknown upstream
@@ -271,6 +359,16 @@ with RivalsClient() as rd:
 
 ## Public resources
 
+For a player selection list, use `rd.search_players("silo")`, or the MCP tool
+`search_players(name="silo")`. Each candidate includes a name and numeric UID;
+pass the selected UID to `get_player_profile(uid=283622404)` for their profile
+overview. `search_player_candidates` remains an alias, and `get_player` still
+accepts a UID or exact name. MCP `search_players` now returns a list instead
+of one resolved account. Live checks on 2026-10-02 confirmed that the
+candidate search includes `siloء` (UID `283622404`) when searching `silo`.
+See [the player-search audit](docs/PLAYER_SEARCH_AUDIT.md) for provider comparisons
+and exact-name versus suggestion behavior.
+
 - `rd.leaderboards.fetch(...)` — global player ranking.
 - `rd.heroes.tier_list(...)`, `.get(hero_id)`, `.meta(hero_id, range=90)`,
   `.leaderboard(hero_id, **filters)` — hero metrics and ranking.
@@ -317,7 +415,7 @@ Existing functions combine public RivalsData, RivalsTracker, and Tracker.gg data
 
 ## Documentation
 
-- [2.0.0 release notes and migration guide](docs/CHANGELOG.md)
+- [Release notes and migration guide](docs/CHANGELOG.md)
 - [Provider integration and data-selection rules](docs/PROVIDER_INTEGRATION.md)
 - [Research findings and unsupported features](docs/PROVIDER_FEATURE_GAPS.md)
 - [RivalsTracker API audit](docs/RIVALSTRACKER_API_AUDIT.md)

{rivals_api-2.0.0 → rivals_api-3.0.0}/README.md

@@ -35,7 +35,15 @@ with RivalsClient() as rd:
     hero_season = player.heroes.fetch(season=20)
     all_hero_seasons = player.heroes.fetch(season="all")
     map_stats = player.stats.maps(season=20)
-    match_page = player.matches.fetch(season=20)
+    match_page = player.matches.fetch(limit=20, season=20)
+    all_matches = player.matches.fetch(limit="all")
+    combined_rate = player.matches.fetch_win_rate(season=20)
+    print(combined_rate.win_rate_pct, combined_rate.provider_rates)
+    fast_rate = player.matches.fetch_win_rate()
+    exact_rate = player.matches.fetch_win_rate(method="exact")
+    cached_rate = player.matches.fetch_win_rate(method="cached")  # after fetch(limit="all")
+    hero_rates = player.matches.fetch_hero_win_rates(method="exact")
+    class_rates = player.matches.fetch_class_win_rates(method="cached")
 
     # Current match when its provider exposes it; Custom discovery is unsupported.
     live_game = player.live_game.fetch()
@@ -213,8 +221,88 @@ with annotations for fields observed in the API inventory. This includes
 `ProficiencyResponse`, `LeaderboardResponse`, `PunishmentsPage`, `XPPage`,
 `Top500Response`, and typed teammate, crosshair, stats, faction, and insight
 records. For example, `rd.matches.get(match_id)` returns a `Match`,
-`player.matches.fetch()` returns a `MatchHistory`, and
-`player.proficiency.fetch()` returns a `ProficiencyResponse`. Nested match
+`player.matches.fetch(limit=...)` returns a `MatchHistory`. The required limit
+is either a positive number (bounded fetch with a resumable cursor) or
+`"all"` (fetch every available page); both combine and deduplicate providers.
+Each history row is a client-bound `Match`. Call `get_details()` while its
+client is open to lazily fetch combined RivalsData, RivalsTracker, and Tracker.gg
+details, including typed teams, players, and hero segments:
+
+```python
+with RivalsClient(use_browser_fallback=True) as client:
+    player = client.get_player(1970288503)
+    history = player.matches.fetch(limit=20)
+    if history.matches:
+        match = history.matches[0]
+        details = match.get_details()  # Match; the history row stays unchanged
+        for team in details.teams:
+            for participant in team.players:
+                print(participant.name, participant.get("accuracy_percent"))
+        print(details.provider_metadata.errors)
+        # match.get_details(refresh=True) bypasses detail/provider caches.
+```
+
+`client.matches.get(match_id, refresh=False)` uses the same fetcher. Provider
+outages return available details with errors; conflicts and field selections
+remain in `provider_metadata`. `accuracy_percent` uses percent units for players
+and heroes. The legacy RD `accuracy` field remains a player percentage or a
+hero ratio; `session_hit_rate` is separate and is never substituted for accuracy.
+Unknown/NaN accuracy is unavailable. See the
+[match detail guide](docs/PROVIDER_INTEGRATION.md#combined-match-details).
+
+History and detail matches also expose readable typed references. They format
+as names in bot messages; use `.name` for a plain string and `.id` for the
+original identifier. For a match with map ID `1288`, mode `3`, and platform `1`:
+
+```python
+print(match.map)                # Hell's Heaven
+print(match.map.name)           # Hell's Heaven (str)
+print(match.map.id)             # 1288
+print(match.map.location)       # Hydra Charteris Base
+print(match.game_mode)          # Custom
+print(match.gameplay_mode)      # Domination
+print(match.platform)           # PC
+print(match.hero)               # Named Character, when history includes a hero
+print(match.rank)               # Named Rank, when a rank level is available
+print(match.season_info)        # Named Season, when a season is available
+```
+
+These are objects with `__str__`, so `f"Played on {match.map}"` prints the map
+name while `match.map.id` remains available. `game_play_mode` aliases
+`gameplay_mode`. Participants expose `hero`, `top_hero`, `rank_info`, and
+`platform_info`; draft entries expose `hero` and `team`. Existing Character
+records now have `.id`, `.name`, and name-based string formatting.
+
+**Migration:** `match.platform` is now a `Platform` object. Use
+`match.platform_id` or `match.platform.id` for its previous numeric value.
+`to_dict()` serializes references as `{id, name, is_known, source, ...}` objects;
+the original `map_id`, `game_mode_id`, and other numeric fields remain present.
+`.raw` preserves the input payload. The packaged catalogs resolve names
+without additional network requests. Unmapped codes produce an explicit
+`Unknown ...` reference with `is_known=False`; absent fields return `None`.
+See [readable match references](docs/GAME_REFERENCES.md) for mapping sources
+and gameplay-code limits.
+
+The overall, hero, and class win-rate methods accept `method="estimate"` (the
+default), `"exact"`, or `"cached"`. Overall estimates average available
+RivalsData/RivalsTracker competitive rates; hero estimates average each
+provider's per-hero rates; class estimates aggregate provider hero-participation
+counts within each class before averaging provider rates. These estimates are
+fast and approximate, and include provider sample counts. Exact calculations
+traverse all available history pages and deduplicate by match ID. Hero/class
+exact calculations also inspect match details and assign each match to the
+player's longest-played hero, which can require one detail lookup per match.
+Cached calculations make no requests and reuse a prior
+`matches.fetch(limit="all")` in the same Python process, including across client
+instances. If the cached history fetch had provider errors, the calculation
+does not retry missing data; inspect its coverage/errors. Cached hero/class
+rates use cached playtime details when available and otherwise fall back to
+the history row's hero. The returned metadata reports sources, unknown results,
+provider errors, and hero-attribution fallback counts. See the
+[win-rate method guide](docs/PROVIDER_INTEGRATION.md#win-rate-calculation-choices)
+for the assumptions and costs of each method.
+MCP tools expose the same three methods. `player.proficiency.fetch()` returns a
+`ProficiencyResponse`. Nested match
 teams and participants are converted to `MatchTeam` and `MatchPlayer`; embedded
 character records use `Character`. Models support mapping access
 (`player["level"]`) and attribute access (`player.level`). Unknown upstream
@@ -235,6 +323,16 @@ with RivalsClient() as rd:
 
 ## Public resources
 
+For a player selection list, use `rd.search_players("silo")`, or the MCP tool
+`search_players(name="silo")`. Each candidate includes a name and numeric UID;
+pass the selected UID to `get_player_profile(uid=283622404)` for their profile
+overview. `search_player_candidates` remains an alias, and `get_player` still
+accepts a UID or exact name. MCP `search_players` now returns a list instead
+of one resolved account. Live checks on 2026-10-02 confirmed that the
+candidate search includes `siloء` (UID `283622404`) when searching `silo`.
+See [the player-search audit](docs/PLAYER_SEARCH_AUDIT.md) for provider comparisons
+and exact-name versus suggestion behavior.
+
 - `rd.leaderboards.fetch(...)` — global player ranking.
 - `rd.heroes.tier_list(...)`, `.get(hero_id)`, `.meta(hero_id, range=90)`,
   `.leaderboard(hero_id, **filters)` — hero metrics and ranking.
@@ -281,7 +379,7 @@ Existing functions combine public RivalsData, RivalsTracker, and Tracker.gg data
 
 ## Documentation
 
-- [2.0.0 release notes and migration guide](docs/CHANGELOG.md)
+- [Release notes and migration guide](docs/CHANGELOG.md)
 - [Provider integration and data-selection rules](docs/PROVIDER_INTEGRATION.md)
 - [Research findings and unsupported features](docs/PROVIDER_FEATURE_GAPS.md)
 - [RivalsTracker API audit](docs/RIVALSTRACKER_API_AUDIT.md)

{rivals_api-2.0.0 → rivals_api-3.0.0}/docs/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 3.0.0 — 2026-10-02
+
+This release changes `match.platform` from a scalar to a typed `Platform`.
+Use `match.platform.id` or `match.platform_id` for the previous numeric value.
+Serialized matches now contain a structured `platform` and readable reference
+objects alongside legacy numeric fields. See `docs/GAME_REFERENCES.md` for
+migration details.
+
+- Added readable typed map, queue, gameplay, platform, rank, season, and hero
+  references to match/history models, including nested participants and draft
+  entries. Names resolve offline; unknown IDs remain explicit. Map 1288 now
+  formats as Hell's Heaven, with its Hydra Charteris Base location accessible.
+  `match.platform` is now a Platform object; use `.platform_id` for its scalar.
+  Serialized responses include structured reference objects alongside legacy IDs.
+- Lazy details retain missing same-match context from their originating history
+  row, with sources recorded in `provider_metadata.history_context`.
+- Added lazy `Match.get_details(refresh=False)` to typed history rows from both
+  providers, bounded/all fetches, and iteration. It returns a new typed full
+  match through the same combined fetcher as `client.matches.get(...)`.
+- Match details preserve raw provider responses, failures, completeness,
+  per-field provenance, and unresolved conflicts. They add provider-only roster
+  entries and hero segments while retaining ambiguous identities separately;
+  responses for a different match are rejected.
+- Separated `session_hit_rate` from accuracy. Added `accuracy_percent` for
+  player/hero percentage access, preserving RD's legacy player-percentage and
+  hero-ratio `accuracy` fields. Unusable accuracy is missing.
+- Scoped shared detail caches by enrichment mode and isolated returned objects.
+  Partial details retry on lookup; `refresh=True` bypasses both detail and
+  provider response caches. MCP `get_match` also accepts `refresh`.
+
+## 2.1.0 — 2026-10-02
+
+- `player.matches.fetch` now requires `limit`: pass a positive integer for a
+  bounded, resumable page of combined history, or `"all"` to traverse all
+  available pages. Results are merged and deduplicated across providers.
+- Added overall, hero, and class win-rate methods to Python and MCP. Each
+  defaults to a quick provider-summary estimate and also supports exact
+  calculations over match history or request-free calculations from full
+  history already cached in the current Python process. Hero/class exact rates
+  attribute matches using the player's longest-played hero from match details,
+  with a summary-hero fallback when detail evidence is unavailable.
+- Match history is shared in a bounded process-level calculation cache so
+  separate client instances can reuse previously fetched full history. Results
+  expose provider coverage, unknown outcomes, and hero attribution fallbacks;
+  exact hero/class calls may require a detail lookup for each match.
+- MCP `search_players(name)` now returns a list of matching players with names
+  and numeric game UIDs instead of automatically resolving one account. Callers
+  must handle list results, including an empty list for no matches.
+- Added MCP `get_player_profile(uid)` to fetch the selected player's overview by
+  numeric UID. `get_player(uid_or_name)` remains available, and
+  `search_player_candidates` is an alias for the list search.
+
 ## 2.0.0 — 2026-10-02
 
 This release changes the project from a RivalsData-only wrapper into **rivals-api**,

rivals_api-3.0.0/docs/GAME_REFERENCES.md

@@ -0,0 +1,91 @@
+# Readable game references
+
+`Match` exposes `map: Map`, `game_mode: GameMode`,
+`gameplay_mode: GameplayMode` (`game_play_mode` is an alias),
+`platform: Platform`, `rank: Rank`, `season_info: Season`, and `hero: Character`.
+Unavailable references are `None`. Printing or formatting a reference uses its
+name; `.name` returns a string, `.id` retains its upstream identifier.
+`Map.location` gives the broader location. `match.winner` references the winning
+`MatchTeam` when known; `match.result` gives Victory, Defeat, or Draw when the
+response establishes it. Team names are neutral Team 1/Team 2 labels; they do
+not claim which side attacked or defended. Match and participant `.id` aliases
+their respective match/game-player identifiers.
+
+`MatchPlayer.hero` uses an explicitly reported hero or top hero, retaining the
+corresponding Character's segment statistics when available. `top_hero`,
+`rank_info`, and `platform_info` resolve their corresponding fields. Draft
+entries have typed `hero` and `team` references. Stats records with `rank_level`,
+`season`, `os`, or `login_os` expose `rank_info`, `season_info`, or
+`platform_info`; player profiles also expose `platform_info`. Numeric fields
+remain available. Account IDs, replay identifiers, party IDs, cosmetic IDs and
+other opaque identifiers are preserved as reported: no established name
+catalog was found for them, and party identifiers are not treated as match
+team camps.
+
+## Serialization and compatibility
+
+References are mapping-compatible models. `match["map"].name` and
+`match.map.name` are equivalent. `to_dict()` recursively serializes references
+into ordinary JSON objects with `id`, `name`, `is_known`, `source`, and any
+type-specific fields. It retains legacy `map_id`, `game_mode_id`,
+`game_play_mode_id`, `season`, `hero_id`, and `rank_level` fields.
+
+`match.platform` now holds a `Platform`; use `.platform_id` or `.platform.id`
+for the original scalar. Serialized matches include both `platform_id` and the
+structured `platform`. `.raw` remains the original input, including numeric
+platform values on responses fetched from providers. Models round-trip through
+`Match(match.to_dict())` without losing labels or nested Character types.
+
+Unknown codes retain their IDs, display `Unknown map`, `Unknown platform`,
+etc., and report `is_known=False`. No label is inferred by truncating a number,
+guessing a future season, or treating every console as PlayStation. Known
+provider labels can resolve a new map even before the packaged catalog changes.
+Names are resolved locally; constructing history references makes no detail or
+metadata requests. `get_details()` also fills missing map/queue/platform/season
+context from the same history match, recording those fields and their sources
+under `provider_metadata.history_context`. Detail values take precedence.
+
+## Catalog evidence (checked 2026-10-02)
+
+The packaged `src/rivals_api/game_catalog.json` contains 118 map variants and
+20 verified season identifiers. It prefers the specific map names from
+[RivalsData's current public match catalog](https://rivalsdata.com/assets/matches-BtVAubcc.js)
+and fills additional variants and location labels from
+[RivalsTracker's public map catalog](https://rivalstracker.com/_nuxt/CUE0zxkU.js).
+For example, `1288` is **Hell's Heaven**, location **Hydra Charteris Base**,
+objective **Domination**; `1245` is **Spider-Islands**, objective **Convoy**.
+Provider-supplied `map_name` / `map_mode_name` values take precedence when usable.
+The catalogs contain provider-maintained labels; resolving a label is not a
+claim that every provider label has been independently verified in-game.
+
+Queue codes `1/2/3/4` mean Quick Match / Competitive / Custom / Arcade. Code 5
+is Tutorial in RivalsTracker; 7 is Practice vs AI; 9/10 are Tournament. Sources
+disagree about code 6: RivalsData labels it **Duel**, RivalsTracker **Practice**.
+The model follows the selected field's provider when available, exposes both
+under `.alternatives`, and reports an unknown name if its source is unestablished.
+See the [RivalsData catalog](https://rivalsdata.com/assets/matches-BtVAubcc.js)
+and [RivalsTracker match UI](https://rivalstracker.com/_nuxt/DDKdWPNg.js).
+
+The raw `game_play_mode_id` has no verified universal objective-name mapping.
+The same code `200` can be returned for different map objectives. Accordingly,
+`GameplayMode.name` comes from the match's `map_mode_name` or its map variant's
+catalog entry. Its `.id` retains the raw gameplay code and `.map_id` records the
+context. Without a known map/objective it stays unknown. It must not be used as
+a global `200 = Convoy` lookup.
+
+Platform codes **1 = PC, 2 = PlayStation, 4 = Xbox** are established by both
+[RivalsData's leaderboard platform options](https://rivalsdata.com/assets/index-B7e1fRs3.js)
+and [RivalsTracker's leaderboard](https://rivalstracker.com/_nuxt/C7pX95rV.js).
+Code 3 is unestablished, so it remains unknown. Platform strings such as `pc`,
+`psn`, and `xbl` retain their original string ID while resolving their name.
+Rank levels and divisions follow the
+[provider rank catalog](https://rivalsdata.com/assets/ranks-D6blxaOO.js), with
+RivalsTracker's observed levels 23–25 labeled One Above All. These are rank
+levels, not hero-stat tier filter IDs, which use a different numbering scheme.
+Season labels follow that same RivalsData catalog and the recorded Tracker
+profile season metadata: internal ID 20 is Season 10, 19 is Season 9.5, and
+1 is Season 0. No future season label is extrapolated.
+
+Catalog updates should verify the current public assets and retain map variant
+keys; several RivalsTracker entries have an inner `ModeID` that differs from
+their dictionary key. The variant dictionary key is the lookup identifier.

rivals_api-3.0.0/docs/PLAYER_SEARCH_AUDIT.md

@@ -0,0 +1,131 @@
+# Player search: `silo` and `siloء`
+
+Live checks on 2026-10-02. The requested behavior is a list of accounts for
+`silo` that includes `siloء`, whose final character is U+0621 (Arabic hamza).
+The exact-name result identifies that account as game UID **283622404**.
+
+## Results
+
+| Source | Search for `silo` | Search for `siloء` | Meets the requested suggestion behavior now? |
+|---|---|---|---|
+| RivalsData | One result: `Silo`, UID 1254981449 | One result: `siloء`, UID 283622404 | No |
+| RivalsTracker | 10 results; `siloء` is fifth, UID 283622404 | One result: `siloء`, UID 283622404 | Yes |
+| RivalsMeta | 10 results; `siloء` is fifth, UID 283622404 | One result: `siloء`, UID 283622404 | Yes |
+| Tracker.gg autocomplete | 20 results, excluding `siloء` | One result: `siloء` | No for the shorter query |
+| Tracker.gg submitted search | One result: `Silo` | One result: `siloء` | No for the shorter query |
+| OP.GG website | Five displayed results after loading; `siloء` is fifth | Navigates to the `siloء` profile | Yes at the website level; a reusable search API contract was not established |
+
+RivalsTracker and RivalsMeta returned identical search arrays in these checks.
+This does not establish that they have independent databases or search coverage.
+Tracker.gg's exact-name profile route also returned a public overview response
+for `siloء`. These observations show that the character can be represented and
+the account can be found. They do not establish why the short-query suggestions
+omit it, nor that special characters in general are filtered out.
+
+RivalsTracker's observed list, in order:
+
+1. `-SILO_`
+2. `Silo`
+3. `Silo_`
+4. `Silo_RAE`
+5. `siloء`
+6. `Silo_Koios`
+7. `Silo af`
+8. `Silo.is.bot`
+9. `silo_greedy`
+10. `Silo_92`
+
+## Exact requests and evidence
+
+- RivalsData: `POST https://api.rivalsdata.com/players/search`, JSON
+  `{"name":"silo"}` or `{"name":"siloء"}`. Both returned HTTP 200.
+  The friend's record contains `aid: "11001_283622404"`.
+- RivalsTracker: `POST https://api.rivalstracker.com/api/find-player`, same JSON
+  bodies. Both returned HTTP 200. The friend's row was
+  `{"aid":"283622404","name":"siloء","cur_head_icon_id":"31048204"}`.
+- RivalsMeta: `POST https://rivalsmeta.com/api/find-player`, same JSON bodies.
+  Both returned HTTP 200 and the same search rows as RivalsTracker. This route
+  and body were found in the site's current search component and runtime config.
+- Tracker.gg: `GET https://api.tracker.gg/api/v2/marvel-rivals/standard/search`
+  with `platform=ign`, `query=silo` or `query=siloء`, and `autocomplete=true`
+  for suggestions. Submitted search omits `autocomplete`. Direct HTTP was
+  challenged with 403; the existing Camoufox provider fallback succeeded for
+  all four searches. Exact profile:
+  `/api/v2/marvel-rivals/standard/profile/ign/silo%D8%A1`.
+- OP.GG: [short-name search](https://op.gg/marvel-rivals/search/silo) and
+  [full-name search](https://op.gg/marvel-rivals/search/silo%D8%A1), checked in
+  Camoufox. The short-name page initially showed four rows; after a longer load
+  it showed `Silofael`, `Silonace`, `silosue`, `Siloger`, and `siloء`. The exact
+  search opened the profile, which showed privacy and update notices. Those
+  notices were respected; no update button was clicked and no private stats
+  were requested. The list itself is the relevant evidence here.
+
+All these are observed website behaviors, not permanent API guarantees.
+Local raw responses and browser observations are saved in the ignored
+`dist/search-audit/` directory. No cookies, authorization headers, or API keys
+were saved in the research artifacts.
+
+## Existing wrapper behavior
+
+The Python method `RivalsClient.search_players()` already uses RivalsTracker's
+multi-result `/find-player` endpoint. A live call to `search_players("silo")`
+returned all 10 candidates, preserving `siloء` and adding numeric UID 283622404.
+It currently queries RivalsTracker alone; it does not merge all three providers.
+
+```python
+from rivals_api import RivalsClient
+
+with RivalsClient() as client:
+    candidates = client.search_players("silo")
+    # Includes a row with name == "siloء" and uid == 283622404.
+```
+
+Following this audit, the MCP search/profile flow was updated:
+
+| MCP tool | What it calls | Live result for `silo` |
+|---|---|---|
+| `search_players(name="silo")` | `client.search_players("silo")` | 10 candidates, including `siloء`, UID 283622404 |
+| `search_player_candidates(name="silo")` | `client.search_players("silo")` | 10 candidates, including `siloء`, UID 283622404 |
+| `get_player_profile(uid=283622404)` | `get_player("283622404")` | Profile overview for the selected numeric UID; not a candidate search |
+
+The original MCP `search_players` resolved one account through RivalsData and
+returned `Silo`, UID 1254981449. It now returns the same list as the candidate
+tool. For a selection list, use **`search_players`**, then **`get_player_profile`**
+with the chosen UID. The candidate tool remains a compatibility alias.
+Entering `silo` into a single-account resolver should not be treated as a
+selection of `siloء`.
+
+## Other trackers and APIs checked
+
+- [RivalCounter](https://www.rivalcounter.com/) routes player searches to
+  filtering its top-500 leaderboard snapshot. Its frontend labels this as
+  matching leaderboard entries. The current PC snapshot did not contain this
+  UID; this is not a general player-discovery replacement.
+- [MarvelRivalsAPI's documented search](https://docs.marvelrivalsapi.com/search-player-19312750e0)
+  is `GET /api/v1/find-player/{username}` and documents one name/UID result and
+  an `x-api-key` header. The anonymous `silo` probe returned a gateway error
+  (502), so live account coverage was not established.
+- [RivalsIsland](https://api.rivalsisland.com/) documents
+  `GET /players/search?name=...` in `/docs/openapi.json`, with a singular
+  `player` response. Both anonymous queries returned 401, missing API key.
+  Its UI describes exact-name lookup; suggestion coverage is unverified.
+- `mrapi.org` did not resolve in this environment. No current search behavior
+  could be verified.
+
+## Recommendation
+
+Use the RivalsTracker candidate path for this task. RivalsMeta is a
+confirmed alternative endpoint, and OP.GG also finds the account on its website.
+An additional provider is not needed to produce the requested list today.
+
+If “always included” is a product requirement, third-party suggestions alone
+cannot guarantee it. Persist the user's verified association between the alias
+`silo` and UID 283622404, then merge that known account with live suggestions,
+deduplicating by UID and preserving the displayed name `siloء`. Keep aliases
+scoped to the user or application that chose them; do not globally equate `Silo`
+with `siloء`. Resolve future names through the stored UID when available, and
+retain a clearly labeled saved candidate during upstream outages.
+
+The follow-up MCP change routes `search_players` to the existing candidate
+search and adds the UID-only profile tool. A persistent alias index is not
+implemented.

{rivals_api-2.0.0 → rivals_api-3.0.0}/docs/PROJECT_CONTEXT.md

@@ -17,7 +17,7 @@ implemented feature. Provider APIs are unofficial/undocumented and may change.
 
 - Distribution: `rivals-api`; preferred import: `rivals_api`.
 - Compatibility: `rivalsdata` and `RivalsDataClient` remain aliases.
-- Version: `2.0.0`.
+- Version: `3.0.0`.
 - Python `>=3.10`, Hatchling build, `src/` layout.
 - Runtime HTTP dependency: `curl-cffi`; optional browser fallback: Camoufox.
 - Public entry point: `RivalsClient`.
@@ -67,11 +67,40 @@ details, leaderboards, heroes, team-ups, insights, factions, profiles and
 favorites. New analytics and public community resources are documented in
 `docs/PROVIDER_INTEGRATION.md` and the feature-gap inventory.
 
+History rows carry their originating client and expose `match.get_details()`.
+Both bounded/all fetches and iteration return these bound `Match` objects. The
+method returns a new typed full `Match` through `client.matches.get(...)`, with
+`refresh=True` available to bypass detail/provider caches. The client reference
+is excluded from model serialization. Keep it open while fetching details.
+The shared fetcher in `match_details.py` validates provider match IDs, preserves
+raw responses and errors, merges roster/hero records by identity, and exposes
+per-field source decisions and completeness. Ambiguous player bridges remain
+unmatched. Accuracy percent is distinct from session hit rate; raw RD hero
+accuracy retains ratio units. Detail caches are scoped to the enrichment setting;
+partial cached evidence remains usable for request-free calculations but is
+retried by detail lookups.
+
+Match models resolve map, queue, gameplay, platform, rank, season, and hero
+references offline from packaged provider catalogs. References format as names
+and expose `.id`; the original numeric fields remain except `match.platform`,
+which is a typed Platform with `.platform_id` providing the previous scalar.
+Gameplay labels come from the map/objective context rather than guessing a
+global interpretation of `game_play_mode_id`. Unknown codes stay explicit.
+The catalog covers 118 map variants and 20 observed seasons; source evidence
+and serialization/migration details are in `docs/GAME_REFERENCES.md`.
+
 The MCP server exposes read-only tools over stdio or Streamable HTTP. It does
 not implement authentication; remote deployments must supply an authenticated
 gateway. The dashboard shows a snapshot and performs provider requests when a
 tool runs.
 
+MCP `search_players(name)` returns a list of RivalsTracker candidates with names
+and numeric game UIDs. `get_player_profile(uid)` retrieves the chosen profile
+by positive integer UID, including its current-season competitive win rate.
+`search_player_candidates` is an alias for the list search; the existing
+`get_player(uid_or_name)` tool remains available. The search tool previously
+resolved one account, so callers must migrate to handling list results.
+
 ## Development and release
 
 Create an isolated virtual environment and install `.[dev]`. Install