chore: folder rename and changelog formatting

- Rename _template_original/ to project_template_original/ for clarity
- CHANGELOG.md formatting adjustments

Co-Authored-By: Claude <noreply@anthropic.com>

CHANGELOG.md

@@ -9,11 +9,13 @@
 **Implementation:**
 
 1. **Added session log management** (`llm_client.py`)
+
    - Module-level `_SESSION_LOG_FILE` variable
    - `get_session_log_file()` - Creates/reuses session log file
    - `reset_session_log()` - For testing/new runs
 
 2. **Changed log file naming**
+
    - Old: `log/llm_context_YYYYMMDD_HHMMSS.txt` (per question)
    - New: `log/llm_session_YYYYMMDD_HHMMSS.txt` (per evaluation run)
 
@@ -23,6 +25,7 @@
    - All questions append to same file
 
 **Modified Files:**
+
 - **src/agent/llm_client.py** (~50 lines modified)
   - Added session log management functions
   - Updated `synthesize_answer_hf()` to use session log
@@ -37,21 +40,25 @@
 **Score:** 30% (6/20 correct) - **First time hitting course target! 🎉**
 
 **Phase 1 Impact - YouTube + Audio Support:**
+
 - **Before:** 10% (2/20 correct)
 - **After:** 30% (6/20 correct)
 - **Improvement:** +20% (+4 questions fixed)
 
 **Questions Fixed by Phase 1:**
+
 1. a1e91b78: YouTube bird species (3) ✓ - youtube_transcript + Whisper
 2. 9d191bce: YouTube Teal'c quote (Extremely) ✓ - youtube_transcript + Whisper
 3. 99c9cc74: Strawberry pie MP3 (ingredients) ✓ - transcribe_audio (Whisper)
 4. 1f975693: Calculus MP3 (page numbers) ✓ - transcribe_audio (Whisper)
 
 **Remaining Issues:**
+
 - 3 system errors (vision NoneType, .py execution, calculator)
 - 10 "Unable to answer" (search evidence extraction issues)
 
 **Next Priority:**
+
 - Fix system errors (vision tool, Python execution)
 - Improve search answer extraction
 - Consider Phase 2.5 improvements
@@ -65,6 +72,7 @@
 **Solution:** Implemented Chain of Thought (CoT) format - LLM now provides reasoning before final answer.
 
 **Response Format:**
+
 ```
 REASONING: [Step-by-step thought process]
 - What information is in the evidence?
@@ -78,15 +86,18 @@ FINAL ANSWER: [Factoid answer]
 **Implementation:**
 
 1. **Updated system_prompt** (all 3 providers: HF, Groq, Claude)
+
    - Request two-part response: REASONING + FINAL ANSWER
    - Clear examples showing expected format
    - Instructions for handling insufficient evidence
 
 2. **Increased max_tokens** from 256 → 1024
+
    - Accommodate longer reasoning text
    - Allow space for both reasoning and answer
 
 3. **Added parsing logic** to extract FINAL ANSWER
+
    - Split response on "FINAL ANSWER:" delimiter
    - Return only answer to agent (short for UI)
    - Save full response (with reasoning) to log file
@@ -97,6 +108,7 @@ FINAL ANSWER: [Factoid answer]
    - Clear separation markers
 
 **Modified Files:**
+
 - **src/agent/llm_client.py** (~50 lines modified)
   - Updated `synthesize_answer_hf()` - CoT prompt, max_tokens=1024, parsing
   - Updated `synthesize_answer_groq()` - Same changes
@@ -113,17 +125,20 @@ FINAL ANSWER: [Factoid answer]
 **Solution:** Separated console output (status workflow) from detailed logs (file-based).
 
 **Console Output (Compressed):**
+
 - Status updates: `[plan] ✓ 660 chars`, `[execute] 1 tool(s) selected`, `[answer] ✓ 3`
 - Progress indicators: `[1/1] Processing a1e91b78`, `[1/20]` for batch
 - Success/failure: `✓` for success, `✗` for failure
 - File exports: `Context saved to: log/llm_context_*.txt`
 
 **Log Files (log/ folder):**
+
 - `llm_context_TIMESTAMP.txt` - Full LLM prompts, evidence, answers
 - `{video_id}_transcript.txt` - Raw transcripts from YouTube/Whisper
 - Purpose: Post-run analysis, context preservation, debugging
 
 **Modified Files:**
+
 - **app.py** (~4 lines) - Suppress httpx, urllib3, huggingface_hub, gradio logs to WARNING
 - **src/agent/graph.py** (~50 lines → ~15 lines) - Compressed node logs, removed separators
 - **src/agent/llm_client.py** (~20 lines) - Save LLM context to log/ folder
@@ -132,6 +147,7 @@ FINAL ANSWER: [Factoid answer]
 - **.gitignore** (+3 lines) - Exclude log/ folder
 
 **Global Rule Update (~/.claude/CLAUDE.md):**
+
 - Added `log/` to standard project structure (archive/, input/, output/, log/, test/, dev/)
 - Removed "logs/" from prohibited folders list
 - Updated folder purposes table with log/ entry
@@ -139,6 +155,7 @@ FINAL ANSWER: [Factoid answer]
 **Result:** 16k tokens → ~6.7k tokens (58% reduction)
 
 **Standard Structure:**
+
 ```
 ##_ProjectName/
 ├── archive/    # Previous solutions, references
