signalwire-sdk 3.0.2.dev38__tar.gz → 3.0.2.dev40__tar.gz

{signalwire_sdk-3.0.2.dev38/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.0.2.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.0.2.dev38
+Version: 3.0.2.dev40
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT

{signalwire_sdk-3.0.2.dev38 → signalwire_sdk-3.0.2.dev40}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.0.2.dev38"
+version = "3.0.2.dev40"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_sdk-3.0.2.dev38 → signalwire_sdk-3.0.2.dev40}/signalwire/signalwire/__init__.py

@@ -18,7 +18,7 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 from .core.logging_config import configure_logging
 configure_logging()
 
-__version__ = "3.0.2.dev38"
+__version__ = "3.0.2.dev40"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase

{signalwire_sdk-3.0.2.dev38 → signalwire_sdk-3.0.2.dev40}/signalwire/signalwire/agent_server.py

@@ -61,7 +61,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.0.2.dev38",
+            version="3.0.2.dev40",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.0.2.dev38 → signalwire_sdk-3.0.2.dev40}/signalwire/signalwire/core/mixins/ai_config_mixin.py

@@ -72,39 +72,48 @@ class AIConfigMixin:
             })
         return self
 
-    def add_language(self, 
-                     name: str, 
-                     code: str, 
+    def add_language(self,
+                     name: str,
+                     code: str,
                      voice: str,
                      speech_fillers: Optional[List[str]] = None,
                      function_fillers: Optional[List[str]] = None,
                      engine: Optional[str] = None,
-                     model: Optional[str] = None) -> 'AgentBase':
+                     model: Optional[str] = None,
+                     params: Optional[Dict[str, Any]] = None) -> 'AgentBase':
         """
         Add a language configuration to support multilingual conversations
-        
+
         Args:
             name: Name of the language (e.g., "English", "French")
             code: Language code (e.g., "en-US", "fr-FR")
-            voice: TTS voice to use. Can be a simple name (e.g., "en-US-Neural2-F") 
+            voice: TTS voice to use. Can be a simple name (e.g., "en-US-Neural2-F")
                   or a combined format "engine.voice:model" (e.g., "elevenlabs.josh:eleven_turbo_v2_5")
             speech_fillers: Optional list of filler phrases for natural speech
             function_fillers: Optional list of filler phrases during function calls
             engine: Optional explicit engine name (e.g., "elevenlabs", "rime")
             model: Optional explicit model name (e.g., "eleven_turbo_v2_5", "arcana")
-            
+            params: Optional per-language params dict (engine-specific tuning,
+                voice settings, etc.). Emitted as the language object's
+                ``params`` key in SWML.
+
         Returns:
             Self for method chaining
-            
+
         Examples:
             # Simple voice name
             agent.add_language("English", "en-US", "en-US-Neural2-F")
-            
+
             # Explicit parameters
             agent.add_language("English", "en-US", "josh", engine="elevenlabs", model="eleven_turbo_v2_5")
-            
+
             # Combined format
             agent.add_language("English", "en-US", "elevenlabs.josh:eleven_turbo_v2_5")
+
+            # Per-language params (engine-specific knobs)
+            agent.add_language("English", "en-US", "josh",
+                               engine="elevenlabs",
+                               params={"stability": 0.5, "similarity_boost": 0.75})
         """
         language = {
             "name": name,
@@ -143,10 +152,54 @@ class AIConfigMixin:
             # If only one type of fillers is provided, use the deprecated "fillers" field
             fillers = speech_fillers or function_fillers
             language["fillers"] = fillers
-        
+
+        # Per-language params (engine-specific tuning, voice settings, etc.).
+        # Only emit the key when non-empty so we don't pollute SWML with
+        # empty objects.
+        if params:
+            language["params"] = params
+
         self._languages.append(language)
         return self
 
+    def set_language_params(self, code: str, params: Dict[str, Any]) -> 'AgentBase':
+        """
+        Set (or replace) the per-language ``params`` dict on an already-added
+        language. Useful when language entries are built up via add_language()
+        first and engine-specific tuning is added later (e.g., from a config
+        loader). Returns self for chaining.
+
+        Args:
+            code: Language code as previously passed to ``add_language`` (e.g. ``"en-US"``).
+            params: Engine-specific params dict to attach. Empty dict removes the key.
+
+        Returns:
+            Self for method chaining. No-op if the code isn't found.
+        """
+        for language in self._languages:
+            if language.get("code") == code:
+                if params:
+                    language["params"] = params
+                else:
+                    language.pop("params", None)
+                break
+        return self
+
+    def get_language_params(self, code: str) -> Optional[Dict[str, Any]]:
+        """
+        Read the per-language ``params`` dict for a previously-added language.
+
+        Args:
+            code: Language code as previously passed to ``add_language``.
+
+        Returns:
+            The params dict if set, ``None`` otherwise (including when the code is unknown).
+        """
+        for language in self._languages:
+            if language.get("code") == code:
+                return language.get("params")
+        return None
+
     def set_languages(self, languages: List[Dict[str, Any]]) -> 'AgentBase':
         """
         Set all language configurations at once

{signalwire_sdk-3.0.2.dev38 → signalwire_sdk-3.0.2.dev40}/signalwire/signalwire/skills/web_search/skill.py

@@ -413,57 +413,136 @@ class GoogleSearchScraper:
 
         return metrics
 
+    def _format_snippet_results(self, query: str, search_results: list,
+                                num_results: int) -> str:
+        """Format Google CSE snippets without fetching the underlying pages.
+
+        Used when snippets_only is True, or as a graceful fallback when page
+        scraping is abandoned by the overall_deadline. The result is shorter
+        than a fully-scraped response but always non-empty when CSE returned
+        anything at all, so the kernel never sees a webhook timeout.
+        """
+        if not search_results:
+            return f"No search results found for query: {query}"
+
+        top = search_results[:max(num_results, 1)]
+        lines = [
+            f"Snippet-only results for '{query}' "
+            f"(page content not scraped):\n"
+        ]
+        for i, result in enumerate(top, 1):
+            lines.append(f"=== RESULT {i} ===")
+            lines.append(f"Title: {result.get('title', '')}")
+            lines.append(f"URL: {result.get('url', '')}")
+            snippet = (result.get('snippet') or '').strip()
+            lines.append(f"Snippet: {snippet}")
+            lines.append("")
+        return "\n".join(lines)
+
     def search_and_scrape_best(self, query: str, num_results: int = 3,
                                oversample_factor: float = 4.0, delay: float = 0.5,
-                               min_quality_score: float = 0.2) -> str:
+                               min_quality_score: float = 0.2,
+                               per_page_timeout: float = 2.0,
+                               overall_deadline: float = 10.0,
+                               parallel_scrape: bool = True,
+                               snippets_only: bool = False) -> str:
         """
-        Search and scrape with quality filtering and source diversity
+        Search and scrape with quality filtering and source diversity.
 
         Args:
             query: Search query
             num_results: Number of best results to return
             oversample_factor: How many extra results to fetch (e.g., 4.0 = fetch 4x)
-            delay: Delay between requests
+            delay: Delay between scrape requests (ignored in parallel mode)
             min_quality_score: Minimum quality score to include a result
+            per_page_timeout: Max seconds to wait on each page scrape
+            overall_deadline: Wall-clock budget (seconds) for the whole call.
+                Anything not yet returned by this deadline is abandoned.
+            parallel_scrape: Run all page scrapes concurrently in a thread pool
+            snippets_only: Skip page scraping entirely; format the CSE
+                snippets directly. Use for fast voice answers when full page
+                content is not required.
 
         Returns:
             Formatted string with the best N results from diverse sources
         """
-        # Fetch more results than requested (increased to 4x for better pool)
+        import concurrent.futures
+
+        deadline_at = time.monotonic() + overall_deadline
+
+        # Fetch CSE results. search_google() already uses a 15s timeout
+        # internally; this is the slowest non-cancelable step.
         fetch_count = min(10, int(num_results * oversample_factor))
         search_results = self.search_google(query, fetch_count)
 
         if not search_results:
             return f"No search results found for query: {query}"
 
-        # Process all results and collect quality metrics
-        processed_results = []
-
-        for result in search_results:
-            # Extract content and quality metrics (pass query for relevance scoring)
-            page_text, metrics = self.extract_text_from_url(result['url'])
-
-            # Recalculate metrics with query relevance
-            if page_text:
-                metrics = self._calculate_content_quality(page_text, result['url'], query)
-
-            if metrics.get('quality_score', 0) >= min_quality_score and page_text:
-                processed_results.append({
-                    'title': result['title'],
-                    'url': result['url'],
-                    'snippet': result['snippet'],
-                    'content': page_text,
-                    'metrics': metrics,
-                    'quality_score': metrics.get('quality_score', 0),
-                    'domain': metrics.get('domain', '')
-                })
+        # Snippets-only fast path: skip scraping entirely. Returns in ~1s.
+        if snippets_only:
+            return self._format_snippet_results(query, search_results, num_results)
+
+        def _scrape_one(result):
+            """Fetch + score one candidate. Returns enriched dict or None."""
+            if time.monotonic() >= deadline_at:
+                return None
+            try:
+                page_text, metrics = self.extract_text_from_url(
+                    result['url'], timeout=per_page_timeout
+                )
+            except Exception:
+                return None
+            if not page_text:
+                return None
+            metrics = self._calculate_content_quality(page_text, result['url'], query)
+            if metrics.get('quality_score', 0) < min_quality_score:
+                return None
+            return {
+                'title': result['title'],
+                'url': result['url'],
+                'snippet': result['snippet'],
+                'content': page_text,
+                'metrics': metrics,
+                'quality_score': metrics.get('quality_score', 0),
+                'domain': metrics.get('domain', '')
+            }
 
-            # Small delay between requests
-            if delay > 0:
-                time.sleep(delay)
+        processed_results = []
+        if parallel_scrape:
+            # Dispatch all scrapes at once, harvest whatever finishes before
+            # the deadline. Abandon the rest.
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=min(8, len(search_results))
+            ) as executor:
+                future_to_result = {
+                    executor.submit(_scrape_one, r): r for r in search_results
+                }
+                for future in concurrent.futures.as_completed(future_to_result):
+                    if time.monotonic() >= deadline_at:
+                        # Cancel everything still queued; we are out of time.
+                        for f in future_to_result:
+                            if not f.done():
+                                f.cancel()
+                        break
+                    item = future.result()
+                    if item is not None:
+                        processed_results.append(item)
+        else:
+            # Sequential mode (legacy). Still honors overall_deadline.
+            for result in search_results:
+                if time.monotonic() >= deadline_at:
+                    break
+                item = _scrape_one(result)
+                if item is not None:
+                    processed_results.append(item)
+                if delay > 0:
+                    time.sleep(delay)
 
         if not processed_results:
-            return f"No quality results found for query: {query}. All results were below quality threshold."
+            # Time ran out or every page was below quality threshold. Fall
+            # back to snippet-only results so we return SOMETHING useful
+            # before the kernel webhook timeout fires.
+            return self._format_snippet_results(query, search_results, num_results)
 
         # Sort by quality score
         processed_results.sort(key=lambda x: x['quality_score'], reverse=True)
@@ -581,6 +660,22 @@ class WebSearchSkill(SkillBase):
         self.oversample_factor = self.params.get('oversample_factor', 2.5)
         self.min_quality_score = self.params.get('min_quality_score', 0.3)
 
+        # Latency-control parameters. The SignalWire kernel times out webhook
+        # responses around 55s, so the handler MUST finish under that.
+        #   per_page_timeout: max seconds to wait on a single page scrape.
+        #   overall_deadline: wall-clock budget for the whole tool call. Once
+        #     exceeded, any in-flight scrapes are abandoned and we format
+        #     whatever results we already have (or fall back to snippets).
+        #   parallel_scrape: fetch all candidate pages concurrently via a
+        #     ThreadPoolExecutor instead of one-after-the-other.
+        #   snippets_only: skip scraping entirely and return Google CSE
+        #     snippets only. Fastest mode (sub-second) and good enough for
+        #     most voice answers.
+        self.per_page_timeout = float(self.params.get('per_page_timeout', 2.0))
+        self.overall_deadline = float(self.params.get('overall_deadline', 10.0))
+        self.parallel_scrape = bool(self.params.get('parallel_scrape', True))
+        self.snippets_only = bool(self.params.get('snippets_only', False))
+
         self.no_results_message = self.params.get('no_results_message',
             "I couldn't find quality results for '{query}'. "
             "The search returned only low-quality or inaccessible pages. "
@@ -642,7 +737,11 @@ class WebSearchSkill(SkillBase):
                 num_results=num_results,
                 oversample_factor=self.oversample_factor,
                 delay=self.default_delay,
-                min_quality_score=self.min_quality_score
+                min_quality_score=self.min_quality_score,
+                per_page_timeout=self.per_page_timeout,
+                overall_deadline=self.overall_deadline,
+                parallel_scrape=self.parallel_scrape,
+                snippets_only=self.snippets_only,
             )
 
             if not search_results or "No quality results found" in search_results or "No search results found" in search_results:

{signalwire_sdk-3.0.2.dev38 → signalwire_sdk-3.0.2.dev40/signalwire/signalwire_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.0.2.dev38
+Version: 3.0.2.dev40
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT