timbal 2.0.2__tar.gz → 2.0.4__tar.gz

{timbal-2.0.2 → timbal-2.0.4}/.gitignore

@@ -48,6 +48,7 @@ node_modules/
 **/*lancedb*/
 
 **/NOTES.md
+**/LINKEDIN.md
 
 
 # Internal planning docs

{timbal-2.0.2 → timbal-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timbal
-Version: 2.0.2
+Version: 2.0.4
 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.0.2 → timbal-2.0.4}/pyproject.toml

@@ -72,6 +72,7 @@ dev = [
   "pyngrok>=7.2.3",
   "pytest>=8.3.4",
   "pytest-asyncio>=0.25.2",
+  "pytest-cov>=7.0.0",
   "yappi>=1.7.6",
 ]
 

{timbal-2.0.2 → timbal-2.0.4}/python/timbal/__init__.py

@@ -5,17 +5,19 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from .core import Agent, Tool, Workflow
+    from .core import Agent, FallbackModel, ModelEntry, Tool, Workflow
 
 try:
     from ._version import __version__  # type: ignore
 except ImportError:
     __version__ = "0.0.0.dev0"
 
-__all__ = ["Agent", "Tool", "Workflow"]
+__all__ = ["Agent", "FallbackModel", "ModelEntry", "Tool", "Workflow"]
 
 _LAZY_IMPORTS = {
     "Agent": ".core",
+    "FallbackModel": ".core",
+    "ModelEntry": ".core",
     "Tool": ".core",
     "Workflow": ".core",
 }

{timbal-2.0.2 → timbal-2.0.4}/python/timbal/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.2'
-__version_tuple__ = version_tuple = (2, 0, 2)
+__version__ = version = '2.0.4'
+__version_tuple__ = version_tuple = (2, 0, 4)
 
 __commit_id__ = commit_id = None

timbal-2.0.4/python/timbal/collectors/impl/timbal.py

@@ -0,0 +1,84 @@
+from typing import Any
+
+# `override` was introduced in Python 3.12; use `typing_extensions` for compatibility with older versions
+try:
+    from typing import override
+except ImportError:
+    from typing_extensions import override
+
+import structlog
+
+from ...types.events.approval import ApprovalEvent as TimbalApprovalEvent
+from ...types.events.base import BaseEvent as TimbalBaseEvent
+from ...types.events.delta import DeltaEvent as TimbalDeltaEvent
+from ...types.events.output import OutputEvent as TimbalOutputEvent
+from ...types.events.start import StartEvent as TimbalStartEvent
+from .. import register_collector
+from ..base import BaseCollector
+
+logger = structlog.get_logger("timbal.collectors.impl.timbal")
+
+
+@register_collector
+class TimbalCollector(BaseCollector):
+    """Collector for Timbal events."""
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        self._output_event: TimbalOutputEvent | None = None
+        # Capture every approval gate that fires during the stream so callers
+        # of .collect() can react to all pending approvals — not just the
+        # first one — when concurrent runnables (parallel workflow steps,
+        # multiplexed tools) gate on the same iteration.
+        self._pending_approvals: list[dict[str, Any]] = []
+
+    @classmethod
+    @override
+    def can_handle(cls, event: Any) -> bool:
+        return isinstance(event, TimbalBaseEvent)
+
+    @override
+    def process(self, event: TimbalBaseEvent) -> TimbalBaseEvent | None:
+        """Processes Timbal events."""
+        if isinstance(event, TimbalStartEvent):
+            return event
+        elif isinstance(event, TimbalDeltaEvent):
+            return event
+        elif isinstance(event, TimbalApprovalEvent):
+            self._pending_approvals.append({
+                "approval_id": event.approval_id,
+                "runnable_path": event.runnable_path,
+                "runnable_name": event.runnable_name,
+                "runnable_type": event.runnable_type,
+                "input": event.input,
+                "prompt": event.prompt,
+                "description": event.description,
+                "metadata": event.metadata,
+                "t0": event.t0,
+                "call_id": event.call_id,
+                "parent_call_id": event.parent_call_id,
+            })
+            return event
+        elif isinstance(event, TimbalOutputEvent):
+            self._output_event = event
+            return event
+        elif isinstance(event, TimbalBaseEvent):
+            return event
+        else:
+            logger.warning("Unknown Timbal event type", event_type=type(event), event=event)
+
+    @override
+    def result(self) -> Any:
+        """Returns the final OutputEvent enriched with pending_approvals.
+
+        When concurrent runnables gate, the OutputEvent only references the
+        *first* pending approval through ``status``/``output``. We attach the
+        full list under ``metadata['pending_approvals']`` so consumers driving
+        the resume loop can see every gate from one ``.collect()`` call.
+        """
+        if self._output_event is not None and self._pending_approvals:
+            self._output_event.metadata = {
+                **(self._output_event.metadata or {}),
+                "pending_approvals": list(self._pending_approvals),
+            }
+        return self._output_event

