Class ::nsmcp::QuestionUsage

::nsmcp::QuestionUsage[i] create ...

Defined in /usr/local/ns/tcl/nsmcp/question-usage.tcl

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::nsmcp::Object[i]
::nx::Class create ::nsmcp::QuestionUsage \
     -superclass ::nsmcp::Object

Methods (to be applied on the object)

  • read (scripted, public)

     nsmcp::QuestionUsage[i] read 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 $result
  • record (scripted, public)

     nsmcp::QuestionUsage[i] record 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 $result
  • recordJson (scripted, public)

     nsmcp::QuestionUsage[i] recordJson 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]]