|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ExtractUsageTokens
Extracts token usage values from JSON.
Intention
The PSJ.ExtractUsageTokens command in SPR takes a JSON string ($$JSON) and extracts token usage values (prompt, completion, and total tokens) from the "usage" object, storing them in specified variables ($$PRM, $$CMP, $$TOT). Optionally, it stores a success flag in $$RET. It’s like asking your robot to read a JSON usage report and break down the token costs for you.
For example, from {"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}, it sets variables to 10, 5, and 15 respectively.
Illustration
📝 Extract: PSJ.ExtractUsageTokens|{"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}|$$PRM|$$CMP|$$TOT sets $$PRM=10, $$CMP=5, $$TOT=15.
📝 With Return: PSJ.ExtractUsageTokens|{"usage":{"prompt_tokens":5,"completion_tokens":15,"total_tokens":20}}|$$PRM|$$CMP|$$TOT|$$RES sets $$RES=0 on success.
Syntax
PSJ.ExtractUsageTokens|$$JSON|$$PRM|$$CMP|$$TOT[|$$RET]
Parameter Explanation
P1 - $$JSON - (Variable, String)
The JSON string to parse (e.g., $$JSON as "{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5,\"total_tokens\":15}}"). Required.
P2 - $$PRM - (Variable, Numeric)
The variable to store the prompt tokens count (e.g., $$PRM as "10"). Required.
P3 - $$CMP - (Variable, Numeric)
The variable to store the completion tokens count (e.g., $$CMP as "5"). Required.
P4 - $$TOT - (Variable, Numeric)
The variable to store the total tokens count (e.g., $$TOT as "15"). Required.
P5 - $$RET - (Variable, Numeric, Optional)
The variable to store the result flag (0 for success, -1 for error) (e.g., $$RET as "$$RES"). If omitted, the flag is returned but not stored.
Technical Background
This command calls W_JSON_ExtractUsageTokens, which parses a JSON string (jsonText) and extracts token usage values from the "usage" object into three LONG variables: promptTokens, completionTokens, and totalTokens. It returns 0 on success or -1 if an error occurs (e.g., invalid JSON, missing "usage" object, or fields). Internally, it likely uses W_JSON_ParseString to create a handle, W_JSON_GetNumberByPath to extract values at "usage.prompt_tokens", "usage.completion_tokens", and "usage.total_tokens", and W_JSON_FreeHandle to clean up. Errors set gLastJSONError and gLastJSONErrorMsg. No handle is returned, so no freeing is needed by the caller.
Examples
'***********************************
' Sample 1: Extract Token Counts
PSJ.ExtractUsageTokens|{"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}|$$PRM|$$CMP|$$TOT
' Print the extracted values
PRT.Prompt: $$PRM
PRT.Completion: $$CMP
PRT.Total: $$TOT
MBX.Ready
'***********************************
' Sample 2: With Result Flag
PSJ.ExtractUsageTokens|{"usage":{"prompt_tokens":5,"completion_tokens":15,"total_tokens":20}}|$$PRM|$$CMP|$$TOT|$$RES
' Print the results
PRT.Prompt: $$PRM
PRT.Completion: $$CMP
PRT.Total: $$TOT
PRT.Result: $$RES
MBX.Ready
Remarks
- Stores token counts as numbers in $$PRM, $$CMP, and $$TOT; no handle is created.
- $$RET is 0 on success, -1 on error.
- Use PSJ.ErrCode to diagnose errors if $$RET is -1.
Limitations
- $$JSON must be valid JSON with a "usage" object.
- Requires fields "prompt_tokens", "completion_tokens", and "total_tokens" in "usage".
See also: