@humeai/audio-decisions 0.0.1 → 0.1.0

package/dist/esm/api/types/ErrorCode.d.mts

@@ -0,0 +1,58 @@
+/**
+ * What went wrong, grouped by the HTTP status it is returned with.
+ *
+ * **`400 Bad Request`**: something in the request needs correcting.
+ *
+ * - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`.
+ * - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options.
+ * - `audio_decode_failed`: the audio file could not be decoded.
+ * - `audio_format_unsupported`: the audio file is not MP3 or WAV.
+ * - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000.
+ * - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000.
+ * - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only.
+ *
+ * **`402 Payment Required`**
+ *
+ * - `payment_required`: the organization has no payment method on file, or has an unpaid invoice.
+ *
+ * **`403 Forbidden`**
+ *
+ * - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it.
+ *
+ * **`404 Not Found`**
+ *
+ * - `not_found`: no run with this ID exists in your organization.
+ *
+ * **`413 Content Too Large`**
+ *
+ * - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together.
+ *
+ * **`415 Unsupported Media Type`**
+ *
+ * - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request.
+ *
+ * **`500 Internal Server Error`**
+ *
+ * - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`.
+ *
+ * **`503 Service Unavailable`**
+ *
+ * - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
+ */
+export declare const ErrorCode: {
+    readonly MessageInvalid: "message_invalid";
+    readonly QuestionInvalid: "question_invalid";
+    readonly AudioDecodeFailed: "audio_decode_failed";
+    readonly AudioFormatUnsupported: "audio_format_unsupported";
+    readonly AudioTooShort: "audio_too_short";
+    readonly AudioTooLong: "audio_too_long";
+    readonly InvalidRequest: "invalid_request";
+    readonly PaymentRequired: "payment_required";
+    readonly Forbidden: "forbidden";
+    readonly NotFound: "not_found";
+    readonly PayloadTooLarge: "payload_too_large";
+    readonly UnsupportedMediaType: "unsupported_media_type";
+    readonly InternalError: "internal_error";
+    readonly ServerBusy: "server_busy";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];

package/dist/esm/api/types/ErrorCode.mjs

@@ -0,0 +1,58 @@
+// This file was auto-generated by Fern from our API Definition.
+/**
+ * What went wrong, grouped by the HTTP status it is returned with.
+ *
+ * **`400 Bad Request`**: something in the request needs correcting.
+ *
+ * - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`.
+ * - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options.
+ * - `audio_decode_failed`: the audio file could not be decoded.
+ * - `audio_format_unsupported`: the audio file is not MP3 or WAV.
+ * - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000.
+ * - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000.
+ * - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only.
+ *
+ * **`402 Payment Required`**
+ *
+ * - `payment_required`: the organization has no payment method on file, or has an unpaid invoice.
+ *
+ * **`403 Forbidden`**
+ *
+ * - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it.
+ *
+ * **`404 Not Found`**
+ *
+ * - `not_found`: no run with this ID exists in your organization.
+ *
+ * **`413 Content Too Large`**
+ *
+ * - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together.
+ *
+ * **`415 Unsupported Media Type`**
+ *
+ * - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request.
+ *
+ * **`500 Internal Server Error`**
+ *
+ * - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`.
+ *
+ * **`503 Service Unavailable`**
+ *
+ * - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
+ */
+export const ErrorCode = {
+    MessageInvalid: "message_invalid",
+    QuestionInvalid: "question_invalid",
+    AudioDecodeFailed: "audio_decode_failed",
+    AudioFormatUnsupported: "audio_format_unsupported",
+    AudioTooShort: "audio_too_short",
+    AudioTooLong: "audio_too_long",
+    InvalidRequest: "invalid_request",
+    PaymentRequired: "payment_required",
+    Forbidden: "forbidden",
+    NotFound: "not_found",
+    PayloadTooLarge: "payload_too_large",
+    UnsupportedMediaType: "unsupported_media_type",
+    InternalError: "internal_error",
+    ServerBusy: "server_busy",
+};

package/dist/esm/api/types/ErrorType.d.mts

@@ -0,0 +1,5 @@
+/** The type of the object. Always `error`. */
+export declare const ErrorType: {
+    readonly Error: "error";
+};
+export type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];

package/dist/esm/api/types/ErrorType.mjs

@@ -0,0 +1,5 @@
+// This file was auto-generated by Fern from our API Definition.
+/** The type of the object. Always `error`. */
+export const ErrorType = {
+    Error: "error",
+};

package/dist/esm/api/types/Error_.d.mts

@@ -0,0 +1,15 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * The body of every error response the service answers. The HTTP status says how the request failed and `code` says why.
+ */
+export interface Error_ {
+    /** The type of the object. Always `error`. */
+    type: Decisions.ErrorType;
+    code: Decisions.ErrorCode;
+    /** A description of the problem for a person. Its wording may change, so switch on `code`. */
+    message: string;
+    /** Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request. */
+    param?: string;
+    /** The ID of the request that failed. Quote it when contacting support. */
+    requestId: string;
+}

package/dist/esm/api/types/Error_.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/GatewayError.d.mts

@@ -0,0 +1,9 @@
+/**
+ * The body of an error that Hume's API gateway answers before the request reaches the service: a `401` for a missing or invalid credential, a `429` for a rate limit, and a `404` for a path or HTTP method the API does not serve. It carries neither `type` nor `code`.
+ */
+export interface GatewayError {
+    /** A description of the problem for a person. */
+    message: string;
+    /** The ID of the request. A `401` carries it only when an API key was rejected, and a `429` never does. */
+    requestId?: string;
+}

package/dist/esm/api/types/GatewayError.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/InputTokensResponse.d.mts

@@ -0,0 +1,7 @@
+/**
+ * The estimated number of input tokens for a decisions request.
+ */
+export interface InputTokensResponse {
+    /** The estimated number of input tokens for the request: what `POST /v0/decisions/file` would bill it, as its response's `received.input_tokens`. The estimate counts the audio from its duration rather than the file, so it can differ slightly. */
+    estimatedInputTokens: number;
+}

package/dist/esm/api/types/InputTokensResponse.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/Moment.d.mts

@@ -0,0 +1,11 @@
+/**
+ * A moment where the described event may occur.
+ */
+export interface Moment {
+    /** Where the moment begins, in milliseconds from the start of the audio file. */
+    audioStartMs: number;
+    /** Where the moment ends, in milliseconds from the start of the audio file. */
+    audioEndMs: number;
+    /** The probability that the event occurs in the moment. */
+    probability: number;
+}

package/dist/esm/api/types/Moment.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/MomentAnswer.d.mts

@@ -0,0 +1,8 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * The answer to a `moment` question.
+ */
+export interface MomentAnswer {
+    /** The moments where the described event may occur, in order of `audio_start_ms`. Overlapping candidates are merged. An empty array means the event was not found. */
+    moments: Decisions.Moment[];
+}

package/dist/esm/api/types/MomentAnswer.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/MomentQuestion.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Asks when an event occurs in the audio.
+ */
+export interface MomentQuestion {
+    /** The question, written in natural language. */
+    instructions: string;
+}

package/dist/esm/api/types/MomentQuestion.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/NoulAnswer.d.mts

@@ -0,0 +1,7 @@
+/**
+ * The answer to a `noul` question.
+ */
+export interface NoulAnswer {
+    /** The estimated share of human raters who would answer yes, from 0 to 1. A value near 0.5 means raters would split, not that the model is unsure. */
+    noul: number;
+}

package/dist/esm/api/types/NoulAnswer.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/NoulCriteria.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Guidance on what counts as a yes or a no answer. The model reads it along with the question.
+ */
+export interface NoulCriteria {
+    /** What counts as a yes answer. */
+    true?: string;
+    /** What counts as a no answer. */
+    false?: string;
+}

package/dist/esm/api/types/NoulCriteria.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/NoulQuestion.d.mts

@@ -0,0 +1,9 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * Asks a yes or no question. Optionally, say what counts as yes or no in `criteria`.
+ */
+export interface NoulQuestion {
+    /** The question, written in natural language. */
+    instructions: string;
+    criteria?: Decisions.NoulCriteria;
+}

package/dist/esm/api/types/NoulQuestion.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/Question.d.mts

@@ -0,0 +1,19 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * A question. `type` names its primitive, which determines the question's options and the structure of its answer.
+ */
+export type Question = Decisions.Question.Noul | Decisions.Question.Choice | Decisions.Question.Score | Decisions.Question.Moment;
+export declare namespace Question {
+    interface Noul extends Decisions.NoulQuestion {
+        type: "noul";
+    }
+    interface Choice extends Decisions.ChoiceQuestion {
+        type: "choice";
+    }
+    interface Score extends Decisions.ScoreQuestion {
+        type: "score";
+    }
+    interface Moment extends Decisions.MomentQuestion {
+        type: "moment";
+    }
+}

package/dist/esm/api/types/Question.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/Questions.d.mts

@@ -0,0 +1,7 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * The questions to answer: at most 20 `noul`, `choice` and `score` questions together, and at most 5 `moment` questions. Each key is a question ID you choose, such as `agent_tone`, and can be any non-empty string of up to 256 characters. The response returns each answer under the same ID.
+ */
+export type Questions = {
+    [key: string]: Decisions.Question;
+};

package/dist/esm/api/types/Questions.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/Received.d.mts

@@ -0,0 +1,7 @@
+/**
+ * What the model received for a decisions request, which is what the request is billed.
+ */
+export interface Received {
+    /** The input tokens this request is billed. `POST /v0/decisions/file/input_tokens` estimates them before a request is sent. */
+    inputTokens: number;
+}

package/dist/esm/api/types/Received.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/Run.d.mts

@@ -0,0 +1,18 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * One model inference in full, including the request it evaluated.
+ */
+export interface Run {
+    /** The run's ID: the `run_id` of a decisions response. */
+    runId: string;
+    /** The ID of the Hume user who made the run. */
+    userId: string;
+    status: Decisions.RunStatus;
+    /** When the run started. */
+    startedAt: Date;
+    /** When the run ended. */
+    endedAt: Date;
+    received: Decisions.RunReceived;
+    /** The `request` part the run evaluated: its `context` and `questions`, as sent. */
+    request: Decisions.DecisionsRequest;
+}

package/dist/esm/api/types/Run.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/RunReceived.d.mts

@@ -0,0 +1,9 @@
+/**
+ * The `file` part a run received, and the input tokens it was billed.
+ */
+export interface RunReceived {
+    /** The size of the `file` part as sent, in bytes. */
+    fileBytes: number;
+    /** The input tokens the run was billed: the decisions response's `received.input_tokens`. Absent for a run that was not billed. */
+    inputTokens?: number;
+}

package/dist/esm/api/types/RunReceived.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/RunStatus.d.mts

@@ -0,0 +1,6 @@
+/** How a run ended: `ended` if it returned answers, and `errored` if it returned none because inference failed or the client closed the connection first. */
+export declare const RunStatus: {
+    readonly Ended: "ended";
+    readonly Errored: "errored";
+};
+export type RunStatus = (typeof RunStatus)[keyof typeof RunStatus];

package/dist/esm/api/types/RunStatus.mjs

@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+/** How a run ended: `ended` if it returned answers, and `errored` if it returned none because inference failed or the client closed the connection first. */
+export const RunStatus = {
+    Ended: "ended",
+    Errored: "errored",
+};

package/dist/esm/api/types/RunSummary.d.mts

@@ -0,0 +1,16 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * One model inference, as the list returns it.
+ */
+export interface RunSummary {
+    /** The run's ID: the `run_id` of a decisions response. */
+    runId: string;
+    /** The ID of the Hume user who made the run. */
+    userId: string;
+    status: Decisions.RunStatus;
+    /** When the run started. */
+    startedAt: Date;
+    /** When the run ended. */
+    endedAt: Date;
+    received: Decisions.RunReceived;
+}

package/dist/esm/api/types/RunSummary.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/RunsPage.d.mts

@@ -0,0 +1,10 @@
+import type * as Decisions from "../index.mjs";
+/**
+ * One page of runs.
+ */
+export interface RunsPage {
+    /** The runs, newest first. */
+    runs: Decisions.RunSummary[];
+    /** Absent on the last page. Pass it back as `cursor` for the next one. */
+    nextCursor?: string;
+}

package/dist/esm/api/types/RunsPage.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/ScoreAnswer.d.mts

@@ -0,0 +1,13 @@
+/**
+ * The answer to a `score` question.
+ */
+export interface ScoreAnswer {
+    /** The probability-weighted mean of the level indices, from 0 to the index of the highest level. */
+    score: number;
+    /** How much human raters would agree, from 0 when the probabilities are at least as spread out as a uniform distribution to 1 when all probability is on one level. */
+    confidence: number;
+    /** The probability of each level, keyed by level index as a string. Each estimates the share of human raters who would choose the level, and together they sum to 1, within rounding. */
+    probabilities: Record<string, number>;
+    /** The text of each level, as given in the question's `criteria`, keyed by level index like `probabilities`, so a score can be read without relying on the key order of a JSON object. */
+    legend: Record<string, string>;
+}

package/dist/esm/api/types/ScoreAnswer.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/ScoreQuestion.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Asks where the audio falls on a scale of two or more ordered levels.
+ */
+export interface ScoreQuestion {
+    /** The question, written in natural language. */
+    instructions: string;
+    /** The levels, ordered from lowest to highest and numbered from 0. The model reads each level's text, and the answer's `legend` returns it. A question with fewer than two levels or more than 10, or with duplicate levels, is rejected with `question_invalid`. */
+    criteria: string[];
+}

package/dist/esm/api/types/ScoreQuestion.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/index.d.mts

@@ -0,0 +1,28 @@
+export * from "./Answer.mjs";
+export * from "./Answers.mjs";
+export * from "./ChoiceAnswer.mjs";
+export * from "./ChoiceQuestion.mjs";
+export * from "./Criterion.mjs";
+export * from "./DecisionsRequest.mjs";
+export * from "./DecisionsResponse.mjs";
+export * from "./Error_.mjs";
+export * from "./ErrorCode.mjs";
+export * from "./ErrorType.mjs";
+export * from "./GatewayError.mjs";
+export * from "./InputTokensResponse.mjs";
+export * from "./Moment.mjs";
+export * from "./MomentAnswer.mjs";
+export * from "./MomentQuestion.mjs";
+export * from "./NoulAnswer.mjs";
+export * from "./NoulCriteria.mjs";
+export * from "./NoulQuestion.mjs";
+export * from "./Question.mjs";
+export * from "./Questions.mjs";
+export * from "./Received.mjs";
+export * from "./Run.mjs";
+export * from "./RunReceived.mjs";
+export * from "./RunStatus.mjs";
+export * from "./RunSummary.mjs";
+export * from "./RunsPage.mjs";
+export * from "./ScoreAnswer.mjs";
+export * from "./ScoreQuestion.mjs";

package/dist/esm/api/types/index.mjs

@@ -0,0 +1,28 @@
+export * from "./Answer.mjs";
+export * from "./Answers.mjs";
+export * from "./ChoiceAnswer.mjs";
+export * from "./ChoiceQuestion.mjs";
+export * from "./Criterion.mjs";
+export * from "./DecisionsRequest.mjs";
+export * from "./DecisionsResponse.mjs";
+export * from "./Error_.mjs";
+export * from "./ErrorCode.mjs";
+export * from "./ErrorType.mjs";
+export * from "./GatewayError.mjs";
+export * from "./InputTokensResponse.mjs";
+export * from "./Moment.mjs";
+export * from "./MomentAnswer.mjs";
+export * from "./MomentQuestion.mjs";
+export * from "./NoulAnswer.mjs";
+export * from "./NoulCriteria.mjs";
+export * from "./NoulQuestion.mjs";
+export * from "./Question.mjs";
+export * from "./Questions.mjs";
+export * from "./Received.mjs";
+export * from "./Run.mjs";
+export * from "./RunReceived.mjs";
+export * from "./RunStatus.mjs";
+export * from "./RunSummary.mjs";
+export * from "./RunsPage.mjs";
+export * from "./ScoreAnswer.mjs";
+export * from "./ScoreQuestion.mjs";

package/dist/esm/audio-helpers/bytes.d.mts

@@ -0,0 +1,6 @@
+export declare function dataView(data: Uint8Array): DataView;
+/** Whether the bytes at `offset` spell `text`, which is ASCII. False when they run past the end. */
+export declare function hasBytes(data: Uint8Array, offset: number, text: string): boolean;
+export declare function writeAscii(data: Uint8Array, offset: number, text: string): void;
+/** The big-endian integer in the 4 bytes from `offset`, or undefined when they do not all lie within `data`. */
+export declare function uint32BE(data: Uint8Array, offset: number): number | undefined;

package/dist/esm/audio-helpers/bytes.mjs

@@ -0,0 +1,32 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+export function dataView(data) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+}
+/** Whether the bytes at `offset` spell `text`, which is ASCII. False when they run past the end. */
+export function hasBytes(data, offset, text) {
+    if (offset < 0 || offset + text.length > data.length) {
+        return false;
+    }
+    for (let index = 0; index < text.length; index++) {
+        if (data[offset + index] !== text.charCodeAt(index)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function writeAscii(data, offset, text) {
+    for (let index = 0; index < text.length; index++) {
+        data[offset + index] = text.charCodeAt(index);
+    }
+}
+/** The big-endian integer in the 4 bytes from `offset`, or undefined when they do not all lie within `data`. */
+export function uint32BE(data, offset) {
+    if (offset < 0 || offset + 4 > data.length) {
+        return undefined;
+    }
+    let value = 0;
+    for (let index = offset; index < offset + 4; index++) {
+        value = value * 256 + data[index];
+    }
+    return value;
+}

package/dist/esm/audio-helpers/checks.d.mts

@@ -0,0 +1,2 @@
+export declare function checkInteger(name: string, value: unknown): number;
+export declare function checkChoice<T>(name: string, value: unknown, choices: readonly T[]): T;

package/dist/esm/audio-helpers/checks.mjs

@@ -0,0 +1,21 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+export function checkInteger(name, value) {
+    // Arithmetic on larger numbers is not exact, and the bounds checked later assume it is.
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new TypeError(`${name} must be a safe integer, got ${describe(value)}.`);
+    }
+    return value;
+}
+export function checkChoice(name, value, choices) {
+    if (!isOneOf(value, choices)) {
+        const quoted = choices.map(describe);
+        throw new RangeError(`${name} must be ${quoted.slice(0, -1).join(", ")} or ${quoted[quoted.length - 1]}, got ${describe(value)}.`);
+    }
+    return value;
+}
+function isOneOf(value, choices) {
+    return choices.includes(value);
+}
+function describe(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}