Cover Performance Analytics

Inspiration

Music creators can collect views, likes, comments, saves, and shares from social platforms, but those metrics do not automatically answer the practical question: What should I publish or test next?

Small datasets create an additional challenge. A cover with very few views can produce unusually high engagement rates and appear more successful than it really is. I wanted to build a system that combines deterministic analytics with AI interpretation while remaining transparent about evidence quality and data limitations.

What it does

Cover Performance Analytics is a bilingual Streamlit application for tracking and analyzing cover-song performance.

Before OpenAI Build Week, the application already supported:

cover metadata and performance snapshot tracking;
engagement and performance calculations;
growth and content-pattern analytics;
future cover candidate testing and history;
Turkish and English interfaces;
CSV and localized text report export.

During OpenAI Build Week, I added an AI Creator Coach powered by GPT-5.6 Sol.

The AI Creator Coach generates a structured report containing:

an executive summary;
strengths supported by evidence;
risks and mitigation suggestions;
prioritized recommended actions;
a next-cover strategy;
explicit data limitations.

How it works

The application does not ask the model to calculate metrics. Numerical calculations remain deterministic and are performed locally in Python.

The architecture follows this flow:

CSV performance data
↓
calculate_metrics()
↓
build_ai_creator_context()
↓
GPT-5.6 Sol through the Responses API
↓
Strict Structured Output
↓
validate_ai_creator_report()
↓
Streamlit AI Creator Coach

Python first prepares a compact, JSON-compatible context containing portfolio metrics, medians, top-cover evidence, category comparisons, and stable data-quality warnings.

GPT-5.6 Sol is instructed to:

use only the supplied context;
never invent or recalculate metrics;
avoid unsupported causal claims;
treat relationships as directional observations;
respect evidence_quality and evidence_flags;
treat low_view_sample as low-confidence evidence;
mention relevant data limitations;
return actionable recommendations in Turkish or English.

The response must conform to a strict JSON Schema and pass a local validator before it can be displayed in the application.

Evidence quality

An important part of the project is its handling of low-view outliers.

In the demo dataset, one cover has an extremely high performance score but only 300 views. Instead of hiding or changing the score, the deterministic context builder marks the observation with:

evidence_quality: low
evidence_flags: low_view_sample

The AI Creator Coach therefore treats this result as an early signal that requires additional testing, rather than presenting it as conclusive evidence.

The system also compares averages with more robust statistics such as medians, helping the model recognize when an outlier is distorting the portfolio summary.

Safety and cost controls

The AI integration includes several controls designed to prevent accidental requests, stale recommendations, and secret exposure:

API calls occur only after an explicit Generate or Regenerate button click.
Validated reports are cached in Streamlit session state.
Ordinary Streamlit reruns do not create additional API requests.
Reports become stale when filters, language, source data, or model settings change.
Stale reports are not displayed as current recommendations.
API keys are loaded from an ignored local Streamlit secrets file.
Secrets are never displayed, logged, added to the AI context, or stored in session state.
Missing configuration, invalid responses, and API failures are handled separately.
There are no automatic retries, background requests, or automatic model calls.

How I used Codex

Codex was used as the repository-level development agent throughout OpenAI Build Week.

It first performed a read-only architecture review of the existing application. The feature was then implemented through small, independently testable components:

a deterministic AI context builder;
evidence-quality detection for low-view samples;
a strict AI report contract and local validator;
an OpenAI Responses API service;
a bilingual Streamlit AI Creator Coach interface;
session-state caching and stale-report detection;
unit tests and submission documentation.

Codex also helped inspect the existing architecture, generate and extend tests, run compile checks, review Git diffs, diagnose failures, and repair issues iteratively.

The feature was deliberately developed in several focused commits instead of one large change, making each architectural layer easier to review and validate.

Challenges

The main technical challenge was preventing a mathematically valid but low-sample result from becoming an overconfident AI recommendation.

The solution was to keep calculations deterministic, expose evidence-quality metadata, constrain the model to bounded context, require strict structured output, and validate every report locally before rendering it.

A second challenge was integrating AI into Streamlit without creating repeated paid requests during ordinary reruns. A deterministic SHA-256 cache key based on the context, language, and model allows valid reports to survive reruns while detecting when a report has become stale.

Accomplishments

Added grounded AI interpretation without replacing deterministic analytics.
Preserved the existing modular Streamlit architecture and V3 functionality.
Implemented strict Structured Outputs and local response validation.
Added Turkish and English AI coaching reports.
Added evidence-quality handling for low-view performance outliers.
Prevented unnecessary API calls through explicit generation, caching, and stale-report detection.
Protected API secrets from Git, logs, prompts, and session state.
Completed 63 passing unit tests.
Successfully completed real Turkish and English GPT-5.6 Sol smoke tests.
Delivered the main Build Week feature through four focused and reviewable Git commits.

What I learned

I learned how to combine deterministic analytics and generative AI without making the model the source of truth for numerical calculations.

The most important design principle was to separate responsibilities:

Python calculates and structures the evidence.
GPT-5.6 interprets the bounded evidence.
A local validator decides whether the response is safe to display.
Streamlit manages explicit user interaction, caching, and presentation.

I also learned that Codex is most effective when used iteratively: architecture review, narrowly scoped implementation, testing, validation, and human review produced a more reliable result than requesting the entire feature in one large step.