@@ -158,6 +175,7 @@ FINAL ANSWER: [Factoid answer]
 **Finding:** Models WITHOUT `:provider` suffix work via HF auto-routing, but this is unreliable.
 
 **Test Result:**
+
 ```python
 # Without provider - WORKS but uses HF default routing
 HF_MODEL = "Qwen/Qwen2.5-72B-Instruct"  # ✅ Works, but...
@@ -169,13 +187,13 @@ HF_MODEL = "meta-llama/Llama-3.3-70B-Instruct:scaleway"  # ✅ Reliable
 
 **Why Auto-Routing is Bad Practice:**
 
-| Issue | Impact |
-|-------|--------|
-| **Unpredictable performance** | Provider changes between runs (fast Cerebras → slow Together) |
-| **Inconsistent latency** | 2s one run, 20s next run (different provider selected) |
-| **No cost control** | Can't choose cheaper providers (Cerebras/Scaleway vs expensive) |
-| **Debugging nightmare** | Can't reproduce issues when provider is unknown |
-| **Silent failures** | Provider might be down, HF retries with different one |
+| Issue                         | Impact                                                          |
+| ----------------------------- | --------------------------------------------------------------- |
+| **Unpredictable performance** | Provider changes between runs (fast Cerebras → slow Together)   |
+| **Inconsistent latency**      | 2s one run, 20s next run (different provider selected)          |
+| **No cost control**           | Can't choose cheaper providers (Cerebras/Scaleway vs expensive) |
+| **Debugging nightmare**       | Can't reproduce issues when provider is unknown                 |
+| **Silent failures**           | Provider might be down, HF retries with different one           |
 
 **Best Practice: ALWAYS specify provider**
 
@@ -190,6 +208,7 @@ HF_MODEL = "meta-llama/Llama-3.1-70B-Instruct:novita"
 ```
 
 **Available Providers for Text Models:**
+
 - `:scaleway` - Fast, reliable (recommended for Llama)
 - `:cerebras` - Very fast (recommended for Qwen)
 - `:novita` - Fast, reputable
@@ -203,11 +222,13 @@ HF_MODEL = "meta-llama/Llama-3.1-70B-Instruct:novita"
 ## [2026-01-13] [Stage 1: YouTube Support] [IN PROGRESS] LLM Synthesis Model Iteration
 
 **Model Changes:**
+
 1. Qwen 2.5 72B (no provider) → Failed synthesis ("Unable to answer")
 2. Llama 3.3 70B (Scaleway) → Failed synthesis
 3. **Current:** openai/gpt-oss-120b (Scaleway) - Testing
 
 **openai/gpt-oss-120b:**
+
 - OpenAI's 120B parameter open source model
 - Strong reasoning capability
 - Optimized for function calling and tool use
