livetennisapi-haystack 0.1.0__py3-none-any.whl

livetennisapi_haystack/__init__.py

@@ -0,0 +1,6 @@
+from .match_fetcher import LiveTennisMatchFetcher
+from .player_search import LiveTennisPlayerSearch
+
+__version__ = "0.1.0"
+
+__all__ = ["LiveTennisMatchFetcher", "LiveTennisPlayerSearch"]

livetennisapi_haystack/_util.py

@@ -0,0 +1,56 @@
+"""Helpers shared by the Live Tennis API components.
+
+Kept private: only the components are public API.
+"""
+
+from typing import Any
+
+from haystack import Document
+from livetennisapi.errors import UpgradeRequired
+
+
+def make_upgrade_document(exc: UpgradeRequired) -> Document:
+    """Turn a 403 tier wall into a readable Document instead of a crash.
+
+    The Live Tennis API returns 403 when the key is valid but the plan does not
+    unlock the endpoint. In a pipeline that should surface as information the
+    downstream LLM (or user) can act on, not as a traceback. The Document is
+    tagged with ``meta["error"] = "upgrade_required"`` so RAG pipelines that
+    only want match data can filter it out.
+    """
+    return Document(
+        content=f"Live Tennis API access notice: {exc}",
+        meta={
+            "source": "livetennisapi",
+            "error": "upgrade_required",
+            "status_code": exc.status_code,
+            "required_tier": exc.required_tier,
+        },
+    )
+
+
+def player_label(player: Any) -> str:
+    """One human-readable label for a player or doubles team.
+
+    Tolerates sparse records: doubles teams have no ranking and lower-tour
+    players may miss country. Only what exists is shown.
+    """
+    if player is None:
+        return "unknown"
+    name = getattr(player, "name", None) or "unknown"
+    bits = []
+    country = getattr(player, "country", None)
+    if country:
+        bits.append(str(country))
+    ranking = getattr(player, "ranking", None)
+    if ranking is not None:
+        bits.append(f"#{ranking}")
+    return f"{name} ({', '.join(bits)})" if bits else name
+
+
+def iso_or_none(value: Any) -> Any:
+    """Datetime/date -> ISO string for JSON-safe Document meta; else pass through."""
+    if value is None:
+        return None
+    iso = getattr(value, "isoformat", None)
+    return iso() if callable(iso) else value

livetennisapi_haystack/match_fetcher.py

