botrun-flow-lang 5.12.264__tar.gz → 6.2.21__tar.gz

{botrun_flow_lang-5.12.264 → botrun_flow_lang-6.2.21}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [6.1.261]
+- 優化 MCP 工具 docstring，避免 LLM 混淆 URL 有效期限：
+  - `create_html_page`：明確標示為 PERMANENT URL that never expires
+  - `generate_tmp_public_url`：改為 temporary URL that may be deleted periodically
+
+## [6.1.72]
+- web_search 如果沒有使用 openrouter 的 api 時，回傳的 usage_metadata model 要加入 perplexity/ 前綴
+
+## [6.1.71]
+- 幾個 mcp 工具加入回傳 llm usage_metadata
+  - web_search、chat_with_pdf、chat_with_imgs、generate_image
+
 ## [5.12.264]
 - 修正 botrun_flow_lang/langgraph_agents/agents/langgraph_react_agent.py
   - from langchain.tools import StructuredTool 改成 from langchain_core.tools import StructuredTool

{botrun_flow_lang-5.12.264 → botrun_flow_lang-6.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: botrun-flow-lang
-Version: 5.12.264
+Version: 6.2.21
 Summary: A flow language for botrun
 Author-email: sebastian-hsu <sebastian.hsu@gmail.com>
 License: MIT
@@ -27,12 +27,12 @@ Requires-Dist: google-cloud-storage<3,>=2.18
 Requires-Dist: google-genai>=1.28.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: langchain-anthropic>=0.3.10
-Requires-Dist: langchain-aws>=0.2.17
+Requires-Dist: langchain-aws>=1.0.0
 Requires-Dist: langchain-community>=0.3.27
-Requires-Dist: langchain-core>=0.3.72
+Requires-Dist: langchain-core>=1.1.2
 Requires-Dist: langchain-google-community>=2.0.3
-Requires-Dist: langchain-google-genai>=2.0.9
-Requires-Dist: langchain-google-vertexai<3.0.0,>=2.1.2
+Requires-Dist: langchain-google-genai>=4.0.0
+Requires-Dist: langchain-google-vertexai<4.0.0,>=3.2.0
 Requires-Dist: langchain-mcp-adapters>=0.1.7
 Requires-Dist: langchain-openai>=0.3.28
 Requires-Dist: langchain>=0.3.27
@@ -41,7 +41,7 @@ Requires-Dist: langgraph-supervisor>=0.0.20
 Requires-Dist: langgraph>=0.6.3
 Requires-Dist: line-bot-sdk>=3.17.1
 Requires-Dist: mcp<1.11.0,>=1.10.1
-Requires-Dist: numpy<2,>=1
+Requires-Dist: numpy>=1.24.0
 Requires-Dist: openai>=1.99.1
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: pdfminer-six==20250506

{botrun_flow_lang-5.12.264 → botrun_flow_lang-6.2.21}/botrun_flow_lang/api/langgraph_api.py

@@ -113,12 +113,17 @@ class GraphSchemaRequest(BaseModel):
     graph_name: str
 
 
-PERPLEXITY_SEARCH_AGENT = "perplexity_search_agent"
+# 從常數檔案匯入，避免外部模組為了取得常數而觸發重型 import
+from botrun_flow_lang.api.langgraph_constants import (
+    LANGGRAPH_REACT_AGENT,
+    GOV_SUBSIDY_AGENT,
+    PERPLEXITY_SEARCH_AGENT,
+)
+
+# 僅在此檔案內部使用的常數
 CUSTOM_WEB_RESEARCH_AGENT = "custom_web_research_agent"
-LANGGRAPH_REACT_AGENT = "langgraph_react_agent"
 DEEP_RESEARCH_AGENT = "deep_research_agent"
 # GOV_RESEARCHER_AGENT = "gov_researcher_agent"
-GOV_SUBSIDY_AGENT = "gov_subsidy_agent"
 GEMINI_SUBSIDY_AGENT = "gemini_subsidy_agent"
 
 

botrun_flow_lang-6.2.21/botrun_flow_lang/api/langgraph_constants.py

@@ -0,0 +1,11 @@
+"""
+LangGraph 常數定義
+
+此檔案只包含常數定義，不包含任何會觸發重型 SDK 載入的 import。
+這樣可以讓其他模組在只需要常數時，不會觸發 langchain_google_vertexai 等重型套件的載入。
+"""
+
+# Graph 名稱常數
+LANGGRAPH_REACT_AGENT = "langgraph_react_agent"
+GOV_SUBSIDY_AGENT = "gov_subsidy_agent"
+PERPLEXITY_SEARCH_AGENT = "perplexity_search_agent"

{botrun_flow_lang-5.12.264 → botrun_flow_lang-6.2.21}/botrun_flow_lang/langgraph_agents/agents/langgraph_react_agent.py

@@ -86,8 +86,9 @@ from langchain_mcp_adapters.client import MultiServerMCPClient
 # ========
 # for Vertex AI
 from google.oauth2 import service_account
-from langchain_google_vertexai import ChatVertexAI
-from langchain_google_vertexai.model_garden import ChatAnthropicVertex
+# 重型 import 改為延遲載入，避免啟動時載入 google-cloud-aiplatform（約 26 秒）
+# ChatVertexAI 已遷移至 ChatGoogleGenerativeAI(vertexai=True)
+# ChatAnthropicVertex 在需要時才 import（見 get_react_agent_model 函數內）
 
 load_dotenv()
 
@@ -234,8 +235,10 @@ def get_react_agent_model(model_name: str = ""):
             # 判斷模型類型並創建相應實例
             if vertex_model_name.startswith("gemini-"):
                 # Gemini 系列：gemini-2.5-pro, gemini-2.5-flash, gemini-pro
-                model = ChatVertexAI(
+                # 使用 ChatGoogleGenerativeAI + vertexai=True，避免載入重型的 langchain_google_vertexai
+                model = ChatGoogleGenerativeAI(
                     model=vertex_model_name,
+                    vertexai=True,
                     location=vertex_region,
                     project=vertex_project,
                     credentials=credentials,
@@ -243,11 +246,13 @@ def get_react_agent_model(model_name: str = ""):
                     max_tokens=GEMINI_MAX_TOKENS,
                 )
                 logger.info(
-                    f"model ChatVertexAI {vertex_model_name} @ {vertex_region} (project: {vertex_project})"
+                    f"model ChatGoogleGenerativeAI(vertexai=True) {vertex_model_name} @ {vertex_region} (project: {vertex_project})"
                 )
 
             elif "claude" in vertex_model_name.lower() or vertex_model_name.startswith("maison/"):
                 # Anthropic Claude (model garden)
+                # 延遲載入 ChatAnthropicVertex，只有在需要時才觸發 langchain_google_vertexai
+                from langchain_google_vertexai.model_garden import ChatAnthropicVertex
                 model = ChatAnthropicVertex(
                     model=vertex_model_name,
                     location=vertex_region,
@@ -302,6 +307,8 @@ def get_react_agent_model(model_name: str = ""):
                 )
 
             # 初始化 ChatAnthropicVertex
+            # 延遲載入，只有在需要時才觸發 langchain_google_vertexai
+            from langchain_google_vertexai.model_garden import ChatAnthropicVertex
             model = ChatAnthropicVertex(
                 project=vertex_project,
                 model=vertex_model,

{botrun_flow_lang-5.12.264 → botrun_flow_lang-6.2.21}/botrun_flow_lang/langgraph_agents/agents/util/img_util.py

@@ -4,8 +4,11 @@ import httpx
 import os
 import imghdr
 from pathlib import Path
+from typing import Dict, Any, List, Tuple
 from dotenv import load_dotenv
 
+from botrun_flow_lang.langgraph_agents.agents.util.usage_metadata import UsageMetadata
+
 load_dotenv()
 
 
@@ -50,7 +53,7 @@ def get_img_content_type(file_path: str | Path) -> str:
 
 def analyze_imgs_with_claude(
     img_urls: list[str], user_input: str, model_name: str = "claude-sonnet-4-5-20250929"
-) -> str:
+) -> Tuple[str, UsageMetadata]:
     """
     Analyze multiple images using Claude Vision API
 
@@ -60,7 +63,7 @@ def analyze_imgs_with_claude(
         model_name: Claude model name to use
 
     Returns:
-        str: Claude's analysis of the image content(s) based on the query
+        Tuple[str, UsageMetadata]: Claude's analysis and usage metadata
 
     Raises:
         ValueError: If image URLs are invalid or model parameters are incorrect
@@ -120,10 +123,20 @@ def analyze_imgs_with_claude(
                 ],
             )
 
+            # Extract usage metadata
+            usage = UsageMetadata(
+                prompt_tokens=message.usage.input_tokens,
+                completion_tokens=message.usage.output_tokens,
+                total_tokens=message.usage.input_tokens + message.usage.output_tokens,
+                cache_creation_input_tokens=getattr(message.usage, 'cache_creation_input_tokens', 0) or 0,
+                cache_read_input_tokens=getattr(message.usage, 'cache_read_input_tokens', 0) or 0,
+                model=model_name,
+            )
+
             print(
                 f"analyze_imgs_with_claude============> input_token: {message.usage.input_tokens} output_token: {message.usage.output_tokens}",
             )
-            return message.content[0].text
+            return message.content[0].text, usage
         except anthropic.APIError as e:
             import traceback
 
@@ -144,7 +157,7 @@ def analyze_imgs_with_gemini(
     img_urls: list[str],
     user_input: str,
     model_name: str = "gemini-2.5-flash",
-) -> str:
+) -> Tuple[str, UsageMetadata]:
     """
     Analyze multiple images using Gemini Vision API
 
@@ -154,7 +167,7 @@ def analyze_imgs_with_gemini(
         model_name: Gemini model name to use
 
     Returns:
-        str: Gemini's analysis of the image content(s) based on the query
+        Tuple[str, UsageMetadata]: Gemini's analysis and usage metadata
 
     Raises:
         ValueError: If image URLs are invalid or model parameters are incorrect
@@ -216,10 +229,23 @@ def analyze_imgs_with_gemini(
             contents=contents,
         )
 
-        print(
-            f"analyze_imgs_with_gemini============> input_token: {response.usage_metadata.prompt_token_count} output_token: {response.usage_metadata.candidates_token_count}"
-        )
-        return response.text
+        # Extract usage metadata
+        usage = UsageMetadata(model=model_name)
+        if hasattr(response, "usage_metadata"):
+            usage_meta = response.usage_metadata
+            usage = UsageMetadata(
+                prompt_tokens=getattr(usage_meta, 'prompt_token_count', 0) or 0,
+                completion_tokens=getattr(usage_meta, 'candidates_token_count', 0) or 0,
+                total_tokens=getattr(usage_meta, 'total_token_count', 0) or 0,
+                cache_creation_input_tokens=0,
+                cache_read_input_tokens=getattr(usage_meta, 'cached_content_token_count', 0) or 0,
+                model=model_name,
+            )
+            print(
+                f"analyze_imgs_with_gemini============> input_token: {usage_meta.prompt_token_count} output_token: {usage_meta.candidates_token_count}"
+            )
+
+        return response.text, usage
 
     except httpx.RequestError as e:
         import traceback
@@ -233,7 +259,7 @@ def analyze_imgs_with_gemini(
         raise Exception(f"Error analyzing image(s) with Gemini {model_name}: {str(e)}")
 
 
-def analyze_imgs(img_urls: list[str], user_input: str) -> str:
+def analyze_imgs(img_urls: list[str], user_input: str) -> Dict[str, Any]:
     """
     Analyze multiple images using configured AI models.
 
@@ -248,8 +274,13 @@ def analyze_imgs(img_urls: list[str], user_input: str) -> str:
         user_input: User's query about the image content(s)
 
     Returns:
-        str: AI analysis of the image content(s) based on the query
+        Dict[str, Any]: {
+            "result": str,  # AI analysis result
+            "usage_metadata": List[Dict]  # Token usage for each LLM call
+        }
     """
+    usage_list: List[UsageMetadata] = []
+
     # Get models from environment variable, split by comma if multiple models
     models_str = os.getenv("IMG_ANALYZER_MODEL", "gemini-2.5-flash")
     print(f"[analyze_imgs] 分析IMG使用模型: {models_str}")
@@ -267,12 +298,20 @@ def analyze_imgs(img_urls: list[str], user_input: str) -> str:
         try:
             if model.startswith("gemini-"):
                 print(f"[analyze_imgs] 嘗試使用 Gemini 模型: {model}")
-                result = analyze_imgs_with_gemini(img_urls, user_input, model)
-                return result
+                result, usage = analyze_imgs_with_gemini(img_urls, user_input, model)
+                usage_list.append(usage)
+                return {
+                    "result": result,
+                    "usage_metadata": [u.to_dict() for u in usage_list],
+                }
             elif model.startswith("claude-"):
                 print(f"[analyze_imgs] 嘗試使用 Claude 模型: {model}")
-                result = analyze_imgs_with_claude(img_urls, user_input, model)
-                return result
+                result, usage = analyze_imgs_with_claude(img_urls, user_input, model)
+                usage_list.append(usage)
+                return {
+                    "result": result,
+                    "usage_metadata": [u.to_dict() for u in usage_list],
+                }
             else:
                 print(f"[analyze_imgs] 不支持的模型格式: {model}, 跳過")
                 errors.append(f"不支持的模型格式: {model}")
@@ -291,4 +330,7 @@ def analyze_imgs(img_urls: list[str], user_input: str) -> str:
 
     # If we've tried all models and none succeeded, return all errors
     error_summary = "\n".join(errors)
-    return f"錯誤: 所有配置的模型都失敗了。詳細錯誤：\n{error_summary}"
+    return {
+        "result": f"錯誤: 所有配置的模型都失敗了。詳細錯誤：\n{error_summary}",
+        "usage_metadata": [u.to_dict() for u in usage_list],
+    }

{botrun_flow_lang-5.12.264 → botrun_flow_lang-6.2.21}/botrun_flow_lang/langgraph_agents/agents/util/pdf_analyzer.py

@@ -11,11 +11,13 @@ import asyncio
 import base64
 import httpx
 import os
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Tuple
 
 from dotenv import load_dotenv
 from google.oauth2 import service_account
 
+from botrun_flow_lang.langgraph_agents.agents.util.usage_metadata import UsageMetadata
+
 load_dotenv()
 
 # 檔案大小閾值（MB）
@@ -30,16 +32,17 @@ MAX_CONCURRENT_CHUNKS = 5
 
 def analyze_pdf_with_claude(
     pdf_data: str, user_input: str, model_name: str = "claude-sonnet-4-5-20250929"
-):
+) -> Tuple[str, UsageMetadata]:
     """
     Analyze a PDF file using Claude API
 
     Args:
         pdf_data: Base64-encoded PDF data
         user_input: User's query about the PDF content
+        model_name: Claude model name to use
 
     Returns:
-        str: Claude's analysis of the PDF content based on the query
+        Tuple[str, UsageMetadata]: Claude's analysis and usage metadata
     """
     # Initialize Anthropic client
     client = anthropic.Anthropic()
@@ -66,15 +69,25 @@ def analyze_pdf_with_claude(
         ],
     )
 
+    # Extract usage metadata
+    usage = UsageMetadata(
+        prompt_tokens=message.usage.input_tokens,
+        completion_tokens=message.usage.output_tokens,
+        total_tokens=message.usage.input_tokens + message.usage.output_tokens,
+        cache_creation_input_tokens=getattr(message.usage, 'cache_creation_input_tokens', 0) or 0,
+        cache_read_input_tokens=getattr(message.usage, 'cache_read_input_tokens', 0) or 0,
+        model=model_name,
+    )
+
     print(
         f"analyze_pdf_with_claude============> input_token: {message.usage.input_tokens} output_token: {message.usage.output_tokens}",
     )
-    return message.content[0].text
+    return message.content[0].text, usage
 
 
 def analyze_pdf_with_gemini(
     pdf_data: str, user_input: str, model_name: str = "gemini-2.5-flash", pdf_url: str = ""
-):
+) -> Tuple[str, UsageMetadata]:
     """
     Analyze a PDF file using Gemini API
 
@@ -82,9 +95,10 @@ def analyze_pdf_with_gemini(
         pdf_data: Base64-encoded PDF data
         user_input: User's query about the PDF content
         model_name: Gemini model name to use
+        pdf_url: Original PDF URL for logging
 
     Returns:
-        str: Gemini's analysis of the PDF content based on the query
+        Tuple[str, UsageMetadata]: Gemini's analysis and usage metadata
     """
     # 放到要用的時候才 import，不然loading 會花時間
     from google import genai
@@ -112,14 +126,25 @@ def analyze_pdf_with_gemini(
             ),
         ],
     )