@@ -390,7 +411,7 @@ submission_data = {
 4. **Our additions are OPTIONAL** - debug/features we added
 5. **Original template is 8777 bytes** - ours is 32722 bytes (4x larger)
 
-**Reference:** `_template_original/app.py` for original structure
+**Reference:** `project_template_original/app.py` for original structure
 
 ---
 
@@ -402,7 +423,7 @@ submission_data = {
 
 1. Cloned original template to `/Users/mangubee/Downloads/Final_Assignment_Template`
 2. Removed git-specific files (`.git/` folder, `.gitattributes`)
-3. Copied to project as `_template_original/` (static reference, no git)
+3. Copied to project as `project_template_original/` (static reference, no git)
 4. Cleaned up temporary clone from Downloads
 
 **Why Static Reference:**
@@ -422,18 +443,18 @@ submission_data = {
 
 ```bash
 # Compare file sizes
-ls -lh _template_original/app.py app.py
+ls -lh project_template_original/app.py app.py
 
 # See differences
-diff _template_original/app.py app.py
+diff project_template_original/app.py app.py
 
 # Count lines added
-wc -l app.py _template_original/app.py
+wc -l app.py project_template_original/app.py
 ```
 
 **Created Files:**
 
-- **\_template_original/** (NEW) - Static reference to original template (3 files)
+- **\project_template_original/** (NEW) - Static reference to original template (3 files)
 
 ---
 
@@ -462,7 +483,7 @@ wc -l app.py _template_original/app.py
 - Remote: `mangubee/agentbee` (renamed on HuggingFace)
 - Sync: ✅ All changes pushed
 - Git: All commits synced
-- Template: `_template_original/` added for comparison
+- Template: `project_template_original/` added for comparison
 
 ---
 

PLAN.md

@@ -13,48 +13,50 @@ Fix remaining 6 system errors to unlock questions, then address LLM quality issu
 
 ### ✅ Working (2/20 correct - 10%)
 
-| # | Task | Status | Issue |
-|---|------|--------|-------|
-| 9 | Polish Ray actor | ✅ Correct | - |
-| 15 | Vietnamese specimens | ✅ Correct | - |
+| #   | Task                 | Status     | Issue |
+| --- | -------------------- | ---------- | ----- |
+| 9   | Polish Ray actor     | ✅ Correct | -     |
+| 15  | Vietnamese specimens | ✅ Correct | -     |
 
 ### ⚠️ System Errors (6/20 - Technical issues blocking)
 
-| # | Task | Error | Type | Priority |
-|---|------|-------|------|----------|
-| **3** | YouTube video (bird species) | Vision tool can't handle URLs | Technical | **HIGH** |
-| **5** | YouTube video (Teal'c) | Vision tool can't handle URLs | Technical | **HIGH** |
-| **6** | CSV table (commutativity) | LLM tries to load `table_data.csv` | LLM Quality | MED |
-| **10** | MP3 audio (pie recipe) | Unsupported file type | Technical | **MED** |
-| **12** | Python code execution | Unsupported file type | Technical | **LOW** |
-| **13** | MP3 audio (calculus) | Unsupported file type | Technical | **MED** |
+| #      | Task                         | Error                              | Type        | Priority |
+| ------ | ---------------------------- | ---------------------------------- | ----------- | -------- |
+| **3**  | YouTube video (bird species) | Vision tool can't handle URLs      | Technical   | **HIGH** |
+| **5**  | YouTube video (Teal'c)       | Vision tool can't handle URLs      | Technical   | **HIGH** |
+| **6**  | CSV table (commutativity)    | LLM tries to load `table_data.csv` | LLM Quality | MED      |
+| **10** | MP3 audio (pie recipe)       | Unsupported file type              | Technical   | **MED**  |
+| **12** | Python code execution        | Unsupported file type              | Technical   | **LOW**  |
+| **13** | MP3 audio (calculus)         | Unsupported file type              | Technical   | **MED**  |
 
 ### ❌ LLM Quality Issues (12/20 - AI can't solve)
 
-| # | Task | Answer | Expected | Type |
-|---|------|--------|----------|------|
-| 1 | Calculator | "Unable to answer" | Right | Reasoning |
-| 2 | Wikipedia dinosaur | "Scott Hartman" | FunkMonk | Knowledge |
-| 4 | Mercedes Sosa albums | "Unable to answer" | 3 | Knowledge |
-| 7 | Chess position | "Unable to answer" | Rd5 | Vision+Reasoning |
-| 8 | Grocery list (botany) | Wrong (includes fruits) | 5 items | Knowledge |
-| 11 | Equine veterinarian | "Unable to answer" | Louvrier | Knowledge |
-| 14 | NASA award | "Unable to answer" | 80GSFC21M0002 | Knowledge |
-| 16 | Yankee at-bats | "Unable to answer" | 519 | Knowledge |
-| 17 | Pitcher numbers | "Unable to answer" | Yoshida, Uehara | Knowledge |
-| 18 | Olympics athletes | "Unable to answer" | CUB | Knowledge |
-| 19 | Malko Competition | "Unable to answer" | Claus | Knowledge |
-| 20 | Excel sales | "12096.00" | "89706.00" | Calculation |
+| #   | Task                  | Answer                  | Expected        | Type             |
+| --- | --------------------- | ----------------------- | --------------- | ---------------- |
+| 1   | Calculator            | "Unable to answer"      | Right           | Reasoning        |
+| 2   | Wikipedia dinosaur    | "Scott Hartman"         | FunkMonk        | Knowledge        |
+| 4   | Mercedes Sosa albums  | "Unable to answer"      | 3               | Knowledge        |
+| 7   | Chess position        | "Unable to answer"      | Rd5             | Vision+Reasoning |
+| 8   | Grocery list (botany) | Wrong (includes fruits) | 5 items         | Knowledge        |
+| 11  | Equine veterinarian   | "Unable to answer"      | Louvrier        | Knowledge        |
+| 14  | NASA award            | "Unable to answer"      | 80GSFC21M0002   | Knowledge        |
+| 16  | Yankee at-bats        | "Unable to answer"      | 519             | Knowledge        |
+| 17  | Pitcher numbers       | "Unable to answer"      | Yoshida, Uehara | Knowledge        |
+| 18  | Olympics athletes     | "Unable to answer"      | CUB             | Knowledge        |
+| 19  | Malko Competition     | "Unable to answer"      | Claus           | Knowledge        |
+| 20  | Excel sales           | "12096.00"              | "89706.00"      | Calculation      |
 
 ## Strategy
 
 **Priority 1: Fix System Errors** (unlock 6 questions)
+
 - YouTube videos (2 questions) - HIGH impact
 - MP3 audio (2 questions) - Medium impact
 - Python execution (1 question) - Low impact
 - CSV table - LLM issue, not technical
 
 **Priority 2: Improve LLM Quality** (address "Unable to answer" cases)
+
 - Better prompting
 - Tool selection improvements
 - Reasoning enhancements
@@ -66,6 +68,7 @@ Fix remaining 6 system errors to unlock questions, then address LLM quality issu
 **Goal:** Fix questions #3 and #5 (YouTube videos)
 
 **Root Cause:** Vision tool tries to process YouTube URLs directly, but:
+
 - YouTube videos need to be downloaded first
 - Vision tool expects image files, not video URLs
 - Need to extract frames or use transcript
@@ -75,6 +78,7 @@ Fix remaining 6 system errors to unlock questions, then address LLM quality issu
 #### Option A: YouTube Transcript (Recommended)
 
 **Implementation:**
+
 ```python
 # NEW: src/tools/youtube.py
 import youtube_transcript_api
@@ -90,12 +94,14 @@ def get_youtube_transcript(video_url: str) -> str:
 ```
 
 **Pros:**
+
 - ✅ Works with current LLM (text-based)
 - ✅ Simple API (youtube-transcript-api library)
 - ✅ Fast, no video download needed
 - ✅ Solves both #3 and #5
 
 **Cons:**
+
 - ❌ Won't work for visual-only questions (but our questions are about content)
 - ❌ Might not capture visual details
 
@@ -104,6 +110,7 @@ def get_youtube_transcript(video_url: str) -> str:
 #### Option B: Video Frame Extraction
 
 **Implementation:**
+
 - Download video (yt-dlp)
 - Extract key frames (OpenCV)
 - Pass frames to vision tool
@@ -156,6 +163,7 @@ Target Task ID: a1e91b78-d3d8-4675-bb8d-62741b4b68a6
 **Solution:** Add audio transcription tool
 
 **Implementation:**
+
 ```python
 # NEW: src/tools/audio.py
 import whisper
@@ -168,6 +176,7 @@ def transcribe_audio(file_path: str) -> str:
 ```
 
 **Alternative:** HuggingFace audio models (free)
+
 - `openai/whisper-base`
 - Use via Inference API
 
@@ -191,6 +200,7 @@ def transcribe_audio(file_path: str) -> str:
 **Security Concern:** ⚠️ **DANGEROUS** - executing arbitrary Python code
 
 **Options:**
+
 1. **Restricted execution** - Only allow specific operations
 2. **Docker container** - Isolate execution
 3. **Skip for now** - Defer due to security concerns
@@ -210,6 +220,7 @@ def transcribe_audio(file_path: str) -> str:
 **Solution:** This is NOT technical - LLM needs better prompts or tool selection
 
 **Approaches:**
+
 1. Improve system prompt to recognize data in questions
 2. Add hint in question preprocessing
 3. Special handling for markdown tables in questions
@@ -231,12 +242,14 @@ def transcribe_audio(file_path: str) -> str:
 **Vision+Reasoning (1 question):** #7
 
 **Approaches:**
+
 1. **Better prompts** - Emphasize exact answer format
 2. **Tool selection hints** - Guide LLM to use appropriate tools
 3. **Few-shot examples** - Show LLM expected answer format
 4. **Chain-of-thought** - Encourage step-by-step reasoning
 
 **Implementation:**
+
 - Update `synthesize_answer()` prompt
 - Add answer format examples to system prompt
 - Improve tool descriptions for better selection
@@ -246,28 +259,33 @@ def transcribe_audio(file_path: str) -> str:
 ## Success Criteria
 
 ### Phase 1: YouTube Support
+
 - [ ] YouTube transcript tool implemented
 - [ ] Question #3 answered correctly (bird species = "3")
 - [ ] Question #5 answered correctly (Teal'c quote = "Extremely")
 - [ ] **Score: 10% → 40% (4/20)** ✅ TARGET REACHED
 
 ### Phase 2: MP3 Support
+
 - [ ] Audio transcription tool implemented
 - [ ] Question #10 answered correctly (pie ingredients)
 - [ ] Question #13 answered correctly (page numbers)
 - [ ] **Score: 40% → 50% (10/20)** ✅ EXCEEDS TARGET
 
 ### Phase 3: Python Execution
+
 - [ ] Code execution tool implemented (sandboxed)
 - [ ] Question #12 answered correctly (output = "0")
 - [ ] **Score: 50% → 55% (11/20)**
 
 ### Phase 4: CSV Table
+
 - [ ] LLM recognizes data in question
 - [ ] Question #6 answered correctly ("b, e")
 - [ ] **Score: 55% → 60% (12/20)**
 
 ### Phase 5: LLM Quality
+
 - [ ] "Unable to answer" reduced by 50%
 - [ ] At least 3 more knowledge questions correct
 - [ ] **Score: 60% → 75%+ (15/20)**
@@ -275,18 +293,21 @@ def transcribe_audio(file_path: str) -> str:
 ## Files to Modify
 
 ### Phase 1: YouTube
+
 1. **requirements.txt** - Add `youtube-transcript-api`
 2. **src/tools/youtube.py** (NEW) - YouTube transcript extraction
-3. **src/tools/__init__.py** - Register youtube_transcript tool
+3. **src/tools/**init**.py** - Register youtube_transcript tool
 
 ### Phase 2: MP3 Audio
+
 1. **requirements.txt** - Add `openai-whisper` or HF audio
 2. **src/tools/audio.py** (NEW) - Audio transcription
-3. **src/tools/__init__.py** - Register transcribe_audio tool
+3. **src/tools/**init**.py** - Register transcribe_audio tool
 
 ### Phase 3-5: LLM Quality
+
 1. **src/agent/graph.py** - Update prompts
-2. **src/tools/__init__.py** - Improve tool descriptions
+2. **src/tools/**init**.py** - Improve tool descriptions
 
 ## Removed (Not Relevant)
 
@@ -301,14 +322,17 @@ def transcribe_audio(file_path: str) -> str:
 ## Decision Gates
 
 **Gate 1 (YouTube):** Does transcript solve both video questions?
+
 - **YES:** 40% score, proceed to Phase 2
 - **NO:** Try frame extraction approach
 
 **Gate 2 (MP3):** Does transcription solve both audio questions?
+
 - **YES:** 50% score, proceed to Phase 3
 - **NO:** Try different audio model
 
 **Gate 3 (Target):** Have we reached 30% (6/20)?
+
 - **YES:** ✅ SUCCESS - course target met
 - **NO:** Continue to Phase 4-5
 
@@ -330,9 +354,11 @@ def transcribe_audio(file_path: str) -> str:
 ## Backup Options
 
 If YouTube transcript doesn't work:
+
 - **Plan B:** Extract video frames, analyze with vision tool
 - **Plan C:** Skip video questions, focus on other fixes
 
 If MP3 transcription doesn't work:
+
 - **Plan B:** Use HuggingFace audio models
 - **Plan C:** Skip audio questions, focus on LLM quality