livetennisapi-haystack 0.1.0__tar.gz

livetennisapi_haystack-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

livetennisapi_haystack-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage

livetennisapi_haystack-0.1.0/BUILD_PLAN.md

@@ -0,0 +1,104 @@
+# BUILD_PLAN — livetennisapi-haystack
+
+> **Status (2026-07-24): ALL UNITS DONE.** BUILD-001..004 landed as commits 1-4; BUILD-005
+> verification passed (clean-venv install, 31 unit tests + 2 live integration tests green,
+> ruff clean, live pipeline smoke incl. doubles/null-server/tour-filter/serialization
+> round-trip, key-leak sweep 0 hits) and surfaced one real-data fix (points [None, None] on
+> completed matches), landed as commit 5. Verification finding: Haystack 3.0 requires
+> `allowed_modules=` to deserialize third-party components — documented in README.
+> Not done on purpose (out of scope by directive): PyPI publish, GitHub repo, catalog PR.
+
+## Build target & source of truth
+Haystack 2.x integration package for the Live Tennis API. Greenfield standalone repo at
+`/var/tmp/haystack-build/livetennisapi-haystack`. No `PLAN.md`; source of truth is the task
+directive (explicit spec: components, Secret handling, tests, README, catalog-entry draft,
+verify steps) plus:
+- Official client: `livetennisapi` 1.0.2 (PyPI == local checkout
+  `~/Documents/ben-is-a-dev/livetennisapi-oss/livetennisapi-python`) — reused, no hand-rolled HTTP.
+- OpenAPI: `~/Documents/ben-is-a-dev/livetennisapi-oss/openapi/openapi.yaml`.
+- Haystack conventions modeled on July-2026 catalog merges: DDGS (#548, `integrations/ddgs.md`),
+  Linkup (#549, component source `linkup_websearch.py` + tests + pyproject in
+  deepset-ai/haystack-core-integrations), Perseus Vault (#538, third-party frontmatter, MIT).
+
+## Summary
+Ready to build as specified. [FACT] Haystack latest on PyPI is 3.0.0 (2026-07); recent catalog
+entries still declare `version: Haystack 2.0` and the `@component`/`Secret` API is unchanged in
+the 3.0 docs — pin `haystack-ai>=2.24.1` (Linkup's pin) and verify against what installs.
+[FACT] client v1.0.2 `list_matches()` does not expose the API's documented `tour` query param
+(client.py:121) — tour support must go through the client's transport (`_request`), a deliberate,
+commented deviation (never hand-rolled HTTP). Top risks: Haystack 3.0 API drift (verified by
+tests), live smoke dependent on what's actually on court (report what's real).
+
+## Build units (ordered)
+
+### BUILD-001 scaffold
+- Delivers: git repo, `pyproject.toml` (hatchling, MIT, deps `haystack-ai>=2.24.1`,
+  `livetennisapi>=1.0.2`), `LICENSE`, `.gitignore`, `src/livetennisapi_haystack/{__init__.py,py.typed}`,
+  README stub. Depends-on: —.
+- Acceptance: `pip install -e .` succeeds in clean venv; `import livetennisapi_haystack` works.
+- Output strategy: one-shot. Becomes commit 1.
+
+### BUILD-002 LiveTennisMatchFetcher + tests
+- Delivers: `src/livetennisapi_haystack/match_fetcher.py` — `@component` class; init
+  `api_key: Secret = Secret.from_env_var("LIVETENNISAPI_KEY")`, `status`, `tour`, `limit`,
+  `base_url`, `timeout`; `warm_up()` lazy `LiveTennisAPI`; `run(status, tour, limit, match_id)`
+  → `documents: list[Document]` (content = human-readable summary; meta = ids/players/scores,
+  JSON-safe). Handles: null `score.server` (omit serving clause), doubles/null
+  `data_completeness`, string points, completed+winner, `UpgradeRequired` → one readable-message
+  Document (`meta.error="upgrade_required"`), `NotFound` on match_id → `[]` + warning.
+  `to_dict`/`from_dict` via `default_to_dict`/`default_from_dict` + `deserialize_secrets_inplace`.
+  Tests: `tests/test_match_fetcher.py`, mocked client, no net.
+- Depends-on: BUILD-001.
+- Acceptance: pytest green incl. null-server, doubles, 403-message, tour, serialization
+  round-trip cases.
+- Output strategy: staged (component skeleton → summary builder → error paths → tests).
+  Becomes commit 2.
+
+### BUILD-003 LiveTennisPlayerSearch + tests
+- Delivers: `src/livetennisapi_haystack/player_search.py` — same shape; `run(query, limit)` →
+  `documents`. Tests incl. empty result + 403. Depends-on: BUILD-001.
+- Acceptance: pytest green. Output strategy: one-shot. Becomes commit 3.
+
+### BUILD-004 README + example + catalog-entry draft
+- Delivers: full `README.md` (runnable pipeline example), `examples/live_demo.py` (env-var key,
+  builds a real Pipeline, prints Documents), `catalog-entry.md` matching current
+  `integrations/*.md` frontmatter exactly (third-party author form per Perseus Vault #538).
+- Depends-on: BUILD-002/003. Acceptance: example runs against live API in smoke step;
+  frontmatter fields match the fetched templates field-for-field. One-shot. Becomes commit 4.
+
+### BUILD-005 verify (no new product code)
+- Clean venv (TMPDIR=/var/tmp/haystack-build/tmp): install, pytest, ruff, live smoke via
+  `examples/live_demo.py` (key from env only), key-leak sweep over tree + git history (0 hits).
+- Acceptance: all green; real live output captured for the report. Fixes, if any, land as
+  their own commits.
+
+## Conventions to follow
+- Component shape: `linkup_websearch.py` (fetched ref): `@component` class, Secret default from
+  env var (never plain string), `warm_up()` lazy client, `@component.output_types`,
+  `documents` output naming, module-level `logger = logging.getLogger(__name__)`.
+- Tests: `test_linkup_websearch.py` (fetched ref): class-based, `MagicMock` client injected via
+  `_client`, `component_to_dict`/`component_from_dict` assertions, `@pytest.mark.integration`
+  gated on env key.
+- Packaging: Linkup `pyproject.toml` (hatchling, ruff config, pytest markers) minus monorepo
+  hatch-vcs; static version.
+- Catalog entry: `ddgs.md`/`linkup.md` frontmatter + section order; third-party `authors:` per
+  `perseus-vault-haystack.md`; MIT license line per Perseus.
+- Client reuse: only `livetennisapi` public API, except the documented `tour` param (OpenAPI
+  openapi.yaml:302-315) via `client._request` — called out in code.
+
+## Open questions & assumptions
+- [ASSUMPTION][blocking→resolved by directive] Task is an explicit approved build+verify
+  directive; proceeding through Phase 2 without an interactive gate.
+- [ASSUMPTION] Sync-only `run` (no `run_async`): the official client has an async twin, but
+  httpx.AsyncClient lifecycle across event loops is a real cost; conventions allow sync-only
+  components. Noted as future work in README.
+- [ASSUMPTION] `haystack-ai` resolves to 3.0.0; `@component`/Secret API verified unchanged by
+  the test suite, and catalog `version:` stays "Haystack 2.0" per current merged entries.
+- [ASSUMPTION] 403 policy: an `UpgradeRequired` becomes a single Document carrying the client's
+  readable tier message (meta-tagged `error`) rather than an exception — per the directive
+  "readable message, not a crash"; other errors still raise (a dead network should fail loud).
+
+## Handoff
+Build, then `/full-review`. Most relevant personas: `/code-logic-review` (summary builder edge
+cases), `/qa-automation` (mock coverage vs live truths), `/security-audit` (secret handling,
+key-leak). No UI — browser-driven QA not applicable.

livetennisapi_haystack-0.1.0/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.

livetennisapi_haystack-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/catalog-entry.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.

livetennisapi_haystack-0.1.0/examples/live_demo.py

@@ -0,0 +1,50 @@
+"""Live demo: a real Haystack pipeline over the Live Tennis API.
+
+Needs only LIVETENNISAPI_KEY in the environment:
+
+    export LIVETENNISAPI_KEY="your-key"
+    python examples/live_demo.py
+
+Fetches live matches (falling back to upcoming, then completed, if no tennis is
+on right now) plus a player search, and prints every Document.
+"""
+
+import os
+import sys
+
+from haystack import Pipeline
+
+from livetennisapi_haystack import LiveTennisMatchFetcher, LiveTennisPlayerSearch
+
+
+def main() -> int:
+    if not os.environ.get("LIVETENNISAPI_KEY"):
+        print("Set LIVETENNISAPI_KEY first.", file=sys.stderr)
+        return 1
+
+    pipe = Pipeline()
+    pipe.add_component("matches", LiveTennisMatchFetcher(limit=10))
+    pipe.add_component("players", LiveTennisPlayerSearch(limit=3))
+
+    docs = []
+    for status in ("live", "upcoming", "completed"):
+        result = pipe.run({"matches": {"status": status}, "players": {"query": "alcaraz"}})
+        docs = result["matches"]["documents"]
+        if docs:
+            print(f"== {status} matches ({len(docs)}) ==")
+            break
+        print(f"== no {status} matches right now ==")
+
+    for doc in docs:
+        print("-", doc.content)
+        print("  meta:", {k: v for k, v in doc.meta.items() if v is not None})
+
+    player_docs = result["players"]["documents"]
+    print(f"\n== player search 'alcaraz' ({len(player_docs)}) ==")
+    for doc in player_docs:
+        print("-", doc.content)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())