# Soccer Agent Toolbelt

Soccer analytics agent toolbelt.

- Repository: https://github.com/oracle-devrel/oracle-ai-developer-hub (4464 stars)
- Category: Data and ML
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add oracle-devrel/oracle-ai-developer-hub --skill soccer-agent-toolbelt -g -a claude-code -y`
Codex: `npx skills add oracle-devrel/oracle-ai-developer-hub --skill soccer-agent-toolbelt -g -a codex -y`
Cursor: `npx skills add oracle-devrel/oracle-ai-developer-hub --skill soccer-agent-toolbelt -g -a cursor -y`
Gemini CLI: `npx skills add oracle-devrel/oracle-ai-developer-hub --skill soccer-agent-toolbelt -g -a gemini-cli -y`

## Description

Soccer analytics agent toolbelt. Gives Claude Code direct access to the Oracle-backed match data, ML predictions, and three-tier memory. Use when answering questions about football matches, building on the soccer agent, or exploring the World Cup dataset.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Soccer Agent Toolbelt

You have 13 tools available. Invoke each via the dispatcher with JSON args.

## Hybrid-first rule for coding agents

When you are building, debugging, or demoing the agent, treat `hybrid_retrieve` as the default retrieval path for explanatory grounding. It is the workshop showcase: model prediction documents plus football facts stored in Oracle through `langchain-oracledb` `OracleVS`, retrieved with native hybrid search when possible or Oracle Text + vector reciprocal-rank fusion on Oracle AI Database Free.

Use `vector_search` deliberately as the semantic-only baseline over `semantic_memory` when you want to contrast "plain vector similarity" with hybrid retrieval. Do not replace `hybrid_retrieve` with `vector_search` in the agent loop, UI demos, or final Grok chat unless the LangChain OracleVS store is unavailable.

## LangGraph OracleDB observability rule

Every live `/chat` turn should leave an ordered step trace in Oracle through `langgraph-oracledb` `OracleStore`, under namespace `("soccer-agent", "agent-steps", session_id)`. Use this for observability/debugging: it records `turn_start`, `grounding_retrieved`, each `model_response`, each `tool_call`, each `tool_result`, and `final_response` or `tool_budget_exhausted`.

Inspect it via the API after a chat turn:

    curl http://localhost:8000/observability/<session_id> | uv run python -m json.tool

Or from Python:

    uv run python - <<'PY'
    from soccer_agent.observability.langgraph_steps import list_steps
    for step in list_steps("<session_id>"):
        print(step.value["step_index"], step.value["event_type"], step.value.get("tool_name"))
    PY

If this returns no rows after a real chat turn, run `uv run python scripts/init_memory.py` and `uv run python scripts/verify.py`; the verifier must report `langgraph-oracledb OracleStore observability setup`.

## Tools

The rest: https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/HEAD/workshops/soccer-analytics-agent/.claude/skills/soccer-agent-toolbelt/SKILL.md