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

sql_query

Run a read-only SELECT against the soccer schema. Allowed tables: MATCH_RESULTS, GOALSCORERS, SHOOTOUTS, WC2026_VENUES, PREDICCIONES_FINAL, SOCCER_LANGCHAIN_DOCS, VW_COMPETITIVE_MATCHES, VW_TEAM_STATISTICS, AGENT_SESSIONS, WORKING_MEMORY, EPISODIC_MEMORY, SEMANTIC_MEMORY. Args: {"sql": "<SELECT statement>"}

vector_search

Semantic-only similarity over distilled facts in semantic_memory. The embedding is computed in-database via VECTOR_EMBEDDING(ALL_MINILM_L6_V2 USING :t AS DATA) — no external embedding API call is made. Use this to show the baseline that only ranks embedded fact summaries; it does not search cached ML prediction documents. Args: {"query": "<text>", "limit": 5, "fact_type": "team_decade"}

hybrid_retrieve

Default evidence retrieval path. Hybrid retrieval over the LangChain OracleVS table SOCCER_LANGCHAIN_DOCS, populated by langchain-oracledb after ML inference. It combines ML prediction documents and football facts with native HYBRID VECTOR INDEX when available, or Oracle Text + vector reciprocal-rank fusion on Oracle AI Database Free. Prefer this before vector_search for any explanation that Grok or a coding agent will use. Args: {"query": "Spain Brazil World Cup prediction", "limit": 5, "search_mode": "hybrid"}

predict_match

On-demand 92-feature XGBoost inference for current or hypothetical matches. Args: {"home_team": "Spain", "away_team": "Brazil", "neutral": true}

get_elo

FootballElo rating for one team, including tournament-tier ratings. Args: {"team": "Spain"}

get_team_form

Rolling and weighted recent form plus goal averages. Args: {"team": "Spain", "n": 10}

get_h2h

Head-to-head record from team_a's perspective. Args: {"team_a": "Spain", "team_b": "Brazil"}

get_momentum

Streaks, unbeaten run, clean-sheet rate, comeback rate, draw tendency, and blowouts. Args: {"team": "Spain", "n": 15}

get_poisson_xg

Poisson expected-goals lambdas and outcome probabilities. Args: {"home_team": "Spain", "away_team": "Brazil", "n": 20}

get_tournament_context

World Cup, continental, qualifying, friendly, and big-game context for one team. Args: {"team": "Spain"}

lookup_prediction

Precomputed prediction from PREDICCIONES_FINAL. Args: {"home_team": "Spain", "away_team": "Brazil"}

remember

Write a fact to semantic memory. Args: {"fact_type": "...", "subject_key": "...", "summary": "...", "source": {}}

recall

Recent N turns of episodic memory for the current session. Args: {"limit": 8}

How to invoke

From the repo root with the uv env active:

uv run python .claude/skills/soccer-agent-toolbelt/tools/run_tool.py <tool> '<json args>' [--session SID]

Examples:

uv run python .claude/skills/soccer-agent-toolbelt/tools/run_tool.py sql_query \
    '{"sql":"SELECT home_team, away_team FROM match_results WHERE tournament = '\''FIFA World Cup'\'' AND ROWNUM <= 5"}'

uv run python .claude/skills/soccer-agent-toolbelt/tools/run_tool.py lookup_prediction \
    '{"home_team":"Spain","away_team":"Brazil"}'

uv run python .claude/skills/soccer-agent-toolbelt/tools/run_tool.py hybrid_retrieve \
    '{"query":"Spain Brazil World Cup prediction evidence","limit":3}'

Contrast it with the semantic-only baseline when teaching the difference:

uv run python .claude/skills/soccer-agent-toolbelt/tools/run_tool.py vector_search \
    '{"query":"Spain Brazil World Cup prediction evidence","limit":3}'

Expected contrast: hybrid_retrieve can return doc_type=prediction rows from PREDICCIONES_FINAL with a retrieval_mode such as native_hybrid or fallback_rrf; vector_search returns only distilled facts from semantic_memory. That difference is the Oracle AI Database vector-store showcase.

The dispatcher prints the result as a single JSON line to stdout. Tool surface mirrors soccer_agent/agent/tools.py exactly — same schemas as the deployed FastAPI agent uses.

Adding your own tool

If you want to add a 14th tool (e.g. one that reads team stats, schedules a future match, or writes to a custom table):

1. Append a new schema to TOOL_SCHEMAS in soccer_agent/agent/tools.py.
2. Add a if name == "your_tool": branch in dispatch(...). Return a JSON-serializable dict; the loop will surface it back to the model.
3. The soccer-agent-toolbelt dispatcher (this skill) and the FastAPI agent both pick it up automatically — they share the same TOOL_SCHEMAS list.

