The best way to control Claude Code, Codex and more from any computer or phone

main
md 70 lines 3.18 KB
Rendered Raw
1 # @effect/ai-cloudflare
2
3 Cloudflare Workers AI provider for Effect's `DecisionModel`. Supports text and JSON classification, ordered ratings, and probabilities with Clef and Clef-flash over REST.
4
5 ## Installation
6
7 ```sh
8 npm install effect @effect/ai-cloudflare
9 ```
10
11 ## Usage
12
13 Set `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, then provide a Cloudflare decision model:
14
15 ```ts
16 import { CloudflareClient, CloudflareDecisionModel } from "@effect/ai-cloudflare"
17 import { Effect, Layer, Schema } from "effect"
18 import { Decision, DecisionModel } from "effect/ai"
19 import { FetchHttpClient } from "effect/http"
20
21 const Triage = Decision.make({
22 input: Schema.String,
23 decisions: {
24 urgent: Decision.probability({
25 instructions: "Does this request need immediate attention?"
26 })
27 }
28 })
29
30 const Clef = CloudflareDecisionModel.layer({ model: "clef-flash" }).pipe(
31 Layer.provide(CloudflareClient.layerConfig()),
32 Layer.provide(FetchHttpClient.layer)
33 )
34
35 const program = DecisionModel.decide(Triage, {
36 input: "Checkout has been failing for every customer for an hour."
37 }).pipe(Effect.provide(Clef))
38 ```
39
40 Declare images as input fields with `Decision.Image`. Clef shows them to the model before the state, and the state lists each image's reference in order:
41
42 ```ts
43 declare const screenshotBytes: Uint8Array
44
45 const ScreenshotTriage = Decision.make({
46 input: Schema.Struct({ report: Schema.String, screenshot: Decision.Image }),
47 decisions: Triage.decisions
48 })
49
50 const withScreenshot = DecisionModel.decide(ScreenshotTriage, {
51 input: {
52 report: "Customers report the error in `screenshot`.",
53 screenshot: { mediaType: "image/png", data: screenshotBytes }
54 }
55 })
56 ```
57
58 Image `data` may be a `Uint8Array`, a base64 string, or a `data:` URL. Remote URLs fail with `AiError.InvalidUserInputError` because Clef does not fetch them, so download the image first. The API accepts up to 4 PNG, JPEG, or WebP images, each at most 4 MiB and 16 megapixels, with 8 MiB of decoded images in total and a 13 MiB request body.
59
60 Use `"clef"` for the larger model. `CloudflareDecisionModel.model` provides a model descriptor with Cloudflare provider metadata. `CloudflareClient.layer` accepts an explicit account ID and redacted API token; `apiUrl` and `transformClient` customize HTTP access.
61
62 Instructions and descriptions can be strings, JSON objects, or JSON arrays. A rating level with a structured description takes an explicit `label`, which answers use.
63
64 The client unwraps Cloudflare's REST envelope and maps failures to `AiError`. It does not retry automatically. Rate-limit errors include `Retry-After` when provided. The decision model validates answers and rescales small probability drift from four-decimal rounding.
65
66 Cloudflare limits each request to 64 questions, classification to 2–255 choices, and ratings to 2–10 levels. See the [Clef API documentation](https://developers.cloudflare.com/workers-ai/models/clef/) for request limits.
67
68 ## AI Gateway
69
70 Set `CLOUDFLARE_AI_GATEWAY_ID` when using `CloudflareClient.layerConfig()` to route requests through a Cloudflare AI Gateway. You can also pass `gatewayId` to `CloudflareClient.layer`. The client adds the `cf-aig-gateway-id` header. Use `transformClient` to add other `cf-aig-*` headers.