workspace cache (#632)

* explose cache support

* docs

* added test

docs/src/content/docs/reference/scripts/cache.mdx

@@ -67,4 +67,18 @@ npx genaiscript run .... --cache-name summary
     -   cache
         -   summary.jsonl
 
-</FileTree>
+</FileTree>
+
+## Programmatic cache
+
+You can instantiate a custom cache object to manage the cache programmatically.
+
+```js
+const cache = await workspace.cache("summary")
+// write entries
+await cache.set("file.txt", "...")
+// read entries
+const content = await cache.get("file.txt")
+// list entries
+const entries = await cache.values()
+```

packages/core/src/filesystem.ts

@@ -1,3 +1,4 @@
+import { JSONLineCache } from "./cache"
 import { DOT_ENV_REGEX } from "./constants"
 import { NotSupportedError, errorMessage } from "./error"
 import { resolveFileContent } from "./file"
@@ -67,6 +68,16 @@ export function createFileSystem(): Omit<WorkspaceFileSystem, "grep"> {
             const res = XMLParse(file.content)
             return res
         },
+        cache: async (name: string) => {
+            if (!name) throw new NotSupportedError("missing cache name")
+            const res = JSONLineCache.byName<any, any>(name)
+            return <WorkspaceFileCache<any, any>>{
+                get: async (key: any) => res.get(key),
+                set: async (key: any, val: any) => res.set(key, val),
+                values: async () =>
+                    res.entries().then((es) => es.map((e) => e.val)),
+            }
+        },
     }
     ;(fs as any).readFile = readText
     return Object.freeze(fs)

packages/core/src/promptcontext.ts

@@ -17,7 +17,6 @@ import { YAMLParse, YAMLStringify } from "./yaml"
 import { createParsers } from "./parsers"
 import { readText } from "./fs"
 import {
-    PromptImage,
     PromptNode,
     appendChild,
     createFileMergeNode,
@@ -105,6 +104,7 @@ export async function createPromptContext(
         readJSON: (f) => runtimeHost.workspace.readJSON(f),
         readXML: (f) => runtimeHost.workspace.readXML(f),
         writeText: (f, c) => runtimeHost.workspace.writeText(f, c),
+        cache: (n) => runtimeHost.workspace.cache(n),
         findFiles: async (pattern, options) => {
             const res = await runtimeHost.workspace.findFiles(pattern, options)
             trace.files(res, {

packages/core/src/types/prompt_template.d.ts

@@ -475,6 +475,25 @@ interface ToolCallContent {
 
 type ToolCallOutput = string | ToolCallContent | ShellOutput | WorkspaceFile
 
+interface WorkspaceFileCache<K, V> {
+    /**
+     * Gets the value associated with the key, or undefined if there is none.
+     * @param key
+     */
+    get(key: K): Promise<V | undefined>
+    /**
+     * Sets the value associated with the key.
+     * @param key
+     * @param value
+     */
+    set(key: K, value: V): Promise<void>
+
+    /**
+     * List the values in the cache.
+     */
+    values(): Promise<V[]>
+}
+
 interface WorkspaceFileSystem {
     /**
      * Searches for files using the glob pattern and returns a list of files.
@@ -524,6 +543,15 @@ interface WorkspaceFileSystem {
      * @param content
      */
     writeText(path: string, content: string): Promise<void>
+
+    /**
+     * Opens a key-value cache for the given cache name.
+     * The cache is persisted accross runs of the script. Entries are dropped when the cache grows too large.
+     * @param cacheName
+     */
+    cache<K = any, V = any>(
+        cacheName: string
+    ): Promise<WorkspaceFileCache<K, V>>
 }
 
 interface ToolCallContext {
@@ -1641,6 +1669,9 @@ interface PromptContext extends ChatGenerationContext {
     path: Path
     parsers: Parsers
     retrieval: Retrieval
+    /**
+     * @deprecated Use `workspace` instead
+     */
     fs: WorkspaceFileSystem
     workspace: WorkspaceFileSystem
     YAML: YAML

packages/sample/genaisrc/cache.genai.mts

@@ -0,0 +1,17 @@
+script({
+    model: "openai:gpt-3.5-turbo",
+    tests: {},
+})
+
+const cache = await workspace.cache<number, number>("test-cache")
+const key = Math.random()
+const value = Math.random()
+
+await cache.set(key, value)
+const result = await cache.get(key)
+if (result !== value) throw new Error(`unexpected value: ${result}`)
+
+const values = await cache.values()
+if (!values.includes(value)) throw new Error(`unexpected values: ${values}`)
+
+console.log(`cache test passed`)