# Public Release Guide

## Goal
- Publish the football prediction model for free.
- Keep the public scope explicitly limited to Spanish La Liga.
- Keep the public release simple, lightweight, and easy to run.
- Release only the champion model.
- Exclude other internal model lines, source-specific ingestion code, private infrastructure, and private data connectors.

## Publishing Recommendation
Publish on both:

1. Hugging Face
- Use this as the canonical home for the model artifact, model card, release notes, and quickstart.
- Best for versioned artifacts and simple public documentation.

2. Kaggle
- Use this as a mirror plus demo environment.
- Best for discoverability, quick notebooks, and public experimentation.

Recommended approach:
- Hugging Face = primary artifact registry
- Kaggle = public notebook/demo mirror
- GitHub = public code home for the bundle itself

Recommended source of truth:
- create the public repository from this public-release branch
- or export this bundle from this branch into a dedicated public repository

That avoids mixing in internal codepaths that are not meant for public use.

## Public Scope
Keep only:
- `la_liga_score_predictor` model artifact
- the three `.cbm` files used by the model artifact
- minimal inference code
- feature schema / sample input
- simple quickstart docs
- versioned release notes

Remove from the public package:
- other internal model lines
- source-specific ingestion code
- private environment variables
- cron / local pipeline scripts
- database code
- non-prediction application code
- monitoring outputs
- cache files
- any raw data that is not safe to redistribute

## Important Release Rule
Do not publish raw historical data unless redistribution rights are explicit.

If redistribution rights are unclear, publish only:
- model artifacts
- inference code
- feature schema
- sample or synthetic rows
- documentation

Do not publish large internal historical CSVs by default.
For a first public release, synthetic samples plus schema documentation are the safer choice.

That is the safer public release shape.

## What the Public Bundle Should Contain
Recommended bundle layout:

```text
football-predictor-public/
  README.md
  LICENSE
  CHANGELOG.md
  ARTIFACTS_SHA256.txt
  pyproject.toml
  requirements.txt
  smoke_test.py
  predict_one.py
  predict_batch.py
  demo_cli.py
  demo_notebook.ipynb
  sample_history.csv
  sample_fixtures.csv
  la_liga_score_predictor/
    __init__.py
    predictor.py
    feature_builder.py
    artifacts/
      la_liga_score_predictor.json
      home_goals_model.cbm
      away_goals_model.cbm
      outcome_model.cbm
```

## Public Prerequisites
For inference only, keep prerequisites minimal:

- Python `3.10+`
- `catboost`
- `numpy`
- `pandas`
- `scipy`

Suggested `requirements.txt`:

```txt
catboost==1.2.8
numpy==2.0.2
pandas==2.2.2
scipy==1.14.1
```

For most users:
- CPU is enough
- no GPU required
- local Python, Kaggle Notebook, Colab, or Hugging Face Space are all fine

## Easy Plug-and-Play Usage
The public release should support two simple usage paths.

### 1. Single Match Inference in Python

```python
from la_liga_score_predictor import LaLigaScorePredictor

predictor = LaLigaScorePredictor.from_defaults(
    dataset_csv_path="sample_history.csv"
)

result = predictor.predict_match(
    home_team="Athletic",
    away_team="Osasuna",
    match_date="2026-04-21",
)

print(result["predicted_score"])
print(result["result_probabilities"])
print(result["confidence_level"])
```

For a smaller response payload:

```python
simple_result = predictor.predict_match_simple(
    home_team="Athletic",
    away_team="Osasuna",
    match_date="2026-04-21",
)
```

Expected output fields:
- `predicted_score`
- `predicted_home_goals`
- `predicted_away_goals`
- `result_probabilities`
- `confidence_level`
- `confidence_score`
- `confidence_margin`
- `abstain_recommended`

### 2. Batch Prediction From CSV
Public release should also include one simple example script that:
- reads `sample_fixtures.csv`
- validates required columns
- predicts one row at a time
- writes predictions to `predictions_output.csv`

That is the easiest path for non-engineering users.

## Public Documentation Requirements
The public README should explain:

1. what the model predicts
2. what files are required
3. how to install dependencies
4. how to run one example prediction
5. how to run batch predictions from CSV
6. what the confidence fields mean
7. what the model does not do

## Public Positioning
Keep the public message simple:

- This is a pre-match football score prediction model for Spanish La Liga only.
- It predicts home goals, away goals, outcome probabilities, and confidence.
- It is built for structured pre-match features.
- It is not a live betting engine.
- It is not a guarantee tool.

## Versioning and Release Cadence
We plan to release new champion versions twice per month.

Recommended public version format:
- `2026.04.1`
- `2026.04.2`
- `2026.05.1`
- `2026.05.2`

Recommended cadence:
- Release A: between the 1st and 5th of the month
- Release B: between the 15th and 20th of the month

Every release should include:
- artifact files
- release notes
- metric summary
- feature schema version
- usage example

## Release Checklist

### Packaging
- [ ] Keep only the model artifact and its `.cbm` files
- [ ] Remove other internal model lines
- [ ] Remove source-specific ingestion references
- [ ] Remove cache, reports, and private outputs
- [ ] Add a minimal `requirements.txt`
- [ ] Add sample history and fixture CSVs
- [ ] Add a prediction example script
- [ ] Add a smoke test
- [ ] Add artifact checksums
- [ ] Add package metadata

### Documentation
- [ ] Add public `README.md`
- [ ] Add `CHAMPION_MODEL_MODEL_CARD.md`
- [ ] Add release notes template
- [ ] Add clear limitations and responsible-use note

### Validation Before Each Release
- [ ] artifact loads successfully in a clean environment
- [ ] single-row prediction example runs
- [ ] batch CSV example runs
- [ ] no private path, key, or DB dependency remains
- [ ] release notes match the shipped artifact

### Publishing
- [ ] push canonical bundle to Hugging Face
- [ ] push mirror dataset/notebook to Kaggle
- [ ] tag the release version
- [ ] attach release notes and metric summary

## What We Should Not Publish
- private `.env` values
- database credentials
- pipeline internals not needed for inference
- source-provider specific code or docs
- other internal experimental artifacts
- raw operational monitoring outputs

## Suggested Public Narrative
Use this framing:

> This release contains the champion pre-match football prediction model and a minimal inference bundle for local or notebook-based use. It predicts scoreline, outcome probabilities, and confidence from structured pre-match features. The release is free to use and is updated twice per month.

## Near-Term Execution Plan

### Phase 1: Prepare Public Bundle
- strip the repo down to public assets
- create minimal inference package
- create public sample input and quickstart

### Phase 2: Publish First Free Release
- publish on Hugging Face
- mirror on Kaggle
- include one notebook demo and one Python script demo

### Phase 3: Run Twice-Monthly Release Cycle
- freeze candidate
- validate offline
- export model artifact
- publish notes and updated files

## Recommended File Pairing
This file is the public release plan.

The companion technical file is:
- `MODEL_CARD.md`

That file should explain how the model works without exposing source-provider details or other internal logic that is not needed for public inference.