Using Secrets

This guide shows how to use TypeScript, a 3rd party search service, and secrets to create a script that augments documents with information from the web.

The goal is to create a script that will augment an existing document with information gathered from the web.

Tavily Search

Tavily is a search service optimized for LLMs that provides a REST API.

The REST API can be invoked using JavaScript fetch and requires an API key.

The script uses the TAVILY_API_KEY which will have to be declare in the script using this function.

const res = await fetch(..., {
    headers: {
        'api_key': env.secrets.TAVILY_API_KEY
    }
})

We define a function tavilySearch in TypeScript that wraps the fetch call and we add type annotations to provide a nice editing experience.

export async function tavilySearch(query: string): Promise<{
    answer: string
    query: string
    results: {
        title: string
        url: string
        content: string
        score: number
    }[]
}> { ... }

The full source looks like this:

tavily.mts

/**
 * Uses the Tavily API to search for a query.
 * @param query question
 * @param apiKey API key https://docs.tavily.com/docs/tavily-api/rest_api
 * @returns
 */
export async function tavilySearch(query: string): Promise<{
    answer: string
    query: string
    results: {
        title: string
        url: string
        content: string
        score: number
    }[]
}> {
    const apiKey = env.secrets.TAVILY_API_KEY
    if (!apiKey) throw new Error("secret TAVILY_API_KEY is not available")

    const res = await fetch("https://api.tavily.com/search", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            "api_key": apiKey,
            query,
            include_answer: true,
            max_results: 5,
        }),
    })
    const data: any = await res.json()
    return data
}

Question -> Search -> Augment

The script is split into 3 phases:

• run a prompt to generate a question based on the document content
• use Tavily to generate an answer to the question
• run a prompt to augment the document with the answer

The secret TAVILY_API_KEY needed by Tavily is declared in the script function call. Also make sure to add it to your .env file.

script({
    secrets: ["TAVILY_API_KEY"],
})

The tavilySearch function is imported using a dynamic import.

const { tavilySearch } = await import("./tavily.mts")
const { answer } = await tavilySearch(question.text)

The full source looks like this:

document-augmentor.genai.mts

script({
    secrets: ["TAVILY_API_KEY"],
    files: "src/rag/markdown.md",
})

const { tavilySearch } = await import("./tavily.mts")
const file = env.files[0]

// Question
const { text: question } = await runPrompt((_) => {
    const filen = _.def("FILE", file)
    _.$`Generate a question that summarizes the content of ${filen}`
})

// Search
const { answer } = await tavilySearch(question)

// Augment
const filen = def("FILE", file)
const answern = def("ANSWER", answer)

$`You are an expert at writing document. Integrate the information of ${answern} into ${filen}
to make it more informative.`