improve readme

lec2note/ingestion/whisper_runner.py

@@ -20,7 +20,7 @@ class WhisperRunner:  # noqa: D101
     model_name: str = "large-v3"
 
     @classmethod
-    def transcribe(cls, audio_fp: str | Path, lang: str = None) -> List[Dict[str, Any]]:
+    def transcribe(cls, audio_fp: str | Path, lang: str = "auto") -> List[Dict[str, Any]]:
         """Transcribe ``audio_fp`` and return list with start/end/text.
 
         Notes

lec2note/processing/processor.py

@@ -23,9 +23,16 @@ class Processor:  # noqa: D101
 
     @staticmethod
     def _img_to_data_uri(img_path: Path) -> str:
+        """Convert image to data URI; return empty string if path invalid."""
+        if not img_path or not Path(img_path).is_file():
+            return ""
         img_path = Path(img_path)
         mime, _ = mimetypes.guess_type(img_path)
-        b64 = base64.b64encode(img_path.read_bytes()).decode()
+        try:
+            b64 = base64.b64encode(img_path.read_bytes()).decode()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("[Processor] failed reading image %s: %s", img_path, exc)
+            return ""
         return f"data:{mime};base64,{b64}"
 
     @staticmethod
@@ -59,34 +66,35 @@ class Processor:  # noqa: D101
 
         # Prompt with explicit mapping guidance
         prompt_text = (
-            "**Role**: You are an expert academic assistant tasked with taking notes from a part of a lecture which will be ultimately merged into a comprehensive and detailed note.\n\n"
-            "**Primary Objective**: Generate a **comprehensive and detailed** note segment in Markdown. Do not omit details or simplify concepts excessively. Your goal is to capture the full context of the lecture segment.\n\n"
-            "**Return Format**: Only return the **note** in Markdown format.\n\n"
+            "Let's think step by step.\n\n"
+            "**Role**: You are an expert academic assistant processing one segment of a longer lecture. Your output for this segment will be merged with others later by a senior editor.\n\n"
+            "**Primary Objective**: Act as a **high-fidelity recorder of information**. Your goal is to generate a comprehensive and detailed note segment in Markdown, capturing the full context of this specific segment. **Do NOT add broad introductions or conclusions** that might be redundant in the final merged document.\n\n"
+            "**Return Format**: Only return the **note segment** in Markdown format, focusing exclusively on the materials provided.\n\n"
             "**Key Instructions**:\n\n"
-            "1.  **Capture Emphasized Points**: Pay close attention to the subtitles. Identify and highlight key points that the speaker seems to emphasize, such as repeated phrases, direct statements of importance (e.g., 'the key is...', 'remember that...'), and core definitions.\n\n"
-            "2.  **Integrate Visuals (Formulas & Tables)**: You MUST analyze the accompanying images. If an image contains crucial information like **formulas, equations, tables, code snippets, or important diagrams**, you must accurately transcribe it into the Markdown note to support the text. Follow these formats:\n"
+            "1.  **Identify the Segment's Core Purpose**: Analyze the materials to determine the main purpose of this specific segment (e.g., 'Is it defining a term?', 'Is it presenting a problem?', 'Is it proposing a solution?'). Structure your note around this local purpose.\n\n"
+            "2.  **Transcribe Visuals with Precision**: You MUST analyze the accompanying images. If an image contains crucial information like **formulas, equations, tables, code snippets, or algorithms**, you must accurately transcribe it into the Markdown note to support the text. Follow these formats:\n"
             "    - For **formulas and equations**, use LaTeX notation (e.g., enclose with `$` or `$$`).\n"
             "    - For **tables**, recreate them using Markdown table syntax.\n"
-            "    - For **code**, use Markdown code blocks with appropriate language identifiers.\n\n"
-            "3.  **Structure and Format**: Organize the notes logically. Use headings, subheadings, lists, and bold text to create a clear, readable, and well-structured document.\n\n"
-            "4.  **Language**: The notes'language should align with the subtitles!!!.\n\n"
-            "5.  **Image Mapping**: Stop referencing the images and try to use formulas, tables, code snippets, or important diagrams to describe the images.\n\n"
-            "---BEGIN LECTURE MATERIALS---\n"
-            f"**Subtitles (placeholders inserted)**:\n{placeholder_subs}"
-            "---END LECTURE MATERIALS---\n"
+            "    - For **algorithms or code**, use Markdown code blocks with appropriate language identifiers (e.g., pseudocode, python).\n\n"
+            "3.  **Capture Emphasized Verbal Points**: From the subtitles, identify and highlight key points, definitions, and direct statements of importance (e.g., 'the key is...', 'the problem is...').\n\n"
+            "4.  **Do Not Reference Images Directly**: Integrate the visual information seamlessly. Instead of writing 'As shown in IMG1', transcribe the formula from IMG1 directly into the text where it is discussed.\n\n"
+            "5.  **Language**: The notes' language should align with the subtitles.\n\n"
+            "---BEGIN LECTURE SEGMENT---\n"
+            f"**Subtitles (with image placeholders)**:\n{placeholder_subs}\n"
+            "---END LECTURE SEGMENT---"
         )
         
-        parts: List[Dict[str, Any]] = [
-            {"type": "text", "text": prompt_text}
-        ]
-        for idx,visual_chunk in enumerate(chunk.visual_chunks, start=1):  # Limit to 6 images
-            parts.append({
-                "type": "image_url",
-                "image_url": {
-                    "url": cls._img_to_data_uri(visual_chunk.image_path),
-                    "detail": f"IMG{idx}", 
-                },
-            })
+        parts: List[Dict[str, Any]] = [{"type": "text", "text": prompt_text}]
+        for idx, visual_chunk in enumerate(chunk.visual_chunks, start=1):
+            data_uri = cls._img_to_data_uri(visual_chunk.image_path)
+            if not data_uri:
+                continue  # skip invalid image
+            parts.append(
+                {
+                    "type": "image_url",
+                    "image_url": {"url": data_uri, "detail": f"IMG{idx}"},
+                }
+            )
         
         return [{"role": "user", "content": parts}]
 
@@ -96,5 +104,5 @@ class Processor:  # noqa: D101
         # collect text for this chunk
         messages = cls._build_messages(chunk)
         note = cls._call_llm(messages)
-        images=[visual_chunk.image_path for visual_chunk in chunk.visual_chunks]
+        images=[vc.image_path for vc in chunk.visual_chunks if vc.image_path and Path(vc.image_path).is_file()]
         return NoteChunk(note=note, images=images)

lec2note/synthesis/assembler.py

@@ -45,18 +45,20 @@ class Assembler:  # noqa: D101
                                 {
                                     "role": "user",
                                     "content": (
-                                        "You are an expert academic editor and content synthesizer. Your task is to transform a collection of fragmented lecture notes into a single, coherent, detailed and logically structured study note.\n\n"
-                                        "**Context:** These notes were generated by summarizing different segments of a single video lecture. As a result, they are chronologically ordered but probably contain significant overlap and redundancy.\n\n"
-                                        "**Primary Goal:** Create a comprehensive and well-organized final document from the provided segements.\n\n"
-                                        "**Key Instructions:**\n"
-                                        "1.  **De-duplicate and Consolidate:** Identify all repetitive definitions and explanations. Merge them into a single, comprehensive section for each core concept. \n"
-                                        "2.  **Synthesize and Enhance:** Where different fragments explain the same concept with slightly different examples or details (e.g., one note uses a 'cheetah' example, another uses a 'robot'), synthesize these details to create a richer, more complete explanation under a single heading.\n"
-                                        "3.  **Polish and Format:** Ensure the final text is grammatically correct, flows naturally, and uses consistent, clean Markdown formatting (e.g., for tables, code blocks, and mathematical notation).\n\n"
-                                        "4.  **Language:** The notes' language should align with the subtitles!!!.\n\n"
-                                        "**Constraint:** Ensure all unique concepts and key details from the original notes are preserved in the final document. The goal is to lose redundancy, not information.\n\n"
+                                        "Let's think step by step.\n\n"
+                                        "**Role**: You are an **expert educator and storyteller**, tasked with synthesizing fragmented notes into a master study guide.\n\n"
+                                        "**Context**: These notes were generated from sequential segments of a single video lecture. They are detailed but contain significant repetition and lack a coherent, overarching narrative.\n\n"
+                                        "**Primary Goal**: Create a definitive, standalone educational document that not only summarizes the content but also explains the underlying **narrative and logic** of the lecture. The final note should be good enough for someone to learn the topic from scratch.\n\n"
+                                        "**Key Instructions**:\n\n"
+                                        "1.  **Establish a Logical Narrative (Explain the 'Why')**: This is your most important task. Do NOT simply list topics. Find the story. Ask yourself: 'What problem is being introduced first? What solution is proposed next? How does each concept build upon the previous one?' Structure the final note to reflect this **problem-solution arc** or logical progression. For example, when introducing 'Actor-Critic', explicitly state that it is a solution to the 'high variance' problem in earlier methods.\n\n"
+                                        "2.  **De-duplicate and Consolidate**: Identify all repetitive definitions (e.g., 'State vs. Observation' is likely defined multiple times). Merge them into a single, comprehensive section for each core concept. The first mention is usually the most important.\n\n"
+                                        "3.  **Highlight Key Trade-offs**: Based on the content, identify and explicitly state any important trade-offs discussed (e.g., 'Bias vs. Variance' in estimation methods, 'On-Policy vs. Off-Policy' sample efficiency). Use a table or bullet points to make these comparisons clear and easy to understand.\n\n"
+                                        "4.  **Synthesize and Enhance**: Where different fragments explain the same concept with slightly different examples (e.g., one note uses a 'cheetah' example, another uses a 'robot'), synthesize these details to create a richer, more complete explanation under a single heading.\n\n"
+                                        "5.  **Structure and Polish**: Create a clean, hierarchical structure with a main title, sections (e.g., `## 1. The Problem of X`), and subsections. Ensure the final text is grammatically correct and flows naturally.\n\n"
+                                        "**Constraint**: The goal is to lose redundancy, not information. Ensure all unique concepts, formulas, and key details from the original fragments are preserved in the final, structured document.\n\n"
                                         "Here are the fragmented notes to process:\n\n"
                                         f"{raw_md}"
-                                    ),
+                                    )
                                 }
                             ],
                         )