- Methods: All Methods Documented Methods Hide Methods
- Source: Display Source Hide Source
- Variables: Show Variables Hide Variables
Class ::nsmcp::QuestionUsage
::nsmcp::QuestionUsagecreate ...
Defined in /usr/local/ns/tcl/nsmcp/question-usage.tcl
Class Relations
::nx::Class create ::nsmcp::QuestionUsage \ -superclass ::nsmcp::ObjectMethods (to be applied on the object)
read (scripted, public)
nsmcp::QuestionUsageread path server
Summarize retained token usage for a virtual server.
- Parameters:
- path (required)
- Path to the current JSON Lines journal.
- server (required)
- Virtual server whose records are included.
- Returns:
- Usage totals, grouped counts and coverage diagnostics.
- Testcases:
- No testcase defined.
set result [dict create available true timezone UTC scope retained-finished-questions totals [::nsmcp::usageEmpty] days {} models {} users {} omittedGroupRecords {days 0 models 0 users 0} malformedRecords 0 duplicateRecords 0 readErrors 0 recordLimitReached false firstAt {} lastAt {} coverageComplete false olderRecordsMayBeOmitted [file exists ${path}.1]] set seen {} set count 0 foreach file [list $path ${path}.1] { if {![file exists $file]} { continue } if {[catch { set f [open $file rb] }]} { dict incr result readErrors continue } try { set examined 0 set buffer {} while {($buffer ne "" || ![eof $f]) && $count < 20000 && ($buffer ne "" || $examined < 4194304)} { # Writer bounds each line; malformed external files cannot cause # unbounded gets allocations or script evaluation. set line {} set long false while {1} { if {[string first "\n" $buffer] >= 0} { set end [string first "\n" $buffer] set part [string range $buffer 0 $end-1] set buffer [string range $buffer $end+1 end] if {[string length $line]+[string length $part] <= 16384} { append line $part } else { set long true } break } if {[string length $line]+[string length $buffer] <= 16384} { append line $buffer } else { set long true } set buffer {} if {[eof $f] || $examined >= 4194304} { break } set buffer [read $f [expr {min(8192,4194304-$examined)}]] incr examined [string length $buffer] } if {$line eq "" && [eof $f]} { break } incr count if {$long || [catch { set entry [ns_json parse [encoding convertfrom utf-8 $line]] foreach key {version timestamp state server backend model principal conversation id tokens} { dict get $entry $key } if {[dict get $entry version] ne "1" || [dict get $entry state] ni {complete partial unavailable} || ![string is wideinteger -strict [dict get $entry timestamp]]} { error invalid } dict for {key n} [dict get $entry tokens] { if {$key ni {inputTokens outputTokens totalTokens cachedInputTokens reasoningOutputTokens} || ![string is wideinteger -strict $n] || $n < 0 || $n > 1000000000000000} { error invalid } } set day [clock format [dict get $entry timestamp] -timezone UTC -format %Y-%m-%d] if {[dict get $entry state] eq "complete"} { foreach key {inputTokens outputTokens totalTokens} { dict get $entry tokens $key } } }]} { dict incr result malformedRecords continue } if {[dict get $entry server] ne $server} { continue } set id [list $server [dict get $entry conversation] [dict get $entry id]] if {[dict exists $seen $id]} { dict incr result duplicateRecords continue } dict set seen $id 1 set stamp [dict get $entry timestamp] if {[dict get $result firstAt] eq "" || $stamp < [dict get $result firstAt]} { dict set result firstAt $stamp } if {[dict get $result lastAt] eq "" || $stamp > [dict get $result lastAt]} { dict set result lastAt $stamp } set totals [dict get $result totals] ::nsmcp::usageAdd totals $entry dict set result totals $totals foreach {view key} [list days $day models [list [dict get $entry backend] [dict get $entry model]] users [dict get $entry principal]] { set groups [dict get $result $view] if {![dict exists $groups $key] && [dict size $groups] >= 512} { set omitted [dict get $result omittedGroupRecords] dict incr omitted $view dict set result omittedGroupRecords $omitted continue } set stats [expr {[dict exists $groups $key] ? [dict get $groups $key] : [::nsmcp::usageEmpty]}] ::nsmcp::usageAdd stats $entry dict set result $view $key $stats } } if {![eof $f] || $count >= 20000} { dict set result recordLimitReached true } } on error {message options} { dict incr result readErrors } finally { close $f } } return $resultrecord (scripted, public)
nsmcp::QuestionUsagerecord record turn timestamp
Build a usage journal entry for a finished turn.
- Parameters:
- record (required)
- Conversation metadata.
- turn (required)
- Finished turn metadata.
- timestamp (required)
- Journal timestamp in Unix seconds.
- Returns:
- A journal dictionary with usage state and bounded counters.
- Testcases:
- No testcase defined.
set tokens {} set usable false set complete false if {[dict exists $turn questionUsage]} { set usage [dict get $turn questionUsage] set usable [expr {[dict exists $usage scope] && [dict get $usage scope] eq "turn" && [dict exists $usage available] && [dict get $usage available]}] set complete $usable } elseif {[dict exists $turn usage scope] && [dict get $turn usage scope] eq "turn"} { set usage [dict get $turn usage] set usable true set complete [expr {[dict exists $usage complete] && [dict get $usage complete]}] } if {$usable} { set tokens [::nsmcp::QuestionBackend usageCounters $usage { inputTokens inputTokens outputTokens outputTokens totalTokens totalTokens cachedInputTokens cachedInputTokens reasoningOutputTokens reasoningOutputTokens }] } set state unavailable if {[dict size $tokens] > 0} { set state partial if {$complete && [dict get $turn status] eq "complete" && [dict exists $tokens inputTokens] && [dict exists $tokens outputTokens] && [dict exists $tokens totalTokens]} { set state complete } } set model [expr {[dict exists $turn model] && [dict get $turn model] ne "" ? [dict get $turn model] : "unknown"}] set result [dict create version 1 timestamp $timestamp state $state model $model tokens $tokens] foreach key {server backend principal} { dict set result $key [dict get $record $key] } foreach key {conversation id} { dict set result $key [dict get $turn $key] } return $resultrecordJson (scripted, public)
nsmcp::QuestionUsagerecordJson record
Encode a usage entry for the JSON Lines journal.
- Parameters:
- record (required)
- A usage journal entry.
- Returns:
- A serialized JSON object.
- Testcases:
- No testcase defined.
set fields {} dict for {key value} $record { if {$key eq "tokens"} { set counters {} dict for {name count} $value { lappend counters $name number $count } lappend fields $key object $counters } else { lappend fields $key [expr {$key in {version timestamp} ? "number" : "string"}] $value } } return [ns_json value -- [list {} object $fields]]
- Methods: All Methods Documented Methods Hide Methods
- Source: Display Source Hide Source
- Variables: Show Variables Hide Variables
![[i]](/resources/acs-subsite/ZoomIn16.gif)