Reinitialize repository without offending large file

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,3 @@
+.env
+
+dev/

README.md

@@ -0,0 +1,12 @@
+---
+title: Pdf Digest
+emoji: 👁
+colorFrom: pink
+colorTo: yellow
+sdk: streamlit
+sdk_version: 1.42.0
+app_file: app.py
+pinned: false
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,282 @@
+import os
+import time
+import asyncio
+import logging
+import json
+import streamlit as st
+from dotenv import load_dotenv
+load_dotenv()
+
+# Import our existing utility functions
+from utils.file_utils import load_prompt, save_intermediate_output, setup_temp_directories, cleanup_temp_files
+from utils.llm_utils import get_generation_model, async_generate_text, generate_title_reference_and_classification
+from utils.tts_utils import generate_tts_audio
+
+# Import the multi‐paper review flow functions
+from utils.review_flow import (
+    process_multiple_pdfs,
+    generate_final_review_pdf
+)
+
+logging.basicConfig(level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+st.set_page_config(page_title="Academic PDF Digester", layout="wide")
+
+# ===== SIDEBAR: Login and Mode Selection =====
+if "authenticated" not in st.session_state:
+    st.session_state["authenticated"] = False
+
+with st.sidebar:
+    st.header("User Login")
+    if not st.session_state["authenticated"]:
+        with st.form(key="login_form"):
+            username = st.text_input("Username")
+            password = st.text_input("Password", type="password")
+            submit_button = st.form_submit_button("Login")
+        # Simple authentication using environment variables
+        if submit_button:
+            expected_username = os.getenv("APP_USERNAME")
+            expected_password = os.getenv("APP_PASSWORD")
+            if username == expected_username and password == expected_password:
+                st.session_state["authenticated"] = True
+                st.session_state["username"] = username  # Store the username
+                st.success("Logged in successfully!")
+                logger.debug("User authenticated successfully.")
+            else:
+                st.error("Invalid credentials")
+                logger.debug("Authentication failed for user: %s", username)
+        st.stop()
+    else:
+        st.info("Logged in as: " + st.session_state.get("username", "Unknown User"))
+
+    st.header("Select Mode")
+    mode = st.radio("Choose a mode:", options=["Explore One Publication", "Write a Literature Review"])
+
+# ===== MAIN APP =====
+st.title("Academic PDF Digester 😋")
+
+st.subheader("Effortlessly analyze and synthesize academic papers")
+st.markdown(
+    """
+    **Welcome to Academic PDF Digester!**  
+    This tool uses advanced Large Language Models (LLMs) to automatically extract key information from academic papers,
+    generate structured summaries, and even produce downloadable PDF and audio outputs. Whether you are exploring a single publication
+    or synthesizing a literature review from multiple papers, our system streamlines your research process.
+    """
+)
+
+with st.expander("How It Works"):
+    st.markdown(
+        """
+        **Overview of the Functionality:**
+        
+        - **File Processing:**  
+          Uploaded PDFs are saved locally and then sent to a cloud-based service where a specialized LLM analyzes the content.
+          
+        - **LLM Integration:**  
+          The LLM extracts key information (such as the core structure, outlines, and insights) and generates structured outputs.
+          These outputs are then used to create comparative analyses, draft final reviews, and check for consistency.
+          
+        - **Outputs:**  
+          The system generates:
+            - A **detailed overview** for individual papers.
+            - A **comparative literature review** for multiple papers.
+            - **Downloadable PDFs** summarizing the findings.
+            - **Audio summaries** for quick listening.
+          
+        **How LLMs Are Used:**  
+        - The tool leverages LLMs to generate conten.
+        - For each step (e.g., generating outlines, synthesizing final reviews), the LLM processes the input and returns a coherent narrative.
+        - Checks are performed to minimize hallucinations and ensure factual accuracy.
+        
+        This powerful combination of file processing, LLM integration, and smart output synthesis helps you gain insights from academic papers quickly and accurately.
+        """
+    )
+
+if mode == "Explore One Publication":
+    st.subheader("Single-Publication Analysis")
+    
+    # Load models for title generation and main analysis
+    title_model_name, title_generation_config = get_generation_model("flash")
+    default_model_name, default_generation_config = get_generation_model("thinking")
+    
+    uploaded_pdf = st.file_uploader("Upload a PDF", type=["pdf"])
+    if uploaded_pdf is not None:
+        if uploaded_pdf.size < 5000:
+            st.error("Input does not appear to be an academic paper. Please upload a valid academic paper.")
+            st.stop()
+        st.session_state["uploaded_pdf"] = uploaded_pdf
+        st.success("PDF uploaded successfully.")
+        
+        progress_bar = st.progress(0)
+        
+        async def process_single_pdf():
+            # Create a temporary directory and save the file locally.
+            temp_dir = setup_temp_directories()
+            try:
+                pdf_basename = os.path.splitext(st.session_state["uploaded_pdf"].name)[0]
+                st.session_state["pdf_basename"] = pdf_basename
+                temp_pdf_path = os.path.join(temp_dir, "uploaded.pdf")
+                with open(temp_pdf_path, "wb") as f:
+                    f.write(st.session_state["uploaded_pdf"].getbuffer())
+                logger.debug("PDF saved locally to %s", temp_pdf_path)
+                progress_bar.progress(10)
+                
+                # Upload file to Gemini.
+                with st.spinner("Uploading PDF to Gemini..."):
+                    try:
+                        pdf_file = upload_to_gemini(temp_pdf_path, mime_type="application/pdf")
+                    except Exception as e:
+                        st.error("Error uploading PDF: " + str(e))
+                        st.stop()
+                progress_bar.progress(20)
+                
+                # Wait for file processing.
+                with st.spinner("Waiting for file processing..."):
+                    try:
+                        wait_for_files_active([pdf_file])
+                    except Exception as e:
+                        st.error("Error in file processing: " + str(e))
+                        st.stop()
+                progress_bar.progress(30)
+                
+                # Generate title, APA reference and classification.
+                with st.spinner("Generating title, APA reference, and classification..."):
+                    title_ref = await generate_title_reference_and_classification(
+                        pdf_file, title_model_name, title_generation_config
+                    )
+                    if title_ref.error:
+                        st.error(title_ref.error)
+                        st.stop()
+                    st.session_state["title"] = title_ref.title
+                    st.session_state["apa_reference"] = title_ref.apa_reference
+                    st.session_state["classification"] = title_ref.classification
+                    st.session_state["bullet_list"] = title_ref.bullet_list  # Save bullet list
+                progress_bar.progress(40)
+                
+                # Load prompts for outline and key insights.
+                try:
+                    outline_prompt = load_prompt("prompts/outline_acad.prompt")
+                    elements_prompt = load_prompt("prompts/elements.prompt")
+                except Exception as e:
+                    st.error("Error loading prompt files: " + str(e))
+                    st.stop()
+                
+                # Generate key insights and outline concurrently.
+                with st.spinner("Extracting key insights and drafting outline..."):
+                    task_outline = async_generate_text(
+                        outline_prompt, pdf_file,
+                        model_name=default_model_name,
+                        generation_config=default_generation_config
+                    )
+                    task_elements = async_generate_text(
+                        elements_prompt, pdf_file,
+                        model_name=default_model_name,
+                        generation_config=default_generation_config
+                    )
+                    outline_acad_output, elements_output = await asyncio.gather(task_outline, task_elements)
+                progress_bar.progress(65)
+                st.info("Key insights extracted and outline drafted successfully!")
+                # Save intermediate outputs.
+                save_intermediate_output(outline_acad_output, pdf_basename, "outline")
+                save_intermediate_output(elements_output, pdf_basename, "elements")
+                
+                # Generate final overview.
+                with st.spinner("Generating final overview..."):
+                    overview_prompt = load_prompt("prompts/overview.prompt")
+                    tts_instruction = "Ensure the final overview is TTS-friendly and does not exceed 3000 words."
+                    combined_overview_prompt = (
+                        tts_instruction + "\n\nAcademic Outline:\n" + outline_acad_output +
+                        "\n\nKey Insights:\n" + elements_output + "\n" +
+                        overview_prompt + "\n" + tts_instruction
+                    )
+                    overview_output = await async_generate_text(
+                        combined_overview_prompt, pdf_file,
+                        model_name=default_model_name,
+                        generation_config=default_generation_config
+                    )
+                    save_intermediate_output(overview_output, pdf_basename, "overview")
+                progress_bar.progress(75)
+                
+                # Generate downloadable PDF.
+                from markdown_pdf import MarkdownPdf, Section
+                with st.spinner("Generating downloadable PDF..."):
+                    try:
+                        pdf_doc = MarkdownPdf(toc_level=2)
+                        bullet_markdown = "\n".join(f"- {item}" for item in st.session_state.get("bullet_list", []))
+                        title_and_ref_markdown = (
+                            f"# {st.session_state['title']}\n\n"
+                            f"*{st.session_state['apa_reference']}*\n\n"
+                            "### Key Components:\n"
+                            f"{bullet_markdown}\n\n"
+                        )
+                        pdf_doc.add_section(Section(title_and_ref_markdown, toc=False))
+                        pdf_doc.add_section(Section(overview_output.strip(), toc=True))
+                        final_pdf_path = os.path.join("promp_tmp", f"{pdf_basename}_final_output.pdf")
+                        pdf_doc.save(final_pdf_path)
+                        with open(final_pdf_path, "rb") as f:
+                            st.session_state["final_pdf"] = f.read()
+                        st.session_state["final_text"] = (
+                            f"# {st.session_state['title']}\n\n"
+                            f"*{st.session_state['apa_reference']}*\n\n"
+                            "### Key Components:\n"
+                            f"{bullet_markdown}\n\n"
+                            f"{overview_output.strip()}"
+                        )
+                        st.success("PDF generated successfully.")
+                    except Exception as e:
+                        st.error("Failed to generate PDF: " + str(e))
+                        st.stop()
+                progress_bar.progress(100)
+                st.session_state["generated"] = True
+            except Exception as e:
+                st.error(f"Error during processing: {str(e)}")
+                st.stop()
+            finally:
+                cleanup_temp_files(temp_dir)
+        
+        if st.button("Generate Overview"):
+            asyncio.run(process_single_pdf())
+    
+    if st.session_state.get("generated"):
+        st.download_button(
+            label="Download Final PDF",
+            data=st.session_state["final_pdf"],
+            file_name="final_output.pdf",
+            mime="application/pdf"
+        )
+                
+elif mode == "Write a Literature Review":
+    st.subheader("Literature Review Generation")
+    
+    st.markdown(
+        "Upload **multiple academic PDFs** to generate a comparative literature review. "
+        "You can select more than one file."
+    )
+    
+    uploaded_pdfs = st.file_uploader("Upload PDFs", type=["pdf"], accept_multiple_files=True)
+    
+    if uploaded_pdfs:
+        st.session_state["uploaded_pdfs"] = uploaded_pdfs
+        st.success(f"{len(uploaded_pdfs)} PDFs uploaded successfully.")
+        
+        if st.button("Generate Literature Review"):
+            with st.spinner("Processing PDFs and generating review..."):
+                # Process the multiple PDFs using our review_flow helper
+                # This function handles the upload, Gemini processing, structured output extraction,
+                # comparative table, outline, final synthesis and even PDF conversion.
+                structured_outputs = asyncio.run(process_multiple_pdfs(uploaded_pdfs))
+                final_review_text = asyncio.run(generate_final_review_pdf(structured_outputs))
+            st.success("Literature review generated successfully!")
+            st.text_area("Final Literature Review", final_review_text, height=300)
+            # Optionally, let the user download the review as PDF
+            review_pdf = st.file_uploader("Download PDF", type=["pdf"])
+            with open("final_literature_review.pdf", "rb") as f:
+                final_pdf_bytes = f.read()
+            st.download_button(
+                label="Download Final Literature Review PDF",
+                data=final_pdf_bytes,
+                file_name="final_literature_review.pdf",
+                mime="application/pdf"
+            )

packages.txt

@@ -0,0 +1,2 @@
+ffmpeg
+espeak-ng

prompts/audio.prompt

@@ -0,0 +1,21 @@
+Create a 3-minute audio summary (approximately 450-500 words) of the provided academic text.
+ONLY output the final text - nothing else.
+The summary should:
+
+Start with a clear introduction that establishes the topic's context and significance in 1-2 sentences
+Present 3-4 key findings or arguments that make this work noteworthy, using clear transitions between points
+Include relevant statistics or concrete examples that illustrate the main points, but limit numbers to those essential for understanding
+Maintain an academic yet conversational tone that engages listeners while preserving scholarly credibility
+Use clear sentence structures optimized for text-to-speech, avoiding:
+
+Special characters, hashtags, or formatting
+Parenthetical statements
+Complex numbered lists
+Citations or references
+Quotation marks for emphasis
+
+End with a brief statement of broader implications or significance
+
+Format the text in clear paragraphs with natural transitions. Use "audio-friendly" punctuation (periods, commas) to create appropriate pacing. Aim for sentences of varying length to maintain listener engagement.
+
+ONLY output the final text - nothing else. No intros! No notes!

prompts/audio_narrate.prompt

@@ -0,0 +1,38 @@
+Transform this academic summary paper into a first-person narrative for audio delivery, following these guidelines - output the final TEXT only - nothing else - no intros or notes:
+
+Voice:
+
+Use clear, direct first-person perspective
+Maintain academic authority while being conversational
+Keep emotional expressions measured and professional
+Use contractions naturally but sparingly
+Avoid overly casual language or slang
+
+Structure:
+
+Break content into clear speaking segments
+Use brief transitions between topics
+Convert visual references to verbal descriptions
+Start with context, then methods, findings, and implications
+End sections with clear takeaways
+
+Technical Content:
+
+Present all data and findings accurately
+Explain methods as deliberate choices
+Keep all limitations and caveats
+Convert statistics into clear spoken numbers
+Maintain academic precision while being accessible
+
+TTS Optimization:
+
+Use standard punctuation for natural pauses
+Keep sentences medium length
+Spell out abbreviations first time
+Break complex ideas into digestible parts
+Use clear paragraph breaks
+
+Aim for the tone of an experienced researcher giving a well-structured talk to colleagues - professional but engaging, detailed but clear.
+AVOID REDUNDANCY - do not repeat the same information in different ways.
+Target audio for around 15 Minutes.
+Output should be around 1000 words.

prompts/audio_pres.prompt

@@ -0,0 +1,82 @@
+Generate a Trump-Style Research Presentation - just output the text that Trump would say. Nothing else.
+Do not write things like applause or anything that would be a description of the speech. Just the text that Trump would say.
+
+You are Donald Trump presenting groundbreaking academic research to your supporters. Transform the provided research paper into a compelling speech that captures Trump's distinctive communication style while accurately conveying the key findings.
+
+## Speech Style Elements
+- Use simple, declarative sentences
+- Employ frequent superlatives ("tremendous," "incredible," "the best")
+- Add personal commentary ("Believe me, folks," "Nobody knew this before")
+- Include strategic repetition
+- Insert rhetorical questions
+- Break up complex ideas into digestible chunks
+- Use informal, conversational language
+- Add improvisational tangents that circle back to main points
+- Reference "many people saying" or "everybody knows"
+- Contrast with competitors/opposition ("They didn't want you to know this")
+
+## Content Structure
+
+1. Opening (Attention Grab)
+- State how huge/important this research is
+- Mention how nobody else is talking about this
+- Reference the "tremendous people" who did this research
+- Take partial credit for bringing this to light
+
+2. Simplified Findings
+- Present each finding as a "tremendous discovery"
+- Break down complex statistics into simple percentages or general terms
+- Use analogies that relate to business or common experiences
+- Add personal anecdotes that relate to the research
+- Frame technical concepts as "very complicated stuff, but I understand it perfectly"
+
+3. Impact Statement
+- Explain why this matters to "the American people"
+- Connect findings to current events or popular concerns
+- Suggest how this proves your previous statements/positions
+- Include calls to action or policy implications
+
+4. Memorable Conclusion
+- Summarize key points with catchphrases
+- End with a strong, memorable statement
+- Reference "making America great again" if relevant
+- Add a forward-looking statement about winning/success
+
+## Specific Language Patterns
+
+Use these Trump-specific speech patterns:
+- "Folks, let me tell you something..."
+- "Nobody knew [subject] could be so complicated"
+- "We have the best [researchers/scientists/experts], don't we?"
+- "People are saying this is the biggest discovery, maybe ever"
+- "The fake [media/experts/establishment] won't tell you this"
+- "I know more about [subject] than anybody"
+- "Believe me, this is very, very important"
+
+## Format Guidelines
+- Length: 500-600 words
+- Paragraph length: 2-4 sentences maximum
+- Use frequent paragraph breaks
+- Include natural pauses for audience reaction
+- Add all-caps for emphasis on key words
+- Use ellipses to indicate pauses
+- Add parenthetical audience reactions [Applause] [Cheers]
+
+## Essential Elements to Preserve
+- Keep core research findings accurate
+- Maintain the significance of the research
+- Present data in simplified but truthful ways
+- Preserve important causal relationships
+- Include actual statistics (but rounded/simplified)
+
+
+## Example Transition Phrases:
+- "Now, this is incredible, folks..."
+- "Here's something they don't want you to know..."
+- "Let me tell you what we found..."
+- "Nobody's ever seen anything like this..."
+- "The numbers are unbelievable..."
+
+Remember: The goal is to make complex research engaging and memorable while maintaining its essential truth, just delivered in Trump's distinctive style.
+Finally. Output thins in TTS friendly format. new line wherever a short break is needed for instance - but also other TTS friendly output styles
+Only output the text that Trump would say. Nothing else. No intros, notes, statements, descriptions.

prompts/elements.prompt

@@ -0,0 +1,42 @@
+Write an analysis of the provided document covering these key areas:
+
+Core Research Elements:
+
+Primary research questions and objectives
+Key findings and conclusions
+Theoretical frameworks or models introduced
+Most significant statistical or empirical results
+
+Hidden Insights & Nuances:
+
+Unexpected or counterintuitive findings
+Interesting tensions or paradoxes in the data
+Subtle patterns or relationships not highlighted in the abstract
+Compelling real-world examples or illustrative quotes
+Secondary findings that deserve more attention
+
+Methodological Strengths:
+
+Notable aspects of study design
+Sample characteristics or data collection methods
+Novel analytical approaches
+Key limitations and how they were addressed
+Methodological innovations
+
+Practical & Theoretical Implications:
+
+Real-world applications of the findings
+Design or policy recommendations
+Implications for theory development
+Suggested changes to current practices
+Training or educational implications
+
+Critical Connections:
+
+Links to broader debates in the field
+Relationships to previous research
+Gaps or questions raised for future research
+Cross-disciplinary implications
+Historical or contextual significance
+
+Focus on distilling and synthesizing the most important aspects within each section. Include specific details, statistics, and quotes where relevant while maintaining a clear high-level perspective.

prompts/elements_review.prompt

@@ -0,0 +1,73 @@
+# Research Paper Analysis Framework
+
+## Bibliographic Information this paper
+- Paper Title
+- Author(s)
+- Publication Year
+- Journal/Conference
+- DOI/Identifier
+- Citation Impact (if available)
+  - Citation count
+  - Notable citing works
+
+## Core Research Elements
+- Primary research questions and objectives
+- Key findings and conclusions
+- Theoretical frameworks or models introduced
+- Most significant statistical or empirical results
+
+## Hidden Insights & Nuances
+- Unexpected or counterintuitive findings
+- Interesting tensions or paradoxes in the data
+- Subtle patterns or relationships not highlighted in the abstract
+- Compelling real-world examples or illustrative quotes
+- Secondary findings that deserve more attention
+
+## Methodological Strengths
+- Notable aspects of study design
+- Sample characteristics or data collection methods
+- Novel analytical approaches
+- Key limitations and how they were addressed
+- Methodological innovations
+
+## Practical & Theoretical Implications
+- Real-world applications of the findings
+- Design or policy recommendations
+- Implications for theory development
+- Suggested changes to current practices
+- Training or educational implications
+
+## Critical Connections
+- Links to broader debates in the field
+- Relationships to previous research
+- Gaps or questions raised for future research
+- Cross-disciplinary implications
+- Historical or contextual significance
+
+## Literature Review Context
+- Position within current literature
+- Key debates or controversies addressed
+- Theoretical lineage
+- Methodological traditions
+- Research gaps addressed
+
+## References
+
+### Core Theoretical References
+[Full APA citations for works that provide the theoretical foundation]
+
+### Key Methodological References
+[Full APA citations for works that influenced or established the methodological approach]
+
+### Contemporary Related Works
+[Full APA citations for recent relevant research in the same area]
+
+### Critical Opposing Views
+[Full APA citations for works presenting alternative perspectives or critiques]
+
+Instructions: 
+1. Focus on distilling and synthesizing the most important aspects within each section. Include specific details, statistics, and quotes where relevant while maintaining a clear high-level perspective.
+2. For each major point or finding, identify and mark the relevant supporting references that should be included in the reference sections.
+3. Ensure all citations in the text correspond to full APA format references in the appropriate reference category.
+4. Format all references according to current APA guidelines (7th edition).
+5. When referencing works in the text, include page numbers for direct quotes and specific findings to facilitate later citation.

prompts/outline.prompt

@@ -0,0 +1,47 @@
+Create a ~3000 word scholarly overview that analyzes the provided research paper and its significance. The overview should maintain academic rigor while being engaging and accessible to scholars across disciplines. Structure the analysis as follows:
+
+Introduction and Context
+
+
+Frame the research's theoretical and practical significance
+Present core research questions and objectives
+Situate the work within broader academic discourse
+
+
+Analysis of Key Findings
+
+
+Synthesize primary empirical results and their implications
+Examine unexpected discoveries and nuances
+Integrate relevant examples and evidence from the source material
+Balance quantitative findings with qualitative insights
+
+
+Methodological and Theoretical Contributions
+
+
+Analyze research design choices and their effectiveness
+Examine theoretical frameworks and their application
+Highlight methodological innovations
+Consider limitations and constraints
+
+
+Broader Implications
+
+
+Discuss theoretical advances and practical applications
+Explore cross-disciplinary relevance
+Consider future research directions
+Analyze societal and organizational implications
+
+Style Guidelines:
+
+Maintain scholarly tone while ensuring accessibility
+Balance technical precision with engaging narrative
+Use source material examples to illustrate key points
+Present clear logical progression
+Integrate insights from both the paper and supplementary analysis
+Preserve academic rigor while making complex concepts accessible
+
+Please draw from both the original paper and supplementary materials to create a comprehensive yet engaging analysis suitable for an academic audience.
+The overview should illuminate both the explicit findings and deeper implications while maintaining scholarly standards and accessibility.

prompts/outline_acad.prompt

@@ -0,0 +1,69 @@
+Given the provided document create a detailed  - maximum x.x structure depth - scholarly outline for a structured analysis suitable for academic audiences. The outline should maintain rigorous academic standards while enabling clear communication across domains.
+
+Framework for Outline Analysis (only if applicatble given the provided document):
+
+1. Research Context & Significance
+- Position within broader theoretical landscape
+- Key research gaps addressed
+- Cross-disciplinary relevance
+- Historical context and evolution of research area
+- Theoretical frameworks engaged
+
+2. Core Research Elements 
+- Research questions and hypotheses
+- Methodological approach with rationale
+- Analytical frameworks employed
+- Key variables and constructs
+- Critical assumptions and boundary conditions
+- Notable methodological innovations
+
+3. Results & Evidence 
+- Primary empirical findings
+- Statistical significance and effect sizes
+- Qualitative insights
+- Robustness checks and alternative explanations
+- Limitations and constraints
+- Unexpected or contradictory findings
+
+4. Theoretical Contributions
+- Advances to existing theory
+- New theoretical propositions
+- Integration with established frameworks
+- Theoretical tensions identified
+- Cross-domain theoretical implications
+- Areas of theoretical uncertainty
+
+5. Methodological Insights
+- Novel methodological approaches
+- Analytical innovations
+- Data collection strategies
+- Validation techniques
+- Replicability considerations
+- Methodological limitations and mitigation strategies
+
+6. Practical & Research Implications
+- Applications for research design
+- Future research directions
+- Cross-disciplinary research opportunities
+- Policy implications
+- Practical applications
+- Educational/training implications
+
+7. Critical Analysis
+- Strengths and limitations
+- Alternative interpretations
+- Generalizability boundaries
+- Integration with existing literature
+- Unresolved questions
+- Meta-theoretical considerations
+
+The outline should:
+- Maintain scholarly rigor and precision
+- Define domain-specific terms when first used
+- Highlight methodological and theoretical innovations
+- Include specific examples and evidence
+- Present clear logical progression
+- Identify cross-disciplinary connections
+- Balance depth with accessibility
+
+Please provide section headers with specific elements to include under each, focusing on academic audience needs while enabling cross-domain understanding.

prompts/overview.prompt

@@ -0,0 +1,100 @@
+!!!YOUR JOB!!!
+
+Create a ~3000! word analytical overview of the provided document that maintains academic rigor while being engaging and accessible to scholars across disciplines. Follow this structure:
+- Use the provided analysis on Core Research Elements and Hidden Insights & Nuances etc.
+- Use also the provided outline as input
+- Make sure to avoid redundancies
+- for structure in the markdown do not use # just use ** to format headers or emphasize.
+- Start with an introductory paragraph that outlines what has been done and the main findings - an academic hook. Then introduce what will be covered in the overview.
+- Be flexible with the structure and adapt it to the content of the document.
+- Include interesting and relevant quotes/examples from the document.
+- Use measured and academic language.
+
+Frame the research context and significance by:
+
+
+Identifying the core research problem and its broader theoretical implications
+Situating the work within existing academic discourse
+Articulating key research questions and objectives
+Highlighting theoretical and methodological innovations
+
+
+Present the key findings and insights by:
+
+
+Synthesizing primary results and their significance
+Examining unexpected or counterintuitive discoveries
+Analyzing methodological contributions
+Including relevant statistical evidence and empirical data
+Incorporating illustrative examples that demonstrate key points
+
+
+Analyze methodological approach through:
+
+
+Research design choices and rationale
+Sample characteristics and data collection methods
+Analytical frameworks employed
+Treatment of limitations and constraints
+
+
+Explore theoretical and practical implications by:
+
+
+Connecting findings to broader academic discourse
+Identifying contributions to theory development
+Discussing methodological innovations
+Examining cross-disciplinary relevance
+Considering future research directions
+
+
+Critically examine the work's significance by:
+
+
+Analyzing strengths and limitations
+Situating findings within existing literature
+Identifying unresolved questions
+Discussing broader implications for theory and practice
+
+Style guidelines:
+
+Maintain scholarly tone while ensuring accessibility
+Use precise academic language but explain technical terms
+Include specific examples and evidence to illustrate points
+Present clear logical progression of ideas
+Balance depth of analysis with engaging narrative flow
+Incorporate relevant quotes and examples from the source material
+
+The overview should preserve academic rigor while making complex research accessible to scholars across disciplines. Focus on analytical depth while maintaining reader engagement through clear structure and illustrative examples.
+Please use the provided research overview and blog post as reference for content while adapting the style for an academic audience.
+
+
+
+For avoiding inventions!
+
+
+When summarizing research papers, never include examples, analogies, or historical references that aren't explicitly mentioned in the original paper
+All findings, statistics, quotations and specific details must come directly from the source material
+If elaborating on implications or recommendations, stay strictly within what was explicitly discussed in the paper
+When uncertain about whether something was mentioned in the original, err on the side of omitting it
+
+
+For making the language more accessible!
+
+
+Use clear, direct language that a general educated audience would understand
+Avoid unnecessary academic jargon and complex sentence structures
+Avoid bullets to be suitable for TTS i.e. Reads naturally when spoken
+Replace phrases like "cognitive stewardship" with simpler terms unless they're specifically used in the original paper
+Break up long sentences into shorter ones
+Use active voice where possible
+Express ideas in plain language while maintaining accuracy
+
+The goal should be a summary that accurately captures the research while being readable and engaging for a broader audience.
+For example, instead of:
+"The empirical heart of the study beats with a mixed-methods approach, combining quantitative rigor with qualitative depth."
+Write:
+"The study used both numbers (surveys) and detailed examples (interviews) to understand how people use AI."
+
+Remember ~3000! words max - be thorough but selective. Find a good balance.
+Only output the final overview text. No additional intros, notes, statements.

prompts/papers_outline.prompt

@@ -0,0 +1,63 @@
+Analyze the above structured outputs from academic papers to create a detailed comparative outline for a literature review. Follow these specific requirements:
+
+COMPARATIVE DIMENSIONS:
+Systematically analyze and compare the papers across these key dimensions:
+
+
+Theoretical Frameworks & Models
+Methodological Approaches
+Research Questions & Objectives
+Key Findings & Conclusions
+Practical Implications
+Knowledge Gaps & Future Directions
+
+
+ANALYSIS REQUIREMENTS:
+For each dimension:
+
+
+Identify areas of consensus and disagreement
+Note methodological similarities and differences
+Highlight complementary or contradictory findings
+Map theoretical connections and divergences
+Track evolution of ideas across papers
+Document shared and unique contributions
+
+
+OUTLINE STRUCTURE:
+Generate a detailed outline that best fits the domain and content of the papers. The structure should:
+
+
+Use clear hierarchical organization
+Reflect the natural themes and patterns in the literature
+Adapt to discipline-specific conventions
+Create logical flow between sections
+Allow for flexible categorization of findings
+
+
+SPECIAL CONSIDERATIONS:
+
+
+Note chronological developments in the field
+Identify emerging trends or patterns
+Highlight innovative approaches or findings
+Document interconnections between papers
+Track citation patterns and influences
+
+
+OUTPUT REQUIREMENTS:
+
+
+Use clear, hierarchical structure
+Include specific examples from papers
+Note paper-specific identifiers for each point
+Maintain balanced coverage of all papers
+Highlight key quotes or statistics where relevant
+
+FINAL GUIDELINES:
+
+Ensure each major point references specific papers
+Identify clear themes and patterns across papers
+Note both similarities and differences explicitly
+Maintain analytical depth while ensuring clarity
+Create logical connections between sections

prompts/papers_synthesis.prompt

@@ -0,0 +1,51 @@
+# Build an integrated literature review synthesis
+
+Using the paper summaries, comparative table, and detailed outline provided above, generate a focused literature review (2500 words) that synthesizes these materials. The structure should follow the themes and organization established in the outline while adhering to domain-specific conventions.
+
+1. DOCUMENT STRUCTURE:
+- Title (specific to the domain and topic)
+- Introduction (scope and purpose)
+- Sections as outlined in the analysis above
+- Comparative overview (featuring the provided table)
+- Conclusions and implications
+- References (Harvard style)
+
+2. FORMATTING REQUIREMENTS:
+- Use markdown formatting 
+- Include clear section headers following the outline
+- Present comparative table where most relevant to the analysis
+- In the table make sure to reference papers with proper academic citations not filenames.
+- Maximum 4 columns in tables
+- Place paper identifiers in a full row to save space
+- Standard markdown without additional ``` markers
+- Add --- before and after the table for clear separation. When adding this before the table also add a new line additional before the table to ensure proper formatting.
+
+3. CONTENT INTEGRATION:
+- Structure narrative according to the themes identified in the outline
+- Incorporate comparative table to support key arguments
+- Build on the patterns and relationships already identified
+- Maintain clear connections between outlined themes
+- Support arguments with specific references from the analysis
+- Ensure smooth transitions between established themes
+- Develop insights from the comparative analysis
+- Conclude based on the synthesized findings
+- Dicuss in detail how summarized focal papers relate to relevant broader literature - and reference that - also in the filal reference list
+
+4. TECHNICAL SPECIFICATIONS:
+- Length: 2500 words (excluding table and references)
+- Academic language appropriate to the discipline
+- APA style citations
+- Complete reference list
+- Refer to papers with proper academic citations, not filenames
+- Adapt style and emphasis to disciplinary norms
+
+Papers, Table, and Outline Analysis provided above.
+
+FINAL GUIDELINES:
+1. Follow the structural themes established in the outline
+2. Integrate comparative findings from the table
+3. Maintain disciplinary conventions and focus
+4. Emphasize patterns identified in the analysis
+5. Present synthesis without additional instructions
+6. Adapt depth and emphasis based on the domain
+7. The output is turned into PDF later with makdownn_pdf package. It is important that the output is a markdown with proper hierarchies.

prompts/papers_table.prompt

@@ -0,0 +1,46 @@
+
+
+
+# Build a dynamic comparative table outline
+
+
+| Paper ID | Aspect 1 | Aspect 2 | Aspect 3 | Aspect 4 |
+|----------|----------|----------|----------|----------|
+| Paper 1  |          |          |          |          |
+| Paper 2  |          |          |          |          |
+
+
+Analyze the structured outputs from the above papers and create a comparative table that best represents their key similarities and differences. Follow these guidelines:
+
+1. TABLE DESIGN:
+- Determine the most appropriate columns (max 4 aspects) based on the common elements and key differences in the papers
+- Design a table structure that highlights the most significant comparative aspects
+- Create column headers that reflect the actual content patterns found across papers
+
+2. COMPARISON APPROACH:
+- Identify recurring themes and patterns across papers
+- Extract comparable elements that appear in multiple papers
+- Note unique aspects that might warrant special columns or annotations
+- Consider both explicit similarities and implicit connections
+
+3. CONTENT ORGANIZATION:
+- Structure information to facilitate meaningful comparisons
+- Ensure balanced representation of each paper
+- Maintain appropriate level of detail for each element
+- Include relevant context where necessary
+
+4. FORMAT REQUIREMENTS:
+- Use markdown table syntax
+- Present information clearly and consistently
+- Include paper identifiers for reference
+- Use formatting that enhances readability and comparison
+
+ANALYSIS GUIDELINES:
+1. First analyze the papers to identify the most relevant comparative dimensions (Do not output this analysis)
+2. Design a table structure that best captures these dimensions
+3. Ensure the table structure serves the comparison purpose effectively
+4. Include any notes about patterns or relationships that emerge
+5. Consider adding brief explanatory text if the table structure needs clarification
+6. output only the table and brief notes if necessary
+
+Based on your analysis of the papers, please generate a comparative table with a structure and columns that best represent the key points of comparison.

requirements.txt

@@ -0,0 +1,7 @@
+google-genai
+markdown-pdf
+kokoro
+soundfile
+python-dotenv
+nest_asyncio
+pikepdf

utils/__init__.py

@@ -0,0 +1,22 @@
+from .llm_utils import (
+    get_generation_model, 
+    async_generate_text, 
+    generate_title_reference_and_classification, 
+    upload_to_gemini, 
+    wait_for_files_active
+)
+
+from .file_utils import (
+    load_prompt, 
+    save_intermediate_output, 
+    setup_temp_directories, 
+    cleanup_temp_files
+)
+
+from .review_flow import (
+    process_single_pdf, 
+    process_multiple_pdfs, 
+    generate_final_review_pdf,
+    create_comparative_table_prompt)
+
+from .tts_utils import generate_tts_audio

utils/file_utils.py

@@ -0,0 +1,36 @@
+# file_utils.py
+import os
+import tempfile
+import shutil
+import logging
+import streamlit as st
+
+logger = logging.getLogger(__name__)
+
+@st.cache_data
+def load_prompt(filepath):
+    with open(filepath, "r", encoding="utf-8") as f:
+        data = f.read()
+    logger.debug("Loaded prompt from %s (length: %d)", filepath, len(data))
+    return data
+
+def save_intermediate_output(content, pdf_basename, suffix):
+    file_path = os.path.join("promp_tmp", f"{pdf_basename}_{suffix}.txt")
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(content)
+    logger.debug("Saved intermediate output to %s", file_path)
+
+def setup_temp_directories():
+    if not os.path.exists("promp_tmp"):
+        os.makedirs("promp_tmp")
+        logger.debug("Created directory 'promp_tmp'.")
+    temp_dir = tempfile.mkdtemp(prefix="pdf_digester_")
+    logger.debug(f"Created temporary directory: {temp_dir}")
+    return temp_dir
+
+def cleanup_temp_files(temp_dir):
+    try:
+        shutil.rmtree(temp_dir)
+        logger.debug(f"Cleaned up temporary directory: {temp_dir}")
+    except Exception as e:
+        logger.error(f"Failed to cleanup temporary directory: {e}")

utils/llm_utils.py

@@ -0,0 +1,130 @@
+# llm_utils.py
+import os
+import time
+import asyncio
+import json
+import logging
+import streamlit as st
+
+from google import genai
+from google.genai import types
+
+logger = logging.getLogger(__name__)
+
+# Initialize the Gemini client using the new SDK
+client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+
+def get_generation_model(model_type: str):
+    if model_type == "flash":
+        model_name = "gemini-2.0-flash"
+    else:
+        model_name = "gemini-2.0-flash-thinking-exp-01-21"
+    generation_config = types.GenerateContentConfig(
+        temperature=0.7,
+        top_p=0.95,
+        top_k=64,
+        max_output_tokens=65536,
+        response_mime_type="text/plain",
+    )
+    return model_name, generation_config
+
+async def async_generate_text(prompt, pdf_file=None, model_name=None, generation_config=None):
+    contents = [pdf_file, prompt] if pdf_file else prompt
+    while True:
+        try:
+            st.toast("Sending prompt to the model...")
+            response = await client.aio.models.generate_content(
+                model=model_name,
+                contents=contents,
+                config=generation_config,
+            )
+            st.toast("Received response from the model.")
+            logger.debug("Generated text for prompt. Length: %d", len(response.text))
+            return response.text
+        except Exception as e:
+            logger.exception("Error during asynchronous LLM API call:")
+            st.toast("Error during asynchronous LLM API call: " + str(e))
+            await asyncio.sleep(30)
+
+def clean_json_response(response_text: str) -> str:
+    stripped = response_text.strip()
+    if stripped.startswith("```"):
+        lines = stripped.splitlines()
+        if lines[0].strip().startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        return "\n".join(lines).strip()
+    return response_text
+
+class TitleReference:
+    def __init__(self, title=None, apa_reference=None, classification=None, bullet_list=None, error=None):
+        self.title = title
+        self.apa_reference = apa_reference
+        self.classification = classification
+        self.bullet_list = bullet_list or []
+        self.error = error
+
+async def generate_title_reference_and_classification(pdf_file, title_model_name, title_generation_config):
+    title_prompt = (
+        "Analyze the uploaded document and determine if it is a valid academic article. "
+        "If it is a valid academic article, generate a concise and engaging title, an APA formatted reference, and classify the paper as 'Good academic paper'. "
+        "Also, generate a bullet list for the following items: context, method, theory, main findings. "
+        "If it is not a valid academic article (for example, if it is too short or just a title page), "
+        "classify it as 'Not a valid academic paper' and return an 'error' key with an appropriate message. "
+        "Output the result strictly in JSON format with keys 'title', 'apa_reference', 'classification', and 'bullet_list'. "
+        "The 'bullet_list' value should be an array of strings. Do not include any extra commentary."
+    )
+    response_text = await async_generate_text(
+        title_prompt,
+        pdf_file,
+        model_name=title_model_name,
+        generation_config=title_generation_config
+    )
+    logger.debug("Title/Reference generation response: %s", response_text)
+    cleaned_response = clean_json_response(response_text)
+    logger.debug("Cleaned Title/Reference JSON: %s", cleaned_response)
+    try:
+        data = json.loads(cleaned_response)
+    except Exception as e:
+        logger.exception("Invalid JSON returned: %s", e)
+        raise Exception("Invalid JSON returned: " + str(e))
+    
+    if "error" in data:
+        return TitleReference(error=data["error"])
+    else:
+        required_keys = ["title", "apa_reference", "classification", "bullet_list"]
+        if any(key not in data for key in required_keys):
+            raise Exception("Expected keys 'title', 'apa_reference', 'classification', and 'bullet_list' not found in response.")
+        return TitleReference(
+            title=data["title"],
+            apa_reference=data["apa_reference"],
+            classification=data["classification"],
+            bullet_list=data["bullet_list"]
+        )
+        
+        
+# Add these functions so they can be imported elsewhere
+def upload_to_gemini(file_path, mime_type=None):
+    client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+    file = client.files.upload(file=file_path)
+    st.toast(f"Uploaded file '{file.display_name}' as: {file.uri}")
+    logger.debug("Uploaded file: %s with URI: %s", file.display_name, file.uri)
+    return file
+
+def wait_for_files_active(files):
+    st.toast("Waiting for file processing...")
+    client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+    for file in files:
+        current_file = client.files.get(name=file.name)
+        logger.debug("Initial state for file %s: %s", file.name, current_file.state.name)
+        while current_file.state.name == "PROCESSING":
+            time.sleep(10)
+            current_file = client.files.get(name=file.name)
+            logger.debug("Polling file %s, state: %s", file.name, current_file.state.name)
+        if current_file.state.name != "ACTIVE":
+            error_msg = f"File {current_file.name} failed to process, state: {current_file.state.name}"
+            logger.error(error_msg)
+            raise Exception(error_msg)
+    st.toast("All files processed and ready.")
+    logger.debug("All files are active.")

utils/markdown_utils.py

@@ -0,0 +1,41 @@
+# markdown_utils.py
+
+import re
+
+def robust_clean_markdown(text):
+    """
+    Cleans markdown text by removing code fences, normalizing headings, and removing extra blank lines.
+    """
+    # Remove code fences with optional language specifiers.
+    text = re.sub(r"```(?:\w+)?\n", "", text)
+    text = re.sub(r"\n```", "", text)
+    
+    # Normalize heading formats: ensure exactly one space after '#' symbols.
+    def fix_heading(match):
+        hashes = match.group(1)
+        title = match.group(2).strip()
+        return f"{hashes} {title}"
+    text = re.sub(r"^(#{1,6})\s*(.*)$", fix_heading, text, flags=re.MULTILINE)
+    
+    # Remove extra blank lines.
+    text = re.sub(r'\n\s*\n', '\n\n', text)
+    return text.strip()
+
+def normalize_heading_levels(text):
+    """
+    Adjusts all heading levels so that the highest-level (smallest number of '#' characters)
+    heading becomes level 1. For example, if the smallest heading in the document is '###',
+    all headings will be promoted by 2 levels.
+    """
+    # Find all heading levels in the text.
+    heading_levels = [len(match.group(1)) for match in re.finditer(r"^(#{1,6})\s", text, flags=re.MULTILINE)]
+    if heading_levels:
+        min_level = min(heading_levels)
+        # Only adjust if the minimum level is greater than 1.
+        if min_level > 1:
+            def adjust_heading(match):
+                current_level = len(match.group(1))
+                new_level = current_level - (min_level - 1)
+                return "#" * new_level + " "
+            text = re.sub(r"^(#{1,6})\s", adjust_heading, text, flags=re.MULTILINE)
+    return text

utils/review_flow.py

@@ -0,0 +1,188 @@
+import os
+import time
+import asyncio
+import logging
+import streamlit as st
+from markdown_pdf import MarkdownPdf, Section
+from utils.file_utils import load_prompt, save_intermediate_output
+from utils.llm_utils import get_generation_model, async_generate_text, upload_to_gemini, wait_for_files_active
+
+logger = logging.getLogger(__name__)
+
+# Get model configuration (using the "thinking" variant)
+default_model_name, default_generation_config = get_generation_model("thinking")
+
+def create_comparative_table_prompt(structured_outputs, table_base_prompt):
+    """
+    Create a prompt to generate a comparative table.
+    This internal prompt is not shown to the user.
+    """
+    prompt = "Structured Outputs from the PDF Papers:\n"
+    for paper_id, content in structured_outputs.items():
+        prompt += f"\nPaper: {paper_id}\n-------\n{content}\n"
+    prompt += "\n" + table_base_prompt + "\n"
+    return prompt
+
+async def generate_comparative_table(structured_outputs):
+    """
+    Generate the comparative table (hidden from the user).
+    """
+    papers_table_prompt_path = os.path.join("prompts", "papers_table.prompt")
+    table_base_prompt = load_prompt(papers_table_prompt_path)
+    table_prompt = create_comparative_table_prompt(structured_outputs, table_base_prompt)
+    logger.info("Generating dynamic comparative table...")
+    table_output = await async_generate_text(
+        table_prompt,
+        model_name=default_model_name,
+        generation_config=default_generation_config
+    )
+    return table_output
+
+async def process_single_pdf(file_obj, elements_prompt):
+    """
+    Process a single PDF: save it locally, upload it, wait for processing,
+    and extract its structured output.
+    """
+    pdf_basename = file_obj.name
+    temp_pdf_path = os.path.join("promp_tmp", pdf_basename)
+    with open(temp_pdf_path, "wb") as f:
+        f.write(file_obj.getbuffer())
+    
+    st.toast(f"Uploading and processing {pdf_basename}...")
+    logger.info(f"Processing {pdf_basename}...")
+    
+    # Upload the file and wait until it's active.
+    uploaded_file = upload_to_gemini(temp_pdf_path, mime_type="application/pdf")
+    wait_for_files_active([uploaded_file])
+    
+    st.toast(f"Extracting content from {pdf_basename}...")
+    result = await async_generate_text(
+        elements_prompt,
+        pdf_file=uploaded_file,  # NOTE: using 'pdf_file' to match the expected parameter
+        model_name=default_model_name,
+        generation_config=default_generation_config
+    )
+    logger.info(f"Completed extraction for {pdf_basename}")
+    return pdf_basename, result
+
+async def process_multiple_pdfs(uploaded_files):
+    """
+    Process multiple PDFs concurrently and return a dictionary mapping filenames
+    to their structured outputs.
+    Raises an exception if fewer than 2 files are provided.
+    """
+    if len(uploaded_files) < 2:
+        raise Exception("Please provide at least two PDF files for review.")
+    elements_prompt_path = os.path.join("prompts", "elements_review.prompt")
+    elements_prompt = load_prompt(elements_prompt_path)
+    
+    tasks = []
+    for file_obj in uploaded_files:
+        tasks.append(asyncio.create_task(process_single_pdf(file_obj, elements_prompt)))
+        await asyncio.sleep(1)  # slight delay between scheduling tasks
+    intermediate_results = await asyncio.gather(*tasks)
+    structured_outputs = {fname: output for fname, output in intermediate_results}
+    return structured_outputs
+
+async def generate_final_review_pdf(structured_outputs):
+    """
+    Generate the final literature review by performing the following steps:
+      0. (Hidden) Generate a comparative table.
+      1. Draft the outline.
+      2. Generate the final synthesis (incorporating the comparative table, outline, and structured outputs).
+      3. Check the final writeup for hallucinations/inaccuracies.
+      4. Clean up the final text and convert it to PDF.
+      
+    All prompts (except the check prompt) are loaded from files.
+    The check prompt remains hardcoded.
+    """
+    progress_bar = st.progress(0)
+    st.toast("Starting review generation...")
+    time.sleep(0.5)
+    
+    # Step 0: Hidden comparative table generation.
+    table_analysis = await generate_comparative_table(structured_outputs)
+    progress_bar.progress(10)
+    time.sleep(0.5)
+    
+    # Step 1: Draft the outline.
+    with st.spinner("Drafting outline..."):
+        outline_prompt_path = os.path.join("prompts", "papers_outline.prompt")
+        outline_prompt = load_prompt(outline_prompt_path)
+        for fname, output in structured_outputs.items():
+            outline_prompt += f"\nPaper: {fname}\n-------\n{output}\n\n"
+        outline = await async_generate_text(
+            outline_prompt,
+            model_name=default_model_name,
+            generation_config=default_generation_config
+        )
+    st.success("Outline drafted!")
+    progress_bar.progress(30)
+    time.sleep(0.5)
+    
+    # Step 2: Draft the final review.
+    with st.spinner("Drafting final review..."):
+        synthesis_prompt_path = os.path.join("prompts", "papers_synthesis.prompt")
+        loaded_final_prompt = load_prompt(synthesis_prompt_path)
+        final_prompt = ""
+        final_prompt += "\nComparative Table:\n" + table_analysis + "\n\n"
+        final_prompt += "Comparative Outline:\n" + outline + "\n\n"
+        final_prompt += "Papers for Analysis:\n"
+        for fname, output in structured_outputs.items():
+            final_prompt += f"\nPaper: {fname}\n-------\n{output}\n\n"
+        final_prompt += "\n" + loaded_final_prompt
+        
+        final_writeup = await async_generate_text(
+            final_prompt,
+            model_name=default_model_name,
+            generation_config=default_generation_config
+        )
+    st.success("Final review drafted!")
+    progress_bar.progress(60)
+    time.sleep(0.5)
+    
+    # Step 3: Check final writeup (using the hardcoded check prompt).
+    with st.spinner("Checking final review..."):
+        check_prompt = (
+            "Review the following final literature review writeup along with the structured outputs from the source papers. "
+            "Your task is to ensure that there are no hallucinations or inaccuracies in the final writeup. "
+            "If any issues are detected, make the most minimal edits necessary to correct them. Otherwise, do not change anything in the text - nor the style or format. "
+            "Output only the final text (do not include any explanations or extra instructions).\n\n"
+            
+            "Final Writeup:\n"
+            "----------------\n"
+            f"{final_writeup}\n\n"
+            
+            "Structured Outputs:\n"
+        )
+        for fname, output in structured_outputs.items():
+            check_prompt += f"\nPaper: {fname}\n-------\n{output}\n\n"
+        final_checked_writeup = await async_generate_text(
+            check_prompt,
+            model_name=default_model_name,
+            generation_config=default_generation_config
+        )
+    st.success("Review check complete!")
+    progress_bar.progress(80)
+    time.sleep(0.5)
+    
+    # Step 4: Generate PDF output.
+    with st.spinner("Generating PDF output..."):
+        from utils.markdown_utils import robust_clean_markdown, normalize_heading_levels
+        final_checked_review = final_checked_writeup.strip()
+        final_checked_review = robust_clean_markdown(final_checked_review)
+        final_checked_review = normalize_heading_levels(final_checked_review)
+        
+        pdf_doc = MarkdownPdf(toc_level=2)
+        pdf_doc.add_section(Section(final_checked_review, toc=True))
+        output_pdf_path = "final_literature_review.pdf"
+        try:
+            pdf_doc.save(output_pdf_path)
+            st.success("PDF successfully created!")
+            logger.info(f"PDF successfully created: {output_pdf_path}")
+        except Exception as e:
+            st.toast("Error generating PDF output: " + str(e))
+            logger.error(f"Error generating PDF: {e}")
+        progress_bar.progress(100)
+    
+    return final_checked_review

utils/tts_utils.py

@@ -0,0 +1,39 @@
+# tts_utils.py
+import os
+import time
+import logging
+import requests
+import streamlit as st
+
+logger = logging.getLogger(__name__)
+
+def generate_tts_audio(text, voice="af_heart", speed=1.0):
+    RUNPOD_API_TOKEN = os.getenv("RUNPOD_GPU")
+    headers = {
+        'Content-Type': 'application/json',
+        'Authorization': f'Bearer {RUNPOD_API_TOKEN}'
+    }
+    data_payload = {"input": {"text": text, "voice": voice, "speed": speed}}
+    response = requests.post('https://api.runpod.ai/v2/ozz8w092oprwqx/run', headers=headers, json=data_payload)
+    if response.status_code != 200:
+        raise Exception(f"RunPod API call failed with status {response.status_code}: {response.text}")
+    run_id = response.json().get("id")
+    status_url = f"https://api.runpod.ai/v2/ozz8w092oprwqx/status/{run_id}"
+    st.toast("TTS generation started, please wait...")
+    while True:
+        time.sleep(5)
+        status_response = requests.post(status_url, headers=headers, json=data_payload)
+        status_json = status_response.json()
+        logger.debug("TTS status: %s", status_json.get("status"))
+        if status_json.get("status") == "COMPLETED":
+            download_url = status_json.get("output", {}).get("download_url")
+            if download_url:
+                mp3_response = requests.get(download_url)
+                if mp3_response.status_code == 200:
+                    return mp3_response.content
+                else:
+                    raise Exception(f"Failed to download audio: {mp3_response.status_code}")
+        elif status_json.get("status") in ["FAILED", "ERROR"]:
+            logger.error("TTS generation failed.")
+            st.error("TTS generation failed. Please try again later.")
+            raise Exception("TTS generation failed.")