@@ -0,0 +1,336 @@
+from typing import Any
+
+from haystack import Document, component, default_from_dict, default_to_dict, logging
+from haystack.utils import Secret, deserialize_secrets_inplace
+from livetennisapi import LiveTennisAPI
+from livetennisapi.errors import NotFound, UpgradeRequired
+from livetennisapi.models import Match
+
+from ._util import iso_or_none, make_upgrade_document, player_label
+
+logger = logging.getLogger(__name__)
+
+_STATUSES = ("live", "upcoming", "completed")
+_TOURS = ("atp", "wta", "challenger", "itf", "juniors")
+_MAX_LIMIT = 200
+
+
+@component
+class LiveTennisMatchFetcher:
+    """
+    Fetches tennis matches from the [Live Tennis API](https://livetennisapi.com) as Haystack Documents.
+
+    Each Document's ``content`` is a clean human-readable match summary (players, tournament,
+    live score, server, winner) and its ``meta`` carries the structured fields (ids, players,
+    sets/games/points), so the component is directly usable in RAG and agent pipelines.
+
+    Requires a Live Tennis API key, read from the ``LIVETENNISAPI_KEY`` environment variable
+    by default.
+
+    ### Usage example
+
+    ```python
+    from livetennisapi_haystack import LiveTennisMatchFetcher
+
+    fetcher = LiveTennisMatchFetcher()          # key from LIVETENNISAPI_KEY
+    result = fetcher.run(status="live")
+    for doc in result["documents"]:
+        print(doc.content)
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("LIVETENNISAPI_KEY"),
+        status: str = "live",
+        tour: str | None = None,
+        limit: int = 10,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        Initialize the LiveTennisMatchFetcher component.
+
+        :param api_key:
+            Live Tennis API key. Defaults to the ``LIVETENNISAPI_KEY`` environment variable.
+        :param status:
+            Default match lifecycle status to fetch: ``"live"``, ``"upcoming"`` or ``"completed"``.
+        :param tour:
+            Optional default tour filter: ``"atp"``, ``"wta"``, ``"challenger"``, ``"itf"`` or
+            ``"juniors"``. Each value covers its singles and doubles draws. ``None`` fetches all tours.
+        :param limit:
+            Default maximum number of matches to return (1-200).
+        :param base_url:
+            Optional API base URL override, mainly for testing.
+        :param timeout:
+            HTTP timeout in seconds.
+        """
+        _validate_status(status)
+        _validate_tour(tour)
+        self.api_key = api_key
+        self.status = status
+        self.tour = tour
+        self.limit = limit
+        self.base_url = base_url
+        self.timeout = timeout
+        self._client: LiveTennisAPI | None = None
+
+    def warm_up(self) -> None:
+        """
+        Initialize the Live Tennis API client.
+
+        Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+        """
+        if self._client is None:
+            self._client = LiveTennisAPI(
+                api_key=self.api_key.resolve_value(),
+                base_url=self.base_url,
+                timeout=self.timeout,
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns: Dictionary with serialized data. The API key is stored as a Secret reference,
+            never as a plain string.
+        """
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            status=self.status,
+            tour=self.tour,
+            limit=self.limit,
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "LiveTennisMatchFetcher":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data: Dictionary to deserialize from.
+        :returns: Deserialized component.
+        """
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        status: str | None = None,
+        tour: str | None = None,
+        limit: int | None = None,
+        match_id: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Fetch matches and return them as Documents.
+
+        :param status:
+            Optional per-run override of the lifecycle status (``"live"``, ``"upcoming"``,
+            ``"completed"``). Ignored when ``match_id`` is given.
+        :param tour:
+            Optional per-run override of the tour filter. Ignored when ``match_id`` is given.
+        :param limit:
+            Optional per-run override of the maximum number of matches (1-200).
+        :param match_id:
+            Fetch one specific match by id instead of a listing. An unknown id yields an
+            empty list, not an error.
+        :returns: A dictionary with:
+            - ``documents``: one Document per match, ``content`` holding the readable summary
+              and ``meta`` the structured fields. If the API answers 403 (tier wall), a single
+              Document tagged ``meta["error"] = "upgrade_required"`` carries the readable
+              message instead.
+        """
+        if self._client is None:
+            self.warm_up()
+        if self._client is None:
+            msg = "LiveTennisMatchFetcher client failed to initialize."
+            raise RuntimeError(msg)
+
+        try:
+            if match_id is not None:
+                match = self._client.get_match(match_id)
+                matches = [match] if match is not None else []
+            else:
+                matches = self._list_matches(status, tour, limit)
+        except NotFound:
+            logger.warning("Live Tennis API: match {match_id} not found", match_id=match_id)
+            return {"documents": []}
+        except UpgradeRequired as exc:
+            logger.warning("Live Tennis API tier wall: {exc}", exc=exc)
+            return {"documents": [make_upgrade_document(exc)]}
+
+        return {"documents": [match_to_document(m) for m in matches if m is not None]}
+
+    def _list_matches(self, status: str | None, tour: str | None, limit: int | None) -> list[Match]:
+        effective_status = status if status is not None else self.status
+        effective_tour = tour if tour is not None else self.tour
+        effective_limit = max(1, min(int(limit if limit is not None else self.limit), _MAX_LIMIT))
+        _validate_status(effective_status)
+        _validate_tour(effective_tour)
+        assert self._client is not None  # noqa: S101 - checked by run()
+
+        if effective_tour is None:
+            return list(self._client.list_matches(status=effective_status, limit=effective_limit))
+
+        # The public /matches endpoint documents a `tour` query parameter
+        # (openapi.yaml, parameters.tour), but livetennisapi 1.0.2 does not yet
+        # expose it on list_matches(). Deliberate deviation: go through the
+        # official client's transport layer (retries, error mapping, auth)
+        # rather than hand-rolling HTTP. Switch to
+        # `client.list_matches(status=..., tour=...)` once the client grows it.
+        raw = self._client._request(
+            "/matches",
+            self._client._params(
+                {"status": effective_status, "tour": effective_tour, "limit": effective_limit, "offset": 0}
+            ),
+        )
+        items = (raw.get("data") or []) if isinstance(raw, dict) else (raw or [])
+        return [m for m in (Match.from_dict(i) for i in items) if m is not None]
+
+
+def _validate_status(status: str) -> None:
+    if status not in _STATUSES:
+        msg = f"status must be one of {_STATUSES}, got {status!r}"
+        raise ValueError(msg)
+
+
+def _validate_tour(tour: str | None) -> None:
+    if tour is not None and tour not in _TOURS:
+        msg = f"tour must be one of {_TOURS} or None, got {tour!r}"
+        raise ValueError(msg)
+
+
+def match_to_document(match: Match) -> Document:
+    """
+    Convert one ``livetennisapi`` Match into a Haystack Document.
+
+    ``content`` is a human-readable summary; ``meta`` carries JSON-safe structured fields.
+    Tolerates every documented sparsity: null ``score.server``, doubles teams without
+    rankings, string points, absent scores on upcoming matches.
+    """
+    p1, p2 = match.p1, match.p2
+    p1_label, p2_label = player_label(p1), player_label(p2)
+
+    where = [str(match.tournament)] if match.tournament else []
+    if match.surface:
+        where.append(f"{match.surface} court" + (" (indoor)" if match.indoor else ""))
+    if match.round:
+        where.append(f"round {match.round}")
+    if match.format:
+        where.append({"BO5": "best of 5", "BO3": "best of 3"}.get(match.format, str(match.format)))
+    kind = "doubles " if match.is_doubles else ""
+
+    head = f"{p1_label} vs {p2_label} — {kind}match"
+    if where:
+        head += f" at {where[0]}" if len(where) == 1 else f" at {', '.join(where)}"
+
+    lines = [head + "."]
+    lines.extend(_status_lines(match, p1_label, p2_label))
+    content = " ".join(lines)
+
+    meta = {
+        "source": "livetennisapi",
+        "match_id": match.id,
+        "status": match.status,
+        "event_status": match.event_status,
+        "tournament": match.tournament,
+        "surface": match.surface,
+        "indoor": match.indoor,
+        "format": match.format,
+        "round": match.round,
+        "is_doubles": match.is_doubles,
+        "scheduled_time": iso_or_none(match.scheduled_time),
+        "p1_id": getattr(p1, "id", None),
+        "p1_name": getattr(p1, "name", None),
+        "p1_country": getattr(p1, "country", None),
+        "p1_ranking": getattr(p1, "ranking", None),
+        "p2_id": getattr(p2, "id", None),
+        "p2_name": getattr(p2, "name", None),
+        "p2_country": getattr(p2, "country", None),
+        "p2_ranking": getattr(p2, "ranking", None),
+        "winner": match.winner,
+    }
+    score = match.score
+    if score is not None:
+        meta.update(
+            {
+                "sets": score.sets,
+                "games": score.games,
+                "points": score.points,
+                "server": score.server,
+                "is_tiebreak": score.is_tiebreak,
+                "score_timestamp": iso_or_none(score.timestamp),
+            }
+        )
+    return Document(content=content, meta=meta)
+
+
+def _status_lines(match: Match, p1_label: str, p2_label: str) -> list[str]:
+    """Readable status/score sentences for one match."""
+    lines: list[str] = []
+    score = match.score
+    names = {1: p1_label, 2: p2_label}
+
+    if match.status == "upcoming":
+        when = iso_or_none(match.scheduled_time)
+        lines.append(f"Scheduled for {when}." if when else "Upcoming; not yet scheduled.")
+        return lines
+
+    if match.status == "completed":
+        winner = names.get(match.winner) if match.winner in (1, 2) else None
+        lines.append(f"Completed; winner: {winner}." if winner else "Completed.")
+    elif match.status == "live":
+        lines.append("Live now.")
+    elif match.status:
+        lines.append(f"Status: {match.status}.")
+
+    if score is None:
+        return lines
+
+    sentence = _score_sentence(score)
+    if sentence:
+        lines.append(sentence)
+    # score.server is nullable by contract: between points/matches the feed may
+    # not know who serves next. Only say so when it does.
+    server = names.get(score.server) if score.server in (1, 2) else None
+    if server and match.status == "live":
+        lines.append(f"{server} is serving.")
+    return lines
+
+
+def _score_sentence(score: Any) -> str | None:
+    """One ``"Score: sets 1-1, games 6-4, 3-6, points 30-15."`` sentence, or None."""
+    parts: list[str] = []
+    if score.sets and len(score.sets) >= 2:
+        parts.append(f"sets {score.sets[0]}-{score.sets[1]}")
+    games = _games_summary(score.games)
+    if games:
+        parts.append(f"games {games}")
+    # Points are strings by contract ("0", "15", "30", "40", "AD") — but live
+    # data shows completed matches can carry [None, None], so only render
+    # points when both sides actually exist.
+    if score.points and len(score.points) >= 2 and score.points[0] is not None and score.points[1] is not None:
+        parts.append(f"points {score.points[0]}-{score.points[1]}")
+    if score.is_tiebreak:
+        parts.append("in a tiebreak")
+    return f"Score: {', '.join(parts)}." if parts else None
+
+
+def _games_summary(games: Any) -> str | None:
+    """Per-set games as ``"6-4, 3-6, 2-1"``.
+
+    The wire format is player-major — ``[games_p1, games_p2]``, each a per-set
+    list — so a set's score is a zip across the two sides, not one row.
+    """
+    if not isinstance(games, list) or len(games) < 2:
+        return None
+    p1, p2 = games[0], games[1]
+    if not isinstance(p1, list) or not isinstance(p2, list):
+        return None
+    # strict=False on purpose: mid-update the two sides can briefly disagree in
+    # length; showing the sets both agree on beats crashing.
+    pairs = [f"{a}-{b}" for a, b in zip(p1, p2, strict=False)]
+    return ", ".join(pairs) if pairs else None

livetennisapi_haystack/player_search.py

@@ -0,0 +1,183 @@
+from typing import Any
+
+from haystack import Document, component, default_from_dict, default_to_dict, logging
+from haystack.utils import Secret, deserialize_secrets_inplace
+from livetennisapi import LiveTennisAPI
+from livetennisapi.errors import UpgradeRequired
+from livetennisapi.models import Player
+
+from ._util import iso_or_none, make_upgrade_document
+
+logger = logging.getLogger(__name__)
+
+_MAX_LIMIT = 200
+
+_HANDS = {"R": "right-handed", "L": "left-handed"}
+_BACKHANDS = {1: "one-handed backhand", 2: "two-handed backhand"}
+
+
+@component
+class LiveTennisPlayerSearch:
+    """
+    Searches players on the [Live Tennis API](https://livetennisapi.com) and returns them as Haystack Documents.
+
+    Each Document's ``content`` is a readable player summary (name, country, ranking, plays)
+    and its ``meta`` carries the structured fields, ready for RAG and agent pipelines.
+    Ranked players come first in the API's ordering.
+
+    Requires a Live Tennis API key, read from the ``LIVETENNISAPI_KEY`` environment variable
+    by default.
+
+    ### Usage example
+
+    ```python
+    from livetennisapi_haystack import LiveTennisPlayerSearch
+
+    search = LiveTennisPlayerSearch()           # key from LIVETENNISAPI_KEY
+    result = search.run(query="alcaraz")
+    for doc in result["documents"]:
+        print(doc.content)
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("LIVETENNISAPI_KEY"),
+        limit: int = 10,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        Initialize the LiveTennisPlayerSearch component.
+
+        :param api_key:
+            Live Tennis API key. Defaults to the ``LIVETENNISAPI_KEY`` environment variable.
+        :param limit:
+            Default maximum number of players to return (1-200).
+        :param base_url:
+            Optional API base URL override, mainly for testing.
+        :param timeout:
+            HTTP timeout in seconds.
+        """
+        self.api_key = api_key
+        self.limit = limit
+        self.base_url = base_url
+        self.timeout = timeout
+        self._client: LiveTennisAPI | None = None
+
+    def warm_up(self) -> None:
+        """
+        Initialize the Live Tennis API client.
+
+        Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+        """
+        if self._client is None:
+            self._client = LiveTennisAPI(
+                api_key=self.api_key.resolve_value(),
+                base_url=self.base_url,
+                timeout=self.timeout,
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns: Dictionary with serialized data. The API key is stored as a Secret reference,
+            never as a plain string.
+        """
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            limit=self.limit,
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "LiveTennisPlayerSearch":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data: Dictionary to deserialize from.
+        :returns: Deserialized component.
+        """
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document])
+    def run(self, query: str, limit: int | None = None) -> dict[str, Any]:
+        """
+        Search players by name and return them as Documents.
+
+        :param query: Player name (or part of it) to search for.
+        :param limit: Optional per-run override of the maximum number of players (1-200).
+        :returns: A dictionary with:
+            - ``documents``: one Document per player. If the API answers 403 (tier wall), a
+              single Document tagged ``meta["error"] = "upgrade_required"`` carries the
+              readable message instead.
+        """
+        if self._client is None:
+            self.warm_up()
+        if self._client is None:
+            msg = "LiveTennisPlayerSearch client failed to initialize."
+            raise RuntimeError(msg)
+
+        effective_limit = max(1, min(int(limit if limit is not None else self.limit), _MAX_LIMIT))
+        try:
+            players = list(self._client.search_players(query, limit=effective_limit))
+        except UpgradeRequired as exc:
+            logger.warning("Live Tennis API tier wall: {exc}", exc=exc)
+            return {"documents": [make_upgrade_document(exc)]}
+
+        return {"documents": [player_to_document(p) for p in players if p is not None]}
+
+
+def player_to_document(player: Player) -> Document:
+    """
+    Convert one ``livetennisapi`` Player into a Haystack Document.
+
+    Tolerates sparse records: doubles teams and lower-tour players may miss country,
+    ranking, hand, backhand or birthday — only what exists is written.
+    """
+    name = player.name or "unknown"
+    bits: list[str] = []
+    if player.is_doubles_team:
+        bits.append("doubles team")
+    if player.country:
+        bits.append(str(player.country))
+    if player.tour:
+        # The record's own tour label is opaque by contract (e.g. "atp", "ATP",
+        # "juniors_boys") — shown as-is, never parsed.
+        bits.append(f"tour {player.tour}")
+    if player.ranking is not None:
+        rank = f"ranked #{player.ranking}"
+        if player.ranking_points is not None:
+            rank += f" ({player.ranking_points} pts)"
+        if player.ranking_movement in ("up", "down"):
+            rank += f", moving {player.ranking_movement}"
+        bits.append(rank)
+    plays = _HANDS.get(player.hand)
+    if plays:
+        backhand = _BACKHANDS.get(player.backhand)
+        bits.append(f"plays {plays}" + (f" with a {backhand}" if backhand else ""))
+    birthday = iso_or_none(player.birthday)
+    if birthday:
+        bits.append(f"born {birthday}")
+
+    content = f"{name} — {'; '.join(bits)}." if bits else f"{name}."
+
+    meta = {
+        "source": "livetennisapi",
+        "player_id": player.id,
+        "name": player.name,
+        "tour": player.tour,
+        "country": player.country,
+        "ranking": player.ranking,
+        "ranking_points": player.ranking_points,
+        "ranking_movement": player.ranking_movement,
+        "hand": player.hand,
+        "backhand": player.backhand,
+        "birthday": iso_or_none(player.birthday),
+        "is_doubles_team": player.is_doubles_team,
+    }
+    return Document(content=content, meta=meta)

livetennisapi_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: livetennisapi-haystack
+Version: 0.1.0
+Summary: Haystack 2.x integration for the Live Tennis API: live scores, matches and players as Documents
+Project-URL: Documentation, https://github.com/livetennisapi/livetennisapi-haystack#readme
+Project-URL: Issues, https://github.com/livetennisapi/livetennisapi-haystack/issues
+Project-URL: Source, https://github.com/livetennisapi/livetennisapi-haystack
+Author-email: Ben <ben@ben-is-a.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Agents,Haystack,Live Scores,RAG,Sports Data,Tennis
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.24.1
+Requires-Dist: livetennisapi>=1.0.2
+Description-Content-Type: text/markdown
+
+# livetennisapi-haystack
+
+[Haystack](https://haystack.deepset.ai) 2.x integration for the
+[Live Tennis API](https://livetennisapi.com): live scores, matches and players as Haystack
+`Document`s for RAG and agent pipelines.
+
+- **`LiveTennisMatchFetcher`** — live / upcoming / completed matches (optionally one match by
+  id, optionally filtered by tour) as `Document`s. `content` is a clean human-readable match
+  summary; `meta` carries the structured fields (ids, players, sets/games/points, server,
+  winner).
+- **`LiveTennisPlayerSearch`** — player search by name, ranked players first, same
+  `Document` shape.
+
+Built on the official [`livetennisapi`](https://pypi.org/project/livetennisapi/) Python
+client (retries, error mapping, typed models) — no hand-rolled HTTP.
+
+## Installation
+
+```bash
+pip install livetennisapi-haystack
+```
+
+You need a Live Tennis API key (free tier: 1000 requests/day, 30/min). Export it as an
+environment variable — the components read `LIVETENNISAPI_KEY` by default and never accept a
+plain-string key:
+
+```bash
+export LIVETENNISAPI_KEY="your-key"
+```
+
+## Usage
+
+### Standalone
+
+```python
+from livetennisapi_haystack import LiveTennisMatchFetcher
+
+fetcher = LiveTennisMatchFetcher()          # key from LIVETENNISAPI_KEY
+result = fetcher.run(status="live", limit=5)
+for doc in result["documents"]:
+    print(doc.content)
+    # e.g. "Carlos Alcaraz (ESP, #2) vs Jannik Sinner (ITA, #1) — match at Wimbledon,
+    #       grass court, round QF, best of 5. Live now. Score: sets 1-1, games 6-4, 3-6,
+    #       2-1, points 30-15. Carlos Alcaraz (ESP, #2) is serving."
+```
+
+### In a pipeline (runnable with only `LIVETENNISAPI_KEY`)
+
+```python
+from haystack import Pipeline
+
+from livetennisapi_haystack import LiveTennisMatchFetcher, LiveTennisPlayerSearch
+
+pipe = Pipeline()
+pipe.add_component("matches", LiveTennisMatchFetcher(limit=5))
+pipe.add_component("players", LiveTennisPlayerSearch(limit=3))
+
+result = pipe.run({"matches": {"status": "live"}, "players": {"query": "alcaraz"}})
+for doc in result["matches"]["documents"] + result["players"]["documents"]:
+    print("-", doc.content)
+```
+
+### RAG over live scores
+
+```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)
+```
+
+A complete runnable script lives at [`examples/live_demo.py`](examples/live_demo.py).
+
+## Behavior worth knowing
+
+- **403 tier wall**: when your key is valid but the plan does not unlock an endpoint, the
+  component returns a single readable `Document` (tagged `meta["error"] = "upgrade_required"`)
+  instead of raising — an agent can tell the user; a RAG pipeline can filter it out. All
+  other errors (bad key, network down, rate limit) still raise the official client's typed
+  exceptions.
+- **Sparse data is normal**: `score.server` is nullable (between points the feed may not
+  know who serves next — the summary simply omits the serving sentence), doubles teams have
+  no individual rankings and a null `data_completeness`, and points are strings
+  (`"0"`, `"15"`, `"30"`, `"40"`, `"AD"`). The components tolerate all of it.
+- **Serialization**: both components implement `to_dict`/`from_dict`; the API key is stored
+  as a `Secret` environment-variable reference, never as a value, so pipelines serialize
+  safely to YAML. Note that Haystack 3.0 refuses to deserialize third-party components
+  unless their module is allow-listed, so reload pipelines with
+  `Pipeline.loads(yaml_str, allowed_modules=["livetennisapi_haystack.match_fetcher", "livetennisapi_haystack.player_search"])`
+  (or `haystack.core.serialization.allow_deserialization_module(...)`).
+- **`tour` filter**: the API's documented `tour` query parameter is not yet exposed by
+  `livetennisapi` 1.0.2's `list_matches()`, so the component routes that one call through
+  the official client's transport layer (same auth/retries/error mapping).
+- **Sync only** for now: `run()` — no `run_async` yet, although the official client has an
+  async twin. Planned.
+
+## Parameters
+
+`LiveTennisMatchFetcher(api_key, status="live", tour=None, limit=10, base_url=None, timeout=30.0)`
+— `status`/`tour`/`limit` can be overridden per `run()`, and `run(match_id=...)` fetches a
+single match. `LiveTennisPlayerSearch(api_key, limit=10, base_url=None, timeout=30.0)` —
+`run(query, limit=None)`.
+
+## Development
+
+```bash
+pip install -e . pytest ruff
+pytest                    # unit tests, fully mocked, no network
+ruff check src tests examples
+LIVETENNISAPI_KEY=... pytest -m integration   # live tests, needs a key
+```
+
+## License
+
+`livetennisapi-haystack` is distributed under the terms of the
+[MIT](https://spdx.org/licenses/MIT.html) license.

livetennisapi_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+livetennisapi_haystack/__init__.py,sha256=oJxbEF_ELKOTSE-kQmLywonD53kZ7zzWsHaEJi4ohrg,187
+livetennisapi_haystack/_util.py,sha256=iUvwNLno6ih0egO7HF2rTlZ9ECq8lNlPj5c6UqvZbOI,1875
+livetennisapi_haystack/match_fetcher.py,sha256=BKygXaRTth_hZX3SMADZ_AA0xFf-6S9sWGmVxGV9me0,13137
+livetennisapi_haystack/player_search.py,sha256=eP4XFO1dX8VO74bZNnV0iYtV4Z0rpcLhPFxzRpRf-Lk,6604
+livetennisapi_haystack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+livetennisapi_haystack-0.1.0.dist-info/METADATA,sha256=4QPq-d5QG2yhDvkxFNile3XBvlQnrVUpveEUA8gAztQ,6821
+livetennisapi_haystack-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+livetennisapi_haystack-0.1.0.dist-info/licenses/LICENSE,sha256=Cj5QnNVv51nLuivjAbWOYUHLKtgDh0bqxZMo8NIL6BU,1060
+livetennisapi_haystack-0.1.0.dist-info/RECORD,,

livetennisapi_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

livetennisapi_haystack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.