From 1dc4f2e8977eb68b54dc3184a9548dfe10e57f3e Mon Sep 17 00:00:00 2001
From: Greyson LaLonde <greyson.r.lalonde@gmail.com>
Date: Wed, 10 Sep 2025 09:23:39 -0400
Subject: [PATCH] chore: add typing and docstrings to base_token_process module
 (#3486)

Co-authored-by: Lucas Gomide <lucaslg200@gmail.com>
---
 .../utilities/base_token_process.py           | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/crewai/agents/agent_builder/utilities/base_token_process.py b/src/crewai/agents/agent_builder/utilities/base_token_process.py
index 3ce5cfb82..1fa46dd61 100644
--- a/src/crewai/agents/agent_builder/utilities/base_token_process.py
+++ b/src/crewai/agents/agent_builder/utilities/base_token_process.py
@@ -1,8 +1,25 @@
+"""Token usage tracking utilities.
+
+This module provides utilities for tracking token consumption and request
+metrics during agent execution.
+"""
+
 from crewai.types.usage_metrics import UsageMetrics
 
 
 class TokenProcess:
+    """Track token usage during agent processing.
+
+    Attributes:
+        total_tokens: Total number of tokens used.
+        prompt_tokens: Number of tokens used in prompts.
+        cached_prompt_tokens: Number of cached prompt tokens used.
+        completion_tokens: Number of tokens used in completions.
+        successful_requests: Number of successful requests made.
+    """
+
     def __init__(self) -> None:
+        """Initialize token tracking with zero values."""
         self.total_tokens: int = 0
         self.prompt_tokens: int = 0
         self.cached_prompt_tokens: int = 0
@@ -10,20 +27,45 @@ class TokenProcess:
         self.successful_requests: int = 0
 
     def sum_prompt_tokens(self, tokens: int) -> None:
+        """Add prompt tokens to the running totals.
+
+        Args:
+            tokens: Number of prompt tokens to add.
+        """
         self.prompt_tokens += tokens
         self.total_tokens += tokens
 
     def sum_completion_tokens(self, tokens: int) -> None:
+        """Add completion tokens to the running totals.
+
+        Args:
+            tokens: Number of completion tokens to add.
+        """
         self.completion_tokens += tokens
         self.total_tokens += tokens
 
     def sum_cached_prompt_tokens(self, tokens: int) -> None:
+        """Add cached prompt tokens to the running total.
+
+        Args:
+            tokens: Number of cached prompt tokens to add.
+        """
         self.cached_prompt_tokens += tokens
 
     def sum_successful_requests(self, requests: int) -> None:
+        """Add successful requests to the running total.
+
+        Args:
+            requests: Number of successful requests to add.
+        """
         self.successful_requests += requests
 
     def get_summary(self) -> UsageMetrics:
+        """Get a summary of all tracked metrics.
+
+        Returns:
+            UsageMetrics object with current totals.
+        """
         return UsageMetrics(
             total_tokens=self.total_tokens,
             prompt_tokens=self.prompt_tokens,