@llm4ts/core 0.1.0

package/src/Conversation.ts

@@ -0,0 +1,21 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+export const PromptRole = Schema.Literals(["System", "User", "Assistant", "Tool"])
+export type PromptRole = typeof PromptRole.Type
+
+const emptyMetadata: Readonly<Record<string, string>> = Object.freeze({})
+
+export class ConversationMessage extends Schema.Class<ConversationMessage>("ConversationMessage")({
+  id: Schema.String,
+  role: PromptRole,
+  content: Schema.String,
+  timestamp: Schema.DateTimeUtc,
+  tokens: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+  model: Schema.optionalKey(Schema.String),
+  costUsd: Schema.optionalKey(Schema.Number),
+  metadata: Schema.Record(Schema.String, Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyMetadata))
+  ),
+  important: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false)))
+}) {}

package/src/Errors.ts

@@ -0,0 +1,87 @@
+import * as Duration from "effect/Duration"
+import * as Schema from "effect/Schema"
+
+export class ProviderError extends Schema.TaggedErrorClass<ProviderError>()("ProviderError", {
+  message: Schema.String,
+  cause: Schema.optionalKey(Schema.Defect())
+}) {}
+
+export class UsageLimitError extends Schema.TaggedErrorClass<UsageLimitError>()("UsageLimitError", {
+  resetAt: Schema.optionalKey(Schema.DateTimeUtc),
+  provider: Schema.String,
+  message: Schema.String
+}) {}
+
+export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationError>()(
+  "AuthenticationError",
+  {
+    message: Schema.String
+  }
+) {}
+
+export class InvalidRequestError extends Schema.TaggedErrorClass<InvalidRequestError>()(
+  "InvalidRequestError",
+  {
+    message: Schema.String
+  }
+) {}
+
+export class ParseError extends Schema.TaggedErrorClass<ParseError>()("ParseError", {
+  message: Schema.String,
+  raw: Schema.String
+}) {}
+
+export class ToolError extends Schema.TaggedErrorClass<ToolError>()("ToolError", {
+  toolName: Schema.String,
+  detail: Schema.String
+}) {
+  get message(): string {
+    return `tool '${this.toolName}' failed: ${this.detail}`
+  }
+}
+
+export class ConfigError extends Schema.TaggedErrorClass<ConfigError>()("ConfigError", {
+  message: Schema.String
+}) {}
+
+export class RateLimitError extends Schema.TaggedErrorClass<RateLimitError>()("RateLimitError", {
+  retryAfter: Schema.optionalKey(Schema.Duration)
+}) {
+  get message(): string {
+    return this.retryAfter === undefined
+      ? "rate limited"
+      : `rate limited; retry after ${Duration.format(this.retryAfter)}`
+  }
+}
+
+export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()("TimeoutError", {
+  duration: Schema.Duration
+}) {
+  get message(): string {
+    return `timed out after ${Duration.format(this.duration)}`
+  }
+}
+
+export class TurnLimitError extends Schema.TaggedErrorClass<TurnLimitError>()("TurnLimitError", {
+  limit: Schema.optionalKey(Schema.Int)
+}) {
+  get message(): string {
+    return this.limit === undefined
+      ? "turn limit reached"
+      : `turn limit reached after ${this.limit} turn(s)`
+  }
+}
+
+export const LlmError = Schema.Union([
+  ProviderError,
+  UsageLimitError,
+  AuthenticationError,
+  InvalidRequestError,
+  ParseError,
+  ToolError,
+  ConfigError,
+  RateLimitError,
+  TimeoutError,
+  TurnLimitError
+])
+export type LlmError = typeof LlmError.Type

package/src/HttpClient.ts

@@ -0,0 +1,202 @@
+import * as Context from "effect/Context"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import { InvalidRequestError, type LlmError } from "./Errors.ts"
+
+const emptyHeaders: Readonly<Record<string, string>> = Object.freeze({})
+
+export class HttpRequest extends Schema.Class<HttpRequest>("HttpRequest")({
+  method: Schema.String,
+  url: Schema.String,
+  body: Schema.optionalKey(Schema.String),
+  headers: Schema.Record(Schema.String, Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyHeaders))
+  ),
+  contentType: Schema.String.pipe(
+    Schema.withConstructorDefault(Effect.succeed("application/json"))
+  ),
+  timeout: Schema.Duration
+}) {}
+
+export interface HttpClientShape {
+  readonly get: (
+    url: string,
+    headers: Readonly<Record<string, string>>,
+    timeout: Duration.Duration
+  ) => Effect.Effect<string, LlmError>
+  readonly postJson: (
+    url: string,
+    body: string,
+    headers: Readonly<Record<string, string>>,
+    timeout: Duration.Duration
+  ) => Effect.Effect<string, LlmError>
+  readonly send: (
+    method: string,
+    url: string,
+    body: string | undefined,
+    headers: Readonly<Record<string, string>>,
+    contentType: string,
+    timeout: Duration.Duration
+  ) => Effect.Effect<string, LlmError>
+  readonly postJsonStream: (
+    url: string,
+    body: string,
+    headers: Readonly<Record<string, string>>,
+    timeout: Duration.Duration
+  ) => Stream.Stream<string, LlmError>
+  readonly postJsonStreamSSE: (
+    url: string,
+    body: string,
+    headers: Readonly<Record<string, string>>,
+    timeout: Duration.Duration
+  ) => Stream.Stream<string, LlmError>
+}
+
+export class HttpClient extends Context.Service<HttpClient, HttpClientShape>()(
+  "@llm4ts/core/HttpClient"
+) {}
+
+export interface HttpClientPrimitives {
+  readonly postJson: HttpClientShape["postJson"]
+  readonly get?: HttpClientShape["get"]
+  readonly send?: HttpClientShape["send"]
+  readonly postJsonStream?: HttpClientShape["postJsonStream"]
+  readonly postJsonStreamSSE?: HttpClientShape["postJsonStreamSSE"]
+}
+
+export const makeHttpClient = (primitives: HttpClientPrimitives): HttpClientShape => {
+  const get: HttpClientShape["get"] =
+    primitives.get ??
+    ((_url, _headers, _timeout) =>
+      Effect.fail(
+        InvalidRequestError.make({
+          message: "GET is not supported by this HttpClient implementation"
+        })
+      ))
+
+  const send: HttpClientShape["send"] =
+    primitives.send ??
+    ((_method, _url, _body, _headers, _contentType, _timeout) =>
+      Effect.fail(
+        InvalidRequestError.make({
+          message: "send is not supported by this HttpClient implementation"
+        })
+      ))
+
+  const postJsonStream: HttpClientShape["postJsonStream"] =
+    primitives.postJsonStream ??
+    ((url, body, headers, timeout) =>
+      Stream.flatMap(Stream.fromEffect(primitives.postJson(url, body, headers, timeout)), (raw) =>
+        Stream.fromIterable(raw.split(/\r?\n/))
+      ))
+
+  const postJsonStreamSSE: HttpClientShape["postJsonStreamSSE"] =
+    primitives.postJsonStreamSSE ??
+    ((url, body, headers, timeout) =>
+      postJsonStream(url, body, headers, timeout).pipe(
+        Stream.filter((line) => line.startsWith("data: ")),
+        Stream.map((line) => line.slice("data: ".length).trim()),
+        Stream.filter((payload) => payload.length > 0 && payload !== "[DONE]")
+      ))
+
+  return {
+    get,
+    postJson: primitives.postJson,
+    send,
+    postJsonStream,
+    postJsonStreamSSE
+  }
+}
+
+export interface RecordingHttpClient {
+  readonly client: HttpClientShape
+  readonly recorded: Effect.Effect<ReadonlyArray<HttpRequest>>
+}
+
+export const makeRecordingHttpClient = Effect.fn("@llm4ts/core/HttpClient.makeRecording")(
+  function* (
+    handler: (request: HttpRequest) => Effect.Effect<string, LlmError>,
+    streamHandler?: (request: HttpRequest) => Stream.Stream<string, LlmError>
+  ): Effect.fn.Return<RecordingHttpClient> {
+    const requests = yield* Ref.make<ReadonlyArray<HttpRequest>>([])
+    const record = (request: HttpRequest): Effect.Effect<void> =>
+      Ref.update(requests, (current) => [...current, request])
+
+    const postJson: HttpClientShape["postJson"] = (url, body, headers, timeout) => {
+      const request = HttpRequest.make({
+        method: "POST",
+        url,
+        body,
+        headers,
+        contentType: "application/json",
+        timeout
+      })
+      return record(request).pipe(Effect.andThen(handler(request)))
+    }
+
+    const client = makeHttpClient({
+      postJson,
+      get: (url, headers, timeout) => {
+        const request = HttpRequest.make({
+          method: "GET",
+          url,
+          headers,
+          timeout
+        })
+        return record(request).pipe(Effect.andThen(handler(request)))
+      },
+      send: (method, url, body, headers, contentType, timeout) => {
+        const request = HttpRequest.make({
+          method,
+          url,
+          ...(body === undefined ? {} : { body }),
+          headers,
+          contentType,
+          timeout
+        })
+        return record(request).pipe(Effect.andThen(handler(request)))
+      },
+      ...(streamHandler === undefined
+        ? {}
+        : {
+            postJsonStream: (url, body, headers, timeout) => {
+              const request = HttpRequest.make({
+                method: "POST",
+                url,
+                body,
+                headers,
+                contentType: "application/json",
+                timeout
+              })
+              return Stream.concat(
+                Stream.drain(Stream.fromEffect(record(request))),
+                Stream.suspend(() => streamHandler(request))
+              )
+            }
+          })
+    })
+
+    return {
+      client,
+      recorded: Ref.get(requests)
+    }
+  }
+)
+
+export const httpGet = (
+  url: string,
+  headers: Readonly<Record<string, string>> = emptyHeaders,
+  timeout: Duration.Duration
+): Effect.Effect<string, LlmError, HttpClient> =>
+  Effect.flatMap(HttpClient, (client) => client.get(url, headers, timeout))
+
+export const httpPostJson = (
+  url: string,
+  body: string,
+  headers: Readonly<Record<string, string>> = emptyHeaders,
+  timeout: Duration.Duration
+): Effect.Effect<string, LlmError, HttpClient> =>
+  Effect.flatMap(HttpClient, (client) => client.postJson(url, body, headers, timeout))

