@lumavox/client 0.0.0-stage → 0.2.0

package/dist/gen/types.gen.d.ts

@@ -0,0 +1,719 @@
+export type ClientOptions = {
+    baseUrl: `${string}://${string}` | (string & {});
+};
+export type ErrorResponse = {
+    error: ErrorInfo;
+};
+export type ErrorInfo = {
+    code: ErrorCode;
+    /**
+     * What went wrong, in words
+     */
+    message: string;
+    /**
+     * Echo of `X-Request-Id` — include it when reporting a problem
+     */
+    request_id: string;
+    /**
+     * Where the request failed validation; empty otherwise
+     */
+    issues: Array<ValidationIssue>;
+};
+/**
+ * What went wrong, for a client to switch on: one per HTTP status, except `waitlisted`, a 403 of its own. New codes may be added.
+ */
+export type ErrorCode = 'invalid_request' | 'unauthenticated' | 'insufficient_credits' | 'forbidden' | 'waitlisted' | 'not_found' | 'method_not_allowed' | 'conflict' | 'too_large' | 'validation_failed' | 'rate_limited' | 'internal' | 'provider_failed' | 'unavailable';
+export type ValidationIssue = {
+    location: 'body' | 'query' | 'path' | 'header';
+    /**
+     * The dotted path to the field (`voice_config.sample_rate`, `agent_ids.2`); `null` for the whole body.
+     */
+    field: string | null;
+    message: string;
+};
+/**
+ * A conversation, and a page of it. `messages` is the conversation so far, oldest first.
+ *
+ * **The most recent 50 by default**, not the whole transcript — a long conversation is not something a caller can be handed in one response. `messages.next_cursor` reaches the older ones: pass it as `cursor` on `GET /v1/agent/sessions/{session_id}`, whose `limit` raises or lowers the page, up to 200. It is null once the page reaches the beginning of the conversation.
+ *
+ * **`messages` is empty on a new conversation, including for an agent that has an opening line**. The opening line — generated or scripted — is the first turn on `/v1/agent/stream`, so it is written when a client connects rather than when the session is created. Opening a session makes no model call and no speech call of any kind.
+ */
+export type SessionDetail = {
+    agent_id: string;
+    created_at: string;
+    /**
+     * Who this conversation is with. Send it again to open another conversation with the same person, carrying their memory.
+     */
+    end_user_id: string;
+    id: string;
+    title: string | null;
+    turn_seq: number;
+    updated_at: string;
+    messages: MessagePage;
+    /**
+     * How this agent stands with this person, as the conversation opens.
+     *
+     * **Null when the agent has `relation_enabled` off**, which is not the same as "they have no history": the counters run for every pair regardless, and returning one for an agent that keeps none would show a relationship the model is not being told about.
+     *
+     * It belongs to the **person**, not the conversation, so it carries across every session with the same `end_user_id`. Here so that rendering it at conversation start needs no second call; `GET /v1/agent/relations` is still how you read it any other time, and the socket's `relation` event is how you learn it moved mid-turn — which is rare, and is the only time it changes.
+     */
+    relation: RelationInfo | null;
+    /**
+     * True when this is a conversation that already existed rather than a new one — see `resume` on the request.
+     *
+     * Worth branching on: a resumed session arrives with its `messages` already populated and its `turn_seq` past zero, so a client that assumed an empty transcript will render nothing until the next turn.
+     */
+    resumed: boolean;
+};
+export type MessagePage = {
+    data: Array<MessageInfo>;
+    /**
+     * Pass as `cursor` for the next page; `null` when this is the last.
+     */
+    next_cursor: string | null;
+};
+export type MessageInfo = {
+    content: string;
+    created_at: string;
+    id: string;
+    /**
+     * On a reply: what the agent looked up in its knowledge for it — each lookup's query, outcome and the entries it found, with their scores. Null when nothing was looked up.
+     */
+    knowledge: MessageKnowledge | null;
+    /**
+     * How the agent said it felt when it wrote this reply, when the agent reports moods. Null on user messages, on agents with emotion off, and on any reply where the model did not report a usable one.
+     */
+    mood: string | null;
+    /**
+     * How strongly, 0 to 1. Null when the model gave a label without a number — the label is the half it gets right.
+     */
+    mood_intensity: number | null;
+    role: 'user' | 'assistant';
+};
+export type MessageKnowledge = {
+    lookups: Array<KnowledgeLookupInfo>;
+    /**
+     * How the agent read its knowledge on this turn: `lookup` or `prompt`.
+     */
+    mode: 'lookup' | 'prompt';
+};
+export type KnowledgeLookupInfo = {
+    hits: Array<KnowledgeCitation>;
+    /**
+     * `found`, `none` (nothing relevant enough), or `failed` (the lookup itself could not be done).
+     */
+    outcome: 'found' | 'none' | 'failed';
+    query: string;
+    /**
+     * `first` — looked up before the reply; `tool` — the model asked for it.
+     */
+    via: 'first' | 'tool';
+};
+export type KnowledgeCitation = {
+    entry_id: string;
+    score: number;
+    title: string;
+};
+export type RelationInfo = {
+    agent_id: string;
+    /**
+     * The agent's name, so a list of these is readable without resolving ids.
+     */
+    agent_name: string | null;
+    /**
+     * Separate sessions, ever. A stronger signal of familiarity than `turns` — twenty short visits is a longer acquaintance than one long conversation.
+     */
+    conversations: number;
+    /**
+     * How much the agent has told **them** about itself, -1 to 1 — the asymmetric half of knowing each other, and the one nothing can count.
+     *
+     * Deliberately not part of `tier`: an agent can have opened up to somebody it has come to dislike, and folding this into affection would make that state unrepresentable.
+     */
+    disclosure: number;
+    /**
+     * The person, as `eu_...`.
+     */
+    end_user_id: string;
+    first_met_at: string | null;
+    last_seen_at: string | null;
+    /**
+     * One line the model wrote about them. **Replaced, not appended** — it is rendered into every future prompt for this pair, so it is bounded by design.
+     */
+    note: string | null;
+    /**
+     * How many times the model has recorded a change. Zero on a long history means the tool is not being called, which is the first thing to check when a relationship is not moving.
+     */
+    recorded: number;
+    /**
+     * The relationship as the model is told it — bands and counted phrases, never numbers. **Empty string** when there is nothing worth saying yet, in which case nothing about them is added to the prompt at all — which is a real state and not a missing value.
+     */
+    summary: string;
+    /**
+     * What the agent would call this relationship, and what it is actually told: **Despised, Disliked, Acquaintances, Friends** or **Good Friends**.
+     *
+     * Derived on every read from the axes below and never stored, so it cannot go stale. The rule is one sentence: *warmth and trust set the direction, familiarity sets how far it can go* — a first conversation caps at Acquaintances however well it went, and the ceiling rises as they talk. Dislike is not capped: an agent can take against somebody on one remark.
+     */
+    tier: 'Despised' | 'Disliked' | 'Acquaintances' | 'Friends' | 'Good Friends';
+    /**
+     * -1 to 1, on the same scale.
+     */
+    trust: number;
+    /**
+     * Turns exchanged, ever. Counted, not judged.
+     */
+    turns: number;
+    /**
+     * -1 to 1. Zero is indifference, which is where every relationship starts.
+     */
+    warmth: number;
+};
+export type SessionCreateRequest = {
+    /**
+     * Which agent this conversation is with.
+     */
+    agent_id: string;
+    /**
+     * Optional, and only ever the key's own end user — their id from `POST /v1/end-users`, or your own id for them.
+     *
+     * **A conversation is always the person the ephemeral key was minted for**: the key says who is talking, so this can only confirm it, and naming anybody else is a **403**. What the agent remembers about them — durable facts and the standing relationship — is theirs, and carries into every conversation with any of your agents.
+     *
+     * Set once, when the session opens. It cannot change afterwards.
+     */
+    end_user_id?: string | null;
+    /**
+     * Whether to continue this person's most recent conversation with this agent instead of starting a new one.
+     *
+     * **Unset is the useful default**: it resumes when this person has a conversation with this agent from the last 7 days to continue, and starts a new one otherwise. That matches what 'open a conversation with this person' usually means, and it stops an integration that opens a session per page load from scattering somebody's history across a dozen fragments.
+     *
+     * `false` always starts a new conversation — this is what a 'new chat' button should send. `true` is the same as leaving it unset; it exists so the intent can be stated rather than implied.
+     *
+     * Nothing is lost by starting fresh: durable facts and the standing relationship belong to the *person*, not the conversation, and are carried into every new one.
+     *
+     * The response's `resumed` says which happened.
+     */
+    resume?: boolean | null;
+    /**
+     * Optional label.
+     */
+    title?: string | null;
+};
+export type SessionPage = {
+    data: Array<SessionInfo>;
+    /**
+     * Pass as `cursor` for the next page; `null` when this is the last.
+     */
+    next_cursor: string | null;
+};
+export type SessionInfo = {
+    agent_id: string;
+    created_at: string;
+    /**
+     * Who this conversation is with. Send it again to open another conversation with the same person, carrying their memory.
+     */
+    end_user_id: string;
+    id: string;
+    title: string | null;
+    turn_seq: number;
+    updated_at: string;
+};
+export type CompactionInfo = {
+    /**
+     * The last message this summary covers. Anything after it is still sent to the model verbatim.
+     */
+    after_seq: number;
+    /**
+     * Durable facts written to long-term memory by this call. Zero when extraction was not asked for, or when there was nothing worth keeping.
+     */
+    facts_stored: number;
+    input_tokens: number | null;
+    /**
+     * What produced the summary.
+     */
+    model: string | null;
+    output_tokens: number | null;
+    session_id: string;
+    /**
+     * What the next turn will start from.
+     */
+    summary: string;
+    /**
+     * `manual` (a client asked), `automatic` (a turn reached the agent's threshold) or `idle` (the conversation went quiet and its facts were extracted).
+     */
+    trigger: 'manual' | 'automatic' | 'idle';
+};
+export type CompactRequest = {
+    /**
+     * Whether to also extract durable facts about the end user, in the same model call.
+     *
+     * Unset uses the agent's own setting.
+     */
+    extract_facts?: boolean | null;
+};
+export type FactPage = {
+    data: Array<FactInfo>;
+    /**
+     * Pass as `cursor` for the next page; `null` when this is the last.
+     */
+    next_cursor: string | null;
+};
+export type FactInfo = {
+    /**
+     * Which agent was being talked to when this was learned.
+     */
+    agent_id: string | null;
+    created_at: string;
+    id: string;
+    text: string;
+    /**
+     * A fact is never edited, only learned or forgotten: the same as `created_at`.
+     */
+    updated_at: string;
+};
+export type FactsDeleted = {
+    /**
+     * How many stored facts were deleted.
+     */
+    facts_deleted: number;
+};
+export type RelationPage = {
+    data: Array<RelationInfo>;
+    /**
+     * Pass as `cursor` for the next page; `null` when this is the last.
+     */
+    next_cursor: string | null;
+};
+export type ListSessionsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * How many to answer, 1 to 200.
+         */
+        limit?: number;
+        /**
+         * The `next_cursor` of the page before.
+         */
+        cursor?: string;
+    };
+    url: '/v1/agent/sessions';
+};
+export type ListSessionsErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type ListSessionsError = ListSessionsErrors[keyof ListSessionsErrors];
+export type ListSessionsResponses = {
+    /**
+     * One page of conversations, most recent first
+     */
+    200: SessionPage;
+};
+export type ListSessionsResponse = ListSessionsResponses[keyof ListSessionsResponses];
+export type CreateSessionData = {
+    body: SessionCreateRequest;
+    path?: never;
+    query?: never;
+    url: '/v1/agent/sessions';
+};
+export type CreateSessionErrors = {
+    /**
+     * The request could not be read: malformed JSON
+     */
+    400: ErrorResponse;
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key's scopes do not cover agents, or it is for another agent or person
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown agent id
+     */
+    404: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type CreateSessionError = CreateSessionErrors[keyof CreateSessionErrors];
+export type CreateSessionResponses = {
+    /**
+     * The conversation — new or continued, per `resumed`
+     */
+    201: SessionDetail;
+};
+export type CreateSessionResponse = CreateSessionResponses[keyof CreateSessionResponses];
+export type DeleteSessionData = {
+    body?: never;
+    path: {
+        session_id: string;
+    };
+    query?: never;
+    url: '/v1/agent/sessions/{session_id}';
+};
+export type DeleteSessionErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown session id
+     */
+    404: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type DeleteSessionError = DeleteSessionErrors[keyof DeleteSessionErrors];
+export type DeleteSessionResponses = {
+    /**
+     * The session and its messages are gone
+     */
+    204: void;
+};
+export type DeleteSessionResponse = DeleteSessionResponses[keyof DeleteSessionResponses];
+export type GetSessionData = {
+    body?: never;
+    path: {
+        session_id: string;
+    };
+    query?: {
+        /**
+         * How many messages, counting back from the newest, 1 to 200. The page itself is oldest first.
+         */
+        limit?: number;
+        /**
+         * `messages.next_cursor` of the page before, for the older messages.
+         */
+        cursor?: string;
+    };
+    url: '/v1/agent/sessions/{session_id}';
+};
+export type GetSessionErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown session id
+     */
+    404: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type GetSessionError = GetSessionErrors[keyof GetSessionErrors];
+export type GetSessionResponses = {
+    /**
+     * The conversation and one page of its messages
+     */
+    200: SessionDetail;
+};
+export type GetSessionResponse = GetSessionResponses[keyof GetSessionResponses];
+export type CompactSessionData = {
+    body: CompactRequest;
+    path: {
+        session_id: string;
+    };
+    query?: never;
+    url: '/v1/agent/sessions/{session_id}/compact';
+};
+export type CompactSessionErrors = {
+    /**
+     * The request could not be read: malformed JSON
+     */
+    400: ErrorResponse;
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown session id
+     */
+    404: ErrorResponse;
+    /**
+     * Another compaction of this conversation finished first
+     */
+    409: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+    /**
+     * The model provider failed or timed out
+     */
+    502: ErrorResponse;
+    /**
+     * The model provider is not configured
+     */
+    503: ErrorResponse;
+};
+export type CompactSessionError = CompactSessionErrors[keyof CompactSessionErrors];
+export type CompactSessionResponses = {
+    /**
+     * The summary that replaced the turns it covers
+     */
+    200: CompactionInfo;
+};
+export type CompactSessionResponse = CompactSessionResponses[keyof CompactSessionResponses];
+export type ExtractSessionFactsData = {
+    body?: never;
+    path: {
+        session_id: string;
+    };
+    query?: never;
+    url: '/v1/agent/sessions/{session_id}/extract';
+};
+export type ExtractSessionFactsErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown session id
+     */
+    404: ErrorResponse;
+    /**
+     * Another compaction of this conversation finished first
+     */
+    409: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+    /**
+     * The model provider failed or timed out
+     */
+    502: ErrorResponse;
+    /**
+     * The model provider is not configured
+     */
+    503: ErrorResponse;
+};
+export type ExtractSessionFactsError = ExtractSessionFactsErrors[keyof ExtractSessionFactsErrors];
+export type ExtractSessionFactsResponses = {
+    /**
+     * The facts pulled out of the conversation and stored
+     */
+    200: CompactionInfo;
+};
+export type ExtractSessionFactsResponse = ExtractSessionFactsResponses[keyof ExtractSessionFactsResponses];
+export type DeleteAllFactsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Optional, and only ever the key's own end user — their `eu_...` id or your own id for them. Anybody else is a 403.
+         */
+        end_user_id?: string;
+    };
+    url: '/v1/agent/facts';
+};
+export type DeleteAllFactsErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type DeleteAllFactsError = DeleteAllFactsErrors[keyof DeleteAllFactsErrors];
+export type DeleteAllFactsResponses = {
+    /**
+     * How many stored facts were deleted
+     */
+    200: FactsDeleted;
+};
+export type DeleteAllFactsResponse = DeleteAllFactsResponses[keyof DeleteAllFactsResponses];
+export type ListFactsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Optional, and only ever the key's own end user — their `eu_...` id or your own id for them. Anybody else is a 403.
+         */
+        end_user_id?: string;
+    };
+    url: '/v1/agent/facts';
+};
+export type ListFactsErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type ListFactsError = ListFactsErrors[keyof ListFactsErrors];
+export type ListFactsResponses = {
+    /**
+     * What the platform remembers about this end user
+     */
+    200: FactPage;
+};
+export type ListFactsResponse = ListFactsResponses[keyof ListFactsResponses];
+export type DeleteFactData = {
+    body?: never;
+    path: {
+        fact_id: string;
+    };
+    query?: never;
+    url: '/v1/agent/facts/{fact_id}';
+};
+export type DeleteFactErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown fact id
+     */
+    404: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type DeleteFactError = DeleteFactErrors[keyof DeleteFactErrors];
+export type DeleteFactResponses = {
+    /**
+     * The fact is gone
+     */
+    204: void;
+};
+export type DeleteFactResponse = DeleteFactResponses[keyof DeleteFactResponses];
+export type ListRelationsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Only this agent's relationship.
+         */
+        agent_id?: string;
+        /**
+         * Optional, and only ever the key's own end user — their `eu_...` id or your own id for them. Anybody else is a 403.
+         */
+        end_user_id?: string;
+        /**
+         * How many to answer, 1 to 200.
+         */
+        limit?: number;
+        /**
+         * The `next_cursor` of the page before.
+         */
+        cursor?: string;
+    };
+    url: '/v1/agent/relations';
+};
+export type ListRelationsErrors = {
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown agent id
+     */
+    404: ErrorResponse;
+    /**
+     * The request failed validation
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type ListRelationsError = ListRelationsErrors[keyof ListRelationsErrors];
+export type ListRelationsResponses = {
+    /**
+     * How each agent feels about the person, most recent first
+     */
+    200: RelationPage;
+};
+export type ListRelationsResponse = ListRelationsResponses[keyof ListRelationsResponses];