JamJamzz/ceview-demand-prediction-model

Ceview AI

A Python Gradio application for the CeView Module 2 Market Radar forecasting model on Hugging Face Spaces. The PyTorch integration uses the supplied complete model.pt export to forecast 12 weeks of tourism search interest from 52 weeks of Google Trends and calendar features, with target market and tourism category identifiers. The Gradio form and /forecast API return actual model predictions, 4-week and 12-week demand averages, and model version metadata. The export has provisional status.

Local development

Use Python 3.12.12 for parity with ZeroGPU. From the project root in PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe app.py

Open the local URL printed by Gradio. See commands for checks and Linux commands.

Hugging Face Spaces

Create a Space using the Gradio SDK and upload these files at its repository root:

• —app.py
• —inference.py
• —requirements.txt
• —README.md
• —The complete ceview_C_seed42_provisional_611011893608/ directory, including model.pt, protocol.json, metrics.json, and the model/ class definitions.

Keep the directory name and structure unchanged. Paths resolve relative to the app, so no Windows paths need editing. Keep .venv, caches, and credentials out of the upload. The Space uses the README metadata to select the SDK and entry point, and installs additional dependencies from the root requirements file. See the official configuration reference and dependency guide.

Keep sdk_version and the Gradio version in requirements.txt synchronized. Choose ZeroGPU in Space settings to use @spaces.GPU. The app loads the model at startup and places it on CUDA when available. On a CPU machine, it uses CPU instead. The decorator has no effect outside ZeroGPU. See the official ZeroGPU guide for runtime compatibility and GPU allocation behavior. A local CPU test does not verify the hosted ZeroGPU runtime. Deployment has not been performed. GitHub Actions provides checks only, with no automatic deployment.

Input and output

Select a market and category, then paste a JSON array of exactly 52 rows, oldest first. Each row contains [trend_scaled, week_sin, week_cos] in that order. Supply already preprocessed history: trend indices divided by 100 and the same ISO-week calendar encodings used in training. This app does not collect Trends data or construct calendar features. Histories must be complete, consecutive, and consistent with the export's preprocessing.md. Without input dates, the app cannot verify missing weeks or calendar alignment.

The response includes weekly_forecasts with week_ahead values 1 through 12 and google_trends values clamped to 0-100. mean_demand_4_weeks averages the first four clamped values; mean_demand_12_weeks averages all twelve. These are search-interest indices, not visitor counts or calibrated cross-market demand volumes.

model identifies the export, SHA-256 checksum, architecture, seed, best epoch, protocol version, dataset version, and provisional status.

Model integration

The model contract records the confirmed requirements, including 4-week and 12-week demand summaries and model version metadata. The owner's export contains a serialized full model, not a best.pt state dictionary. Only this fixed, trusted bundle is loaded. The app does not accept checkpoint uploads. See the active task for validation scope.