@effect-agent/ai-decision 0.1.0-beta.102

package/src/DecisionSchema.ts

@@ -0,0 +1,295 @@
+/**
+ * Request and response schemas for provider-neutral decision evaluations.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+
+/**
+ * Text or JSON objects and arrays used as state and question instructions.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Content = Schema.Union([Schema.String, Schema.JsonObject, Schema.Array(Schema.Json)]);
+
+/** @category models
+ * @since 0.1.0
+ */
+export type Content = typeof Content.Type;
+
+/**
+ * A choice between named options. A null rubric uses the option name alone.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ChoiceQuestion = Schema.Struct({
+  type: Schema.Literal("choice"),
+  instructions: Content,
+  criteria: Schema.Record(Schema.String, Schema.NullOr(Schema.String)).check(
+    Schema.isMinProperties(1),
+  ),
+});
+
+/** @category models
+ * @since 0.1.0
+ */
+export type ChoiceQuestion = typeof ChoiceQuestion.Type;
+
+/**
+ * A rating along at least two ordered, zero-indexed level descriptions.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ScoreQuestion = Schema.Struct({
+  type: Schema.Literal("score"),
+  instructions: Content,
+  criteria: Schema.Array(Schema.String).check(Schema.isMinLength(2)),
+});
+
+/** @category models
+ * @since 0.1.0
+ */
+export type ScoreQuestion = typeof ScoreQuestion.Type;
+
+/**
+ * A yes/no judgment, with optional descriptions of either outcome.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ProbabilityQuestion = Schema.Struct({
+  type: Schema.Literal("probability"),
+  instructions: Content,
+  criteria: Schema.optionalKey(
+    Schema.Struct({
+      true: Schema.optionalKey(Schema.String),
+      false: Schema.optionalKey(Schema.String),
+    }),
+  ),
+});
+
+/** @category models
+ * @since 0.1.0
+ */
+export type ProbabilityQuestion = typeof ProbabilityQuestion.Type;
+
+/** @category schemas
+ * @since 0.1.0
+ */
+export const Question = Schema.Union([ChoiceQuestion, ScoreQuestion, ProbabilityQuestion]);
+
+/** @category models
+ * @since 0.1.0
+ */
+export type Question = typeof Question.Type;
+
+/** @category schemas
+ * @since 0.1.0
+ */
+export const Questions = Schema.Record(Schema.String, Question);
+
+/** @category models
+ * @since 0.1.0
+ */
+export type Questions = typeof Questions.Type;
+
+/** @category schemas
+ * @since 0.1.0
+ */
+export const EvaluateRequest = Schema.Struct({
+  state: Content,
+  questions: Questions,
+});
+
+/**
+ * Evaluation input. Keep question literals with `satisfies Questions` when
+ * storing questions separately from the call to `evaluate`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type EvaluateRequest<Q extends Questions = Questions> = Omit<
+  typeof EvaluateRequest.Type,
+  "questions"
+> & { readonly questions: Q };
+
+/**
+ * A finite probability or confidence in the inclusive range [0, 1].
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Probability = Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 1 }));
+
+/**
+ * A selected option and its full distribution. Provider-specific confidence
+ * statistics belong to evaluation metadata, not the shared answer contract.
+ * Probabilities retain the provider's reported precision and are not normalized.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ChoiceAnswer = Schema.Struct({
+  type: Schema.Literal("choice"),
+  choice: Schema.String,
+  probabilities: Schema.Record(Schema.String, Probability),
+});
+
+/**
+ * Known option unions infer literal choices and required probability keys.
+ * Open string or template-pattern option types allow absent dictionary entries.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ChoiceAnswer<Choice extends string = string> = Omit<
+  typeof ChoiceAnswer.Type,
+  "choice" | "probabilities"
+> & {
+  readonly choice: Choice;
+  readonly probabilities: {
+    readonly [K in Choice]: {} extends Pick<Record<Choice, unknown>, K>
+      ? number | undefined
+      : number;
+  };
+};
+
+/**
+ * A fractional, probability-weighted level, with the supplied rubric as legend.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ScoreAnswer = Schema.Struct({
+  type: Schema.Literal("score"),
+  score: Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0)),
+  legend: Schema.Record(Schema.String, Schema.String),
+  probabilities: Schema.Record(Schema.String, Probability),
+});
+
+/**
+ * Score levels are keyed at runtime; an arbitrary legend or probability lookup
+ * may be absent.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ScoreAnswer = Omit<typeof ScoreAnswer.Type, "legend" | "probabilities"> & {
+  readonly legend: { readonly [level: string]: string | undefined };
+  readonly probabilities: { readonly [level: string]: number | undefined };
+};
+
+/**
+ * The probability of yes. A probability answer has no separate confidence field.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ProbabilityAnswer = Schema.Struct({
+  type: Schema.Literal("probability"),
+  probability: Probability,
+});
+
+/** @category models
+ * @since 0.1.0
+ */
+export type ProbabilityAnswer = typeof ProbabilityAnswer.Type;
+
+/** @category schemas
+ * @since 0.1.0
+ */
+export const Answer = Schema.Union([ChoiceAnswer, ScoreAnswer, ProbabilityAnswer]);
+
+/** @category models
+ * @since 0.1.0
+ */
+export type Answer = ChoiceAnswer | ScoreAnswer | ProbabilityAnswer;
+
+/** @category schemas
+ * @since 0.1.0
+ */
+export const Usage = Schema.Struct({
+  inputTokens: Schema.NullOr(Schema.Natural),
+  outputTokens: Schema.NullOr(Schema.Natural),
+});
+
+/** @category models
+ * @since 0.1.0
+ */
+export type Usage = typeof Usage.Type;
+
+/**
+ * Provider-namespaced evidence that has no shared interpretation. Consumers
+ * decode a namespace with its provider's schema before using its contents.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ProviderMetadata = Schema.Record(Schema.String, Schema.JsonObject);
+
+/** @category models
+ * @since 0.1.0
+ */
+export type ProviderMetadata = typeof ProviderMetadata.Type;
+
+/**
+ * The wire response shape. `DecisionModel.evaluate` additionally validates
+ * answer IDs, question kinds, criteria, distributions, and score correlations.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const EvaluateResponse = Schema.Struct({
+  provider: Schema.NonEmptyString,
+  model: Schema.String,
+  answers: Schema.Record(Schema.String, Answer),
+  usage: Usage,
+  providerMetadata: Schema.optionalKey(ProviderMetadata),
+});
+
+type ChoiceAnswerFor<Criteria> = Criteria extends unknown
+  ? Omit<typeof ChoiceAnswer.Type, "choice" | "probabilities"> & {
+      readonly choice: `${Extract<keyof Criteria, string | number>}`;
+      readonly probabilities: {
+        readonly [
+          K in keyof Criteria as K extends string | number ? `${K}` : never
+        ]: {} extends Pick<Criteria, K> ? number | undefined : number;
+      };
+    }
+  : never;
+
+/**
+ * Infer a question's answer, preserving optional choice criteria in its probabilities.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type AnswerFor<Q extends Question> = Q extends ChoiceQuestion
+  ? ChoiceAnswerFor<Q["criteria"]>
+  : Q extends ScoreQuestion
+    ? ScoreAnswer
+    : ProbabilityAnswer;
+
+/**
+ * One answer for each required question. Optional properties and open string,
+ * numeric, or template-pattern indexes require checking an entry for absence.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Answers<Q extends Questions> = {
+  readonly [K in keyof Q as K extends string | number ? `${K}` : never]: {} extends Pick<Q, K>
+    ? AnswerFor<NonNullable<Q[K]>> | undefined
+    : AnswerFor<Q[K]>;
+};
+
+/** @category models
+ * @since 0.1.0
+ */
+export type EvaluateResponse<Q extends Questions = Questions> = Omit<
+  typeof EvaluateResponse.Type,
+  "answers"
+> & { readonly answers: Answers<Q> };

