freeharness 0.4.1 → 0.4.2

package/dist/cli/cost-quota.d.ts

@@ -0,0 +1,158 @@
+import type { ModelFamily, TokenGroup } from "./cost.js";
+export declare const QUOTA_WINDOWS: readonly ["five_hour", "seven_day"];
+export type QuotaWindow = (typeof QUOTA_WINDOWS)[number];
+export declare const DEFAULT_QUOTA_DAYS = 14;
+export interface WindowReading {
+    used_percentage: number;
+    resets_at: number;
+}
+/** One validated readings line; `ts` re-rendered from its parsed time so untrusted text never prints. */
+export interface QuotaReading {
+    ts: string;
+    time: number;
+    model: string | null;
+    five_hour: WindowReading | null;
+    seven_day: WindowReading | null;
+}
+/** The fit's input row: a percentage rise and the tokens per family recorded while it rose. */
+export interface QuotaInterval {
+    delta: number;
+    tokens: Partial<Record<ModelFamily, TokenGroup>>;
+}
+/** A rising interval as reported, traceable to its two readings. */
+export interface ReportedInterval extends QuotaInterval {
+    window: QuotaWindow;
+    resets_at: number;
+    start: {
+        ts: string;
+        model: string | null;
+        used_percentage: number;
+    };
+    end: {
+        ts: string;
+        model: string | null;
+        used_percentage: number;
+    };
+    tokens_per_pct: Partial<Record<ModelFamily, TokenGroup>>;
+}
+export type FamilyWeights = Partial<Record<ModelFamily, TokenGroup>>;
+export type FitResult = {
+    weights: FamilyWeights;
+    residual: number;
+    intervals: number;
+} | {
+    needed: number;
+    features: number;
+};
+export interface WindowReport {
+    calibrated: boolean;
+    interval_count: number;
+    features: number;
+    needed: number;
+    weights?: FamilyWeights;
+    residual?: number;
+    intervals: ReportedInterval[];
+}
+export interface QuotaReport {
+    days: number;
+    readings: {
+        files: string[];
+        lines: number;
+        malformed: number;
+        out_of_range: number;
+        skipped: string[];
+    };
+    transcripts: {
+        files: number;
+        oversize: number;
+        skipped: number;
+        messages: number;
+    };
+    windows: Record<QuotaWindow, WindowReport>;
+    note: string;
+    written: string | null;
+}
+/** quota-calibration.json: calibrated windows only. */
+export interface QuotaCalibration {
+    written: string;
+    days: number;
+    windows: Partial<Record<QuotaWindow, {
+        weights: FamilyWeights;
+        intervals: number;
+        residual: number;
+    }>>;
+}
+export declare function quotaDir(home?: string): string;
+export declare function quotaCalibrationPath(home?: string): string;
+/** A readings line in the sink schema, else null (malformed). */
+export declare function parseReading(raw: string): QuotaReading | null;
+/** Readings from the rotation then the live file, within the last `days`, in time order. */
+export declare function readReadings(home: string, days: number, now: Date): {
+    readings: QuotaReading[];
+    report: QuotaReport["readings"];
+};
+/**
+ * Rising intervals per window. A reading repeating the window's previous percentage and reset is
+ * no new reading for that window (the other window changed), so the interval starts at the first
+ * reading of the value and keeps the tokens spent while the meter had not yet moved.
+ */
+export declare function formIntervals(readings: QuotaReading[]): Record<QuotaWindow, Omit<ReportedInterval, "tokens" | "tokens_per_pct">[]>;
+interface Message {
+    time: number;
+    family: ModelFamily;
+    cache_read: number;
+    fresh: number;
+}
+/**
+ * Assistant messages with usage, one per `message.id` (else per file and line); the last line of
+ * an id wins, as in the cost tracker, since a streamed message repeats its usage on every line.
+ * A file last written before `since` cannot hold a message inside any interval and is not read.
+ */
+export declare function readMessages(home: string, since: number): {
+    messages: Message[];
+    report: QuotaReport["transcripts"];
+};
+/** Non-negative least squares, Lawson-Hanson (1974): min ||Ax - b|| subject to x >= 0. */
+export declare function nnls(A: number[][], b: number[]): number[];
+/**
+ * Fits percent per million tokens per family and group to the intervals' percentage rises.
+ * @param intervals Rows of (delta percent, tokens per family); tokens are raw counts.
+ * @returns The weights of every family with tokens, the interval count and the median absolute
+ *   residual in percentage points; or, below three intervals per feature, the count needed (a
+ *   window without tokens needs at least one family's two features).
+ */
+export declare function fitWeights(intervals: QuotaInterval[]): FitResult;
+/** Reads, forms intervals, sums tokens and fits each window; writes nothing. */
+export declare function quotaReport(home: string, days: number, now?: Date): QuotaReport;
+export declare function formatQuota(report: QuotaReport): string[];
+/** The calibration file's content: calibrated windows only, so a window without a fit never overwrites one. */
+export declare function calibrationOf(report: QuotaReport, now: Date): QuotaCalibration;
+/**
+ * Replaces the calibration file whole: a temporary file in the same directory, fsync, rename, so
+ * the routing report never reads a half-written file; an existing symlink or non-regular target
+ * is refused rather than replaced.
+ */
+export declare function writeCalibration(file: string, calibration: QuotaCalibration): void;
+/**
+ * Reads the calibration for the routing report's window estimate.
+ * @returns The shape-checked calibration; null without a warning when the file is absent; null
+ *   with one `quota calibration ignored: <reason>` line when it is unreadable or off-contract.
+ */
+export declare function readCalibration(file?: string): {
+    calibration: QuotaCalibration | null;
+    warning: string | null;
+};
+export interface CostQuotaOptions {
+    days?: number;
+    json?: boolean;
+    write?: boolean;
+    /** Tests and callers pin these; the CLI uses the user's HOME and the wall clock. */
+    home?: string;
+    now?: Date;
+}
+/**
+ * Runs the calibration and, with `write`, stores the calibrated windows.
+ * @returns The lines to print: the text report, or one JSON document with `--json`.
+ */
+export declare function costQuota(opts?: CostQuotaOptions): string[];
+export {};