commit

app.py

@@ -8,11 +8,13 @@ import requests
 
 
 class ToolCallError(RuntimeError):
-    """Raised when a tool invocation fails even after retry."""
+    """リトライを行ってもツール呼び出しが失敗した場合に発生する例外。"""
 
 
 @dataclass
 class StorageHit:
+    """storage_search が返すヒット1件分の情報を保持する構造体。"""
+
     file_id: Optional[str]
     file_name: Optional[str]
     chunk_id: Optional[str]
@@ -24,9 +26,10 @@ VECTOR_STORE_ID_RE = re.compile(r"vs_[a-zA-Z0-9]{8,}")
 
 
 class OpenAIStorageClient:
-    """Minimal client for OpenAI Storage search/get endpoints."""
+    """OpenAI Storage の検索・取得APIを呼び出す最小限のクライアント。"""
 
     def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: float = 15.0):
+        """APIキーと各種設定を初期化する。"""
         if not api_key:
             raise ValueError("api_key is required")
         self.api_key = api_key
@@ -35,6 +38,7 @@ class OpenAIStorageClient:
         self.timeout = timeout
 
     def _post(self, path: str, payload: Dict) -> Dict:
+        """与えられたパスにPOSTし、JSONレスポンスを辞書で返す。"""
         url = f"{self.base_url}{path}"
         headers = {
             "Authorization": f"Bearer {self.api_key}",
@@ -60,6 +64,7 @@ class OpenAIStorageClient:
         filters: Optional[Dict] = None,
         retries: int = 1,
     ) -> List[StorageHit]:
+        """storage_search エンドポイントを呼び出してヒットを整形する。"""
         payload: Dict[str, object] = {"query": query, "top_k": top_k}
         if filters:
             payload["filters"] = filters
@@ -92,6 +97,7 @@ class OpenAIStorageClient:
         file_id: Optional[str] = None,
         retries: int = 1,
     ) -> Optional[str]:
+        """storage_get エンドポイントからチャンクまたはファイルを取得する。"""
         if not chunk_id and not file_id:
             raise ValueError("Either chunk_id or file_id must be provided.")
 
@@ -114,7 +120,7 @@ class OpenAIStorageClient:
                 if attempts > retries:
                     raise
 def get_vector_store_ids_from_env() -> List[str]:
-    """Read VECTOR_STORE_ID env var and return validated vector store IDs."""
+    """環境変数 VECTOR_STORE_ID からベクターストアIDのリストを抽出する。"""
     raw = os.getenv("VECTOR_STORE_ID", "").strip()
     if not raw:
         return []
@@ -129,7 +135,7 @@ def get_vector_store_ids_from_env() -> List[str]:
 
 
 def generate_search_queries(question: str) -> List[str]:
-    """Generate up to three search queries following the spec."""
+    """自然言語の質問から最大3件の検索クエリを生成する。"""
     normalized = question.strip()
     if not normalized:
         return []
@@ -151,7 +157,7 @@ def generate_search_queries(question: str) -> List[str]:
 
 
 def deduplicate_hits(hits_by_query: Iterable[Tuple[str, List[StorageHit]]]) -> List[StorageHit]:
-    """Merge and deduplicate hits by chunk/file IDs while preserving ordering."""
+    """クエリごとのヒットを重複除去しながら結合する。"""
     seen_keys = set()
     merged: List[StorageHit] = []
     for _, hits in hits_by_query:
@@ -165,7 +171,7 @@ def deduplicate_hits(hits_by_query: Iterable[Tuple[str, List[StorageHit]]]) -> L
 
 
 def build_excerpt(text: str, limit: int = 280) -> str:
-    """Return a compact excerpt trimmed to the requested limit."""
+    """テキストを指定文字数以内に要約した抜粋を返す。"""
     collapsed = re.sub(r"\s+", " ", text).strip()
     if len(collapsed) <= limit:
         return collapsed
@@ -173,7 +179,7 @@ def build_excerpt(text: str, limit: int = 280) -> str:
 
 
 def produce_answer(question: str, top_k: int) -> str:
-    """Main orchestration pipeline for the MCP responder."""
+    """質問に応じて検索を実行し、仕様に沿った回答テキストを生成する。"""
     question = (question or "").strip()
     if not question:
         return "質問が入力されていません。"
@@ -239,7 +245,7 @@ def produce_answer(question: str, top_k: int) -> str:
 
 
 def respond(question: str, top_k: int = 5) -> str:
-    """Wrapper for the Gradio UI."""
+    """Gradio UI から呼び出されるエントリーポイント。"""
     try:
         return produce_answer(question, top_k=int(top_k))
     except Exception:  # pragma: no cover - defensive fallback for UI
@@ -249,9 +255,7 @@ def respond(question: str, top_k: int = 5) -> str:
 with gr.Blocks() as demo:
     gr.Markdown(
         """
-        ## MCP Storage レスポンダ
-        OpenAI Storage (Files / Vector Store) に登録されたデータを検索し、根拠付きで回答します。
-        OPENAI_API_KEY と VECTOR_STORE_ID を環境変数に設定してからご利用ください。
+        ## MCP Storage
         """
     )