@gammatech/aijsx 0.1.0-beta.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Fixie.ai
+
+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,224 @@
+# AIJSX
+
+> This is forked from [@fixie-ai/ai-jsx](https://github.com/fixie-ai/ai-jsx)
+
+**Reasons for forking**
+
+- Streamlined Library: We found that the original library, [@fixie-ai/ai-jsx], came with an abundance of tools, integrations, models, and features that surpassed our project's requirements. Our fork aims to provide a more focused and simplified version tailored to our needs.
+
+- Performance Optimization: The production instance of ai-jsx exhibited performance issues, consuming approximately 30MB of head memory per stream and displaying slow garbage collection. This behavior led to server restarts. Our fork addresses these concerns, optimizing performance and memory usage.
+
+- Tailored Functionality: We identified several features in the original library that were surplus to our project requirements. By eliminating unnecessary functionalities, we aim to create a leaner and faster library.
+
+### What is AIJSX?
+
+AIJSX is a framework/toolkit designed to facilitate the construction of Large Language Model (LLM) prompts in a composable and ergonomic manner by leveraging JSX.
+
+Example:
+
+```ts
+import {
+  OpenAIChatCompletion,
+  SystemMessage,
+  UserMessage,
+  createRenderContext,
+} from '@gammatech/aijsx'
+
+function JokePrompt(props: { input: string }) {
+  return (
+    <OpenAIChatCompletion>
+      <SysytemMessage>You are funny</SysytemMessage>
+      <UserMessage>Tell me a joke about: {props.input}</UserMessage>
+    </OpenAIChatCompletion>
+  )
+}
+
+const result = await createRenderContext().render(
+  <JokePrompt input="bananas" />
+)
+```
+
+### Why JSX?
+
+- JSX facilitates the mixing of string interpolation and control flow logic in a type-safe and familiar manner.
+
+- JSX excels in handling composition, allowing the chaining of prompt results to the input of another.
+
+- JSX enjoys widespread support across various build systems and does not necessitate a one-off compilation for string-based templating.
+
+It's important to note that using JSX is distinct from using React. JSX is compile-time sugar that converts a component into a function call. In contrast, React + ReactDOM is a framework responsible for synchronizing the state of a virtual representation of the DOM with an actual browser DOM. AIJSX leverages JSX more akin to using React.renderToString.
+
+### How AIJSX Works to Build Prompts
+
+In its simplest form, AIJSX transforms a tree of JSX components into a string. This resulting string can serve as input to an LLM call or be returned via API, offering flexibility in usage. Unlike React, where components may need to respond to updates and state changes, AIJSX follows a render-once-and-done approach.
+
+### Differences between AIJSX and React
+
+**React's Component Type Signature**
+
+```ts
+type Component = (props: P) => React.Element
+```
+
+**AIJSX Component Type Signature**
+
+```ts
+export interface RenderableStream {
+  [Symbol.asyncIterator]: () => AsyncGenerator<string, void, unknown>
+}
+type AINode = Literal | AIElement<any> | AINode[]
+type Renderable = AINode | PromiseLike<Renderable> | RenderableStream
+
+type AIComponent = (props: P, context: RenderContext) => Renderable
+```
+
+AIComponents in AIJSX can return two additional types: `PromiseLike<Renderable>` and `RenderableStream`. This distinction fundamentally changes the rendering paradigm in AIJSX, introducing asynchronous rendering that can return either a `Promise` or an object with access to an `AsyncGenerator` (`RenderableStream`).
+
+The asynchronous render abstraction is powerful, allowing chaining of results from asynchronous operations (such as an LLM API call) to the input of another component.
+
+Example:
+
+```ts
+const GetLang: AIComponent<{ children: AINode }> = (
+  { children },
+  { render }
+) => {
+  const renderedChildren = await render(children)
+  const language = await determineLanguage(renderedChildren)
+
+  return language
+}
+```
+
+You'll notice several differences from normal React components. The second argument to `AIComponent` is the `RenderContext` object, which has a `render` method, allowing us to resolve the value of this components children and use them as inputs to an API call.
+
+Because `GetLang` returns `Promise<string>` which matches the signature of a `Renderable` in AIJSX we can use it as an input in another component
+
+```ts
+import {
+  OpenAIChatCompletion,
+  SystemMessage,
+  UserMessage,
+  createRenderContext,
+} from '@gammatech/aijsx'
+
+const WritePoem: AIComponent<{ input: string }> = (
+  { sentence },
+  { logger }
+) => {
+  return (
+    <OpenAIChatCompletion>
+      <SysytemMessage>You are a world class poet</SysytemMessage>
+      <UserMessage>
+        Write a poem about "{sentence}" in <GetLang>{sentence}</GetLang>
+      </UserMessage>
+    </OpenAIChatCompletion>
+  )
+}
+
+const result = createRenderContext.render(<WritePoem input="公共車" />)
+```
+
+The above code will first render all of the elements under `<OpenAIChatCompletion>`
+
+```ts
+<OpenAIChatCompletion>
+  <SysytemMessage>You are a world class poet</SysytemMessage>
+  <UserMessage>
+    Write a poem about "公共車" in <GetLang>公共車</GetLang>
+  </UserMessage>
+</OpenAIChatCompletion>
+```
+
+```ts
+<OpenAIChatCompletion>
+  <SysytemMessage>You are a world class poet</SysytemMessage>
+  <UserMessage>Write a poem about "公共車" in Simplified Chinese</UserMessage>
+</OpenAIChatCompletion>
+```
+
+# Recipes
+
+## Logging
+
+`createRenderContext` can take a `logger: LogImplementation` option. This is used as the base logger when the `RenderContext` traverses the component tree and passes `Logger` to each component.
+
+At the very least, extenders of `LogImplementation` must implement:
+
+```ts
+abstract log(ctx: RenderContext, level: LogLevel, message: string): void
+```
+
+## Creating Components
+
+**Basic synchronous components**
+
+```tsx
+const Text: AIComponent<{ children: AINode }> = ({ children }) => {
+  return (
+    <>
+      {children}
+      {'\n'}
+    </>
+  )
+}
+```
+
+**Creating Async Components**
+
+```tsx
+const AsyncComponent: AIComponent<{ input: string }> = async ({ input }) => {
+  const result = await someApICall(input)
+  return <>result: {result}</>
+}
+```
+
+**Creating AsyncGenerator Components**
+
+```tsx
+async function* GeneratorComponent(props: { input: string }) {
+  yield 'this '
+  yield 'is '
+  yield 'a '
+  yield 'test'
+
+  // NOTE: AsyncGenerator component in AIJSX do not return values, and it's assumed that
+  // there yielded results should be string concattenated together
+}
+
+async function* GeneratorComponent2(props: { input: string }) {
+  return yield* someAsyncGeneratingFunction(input)
+}
+```
+
+# API Reference
+
+### Top Level Methods
+
+`createRenderContext` - creates a render context used to render a
+
+```ts
+export function createRenderContext(opts: {
+  logger?: LogImplementation
+  rootRenderId?: string
+}): RenderContext
+
+export interface RenderContext {
+  parentContext: RenderContext | null
+
+  element: AIElement<any>
+
+  renderId: string
+
+  logger: Logger
+
+  getContext<T>(context: Context<T>): T
+
+  render(renderable: Renderable): RenderResult
+}
+```
+
+**args**
+
+- `logger?: LogImplementation` - Defualts to `NoopLogImplementation`
+- `rootRenderId?: string` - allows setting the root RenderContext's renderId, auto-generates a nanoid if left undefined

package/dist/createElement-Q_LxUYf8.d.ts

@@ -0,0 +1,159 @@
+type Literal = string | number | null | undefined | boolean;
+interface RenderableStream {
+    [Symbol.asyncIterator]: () => AsyncGenerator<string, void, unknown>;
+}
+interface RenderResult extends RenderableStream {
+    then: (onResolved: (value: string) => void, onRejected?: (reason?: any) => void) => void;
+}
+interface Context<T> {
+    Provider: AIComponent<{
+        children: AINode;
+        value: T;
+    }>;
+    defaultValue: T;
+    key: symbol;
+}
+type AIComponent<P> = (props: P, context: RenderContext) => Renderable;
+declare const attachedContextSymbol: unique symbol;
+interface AIElement<P> {
+    /** The tag associated with this {@link AIElement}. */
+    tag: AIComponent<P>;
+    /** The component properties. */
+    props: P;
+    /** A function that renders this {@link AIElement} to a {@link Renderable}. */
+    render: (ctx: RenderContext) => Renderable;
+    /** The {@link RenderContext} associated with this {@link Element}. */
+    [attachedContextSymbol]?: Record<symbol, any>;
+}
+type AINode = Literal | AIElement<any> | AINode[];
+type Renderable = AINode | PromiseLike<Renderable> | RenderableStream;
+type PropsOfAIComponent<T extends AIComponent<any>> = T extends AIComponent<infer P> ? P : never;
+
+declare const LoggerContext: Context<LogImplementation>;
+interface RenderContext {
+    parentContext: RenderContext | null;
+    element: AIElement<any>;
+    renderId: string;
+    logger: Logger;
+    getContext<T>(context: Context<T>): T;
+    render(renderable: Renderable): RenderResult;
+}
+declare function createContext<T>(defaultValue: T): Context<T>;
+
+/**
+ * This can be extended using declare module to add additional providers.
+ */
+interface ChatCompletionRequestPayloads {
+}
+interface LogChatCompletionRequest<R extends Record<string, any> = ChatCompletionRequestPayloads[keyof ChatCompletionRequestPayloads]> {
+    startTime: number;
+    model: string;
+    providerRegion?: string;
+    provider?: string;
+    inputMessages: RenderedConversationMessage[];
+    request: R;
+}
+interface LogChatCompletionResponse<R extends Record<string, any> = ChatCompletionRequestPayloads[keyof ChatCompletionRequestPayloads]> extends LogChatCompletionRequest<R> {
+    latency: number;
+    outputMessage: RenderedConversationMessage;
+    finishReason: string;
+    tokensUsed: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+}
+type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+type Loggable = string | number | boolean | undefined | null | object;
+type Logger = {
+    error: (...msg: Loggable[]) => void;
+    warn: (...msg: Loggable[]) => void;
+    info: (...msg: Loggable[]) => void;
+    debug: (...msg: Loggable[]) => void;
+    logException: (exception: unknown) => void;
+    chatCompletionRequest: <K extends keyof ChatCompletionRequestPayloads>(provider: K, payload: LogChatCompletionRequest<ChatCompletionRequestPayloads[K]>) => void;
+    chatCompletionResponse: <K extends keyof ChatCompletionRequestPayloads>(provider: K, payload: LogChatCompletionResponse<ChatCompletionRequestPayloads[K]>) => void;
+};
+declare abstract class LogImplementation {
+    protected readonly loggedExceptions: WeakMap<object, boolean>;
+    /**
+     * @param ctx The current RenderContext
+     * @param level The log level, e.g. 'error', 'warn', 'info', 'debug'
+     * @param message
+     */
+    abstract log(ctx: RenderContext, level: LogLevel, message: string): void;
+    /**
+     * Logs exceptions thrown during an element's render.
+     */
+    logException(ctx: RenderContext, exception: unknown): void;
+    chatCompletionRequest<K extends keyof ChatCompletionRequestPayloads>(_ctx: RenderContext, _provider: K, _payload: LogChatCompletionRequest<ChatCompletionRequestPayloads[K]>): void;
+    chatCompletionResponse<K extends keyof ChatCompletionRequestPayloads>(_ctx: RenderContext, _provider: K, _payload: LogChatCompletionResponse<ChatCompletionRequestPayloads[K]>): void;
+}
+declare class BoundLogger implements Logger {
+    private readonly impl;
+    private readonly ctx;
+    constructor(impl: LogImplementation, ctx: RenderContext);
+    private formatMessage;
+    error: (...msgs: Loggable[]) => void;
+    warn: (...msgs: Loggable[]) => void;
+    info: (...msgs: Loggable[]) => void;
+    debug: (...msgs: Loggable[]) => void;
+    logException: (exception: unknown) => void;
+    chatCompletionRequest: <K extends keyof ChatCompletionRequestPayloads>(provider: K, payload: LogChatCompletionRequest<ChatCompletionRequestPayloads[K]>) => void;
+    chatCompletionResponse: <K extends keyof ChatCompletionRequestPayloads>(provider: K, payload: LogChatCompletionResponse<ChatCompletionRequestPayloads[K]>) => void;
+}
+declare class NoopLogImplementation extends LogImplementation {
+    log(_ctx: RenderContext, _level: LogLevel, _message: string): void;
+}
+declare class ConsoleLogger extends LogImplementation {
+    log(ctx: RenderContext, level: LogLevel, message: string): void;
+}
+declare class CombinedLogger extends LogImplementation {
+    private readonly loggers;
+    constructor(loggers: LogImplementation[]);
+    log(...args: Parameters<LogImplementation['log']>): void;
+    chatCompletionRequest<K extends keyof ChatCompletionRequestPayloads>(...args: Parameters<LogImplementation['chatCompletionRequest']>): void;
+    chatCompletionResponse<K extends keyof ChatCompletionRequestPayloads>(...args: Parameters<LogImplementation['chatCompletionResponse']>): void;
+}
+
+type ChatCompletionRole = 'user' | 'system' | 'assistant';
+declare const SystemMessage: (props: {
+    children: AINode;
+}) => AINode;
+declare const UserMessage: (props: {
+    children: AINode;
+}) => AINode;
+declare const AssistantMessage: (props: {
+    children: AINode;
+}) => AINode;
+interface ConversationMessageType<T extends ChatCompletionRole, C extends AIComponent<any>> {
+    type: T;
+    element: AIElement<PropsOfAIComponent<C>>;
+}
+type ConversationMessage = ConversationMessageType<'user', typeof UserMessage> | ConversationMessageType<'assistant', typeof AssistantMessage> | ConversationMessageType<'system', typeof SystemMessage>;
+type RenderedConversationMessage = ConversationMessage & {
+    content: string;
+    tokens: number;
+};
+declare const childrenToConversationMessage: (c: AIElement<any> | AIElement<any>[]) => ConversationMessage[];
+declare const computeUsage: (messages: RenderedConversationMessage[]) => {
+    prompt: number;
+    completion: number;
+    total: number;
+};
+declare class ChatCompletionError extends Error {
+    readonly chatCompletionRequest: LogChatCompletionRequest;
+    constructor(message: string, chatCompletionRequest: LogChatCompletionRequest);
+}
+
+declare function createAIElement<P extends {
+    children: C;
+}, C>(tag: AIComponent<P>, props: Omit<P, 'children'> | null, ...children: [C]): AIElement<P>;
+declare function createAIElement<P extends {
+    children: C[];
+}, C>(tag: AIComponent<P>, props: Omit<P, 'children'> | null, ...children: C[]): AIElement<P>;
+declare function AIFragment({ children }: {
+    children: AINode;
+}): Renderable;
+
+export { type AIElement as A, BoundLogger as B, type Context as C, LogImplementation as L, NoopLogImplementation as N, type PropsOfAIComponent as P, type RenderContext as R, SystemMessage as S, UserMessage as U, type RenderedConversationMessage as a, AIFragment as b, createAIElement as c, LoggerContext as d, createContext as e, AssistantMessage as f, type ConversationMessage as g, childrenToConversationMessage as h, computeUsage as i, ChatCompletionError as j, type ChatCompletionRequestPayloads as k, type LogChatCompletionRequest as l, type LogChatCompletionResponse as m, type LogLevel as n, type Logger as o, ConsoleLogger as p, CombinedLogger as q, type Literal as r, type RenderableStream as s, type RenderResult as t, type AIComponent as u, attachedContextSymbol as v, type AINode as w, type Renderable as x };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { L as LogImplementation, R as RenderContext, C as Context, A as AIElement, a as RenderedConversationMessage } from './createElement-Q_LxUYf8.js';
+export { u as AIComponent, b as AIFragment, w as AINode, f as AssistantMessage, B as BoundLogger, j as ChatCompletionError, k as ChatCompletionRequestPayloads, q as CombinedLogger, p as ConsoleLogger, g as ConversationMessage, r as Literal, l as LogChatCompletionRequest, m as LogChatCompletionResponse, n as LogLevel, o as Logger, d as LoggerContext, N as NoopLogImplementation, P as PropsOfAIComponent, t as RenderResult, x as Renderable, s as RenderableStream, S as SystemMessage, U as UserMessage, v as attachedContextSymbol, h as childrenToConversationMessage, i as computeUsage, c as createAIElement, e as createContext } from './createElement-Q_LxUYf8.js';
+import { OpenAI } from 'openai';
+export { OpenAI as OpenAIClient } from 'openai';
+import AnthropicClient from '@anthropic-ai/sdk';
+export { default as AnthropicClient } from '@anthropic-ai/sdk';
+export { countTokens as countAnthropicTokens } from '@anthropic-ai/tokenizer';
+
+declare function createRenderContext({ logger, rootRenderId, }?: {
+    logger?: LogImplementation;
+    rootRenderId?: string;
+}): RenderContext;
+
+type OpenAIChatCompletionRequest = OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming;
+declare module '@gammatech/aijsx' {
+    interface ChatCompletionRequestPayloads {
+        openai: OpenAIChatCompletionRequest;
+    }
+}
+type ValidOpenAIChatModel = 'gpt-4' | 'gpt-4-0314' | 'gpt-4-0613' | 'gpt-4-32k' | 'gpt-4-32k-0314' | 'gpt-4-32k-0613' | 'gpt-4-1106-preview' | 'gpt-3.5-turbo' | 'gpt-3.5-turbo-0301' | 'gpt-3.5-turbo-0613' | 'gpt-3.5-turbo-16k' | 'gpt-3.5-turbo-16k-0613' | 'gpt-3.5-turbo-1106';
+declare const OpenAIClientContext: Context<() => OpenAI>;
+type OpenAIChatCompletionProps = {
+    model: ValidOpenAIChatModel;
+    maxTokens?: number;
+    temperature?: number;
+    children: AIElement<any> | AIElement<any>[];
+    provider?: string;
+    providerRegion?: string;
+};
+declare function OpenAIChatCompletion(props: OpenAIChatCompletionProps, { logger, render, getContext }: RenderContext): AsyncGenerator<string, void, unknown>;
+
+declare const tokenizer: {
+    encode: (text: string) => number[];
+    decode: (tokens: number[]) => string;
+};
+declare function tokenLimitForChatModel(model: ValidOpenAIChatModel): number | undefined;
+declare function tokenCountForConversationMessage(message: Pick<RenderedConversationMessage, 'type' | 'content'>): number;
+
+type AnthropicChatCompletionRequest = AnthropicClient.CompletionCreateParams;
+declare module '@gammatech/aijsx' {
+    interface ChatCompletionRequestPayloads {
+        anthropic: AnthropicChatCompletionRequest;
+    }
+}
+/**
+ * The set of valid Claude models.
+ * @see https://docs.anthropic.com/claude/reference/selecting-a-model
+ */
+type ValidAnthropicChatModel = 'claude-instant-1.2' | 'claude-2.1';
+declare const AnthropicClientContext: Context<() => AnthropicClient>;
+/**
+ * If you use an Anthropic model without specifying the max tokens for the completion, this value will be used as the default.
+ */
+declare const defaultMaxTokens = 4096;
+type AnthropicChatCompletionProps = {
+    model: ValidAnthropicChatModel;
+    maxTokens?: number;
+    temperature?: number;
+    children: AIElement<any> | AIElement<any>[];
+    provider?: string;
+    providerRegion?: string;
+};
+/**
+ * An AI.JSX component that invokes an Anthropic Large Language Model.
+ * @param children The children to render.
+ * @param chatModel The chat model to use.
+ * @param completionModel The completion model to use.
+ * @param client The Anthropic client.
+ */
+declare function AnthropicChatCompletion(props: AnthropicChatCompletionProps, { render, logger, getContext }: RenderContext): AsyncGenerator<string, void, unknown>;
+
+export { AIElement, AnthropicChatCompletion, type AnthropicChatCompletionRequest, AnthropicClientContext, Context, LogImplementation, OpenAIChatCompletion, type OpenAIChatCompletionRequest, OpenAIClientContext, RenderContext, RenderedConversationMessage, type ValidAnthropicChatModel, type ValidOpenAIChatModel, createRenderContext, defaultMaxTokens, tokenCountForConversationMessage, tokenLimitForChatModel, tokenizer };