[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Results\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  /**
   8   * Represents token usage statistics for an AI operation.
   9   *
  10   * This DTO tracks the number of tokens used in prompts and completions,
  11   * which is important for monitoring usage and costs.
  12   *
  13   * Note that thought tokens are a subset of completion tokens, not additive.
  14   * In other words: completionTokens - thoughtTokens = tokens of actual output content.
  15   *
  16   * @since 0.1.0
  17   *
  18   * @phpstan-type TokenUsageArrayShape array{
  19   *     promptTokens: int,
  20   *     completionTokens: int,
  21   *     totalTokens: int,
  22   *     thoughtTokens?: int
  23   * }
  24   *
  25   * @extends AbstractDataTransferObject<TokenUsageArrayShape>
  26   */
  27  class TokenUsage extends AbstractDataTransferObject
  28  {
  29      public const KEY_PROMPT_TOKENS = 'promptTokens';
  30      public const KEY_COMPLETION_TOKENS = 'completionTokens';
  31      public const KEY_TOTAL_TOKENS = 'totalTokens';
  32      public const KEY_THOUGHT_TOKENS = 'thoughtTokens';
  33      /**
  34       * @var int Number of tokens in the prompt.
  35       */
  36      private int $promptTokens;
  37      /**
  38       * @var int Number of tokens in the completion, including any thought tokens.
  39       */
  40      private int $completionTokens;
  41      /**
  42       * @var int Total number of tokens used.
  43       */
  44      private int $totalTokens;
  45      /**
  46       * @var int|null Number of tokens used for thinking, as a subset of completion tokens.
  47       */
  48      private ?int $thoughtTokens;
  49      /**
  50       * Constructor.
  51       *
  52       * @since 0.1.0
  53       *
  54       * @param int $promptTokens Number of tokens in the prompt.
  55       * @param int $completionTokens Number of tokens in the completion, including any thought tokens.
  56       * @param int $totalTokens Total number of tokens used.
  57       * @param int|null $thoughtTokens Number of tokens used for thinking, as a subset of completion tokens.
  58       */
  59      public function __construct(int $promptTokens, int $completionTokens, int $totalTokens, ?int $thoughtTokens = null)
  60      {
  61          $this->promptTokens = $promptTokens;
  62          $this->completionTokens = $completionTokens;
  63          $this->totalTokens = $totalTokens;
  64          $this->thoughtTokens = $thoughtTokens;
  65      }
  66      /**
  67       * Gets the number of prompt tokens.
  68       *
  69       * @since 0.1.0
  70       *
  71       * @return int The prompt token count.
  72       */
  73      public function getPromptTokens(): int
  74      {
  75          return $this->promptTokens;
  76      }
  77      /**
  78       * Gets the number of completion tokens, including any thought tokens.
  79       *
  80       * @since 0.1.0
  81       *
  82       * @return int The completion token count.
  83       */
  84      public function getCompletionTokens(): int
  85      {
  86          return $this->completionTokens;
  87      }
  88      /**
  89       * Gets the total number of tokens.
  90       *
  91       * @since 0.1.0
  92       *
  93       * @return int The total token count.
  94       */
  95      public function getTotalTokens(): int
  96      {
  97          return $this->totalTokens;
  98      }
  99      /**
 100       * Gets the number of thought tokens, which is a subset of the completion token count.
 101       *
 102       * @since 1.3.0
 103       *
 104       * @return int|null The thought token count or null if not available.
 105       */
 106      public function getThoughtTokens(): ?int
 107      {
 108          return $this->thoughtTokens;
 109      }
 110      /**
 111       * {@inheritDoc}
 112       *
 113       * @since 0.1.0
 114       */
 115      public static function getJsonSchema(): array
 116      {
 117          return ['type' => 'object', 'properties' => [self::KEY_PROMPT_TOKENS => ['type' => 'integer', 'description' => 'Number of tokens in the prompt.'], self::KEY_COMPLETION_TOKENS => ['type' => 'integer', 'description' => 'Number of tokens in the completion, including any thought tokens.'], self::KEY_TOTAL_TOKENS => ['type' => 'integer', 'description' => 'Total number of tokens used.'], self::KEY_THOUGHT_TOKENS => ['type' => 'integer', 'description' => 'Number of tokens used for thinking, as a subset of completion tokens.']], 'required' => [self::KEY_PROMPT_TOKENS, self::KEY_COMPLETION_TOKENS, self::KEY_TOTAL_TOKENS]];
 118      }
 119      /**
 120       * {@inheritDoc}
 121       *
 122       * @since 0.1.0
 123       *
 124       * @return TokenUsageArrayShape
 125       */
 126      public function toArray(): array
 127      {
 128          $data = [self::KEY_PROMPT_TOKENS => $this->promptTokens, self::KEY_COMPLETION_TOKENS => $this->completionTokens, self::KEY_TOTAL_TOKENS => $this->totalTokens];
 129          if ($this->thoughtTokens !== null) {
 130              $data[self::KEY_THOUGHT_TOKENS] = $this->thoughtTokens;
 131          }
 132          return $data;
 133      }
 134      /**
 135       * {@inheritDoc}
 136       *
 137       * @since 0.1.0
 138       */
 139      public static function fromArray(array $array): self
 140      {
 141          static::validateFromArrayData($array, [self::KEY_PROMPT_TOKENS, self::KEY_COMPLETION_TOKENS, self::KEY_TOTAL_TOKENS]);
 142          return new self($array[self::KEY_PROMPT_TOKENS], $array[self::KEY_COMPLETION_TOKENS], $array[self::KEY_TOTAL_TOKENS], $array[self::KEY_THOUGHT_TOKENS] ?? null);
 143      }
 144  }