{timbal-2.0.2 → timbal-2.0.4}/python/timbal/core/__init__.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from .agent import Agent
+    from .fallback_model import FallbackModel, ModelEntry
     from .mcp import MCPServer
     from .memory_compaction import MemoryCompactor  # noqa: F401 - type alias
     from .skill import Skill
@@ -16,7 +17,9 @@ if TYPE_CHECKING:
 
 __all__ = [
     "Agent",
+    "FallbackModel",
     "MCPServer",
+    "ModelEntry",
     "Skill",
     "TestModel",
     "Tool",
@@ -26,7 +29,9 @@ __all__ = [
 
 _LAZY_IMPORTS = {
     "Agent": ".agent",
+    "FallbackModel": ".fallback_model",
     "MCPServer": ".mcp",
+    "ModelEntry": ".fallback_model",
     "Skill": ".skill",
     "TestModel": ".test_model",
     "Tool": ".tool",

{timbal-2.0.2 → timbal-2.0.4}/python/timbal/core/agent.py

@@ -26,7 +26,7 @@ from pydantic import (
 )
 from uuid_extensions import uuid7
 
-from ..errors import InterruptError, bail
+from ..errors import ApprovalRequired, InterruptError, bail
 from ..state import get_run_context
 from ..types.content import CustomContent, FileContent, TextContent, ToolResultContent, ToolUseContent
 from ..types.events import BaseEvent, OutputEvent
@@ -195,12 +195,14 @@ class Agent(Runnable):
 
         # Build default params for the internal LLM tool from individual fields
         _llm_default_params = {
-            k: v for k, v in [
+            k: v
+            for k, v in [
                 ("max_tokens", self.max_tokens),
                 ("temperature", self.temperature),
                 ("base_url", self.base_url),
                 ("api_key", self.api_key),
-            ] if v is not None
+            ]
+            if v is not None
         }
         if self.model_params:
             _llm_default_params["provider_params"] = self.model_params
@@ -338,6 +340,37 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
 
         return system_prompt
 
+    def _find_pending_tool_uses(self, memory: list[Message]) -> list[ToolUseContent]:
+        """Return any tool_uses in the most recent assistant message that
+        still have no matching tool_result anywhere later in memory.
+
+        Used on approval-resume: the previous turn left tool_uses unresolved
+        because the user hadn't approved yet. Now that we have a decision we
+        re-execute those gated tool_uses directly without re-calling the LLM
+        (which would fail because most providers reject a request whose last
+        assistant message has unresolved tool_uses).
+        """
+        if not memory:
+            return []
+        for i in range(len(memory) - 1, -1, -1):
+            msg = memory[i]
+            if msg.role != "assistant":
+                continue
+            tool_uses = [
+                c for c in msg.content
+                if isinstance(c, ToolUseContent) and not c.is_server_tool_use
+            ]
+            if not tool_uses:
+                # Most recent assistant message has no tool_uses to resume.
+                return []
+            fulfilled: set[str] = set()
+            for later in memory[i + 1:]:
+                for c in later.content:
+                    if isinstance(c, ToolResultContent):
+                        fulfilled.add(c.id)
+            return [tu for tu in tool_uses if tu.id not in fulfilled]
+        return []
+
     def _synthesize_missing_tool_results(self, memory: list[Message]) -> None:
         """Append synthetic error results for any tool_use blocks that were interrupted.
 
@@ -435,13 +468,28 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
             return
 
         previous_span = self_spans[0]
-
+        prev_status = previous_span.status
+        if isinstance(prev_status, dict):
+            prev_code = prev_status.get("code")
+            prev_reason = prev_status.get("reason")
+        elif prev_status is not None:
+            prev_code = prev_status.code
+            prev_reason = prev_status.reason
+        else:
+            prev_code = None
+            prev_reason = None
         if not isinstance(previous_span.memory, list):
             return
         memory = [Message.validate(m) for m in previous_span.memory]
 
-        # Ensure interrupted tool calls have corresponding results before resuming.
-        self._synthesize_missing_tool_results(memory)
+        # On approval-required resume the gated tool_uses will be re-executed
+        # by the agent loop (see _find_pending_tool_uses), so we must NOT
+        # inject synthetic "tool failed" results for them. Without this guard
+        # the LLM would see fake failures and probably skip retrying the
+        # gated calls, silently dropping the user's approval decisions.
+        is_approval_resume = prev_code == "cancelled" and prev_reason == "approval_required"
+        if not is_approval_resume:
+            self._synthesize_missing_tool_results(memory)
         current_span.memory = memory + current_span.memory
 
         # Cache the already-serialized previous memory so handler() can skip re-dumping.
@@ -472,9 +520,7 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
                     )
                     should_compact = True
                 elif previous_span.usage:
-                    prev_input_tokens = sum(
-                        v for k, v in previous_span.usage.items() if ":input" in k and "token" in k
-                    )
+                    prev_input_tokens = sum(v for k, v in previous_span.usage.items() if ":input" in k and "token" in k)
                     prev_output_tokens = sum(
                         v for k, v in previous_span.usage.items() if ":output" in k and "token" in k
                     )
@@ -495,9 +541,7 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
 
             if should_compact:
                 compactors = (
-                    [self.memory_compaction]
-                    if not isinstance(self.memory_compaction, list)
-                    else self.memory_compaction
+                    [self.memory_compaction] if not isinstance(self.memory_compaction, list) else self.memory_compaction
                 )
                 compaction_steps = []
                 for compactor in compactors:
@@ -509,11 +553,13 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
                         current_span.memory = await compactor(current_span.memory)
                     else:
                         current_span.memory = compactor(current_span.memory)
-                    compaction_steps.append({
-                        "compactor": getattr(compactor, "__name__", repr(compactor)),
-                        "before": before,
-                        "after": len(current_span.memory),
-                    })
+                    compaction_steps.append(
+                        {
+                            "compactor": getattr(compactor, "__name__", repr(compactor)),
+                            "before": before,
+                            "after": len(current_span.memory),
+                        }
+                    )
                 current_span.metadata["compaction"] = {
                     "triggered": True,
                     "utilization": round(utilization, 4) if utilization is not None else None,
@@ -537,6 +583,9 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
             tools_names.add(tool.name)
             if tool.command:
                 commands[tool.command] = tool
+                stripped = tool.command.strip("/")
+                if stripped:
+                    commands[stripped] = tool
 
         for t in self.tools:
             if isinstance(t, ToolSet):
@@ -632,7 +681,7 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
             # Reuse the already-serialized previous messages; only dump new ones
             # (prompt + any synthetic tool results added by _synthesize_missing_tool_results).
             # If compaction ran it rewrites memory, invalidating the cached dump.
-            new_messages = current_span.memory[len(prev_dump):]
+            new_messages = current_span.memory[len(prev_dump) :]
             current_span._memory_dump = prev_dump + await dump(new_messages)
         else:
             current_span._memory_dump = await dump(current_span.memory)
@@ -649,10 +698,15 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
             """Helper to process tool output events and create tool results."""
             if not isinstance(event, OutputEvent) or event.path.count(".") != self._path.count(".") + 1:
                 return
+            if event.status.code == "cancelled" and event.status.reason == "approval_required":
+                return
             if event.status.code == "cancelled" and event.status.reason == "early_exit":
                 bail(event.status.message)
             content = None
-            if event.status.code == "cancelled" and event.status.reason == "early_exit_local":
+            if event.status.code == "cancelled" and event.status.reason == "approval_denied":
+                msg = event.status.message or "The tool call was denied."
+                content = f"[Approval denied] {msg}"
+            elif event.status.code == "cancelled" and event.status.reason == "early_exit_local":
                 msg = event.status.message or "The tool exited early."
                 content = f"[Cancelled] {msg}"
             elif event.error is not None:
@@ -713,7 +767,12 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
                                     {
                                         "role": "assistant",
                                         "content": [
-                                            {"type": "tool_use", "id": tool_use_id, "name": tool.name, "input": tool_input}
+                                            {
+                                                "type": "tool_use",
+                                                "id": tool_use_id,
+                                                "name": tool.name,
+                                                "input": tool_input,
+                                            }
                                         ],
                                     }
                                 )
@@ -721,6 +780,12 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
                                 async for event in tool(**tool_input):
                                     await _process_tool_event(event, tool_use_id, append_to_messages=False)
                                     if isinstance(event, OutputEvent) and event.output is not None:
+                                        if (
+                                            event.status.code == "cancelled"
+                                            and event.status.reason == "approval_required"
+                                        ):
+                                            yield event
+                                            raise ApprovalRequired(event)
                                         current_span.memory.append(
                                             Message.validate(
                                                 {
@@ -732,6 +797,32 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
                                     yield event
                                 return
 
+                # Resume path: if the trailing assistant message has tool_uses
+                # that were left unresolved by an earlier approval gate, run
+                # them directly. Skipping the LLM call here is important —
+                # most providers reject a request whose conversation ends in
+                # an assistant message whose tool_uses have no matching
+                # tool_results.
+                pending_tool_uses = self._find_pending_tool_uses(current_span.memory)
+                if pending_tool_uses:
+                    _llm_memory_saved = True  # nothing to salvage; we never called the LLM
+                    tool_calls = pending_tool_uses
+                    first_pending_approval: OutputEvent | None = None
+                    async for tool_call, event in self._multiplex_tools(tools, tool_calls):
+                        await _process_tool_event(event, tool_call.id, append_to_messages=True)
+                        yield event
+                        if (
+                            isinstance(event, OutputEvent)
+                            and event.status.code == "cancelled"
+                            and event.status.reason == "approval_required"
+                            and first_pending_approval is None
+                        ):
+                            first_pending_approval = event
+                    if first_pending_approval is not None:
+                        raise ApprovalRequired(first_pending_approval)
+                    i += 1
+                    continue
+
                 async for event in self._llm(
                     model=model,
                     messages=current_span.memory,
@@ -819,9 +910,19 @@ If the file is relevant for the user query, USE the `read_skill` tool to get its
                 if not tool_calls:
                     break
 
+                first_pending_approval: OutputEvent | None = None
                 async for tool_call, event in self._multiplex_tools(tools, tool_calls):
                     await _process_tool_event(event, tool_call.id, append_to_messages=True)
                     yield event
+                    if (
+                        isinstance(event, OutputEvent)
+                        and event.status.code == "cancelled"
+                        and event.status.reason == "approval_required"
+                        and first_pending_approval is None
+                    ):
+                        first_pending_approval = event
+                if first_pending_approval is not None:
+                    raise ApprovalRequired(first_pending_approval)
                 i += 1
         finally:
             if not _llm_memory_saved:

timbal-2.0.4/python/timbal/core/fallback_model.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable
+from dataclasses import dataclass
+from typing import Any
+
+import structlog
+from anthropic import APIConnectionError as AnthropicAPIConnectionError
+from anthropic import APIStatusError as AnthropicAPIStatusError
+from anthropic import APITimeoutError as AnthropicAPITimeoutError
+from anthropic import RateLimitError as AnthropicRateLimitError
+from openai import APIConnectionError as OpenAIAPIConnectionError
+from openai import APIStatusError as OpenAIAPIStatusError
+from openai import APITimeoutError as OpenAIAPITimeoutError
+from openai import RateLimitError as OpenAIRateLimitError
+
+from ..errors import FallbackExhausted
+
+logger = structlog.get_logger("timbal.core.fallback_model")
+
+_RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+@dataclass(frozen=True, slots=True)
+class ModelEntry:
+    """One model in a fallback chain."""
+
+    model: str
+    max_retries: int = 2
+    retry_delay: float = 1.0
+    api_key: str | None = None
+    base_url: str | None = None
+
+
+class FallbackModel:
+    """Ordered fallback chain for LLM providers.
+
+    The first model is tried first. If it fails with a retryable provider error
+    after its per-model retries are exhausted, the next entry is attempted.
+    """
+
+    __timbal_fallback_model__ = True
+    provider = "fallback"
+
+    def __init__(
+        self,
+        *models: str | ModelEntry,
+        fallback_on: type[BaseException]
+        | tuple[type[BaseException], ...]
+        | list[type[BaseException]]
+        | Callable[[BaseException], bool]
+        | None = None,
+    ) -> None:
+        if not models:
+            raise ValueError("FallbackModel requires at least one model.")
+
+        self.entries = tuple(entry if isinstance(entry, ModelEntry) else ModelEntry(entry) for entry in models)
+        self.fallback_on = fallback_on
+        self.model_name = " -> ".join(entry.model for entry in self.entries)
+
+    def __str__(self) -> str:
+        return self.entries[0].model
+
+    async def route(
+        self,
+        router: Callable[..., AsyncGenerator[Any, None]],
+        **llm_router_kwargs: Any,
+    ) -> AsyncGenerator[Any, None]:
+        errors: list[tuple[str, BaseException]] = []
+
+        for index, entry in enumerate(self.entries):
+            started = False
+            kwargs = {
+                **llm_router_kwargs,
+                "model": entry.model,
+                "max_retries": entry.max_retries,
+                "retry_delay": entry.retry_delay,
+            }
+            if entry.api_key is not None:
+                kwargs["api_key"] = entry.api_key
+            if entry.base_url is not None:
+                kwargs["base_url"] = entry.base_url
+
+            try:
+                async for chunk in router(**kwargs):
+                    started = True
+                    yield chunk
+                return
+            except Exception as exc:
+                if started:
+                    raise
+                if not self._should_fallback(exc):
+                    raise
+
+                errors.append((entry.model, exc))
+                next_model = self.entries[index + 1].model if index + 1 < len(self.entries) else None
+                logger.warning(
+                    "Falling back to next LLM model",
+                    failed_model=entry.model,
+                    next_model=next_model,
+                    error_type=type(exc).__name__,
+                    error=str(exc),
+                )
+
+        raise FallbackExhausted(errors)
+
+    def _should_fallback(self, exc: BaseException) -> bool:
+        if self.fallback_on is None:
+            return is_retryable_provider_error(exc)
+        if isinstance(self.fallback_on, type) and issubclass(self.fallback_on, BaseException):
+            return isinstance(exc, self.fallback_on)
+        if isinstance(self.fallback_on, (tuple, list)):
+            return isinstance(exc, self.fallback_on)
+        return bool(self.fallback_on(exc))
+
+
+def is_retryable_provider_error(exc: BaseException) -> bool:
+    if isinstance(exc, (OpenAIRateLimitError, AnthropicRateLimitError)):
+        return True
+    if isinstance(exc, (OpenAIAPITimeoutError, AnthropicAPITimeoutError)):
+        return True
+    if isinstance(exc, (OpenAIAPIConnectionError, AnthropicAPIConnectionError)):
+        return True
+    if isinstance(exc, (OpenAIAPIStatusError, AnthropicAPIStatusError)):
+        status_code = getattr(exc, "status_code", None)
+        if status_code is None:
+            status_code = getattr(getattr(exc, "response", None), "status_code", None)
+        return status_code in _RETRYABLE_STATUS_CODES
+    if isinstance(exc, StopAsyncIteration):
+        return True
+
+    message = str(exc).lower()
+    return "overload" in message or "capacity" in message