-    # Log token usage if available
+
+    # Extract usage metadata
+    usage = UsageMetadata(model=model_name)
     if hasattr(response, "usage_metadata"):
+        usage_meta = response.usage_metadata
+        usage = UsageMetadata(
+            prompt_tokens=getattr(usage_meta, 'prompt_token_count', 0) or 0,
+            completion_tokens=getattr(usage_meta, 'candidates_token_count', 0) or 0,
+            total_tokens=getattr(usage_meta, 'total_token_count', 0) or 0,
+            cache_creation_input_tokens=0,
+            cache_read_input_tokens=getattr(usage_meta, 'cached_content_token_count', 0) or 0,
+            model=model_name,
+        )
         print(
-            f"analyze_pdf_with_gemini============> input_token: {response.usage_metadata.prompt_token_count} output_token: {response.usage_metadata.candidates_token_count}",
+            f"analyze_pdf_with_gemini============> input_token: {usage_meta.prompt_token_count} output_token: {usage_meta.candidates_token_count}",
         )
 
     print(f"{pdf_url} success")
-    return response.text
+    return response.text, usage
 
 
 def _analyze_single_chunk(
@@ -135,7 +160,7 @@ def _analyze_single_chunk(
         model_name: 使用的模型名稱
 
     Returns:
-        Dict: {"page_range": str, "answer": str, "relevant": bool, "error": str|None}
+        Dict: {"page_range": str, "answer": str, "relevant": bool, "error": str|None, "usage": UsageMetadata}
     """
     # 構建切片專用的 prompt
     chunk_prompt = f"""你正在閱讀一份大型 PDF 文件的其中一部分（{page_range}）。
@@ -149,15 +174,16 @@ def _analyze_single_chunk(
 
     try:
         if model_name.startswith("gemini-"):
-            answer = analyze_pdf_with_gemini(chunk_data, chunk_prompt, model_name)
+            answer, usage = analyze_pdf_with_gemini(chunk_data, chunk_prompt, model_name)
         elif model_name.startswith("claude-"):
-            answer = analyze_pdf_with_claude(chunk_data, chunk_prompt, model_name)
+            answer, usage = analyze_pdf_with_claude(chunk_data, chunk_prompt, model_name)
         else:
             return {
                 "page_range": page_range,
                 "answer": "",
                 "relevant": False,
                 "error": f"Unknown model type: {model_name}",
+                "usage": UsageMetadata(),
             }
 
         # 判斷是否相關
@@ -168,6 +194,7 @@ def _analyze_single_chunk(
             "answer": answer if is_relevant else "",
             "relevant": is_relevant,
             "error": None,
+            "usage": usage,
         }
 
     except Exception as e:
@@ -179,12 +206,13 @@ def _analyze_single_chunk(
             "answer": "",
             "relevant": False,
             "error": str(e),
+            "usage": UsageMetadata(model=model_name),
         }
 
 
 async def analyze_pdf_chunks_parallel(
     chunks: List[tuple], user_input: str, model_name: str, max_concurrent: int = 5
-) -> List[Dict[str, Any]]:
+) -> Tuple[List[Dict[str, Any]], List[UsageMetadata]]:
     """
     平行問答多個 PDF 切片
 
@@ -195,7 +223,7 @@ async def analyze_pdf_chunks_parallel(
         max_concurrent: 最大平行數量
 
     Returns:
-        List[Dict]: 每個切片的回答結果
+        Tuple[List[Dict], List[UsageMetadata]]: 每個切片的回答結果和每次呼叫的 usage list
     """
     semaphore = asyncio.Semaphore(max_concurrent)
 
@@ -224,8 +252,9 @@ async def analyze_pdf_chunks_parallel(
     # 平行執行
     results = await asyncio.gather(*tasks, return_exceptions=True)
 
-    # 處理例外
+    # 處理例外並收集 usage list
     processed_results = []
+    usage_list = []
     for i, result in enumerate(results):
         if isinstance(result, Exception):
             processed_results.append(
@@ -234,19 +263,24 @@ async def analyze_pdf_chunks_parallel(
                     "answer": "",
                     "relevant": False,
                     "error": str(result),
+                    "usage": UsageMetadata(model=model_name),
                 }
             )
+            usage_list.append(UsageMetadata(model=model_name))
         else:
             processed_results.append(result)
+            # 收集 usage
+            if "usage" in result and isinstance(result["usage"], UsageMetadata):
+                usage_list.append(result["usage"])
 
-    return processed_results
+    return processed_results, usage_list
 
 
 def merge_chunk_results(
     chunk_results: List[Dict[str, Any]],
     user_input: str,
     model_name: str = "gemini-2.5-flash",
-) -> str:
+) -> Tuple[str, UsageMetadata]:
     """
     使用 LLM 統整多個切片的回答
 
@@ -256,7 +290,7 @@ def merge_chunk_results(
         model_name: 統整使用的模型名稱
 
     Returns:
-        str: 統整後的回答
+        Tuple[str, UsageMetadata]: 統整後的回答和 usage metadata
     """
     # 過濾出相關的回答
     relevant_results = [r for r in chunk_results if r.get("relevant", False)]
@@ -266,12 +300,12 @@ def merge_chunk_results(
         error_results = [r for r in chunk_results if r.get("error")]
         if error_results:
             error_msgs = [f"{r['page_range']}: {r['error']}" for r in error_results]
-            return f"分析 PDF 時發生錯誤：\n" + "\n".join(error_msgs)
-        return "在 PDF 文件中未找到與您問題相關的內容。"
+            return f"分析 PDF 時發生錯誤：\n" + "\n".join(error_msgs), UsageMetadata(model=model_name)
+        return "在 PDF 文件中未找到與您問題相關的內容。", UsageMetadata(model=model_name)
 
-    # 只有一個相關結果，直接回傳
+    # 只有一個相關結果，直接回傳（不需要額外的 LLM 呼叫）
     if len(relevant_results) == 1:
-        return relevant_results[0]["answer"]
+        return relevant_results[0]["answer"], UsageMetadata(model=model_name)
 
     # 多個相關結果，需要統整
     combined_content = "\n\n".join(
@@ -310,22 +344,33 @@ def merge_chunk_results(
             contents=[merge_prompt],
         )
 
+        # Extract usage metadata
+        usage = UsageMetadata(model=model_name)
         if hasattr(response, "usage_metadata"):
+            usage_meta = response.usage_metadata
+            usage = UsageMetadata(
+                prompt_tokens=getattr(usage_meta, 'prompt_token_count', 0) or 0,
+                completion_tokens=getattr(usage_meta, 'candidates_token_count', 0) or 0,
+                total_tokens=getattr(usage_meta, 'total_token_count', 0) or 0,
+                cache_creation_input_tokens=0,
+                cache_read_input_tokens=getattr(usage_meta, 'cached_content_token_count', 0) or 0,
+                model=model_name,
+            )
             print(
-                f"merge_chunk_results============> input_token: {response.usage_metadata.prompt_token_count} output_token: {response.usage_metadata.candidates_token_count}",
+                f"merge_chunk_results============> input_token: {usage_meta.prompt_token_count} output_token: {usage_meta.candidates_token_count}",
             )
 
-        return response.text
+        return response.text, usage
 
     except Exception as e:
         import traceback
 
         traceback.print_exc()
         # 統整失敗，直接回傳合併的內容
-        return f"統整時發生錯誤，以下是各部分的回答：\n\n{combined_content}"
+        return f"統整時發生錯誤，以下是各部分的回答：\n\n{combined_content}", UsageMetadata(model=model_name)
 
 
-async def analyze_pdf_async(pdf_url: str, user_input: str) -> str:
+async def analyze_pdf_async(pdf_url: str, user_input: str) -> Dict[str, Any]:
     """
     非同步分析 PDF 檔案（智慧處理策略）
 
@@ -338,8 +383,13 @@ async def analyze_pdf_async(pdf_url: str, user_input: str) -> str:
         user_input: 使用者問題
 
     Returns:
-        str: 分析結果
+        Dict[str, Any]: {
+            "result": str,  # 分析結果
+            "usage_metadata": List[Dict]  # 每次 LLM 呼叫的 usage 資訊
+        }
     """
+    usage_list: List[UsageMetadata] = []
+
     try:
         # 1. 下載 PDF
         print(f"[analyze_pdf_async] 下載 PDF: {pdf_url}")
@@ -364,9 +414,19 @@ async def analyze_pdf_async(pdf_url: str, user_input: str) -> str:
             for model in models:
                 try:
                     if model.startswith("gemini-"):
-                        return analyze_pdf_with_gemini(pdf_data, user_input, model, pdf_url)
+                        result, usage = analyze_pdf_with_gemini(pdf_data, user_input, model, pdf_url)
+                        usage_list.append(usage)
+                        return {
+                            "result": result,
+                            "usage_metadata": [u.to_dict() for u in usage_list],
+                        }
                     elif model.startswith("claude-"):
-                        return analyze_pdf_with_claude(pdf_data, user_input, model)
+                        result, usage = analyze_pdf_with_claude(pdf_data, user_input, model)
+                        usage_list.append(usage)
+                        return {
+                            "result": result,
+                            "usage_metadata": [u.to_dict() for u in usage_list],
+                        }
                 except Exception as e:
                     import traceback
 
@@ -374,7 +434,10 @@ async def analyze_pdf_async(pdf_url: str, user_input: str) -> str:
                     last_error = str(e)
                     continue
 
-            return f"分析 PDF 時所有模型都失敗。最後錯誤: {last_error}"
+            return {
+                "result": f"分析 PDF 時所有模型都失敗。最後錯誤: {last_error}",
+                "usage_metadata": [u.to_dict() for u in usage_list],
+            }
 
         # 3. 大檔：壓縮 → 切割 → 平行問答 → 統整
         print(f"[analyze_pdf_async] 大檔模式 (>= {PDF_SIZE_THRESHOLD_MB}MB)")
@@ -427,9 +490,10 @@ async def analyze_pdf_async(pdf_url: str, user_input: str) -> str:
 
         # 3.3 平行問答
         print(f"[analyze_pdf_async] 開始平行問答 (最大並行: {MAX_CONCURRENT_CHUNKS})...")
-        chunk_results = await analyze_pdf_chunks_parallel(
+        chunk_results, chunk_usage_list = await analyze_pdf_chunks_parallel(
             chunks, user_input, primary_model, max_concurrent=MAX_CONCURRENT_CHUNKS
         )
+        usage_list.extend(chunk_usage_list)
 
         # 統計結果
         relevant_count = sum(1 for r in chunk_results if r.get("relevant", False))
@@ -441,19 +505,28 @@ async def analyze_pdf_async(pdf_url: str, user_input: str) -> str:
 
         # 3.4 統整結果
         print("[analyze_pdf_async] 統整結果...")
-        result = merge_chunk_results(chunk_results, user_input, primary_model)
+        result, merge_usage = merge_chunk_results(chunk_results, user_input, primary_model)
+        # 只有當 merge_usage 有實際 token 使用時才加入（避免加入空的 usage）
+        if merge_usage.prompt_tokens > 0 or merge_usage.completion_tokens > 0:
+            usage_list.append(merge_usage)
         print("[analyze_pdf_async] 完成")
 
-        return result
+        return {
+            "result": result,
+            "usage_metadata": [u.to_dict() for u in usage_list],
+        }
 
     except Exception as e:
         import traceback
 
         traceback.print_exc()
-        return f"分析 PDF {pdf_url} 時發生錯誤: {str(e)}"
+        return {
+            "result": f"分析 PDF {pdf_url} 時發生錯誤: {str(e)}",
+            "usage_metadata": [u.to_dict() for u in usage_list],
+        }
 
 
-def analyze_pdf(pdf_url: str, user_input: str) -> str:
+def analyze_pdf(pdf_url: str, user_input: str) -> Dict[str, Any]:
     """
     分析 PDF 檔案（同步包裝函數）
 
@@ -465,7 +538,10 @@ def analyze_pdf(pdf_url: str, user_input: str) -> str:
         user_input: 使用者問題
 
     Returns:
-        str: 分析結果
+        Dict[str, Any]: {
+            "result": str,  # 分析結果
+            "usage_metadata": List[Dict]  # 每次 LLM 呼叫的 usage 資訊
+        }
     """
     try:
         # 嘗試取得現有的事件迴圈