@popcomputer/structured-chat 0.1.0

package/dist/core/collect-stage.d.ts

@@ -0,0 +1,203 @@
+import { Effect, Schema } from "effect";
+import type * as ParseResult from "effect/ParseResult";
+import type { AnswerDefinition, AnswerDefinitionContract, AnswerMode } from "./answer.js";
+import { ChatModelUnavailable, StructuredChatModel, type UnsupportedModelToolSchema, type UntrustedMessage } from "./model.js";
+import type { ModelGuardError, ModelGuardRequirements, ModelGuardTuple } from "./model-guard.js";
+import { InvalidToolCall, type InvalidToolProjection } from "./tool.js";
+import type { AdaptiveChoiceQuestion, ChoiceQuestion, QuestionChoice } from "./question.js";
+import { type StructuredDefinition } from "./definition.js";
+/** Safe reason that a collect-stage model proposal was rejected. */
+export declare const InvalidCollectStageResponseReasonSchema: Schema.Literal<["invalid_evidence", "invalid_repair"]>;
+declare const InvalidCollectStageResponse_base: Schema.TaggedErrorClass<InvalidCollectStageResponse, "InvalidCollectStageResponse", {
+    readonly _tag: Schema.tag<"InvalidCollectStageResponse">;
+} & {
+    stage: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    reason: Schema.Literal<["invalid_evidence", "invalid_repair"]>;
+}>;
+/** A collect-stage proposal was not grounded in a user message. */
+export declare class InvalidCollectStageResponse extends InvalidCollectStageResponse_base {
+}
+/** Named answer fields accepted by a collect stage. */
+export type AnswerFields = Readonly<Record<string, AnswerDefinitionContract>>;
+type AnswerValue<Answer> = Answer extends AnswerDefinition<infer _Mode, infer ValueSchema, infer _Error, infer _Requirements> ? Schema.Schema.Type<ValueSchema> : never;
+/** Complete typed answers required by a collect stage. */
+export type CollectAnswers<Fields extends AnswerFields> = {
+    readonly [Field in keyof Fields]: AnswerValue<Fields[Field]>;
+};
+/**
+ * Location of the user-authored text that supported an accepted answer.
+ *
+ * The quote is untrusted conversation data. For semantic answers it supports
+ * an inference; it is not required to equal the accepted typed value.
+ */
+export interface AcceptedAnswerEvidence {
+    readonly messageIndex: number;
+    readonly quote: string;
+}
+/** One typed answer persisted together with its supporting transcript data. */
+export interface AcceptedAnswer<Value> {
+    readonly value: Value;
+    readonly evidence: AcceptedAnswerEvidence;
+}
+declare const AnswerValidationRejected_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AnswerValidationRejected";
+} & Readonly<A>;
+/** A domain validator rejected one structurally valid proposed answer. */
+export declare class AnswerValidationRejected<Error, Question> extends AnswerValidationRejected_base<{
+    readonly stage: string;
+    readonly field: string;
+    readonly error: Error;
+    readonly question: Question;
+}> {
+}
+/** Accepted answer units keyed by their collect-stage field. */
+export type CollectAcceptedAnswers<Fields extends AnswerFields> = {
+    readonly [Field in keyof Fields]: AcceptedAnswer<AnswerValue<Fields[Field]>>;
+};
+/** One assistant question persisted together with its transcript location. */
+export interface IssuedCollectQuestion {
+    readonly messageIndex: number;
+    readonly text: string;
+}
+/** Server-owned progress for one collect stage. */
+export interface CollectStageState<Fields extends AnswerFields> {
+    readonly accepted: Partial<CollectAcceptedAnswers<Fields>>;
+    readonly asked: Partial<Record<keyof Fields & string, IssuedCollectQuestion>>;
+}
+/** Typed question selected for the next missing answer. */
+export type CollectStageQuestion<Fields extends AnswerFields> = {
+    [Field in keyof Fields & string]: {
+        readonly field: Field;
+        readonly mode: Fields[Field]["mode"];
+        readonly description: string;
+        readonly question: Fields[Field]["question"];
+    };
+}[keyof Fields & string];
+type QuestionOptions<Question> = Question extends ChoiceQuestion<infer Value> ? ReadonlyArray<QuestionChoice<Value>> : Question extends AdaptiveChoiceQuestion ? ReadonlyArray<QuestionChoice<string>> : readonly [];
+/** Browser-ready question deterministically selected after fact extraction. */
+export type CollectStagePrompt<Fields extends AnswerFields> = {
+    [Field in keyof Fields & string]: {
+        readonly field: Field;
+        readonly mode: Fields[Field]["mode"];
+        readonly text: string;
+        readonly options: QuestionOptions<Fields[Field]["question"]>;
+        readonly escape?: {
+            readonly label: string;
+        };
+    };
+}[keyof Fields & string];
+type AnswerValidationError<Answer> = Answer extends AnswerDefinition<infer _Mode, infer _Schema, infer Error, infer _Requirements> ? Error : never;
+type AnswerValidationRequirements<Answer> = Answer extends AnswerDefinition<infer _Mode, infer _Schema, infer _Error, infer Requirements> ? Requirements : never;
+/** Failure union produced by all field validators in a collect stage. */
+export type CollectAnswerValidationError<Fields extends AnswerFields> = {
+    [Field in keyof Fields & string]: [
+        AnswerValidationError<Fields[Field]>
+    ] extends [never] ? never : AnswerValidationRejected<AnswerValidationError<Fields[Field]>, Extract<CollectStagePrompt<Fields>, {
+        readonly field: Field;
+    }>>;
+}[keyof Fields & string];
+/** Effect service union required by all field validators in a collect stage. */
+export type CollectAnswerValidationRequirements<Fields extends AnswerFields> = AnswerValidationRequirements<Fields[keyof Fields]>;
+/** Result of one collect-stage model turn. */
+export interface CollectStageTurn<Fields extends AnswerFields> {
+    readonly state: CollectStageState<Fields>;
+    readonly complete: boolean;
+    readonly question: CollectStagePrompt<Fields> | undefined;
+}
+type RuntimeAnswerValue = Schema.Schema.Type<Schema.Schema.AnyNoContext>;
+type RuntimeAcceptedAnswer = AcceptedAnswer<RuntimeAnswerValue>;
+interface RuntimeCollectStageState {
+    readonly accepted: Readonly<Partial<Record<string, RuntimeAcceptedAnswer>>>;
+    readonly asked: Readonly<Partial<Record<string, IssuedCollectQuestion>>>;
+}
+interface RuntimeCollectStagePrompt {
+    readonly field: string;
+    readonly mode: AnswerMode;
+    readonly text: string;
+    readonly options: ReadonlyArray<QuestionChoice<RuntimeAnswerValue>>;
+    readonly escape?: {
+        readonly label: string;
+    };
+}
+interface RuntimeCollectStageTurn {
+    readonly state: RuntimeCollectStageState;
+    readonly complete: boolean;
+    readonly question: RuntimeCollectStagePrompt | undefined;
+}
+interface RuntimeCollectRepair {
+    readonly _tag: "ReplaceAcceptedAnswer" | "ReconfirmAnswer";
+    readonly field: string;
+    readonly value?: RuntimeAnswerValue;
+    readonly evidence: {
+        readonly quote: string;
+    };
+}
+interface RuntimeCollectRepairResult {
+    readonly state: RuntimeCollectStageState;
+    readonly requiresConfirmation: boolean;
+}
+/** @internal Erased collect-stage behavior consumed by the chat runtime. */
+export interface CollectStageRuntime {
+    readonly initialState: RuntimeCollectStageState;
+    readonly stateSchema: Schema.Schema.AnyNoContext;
+    readonly isInitial: (state: RuntimeCollectStageState) => boolean;
+    readonly isValid: (state: RuntimeCollectStageState) => boolean;
+    readonly isGroundedInMessages: (state: RuntimeCollectStageState, messages: ReadonlyArray<UntrustedMessage>) => boolean;
+    readonly isComplete: (state: RuntimeCollectStageState) => boolean;
+    readonly repairSchema: Schema.Schema.AnyNoContext;
+    readonly applyRepairs: (state: RuntimeCollectStageState, messages: ReadonlyArray<UntrustedMessage>, repairs: ReadonlyArray<RuntimeCollectRepair>) => Effect.Effect<RuntimeCollectRepairResult, unknown, unknown>;
+    readonly run: (input: {
+        readonly state: RuntimeCollectStageState;
+        readonly messages: ReadonlyArray<UntrustedMessage>;
+    }) => Effect.Effect<RuntimeCollectStageTurn, unknown, unknown>;
+}
+declare const collectStageRuntime: unique symbol;
+/** Minimum sealed collect-stage shape accepted by a chat definition. */
+export interface CollectStageDefinitionContract extends StructuredDefinition<"collect_stage"> {
+    readonly _tag: "CollectStage";
+    readonly name: string;
+    readonly [collectStageRuntime]: CollectStageRuntime;
+}
+/** @internal Read the erased runtime from an authentic collect stage. */
+export declare const readCollectStageRuntime: (stage: CollectStageDefinitionContract) => CollectStageRuntime;
+/** Shared conversational policy for questions in one collect stage. */
+export interface CollectQuestionPolicy {
+    /** Trusted style guidance applied to every adaptive question in this stage. */
+    readonly guidance?: string;
+    /** A browser-visible answer that keeps the current field unresolved. */
+    readonly escape?: string;
+}
+/** Definition input for one schema-derived fact collection stage. */
+export interface DefineCollectStageInput<Name extends string, Fields extends AnswerFields, Guards extends ModelGuardTuple> {
+    readonly name: Name;
+    readonly questions?: CollectQuestionPolicy;
+    readonly fields: Fields;
+    readonly guards?: Guards;
+}
+/** One schema-derived stage that is complete only when every fact is known. */
+export interface CollectStage<Name extends string, Fields extends AnswerFields, Guards extends ModelGuardTuple = readonly []> extends CollectStageDefinitionContract {
+    readonly _tag: "CollectStage";
+    readonly name: Name;
+    readonly fields: Fields;
+    readonly questions: CollectQuestionPolicy;
+    readonly answersSchema: Schema.Schema<CollectAnswers<Fields>, unknown, never>;
+    readonly stateSchema: Schema.Schema<CollectStageState<Fields>, unknown, never>;
+    readonly initialState: CollectStageState<Fields>;
+    readonly guards: Guards;
+    /** Strictly parse persisted or client-returned stage state. */
+    readonly parseState: (input: Schema.Schema.Encoded<Schema.Schema<CollectStageState<Fields>, unknown, never>>) => Effect.Effect<CollectStageState<Fields>, ParseResult.ParseError>;
+    /** Test whether every schema-defined answer has been populated. */
+    readonly isComplete: (state: CollectStageState<Fields>) => boolean;
+    /** Select the first missing question in schema declaration order. */
+    readonly nextQuestion: (state: CollectStageState<Fields>) => CollectStageQuestion<Fields> | undefined;
+    /** Record the first assistant question issued for one field. */
+    readonly markAsked: <Field extends keyof Fields & string>(state: CollectStageState<Fields>, field: Field, messageIndex: number, text: string) => CollectStageState<Fields>;
+    /** Extract grounded answers and deterministically advance one turn. */
+    readonly run: (input: {
+        readonly state: CollectStageState<Fields>;
+        readonly messages: ReadonlyArray<UntrustedMessage>;
+    }) => Effect.Effect<CollectStageTurn<Fields>, ChatModelUnavailable | UnsupportedModelToolSchema | InvalidToolCall | InvalidToolProjection | InvalidCollectStageResponse | CollectAnswerValidationError<Fields> | ModelGuardError<Guards>, StructuredChatModel | CollectAnswerValidationRequirements<Fields> | ModelGuardRequirements<Guards>>;
+}
+/** Define one deterministic schema-derived fact collection stage. */
+export declare const defineCollectStage: <const Name extends string, const Fields extends AnswerFields, const Guards extends ModelGuardTuple = readonly []>(definition: DefineCollectStageInput<Name, Fields, Guards>) => CollectStage<Name, Fields, Guards>;
+export {};