package/src/DecisionSet.ts

@@ -0,0 +1,36 @@
+/**
+ * Reusable question collections with a schema-defined input. The set owns no
+ * provider, live resources, routing policy, or execution state.
+ *
+ * @since 0.1.0
+ */
+import type * as Schema from "effect/Schema";
+
+import type * as DecisionSchema from "./DecisionSchema.ts";
+
+/** @category models
+ * @since 0.1.0
+ */
+export interface DecisionSet<Input extends Schema.Top, Questions extends DecisionSchema.Questions> {
+  /** The encoded input becomes model-visible state: a string, JSON object, or JSON array. */
+  readonly input: Input;
+  /** Independent questions evaluated together against that state. */
+  readonly questions: Questions;
+}
+
+/**
+ * Describe a reusable assessment. Construction performs no encoding or model
+ * I/O. Input encoding and question validation occur inside model.evaluate.
+ * Treat nested instruction content as readonly; evaluation snapshots it before
+ * calling the provider. Dynamic question records are supported.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <Input extends Schema.Top, const Questions extends DecisionSchema.Questions>(
+  options: DecisionSet<Input, Questions>,
+): DecisionSet<Input, Questions> =>
+  Object.freeze({
+    input: options.input,
+    questions: Object.freeze({ ...options.questions }),
+  });

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as DecisionModel from "./DecisionModel.ts";
+export * as DecisionQuery from "./DecisionQuery.ts";
+export * as DecisionSchema from "./DecisionSchema.ts";
+export * as DecisionSet from "./DecisionSet.ts";

package/src/internal/schema.ts

@@ -0,0 +1,98 @@
+import * as Schema from "effect/Schema";
+import type * as SchemaAST from "effect/SchemaAST";
+
+import * as DecisionSchema from "../DecisionSchema.ts";
+
+// Permit floating-point serialization error without changing provider values.
+const tolerance = 1e-6;
+
+const probabilitySum = Schema.makeFilter(
+  (probabilities: Readonly<Record<string, number>>) =>
+    Math.abs(Object.values(probabilities).reduce((sum, value) => sum + value, 0) - 1) <= tolerance,
+  { expected: "probabilities summing to 1 (within 1e-6)" },
+);
+
+const distribution = (
+  keys: ReadonlyArray<string>,
+  sumCheck: SchemaAST.Check<Readonly<Record<string, number>>> = probabilitySum,
+) => Schema.Record(Schema.Literals(keys), DecisionSchema.Probability).check(sumCheck);
+
+const answerFor = (
+  question: DecisionSchema.Question,
+  choiceProbabilitySum: SchemaAST.Check<Readonly<Record<string, number>>> | undefined,
+) => {
+  switch (question.type) {
+    case "choice": {
+      const keys = Object.keys(question.criteria);
+
+      return Schema.Struct({
+        ...DecisionSchema.ChoiceAnswer.fields,
+        choice: Schema.Literals(keys),
+        probabilities: distribution(keys, choiceProbabilitySum),
+      }).check(
+        Schema.makeFilter(
+          ({ choice, probabilities }) =>
+            Object.values(probabilities).every((value) => value <= probabilities[choice]),
+          { expected: "a highest-probability choice" },
+        ),
+      );
+    }
+    case "score": {
+      const maxLevel = question.criteria.length - 1;
+
+      const levels = question.criteria.map(
+        (description, index) => [String(index), description] as const,
+      );
+
+      return Schema.Struct({
+        ...DecisionSchema.ScoreAnswer.fields,
+        score: Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: maxLevel })),
+        legend: Schema.Struct(
+          Object.fromEntries(
+            levels.map(([key, description]) => [key, Schema.Literal(description)]),
+          ),
+        ),
+        probabilities: distribution(levels.map(([key]) => key)),
+      }).check(
+        Schema.makeFilter(
+          ({ score, probabilities }) =>
+            Math.abs(
+              score -
+                Object.entries(probabilities).reduce(
+                  (sum, [level, probability]) => sum + Number(level) * probability,
+                  0,
+                ),
+            ) <=
+            tolerance * Math.max(1, maxLevel),
+          { expected: "the probability-weighted score (within 1e-6 per level)" },
+        ),
+      );
+    }
+    case "probability":
+      return DecisionSchema.ProbabilityAnswer;
+  }
+};
+
+// The overload describes the dependent type enforced by the literal keys and
+// per-question schemas below. No JSON value is asserted to have that type.
+export function responseFor<const Q extends DecisionSchema.Questions>(
+  questions: Q,
+  choiceProbabilitySum?: SchemaAST.Check<Readonly<Record<string, number>>>,
+): Schema.Codec<DecisionSchema.EvaluateResponse<Q>>;
+
+export function responseFor(
+  questions: DecisionSchema.Questions,
+  choiceProbabilitySum?: SchemaAST.Check<Readonly<Record<string, number>>>,
+): Schema.Top {
+  return Schema.Struct({
+    ...DecisionSchema.EvaluateResponse.fields,
+    answers: Schema.Struct(
+      Object.fromEntries(
+        Object.entries(questions).map(([id, question]) => [
+          id,
+          answerFor(question, choiceProbabilitySum),
+        ]),
+      ),
+    ),
+  });
+}