refactor: extract DEFAULT_HYBRID_ALPHA to constants

Move magic number 0.2 to a named constant in stackone_ai/constants.py
to improve code maintainability and documentation.

Changes:
- Add DEFAULT_HYBRID_ALPHA constant with detailed documentation
- Update ToolIndex.__init__() to use the constant
- Update Tools.meta_tools() to use the constant
- Document the rationale: 10.8% accuracy improvement, validation tested

This makes the hybrid search configuration more discoverable and
easier to maintain across the codebase.

Matches constant extraction done in Node.js SDK (stackone-ai-node#136).

Author: ryoppippi

stackone_ai/constants.py

@@ -3,3 +3,9 @@
 
 # Use bundled specs directly
 OAS_DIR = Path(str(importlib.resources.files("stackone_ai") / "oas"))
+
+# Hybrid search default weight for BM25 vs TF-IDF
+# alpha=0.2 means: 20% BM25 + 80% TF-IDF
+# This value was optimized through validation testing and provides
+# 10.8% improvement in tool discovery accuracy
+DEFAULT_HYBRID_ALPHA: float = 0.2

stackone_ai/meta_tools.py

@@ -9,6 +9,7 @@
 import numpy as np
 from pydantic import BaseModel
 
+from stackone_ai.constants import DEFAULT_HYBRID_ALPHA
 from stackone_ai.models import ExecuteConfig, JsonDict, StackOneTool, ToolParameters
 from stackone_ai.utils.tfidf_index import TfidfDocument, TfidfIndex
 
@@ -27,20 +28,23 @@ class MetaToolSearchResult(BaseModel):
 class ToolIndex:
     """Hybrid BM25 + TF-IDF tool search index"""
 
-    DEFAULT_HYBRID_ALPHA: float = 0.2
-
-    def __init__(self, tools: list[StackOneTool], hybrid_alpha: float = DEFAULT_HYBRID_ALPHA) -> None:
+    def __init__(
+        self, tools: list[StackOneTool], hybrid_alpha: float | None = None
+    ) -> None:
         """Initialize tool index with hybrid search
 
         Args:
             tools: List of tools to index
-            hybrid_alpha: Weight for BM25 in hybrid search (0-1). Default 0.2 gives
-                more weight to BM25 scoring, which has been shown to provide better
-                tool discovery accuracy (10.8% improvement in validation testing).
+            hybrid_alpha: Weight for BM25 in hybrid search (0-1). If not provided,
+                uses DEFAULT_HYBRID_ALPHA (0.2), which gives more weight to BM25 scoring
+                and has been shown to provide better tool discovery accuracy
+                (10.8% improvement in validation testing).
         """
         self.tools = tools
         self.tool_map = {tool.name: tool for tool in tools}
-        self.hybrid_alpha = max(0.0, min(1.0, hybrid_alpha))
+        # Use default if not provided, then clamp to [0, 1]
+        alpha = hybrid_alpha if hybrid_alpha is not None else DEFAULT_HYBRID_ALPHA
+        self.hybrid_alpha = max(0.0, min(1.0, alpha))
 
         # Prepare corpus for both BM25 and TF-IDF
         corpus = []

stackone_ai/models.py

@@ -532,15 +532,16 @@ def to_langchain(self) -> Sequence[BaseTool]:
         """
         return [tool.to_langchain() for tool in self.tools]
 
-    def meta_tools(self, hybrid_alpha: float = 0.2) -> Tools:
+    def meta_tools(self, hybrid_alpha: float | None = None) -> Tools:
         """Return meta tools for tool discovery and execution
 
         Meta tools enable dynamic tool discovery and execution based on natural language queries
         using hybrid BM25 + TF-IDF search.
 
         Args:
-            hybrid_alpha: Weight for BM25 in hybrid search (0-1). Default 0.2 gives more weight
-                to BM25 scoring, which has been shown to provide better tool discovery accuracy
+            hybrid_alpha: Weight for BM25 in hybrid search (0-1). If not provided, uses
+                ToolIndex.DEFAULT_HYBRID_ALPHA (0.2), which gives more weight to BM25 scoring
+                and has been shown to provide better tool discovery accuracy
                 (10.8% improvement in validation testing).
 
         Returns: