@pantheon.ai/mcp 0.0.1

package/packages/sdk/src/lib/api.ts

@@ -0,0 +1,265 @@
+import type { ApiExecutorContext } from "@pantheon/sdk/lib/api-executor"
+import { StreamResponseParser } from "@pantheon/sdk/lib/stream-parser"
+import { isValidator, type Validator } from "@pantheon/sdk/lib/validator"
+import { parseTemplate, type PrimitiveValue, type Template } from "url-template"
+import type { ZodType } from "zod"
+
+export type ApiMethod = "get" | "post" | "put" | "delete" | "patch"
+
+export type PhantomType<T> = {
+  readonly __phantom_type__: T
+}
+
+export function typeOf<T>(): PhantomType<T> {
+  return null as never as PhantomType<T>
+}
+
+type ParamsTypeOf<Params extends readonly string[]> = Params extends []
+  ? null
+  : {
+      [K in Params[number] as K extends `${infer Name}?` ? Name : never]?:
+        | PrimitiveValue
+        | PrimitiveValue[]
+    } & {
+      [K in Params[number] as K extends `${string}?` ? never : K]:
+        | PrimitiveValue
+        | PrimitiveValue[]
+    }
+
+declare global {
+  interface RequestInit {
+    duplex?: "half"
+  }
+}
+
+export interface Api<
+  Method extends ApiMethod,
+  Params extends Record<string, PrimitiveValue | PrimitiveValue[]> | null,
+  RequestBody,
+  ResponseBody,
+> {
+  readonly method: Method
+  readonly signature: string
+  readonly url: Params extends null ? () => string : (params: Params) => string
+  readonly requestInit: Method extends "get" | "delete"
+    ? () => Pick<RequestInit, "headers" | "duplex" | "method" | "body">
+    : (
+        body: RequestBody
+      ) => Pick<RequestInit, "headers" | "duplex" | "method" | "body">
+  readonly handleResponse: (
+    response: Response,
+    context: ApiExecutorContext
+  ) => Promise<ResponseBody>
+}
+
+export type ApiParams<API> = API extends Api<any, infer P, any, any> ? P : never
+export type ApiRequestBody<API> =
+  API extends Api<any, any, infer B, any> ? B : never
+export type ApiResponseBody<API> =
+  API extends Api<any, any, any, infer R> ? R : never
+
+interface UrlTemplate<
+  Method extends ApiMethod,
+  Params extends Record<string, PrimitiveValue | PrimitiveValue[]> | null,
+> {
+  readonly method: Method
+  readonly templateUrl: string
+  readonly signature: string
+  readonly template: Template
+  readonly __params__: PhantomType<Params>
+}
+
+function createUrlTemplate<Method extends ApiMethod>(method: Method) {
+  return function <Params extends string[]>(
+    arr: TemplateStringsArray,
+    ...params: Params
+  ): UrlTemplate<Method, ParamsTypeOf<Params>> {
+    let url = arr[0]
+    let expandedPaths = false
+    for (let i = 1; i < arr.length; i++) {
+      if (params[i - 1] === "path*") {
+        url += "<path*>"
+        expandedPaths = true
+      } else {
+        url += "{" + params[i - 1].replace(/\?$/, "") + "}" + arr[i]
+      }
+    }
+
+    const [pathPart, searchPart] = url.split("?")
+
+    const pathPartTemplate: Template = expandedPaths
+      ? {
+          expand: (context) => {
+            return parseTemplate(
+              pathPart.replace(
+                /<path\*>/,
+                String(context["path*"]).replace(/^\//, "")
+              )
+            ).expand(context)
+          },
+        }
+      : parseTemplate(pathPart)
+
+    // key={template_value}, this will allow array values.
+    // key=prefix-{value}, this will go through the normal template expansion.
+    // key=constant, will be added as is.
+    const searchParamsBuilders: Array<
+      (usp: URLSearchParams, context: Record<string, any>) => void
+    > = []
+
+    if (searchPart) {
+      searchPart.split("&").forEach((entry) => {
+        const [key, value = ""] = entry.split("=").map(decodeURIComponent)
+
+        if (/^\{[^}]+}$/.test(value)) {
+          const templateValue = value.slice(1, -1)
+          searchParamsBuilders.push((usp, context) => {
+            if (templateValue in context) {
+              const value = context[templateValue]
+              if (value === undefined) {
+                return
+              }
+              if (Array.isArray(value)) {
+                value.forEach((v) => usp.append(key, String(v)))
+              } else {
+                usp.append(key, String(value))
+              }
+            }
+          })
+        } else if (value !== "") {
+          const template = parseTemplate(value)
+
+          searchParamsBuilders.push((usp, context) => {
+            usp.append(key, template.expand(context))
+          })
+        } else {
+          searchParamsBuilders.push((usp) => {
+            usp.append(key, "")
+          })
+        }
+      })
+    }
+
+    return {
+      method,
+      signature: `${method} ${url}`,
+      templateUrl: url,
+      template: {
+        expand: (context) => {
+          const pathPart = pathPartTemplate.expand(context)
+          const usp = new URLSearchParams()
+          searchParamsBuilders.forEach((template) => {
+            template(usp, context)
+          })
+
+          if (Array.from(usp).length > 0) {
+            return pathPart + "?" + usp.toString()
+          } else {
+            return pathPart
+          }
+        },
+      },
+      __params__: typeOf<ParamsTypeOf<Params>>(),
+    }
+  }
+}
+
+export const get = createUrlTemplate("get")
+export const post = createUrlTemplate("post")
+export const put = createUrlTemplate("put")
+export const del = createUrlTemplate("delete")
+export const patch = createUrlTemplate("patch")
+
+type ParamsOf<T extends UrlTemplate<any, any>> = [T] extends [
+  UrlTemplate<any, infer O>,
+]
+  ? O
+  : null
+type MethodOf<T extends UrlTemplate<any, any>> = [T] extends [
+  UrlTemplate<infer O, any>,
+]
+  ? O
+  : never
+
+type ResponseSchemaType =
+  | ZodType<any>
+  | StreamResponseParser<any>
+  | Validator<any>
+  | "raw"
+type inferResponse<ResponseSchema extends ResponseSchemaType> =
+  ResponseSchema extends Validator<infer O>
+    ? O
+    : ResponseSchema extends ZodType<infer O>
+      ? O
+      : ResponseSchema extends StreamResponseParser<infer O>
+        ? ReadableStream<O>
+        : ResponseSchema extends "raw"
+          ? Response
+          : never
+
+export function defineApi<
+  UrlTemplateParameter extends UrlTemplate<any, any>,
+  RequestBody = void,
+  ResponseSchema extends ResponseSchemaType = "raw",
+>(
+  urlTemplate: UrlTemplateParameter,
+  _type: MethodOf<UrlTemplateParameter> extends "get" | "delete"
+    ? null
+    : PhantomType<RequestBody> | null,
+  responseSchema: ResponseSchema
+) {
+  type Method = MethodOf<UrlTemplateParameter>
+  type Params = ParamsOf<UrlTemplateParameter>
+  type ResponseBody = inferResponse<ResponseSchema>
+  const method = urlTemplate.method
+
+  const api: Api<Method, Params, RequestBody, ResponseBody> = {
+    method: urlTemplate.method,
+    signature: urlTemplate.signature,
+    url: ((params: any | null) =>
+      urlTemplate.template.expand(params ?? {})) as any,
+    requestInit: (
+      body?: any
+    ): Pick<RequestInit, "headers" | "duplex" | "method" | "body"> => {
+      if (method === "get" || method === "delete") {
+        return {
+          method,
+        }
+      }
+
+      if (body instanceof ReadableStream) {
+        return {
+          method,
+          body,
+          duplex: "half",
+        }
+      } else if (body instanceof FormData) {
+        return {
+          method,
+          body,
+        }
+      } else {
+        return {
+          method,
+          body: JSON.stringify(body),
+          headers: {
+            "Content-Type": "application/json",
+          },
+        }
+      }
+    },
+    handleResponse: async (response, context) => {
+      if (responseSchema instanceof StreamResponseParser) {
+        return responseSchema.handleResponse(response, context)
+      } else if (responseSchema === "raw") {
+        return response
+      } else if (isValidator(responseSchema)) {
+        return responseSchema.parse(response)
+      } else {
+        return responseSchema.parse(await response.json())
+      }
+    },
+  }
+
+  return api
+}

package/packages/sdk/src/lib/stream-parser.ts

@@ -0,0 +1,30 @@
+import type { ApiExecutorContext } from "@pantheon/sdk/lib/api-executor"
+
+export interface StreamResponseParserOptions<Output> {
+  readonly validateResponse?: (response: Response) => void | Promise<void>
+  readonly pipe: (
+    input: ReadableStream<BufferSource>,
+    context: ApiExecutorContext & { readonly response: Response }
+  ) => ReadableStream<Output>
+}
+
+export class StreamResponseParser<Output> {
+  private readonly options: StreamResponseParserOptions<Output>
+
+  constructor(options: StreamResponseParserOptions<Output>) {
+    this.options = options
+  }
+
+  async handleResponse(response: Response, context: ApiExecutorContext) {
+    this.options.validateResponse?.(response)
+
+    if (!response.body) {
+      throw new Error("Response body is missing")
+    }
+
+    return this.options.pipe(
+      response.body,
+      Object.freeze({ ...context, response })
+    )
+  }
+}

package/packages/sdk/src/lib/validator.ts

@@ -0,0 +1,19 @@
+import type { PhantomType } from "@pantheon/sdk/lib/api"
+
+export const VALIDATOR_SYMBOL = Symbol("validator")
+
+export interface Validator<Output> {
+  readonly [VALIDATOR_SYMBOL]: true
+  readonly __phantom__: PhantomType<Output>
+
+  parse(input: Response): Output | Promise<Output>
+}
+
+export function isValidator(object: any): object is Validator<unknown> {
+  return (
+    typeof object === "object" &&
+    object !== null &&
+    object[VALIDATOR_SYMBOL] === true &&
+    typeof object.parse === "function"
+  )
+}

package/packages/sdk/src/lib/vercel-ai-hack.ts

@@ -0,0 +1,133 @@
+import {
+  createStreamingUIMessageState,
+  processUIMessageStream,
+  type StreamingUIMessageState,
+  type UIMessage,
+  type UIMessageChunk,
+} from "ai"
+
+export async function fastReadUIMessageStream<UI_MESSAGE extends UIMessage>({
+  stream,
+  messageId,
+  onState,
+  state: propState,
+}: {
+  stream: ReadableStream<UIMessageChunk>
+  messageId: string
+  onState: (state: StreamingUIMessageState<UI_MESSAGE>) => void
+  state?: StreamingUIMessageState<UI_MESSAGE>
+}) {
+  const state =
+    propState ??
+    createStreamingUIMessageState<UI_MESSAGE>({
+      lastMessage: undefined,
+      messageId,
+    })
+
+  const res = processUIMessageStream<UI_MESSAGE>({
+    stream,
+    runUpdateMessageJob(
+      job: (options: {
+        state: StreamingUIMessageState<UI_MESSAGE>
+        write: () => void
+      }) => Promise<void>
+    ) {
+      return job({
+        state,
+        write: () => {},
+      })
+    },
+    onError: (error) => {
+      // ignore error chunk
+      state.message.metadata ??= {}
+      ;(state.message.metadata as any).__stream_error__ = (
+        error as Error
+      ).message
+    },
+  })
+
+  let chunks = 0
+
+  const reader = res.getReader()
+  while (true) {
+    const chunk = await reader.read()
+
+    if (chunk.done) break
+    chunks++
+    onState(state)
+  }
+
+  return { chunks, state }
+}
+
+export type UIMessageStreamCursor<UI_MESSAGE extends UIMessage> = {
+  offset: number
+  state: StreamingUIMessageState<UI_MESSAGE>
+  chunk: UIMessageChunk
+}
+
+export function fastResumeReadUIMessageStream<UI_MESSAGE extends UIMessage>({
+  stream,
+  messageId,
+  state: propState,
+  offset = 0,
+}: {
+  stream: ReadableStream<UIMessageChunk>
+  messageId: string
+  state?: StreamingUIMessageState<UI_MESSAGE>
+  offset?: number
+}) {
+  const state =
+    propState ??
+    createStreamingUIMessageState<UI_MESSAGE>({
+      lastMessage: undefined,
+      messageId,
+    })
+
+  return new ReadableStream<UIMessageStreamCursor<UI_MESSAGE>>({
+    async start(controller) {
+      try {
+        const res = processUIMessageStream<UI_MESSAGE>({
+          stream,
+          runUpdateMessageJob(
+            job: (options: {
+              state: StreamingUIMessageState<UI_MESSAGE>
+              write: () => void
+            }) => Promise<void>
+          ) {
+            return job({
+              state,
+              write: () => {},
+            })
+          },
+          onError: (error) => {
+            // ignore error chunk
+            state.message.metadata ??= {}
+            ;(state.message.metadata as any).__stream_error__ = (
+              error as Error
+            ).message
+          },
+        })
+
+        let chunks = 0
+
+        const reader = res.getReader()
+
+        while (true) {
+          const chunk = await reader.read()
+          if (chunk.done) break
+          controller.enqueue({
+            offset: chunks + offset,
+            state,
+            chunk: chunk.value,
+          })
+          chunks++
+        }
+
+        controller.close()
+      } catch (e) {
+        controller.error(e)
+      }
+    },
+  })
+}

package/packages/sdk/src/lib/zod.ts

@@ -0,0 +1,32 @@
+import { z, type ZodType } from "zod"
+
+export interface ZodStreamOptions<Input, Z extends ZodType<unknown, Input>> {
+  schema: Z
+  onParseFailed?: (
+    error: unknown,
+    chunk: unknown,
+    controller: TransformStreamDefaultController<z.infer<Z>>
+  ) => void
+}
+
+export class ZodStream<
+  Input,
+  Z extends ZodType<unknown, Input>,
+> extends TransformStream<Input, z.infer<Z>> {
+  constructor({ schema, onParseFailed }: ZodStreamOptions<Input, Z>) {
+    super({
+      async transform(chunk, controller) {
+        const result = await schema.safeParseAsync(chunk)
+        if (result.success) {
+          controller.enqueue(result.data)
+        } else if (onParseFailed) {
+          onParseFailed(result.error, chunk, controller)
+        } else {
+          controller.error(result.error)
+        }
+      },
+    })
+  }
+}
+
+export const zodJsonDate = z.string() // z.iso.datetime().transform((d) => new Date(d));