Class ::nsmcp::QuestionUsage (public)

 ::nx::Class ::nsmcp::QuestionUsage[i]

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

Testcases:
No testcase defined.
Source code:
    :public object method read {path server} {
        #
        # Summarize retained token usage for a virtual server.
        #
        # @param path Path to the current JSON Lines journal.
        # @param server Virtual server whose records are included.
        # @return Usage totals, grouped counts and coverage diagnostics.
        #
        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
    }

    :public object method recordJson {record} {
        #
        # Encode a usage entry for the JSON Lines journal.
        #
        # @param record A usage journal entry.
        # @return A serialized JSON object.
        #
        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]]
    }

    :public object method record {record turn timestamp} {
        #
        # Build a usage journal entry for a finished turn.
        #
        # @param record Conversation metadata.
        # @param turn Finished turn metadata.
        # @param timestamp Journal timestamp in Unix seconds.
        # @return A journal dictionary with usage state and bounded counters.
        #
        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
    }
XQL Not present:
Generic, PostgreSQL, Oracle
[ hide source ] | [ make this the default ]
Show another procedure: