diff --git a/integrations/livetennisapi.md b/integrations/livetennisapi.md new file mode 100644 index 00000000..b385ee54 --- /dev/null +++ b/integrations/livetennisapi.md @@ -0,0 +1,138 @@ +--- +layout: integration +name: Live Tennis API +description: Live tennis scores, matches and players as Haystack Documents for RAG and agent pipelines +authors: + - name: Ben + socials: + github: bensynapse +pypi: https://pypi.org/project/livetennisapi-haystack/ +repo: https://github.com/livetennisapi/livetennisapi-haystack +type: Data Ingestion +report_issue: https://github.com/livetennisapi/livetennisapi-haystack/issues +version: Haystack 2.0 +toc: true +--- + +### Table of Contents + +- [Overview](#overview) +- [Installation](#installation) +- [Usage](#usage) + - [LiveTennisMatchFetcher](#livetennismatchfetcher) + - [LiveTennisPlayerSearch](#livetennisplayersearch) +- [License](#license) + +## Overview + +The [Live Tennis API](https://livetennisapi.com) serves live scores, matches and player data +across the ATP, WTA, Challenger, ITF and junior tours. + +This integration provides: + +- **`LiveTennisMatchFetcher`**: fetches live, upcoming or completed matches (optionally one + match by id, optionally filtered by tour) and returns them as Haystack `Document` objects. + Each Document's `content` is a clean human-readable match summary and its `meta` carries + the structured fields (ids, players, sets/games/points, server, winner). +- **`LiveTennisPlayerSearch`**: searches players by name (ranked players first) and returns + them as `Document` objects with the same content/meta split. + +You need a Live Tennis API key to use this integration (a free tier is available). The +components read it from the `LIVETENNISAPI_KEY` environment variable via Haystack's `Secret`, +so serialized pipelines never contain the key. Built on the official +[`livetennisapi`](https://pypi.org/project/livetennisapi/) Python client. + +## Installation + +```bash +pip install livetennisapi-haystack +``` + +## Usage + +Set your API key as the `LIVETENNISAPI_KEY` environment variable. + +### LiveTennisMatchFetcher + +#### Basic Example + +```python +from livetennisapi_haystack import LiveTennisMatchFetcher + +fetcher = LiveTennisMatchFetcher(limit=5) +result = fetcher.run(status="live") +for doc in result["documents"]: + print(doc.content) +``` + +#### In a Pipeline + +A RAG pipeline that answers questions about the matches on court right now: + +```python +from haystack import Pipeline +from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +from livetennisapi_haystack import LiveTennisMatchFetcher + +prompt_template = [ + ChatMessage.from_system("You are a tennis commentator."), + ChatMessage.from_user( + "Current matches:\n" + "{% for document in documents %}{{ document.content }}\n{% endfor %}\n" + "Answer the following question: {{ query }}\nAnswer:" + ), +] + +pipe = Pipeline() +pipe.add_component("matches", LiveTennisMatchFetcher(limit=10)) +pipe.add_component( + "prompt_builder", + ChatPromptBuilder(template=prompt_template, required_variables={"query", "documents"}), +) +pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini")) +pipe.connect("matches.documents", "prompt_builder.documents") +pipe.connect("prompt_builder.prompt", "llm.messages") + +query = "Who is closest to winning right now?" +result = pipe.run({"matches": {"status": "live"}, "prompt_builder": {"query": query}}) +print(result["llm"]["replies"][0].text) +``` + +#### Parameters + +- **`api_key`**: API key for the Live Tennis API. Defaults to the `LIVETENNISAPI_KEY` + environment variable. +- **`status`**: Default lifecycle status: `"live"`, `"upcoming"` or `"completed"`. + Overridable per `run()`. +- **`tour`**: Optional tour filter: `"atp"`, `"wta"`, `"challenger"`, `"itf"` or + `"juniors"`. Each value covers its singles and doubles draws. +- **`limit`**: Maximum number of matches to return (1-200). Defaults to 10. +- **`run(match_id=...)`**: fetches one specific match instead of a listing. + +If your key's tier does not unlock an endpoint (HTTP 403), the component returns a single +readable Document tagged `meta["error"] = "upgrade_required"` instead of raising, so agents +can surface the message and RAG pipelines can filter it. + +### LiveTennisPlayerSearch + +```python +from livetennisapi_haystack import LiveTennisPlayerSearch + +search = LiveTennisPlayerSearch(limit=3) +result = search.run(query="alcaraz") +for doc in result["documents"]: + print(doc.content) +``` + +#### Parameters + +- **`api_key`**: API key. Defaults to the `LIVETENNISAPI_KEY` environment variable. +- **`limit`**: Maximum number of players to return (1-200). Defaults to 10. + +## License + +`livetennisapi-haystack` is distributed under the terms of the +[MIT](https://spdx.org/licenses/MIT.html) license.