timbal 2.2.4__tar.gz → 2.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timbal
-Version: 2.2.4
+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.4 → 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.4'
-__version_tuple__ = version_tuple = (2, 2, 4)
+__version__ = version = '2.2.5'
+__version_tuple__ = version_tuple = (2, 2, 5)
 
 __commit_id__ = commit_id = None

{timbal-2.2.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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.4 → 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
 

{timbal-2.2.4 → timbal-2.2.5}/python/timbal/tools/zendesk.py

@@ -195,7 +195,10 @@ class ZendeskShowTicket(Tool):
 
 class ZendeskUpdateTicket(Tool):
     name: str = "zendesk_update_ticket"
-    description: str | None = "Update an existing Zendesk ticket."
+    description: str | None = (
+        "Update or reply to an existing Zendesk support ticket: add a public "
+        "reply/comment, change status, or reassign."
+    )
     integration: Annotated[str, Integration("zendesk")] | None = None
     subdomain: str | None = None
     email: SecretStr | None = None
@@ -8600,7 +8603,10 @@ class ZendeskCreateRequest(Tool):
 
 class ZendeskUpdateRequest(Tool):
     name: str = "zendesk_update_request"
-    description: str | None = "Update a Zendesk request (add comment, mark solved, add collaborators)."
+    description: str | None = (
+        "Update or reply to a Zendesk request (end-user support ticket): add a "
+        "comment/reply, mark solved, or add collaborators."
+    )
     integration: Annotated[str, Integration("zendesk")] | None = None
     subdomain: str | None = None
     email: SecretStr | None = None