Upload 27 files

app_pages/comparison.py

@@ -0,0 +1,416 @@
+import os
+import json
+import uuid
+import logging
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+import streamlit as st
+
+from services.video_analyzer import analyze_multiple_videos
+from services.comparison import generate_comparison_summary
+from database import insert_comparison_result, get_all_comparisons
+
+
+# ---------- Logging Setup ----------
+
+LOGGER_NAME = "app_pages.comparison"
+logger = logging.getLogger(LOGGER_NAME)
+if not logger.handlers:
+    logging.basicConfig(
+        level=os.environ.get("LOG_LEVEL", "INFO"),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+logger.setLevel(os.environ.get("LOG_LEVEL", "INFO"))
+
+
+def _log_exception(context: str, exc: Exception) -> None:
+    """Log exceptions with context and show a clean UI error."""
+    logger.exception("Exception in %s: %s", context, exc)
+    st.error(f"{context} failed: {exc}")
+
+
+def _rerun_analyses(analyses: List[Dict[str, Any]]) -> str:
+    """Stable fingerprint of analyses to avoid recomputation across reruns."""
+    try:
+        
+        slim = []
+        for item in analyses or []:
+            slim.append({
+                "video_name": item.get("video_name"),
+                # Avoid huge or non-deterministic blobs like thumbnails
+                "analysis": item.get("analysis", {}),
+            })
+        return json.dumps(slim, sort_keys=True, ensure_ascii=False)
+    except Exception as e:
+        _log_exception("_rerun_analyses", e)
+        # Fallback: random to force recompute
+        return str(uuid.uuid4())
+
+
+# ---------- Helpers ----------
+
+def _mean_effectiveness(metrics):
+    """Compute average effectiveness score from e.g. '7/10' style values."""
+    scores = []
+    for m in metrics or []:
+        try:
+            scores.append(int(str(m.get("effectiveness_score", "0/10")).split("/")[0]))
+        except Exception:
+            # Log and skip bad value
+            logger.debug("Bad effectiveness_score value: %s", m)
+            pass
+    return round(sum(scores) / len(scores), 2) if scores else 0.0
+
+
+def compare_analyses(analyses):
+    """Build a structured dict from analyses for tabular display."""
+    comparison = {
+        "hooks": [],
+        "frameworks": [],
+        "audiences": [],
+        "metrics_summary": [],
+        "improvements": []
+    }
+    for item in analyses:
+        try:
+            name = item["video_name"]
+            analysis = item["analysis"]
+
+            hook = analysis.get("hook", {}) or {}
+            comparison["hooks"].append({
+                "video": name,
+                "hook_text": hook.get("hook_text"),
+                "principle": hook.get("principle")
+            })
+
+            comparison["frameworks"].append({
+                "video": name,
+                "framework_analysis": analysis.get("framework_analysis")
+            })
+
+            va = analysis.get("video_analysis", {}) or {}
+            comparison["audiences"].append({
+                "video": name,
+                "audience": va.get("target_audience")
+            })
+
+            metrics = va.get("video_metrics", []) or []
+            avg = _mean_effectiveness(metrics)
+            comparison["metrics_summary"].append({
+                "video": name,
+                "avg_score": avg
+            })
+
+            comparison["improvements"].append({
+                "video": name,
+                "recommendations": analysis.get("timestamp_improvements", []) or []
+            })
+        except Exception as e:
+            _log_exception("compare_analyses (per-item)", e)
+    return comparison
+
+
+def _arrow_safe_df(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Make dataframe Arrow-compatible for Streamlit:
+    - Replace NaN with empty strings
+    - Coerce to string to avoid mixed object dtype issues
+    """
+    try:
+        return df.fillna("").astype(str)
+    except Exception as e:
+        _log_exception("_arrow_safe_df", e)
+        return df  # last resort (may still error later)
+
+
+def _ensure_state_keys():
+    """Initialize session_state keys used in this page."""
+    defaults = {
+        "comparison_prompt": "Compare these videos",
+        "analyses": None,
+        "summary": None,
+        "comparison_dict": None,
+        "_analyses_fp": None,
+        "_run_no": 0,
+        "_last_action": None,
+        "_last_tab": None,
+    }
+    for k, v in defaults.items():
+        if k not in st.session_state:
+            st.session_state[k] = v
+
+
+def _log_run_header(selected_tab: str):
+    """Log a trace line at every rerun to make lifecycle obvious."""
+    st.session_state["_run_no"] = int(st.session_state.get("_run_no", 0)) + 1
+    run_no = st.session_state["_run_no"]
+    analyses_present = st.session_state.get("analyses") is not None
+    summary_present = st.session_state.get("summary") is not None
+    comp_present = st.session_state.get("comparison_dict") is not None
+    last_action = st.session_state.get("_last_action")
+    logger.info(
+        "RERUN #%d | tab=%s | analyses=%s | summary=%s | table=%s | last_action=%s",
+        run_no,
+        selected_tab,
+        analyses_present,
+        summary_present,
+        comp_present,
+        last_action,
+    )
+
+
+
+def _save_comparison_callback():
+    """Button callback to save comparison to DB exactly once per click."""
+    try:
+        analyses = st.session_state.get("analyses")
+        comparison_dict = st.session_state.get("comparison_dict")
+        summary = st.session_state.get("summary")
+
+        logger.info("Save callback invoked | analyses=%s | table=%s | summary=%s",
+                    analyses is not None, comparison_dict is not None, summary is not None)
+
+        if not analyses or not comparison_dict or summary is None:
+            st.warning("Nothing to save yet. Please run a comparison first.")
+            logger.warning("Save aborted: missing data (analyses/table/summary).")
+            return
+
+        video_names = [item["video_name"] for item in analyses]
+        thumbnails = {item["video_name"]: item.get("thumbnail", "") for item in analyses}
+
+        logger.info("Inserting comparison_result | videos=%s", video_names)
+        insert_comparison_result(
+            video_name="comparison_result",
+            video_names=video_names,
+            user_prompt=st.session_state.get("comparison_prompt", ""),
+            response={"comparison_table": comparison_dict, "summary": summary},
+            thumbnails=thumbnails
+        )
+        st.success("Comparison saved to database!")
+        st.session_state["_last_action"] = "saved_to_db"
+        logger.info("Save completed successfully.")
+
+    except Exception as e:
+        _log_exception("_save_comparison_callback", e)
+
+
+# ---------- Page ----------
+
+def comparison_page():
+    _ensure_state_keys()
+
+    selected_tab = st.sidebar.radio("Select Mode", ["Comparison", "History"], index=0, key="tab_radio")
+
+
+    if st.session_state.get("_last_tab") != selected_tab:
+        st.session_state["_last_tab"] = selected_tab
+    _log_run_header(selected_tab)
+
+    if selected_tab == "Comparison":
+        st.subheader("Video Comparison")
+
+      
+        num_videos = st.slider("Select Number of Videos to Compare", 2, 5, 2, key="num_videos_slider")
+
+        
+        uploaded_videos = []
+        for i in range(num_videos):
+            try:
+                file = st.file_uploader(
+                    f"Upload Video {i+1}",
+                    type=["mp4", "mov", "avi", "mkv"],
+                    key=f"video_{i}"
+                )
+                if file:
+                    uploaded_videos.append(file)
+            except Exception as e:
+                _log_exception(f"file_uploader[{i}]", e)
+
+        # Run comparison
+        if st.button("Run Comparison", use_container_width=True, key="run_comparison_btn"):
+            logger.info("Run Comparison clicked | uploaded=%d / expected=%d", len(uploaded_videos), num_videos)
+            if len(uploaded_videos) < num_videos:
+                st.error("Please upload all videos before running comparison.")
+                logger.warning("Run Comparison aborted: insufficient uploads.")
+            else:
+                try:
+                    with st.spinner("Analyzing videos..."):
+                        analyses = analyze_multiple_videos(uploaded_videos)
+                        st.session_state["analyses"] = analyses
+                        st.session_state["_analyses_fp"] = _rerun_analyses(analyses)
+                        st.session_state["summary"] = None
+                        st.session_state["comparison_dict"] = None
+                        logger.info("Analyses computed. Set rerun and cleared summary/table.")
+                except Exception as e:
+                    _log_exception("analyze_multiple_videos", e)
+
+        
+        analyses = st.session_state.get("analyses")
+        if analyses:
+            st.divider()
+            st.subheader("Comparison")
+
+            current_fp = _rerun_analyses(analyses)
+            cached_fp = st.session_state.get("_analyses_fp")
+
+            # ---- Summary ----
+            st.markdown("#### Comparison Summary")
+            try:
+                if st.session_state.get("summary") is None or current_fp != cached_fp:
+                    logger.info("Generating summary (fp changed? %s)", current_fp != cached_fp)
+                    with st.spinner("Generating comparison..."):
+                        summary = generate_comparison_summary(
+                            analyses,
+                            st.session_state.get("comparison_prompt", "Compare these videos")
+                        )
+                    st.session_state["summary"] = summary
+                    st.session_state["_analyses_fp"] = current_fp
+                else:
+                    logger.info("Reusing cached summary.")
+                st.markdown(st.session_state["summary"])
+            except Exception as e:
+                _log_exception("generate_comparison_summary", e)
+
+            # ---- Structured Comparison ----
+            st.markdown("#### Structured Comparison")
+            try:
+                if st.session_state.get("comparison_dict") is None or current_fp != cached_fp:
+                    logger.info("Building comparison table (fp changed? %s)", current_fp != cached_fp)
+                    comparison = compare_analyses(analyses)
+
+                    
+                    comparison_dict = {}
+                    for hook, fw, aud, met in zip(
+                        comparison["hooks"],
+                        comparison["frameworks"],
+                        comparison["audiences"],
+                        comparison["metrics_summary"]
+                    ):
+                        video = hook["video"]
+                        comparison_dict[video] = {
+                            "Hook Text": hook.get("hook_text", ""),
+                            "Principle": hook.get("principle", ""),
+                            "Framework Analysis": fw.get("framework_analysis", ""),
+                            "Target Audience": aud.get("audience", ""),
+                            "Avg Score": met.get("avg_score", ""),
+                        }
+
+                    st.session_state["comparison_dict"] = comparison_dict
+                    st.session_state["_analyses_fp"] = current_fp
+                else:
+                    logger.info("Reusing cached comparison table.")
+
+                df_horizontal = pd.DataFrame(st.session_state["comparison_dict"])
+                df_display = _arrow_safe_df(df_horizontal.copy())
+                st.dataframe(df_display, use_container_width=True)
+
+                csv_data = df_horizontal.to_csv(index=True).encode("utf-8")
+                st.download_button(
+                    "Download CSV",
+                    data=csv_data,
+                    file_name="comparison_results.csv",
+                    mime="text/csv",
+                    use_container_width=True,
+                    key="download_current_csv_btn"
+                )
+            except Exception as e:
+                _log_exception("Structured Comparison section", e)
+
+            st.button(
+                "Save to DB",
+                use_container_width=True,
+                key="save_to_db_btn",
+                on_click=_save_comparison_callback
+            )
+
+            if st.session_state.get("_last_action") == "saved_to_db":
+                st.info("Saved to DB")
+
+        else:
+            logger.info("No analyses in session_state yet.")
+
+    else:
+        # ---------- History ----------
+        logger.info("Entering History tab.")
+        try:
+            history_items = get_all_comparisons(limit=20)
+            logger.info("Fetched %d history items.", len(history_items) if history_items else 0)
+        except Exception as e:
+            _log_exception("get_all_comparisons", e)
+            history_items = []
+
+        if history_items:
+            # Titles for sidebar selection
+            try:
+                titles = [
+                    f"{item['video_name']} ({item['created_at'].strftime('%Y-%m-%d %H:%M')})"
+                    for item in history_items
+                ]
+            except Exception:
+                titles = [
+                    f"{item.get('video_name', 'comparison_result')} ({item.get('created_at')})"
+                    for item in history_items
+                ]
+
+            try:
+                selected = st.sidebar.radio("History Items", titles, index=0, key="history_select_radio")
+                idx = titles.index(selected)
+                selected_data = history_items[idx]
+                logger.info("History selection: index=%d title=%s", idx, selected)
+            except Exception as e:
+                _log_exception("History selection radio", e)
+                selected_data = history_items[0]
+
+            st.subheader("Comparison Result")
+
+    
+            try:
+                if "video_names" in selected_data:
+                    st.markdown("### Compared Videos")
+                    cols = st.columns(len(selected_data["video_names"]))
+                    for i, name in enumerate(selected_data["video_names"]):
+                        with cols[i]:
+                            thumb = selected_data.get("thumbnails", {}).get(name, "")
+                            if thumb:
+                                st.image("data:image/jpeg;base64," + thumb, width=120)
+                            st.caption(name)
+            except Exception as e:
+                _log_exception("Rendering thumbnails", e)
+
+            # Response content
+            response = selected_data.get("response", {}) or {}
+
+            # Summary
+            try:
+                if "summary" in response:
+                    st.markdown("### Comparison Summary")
+                    st.markdown(response["summary"])
+            except Exception as e:
+                _log_exception("Rendering history summary", e)
+
+            # Table
+            try:
+                if "comparison_table" in response:
+                    st.markdown("### Structured Comparison")
+                    df_hist = pd.DataFrame(response["comparison_table"])
+                    df_hist_display = _arrow_safe_df(df_hist.copy())
+                    st.dataframe(df_hist_display, use_container_width=True)
+
+                    csv_hist = df_hist.to_csv(index=True).encode("utf-8")
+                    st.download_button(
+                        "Download CSV",
+                        data=csv_hist,
+                        file_name="past_comparison.csv",
+                        mime="text/csv",
+                        use_container_width=True,
+                        key="download_history_csv_btn"
+                    )
+            except Exception as e:
+                _log_exception("Rendering history table", e)
+
+        else:
+            st.sidebar.info("No saved comparisons yet.")
+            st.info("No saved history available.")
+            logger.info("History tab: no items.")
+

app_pages/script_generator.py

@@ -0,0 +1,155 @@
+import os
+import tempfile
+import pandas as pd
+import streamlit as st
+
+from services.script_generator import generate_scripts
+from utils.video import get_video_thumbnail_base64
+from components.display_variations import display_script_variations
+from database import insert_script_result, get_all_scripts
+
+def generator_page():
+    selected_tab = st.sidebar.radio("Select Mode", ["Script Generator", "History"], index=0)
+
+    if selected_tab == "Script Generator":
+        st.subheader("Script Generator")
+
+        uploaded_video = st.file_uploader(
+            "Upload Video or ZIP (max 3 videos)", 
+            type=['mp4','mov','avi','mkv','zip']
+        )
+        script_duration = st.slider("Script Duration (seconds)", 0, 180, 60, 5)
+        num_scripts = st.slider("Number of Scripts", 1, 5, 3)
+
+        st.markdown("Additional Information")
+        offer_details = st.text_area("Offer Details", placeholder="e.g., Solar installation with $0 down payment...")
+        target_audience = st.text_area("Target Audience", placeholder="e.g., 40+ homeowners with high electricity bills...")
+        specific_hooks = st.text_area("Specific Hooks to Test", placeholder="e.g., Government rebate angle...")
+        additional_context = st.text_area("Additional Context", placeholder="Compliance requirements, brand guidelines...")
+
+        script_button = st.button("Generate Scripts", use_container_width=True)
+        if script_button and uploaded_video:
+            with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(uploaded_video.name)[1]) as tmp:
+                tmp.write(uploaded_video.read())
+                video_path = tmp.name
+            with st.spinner("Generating scripts..."):
+                st.session_state.setdefault("scripts", [])
+                result = generate_scripts(
+                    video_path,
+                    offer_details,
+                    target_audience,
+                    specific_hooks,
+                    additional_context,
+                    num_scripts=num_scripts,
+                    duration=script_duration
+                )
+                if result and "script_variations" in result:
+                    st.session_state["scripts"].append({
+                        "prompt_used": "Initial Generation",
+                        "variations": result["script_variations"]
+                    })
+                    st.session_state["video_name"] = uploaded_video.name
+                    st.session_state["video_path"] = video_path
+                    st.session_state["thumbnail"] = get_video_thumbnail_base64(video_path)
+                    st.session_state["meta"] = {
+                        "offer_details": offer_details,
+                        "target_audience": target_audience,
+                        "specific_hook": specific_hooks,
+                        "additional_context": additional_context
+                    }
+
+        if "scripts" in st.session_state and st.session_state["scripts"]:
+            for round_idx, round_data in enumerate(st.session_state["scripts"], 1):
+                st.markdown(f"### Generation Round {round_idx}")
+                st.text_input("Prompt used:", round_data["prompt_used"], disabled=True, key=f"prompt_{round_idx}")
+                for i, variation in enumerate(round_data["variations"], 1):
+                    st.markdown(f"#### Variation {i}: {variation.get('variation_name','Var')}")
+                    df = pd.DataFrame(variation.get("script_table", []))
+                    st.table(df)
+
+            st.divider()
+            save_button = st.button("Save to DB", use_container_width=True)
+            if save_button:
+                try:
+                    insert_script_result(
+                        video_name=st.session_state.get("video_name", "unknown"),
+                        offer_details=st.session_state["meta"].get("offer_details", ""),
+                        target_audience=st.session_state["meta"].get("target_audience", ""),
+                        specific_hook=st.session_state["meta"].get("specific_hook", ""),
+                        additional_context=st.session_state["meta"].get("additional_context", ""),
+                        response=st.session_state["scripts"],
+                        thumbnail=st.session_state.get("thumbnail", "")
+                    )
+                    st.success("Scripts saved to database!")
+                except Exception as e:
+                    st.error(f"Failed to save scripts: {e}")
+
+            st.subheader("Generate More Scripts")
+            more_num = st.slider("How many more scripts?", 1, 5, 1, key="more_scripts_slider")
+            more_prompt = st.text_area("Required Prompt", placeholder="Add specific guidance")
+            if st.button("Generate More Scripts", use_container_width=True):
+                if not more_prompt.strip():
+                    st.error("Please provide a prompt before generating more scripts.")
+                else:
+                    video_path = st.session_state.get("video_path")
+                    if not video_path:
+                        st.error("No video available. Please upload again.")
+                    else:
+                        with st.spinner("Generating more scripts..."):
+                            extra_result = generate_scripts(
+                                video_path,
+                                st.session_state["meta"]["offer_details"],
+                                st.session_state["meta"]["target_audience"],
+                                st.session_state["meta"]["specific_hook"],
+                                st.session_state["meta"]["additional_context"] + "\n\n" + more_prompt,
+                                num_scripts=more_num,
+                                duration=script_duration
+                            )
+                            if extra_result and "script_variations" in extra_result:
+                                st.session_state["scripts"].append({
+                                    "prompt_used": more_prompt,
+                                    "variations": extra_result["script_variations"]
+                                })
+
+    else:
+        history_items = get_all_scripts(limit=20)
+        if history_items:
+            video_titles = [
+                f"{item['video_name']} ({item['created_at'].strftime('%Y-%m-%d %H:%M ')})"
+                for item in history_items
+            ]
+            selected = st.sidebar.radio("History Items", video_titles, index=0)
+            idx = video_titles.index(selected)
+            selected_data = history_items[idx]
+
+            st.subheader(f"Scripts for: {selected_data['video_name']}")
+            if selected_data.get("thumbnail"):
+                st.image("data:image/jpeg;base64," + selected_data["thumbnail"], width=150)
+
+            json_response = selected_data.get("response")
+            if json_response:
+                if isinstance(json_response, list):
+                    all_tables = []
+                    for round_idx, round_data in enumerate(json_response, 1):
+                        st.markdown(f"### Generation Round {round_idx}")
+                        st.text_input("Prompt used:", round_data.get("prompt_used", "N/A"), disabled=True)
+                        for i, variation in enumerate(round_data.get("variations", []), 1):
+                            st.markdown(f"#### Variation {i}: {variation.get('variation_name','Var')}")
+                            df = pd.DataFrame(variation.get("script_table", []))
+                            st.table(df)
+                            if not df.empty:
+                                df["Variation"] = variation.get("variation_name", f"Var{i}")
+                                df["Round"] = round_idx
+                                all_tables.append(df)
+
+                    if all_tables:
+                        csv_scripts = pd.concat(all_tables, ignore_index=True).to_csv(index=False)
+                        st.download_button(
+                            "Download CSV",
+                            data=csv_scripts,
+                            file_name=f"{selected_data['video_name']}_scripts.csv",
+                            mime="text/csv",
+                            use_container_width=True
+                        )
+        else:
+            st.info("No saved history available.")

app_pages/video_analyzer.py

@@ -0,0 +1,112 @@
+import os
+import tempfile
+import pandas as pd
+import streamlit as st
+
+from services.video_analyzer import analyze_video_only
+from components.render_analysis import render_analyzer_results
+from utils.video import get_video_thumbnail_base64
+from utils.dataframe import analysis_to_csv
+from database import insert_video_analysis, get_all_video_analyses
+
+def analyzer_page():
+    selected_tab = st.sidebar.radio("Select Mode", ["Video Analyser", "History"], index=0)
+
+    if selected_tab == "Video Analyser":
+        st.subheader(" Video Analyser")
+        uploaded_video = st.file_uploader("Upload Video",
+                                          type=['mp4','mov','avi','mkv'],
+                                          help="Upload a video for analysis")
+        analyse_button = st.button("Run Analysis", use_container_width=True)
+
+        if uploaded_video and analyse_button:
+            with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(uploaded_video.name)[1]) as tmp:
+                tmp.write(uploaded_video.read())
+                video_path = tmp.name
+            with st.spinner("Analyzing video..."):
+                st.session_state["analysis"] = analyze_video_only(video_path)
+                st.session_state["video_name"] = uploaded_video.name
+                st.session_state["video_path"] = video_path
+                st.session_state["thumbnail"] = get_video_thumbnail_base64(video_path)
+
+        if "analysis" in st.session_state and st.session_state["analysis"]:
+            render_analyzer_results(st.session_state["analysis"])
+
+            col1, col2 = st.columns(2)
+            with col1:
+                analysis = st.session_state["analysis"]
+                frames = []
+                if "storyboard" in analysis:
+                    df_storyboard = pd.DataFrame(analysis["storyboard"])
+                    df_storyboard["section"] = "Storyboard"
+                    frames.append(df_storyboard)
+                if "script" in analysis:
+                    df_script = pd.DataFrame(analysis["script"])
+                    df_script["section"] = "Script"
+                    frames.append(df_script)
+                if "video_analysis" in analysis and "video_metrics" in analysis["video_analysis"]:
+                    df_metrics = pd.DataFrame(analysis["video_analysis"]["video_metrics"])
+                    df_metrics["section"] = "Metrics"
+                    frames.append(df_metrics)
+                if "timestamp_improvements" in analysis:
+                    df_improvements = pd.DataFrame(analysis["timestamp_improvements"])
+                    df_improvements["section"] = "Improvements"
+                    frames.append(df_improvements)
+
+                if frames:
+                    csv_content = pd.concat(frames, ignore_index=True).to_csv(index=False)
+                    st.download_button(
+                        "Download CSV",
+                        data=csv_content,
+                        file_name=f"{st.session_state.get('video_name','analysis')}.csv",
+                        mime="text/csv",
+                        use_container_width=True
+                    )
+                else:
+                    st.info("No tabular data available for CSV export.")
+
+            with col2:
+                if st.button("Save to DB", use_container_width=True):
+                    try:
+                        insert_video_analysis(
+                            video_name=st.session_state.get("video_name", "unknown"),
+                            response=st.session_state["analysis"],
+                            thumbnail=st.session_state.get("thumbnail", "")
+                        )
+                        st.success("Analysis saved to database ")
+                    except Exception as e:
+                        st.error(f"Failed to save analysis: {e}")
+
+    else:
+        history_items = get_all_video_analyses(limit=20)
+        if history_items:
+            video_titles = [
+                f"{item['video_name']} ({item['created_at'].strftime('%Y-%m-%d %H:%M')})"
+                for item in history_items
+            ]
+            selected = st.sidebar.radio("History Items", video_titles, index=0)
+            idx = video_titles.index(selected)
+            selected_data = history_items[idx]
+
+            st.subheader(f"Analysis for: {selected_data['video_name']}")
+            if selected_data.get("thumbnail"):
+                st.image("data:image/jpeg;base64," + selected_data["thumbnail"], width=150)
+
+            json_response = selected_data.get("response")
+            if json_response:
+                tabs = st.tabs(["Video Analysis"])
+                with tabs[0]:
+                    render_analyzer_results(json_response)
+                    try:
+                        csv_data = analysis_to_csv(json_response)
+                        st.download_button(
+                            "Download CSV",
+                            data=csv_data,
+                            file_name=f"{selected_data['video_name']}_analysis.csv",
+                            mime="text/csv",
+                            use_container_width=True
+                        )
+                    except Exception as e:
+                        st.error(f"CSV export failed: {e}")
+        else:
+            st.info("No saved history available.")

components/display_variations.py

@@ -0,0 +1,19 @@
+import pandas as pd
+import streamlit as st
+
+def display_script_variations(json_data: dict):
+    if not json_data or "script_variations" not in json_data:
+        st.error("No script variations found")
+        return
+    for i, variation in enumerate(json_data["script_variations"], 1):
+        st.markdown(f"### Variation {i}: {variation.get('variation_name','Var')}")
+        df = pd.DataFrame(variation.get("script_table", []))
+        st.table(df)
+    csv_content = pd.concat(
+        [pd.DataFrame(v.get("script_table", []))
+         .assign(Variation=v.get("variation_name", f"Var{i+1}"))
+         for i, v in enumerate(json_data["script_variations"])],
+        ignore_index=True
+    ).to_csv(index=False)
+    st.download_button("Download CSV", data=csv_content,
+                       file_name="scripts.csv", mime="text/csv")

components/render_analysis.py

@@ -0,0 +1,124 @@
+import json
+import pandas as pd
+import streamlit as st
+from utils.dataframe import (
+    _normalize_list, _to_dataframe, _mean_effectiveness, _search_dataframe, safe_dataframe
+)
+
+def render_analyzer_results(analysis: dict, prefix: str = "") -> None:
+    if not isinstance(analysis, dict) or not analysis:
+        st.warning("No analysis available.")
+        return
+
+    st.markdown("""
+        <style>
+        .metric-card {background: #0f172a; padding: 14px 16px; border-radius: 14px; border: 1px solid #1f2937;}
+        .section-card {background: #0b1220; padding: 18px; border-radius: 14px; border: 1px solid #1f2937;}
+        .label {font-size: 12px; color: #94a3b8; margin-bottom: 6px;}
+        .value {font-size: 16px; color: #e2e8f0;}
+        </style>
+    """, unsafe_allow_html=True)
+
+    va = analysis.get("video_analysis", {}) or {}
+    storyboard = analysis.get("storyboard", []) or []
+    script = analysis.get("script", []) or []
+    metrics = va.get("video_metrics", []) or []
+    mean_score = _mean_effectiveness(metrics)
+
+    mcol1, mcol2, mcol3, mcol4 = st.columns([1,1,1,1])
+    with mcol1:
+        st.markdown(f'<div class="metric-card"><div class="label">Scenes</div><div class="value">{len(storyboard)}</div></div>', unsafe_allow_html=True)
+    with mcol2:
+        st.markdown(f'<div class="metric-card"><div class="label">Dialogue Lines</div><div class="value">{len(script)}</div></div>', unsafe_allow_html=True)
+    with mcol3:
+        st.markdown(f'<div class="metric-card"><div class="label">Avg Effectiveness</div><div class="value">{mean_score}/10</div></div>', unsafe_allow_html=True)
+    with mcol4:
+        st.markdown(f'<div class="metric-card"><div class="label">Improvements</div><div class="value">{len(analysis.get("timestamp_improvements", []) or [])}</div></div>', unsafe_allow_html=True)
+
+    colA, colB = st.columns([1.3,1])
+    with colA:
+        with st.container():
+            st.markdown("### Executive Summary")
+            c1, c2 = st.columns(2)
+            with c1:
+                with st.expander("Brief", expanded=True):
+                    st.write(analysis.get("brief", "N/A"))
+                with st.expander("Caption Details", expanded=False):
+                    st.write(analysis.get("caption_details", "N/A"))
+            with c2:
+                hook = analysis.get("hook", {}) or {}
+                with st.expander("Hook", expanded=True):
+                    st.markdown(f"**Opening:** {hook.get('hook_text','N/A')}")
+                    st.markdown(f"**Principle:** {hook.get('principle','N/A')}")
+                    adv = _normalize_list(hook.get("advantages"))
+                    if adv:
+                        st.markdown("**Advantages:**")
+                        st.markdown("\n".join([f"- {a}" for a in adv]))
+        st.divider()
+        st.markdown("### Narrative & Copy Frameworks")
+        with st.expander("Framework Analysis", expanded=True):
+            st.write(analysis.get("framework_analysis", "N/A"))
+
+    with colB:
+        st.markdown("### Snapshot")
+        with st.container():
+            st.caption("Top Drivers")
+            st.markdown(f'{va.get("effectiveness_factors","N/A")}</div>', unsafe_allow_html=True)
+        st.markdown("")
+        with st.container():
+            st.caption("Psychological Triggers")
+            st.markdown(f'{va.get("psychological_triggers","N/A")}</div>', unsafe_allow_html=True)
+        st.markdown("")
+        with st.container():
+            st.caption("Target Audience")
+            st.markdown(f'{va.get("target_audience","N/A")}</div>', unsafe_allow_html=True)
+
+    st.divider()
+    tabs = st.tabs(["Storyboard", "Script", "Scored Metrics", "Improvements", "Raw JSON"])
+
+    with tabs[0]:
+        q = st.text_input("Search storyboard", key=f"{prefix}_storyboard")
+        if storyboard:
+            df = _to_dataframe(storyboard, {"timeline": "Timeline", "scene": "Scene", "visuals": "Visuals", "dialogue": "Dialogue", "camera": "Camera", "sound_effects": "Sound Effects"})
+            df = _search_dataframe(df, q)
+            st.dataframe(safe_dataframe(df), use_container_width=True, height=480)
+        else:
+            st.info("No storyboard available.")
+
+    with tabs[1]:
+        q2 = st.text_input("Search script", key=f"{prefix}_script")
+        if script:
+            df = _to_dataframe(script, {"timeline": "Timeline", "dialogue": "Dialogue"})
+            df = _search_dataframe(df, q2)
+            st.dataframe(safe_dataframe(df), use_container_width=True, height=480)
+        else:
+            st.info("No script breakdown available.")
+
+    with tabs[2]:
+        q3 = st.text_input("Search metrics", key=f"{prefix}_metrics")
+        if metrics:
+            dfm = _to_dataframe(metrics, {"timestamp": "Timestamp", "element": "Element", "current_approach": "Current Approach", "effectiveness_score": "Effectiveness Score", "notes": "Notes"})
+            dfm = _search_dataframe(dfm, q3)
+            st.dataframe(dfm, use_container_width=True, height=480)
+        else:
+            st.info("No video metrics available.")
+
+    with tabs[3]:
+        improvements = analysis.get("timestamp_improvements", []) or []
+        q4 = st.text_input("Search improvements", key=f"{prefix}_improvements")
+        if improvements:
+            imp_df = _to_dataframe(improvements, {"timestamp": "Timestamp", "current_element": "Current Element", "improvement_type": "Improvement Type", "recommended_change": "Recommended Change", "expected_impact": "Expected Impact", "priority": "Priority"})
+            if "Priority" in imp_df.columns:
+                order = pd.CategoricalDtype(["High", "Medium", "Low"], ordered=True)
+                imp_df["Priority"] = imp_df["Priority"].astype(order)
+                if "Timestamp" in imp_df.columns:
+                    imp_df = imp_df.sort_values(["Priority", "Timestamp"])
+            imp_df = _search_dataframe(imp_df, q4)
+            st.dataframe(imp_df, use_container_width=True, height=480)
+        else:
+            st.info("No timestamp-based improvements available.")
+
+    with tabs[4]:
+        pretty = json.dumps(analysis, indent=2, ensure_ascii=False)
+        st.code(pretty, language="json")
+        st.download_button("Download JSON", data=pretty.encode("utf-8"), file_name="ad_analysis.json", mime="application/json", use_container_width=True)

prompt/analyser_prompt.py

@@ -0,0 +1,38 @@
+analyser_prompt = """You are an expert video advertisement analyst. Analyze the provided video and give response conforms EXACTLY to the schema below with no extra text or markdown.
+Populate:
+
+1. **brief** → A concise summary covering visual style, speaker, target audience, and marketing objective.  
+2. **caption_details** → Description of captions (color/style/position) or exactly the string `"None"` if not visible.  
+3. **hook** →  
+   - `"hook_text"`: Exact opening line or, if no speech, the precise description of the opening visual.  
+   - `"principle"`: Psychological/marketing principle that makes this hook effective.  
+   - `"advantages"`: ARRAY of 3–6 concise benefit statements tied to the ad’s value proposition.  
+4. **framework_analysis** → A detailed block identifying copywriting/psychology/storytelling frameworks (e.g., PAS, AIDA). Highlight use of social proof, urgency, fear, authority, scroll-stopping hooks, loop openers, value positioning, and risk reversals.  
+5. **storyboard** → ARRAY of 4–10 objects. Each must include:  
+   - `"timeline"` in `"MM:SS"` (zero-padded)  
+   - `"scene"` (brief)  
+   - `"visuals"` (detailed)  
+   - `"dialogue"` (exact words; use `""` if none)  
+   - `"camera"` (shot/angle)  
+   - `"sound_effects"` (or `"None"`)  
+6. **script** → ARRAY of dialogue objects, each with `"timeline"` (`"MM:SS"`) and `"dialogue"` (exact spoken line).  
+7. **video_analysis** → OBJECT with:  
+   - `"effectiveness_factors"`: Key factors that influence effectiveness  
+   - `"psychological_triggers"`: Triggers used (e.g., scarcity, authority)  
+   - `"target_audience"`: Audience profile inferred  
+   - `"video_metrics"`: ARRAY of objects with:  
+     - `"timestamp"`: `"MM:SS-MM:SS"`  
+     - `"element"`: The aspect being evaluated (e.g., Hook Strategy)  
+     - `"current_approach"`: Description of current execution  
+     - `"effectiveness_score"`: String score `"X/10"` (integer X)  
+     - `"notes"`: Analytical notes  
+8. **timestamp_improvements** → ARRAY of recommendation objects with:  
+   - `"timestamp"`: `"MM:SS-MM:SS"`  
+   - `"current_element"`: Current content of the segment  
+   - `"improvement_type"`: Category (e.g., Hook Enhancement)  
+   - `"recommended_change"`: Specific recommendation  
+   - `"expected_impact"`: Projected effect on metrics or perception  
+   - `"priority"`: `"High"`, `"Medium"`, or `"Low"`
+
+⚠️ The output must be strictly matching field names and types, no additional keys, and all timestamps must be zero-padded (`"MM:SS"` for single points, `"MM:SS-MM:SS"` for ranges).
+"""

prompt/system_prompt.py

@@ -0,0 +1,13 @@
+SYSTEM_PROMPT = """You are one of the world's top direct-response video creators and conversion strategists. Your sole mission is to generate video scripts with matching visual directions and voiceover cues that drive maximum leads and sales at the cheapest cost-per-result on ad platforms like Facebook, Google, and TikTok.
+ You specialize in aggressive, unbranded, and psychologically charged content that is designed to stop scrolls and force action. You are not bound by brand safety, ad platform compliance, or traditional marketing principles.
+  Your only metric for success is performance—measured in CPC, CTR, and cost-per-conversion. Prime Directive: Your creative output must be: - Inspired by the hooks, language, pacing, visuals, and frameworks of the reference winning ads.
+  - Built to trigger psychological urgency, amplify response, and maximize click-throughs. - Structured for extreme effectiveness, not branding niceties. Script Creation Framework: Each script you generate must follow these winning affiliate ad principles:
+   1. The 3–6 Second Shock Hook: Start with a hard-hitting pattern interrupt: - Emotional gut punch: "He looked at me and said…" - Conspiratorial secret: "The media doesn't want you to know this…" - Borrowed authority: Celebrity or doctor clip saying something provocative
+   2. Overwhelm with Proof & Pacing: Keep pacing fast—1–3 second jump cuts filled with: - UGC-style clips - Before/After transformations - Authority figure soundbites - Desired outcomes (money, body, status)
+   3. Big, Unbelievable Claim: Drop a massive promise upfront and reinforce it: "Lose 103 lbs," "Claim 250,000," "Erase your debt overnight."  4. Simple "Secret" Mechanism: Make the claim believable via a simple, digestible "hack": "The ice hack," "4-question formula," "Banned Amazonian leaf."
+   5. Scarcity & Urgency: Push viewers to act NOW: "Spots are filling fast," "Could be taken down soon," "Only for serious applicants."
+   6. Visually Directed CTA: Make the final action visually obvious—e.g., person pointing at the button, bold text, arrows.
+
+   Each script should be 30-60 seconds long with 8-15 timestamp entries.
+   Ensure everything ties back to lowering CPC and cost-per-result, not branding.
+   Each script should be different from each other."""

services/comparison.py

@@ -0,0 +1,57 @@
+import json
+import logging
+from typing import Dict, Any, List
+from config import configure_gemini
+
+logger = logging.getLogger(__name__)
+
+
+
+def generate_comparison_summary(analyses: List[Dict[str, Any]], user_prompt: str) -> str:
+    """
+    Generate a natural-language comparison between videos,
+    given their AdAnalysis JSON and a user prompt.
+    """
+    client = configure_gemini()
+
+  
+    try:
+        analyses_json = json.dumps(
+            [{"video": a.get("video_name"), "analysis": a.get("analysis")} for a in analyses],
+            ensure_ascii=False, indent=2
+        )
+    except Exception:
+        logger.exception("Failed to serialize analyses for comparison")
+        analyses_json = "[]"
+
+    system_prompt = (
+        "You are an expert video ad strategist. Compare multiple video ad analyses and return "
+        "a clear, structured comparison. Highlight:\n"
+        "- Hooks and opening strategies\n"
+        "- Copywriting / psychology frameworks\n"
+        "- Target audience differences\n"
+        "- Average effectiveness scores\n"
+        "- Major timestamp improvements\n"
+        "- Strengths & weaknesses of each video\n\n"
+        "Always structure output into sections and provide actionable insights."
+    )
+
+    user_message = (
+        f"Here are the analyses for multiple videos:\n\n{analyses_json}\n\n"
+        f"Now, based on this data, {user_prompt}."
+    )
+
+    try:
+        resp = client.chat.completions.create(
+            model="gemini-2.0-flash",
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_message}
+            ],
+            temperature=0.2,
+        )
+        return resp.choices[0].message.content or "No summary generated."
+    except Exception:
+        logger.exception("Comparison summary generation failed")
+        return "Failed to generate comparison summary."
+

services/script_generator.py

@@ -0,0 +1,139 @@
+import json
+import os
+import time
+import logging
+from typing import Dict, Any
+
+from prompt.system_prompt import SYSTEM_PROMPT
+from schema_script import ScriptResponse  
+from google import genai
+from dotenv import load_dotenv
+
+load_dotenv()
+GEMINI_API_KEY = os.getenv("GEMINI_KEY")
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[logging.StreamHandler()]
+)
+logger = logging.getLogger(__name__)
+
+
+def configure_gemini():
+    return genai.Client(api_key=GEMINI_API_KEY)
+
+
+def generate_scripts(
+    video_path: str,
+    offer_details: str,
+    target_audience: str,
+    specific_hooks: str,
+    additional_context: str,
+    num_scripts: int = 3,
+    duration: int = 60
+) -> Dict[str, Any]:
+    client = configure_gemini()
+
+    try:
+        user_prompt = f"""
+                    Generate {num_scripts} high-converting direct response script variations,
+                    each about {duration} seconds long.
+
+                    CONTEXT TO FOLLOW:
+                    - Offer Details: {offer_details}
+                    - Target Audience: {target_audience}
+                    - Specific Hooks: {specific_hooks}
+
+                    ADDITIONAL CONTEXT:
+                    {additional_context}
+                    You must reflect this additional context in:
+        - The script tone, CTA, visuals
+        - Compliance or branding constraints
+        - Any assumptions about audience or product
+        Failure to include this will be considered incomplete.
+        Please provide a comprehensive analysis including:
+        1. DETAILED VIDEO ANALYSIS with timestamp-based metrics:
+           - Break down the video into 5-10 second segments
+           - Rate each segment's effectiveness (1-10 scale)
+           - Identify specific elements (hook, transition, proof, CTA, etc.)
+        2. TIMESTAMP-BASED IMPROVEMENTS:
+           - Specific recommendations for each time segment
+           - Priority level for each improvement
+           - Expected impact of implementing changes
+        3. SCRIPT VARIATIONS:
+           - Create 2-3 complete script variations
+           - Each with timestamp-by-timestamp breakdown
+           - Different psychological triggers and approaches
+        IMPORTANT: Return only valid JSON in the exact format specified in the system prompt. Analyze the video second-by-second for maximum detail.
+
+                    Return ONLY valid JSON that matches this schema:
+                    {{
+                    "script_variations": [
+                        {{
+                        "variation_name": "string",
+                        "script_table": [
+                            {{
+                            "timestamp": "M:SS or MM:SS",
+                            "script_voiceover": "string",
+                            "visual_direction": "string",
+                            "psychological_trigger": "string",
+                            "cta_action": "string"
+                            }}
+                        ]
+                        }}
+                    ]
+                    }}
+"""
+
+        video_file = client.files.upload(file=video_path)
+
+        while getattr(video_file.state, "name", "") == "PROCESSING":
+            time.sleep(1.0)
+            video_file = client.files.get(name=video_file.name)
+        if getattr(video_file.state, "name", "") == "FAILED":
+            logger.error("Video processing FAILED.")
+            return {}
+
+        resp = client.models.generate_content(
+            model="gemini-2.0-flash",
+            contents=[SYSTEM_PROMPT, user_prompt, video_file],
+            config={
+                "response_mime_type": "application/json",
+                "response_schema": ScriptResponse,
+    
+            },
+        )
+
+
+        parsed = getattr(resp, "parsed", None)
+        if parsed is None:
+
+            raw_text = getattr(resp, "text", "") or ""
+            if not raw_text:
+                # Inspect parts for better debugging
+                parts = None
+                if getattr(resp, "candidates", None):
+                    parts = getattr(resp.candidates[0].content, "parts", None)
+                raise RuntimeError(f"Model returned no JSON text. parts={parts}")
+            data = json.loads(raw_text)
+            return data
+
+   
+        out = parsed.model_dump()
+        logger.info("Generated %d variations.", len(out.get("script_variations", [])))
+        return out
+
+    except Exception as e:
+        logger.exception("generate_scripts failed: %s", e)
+        return {}
+
+
+
+
+
+
+
+
+
+

services/video_analyzer.py

@@ -0,0 +1,117 @@
+import json
+import os
+import tempfile
+import logging
+import pandas as pd
+import streamlit as st
+from typing import Dict, Any, List
+import cv2
+import base64
+
+from config import configure_gemini
+from prompt.analyser_prompt import analyser_prompt
+from schema import AdAnalysis
+from utils.video import get_video_thumbnail_base64
+
+logger = logging.getLogger(__name__)
+
+
+
+def _sample_frames_b64(video_path: str, num_frames: int = 6, max_side: int = 896) -> List[str]:
+    """
+    Return up to `num_frames` JPEG frames from the video as base64 strings.
+    Frames are spaced across the video duration and resized so the longer
+    side is <= max_side to keep payload smaller.
+    """
+    b64s: List[str] = []
+    cap = cv2.VideoCapture(video_path)
+    try:
+        total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+        if total <= 0:
+            return b64s
+
+  
+        idxs = [int(i * (total - 1) / max(num_frames - 1, 1)) for i in range(num_frames)]
+        for idx in idxs:
+            cap.set(cv2.CAP_PROP_POS_FRAMES, idx)
+            ok, frame = cap.read()
+            if not ok or frame is None:
+                continue
+
+            h, w = frame.shape[:2]
+            scale = min(1.0, float(max_side) / max(h, w))
+            if scale < 1.0:
+                frame = cv2.resize(frame, (int(w * scale), int(h * scale)))
+
+            ok, buf = cv2.imencode(".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
+            if not ok:
+                continue
+            b64s.append(base64.b64encode(buf.tobytes()).decode("utf-8"))
+        return b64s
+    finally:
+        cap.release()
+
+
+def analyze_video_only(video_path: str) -> Dict[str, Any]:
+    client = configure_gemini()
+    try:
+        
+        frames_b64 = _sample_frames_b64(video_path, num_frames=8)
+        if not frames_b64:
+            logger.error("Could not extract frames from video.")
+            return {}
+
+        user_parts: List[Dict[str, Any]] = [
+            {
+                "type": "text",
+                "text": (
+                    "Analyze these frames of the ad and return ONLY valid JSON "
+                    "that conforms exactly to the schema described in the system message."
+                ),
+            }
+        ]
+        for b64 in frames_b64:
+            user_parts.append({
+                "type": "image_url",
+                "image_url": {"url": f"data:image/jpeg;base64,{b64}"}
+            })
+        resp = client.beta.chat.completions.parse(
+            model="gemini-2.0-flash",
+            messages=[
+                {"role": "system", "content": analyser_prompt},
+                {"role": "user", "content": user_parts},
+            ],
+            response_format=AdAnalysis,
+            
+           
+        )
+
+        raw = resp.choices[0].message.parsed 
+
+        try:
+            
+            return raw.model_dump()
+        except Exception:
+            return json.loads(raw)
+
+    except Exception as e:
+        logger.exception("Video analysis failed")
+        return {}
+
+
+def analyze_multiple_videos(video_files: List[st.runtime.uploaded_file_manager.UploadedFile]) -> List[Dict[str, Any]]:
+    results = []
+    for file in video_files:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(file.name)[1]) as tmp:
+            tmp.write(file.read())
+            video_path = tmp.name
+
+        analysis = analyze_video_only(video_path)
+        thumbnail_b64 = get_video_thumbnail_base64(video_path)
+
+        results.append({
+            "video_name": file.name,
+            "analysis": analysis,
+            "thumbnail": thumbnail_b64
+        })
+    return results

utils/auth.py

@@ -0,0 +1,33 @@
+import os
+import logging
+import streamlit as st
+
+logger = logging.getLogger(__name__)
+
+def check_token(user_token: str):
+    ACCESS_TOKEN = os.getenv("ACCESS_TOKEN")
+    if not ACCESS_TOKEN:
+        logger.critical("ACCESS_TOKEN not set in environment.")
+        return False, "Server error: Access token not configured."
+    if user_token == ACCESS_TOKEN:
+        logger.info("Access token validated successfully.")
+        return True, ""
+    logger.warning("Invalid access token attempt.")
+    return False, "Invalid token."
+
+def gated_access() -> bool:
+    if "authenticated" not in st.session_state:
+        st.session_state["authenticated"] = False
+
+    if not st.session_state["authenticated"]:
+        st.markdown("## Access Required")
+        token_input = st.text_input("Enter Access Token", type="password")
+        if st.button("Unlock App"):
+            ok, error_msg = check_token(token_input)
+            if ok:
+                st.session_state["authenticated"] = True
+                st.rerun()
+            else:
+                st.error(error_msg)
+        return False
+    return True

utils/dataframe.py

@@ -0,0 +1,59 @@
+import json
+import pandas as pd
+from typing import Any, Dict, List
+
+def safe_dataframe(df: pd.DataFrame) -> pd.DataFrame:
+    for col in df.columns:
+        df[col] = df[col].astype(str)
+    return df
+
+def analysis_to_csv(analysis: Dict[str, Any]) -> str:
+    rows = []
+    for sb in analysis.get("storyboard", []):
+        rows.append({"Section": "Storyboard", **sb})
+    for sc in analysis.get("script", []):
+        rows.append({"Section": "Script", **sc})
+    for met in analysis.get("video_analysis", {}).get("video_metrics", []):
+        rows.append({"Section": "Metrics", **met})
+    for imp in analysis.get("timestamp_improvements", []):
+        rows.append({"Section": "Improvements", **imp})
+    if not rows:
+        return ""
+    df = pd.DataFrame(rows)
+    return df.to_csv(index=False)
+
+def _normalize_list(value: Any) -> List[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    return [s for s in str(value).splitlines() if s.strip()]
+
+def _to_dataframe(items: Any, columns_map: Dict[str, str]) -> pd.DataFrame:
+    if not isinstance(items, list) or not items:
+        return pd.DataFrame(columns=list(columns_map.values()))
+    df = pd.DataFrame(items)
+    df = df.rename(columns=columns_map)
+    ordered_cols = [columns_map[k] for k in columns_map.keys() if columns_map[k] in df.columns]
+    df = df.reindex(columns=ordered_cols)
+    return df
+
+def _mean_effectiveness(metrics: List[Dict[str, Any]]) -> float:
+    if not metrics:
+        return 0.0
+    scores = []
+    for m in metrics:
+        s = str(m.get("effectiveness_score", "0/10")).split("/")[0]
+        try:
+            scores.append(int(s))
+        except Exception:
+            pass
+    return round(sum(scores) / len(scores), 2) if scores else 0.0
+
+def _search_dataframe(df: pd.DataFrame, query: str) -> pd.DataFrame:
+    if not query or df.empty:
+        return df
+    mask = pd.Series([False]*len(df))
+    for col in df.columns:
+        mask = mask | df[col].astype(str).str.contains(query, case=False, na=False)
+    return df[mask]

utils/video.py

@@ -0,0 +1,19 @@
+import cv2
+import base64
+import logging
+
+logger = logging.getLogger(__name__)
+
+def get_video_thumbnail_base64(video_path: str, time_sec: int = 1) -> str:
+    try:
+        cap = cv2.VideoCapture(video_path)
+        cap.set(cv2.CAP_PROP_POS_MSEC, time_sec * 1000)
+        success, frame = cap.read()
+        cap.release()
+        if not success:
+            return ""
+        _, buffer = cv2.imencode(".jpg", frame)
+        return base64.b64encode(buffer).decode("utf-8")
+    except Exception:
+        logger.exception("Thumbnail extraction failed")
+        return ""