timbal 2.2.3__tar.gz → 2.2.5__tar.gz

{timbal-2.2.3 → timbal-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timbal
-Version: 2.2.3
+Version: 2.2.5
 Summary: Simple, performant, battle-tested framework for building reliable AI applications
 Project-URL: Source, https://github.com/timbal-ai/timbal
 Author-email: Timbal <team@timbal.ai>

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.3'
-__version_tuple__ = version_tuple = (2, 2, 3)
+__version__ = version = '2.2.5'
+__version_tuple__ = version_tuple = (2, 2, 5)
 
 __commit_id__ = commit_id = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/codegen/flow.py

@@ -203,6 +203,24 @@ def _build_node(runnable: Any, *, include_tools: bool = True) -> dict[str, Any]:
     return node
 
 
+def _edge_kind(kinds: set[str] | None) -> str:
+    """Collapse a set of edge-origin kinds into a single label for JSON output.
+
+    A dependency can arise from several sources at once (e.g. an explicit
+    ``depends_on`` that also reads the step's output via a param map). Precedence
+    is ``ordering > when > param`` so explicit sequencing is never masked by
+    param wiring. Unknown/missing (e.g. edges from a direct ``_link``) default to
+    ``ordering`` — the safe choice, since ordering edges are never reduced away.
+    """
+    if not kinds:
+        return "ordering"
+    if "ordering" in kinds:
+        return "ordering"
+    if "when" in kinds:
+        return "when"
+    return "param"
+
+
 def get_flow(workspace_path: str | Path) -> dict[str, Any]:
     """Return a ReactFlow-compatible graph for the workspace entry point.
 
@@ -239,12 +257,14 @@ def get_flow(workspace_path: str | Path) -> dict[str, Any]:
 
         for _step_name, step in runnable._steps.items():
             when_source = _get_when_source(step) if step.when else None
+            kinds_map = getattr(step, "previous_steps_kinds", None) or {}
             for prev_name in step.previous_steps:
                 prev_step = runnable._steps[prev_name]
                 edge: dict[str, Any] = {
                     "id": f"{prev_step._path}->{step._path}",
                     "source": prev_step._path,
                     "target": step._path,
+                    "kind": _edge_kind(kinds_map.get(prev_name)),
                 }
                 if when_source is not None:
                     edge["when"] = when_source
@@ -390,6 +410,48 @@ def _fmt_node_lines(node: dict, indent: str) -> list[str]:
     return lines
 
 
+def _reduce_param_edges(edges: list[dict]) -> list[dict]:
+    """Drop param-induced edges that are transitively implied by another path.
+
+    A param dependency ``A → C`` (the handler/agent on C reads A's output) is a
+    real await-gate at runtime, but for an execution-order view it is redundant
+    when A already reaches C through some other path (e.g. ``A → B → C``). Left
+    in, such edges turn a linear pipeline into a misleading fan-out from the
+    first step.
+
+    Only edges whose single ``kind`` is ``param`` are eligible for removal —
+    explicit ordering (``depends_on`` / hooks) and ``when`` edges are always
+    kept so user-added structure never silently disappears from the compact
+    view. The full edge set (including these) is retained in the JSON output.
+    """
+    adj: dict[str, list[str]] = defaultdict(list)
+    for e in edges:
+        adj[e["source"]].append(e["target"])
+
+    def _reaches(start: str, goal: str, skip: tuple[str, str]) -> bool:
+        """True if ``goal`` is reachable from ``start`` without using the direct ``skip`` edge."""
+        stack = [start]
+        seen = {start}
+        while stack:
+            node = stack.pop()
+            for nxt in adj.get(node, []):
+                if (node, nxt) == skip:
+                    continue
+                if nxt == goal:
+                    return True
+                if nxt not in seen:
+                    seen.add(nxt)
+                    stack.append(nxt)
+        return False
+
+    kept: list[dict] = []
+    for e in edges:
+        if e.get("kind") == "param" and _reaches(e["source"], e["target"], (e["source"], e["target"])):
+            continue
+        kept.append(e)
+    return kept
+
+
 def _build_edge_lines(edges: list[dict]) -> list[str]:
     """Render edges grouped by source, one line per source node."""
     targets_of: dict[str, list[tuple[str, str | None]]] = defaultdict(list)
@@ -472,6 +534,7 @@ def format_compact(flow: dict) -> str:
             for line in _fmt_node_lines(node, indent="  "):
                 lines.append(line)
 
+    edges = _reduce_param_edges(edges)
     if edges:
         lines.append("")
         lines.append("EDGES")

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/core/workflow.py

@@ -142,29 +142,53 @@ class Workflow(Runnable):
         self._steps[runnable.name] = runnable
         runnable.previous_steps = set()
         runnable.next_steps = set()
+        # Per-source edge kinds: maps a previous step name -> set of kinds
+        # ("ordering" | "when" | "param"). Used by introspection (get_flow) to
+        # distinguish explicit sequencing from param/when-induced dependencies.
+        # Runtime sequencing only ever looks at ``previous_steps``.
+        runnable.previous_steps_kinds = {}
         runnable.when = None
 
         # Explicit dependencies
         if depends_on and not isinstance(depends_on, list):
             raise ValueError("depends_on must be a list of step names")
-        depends_on = set(depends_on or [])  # Deduplicate here to avoid duplicate _is_dag calls
 
-        depends_on.update(runnable._dependencies)
-        depends_on.update(runnable._pre_hook_dependencies)
-        depends_on.update(runnable._post_hook_dependencies)
+        # Track dependency origins so introspection can tell explicit ordering
+        # (depends_on / hooks) apart from param- and when-induced wiring. These
+        # all merge into ``previous_steps`` for execution, but the distinction is
+        # lossy once merged (a step can be both an explicit dep and a param dep),
+        # so we record it here while the sources are still separate.
+        ordering_deps = set(depends_on or [])
+        # Hooks read sibling outputs via step_span(); treat as ordering so they
+        # are never silently collapsed in compact views.
+        ordering_deps.update(runnable._pre_hook_dependencies)
+        ordering_deps.update(runnable._post_hook_dependencies)
+        # Handler-body step_span() references are data wiring, not explicit ordering.
+        param_deps = set(runnable._dependencies)
+        when_deps: set[str] = set()
 
         # Optional handler to determine whether to execute the step, and inspect it to automatically link steps
         if when:
             inspect_result = runnable._inspect_callable(when)
             runnable.when = {"callable": when, **inspect_result}
-            depends_on.update(inspect_result["dependencies"])
+            when_deps.update(inspect_result["dependencies"])
 
         # Use kwargs as default params for the runnable, and inspect callables to automatically link steps
         runnable._prepare_default_params(kwargs)
         for v in runnable._default_runtime_params.values():
-            depends_on.update(v["dependencies"])
-
-        for dep in depends_on:
+            param_deps.update(v["dependencies"])
+
+        edge_kinds: dict[str, set[str]] = {}
+        for dep in ordering_deps:
+            edge_kinds.setdefault(dep, set()).add("ordering")
+        for dep in when_deps:
+            edge_kinds.setdefault(dep, set()).add("when")
+        for dep in param_deps:
+            edge_kinds.setdefault(dep, set()).add("param")
+        runnable.previous_steps_kinds = edge_kinds
+
+        # Deduplicate (set union) to avoid duplicate _is_dag calls per shared dep.
+        for dep in edge_kinds:
             logger.info("Linking steps", previous_step=dep, next_step=runnable.name)
             self._link(dep, runnable.name)
 

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/__init__.py

@@ -493,6 +493,7 @@ if TYPE_CHECKING:
         OutlookTrash,
         OutlookUpdateEmail,
     )
+    from .parallel import ParallelExtract, ParallelSearch, ParallelTaskRun
     from .pinecone import (
         PineconeCreateIndex,
         PineconeDeleteVectors,
@@ -1330,6 +1331,9 @@ __all__ = [
     "TavilyExtract",
     "TavilyMap",
     "TavilySearch",
+    "ParallelSearch",
+    "ParallelExtract",
+    "ParallelTaskRun",
     "WebSearch",
     "Write",
     "XSearch",
@@ -2400,6 +2404,9 @@ _LAZY_IMPORTS = {
     "TavilyExtract": ".tavily",
     "TavilyMap": ".tavily",
     "TavilySearch": ".tavily",
+    "ParallelSearch": ".parallel",
+    "ParallelExtract": ".parallel",
+    "ParallelTaskRun": ".parallel",
     "WebSearch": ".web_search",
     "Write": ".write",
     "XSearch": ".xai",

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/elasticsearch.py

@@ -33,8 +33,11 @@ async def _resolve_credentials(tool: Any) -> tuple[str, str | None]:
 class ElasticsearchIngestAttachment(Tool):
     name: str = "elasticsearch_ingest_attachment"
     description: str | None = (
-        "Ingest a base64-encoded file attachment into an Elasticsearch index "
-        "using the ingest-attachment pipeline to extract text content."
+        "Ingest and parse a file attachment — PDF, Word DOCX, PowerPoint PPTX, "
+        "Excel, HTML, RTF, or plain text document — into searchable full text in "
+        "an Elasticsearch index using the ingest-attachment (Apache Tika) pipeline. "
+        "Extract text and metadata from a base64-encoded document or file for "
+        "full-text search."
     )
     integration: Annotated[str, Integration("elasticsearch")] | None = None
     api_key: SecretStr | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/elevenlabs.py

@@ -13,8 +13,9 @@ _ELEVENLABS_BASE = "https://api.elevenlabs.io/v1"
 class ElevenLabsTextToSpeech(Tool):
     name: str = "elevenlabs_text_to_speech"
     description: str | None = (
-        "Convert text to speech using a specified ElevenLabs voice. "
-        "Returns the audio encoded as a base64 string."
+        "Generate a voiceover or narration from text: text-to-speech (TTS) that "
+        "produces natural spoken audio in a chosen ElevenLabs voice. Returns the "
+        "audio as a base64 string."
     )
     integration: Annotated[str, Integration("elevenlabs")] | None = None
     api_key: SecretStr | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/fal.py

@@ -37,12 +37,15 @@ def _queue_model_path_from_submit_response(data: dict[str, Any]) -> str | None:
 class FalQueueSubmit(Tool):
     name: str = "fal_queue_submit"
     description: str | None = (
-        "Submit an async inference job to fal's queue for a model (e.g. fal-ai/flux/schnell). "
-        "Returns request_id, status_url, response_url, cancel_url, and queue_model_path (canonical path for "
-        "follow-up calls). Important: fal may rewrite the route—e.g. you submit fal-ai/flux/schnell but URLs use "
-        "fal-ai/flux. For fal_queue_status, fal_queue_result, and fal_queue_cancel always pass model_id="
-        "queue_model_path from this response (or the path segment from status_url before /requests/), not the "
-        "original submit string, or status polling can return HTTP 405."
+        "Run an AI model on fal (e.g. FLUX) to generate images, video, or audio — "
+        "submits an async inference/generation job to fal's queue. General-purpose "
+        "model runner. Returns request_id, status_url, response_url, cancel_url, and "
+        "queue_model_path (canonical path for follow-up calls). Important: fal may "
+        "rewrite the route—e.g. you submit fal-ai/flux/schnell but URLs use fal-ai/flux. "
+        "For fal_queue_status, fal_queue_result, and fal_queue_cancel always pass "
+        "model_id=queue_model_path from this response (or the path segment from "
+        "status_url before /requests/), not the original submit string, or status "
+        "polling can return HTTP 405."
     )
     integration: Annotated[str, Integration("fal")] | None = None
     api_key: SecretStr | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/gemini_images.py

@@ -148,8 +148,9 @@ class GeminiImagesGenerateImage(Tool):
 class GeminiImagesAnalyzeImage(Tool):
     name: str = "gemini_analyze_image"
     description: str | None = (
-        "Analyze, describe, or extract information from an image using Gemini vision. "
-        "Returns a text response based on your question or instruction."
+        "Analyze an image with the Gemini vision model: describe a picture, photo, "
+        "or screenshot, answer questions about its contents, and OCR — read, "
+        "extract, and transcribe text from an image."
     )
     integration: Annotated[str, Integration("gemini")] | None = None
     api_key: SecretStr | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/google_analytics.py

@@ -74,7 +74,10 @@ class GoogleAnalyticsListAccountSummaries(Tool):
 
 class GoogleAnalyticsRunReport(Tool):
     name: str = "google_analytics_run_report"
-    description: str | None = "Run a standard GA4 report with dimensions, metrics, and date ranges."
+    description: str | None = (
+        "Run a standard GA4 analytics report — website traffic, visitors, sessions, "
+        "pageviews, and conversions — with dimensions, metrics, and date ranges."
+    )
     integration: Annotated[str, Integration("google_analytics")] | None = None
     token: SecretStr | None = None
     default_property_id: str | None = None
@@ -131,7 +134,10 @@ class GoogleAnalyticsRunReport(Tool):
 
 class GoogleAnalyticsRunRealtimeReport(Tool):
     name: str = "google_analytics_run_realtime_report"
-    description: str | None = "Run a GA4 realtime report for active users and events."
+    description: str | None = (
+        "Run a GA4 realtime report: active users and visitors on your site right "
+        "now — live website traffic and events."
+    )
     integration: Annotated[str, Integration("google_analytics")] | None = None
     token: SecretStr | None = None
     default_property_id: str | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/google_docs.py

@@ -505,7 +505,7 @@ class GoogleDocsGetTabContent(Tool):
 class GoogleDocsGetDocument(Tool):
     name: str = "google_docs_get_document"
     description: str | None = (
-        "Get the contents of the latest version of a Google Doc. "
+        "Read and return the text contents of a Google Docs document. "
         "Set include_tabs_content=true for multi-tab documents."
     )
     integration: Annotated[str, Integration("google_docs")] | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/google_drive.py

@@ -143,7 +143,7 @@ class GoogleDriveGetDownloadLink(Tool):
 
 class GoogleDriveGetFile(Tool):
     name: str = "google_drive_get_file"
-    description: str | None = "Download and return content of a Google Drive file."
+    description: str | None = "Download and return the content of a Google Drive file or document (PDF, Word, etc.) by id."
     integration: Annotated[str, Integration("google_drive")] | None = None
     token: SecretStr | None = None
 
@@ -308,7 +308,7 @@ class GoogleDriveSearchFolders(Tool):
 
 class GoogleDriveSearchFiles(Tool):
     name: str = "google_drive_search_files"
-    description: str | None = "Search for files in Google Drive with optional query. Supports pagination, filtering by folder, name, and trashed status."
+    description: str | None = "Search Google Drive to find a file, document, or folder by name or query. Locate documents in Drive. Supports pagination, filtering by folder, name, and trashed status."
     integration: Annotated[str, Integration("google_drive")] | None = None
     token: SecretStr | None = None
 

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/higgsfield.py

@@ -653,7 +653,11 @@ class HiggsfieldSoulTrain(_HiggsfieldTool):
 
 class HiggsfieldSoulGenerate(_HiggsfieldTool):
     name: str = "higgsfield_soul_generate"
-    description: str | None = "Generate image or video using a trained Soul character."
+    description: str | None = (
+        "Generate photorealistic images of a person or character with Higgsfield "
+        "Soul — UGC-style content, avatars, and character image generation from a "
+        "prompt, using a trained Soul character."
+    )
 
     def __init__(self, **kwargs: Any) -> None:
         async def _soul_generate(

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/jira.py

@@ -495,7 +495,10 @@ class JiraGetIssueTypesForProject(Tool):
 
 class JiraCreateIssue(Tool):
     name: str = "jira_create_issue"
-    description: str | None = "Create an issue with a Jira fields payload (project, issuetype, summary, etc.)."
+    description: str | None = (
+        "Create a Jira issue — a bug, task, story, or ticket — from a fields "
+        "payload (project, issuetype, summary, etc.)."
+    )
     integration: Annotated[str, Integration("jira")] | None = None
     token: SecretStr | None = None
 

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/onedrive.py

@@ -127,7 +127,7 @@ class OneDriveListFiles(Tool):
 
 class OneDriveGetFile(Tool):
     name: str = "onedrive_get_file"
-    description: str | None = "Get file metadata and content by file ID from OneDrive."
+    description: str | None = "Get the content and metadata of a OneDrive file or document by id."
     integration: Annotated[str, Integration("onedrive")] | None = None
 
     def get_config(self) -> dict[str, Any]:
@@ -210,7 +210,7 @@ class OneDriveFindFile(Tool):
 
 class OneDriveDownloadFile(Tool):
     name: str = "onedrive_download_file"
-    description: str | None = "Download a file from OneDrive by file ID."
+    description: str | None = "Download a OneDrive file or document (Word, Excel, PDF, etc.) by id."
     integration: Annotated[str, Integration("onedrive")] | None = None
 
     def get_config(self) -> dict[str, Any]:

timbal-2.2.5/python/timbal/tools/parallel.py

@@ -0,0 +1,191 @@
+from typing import Annotated, Any
+
+from pydantic import Field, SecretStr
+
+from ..core.tool import Tool
+from ..platform.integrations import Integration
+from ._creds import resolve_api_key
+
+_BASE_URL = "https://api.parallel.ai"
+
+
+class ParallelSearch(Tool):
+    name: str = "parallel_search"
+    description: str | None = (
+        "Search the web with Parallel. Takes a natural-language objective and/or keyword "
+        "queries and returns ranked results with LLM-optimized excerpts, titles, and URLs."
+    )
+    integration: Annotated[str, Integration("parallel")] | None = None
+    api_key: SecretStr | None = None
+
+    def get_config(self) -> dict[str, Any]:
+        """See base class."""
+        return {
+            **super().get_config(),
+            **self._annotate_config({"integration": self.integration, "api_key": self.api_key}),
+        }
+
+    def __init__(self, **kwargs: Any) -> None:
+        async def _parallel_search(
+            search_queries: list[str] = Field(..., description="Concise keyword search queries, 3-6 words each"),
+            objective: str | None = Field(None, description="Natural-language description of the underlying question or goal"),
+            mode: str = Field("advanced", description='Search mode: "turbo", "basic", or "advanced"'),
+            max_results: int = Field(10, description="Maximum number of results to return"),
+            max_chars_total: int | None = Field(None, description="Upper bound on total excerpt characters across results"),
+            include_domains: list[str] | None = Field(None, description="Only include results from these domains"),
+            exclude_domains: list[str] | None = Field(None, description="Exclude results from these domains"),
+            location: str | None = Field(None, description="ISO 3166-1 alpha-2 country code to bias results (e.g. 'US')"),
+        ) -> dict:
+            api_key = await resolve_api_key(tool=self, provider_name="Parallel", env_var="PARALLEL_API_KEY")
+            import httpx
+
+            advanced_settings: dict[str, Any] = {"max_results": max_results}
+            if location:
+                advanced_settings["location"] = location
+            source_policy: dict[str, Any] = {}
+            if include_domains:
+                source_policy["include_domains"] = include_domains
+            if exclude_domains:
+                source_policy["exclude_domains"] = exclude_domains
+            if source_policy:
+                advanced_settings["source_policy"] = source_policy
+
+            payload: dict[str, Any] = {
+                "search_queries": search_queries,
+                "mode": mode,
+                "advanced_settings": advanced_settings,
+            }
+            if objective:
+                payload["objective"] = objective
+            if max_chars_total is not None:
+                payload["max_chars_total"] = max_chars_total
+
+            async with httpx.AsyncClient(timeout=httpx.Timeout(30.0, connect=10.0)) as client:
+                response = await client.post(
+                    f"{_BASE_URL}/v1/search",
+                    headers={"x-api-key": api_key, "Content-Type": "application/json"},
+                    json=payload,
+                    timeout=httpx.Timeout(60.0, read=None),
+                )
+                response.raise_for_status()
+                return response.json()
+
+        super().__init__(handler=_parallel_search, **kwargs)
+
+
+class ParallelExtract(Tool):
+    name: str = "parallel_extract"
+    description: str | None = (
+        "Extract content from specific web pages with Parallel. Provide up to 20 URLs and get back "
+        "LLM-optimized excerpts (and optionally full page content) for each, ranked against an "
+        "optional objective and queries."
+    )
+    integration: Annotated[str, Integration("parallel")] | None = None
+    api_key: SecretStr | None = None
+
+    def get_config(self) -> dict[str, Any]:
+        """See base class."""
+        return {
+            **super().get_config(),
+            **self._annotate_config({"integration": self.integration, "api_key": self.api_key}),
+        }
+
+    def __init__(self, **kwargs: Any) -> None:
+        async def _parallel_extract(
+            urls: list[str] = Field(..., description="URLs to extract content from (up to 20)"),
+            objective: str | None = Field(None, description="Natural-language description of what to extract from the pages"),
+            search_queries: list[str] | None = Field(None, description="Optional keyword queries to rank excerpts against"),
+            max_chars_total: int | None = Field(None, description="Upper bound on total characters across all excerpts"),
+            max_chars_per_result: int | None = Field(None, description="Upper bound on excerpt characters per URL"),
+            full_content: bool = Field(False, description="Return the full cleaned page content in addition to excerpts"),
+        ) -> dict:
+            api_key = await resolve_api_key(tool=self, provider_name="Parallel", env_var="PARALLEL_API_KEY")
+            import httpx
+
+            advanced_settings: dict[str, Any] = {}
+            if max_chars_per_result is not None:
+                advanced_settings["excerpt_settings"] = {"max_chars_per_result": max_chars_per_result}
+            if full_content:
+                advanced_settings["full_content"] = True
+
+            payload: dict[str, Any] = {"urls": urls}
+            if objective:
+                payload["objective"] = objective
+            if search_queries:
+                payload["search_queries"] = search_queries
+            if max_chars_total is not None:
+                payload["max_chars_total"] = max_chars_total
+            if advanced_settings:
+                payload["advanced_settings"] = advanced_settings
+
+            async with httpx.AsyncClient(timeout=httpx.Timeout(30.0, connect=10.0)) as client:
+                response = await client.post(
+                    f"{_BASE_URL}/v1/extract",
+                    headers={"x-api-key": api_key, "Content-Type": "application/json"},
+                    json=payload,
+                    timeout=httpx.Timeout(120.0, read=None),
+                )
+                response.raise_for_status()
+                return response.json()
+
+        super().__init__(handler=_parallel_extract, **kwargs)
+
+
+class ParallelTaskRun(Tool):
+    name: str = "parallel_task_run"
+    description: str | None = (
+        "Run a Parallel research task: give a plain-language objective and Parallel performs web "
+        "research and returns an answer with citations. Optionally pass a JSON schema to get "
+        "structured output. Blocks until the run completes."
+    )
+    integration: Annotated[str, Integration("parallel")] | None = None
+    api_key: SecretStr | None = None
+
+    def get_config(self) -> dict[str, Any]:
+        """See base class."""
+        return {
+            **super().get_config(),
+            **self._annotate_config({"integration": self.integration, "api_key": self.api_key}),
+        }
+
+    def __init__(self, **kwargs: Any) -> None:
+        async def _parallel_task_run(
+            input: str | dict = Field(..., description="The research objective as text, or a structured input object"),
+            processor: str = Field("base", description='Depth/latency tier: "lite", "base", "core", "pro", or "ultra" (append "-fast" for low-latency variants, e.g. "ultra-fast")'),
+            output_schema: dict | None = Field(None, description="Optional JSON schema for structured output. Omit to get a text answer."),
+            output_description: str | None = Field(None, description="Natural-language description of the desired output when not using a JSON schema"),
+        ) -> dict:
+            api_key = await resolve_api_key(tool=self, provider_name="Parallel", env_var="PARALLEL_API_KEY")
+            import httpx
+
+            task_spec: dict[str, Any] = {}
+            if output_schema is not None:
+                task_spec["output_schema"] = {"type": "json", "json_schema": output_schema}
+            elif output_description is not None:
+                task_spec["output_schema"] = {"type": "text", "description": output_description}
+
+            payload: dict[str, Any] = {"input": input, "processor": processor}
+            if task_spec:
+                payload["task_spec"] = task_spec
+
+            headers = {"x-api-key": api_key, "Content-Type": "application/json"}
+            async with httpx.AsyncClient(timeout=httpx.Timeout(30.0, connect=10.0)) as client:
+                create = await client.post(
+                    f"{_BASE_URL}/v1/tasks/runs",
+                    headers=headers,
+                    json=payload,
+                    timeout=httpx.Timeout(60.0, read=None),
+                )
+                create.raise_for_status()
+                run_id = create.json()["run_id"]
+
+                # Blocks until the run is completed.
+                result = await client.get(
+                    f"{_BASE_URL}/v1/tasks/runs/{run_id}/result",
+                    headers=headers,
+                    timeout=httpx.Timeout(600.0, read=None),
+                )
+                result.raise_for_status()
+                return result.json()
+
+        super().__init__(handler=_parallel_task_run, **kwargs)

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/pinecone.py

@@ -160,7 +160,10 @@ class PineconeUpsertVectors(Tool):
 
 class PineconeQuery(Tool):
     name: str = "pinecone_query"
-    description: str | None = "Query a Pinecone index for nearest neighbors."
+    description: str | None = (
+        "Query a Pinecone vector index for nearest neighbors — semantic similarity "
+        "search / vector search over stored embeddings."
+    )
     integration: Annotated[str, Integration("pinecone")] | None = None
     api_key: SecretStr | None = None
 

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/quiver_ai.py

@@ -39,9 +39,11 @@ def _normalize_image(image: str | dict[str, str]) -> dict[str, str]:
 class QuiverAIGenerateSVG(Tool):
     name: str = "quiver_ai_generate_svg"
     description: str | None = (
-        "Generate one or more SVG graphics from a text prompt using QuiverAI's Arrow models. "
-        "Supports optional reference images to guide style/composition. "
-        "Returns raw SVG markup along with request metadata and credit usage."
+        "Generate SVG vector graphics — logos, icons, and illustrations — from a "
+        "text prompt with QuiverAI's Arrow models. Produces scalable vector (SVG) "
+        "output, not raster images. Supports optional reference images to guide "
+        "style/composition. Returns raw SVG markup along with request metadata and "
+        "credit usage."
     )
     integration: Annotated[str, Integration("quiver_ai")] | None = None
     api_key: SecretStr | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/replicate.py

@@ -22,9 +22,11 @@ def _replicate_headers(api_token: str, extra: dict[str, str] | None = None) -> d
 class ReplicateCreatePrediction(Tool):
     name: str = "replicate_create_prediction"
     description: str | None = (
-        "Create a Replicate prediction for a model version and inputs. "
-        "Use official model refs like owner/name or a full version id. "
-        "Optionally wait up to N seconds for completion via prefer_wait_seconds."
+        "Run any AI model on Replicate (owner/name model refs) to generate images, "
+        "video, audio, or text from inputs. General-purpose model runner / inference "
+        "call for open-source and community models. Use official model refs like "
+        "owner/name or a full version id. Optionally wait up to N seconds for "
+        "completion via prefer_wait_seconds."
     )
     integration: Annotated[str, Integration("replicate")] | None = None
     api_token: SecretStr | None = None

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/sharepoint.py

@@ -252,8 +252,8 @@ class SharePointGetFile(Tool):
 class SharePointDownloadFile(Tool):
     name: str = "sharepoint_download_file"
     description: str | None = (
-        "Download a file from a SharePoint site by file ID. Returns base64-encoded content "
-        "(safe for Word, Excel, PDF and other binaries)."
+        "Download a SharePoint file or document (Word, Excel, PDF, etc.) by file id. "
+        "Returns base64-encoded content (safe for Word, Excel, PDF and other binaries)."
     )
     integration: Annotated[str, Integration("sharepoint")] | None = None
 

{timbal-2.2.3 → timbal-2.2.5}/python/timbal/tools/stripe.py

@@ -147,7 +147,10 @@ class SearchCustomer(Tool):
 
 class CreatePayment(Tool):
     name: str = "stripe_create_payment"
-    description: str | None = "Create a Stripe PaymentIntent to collect a payment."
+    description: str | None = (
+        "Charge a customer / collect a payment — create a Stripe PaymentIntent to "
+        "bill, take, or process a payment."
+    )
     integration: Annotated[str, Integration("stripe")] | None = None
     api_key: SecretStr | None = None