💡 docs: Inserindo comentários referente as principais funcionalidades relacionadas as Tools e ao LLMService.

app/services/llm_service.py

@@ -19,6 +19,7 @@ class LLMService:
 
         vertex_tools = []
 
+        # Para cada Tool registrada no sistema (depende da proposta do cliente) criamos uma Tool do Vertex AI
         for tool in tools:
             vertex_tools.append(
                 Tool(
@@ -34,6 +35,14 @@ class LLMService:
 
         return vertex_tools
 
+    """
+    Fluxo principal de geração de resposta.
+
+    Parâmetros:
+    - message: mensagem do usuário
+    - tools: lista de ferramentas disponíveis
+    - history: histórico da conversa (memória)
+    """
     async def generate_response(
         self,
         message: str,
@@ -43,6 +52,9 @@ class LLMService:
 
         vertex_tools = self.build_vertex_tools(tools) # Convertendo tools para formato do Vertex
 
+        # Inicia uma sessão de chat com:
+        # - histórico (se existir)
+        # - ferramentas disponíveis
         chat = self.model.start_chat(
             history=history or [],
             tools=vertex_tools
@@ -50,8 +62,13 @@ class LLMService:
 
         response = chat.send_message(message)
 
+        # Pegamos a primeira resposta candidata do modelo (a com maior coerência com o assunto)
+        # Estrutura interna:
+        # response.candidates -> lista de possíveis respostas
+        # content.parts -> partes da resposta
         part = response.candidates[0].content.parts[0]
 
+        # Verificação se o modelo decidiu chamar alguma função, se decidiu, retornará o nome da função que ele quer executar e o argumento que ele extraiu da mensagem do usuário.
         if part.function_call:
             return {
                 "response": None,
@@ -61,6 +78,7 @@ class LLMService:
                 }
             }
 
+        # Caso não ocorra a chamada de uma função, significa que o modelo respondeu diretamente em texto
         return {
             "response": response.text,
             "tool_call": None

app/services/tool_registry.py

@@ -8,6 +8,7 @@ class ToolRegistry:
     def __init__(self):
         self._tools = []
 
+        # Registrando manualmente por enquanto, porém isso poderia vir de um BD.
         self.register_tool(
             name="consultar_estoque",
             description="Consulta veículos disponíveis até determinado preço", # Descrição que ajuda o modelo Gemini a entender quado selecionar essa Tool.
@@ -25,6 +26,7 @@ class ToolRegistry:
         )
 
 
+    # O método abaixo serve para adicionar uma nova tool ao sistema (podendo inserir a lógica de adcicionar ao BD futuramente).
     def register_tool(self, name, description, parameters, handler):
         self._tools.append(
             ToolDefinition(
@@ -36,10 +38,17 @@ class ToolRegistry:
         )
 
 
+    # Retorna todas as tools registradas, isso será usado pelo LLMService para enviar as ferramentas para o modelo
     def get_tools(self) -> List[ToolDefinition]:
         return self._tools
 
 
+    """
+    Essa função é responsável por executar a tool solicitada pelo modelo.
+        Parâmetros:
+        - name: nome da função que o Gemini decidiu chamar
+        - arguments: argumentos extraídos da mensagem do usuário
+    """
     async def execute(self, name: str, arguments: dict):
         tool = next((t for t in self._tools if t.name == name), None) # Procura dentro da lista de tools aquela que tem o mesmo nome