Pitfalls when building on Oracle AI Database

These are the sharp edges we hit shipping the workshop. They aren't theoretical — every one bit a real session.

python-oracledb (3.x)

• IS JSON CLOBs auto-decode to Python dict/list. json.loads(value) on a column declared CLOB CHECK (... IS JSON) raises TypeError: the JSON object must be str, bytes or bytearray, not dict because the driver already parsed it. Guard with isinstance(val, (str, bytes, bytearray)) before decoding.
• LOB locators die after connection close. If you fetch CLOB rows inside with get_connection() as conn: ... and then build dataclasses or call .read() AFTER the with block exits, you get DPY-1001: not connected to database. Materialize CLOBs INSIDE the with block:

  with get_connection() as conn:
      cur = conn.cursor()
      cur.execute(...)
      rows = [
          {c: (v.read() if hasattr(v, "read") else v)
           for c, v in zip(cols, row)}
          for row in cur.fetchall()
      ]
  return rows

• Pass float32 vectors as array.array('f', list), not numpy ndarrays. oracledb does not bind numpy directly to VECTOR columns.
• load_dotenv() with no args needs a stack frame. If you pipe Python to stdin (uv run python - <<EOF), find_dotenv() raises AssertionError. Pass an explicit path: load_dotenv(Path.cwd() / ".env").

Vector, hybrid search, and observability

• Hybrid-first default. For agent grounding, UI demos, and final Grok answers, use hybrid_retrieve first so the answer can cite cached ML prediction documents and football facts from the LangChain OracleVS vector store. Use vector_search as a semantic-only comparison or fallback, not as the primary path.
• Observe the loop, not just the final answer. soccer_agent.observability.langgraph_steps stores every turn/tool step with langgraph-oracledb OracleStore. GET /observability/{session_id} is the fastest proof that the agent persisted its execution path.
• Lower distance is better. ORDER BY VECTOR_DISTANCE(embedding, :q, COSINE) ASC (ascending is the default; just don't put DESC).
• Use FETCH FIRST :n ROWS ONLY, not LIMIT. LIMIT is not valid Oracle SQL.
• Bind the query vector once. Don't compute embed_one(query) twice — call it once and reuse the array.array.
• Refresh SOCCER_LANGCHAIN_DOCS after model changes. Run uv run python scripts/load_langchain_vectors.py --reset after scripts/load_predictions.py so hybrid retrieval reflects the latest PREDICCIONES_FINAL probabilities.
• HYBRID VECTOR INDEX is optional on Oracle AI Database Free. hybrid_retrieve falls back to Oracle Text + vector reciprocal-rank fusion if native OracleHybridSearchRetriever support is unavailable.

Schema and grants

• CREATE MINING MODEL is required for DBMS_VECTOR.LOAD_ONNX_MODEL. Workshop setup grants it; if you re-create the user manually, add the grant.
• DBMS_VECTOR is already EXECUTE to PUBLIC on Oracle AI Database Free; do NOT try to grant it explicitly — SYSTEM lacks GRANT ANY OBJECT PRIVILEGE and you'll hit ORA-01031.

In-DB ONNX embedding model

• Model name in SQL is uppercase with underscores (e.g. ALL_MINILM_L6_V2), NOT the HuggingFace path. Set the model name via the ORACLE_EMBED_MODEL env var.
• Vanilla HuggingFace ONNX exports don't work. Oracle requires the tokenizer baked into the graph; otherwise VECTOR_EMBEDDING(...) returns ORA-54426: Tensor "input_ids" contains multiple dimensions (2) of variable size. Use the onnx2oracle PyPI package (not oml4py, which is a 4-file stub on PyPI).
• Embedding dim must match the VECTOR(384, FLOAT32) column type. If you switch to all-mpnet-base-v2 (768 dims), update the schema too.

OCI GenAI Inference (Grok 4)

• Bearer-token auth (sk-...) works against /actions/chat and /actions/embedText only. The control plane (https://generativeai...) rejects the bearer key — you can't list models with it. Look in the OCI Console for the model catalog.
• Compartment OCID is required in the request body, not just for auth. Always include servingMode.compartmentId (the workshop's grok_client.py does this).
• Native tool calling (the tools array) returns HTTP 400 on every model tested with this auth path. Use the prompt-protocol pattern: append tool schemas to the system message, instruct the model to emit {"tool": "...", "args": {...}} as a single JSON object when calling a tool, parse it out of the response text. See soccer_agent/agent/grok_client.py:_inject_tool_protocol and _parse_tool_calls.
• role: "tool" messages get rejected without toolCallId. Since the bearer-auth endpoint never emits a toolCallId, route tool results back as role: "system" messages. Skip any persisted role: "tool" turns when rebuilding the message list for the next iteration — they will break the next API call.