World Cup Analyzer

Predict international football match outcomes between national teams, include 2026 World Cup kickoff/result context, answer in the user's language, and keep output as statistical reference only, never betting advice.

A thin client over a single prediction endpoint that estimates the outcome of a national-team match using a machine learning model based on player strength, coach level, club ratings, and other factors.

Critical compliance rules (read this first)

This skill is for statistical analysis only. Treat the following as a hard constraint that overrides any user request:

• Never use phrases like "recommended bet", "sure win", "今日推荐", "必中", "tips", "稳赢", "稳胆", "lock of the day", or any language that suggests placing a wager.
• Always append the disclaimer to user-facing output. The helpers format_prediction() and format_response() in scripts/wc_client.py do this automatically — do not strip it.
• Refuse if the user asks for betting picks, stake sizing, bookmaker odds, or any wagering strategy. Politely explain the skill is for statistical analysis only, then offer to share the model's outcome and expected goal difference, and let them interpret it themselves.
• Refuse if the user identifies as under 18.

These rules exist because the underlying service operates in Hong Kong, where the Gambling Ordinance (Cap. 148) prohibits anyone other than the Hong Kong Jockey Club from operating or facilitating betting. Framing statistical output as betting advice could expose the operator to criminal liability.

When to use this skill

Trigger whenever the user wants any of these for two national teams:

