Add LLM token

backend/app/services/llm/base_client.py

@@ -1,9 +1,16 @@
-"""Provide service-layer logic for base client."""
+"""Provide service-layer logic for base client.
+
+P0-0: ``LLMResponse`` now carries an optional ``tool_calls`` list so that any
+downstream code (agents, pipelines) can inspect and dispatch tool invocations
+without touching the provider-specific adapter layer.
+"""
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import List, Dict, Optional, Any
 from enum import Enum
+
+from app.services.llm.tool_types import Tool, ToolCall  # noqa: F401 – re-exported for callers
 # Keep provider-specific behavior explicit so debugging stays straightforward.
 
 
@@ -24,6 +31,8 @@ class LLMResponse:
     finish_reason: str = "stop"
     latency_ms: int = 0
     error: Optional[str] = None
+    # P0-0: populated when the model returns tool-call(s) instead of plain text.
+    tool_calls: List[ToolCall] = field(default_factory=list)
 
     @property
     def is_success(self) -> bool:
@@ -63,9 +72,19 @@ class BaseLLMClient(ABC):
         messages: List[Dict[str, str]],
         max_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
+        tools: Optional[List["Tool"]] = None,
         **kwargs
     ) -> LLMResponse:
-        """Handle chat for the Base L L M Client instance."""
+        """Handle chat for the Base L L M Client instance.
+
+        Args:
+            messages: OpenAI-format message list.
+            max_tokens: Override config max_tokens when set.
+            temperature: Override config temperature when set.
+            tools: Optional list of Tool definitions to offer the model.
+                   When provided, the model may respond with tool_calls in the
+                   returned LLMResponse instead of (or in addition to) content.
+        """
         pass
 
     def complete(