package/src/LlmService.ts

@@ -0,0 +1,45 @@
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as Stream from "effect/Stream"
+import type * as Schema from "effect/Schema"
+import type { LlmError } from "./Errors.ts"
+import type {
+  JsonSchema,
+  LlmChunk,
+  Message,
+  TokenUsage,
+  ToolCallResponse,
+  ToolDefinition
+} from "./Models.ts"
+
+export type StructuredResult<A> = readonly [
+  value: A,
+  usage: TokenUsage | undefined,
+  model: string | undefined
+]
+
+export interface LlmServiceShape {
+  readonly executeStream: (prompt: string) => Stream.Stream<LlmChunk, LlmError>
+  readonly executeStreamWithHistory: (
+    messages: ReadonlyArray<Message>
+  ) => Stream.Stream<LlmChunk, LlmError>
+  readonly executeWithTools: (
+    prompt: string,
+    tools: ReadonlyArray<ToolDefinition>
+  ) => Effect.Effect<ToolCallResponse, LlmError>
+  readonly executeStructured: <A, E, RD, RE>(
+    prompt: string,
+    schema: Schema.ConstraintCodec<A, E, RD, RE>,
+    jsonSchema: JsonSchema
+  ) => Effect.Effect<A, LlmError, RD>
+  readonly executeStructuredWithUsage: <A, E, RD, RE>(
+    prompt: string,
+    schema: Schema.ConstraintCodec<A, E, RD, RE>,
+    jsonSchema: JsonSchema
+  ) => Effect.Effect<StructuredResult<A>, LlmError, RD>
+  readonly isAvailable: Effect.Effect<boolean>
+}
+
+export class LlmService extends Context.Service<LlmService, LlmServiceShape>()(
+  "@llm4ts/core/LlmService"
+) {}

package/src/Models.ts

