Skip to main content

​
Installation

Install the Simforge TypeScript SDK using your preferred package manager: 
npm install @goharvest/simforge

​
Quick Start

import { Simforge } from "@goharvest/simforge"

// Initialize the client
const client = new Simforge({
  apiKey: process.env.SIMFORGE_API_KEY,
  envVars: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  },
})

// Call a function
const result = await client.call("ExtractName", {
  text: "My name is John Doe",
})

console.log(result)
// { firstName: "John", lastName: "Doe" }
Currently, only OpenAI is supported as an LLM provider. Support for additional providers is coming soon.

​
Configuration

​
Constructor Options

OptionTypeRequiredDescription
apiKeystringYesYour Simforge API key
envVarsRecord<string, string>NoEnvironment variables to pass to BAML execution

​
Environment Variables

Pass your OpenAI API key to enable BAML function execution: 
const client = new Simforge({
  apiKey: process.env.SIMFORGE_API_KEY,
  envVars: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  },
})
Currently, only OPENAI_API_KEY is supported. Additional LLM providers will be added in future releases.

​
Calling Functions

​
Basic Call

const result = await client.call("FunctionName", {
  inputField: "value",
})

​
With Type Safety

The SDK returns typed results based on your BAML function definitions: 
// If your BAML function returns:
// class Person {
//   firstName string
//   lastName string
// }

const result = await client.call("ExtractPerson", { text: "..." })
// result is typed as { firstName: string, lastName: string }

​
Tracing with OpenAI Agents SDK

The Simforge SDK integrates with the OpenAI Agents SDK to automatically capture traces: 
import { Simforge } from "@goharvest/simforge"
import { Agent, Runner, setTraceProcessors } from "@openai/agents"

// Create Simforge client
const client = new Simforge({
  apiKey: process.env.SIMFORGE_API_KEY,
})

// Get the tracing processor
const processor = client.getOpenAITracingProcessor()

// Register with OpenAI Agents SDK
setTraceProcessors([processor])

// Now all agent runs will be traced to Simforge
const agent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "gpt-4o",
})

const result = await Runner.run(agent, "Hello!")

​
Error Handling

try {
  const result = await client.call("FunctionName", input)
} catch (error) {
  if (error instanceof SimforgeError) {
    console.error("Simforge error:", error.message)
    console.error("Status:", error.status)
  } else {
    throw error
  }
}

​
Examples

​
Extract Structured Data

const result = await client.call("ExtractInvoice", {
  text: `
    Invoice #12345
    Date: 2024-01-15
    Total: $150.00
    Items:
    - Widget x2 @ $50.00
    - Gadget x1 @ $50.00
  `,
})

console.log(result)
// {
//   invoiceNumber: "12345",
//   date: "2024-01-15",
//   total: 150.00,
//   items: [
//     { name: "Widget", quantity: 2, price: 50.00 },
//     { name: "Gadget", quantity: 1, price: 50.00 }
//   ]
// }

​
Classify Text

const result = await client.call("ClassifySentiment", {
  text: "I love this product! It's amazing!",
})

console.log(result)
// { sentiment: "positive", confidence: 0.95 }