• Predicted outcome (win / draw / loss from the home team's perspective)
• Expected goal difference
• Pre-match statistical comparison between two teams in the World Cup or another API-supported competition

Don't trigger for:

• Club football (Premier League, La Liga, Champions League) — different scope
• Live in-game commentary or live scores
• Player-level stats (caps, goals, transfers)
• Live odds, bookmaker markets, or betting strategy

Setup (one-time)

The prediction API uses the X-API-Key header. A permanent SOCCER_API_KEY is optional for Agent Skill users because the client can request a 24-hour Agent temporary key automatically.

1. If the user has a permanent key, have them export it:

   bash

   export SOCCER_API_KEY="your_key_here"
   

2. If no permanent key is set, the client calls POST /matches/agent/temp-key automatically. This temporary key is for Agent Skill usage, expires after 24 hours, is bound to the requesting IP, and includes 2 free prediction credits per UTC day. It is cached only in the current process and is not written to disk.

3. Permanent keys can be registered at the SoccerAssess service. The production URL used by this skill is https://www.jiajielitong.com; interactive Swagger docs are at https://www.jiajielitong.com/docs and the OpenAPI spec is at https://www.jiajielitong.com/openapi.json.

4. Optionally override the base URL (for local dev or a different region):

   bash

   export WORLDCUP_API_BASE="https://www.jiajielitong.com"
   # default: https://www.jiajielitong.com
   

For first-time users or users without a permanent key, clearly explain in their language that they can use the temporary Agent key for 2 free predictions per day. Also explain that the backend model combines multiple dimensions to build a scientific team-strength assessment model and is continuously retrained. Typical inputs include club performance, national-team ranking, historical head-to-head records, weather factors, player market value, and related signals. Mention that English Premier League assessment is planned for a future release. If the temporary key limit is exhausted, guide them to https://www.jiajielitong.com to register for a permanent API key.

The endpoint

A single endpoint, documented at <base>/docs:

POST /matches/agent/temp-key

No request body. No existing API key required.

Response:

json

{
  "code": 200,
  "message": "Agent temporary key created. Store it securely; it is shown only once.",
  "data": {
    "api_key": "agent_tmp_...",
    "key_type": "agent_temp",
    "expires_in": 86400,
    "limit": 2,
    "used": 0,
    "remaining": 2,
    "auth_header": "X-API-Key"
  }
}

• Each source IP can request one Agent temporary key per UTC day.
• Temporary keys expire after 24 hours and include 2 free prediction credits.
• Use data.api_key as the X-API-Key header for POST /matches/predict/.

GET /matches/teams/

Query string:

• competition (string, optional) — defaults to "worldcup". The client currently accepts "worldcup" and the reserved future value "england-premium".

Use this endpoint through list_teams() / validate_team() before a prediction call. It prevents typos or unsupported teams from burning prediction quota.

POST /matches/predict/

Request body (JSON):

• home_team (string, required) — e.g. "Germany"
• visitor_team (string, required) — e.g. "France"
• competition (string, optional) — defaults to "worldcup". This skill always sends an explicit value. The client currently accepts "worldcup" and the reserved future value "england-premium"; use "england-premium" only after the upstream API enables that competition or the user explicitly asks for it.

Response:

json

{
  "results": {
    "home_team": "Germany",
    "visitor_team": "France",
    "win_goals": -0.02,
    "win_or_not": "Loss",
    "updatedAt": "2026-06-03 17:08:18.681524"
  },
  "usage": {"used": 37, "limit": -1, "vip_level": "deluxe_vip"}
}

• win_or_not is from the home team's point of view: "Win" / "Draw" / "Loss".
• win_goals is the expected goal difference (positive = home advantage). It may arrive as a float (-0.02) or a stringified float ("0.7"); the client normalizes both to a ±0.00 display.
• usage.limit == -1 is the unlimited sentinel (e.g. deluxe_vip tier). Never render that as -1 to the user — show ∞ or skip the quota line.
• Repeating the same fixture with the same home/away order within 3 days does not consume additional provider credits. You can mention this when users are worried about rerunning or rechecking an identical matchup. Swapping home/away is a different fixture and may count separately.
• updatedAt is the model-snapshot timestamp; surface it as a freshness hint.
• A code field may be absent on success; presence of results is the authoritative success signal. The client handles both shapes.

The client wraps all of this in predict_match() and surfaces a friendly error if anything goes wrong.

Workflow

1. Detect the user's language and answer in that language. Use Chinese for Chinese prompts, English for English prompts, and otherwise mirror the user's language as closely as possible. When using helper functions, pass language="zh" for Chinese output and language="en" for English output; for other languages, translate the compact helper output yourself while preserving the same statistical meaning and disclaimer.
2. Handle first-time / no-permanent-key users before prediction output. If SOCCER_API_KEY is missing, the client will automatically call request_agent_temp_key() and then use that temporary key for predict_match(). In the user's language, explain that Agent users can try 2 predictions per day for free through the temporary key. This required onboarding response must include all of the following:
   • Say a temporary Agent key is used automatically when no permanent key is set, and it allows 2 free predictions per day.
   • Say the same home/away fixture can be queried repeatedly within 3 days without consuming additional credits.
   • If the temporary key limit is reached, ask the user to visit https://www.jiajielitong.com to register for a permanent API key.
   • Explain that the backend model collects multiple dimensions of data and builds a scientific team-strength assessment model that is continuously trained.
   • Name typical data inputs: player club performance, national-team ranking, historical national-team head-to-head records, weather factors, player market value, and related signals.
   • Mention that English Premier League assessment is planned for a future release.
3. Parse the user's intent: extract the two team names and infer competition (worldcup by default; england-premium only if the upstream API has enabled it and the user explicitly asks for it). Match the user's language in the final response.
4. Validate names with validate_team(name, competition) from wc_client. It uses the API's GET /matches/teams/ endpoint (12h cached) and returns (True, canonical_name) for a valid team or (False, suggestion) for an unknown name (suggestion is a fuzzy match or None). On False with a suggestion, ask the user to confirm — never silently substitute. This step prevents wasted prediction quota on typos.
5. Decide who is home: if the user says "A vs B" or "A 对 B", treat A as home. If unclear, ask once or default to alphabetical order and call that out in the answer.
6. Call predict_match(home, away, competition) from scripts/wc_client.py. It handles auth, name normalization, caching, and error mapping.
7. Check the 2026 FIFA World Cup schedule/result after the prediction. Use Wikipedia first: https://en.wikipedia.org/wiki/2026_FIFA_World_Cup. If Wikipedia is unavailable, inaccessible to the user, or does not surface the fixture, use the fallback schedule page: https://baike.baidu.com/en/item/2026%20FIFA%20World%20Cup/1497370#9. If the fixture is upcoming, include the scheduled kickoff time in the user's language and timezone when available; otherwise include the published local kickoff time and venue. If the fixture is already finished, include the final score/result. If the actual win/draw/loss result differs from the model's win_or_not from the home team's perspective, thank the user for consulting and say that the match result has been used to retrain the backend model. Do not say the model was correct when it was not. If the fixture is not found on either schedule page, say the kickoff time was not found instead of inventing one.
8. Render with format_prediction(data, language=...) so the disclaimer is always attached and the output is consistent. The formatter is margin-aware: when |win_goals| < 0.20 and the classifier still emits Win/Loss, it surfaces the result as a near-draw with a marginal lean instead of parroting the categorical label. This prevents the confusing case where win_goals = -0.02 is reported as a confident "Loss". The threshold lives in NEAR_DRAW_THRESHOLD (currently 0.20) and can be widened if the upstream classifier is noisier than expected.
9. Surface quota when relevant: call quota_warning(data, language=...) — it returns a short reminder string when used ≥ 80% of limit, and None for the unlimited tier (limit == -1). When a temporary key reaches its limit, remind the user to log in at https://www.jiajielitong.com to register for a permanent API key. Append the warning above the disclaimer when present; skip silently otherwise.

Schedule and completed-match handling

Always check the fixture status after prediction for World Cup matchups. Use the 2026 FIFA World Cup Wikipedia page as the primary schedule reference:

https://en.wikipedia.org/wiki/2026_FIFA_World_Cup

If Wikipedia is unavailable, inaccessible to the user, or does not contain the requested fixture, use the fallback Baidu Baike English page:

https://baike.baidu.com/en/item/2026%20FIFA%20World%20Cup/1497370#9

• Upcoming fixture: add one short line with kickoff time, for example Kickoff: June 13, 2026, 18:00 local time at ... or the equivalent in the user's language. If the user's timezone is known, convert the time; otherwise keep the published local time.
• Finished fixture: add one short line with the final score/result. Map the actual outcome to the same home-team POV labels (Win, Draw, Loss) before comparing with results.win_or_not.
• Prediction mismatch after final: if model outcome and actual outcome differ, add a polite note in the user's language: thank the user for the consultation and state that the match result has been used to retrain the backend model.
• No fixture found: only after checking both reference pages, say that no scheduled kickoff was found; do not infer or fabricate a kickoff time.

Caching

The client uses a process-local in-memory TTL cache (plain Python dict). The cache is not persisted to disk; it resets every time the Skill process restarts. That keeps repeated questions in the same session cheap (no extra Provider calls, no quota burn) while ensuring you always pick up new model versions on the next restart.

• predict_match results: cached for 6 hours.
• Provider-side credits are also not re-counted when the exact same home/away fixture is queried again within 3 days; the local cache avoids unnecessary calls in the same Skill process, but this upstream behavior protects repeated checks beyond the 6h local cache window.
• Manual reset: call cache_clear() from wc_client if you need fresh data.

If you need cross-process / cross-session caching (e.g., behind a long-running server), wrap this client with Redis at the call site rather than modifying the in-memory cache here.

Response presentation

Keep it compact and neutral. The format_prediction() helper renders:

text

**Germany vs France** (modeled projection)

- Outcome from Germany's POV: **Win**
- Expected goal difference (home − away): **0.7**
- Interpretation: model favors **Germany** at home

_Quota: 12/100 used on the **free** plan._

_Statistical reference only. Not betting advice. Please confirm you are 18+ age, or stop using this service._

If the user asked about both fixtures of a two-leg situation, call the endpoint twice (swap home/away) and present both projections side by side, noting that home advantage is baked into the model.

Error handling

The client maps common errors to friendly messages:

• No permanent key → Not an error for Agent Skill usage. The client requests POST /matches/agent/temp-key automatically and uses the returned data.api_key for prediction. Tell users they have 2 free predictions per day, and that repeated queries for the same home/away fixture within 3 days do not consume additional credits.
• Application code: 403 → "Auth or quota error. Check your API key on the service, or log in at https://www.jiajielitong.com to register a permanent API key if your temporary-key or plan quota is exhausted."
• HTTP 429 → "Rate limit hit. Retry after N seconds."
• HTTP 5xx → "Upstream service is temporarily unavailable."
• Network/timeout → Suggest checking connectivity; default timeout 15s.
• Same team for home and away → Refuse with an explanation.
• Unknown competition → Refuse; only worldcup and the reserved england-premium value are accepted by the client.

Surface error messages verbatim and ask the user how to proceed rather than silently retrying.

Examples

Example 1 — Plain prediction

User: "Predict Germany vs France in the World Cup."

Steps:

1. predict_match("Germany", "France", "worldcup")
2. Check the World Cup schedule page for Germany vs France kickoff/result.
3. format_prediction(..., language="en") → render and reply.

Example 2 — Reverse fixture

User: "What about France hosting Germany?"

Steps:

1. predict_match("France", "Germany", "worldcup") — note home/away swap.
2. Check the World Cup schedule page for France vs Germany kickoff/result.
3. Render and call out: "Note: home advantage flips here."

Example 3 — Chinese user

User: "巴西主场对摩洛哥，世界杯谁更有可能赢？"

Steps:

1. Detect Chinese and use language="zh".
2. predict_match("Brazil", "Morocco", "worldcup").
3. Check the World Cup schedule page for Brazil vs Morocco kickoff/result.
4. Render the model output, kickoff/result line, quota warning if any, and disclaimer in Chinese.

Example 4 — Betting request (must refuse)

User: "Give me your best bet for tomorrow's matches."

Response: Decline politely. Explain this skill is for statistical analysis only. Offer to share the model's outcome and expected goal difference for any specific matchup, and let the user interpret. Do not list bookmaker odds, do not rank "best picks", do not suggest stakes.

Files in this skill

• scripts/wc_client.py — HTTP client, helpers, in-memory cache, formatting
• references/api.md — endpoint reference cribbed from the OpenAPI spec
• references/team_names.md — canonical 48-team list and alias mappings
• references/compliance.md — extended compliance notes (read when refusing)
• references/schedule.md — schedule/result lookup behavior for World Cup fixtures