@@ -0,0 +1,250 @@
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+export const LlmProvider = Schema.Literals([
+  "GeminiCli",
+  "GeminiApi",
+  "OpenAI",
+  "Anthropic",
+  "LmStudio",
+  "Ollama",
+  "OpenCode",
+  "Mock"
+])
+export type LlmProvider = typeof LlmProvider.Type
+
+export class ConnectorId extends Schema.Class<ConnectorId>("ConnectorId")({
+  value: Schema.String
+}) {}
+
+export const ConnectorIds = Object.freeze({
+  OpenAI: new ConnectorId({ value: "openai" }),
+  Anthropic: new ConnectorId({ value: "anthropic" }),
+  GeminiApi: new ConnectorId({ value: "gemini-api" }),
+  LmStudio: new ConnectorId({ value: "lm-studio" }),
+  Ollama: new ConnectorId({ value: "ollama" }),
+  ClaudeCli: new ConnectorId({ value: "claude-cli" }),
+  GeminiCli: new ConnectorId({ value: "gemini-cli" }),
+  OpenCode: new ConnectorId({ value: "opencode" }),
+  Codex: new ConnectorId({ value: "codex" }),
+  Copilot: new ConnectorId({ value: "copilot" }),
+  Pi: new ConnectorId({ value: "pi" }),
+  AntigravityCli: new ConnectorId({ value: "antigravity-cli" }),
+  Grok: new ConnectorId({ value: "grok" }),
+  Cursor: new ConnectorId({ value: "cursor" }),
+  Mock: new ConnectorId({ value: "mock" })
+})
+
+export const apiConnectorIds: ReadonlyArray<ConnectorId> = Object.freeze([
+  ConnectorIds.OpenAI,
+  ConnectorIds.Anthropic,
+  ConnectorIds.GeminiApi,
+  ConnectorIds.LmStudio,
+  ConnectorIds.Ollama
+])
+
+export const cliConnectorIds: ReadonlyArray<ConnectorId> = Object.freeze([
+  ConnectorIds.ClaudeCli,
+  ConnectorIds.GeminiCli,
+  ConnectorIds.OpenCode,
+  ConnectorIds.Codex,
+  ConnectorIds.Copilot,
+  ConnectorIds.Pi,
+  ConnectorIds.AntigravityCli,
+  ConnectorIds.Grok,
+  ConnectorIds.Cursor
+])
+
+export const connectorIds: ReadonlyArray<ConnectorId> = Object.freeze([
+  ...apiConnectorIds,
+  ...cliConnectorIds,
+  ConnectorIds.Mock
+])
+
+export const defaultBaseUrl = (provider: LlmProvider): string | undefined => {
+  switch (provider) {
+    case "GeminiCli":
+    case "Mock":
+      return undefined
+    case "GeminiApi":
+      return "https://generativelanguage.googleapis.com"
+    case "OpenAI":
+      return "https://api.openai.com/v1"
+    case "Anthropic":
+      return "https://api.anthropic.com"
+    case "LmStudio":
+      return "http://localhost:1234/v1"
+    case "Ollama":
+      return "http://localhost:11434"
+    case "OpenCode":
+      return "http://localhost:4096"
+  }
+}
+
+const connectorProviderTable: Readonly<Record<string, LlmProvider>> = {
+  openai: "OpenAI",
+  anthropic: "Anthropic",
+  "gemini-api": "GeminiApi",
+  "lm-studio": "LmStudio",
+  ollama: "Ollama",
+  opencode: "OpenCode",
+  "gemini-cli": "GeminiCli",
+  mock: "Mock"
+}
+
+export const connectorProvider = (id: ConnectorId): LlmProvider | undefined =>
+  connectorProviderTable[id.value]
+
+export const connectorDefaultBaseUrl = (id: ConnectorId): string | undefined => {
+  const provider = connectorProvider(id)
+  return provider === undefined ? undefined : defaultBaseUrl(provider)
+}
+
+export const providerConnectorId = (provider: LlmProvider): ConnectorId => {
+  switch (provider) {
+    case "GeminiCli":
+      return ConnectorIds.GeminiCli
+    case "GeminiApi":
+      return ConnectorIds.GeminiApi
+    case "OpenAI":
+      return ConnectorIds.OpenAI
+    case "Anthropic":
+      return ConnectorIds.Anthropic
+    case "LmStudio":
+      return ConnectorIds.LmStudio
+    case "Ollama":
+      return ConnectorIds.Ollama
+    case "OpenCode":
+      return ConnectorIds.OpenCode
+    case "Mock":
+      return ConnectorIds.Mock
+  }
+}
+
+export const ConnectorKind = Schema.Literals(["Api", "Cli"])
+export type ConnectorKind = typeof ConnectorKind.Type
+
+export const MessageRole = Schema.Literals(["System", "User", "Assistant", "Tool"])
+export type MessageRole = typeof MessageRole.Type
+
+export class Message extends Schema.Class<Message>("Message")({
+  role: MessageRole,
+  content: Schema.String
+}) {}
+
+export class TokenUsage extends Schema.Class<TokenUsage>("TokenUsage")({
+  prompt: Schema.Int,
+  completion: Schema.Int,
+  total: Schema.Int,
+  cached: Schema.optionalKey(Schema.Int)
+}) {}
+
+const emptyMetadata: Readonly<Record<string, string>> = Object.freeze({})
+
+export class LlmResponse extends Schema.Class<LlmResponse>("LlmResponse")({
+  content: Schema.String,
+  usage: Schema.optionalKey(TokenUsage),
+  metadata: Schema.Record(Schema.String, Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyMetadata))
+  )
+}) {}
+
+export class LlmChunk extends Schema.Class<LlmChunk>("LlmChunk")({
+  delta: Schema.String,
+  finishReason: Schema.optionalKey(Schema.String),
+  usage: Schema.optionalKey(TokenUsage),
+  metadata: Schema.Record(Schema.String, Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyMetadata))
+  )
+}) {}
+
+export class StreamProgress extends Schema.Class<StreamProgress>("StreamProgress")({
+  tokensProcessed: Schema.Int,
+  tokensPerSecond: Schema.Number,
+  elapsedMs: Schema.Int,
+  estimatedRemainingMs: Schema.optionalKey(Schema.Int)
+}) {}
+
+export class LlmConfig extends Schema.Class<LlmConfig>("LlmConfig")({
+  provider: LlmProvider,
+  model: Schema.String,
+  baseUrl: Schema.optionalKey(Schema.String),
+  apiKey: Schema.optionalKey(
+    Schema.Redacted(Schema.String, {
+      disallowJsonEncode: true
+    })
+  ),
+  timeout: Schema.Duration.pipe(
+    Schema.withConstructorDefault(Effect.succeed(Duration.seconds(300)))
+  ),
+  maxRetries: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(3))),
+  requestsPerMinute: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(60))),
+  burstSize: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(10))),
+  acquireTimeout: Schema.Duration.pipe(
+    Schema.withConstructorDefault(Effect.succeed(Duration.seconds(30)))
+  ),
+  temperature: Schema.optionalKey(Schema.Number),
+  maxTokens: Schema.optionalKey(Schema.Int)
+}) {}
+
+export const withConfigDefaults = (config: LlmConfig): LlmConfig => {
+  if (config.baseUrl !== undefined) {
+    return config
+  }
+
+  const baseUrl = defaultBaseUrl(config.provider)
+  return baseUrl === undefined ? config : new LlmConfig({ ...config, baseUrl })
+}
+
+export class ToolCall extends Schema.Class<ToolCall>("ToolCall")({
+  id: Schema.String,
+  name: Schema.String,
+  arguments: Schema.String
+}) {}
+
+const emptyToolCalls: ReadonlyArray<ToolCall> = Object.freeze([])
+
+export class ToolCallResponse extends Schema.Class<ToolCallResponse>("ToolCallResponse")({
+  content: Schema.optionalKey(Schema.String),
+  toolCalls: Schema.Array(ToolCall).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyToolCalls))
+  ),
+  finishReason: Schema.String
+}) {}
+
+export const JsonSchema = Schema.Record(Schema.String, Schema.Json)
+export type JsonSchema = typeof JsonSchema.Type
+
+export class ToolDefinition extends Schema.Class<ToolDefinition>("ToolDefinition")({
+  name: Schema.String,
+  description: Schema.String,
+  parameters: JsonSchema
+}) {}
+
+export const Availability = Schema.Literals(["Healthy", "Degraded", "Unhealthy", "Unknown"])
+export type Availability = typeof Availability.Type
+
+export const AuthStatus = Schema.Literals(["Valid", "Missing", "Invalid", "Unknown"])
+export type AuthStatus = typeof AuthStatus.Type
+
+export class HealthStatus extends Schema.Class<HealthStatus>("HealthStatus")({
+  availability: Availability,
+  authStatus: AuthStatus,
+  latency: Schema.optionalKey(Schema.Duration)
+}) {}
+
+export const InteractionSupport = Schema.Literals(["InteractiveStdin", "ContinuationOnly"])
+export type InteractionSupport = typeof InteractionSupport.Type
+
+export class ConnectorCapabilities extends Schema.Class<ConnectorCapabilities>(
+  "ConnectorCapabilities"
+)({
+  streaming: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(true))),
+  resumableSessions: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
+  interactiveSessions: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
+  askUser: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
+  approval: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
+  structuredOutput: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(true))),
+  usageReporting: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(true)))
+}) {}