@happyvertical/smrt-planner 0.57.6 → 0.57.7

package/dist/reports/intent.d.ts

@@ -0,0 +1,106 @@
+/**
+ * A report request as the assistant's model states it, and the spec the
+ * planner's code builds from it (#4100).
+ *
+ * The on-device model is small, so it never writes a `RuntimeReportSpec`. It
+ * names an intent in its structured-JSON answer (which records, what to
+ * measure, how to group, which period); this module resolves the names
+ * against the source's fields, fills the gaps a person leaves ("a summary" is
+ * a count and the main amount; a period uses the business date) and builds the
+ * spec, which `parseRuntimeReportSpec` then validates. Anything it cannot
+ * resolve becomes a follow-up question, never a guess.
+ */
+import { RuntimeReportError, type RuntimeReportSpec } from '@happyvertical/smrt-reports/spec';
+import type { PlannerReportSource } from './sources.ts';
+export declare const REPORT_PERIODS: readonly ["today", "yesterday", "this_week", "last_week", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "all_time"];
+export type ReportPeriod = (typeof REPORT_PERIODS)[number];
+export declare const REPORT_BUCKETS: readonly ["minute", "hour", "day", "week", "month", "quarter", "year"];
+export type ReportBucket = (typeof REPORT_BUCKETS)[number];
+export declare const REPORT_MEASURES: readonly ["count", "sum", "avg", "min", "max"];
+export type ReportMeasure = (typeof REPORT_MEASURES)[number];
+export declare const REPORT_FILTER_OPS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "contains"];
+export type ReportFilterOp = (typeof REPORT_FILTER_OPS)[number];
+/** What the model says it wants. Everything but `source` is optional. */
+export interface ReportIntent {
+    source: string;
+    measures?: {
+        fn: ReportMeasure;
+        field?: string;
+    }[];
+    /** A field to group by (a status, a customer). */
+    groupBy?: string;
+    /** Group by time on the date field instead (or as well). */
+    bucket?: ReportBucket;
+    period?: ReportPeriod;
+    /** A period in words ("last 90 days", "Q3", "December"); code resolves it. */
+    range?: string;
+    /** The date a period and a time grouping use; defaults to the source's. */
+    dateField?: string;
+    filters?: {
+        field: string;
+        op: ReportFilterOp;
+        value: string | number | boolean;
+    }[];
+    title?: string;
+    /** Parts the model stated that could not be read; a follow-up asks about them. */
+    unreadable?: string[];
+}
+/** The JSON Schema of the `report` property of one assistant turn. */
+export declare function reportIntentSchema(sourceIds: readonly string[]): Record<string, unknown>;
+/**
+ * Read the model's `report` property. Structure only: names are kept as the
+ * model wrote them and resolved by `specFromIntent`. A `source` outside the
+ * offered ids is kept too, so the follow-up can say what is offered.
+ */
+export declare function parseReportIntent(value: unknown): ReportIntent | null;
+/** One option of a follow-up: picking it merges `apply` into the intent. */
+export interface ReportFollowUpOption {
+    value: string;
+    label: string;
+    /** Extra words a typed answer may use ("monthly", "date"). */
+    keywords?: string[];
+    apply: Partial<ReportIntent>;
+}
+/**
+ * A follow-up question built by code from the source descriptor (its human
+ * dimensions, time fields and amounts), never from a model's prose. The
+ * transport renders it as a form and merges the pick into the pending intent.
+ */
+export interface ReportFollowUp {
+    /** The intent slot it fills: `groupBy`, `source`, `measure`, `dateField`, `period`. */
+    field: string;
+    /** The form field's label ("Group by"). */
+    label: string;
+    /** The question ("Group Invoices by…"). */
+    prompt: string;
+    options: ReportFollowUpOption[];
+    /** The sensible pick, preselected and used after a second miss. */
+    default: string;
+}
+export type IntentResult = {
+    ok: true;
+    spec: RuntimeReportSpec;
+    source: PlannerReportSource;
+} | {
+    ok: false;
+    question: string;
+    followUp?: ReportFollowUp;
+};
+/** "Which records should the report cover?", with the sources as options. */
+export declare function sourceFollowUp(sources: readonly PlannerReportSource[]): ReportFollowUp | null;
+/** The question for records no source offers. */
+export declare function whichSourceQuestion(sources: readonly PlannerReportSource[]): string;
+/**
+ * Build a spec from an intent over the offered sources. `now` is the clock a
+ * period is relative to (the planner passes its sample-data clock); `text` is
+ * what the person said, whose time words ("by month", "last quarter", "over
+ * time") fill what the model left out. Anything else unresolved is a
+ * follow-up built from the source descriptor.
+ */
+export declare function specFromIntent(intent: ReportIntent, sources: readonly PlannerReportSource[], now: Date, text?: string): IntentResult;
+/**
+ * A follow-up for a spec the runner rejected (a filter value of the wrong
+ * type, an operator a field does not take): what to change, as a question.
+ */
+export declare function questionForError(error: RuntimeReportError, source: PlannerReportSource): string;
+//# sourceMappingURL=intent.d.ts.map

package/dist/reports/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../src/lib/reports/intent.ts"],"names":[],"mappings":"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"}