.github/workflows/check.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install dependencies
         uses: ./.github/actions/setup
       - run: pnpm check
-      - run: pnpm dtslint
+      - run: pnpm test-types --target '>=5.4'
 
   lint:
     name: Lint

.github/workflows/nightly.yml

@@ -0,0 +1,17 @@
+name: TypeScript's Nightly
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 12 * * *"
+
+jobs:
+  types:
+    name: Types
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        uses: ./.github/actions/setup
+      - run: pnpm test-types --target next

README.md

@@ -88,7 +88,7 @@ git checkout -b my-branch
 Ensure all required dependencies are installed by running:
 
 ```bash
-pnpm install  # Requires pnpm version 9.0.4
+pnpm install  # Requires pnpm version 10.4.0
 ```
 
 ## Making Changes
@@ -107,7 +107,7 @@ Run the following commands to ensure your changes do not introduce any issues:
 - `pnpm circular`: Check for any circular dependencies in imports.
 - `pnpm lint`: Ensure the code adheres to our coding standards.
   - If you encounter style issues, use `pnpm lint-fix` to automatically correct some of these.
-- `pnpm dtslint`: Run type-level tests.
+- `pnpm test-types`: Run type-level tests. Tests are written using [tstyche](https://tstyche.org/).
 - `pnpm docgen`: Ensure the documentation generates correctly and reflects any changes made.
 
 ### Document Your Changes

package.json

@@ -15,8 +15,7 @@
     "lint": "eslint \"**/{src,test,examples,scripts,dtslint}/**/*.{ts,mjs}\"",
     "lint-fix": "pnpm lint --fix",
     "docgen": "pnpm --recursive --parallel exec docgen && node scripts/docs.mjs",
-    "dtslint": "pnpm --recursive --parallel run dtslint",
-    "dtslint-clean": "dtslint --clean",
+    "test-types": "tstyche",
     "changeset-version": "changeset version && node scripts/version.mjs",
     "changeset-publish": "pnpm codemod && pnpm build && TEST_DIST= pnpm vitest && changeset publish"
   },
@@ -42,7 +41,6 @@
     "@edge-runtime/vm": "^4.0.0",
     "@effect/build-utils": "^0.7.7",
     "@effect/docgen": "^0.5.2",
-    "@effect/dtslint": "^0.1.2",
     "@effect/eslint-plugin": "^0.2.0",
     "@effect/language-service": "^0.1.0",
     "@effect/vitest": "workspace:^",
@@ -71,6 +69,7 @@
     "playwright": "^1.46.0",
     "prettier": "^3.3.3",
     "rimraf": "^6.0.1",
+    "tstyche": "^3.5.0",
     "tsx": "^4.17.0",
     "typescript": "^5.7.2",
     "vite": "^6.0.11",

packages/ai/ai/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @effect/ai
 
+## 0.10.3
+
+### Patch Changes
+
+- [#4504](https://github.com/Effect-TS/effect/pull/4504) [`a67a8a1`](https://github.com/Effect-TS/effect/commit/a67a8a1a4979fb7a039a060d067d805879da4d4b) Thanks @IMax153! - Introduce `AiModel` and `AiPlan` for describing retry / fallback logic between
+  models and providers
+
+  For example, the following program builds an `AiPlan` which will attempt to use
+  OpenAi's chat completions API, and if after three attempts the operation
+  is still failing, the plan will fallback to utilizing Anthropic's messages API
+  to resolve the request.
+
+  ```ts
+  import { AiPlan, Completions } from "@effect/ai"
+  import { AnthropicClient, AnthropicCompletions } from "@effect/ai-anthropic"
+  import { OpenAiClient, OpenAiCompletions } from "@effect/ai-openai"
+  import { NodeHttpClient, NodeRuntime } from "@effect/platform-node"
+  import { Config, Console, Effect, Layer } from "effect"
+
+  // Create Anthropic client
+  const Anthropic = AnthropicClient.layerConfig({
+    apiKey: Config.redacted("ANTHROPIC_API_KEY")
+  }).pipe(Layer.provide(NodeHttpClient.layerUndici))
+
+  // Create OpenAi client
+  const OpenAi = OpenAiClient.layerConfig({
+    apiKey: Config.redacted("OPENAI_API_KEY")
+  }).pipe(Layer.provide(NodeHttpClient.layerUndici))
+
+  // Create a plan of request execution
+  const Plan = AiPlan.fromModel(OpenAiCompletions.model("gpt-4o-mini"), {
+    attempts: 3
+  }).pipe(
+    AiPlan.withFallback({
+      model: AnthropicCompletions.model("claude-3-5-haiku-latest")
+    })
+  )
+
+  const program = Effect.gen(function* () {
+    // Build the plan of execution
+    const plan = yield* Plan
+
+    // Create a program which uses the services provided by the plan
+    const getDadJoke = Effect.gen(function* () {
+      const completions = yield* Completions.Completions
+      const response = yield* completions.create("Tell me a dad joke")
+      yield* Console.log(response.text)
+    })
+
+    // Provide the plan to whichever programs need it
+    yield* plan.provide(getDadJoke)
+  })
+
+  program.pipe(Effect.provide([Anthropic, OpenAi]), NodeRuntime.runMain)
+  ```
+
+- Updated dependencies [[`cc5588d`](https://github.com/Effect-TS/effect/commit/cc5588df07f9103513547cb429ce041b9436a8bd), [`623c8cd`](https://github.com/Effect-TS/effect/commit/623c8cd053ed6ee3d353aaa8778d484670fca2bb), [`00b4eb1`](https://github.com/Effect-TS/effect/commit/00b4eb1ece12a16e222e6220965bb4024d6752ac), [`f2aee98`](https://github.com/Effect-TS/effect/commit/f2aee989b0a600900ce83e7f460d02908620c80f), [`fb798eb`](https://github.com/Effect-TS/effect/commit/fb798eb9061f1191badc017d1aa649360254da20), [`2251b15`](https://github.com/Effect-TS/effect/commit/2251b1528810bb695b37ce388b653cec0c5bf80c), [`2e15c1e`](https://github.com/Effect-TS/effect/commit/2e15c1e33648add0b29fe274fbcb7294b7515085), [`a4979db`](https://github.com/Effect-TS/effect/commit/a4979db021aef16e731be64df196b72088fc4376), [`b74255a`](https://github.com/Effect-TS/effect/commit/b74255a304ad49d60bedb1a260fd697f370af27a), [`d7f6a5c`](https://github.com/Effect-TS/effect/commit/d7f6a5c7d26c1963dcd864ca62360d20d08c7b49), [`9dd8979`](https://github.com/Effect-TS/effect/commit/9dd8979e940915b1cc1b1f264f3d019c77a65a02), [`477b488`](https://github.com/Effect-TS/effect/commit/477b488284f47c5469d7fba3e4065fb7e3b6556e), [`10932cb`](https://github.com/Effect-TS/effect/commit/10932cbf58fc721ada631cebec42f773ce96d3cc), [`9f6c784`](https://github.com/Effect-TS/effect/commit/9f6c78468b3b5e9ebfc38ffdfb70702901ee977b), [`2c639ec`](https://github.com/Effect-TS/effect/commit/2c639ecee332de4266e36022c989c35ae4e02105), [`886aaa8`](https://github.com/Effect-TS/effect/commit/886aaa81e06dfd3cd9391e8ea987d8cd5ada1124)]:
+  - effect@3.13.3
+  - @effect/experimental@0.41.3
+  - @effect/platform@0.77.3
+
 ## 0.10.2
 
 ### Patch Changes

packages/ai/ai/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effect/ai",
   "type": "module",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "license": "MIT",
   "description": "Effect modules for working with AI apis",
   "homepage": "https://effect.website",

packages/ai/ai/src/AiModel.ts

@@ -0,0 +1,91 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import type * as Scope from "effect/Scope"
+import type * as AiPlan from "./AiPlan.js"
+import * as InternalAiPlan from "./internal/aiPlan.js"
+
+/**
+ * @since 1.0.0
+ * @category type ids
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/ai/AiModel")
+
+/**
+ * @since 1.0.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 1.0.0
+ * @category type ids
+ */
+export const PlanTypeId: unique symbol = Symbol.for("@effect/ai/Plan")
+
+/**
+ * @since 1.0.0
+ * @category type ids
+ */
+export type PlanTypeId = typeof TypeId
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface AiModel<in out Provides, in out Requires> extends AiPlan.AiPlan<unknown, Provides, Requires> {
+  readonly [TypeId]: TypeId
+  readonly model: string
+  readonly cacheKey: symbol
+  readonly requires: Context.Tag<Requires, any>
+  readonly provides: AiModel.ContextBuilder<Provides, Requires>
+  readonly updateContext: (context: Context.Context<Provides>) => Context.Context<Provides>
+}
+
+/**
+ * @since 1.0.0
+ */
+export declare namespace AiModel {
+  /**
+   * @since 1.0.0
+   * @category AiModel
+   */
+  export type ContextBuilder<Provides, Requires> = Effect.Effect<
+    Context.Context<Provides>,
+    never,
+    Requires | Scope.Scope
+  >
+}
+
+const AiModelProto = {
+  ...InternalAiPlan.PlanPrototype,
+  [TypeId]: TypeId
+}
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = <Provides, Requires>(options: {
+  readonly model: string
+  readonly cacheKey: symbol
+  readonly requires: Context.Tag<Requires, any>
+  readonly provides: AiModel.ContextBuilder<Provides, Requires>
+  readonly updateContext: (context: Context.Context<Provides>) => Context.Context<Provides>
+}): AiModel<Provides, Requires> => {
+  const self = Object.create(AiModelProto)
+  self.cacheKey = options.cacheKey
+  self.model = options.model
+  self.provides = options.provides
+  self.requires = options.requires
+  self.updateContext = options.updateContext
+  self.steps = [{
+    model: self,
+    check: Option.none(),
+    schedule: Option.none()
+  }]
+  return self
+}

packages/ai/ai/src/AiModels.ts

@@ -0,0 +1,77 @@
+/**
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Equal from "effect/Equal"
+import * as Hash from "effect/Hash"
+import * as Layer from "effect/Layer"
+import * as RcMap from "effect/RcMap"
+import type * as Scope from "effect/Scope"
+import type { AiModel } from "./AiModel.js"
+
+/**
+ * @since 1.0.0
+ * @category tags
+ */
+export class AiModels extends Context.Tag("@effect/ai/AiModels")<
+  AiModels,
+  AiModels.Service
+>() {}
+
+/**
+ * @since 1.0.0
+ */
+export declare namespace AiModels {
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Service {
+    readonly build: <Provides, Requires>(
+      model: AiModel<Provides, Requires>,
+      context: Context.Context<Requires>
+    ) => Effect.Effect<Context.Context<Provides>, never, Scope.Scope>
+  }
+}
+
+class AiModelsKey {
+  constructor(
+    readonly model: AiModel<any, any>,
+    readonly service: unknown
+  ) {}
+
+  [Equal.symbol](that: AiModelsKey): boolean {
+    return this.service === that.service && this.model.cacheKey === that.model.cacheKey
+  }
+  [Hash.symbol](): number {
+    return Hash.combine(Hash.hash(this.service))(Hash.hash(this.model.cacheKey))
+  }
+}
+
+const make = Effect.gen(function*() {
+  const services = yield* RcMap.make({
+    idleTimeToLive: "1 minute",
+    lookup: (key: AiModelsKey) => Effect.provideService(key.model.provides, key.model.requires, key.service)
+  })
+
+  const build = <Provides, Requires>(
+    model: AiModel<Provides, Requires>,
+    context: Context.Context<Requires>
+  ): Effect.Effect<Context.Context<Provides>, never, Scope.Scope> =>
+    Effect.map(
+      RcMap.get(
+        services,
+        new AiModelsKey(model, Context.get(context, model.requires as any))
+      ),
+      (context) => model.updateContext(context)
+    )
+
+  return { build } as const
+})
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer: Layer.Layer<AiModels> = Layer.scoped(AiModels, make)