Metadata-Version: 2.4
Name: gaffers-guide
Version: 2.0.2
Summary: Tactical intelligence and computer vision pipeline for football analytics.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: redis>=5.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scipy>=1.13.0
Requires-Dist: opencv-python<4.12.0,>=4.10.0
Requires-Dist: supervision>=0.22.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: openai>=1.55.0
Requires-Dist: google-generativeai>=0.8.0
Requires-Dist: huggingface_hub>=0.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: vision
Requires-Dist: torch>=2.0.0; extra == "vision"
Requires-Dist: ultralytics>=8.0.0; extra == "vision"
Requires-Dist: sahi>=0.11.0; extra == "vision"
Provides-Extra: spatial
Provides-Extra: tactical
Requires-Dist: scikit-learn>=1.3.0; extra == "tactical"
Provides-Extra: io
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Provides-Extra: full
Requires-Dist: gaffers-guide[dev,tactical,vision]; extra == "full"

# Gaffers Guide SDK

Gaffers Guide SDK is a modular sports computer vision library for tracking, spatial mapping, and tactical analysis workflows. It is designed as a pip-installable Python SDK with lightweight base modules and optional heavy ML vision components.

## Installation

Base install (Parsers & IO):

```bash
pip install gaffers-guide
```

Full ML install (YOLO/SAHI Vision):

```bash
pip install "gaffers-guide[vision]"
```

## Quickstart & Usage

Spatial Mapping (No ML required):

```python
import numpy as np
from gaffers_guide.spatial import HomographyEngine

corners_px = np.array(
    [[120.0, 50.0], [1800.0, 45.0], [1900.0, 1030.0], [80.0, 1035.0]],
    dtype=np.float64,
)

engine = HomographyEngine()
mapping = engine.fit(corners_px, frame_shape=(1080, 1920))
pitch_point = mapping.pixel_to_pitch((960.0, 540.0))
print(pitch_point.to_dict())
```

Tactical IO:

```python
from pathlib import Path
from gaffers_guide.io import parse_tracking_json

tracking = parse_tracking_json(Path("tracking_data.json"))
print(tracking.keys())
```

The Full Engine:

```python
from pathlib import Path
from gaffers_guide.pipeline import MatchAnalysisPipeline
from gaffers_guide.pipeline.config import PipelineConfig

pipeline = MatchAnalysisPipeline.from_profile("balanced")
report_path = pipeline.process_video(
    PipelineConfig(
        video=Path("match.mp4"),
        output_dir=Path("output"),
        quality_profile="balanced",
    )
)
print(report_path)
```
