@llm4ts/js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Riccardo Merolla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @llm4ts/js
+
+The fastest way to try [llm4ts](https://github.com/riccardomerolla/llm4ts):
+a Promise-based client for plain JavaScript and TypeScript consumers — no
+Effect knowledge required.
+
+## Install
+
+```bash
+npm install @llm4ts/js
+```
+
+Requires Node.js >= 22.
+
+## Usage
+
+Works out of the box with the built-in mock provider — no credentials needed:
+
+```js
+import { createClient } from "@llm4ts/js"
+
+const client = createClient({ provider: "mock", model: "mock" })
+const response = await client.complete("Say hello")
+console.log(response.content)
+```
+
+Swap in a real provider by name (`openai`, `anthropic`, `gemini`,
+`lm-studio`, `ollama`) — API keys are read from the standard environment
+variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`):
+
+```js
+const client = createClient({
+  provider: "anthropic",
+  model: "claude-sonnet-4-5"
+})
+const answer = await client.complete("Summarize the Effect library in one line")
+```
+
+The client also exposes `health()` for checking provider availability and
+credentials.
+
+For full flows — plans, review loops, Git integration, CLI coding agents —
+use [`@llm4ts/runner`](https://www.npmjs.com/package/@llm4ts/runner).
+
+## License
+
+MIT

package/dist/Client.d.ts

@@ -0,0 +1,53 @@
+import * as Schema from "effect/Schema";
+export declare const JsProvider: Schema.Literals<readonly ["mock", "openai", "anthropic", "gemini", "lm-studio", "ollama"]>;
+export type JsProvider = typeof JsProvider.Type;
+declare const ClientConfig_base: Schema.Class<ClientConfig, Schema.Struct<{
+    readonly provider: Schema.Literals<readonly ["mock", "openai", "anthropic", "gemini", "lm-studio", "ollama"]>;
+    readonly model: Schema.optionalKey<Schema.String>;
+    readonly baseUrl: Schema.optionalKey<Schema.String>;
+    readonly apiKey: Schema.optionalKey<Schema.String>;
+    readonly timeoutSeconds: Schema.optionalKey<Schema.Number>;
+    readonly temperature: Schema.optionalKey<Schema.Number>;
+    readonly maxTokens: Schema.optionalKey<Schema.Int>;
+}>, {}>;
+export declare class ClientConfig extends ClientConfig_base {
+}
+declare const CompletionUsage_base: Schema.Class<CompletionUsage, Schema.Struct<{
+    readonly prompt: Schema.Int;
+    readonly completion: Schema.Int;
+    readonly total: Schema.Int;
+    readonly cached: Schema.optionalKey<Schema.Int>;
+}>, {}>;
+export declare class CompletionUsage extends CompletionUsage_base {
+}
+declare const Completion_base: Schema.Class<Completion, Schema.Struct<{
+    readonly content: Schema.String;
+    readonly usage: Schema.optionalKey<typeof CompletionUsage>;
+    readonly metadata: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+export declare class Completion extends Completion_base {
+}
+declare const ClientHealth_base: Schema.Class<ClientHealth, Schema.Struct<{
+    readonly available: Schema.Boolean;
+    readonly availability: Schema.String;
+    readonly authentication: Schema.String;
+}>, {}>;
+export declare class ClientHealth extends ClientHealth_base {
+}
+export type ErrorCategory = "Configuration" | "Authentication" | "RateLimit" | "Timeout" | "Parse" | "Provider" | "Interrupted" | "Unknown";
+export declare class Llm4tsError extends Error {
+    readonly category: ErrorCategory;
+    readonly detail: unknown;
+    constructor(category: ErrorCategory, message: string, detail?: unknown);
+}
+export interface CallOptions {
+    readonly signal?: AbortSignal;
+}
+export interface LlmClient {
+    readonly complete: (prompt: string, options?: CallOptions) => Promise<Completion>;
+    readonly health: (options?: CallOptions) => Promise<ClientHealth>;
+}
+export declare const createClient: (input: unknown) => LlmClient;
+export declare const mockClient: () => LlmClient;
+export {};
+//# sourceMappingURL=Client.d.ts.map

package/dist/Client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../src/Client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAavC,eAAO,MAAM,UAAU,4FAOrB,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;;;;;;;;;;AAE/C,qBAAa,YAAa,SAAQ,iBAQhC;CAAG;;;;;;;AAEL,qBAAa,eAAgB,SAAQ,oBAKnC;CAAG;;;;;;AAEL,qBAAa,UAAW,SAAQ,eAI9B;CAAG;;;;;;AAEL,qBAAa,YAAa,SAAQ,iBAIhC;CAAG;AAEL,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,SAAS,GACT,OAAO,GACP,UAAU,GACV,aAAa,GACb,SAAS,CAAA;AAEb,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;gBAEZ,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;CAMvE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACjF,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;CAClE;AAoFD,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,SAiC7C,CAAA;AAED,eAAO,MAAM,UAAU,QAAO,SAA8D,CAAA"}

package/dist/Client.js

@@ -0,0 +1,143 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { ApiConnectorConfig } from "@llm4ts/core/ConnectorConfig";
+import { AuthenticationError, ConfigError, ParseError, RateLimitError, TimeoutError } from "@llm4ts/core/Errors";
+import { ConnectorIds } from "@llm4ts/core/Models";
+import { collect } from "@llm4ts/core/Streaming";
+import { nodeFlowRunnerDependencies } from "@llm4ts/runner/FlowRunner";
+export const JsProvider = Schema.Literals([
+    "mock",
+    "openai",
+    "anthropic",
+    "gemini",
+    "lm-studio",
+    "ollama"
+]);
+export class ClientConfig extends Schema.Class("ClientConfig")({
+    provider: JsProvider,
+    model: Schema.optionalKey(Schema.String),
+    baseUrl: Schema.optionalKey(Schema.String),
+    apiKey: Schema.optionalKey(Schema.String),
+    timeoutSeconds: Schema.optionalKey(Schema.Number),
+    temperature: Schema.optionalKey(Schema.Number),
+    maxTokens: Schema.optionalKey(Schema.Int)
+}) {
+}
+export class CompletionUsage extends Schema.Class("CompletionUsage")({
+    prompt: Schema.Int,
+    completion: Schema.Int,
+    total: Schema.Int,
+    cached: Schema.optionalKey(Schema.Int)
+}) {
+}
+export class Completion extends Schema.Class("Completion")({
+    content: Schema.String,
+    usage: Schema.optionalKey(CompletionUsage),
+    metadata: Schema.Record(Schema.String, Schema.String)
+}) {
+}
+export class ClientHealth extends Schema.Class("ClientHealth")({
+    available: Schema.Boolean,
+    availability: Schema.String,
+    authentication: Schema.String
+}) {
+}
+export class Llm4tsError extends Error {
+    category;
+    detail;
+    constructor(category, message, detail) {
+        super(message, { cause: detail });
+        this.name = "Llm4tsError";
+        this.category = category;
+        this.detail = detail;
+    }
+}
+const connectorId = (provider) => {
+    switch (provider) {
+        case "mock":
+            return ConnectorIds.Mock;
+        case "openai":
+            return ConnectorIds.OpenAI;
+        case "anthropic":
+            return ConnectorIds.Anthropic;
+        case "gemini":
+            return ConnectorIds.GeminiApi;
+        case "lm-studio":
+            return ConnectorIds.LmStudio;
+        case "ollama":
+            return ConnectorIds.Ollama;
+    }
+};
+const categoryOf = (error) => error instanceof ConfigError
+    ? "Configuration"
+    : error instanceof AuthenticationError
+        ? "Authentication"
+        : error instanceof RateLimitError
+            ? "RateLimit"
+            : error instanceof TimeoutError
+                ? "Timeout"
+                : error instanceof ParseError
+                    ? "Parse"
+                    : "Provider";
+const messageOf = (error) => error instanceof Error && error.message.length > 0 ? error.message : String(error);
+const bridge = async (effect, options) => {
+    try {
+        const result = await Effect.runPromise(Effect.result(effect), {
+            ...(options?.signal === undefined ? {} : { signal: options.signal })
+        });
+        if (result._tag === "Failure") {
+            const failure = result.failure;
+            const category = categoryOf(failure);
+            throw new Llm4tsError(category, messageOf(failure), failure);
+        }
+        return result.success;
+    }
+    catch (error) {
+        if (error instanceof Llm4tsError) {
+            throw error;
+        }
+        const interrupted = options?.signal?.aborted === true;
+        throw new Llm4tsError(interrupted ? "Interrupted" : "Unknown", interrupted ? "operation interrupted" : messageOf(error), error);
+    }
+};
+const decodeConfig = (input) => {
+    try {
+        return Schema.decodeUnknownSync(ClientConfig)(input);
+    }
+    catch (error) {
+        throw new Llm4tsError("Configuration", `invalid client configuration: ${messageOf(error)}`, error);
+    }
+};
+const apiConfig = (config) => ApiConnectorConfig.make({
+    connectorId: connectorId(config.provider),
+    model: config.model ?? (config.provider === "mock" ? "mock" : ""),
+    ...(config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl }),
+    ...(config.apiKey === undefined ? {} : { apiKey: Redacted.make(config.apiKey) }),
+    ...(config.timeoutSeconds === undefined
+        ? {}
+        : { timeout: Duration.seconds(config.timeoutSeconds) }),
+    ...(config.temperature === undefined ? {} : { temperature: config.temperature }),
+    ...(config.maxTokens === undefined ? {} : { maxTokens: config.maxTokens })
+});
+export const createClient = (input) => {
+    const config = apiConfig(decodeConfig(input));
+    const connector = nodeFlowRunnerDependencies().registry.resolve(config);
+    return {
+        complete: (prompt, options) => bridge(Effect.flatMap(connector, (service) => collect(service.executeStream(prompt))).pipe(Effect.map((response) => Completion.make({
+            content: response.content,
+            metadata: response.metadata,
+            ...(response.usage === undefined
+                ? {}
+                : { usage: CompletionUsage.make(response.usage) })
+        }))), options),
+        health: (options) => bridge(Effect.flatMap(connector, (service) => service.healthCheck).pipe(Effect.map((health) => ClientHealth.make({
+            available: health.availability === "Healthy" || health.availability === "Degraded",
+            availability: health.availability,
+            authentication: health.authStatus
+        }))), options)
+    };
+};
+export const mockClient = () => createClient({ provider: "mock", model: "mock" });
+//# sourceMappingURL=Client.js.map

package/dist/Client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Client.js","sourceRoot":"","sources":["../src/Client.ts"],"names":[],"mappings":"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"}

package/dist/Package.d.ts

@@ -0,0 +1,2 @@
+export declare const packageName = "@llm4ts/js";
+//# sourceMappingURL=Package.d.ts.map

package/dist/Package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Package.d.ts","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,eAAe,CAAA"}

package/dist/Package.js

@@ -0,0 +1,2 @@
+export const packageName = "@llm4ts/js";
+//# sourceMappingURL=Package.js.map

package/dist/Package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Package.js","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAA"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@llm4ts/js",
+  "version": "0.1.0",
+  "description": "Promise and exception facade for llm4ts",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": "./dist/Client.js",
+    "./Client": "./dist/Client.js",
+    "./Package": "./dist/Package.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/riccardomerolla/llm4ts.git",
+    "directory": "packages/js"
+  },
+  "homepage": "https://github.com/riccardomerolla/llm4ts#readme",
+  "bugs": {
+    "url": "https://github.com/riccardomerolla/llm4ts/issues"
+  },
+  "keywords": [
+    "llm",
+    "effect",
+    "ai",
+    "agents",
+    "workflow",
+    "typescript"
+  ],
+  "dependencies": {
+    "@llm4ts/flow": "0.1.0",
+    "@llm4ts/core": "0.1.0",
+    "@llm4ts/runner": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0-beta.102"
+  },
+  "devDependencies": {
+    "effect": "^4.0.0-beta.102"
+  },
+  "scripts": {
+    "clean": "tsc -b tsconfig.json --clean",
+    "test": "vitest run test"
+  }
+}

package/src/Client.ts

@@ -0,0 +1,204 @@
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Redacted from "effect/Redacted"
+import * as Schema from "effect/Schema"
+import { ApiConnectorConfig } from "@llm4ts/core/ConnectorConfig"
+import {
+  AuthenticationError,
+  ConfigError,
+  ParseError,
+  RateLimitError,
+  TimeoutError
+} from "@llm4ts/core/Errors"
+import { ConnectorIds, type ConnectorId } from "@llm4ts/core/Models"
+import { collect } from "@llm4ts/core/Streaming"
+import { nodeFlowRunnerDependencies } from "@llm4ts/runner/FlowRunner"
+
+export const JsProvider = Schema.Literals([
+  "mock",
+  "openai",
+  "anthropic",
+  "gemini",
+  "lm-studio",
+  "ollama"
+])
+export type JsProvider = typeof JsProvider.Type
+
+export class ClientConfig extends Schema.Class<ClientConfig>("ClientConfig")({
+  provider: JsProvider,
+  model: Schema.optionalKey(Schema.String),
+  baseUrl: Schema.optionalKey(Schema.String),
+  apiKey: Schema.optionalKey(Schema.String),
+  timeoutSeconds: Schema.optionalKey(Schema.Number),
+  temperature: Schema.optionalKey(Schema.Number),
+  maxTokens: Schema.optionalKey(Schema.Int)
+}) {}
+
+export class CompletionUsage extends Schema.Class<CompletionUsage>("CompletionUsage")({
+  prompt: Schema.Int,
+  completion: Schema.Int,
+  total: Schema.Int,
+  cached: Schema.optionalKey(Schema.Int)
+}) {}
+
+export class Completion extends Schema.Class<Completion>("Completion")({
+  content: Schema.String,
+  usage: Schema.optionalKey(CompletionUsage),
+  metadata: Schema.Record(Schema.String, Schema.String)
+}) {}
+
+export class ClientHealth extends Schema.Class<ClientHealth>("ClientHealth")({
+  available: Schema.Boolean,
+  availability: Schema.String,
+  authentication: Schema.String
+}) {}
+
+export type ErrorCategory =
+  | "Configuration"
+  | "Authentication"
+  | "RateLimit"
+  | "Timeout"
+  | "Parse"
+  | "Provider"
+  | "Interrupted"
+  | "Unknown"
+
+export class Llm4tsError extends Error {
+  readonly category: ErrorCategory
+  readonly detail: unknown
+
+  constructor(category: ErrorCategory, message: string, detail?: unknown) {
+    super(message, { cause: detail })
+    this.name = "Llm4tsError"
+    this.category = category
+    this.detail = detail
+  }
+}
+
+export interface CallOptions {
+  readonly signal?: AbortSignal
+}
+
+export interface LlmClient {
+  readonly complete: (prompt: string, options?: CallOptions) => Promise<Completion>
+  readonly health: (options?: CallOptions) => Promise<ClientHealth>
+}
+
+const connectorId = (provider: JsProvider): ConnectorId => {
+  switch (provider) {
+    case "mock":
+      return ConnectorIds.Mock
+    case "openai":
+      return ConnectorIds.OpenAI
+    case "anthropic":
+      return ConnectorIds.Anthropic
+    case "gemini":
+      return ConnectorIds.GeminiApi
+    case "lm-studio":
+      return ConnectorIds.LmStudio
+    case "ollama":
+      return ConnectorIds.Ollama
+  }
+}
+
+const categoryOf = (error: unknown): ErrorCategory =>
+  error instanceof ConfigError
+    ? "Configuration"
+    : error instanceof AuthenticationError
+      ? "Authentication"
+      : error instanceof RateLimitError
+        ? "RateLimit"
+        : error instanceof TimeoutError
+          ? "Timeout"
+          : error instanceof ParseError
+            ? "Parse"
+            : "Provider"
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error && error.message.length > 0 ? error.message : String(error)
+
+const bridge = async <A, E>(effect: Effect.Effect<A, E>, options?: CallOptions): Promise<A> => {
+  try {
+    const result = await Effect.runPromise(Effect.result(effect), {
+      ...(options?.signal === undefined ? {} : { signal: options.signal })
+    })
+    if (result._tag === "Failure") {
+      const failure = result.failure
+      const category = categoryOf(failure)
+      throw new Llm4tsError(category, messageOf(failure), failure)
+    }
+    return result.success
+  } catch (error) {
+    if (error instanceof Llm4tsError) {
+      throw error
+    }
+    const interrupted = options?.signal?.aborted === true
+    throw new Llm4tsError(
+      interrupted ? "Interrupted" : "Unknown",
+      interrupted ? "operation interrupted" : messageOf(error),
+      error
+    )
+  }
+}
+
+const decodeConfig = (input: unknown): ClientConfig => {
+  try {
+    return Schema.decodeUnknownSync(ClientConfig)(input)
+  } catch (error) {
+    throw new Llm4tsError(
+      "Configuration",
+      `invalid client configuration: ${messageOf(error)}`,
+      error
+    )
+  }
+}
+
+const apiConfig = (config: ClientConfig): ApiConnectorConfig =>
+  ApiConnectorConfig.make({
+    connectorId: connectorId(config.provider),
+    model: config.model ?? (config.provider === "mock" ? "mock" : ""),
+    ...(config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl }),
+    ...(config.apiKey === undefined ? {} : { apiKey: Redacted.make(config.apiKey) }),
+    ...(config.timeoutSeconds === undefined
+      ? {}
+      : { timeout: Duration.seconds(config.timeoutSeconds) }),
+    ...(config.temperature === undefined ? {} : { temperature: config.temperature }),
+    ...(config.maxTokens === undefined ? {} : { maxTokens: config.maxTokens })
+  })
+
+export const createClient = (input: unknown): LlmClient => {
+  const config = apiConfig(decodeConfig(input))
+  const connector = nodeFlowRunnerDependencies().registry.resolve(config)
+  return {
+    complete: (prompt, options) =>
+      bridge(
+        Effect.flatMap(connector, (service) => collect(service.executeStream(prompt))).pipe(
+          Effect.map((response) =>
+            Completion.make({
+              content: response.content,
+              metadata: response.metadata,
+              ...(response.usage === undefined
+                ? {}
+                : { usage: CompletionUsage.make(response.usage) })
+            })
+          )
+        ),
+        options
+      ),
+    health: (options) =>
+      bridge(
+        Effect.flatMap(connector, (service) => service.healthCheck).pipe(
+          Effect.map((health) =>
+            ClientHealth.make({
+              available: health.availability === "Healthy" || health.availability === "Degraded",
+              availability: health.availability,
+              authentication: health.authStatus
+            })
+          )
+        ),
+        options
+      )
+  }
+}
+
+export const mockClient = (): LlmClient => createClient({ provider: "mock", model: "mock" })

package/src/Package.ts

@@ -0,0 +1 @@
+export const packageName = "@llm4ts/js"