updates to comments, docs, example code

Author: robbyt

Diff for: README.md

@@ -9,9 +9,9 @@ A Go package providing a unified interface for loading and running various scrip
 
 ## Overview
 
-go-polyscript provides a consistent API across different scripting engines, allowing for easy interchangeability and minimizing lock-in to a specific scripting language. This is achieved through a low-overhead abstraction of "machines," "executables," and the final "result". The input/output and runtime features provided by the scripting engines are standardized, which simplifies combining or swapping scripting engines in your application.
+go-polyscript provides a consistent API across different scripting engines, allowing for easy interchangeability and minimizing lock-in to a specific scripting language. This package provides low-overhead abstractions of "machines," "executables," and the final "result". The API for the input/output and runtime are all standardized, which simplifies combining or swapping scripting engines in your application.
 
-Currently supported scripting engines ("machines"):
+Currently supported scripting engines "machines":
 
 - **Risor**: A simple scripting language specifically designed for embedding in Go applications
 - **Starlark**: Google's configuration language (a Python dialect) used in Bazel and many other tools
@@ -21,11 +21,10 @@ Currently supported scripting engines ("machines"):
 
 - **Unified API**: Common interfaces for all supported scripting languages
 - **Flexible Engine Selection**: Easily switch between different script engines
-- **Powerful Data Passing**: Multiple ways to provide input data to scripts
-- **Comprehensive Logging**: Structured logging with `slog` support
-- **Error Handling**: Robust error handling and reporting from script execution
+- **Thread-safe Data Management**: Multiple ways to provide input data to scripts
 - **Compilation and Evaluation Separation**: Compile once, run multiple times with different inputs
 - **Data Preparation and Evaluation Separation**: Prepare data in one step/system, evaluate in another
+- **Slog Logging**: Customizable structured logging with `slog`
 
 ## Installation
 
@@ -35,7 +34,7 @@ go get github.com/robbyt/go-polyscript@latest
 
 ## Quick Start
 
-Here's a simple example of using go-polyscript with the Risor scripting engine:
+Using go-polyscript with the Risor scripting engine:
 
 ```go
 package main
@@ -47,10 +46,6 @@ import (
 	"os"
 
 	"github.com/robbyt/go-polyscript"
-	"github.com/robbyt/go-polyscript/execution/constants"
-	"github.com/robbyt/go-polyscript/execution/data"
-	"github.com/robbyt/go-polyscript/machines/risor"
-	"github.com/robbyt/go-polyscript/engine/options"
 )
 
 func main() {
@@ -73,15 +68,12 @@ func main() {
 
 	// Input data
 	inputData := map[string]any{"name": "World"}
-	dataProvider := data.NewStaticProvider(inputData)
 
-	// Create evaluator with functional options
-	evaluator, err := polyscript.FromRisorString(
+	// Create evaluator from string with static data
+	evaluator, err := polyscript.FromRisorStringWithData(
 		scriptContent,
-		options.WithDefaults(),
-		options.WithLogHandler(handler),
-		options.WithDataProvider(dataProvider),
-		risor.WithGlobals([]string{"ctx"}),
+		inputData,
+		handler,
 	)
 	if err != nil {
 		logger.Error("Failed to create evaluator", "error", err)
@@ -110,12 +102,11 @@ go-polyscript uses data providers to supply information to scripts during evalua
 The `StaticProvider` supplies fixed data for all evaluations. This is ideal for scenarios where the input data remains constant across evaluations:
 
 ```go
-// Create a static provider with predefined data
+// Create static data for configuration
 configData := map[string]any{"name": "World", "timeout": 30}
-provider := data.NewStaticProvider(configData)
 
-// Create evaluator with the provider
-evaluator, err := polyscript.FromRisorString(script, options.WithDataProvider(provider))
+// Create evaluator with static data
+evaluator, err := polyscript.FromRisorStringWithData(script, configData, logHandler)
 
 // In scripts, static data is accessed directly:
 // name := ctx["name"]  // "World"
@@ -128,45 +119,57 @@ However, when using `StaticProvider`, each evaluation will always use the same i
 The `ContextProvider` retrieves dynamic data from the context and makes it available to scripts. This is useful for scenarios where input data changes at runtime:
 
 ```go
-// Create a context provider for dynamic data
-provider := data.NewContextProvider(constants.EvalData)
+// Create evaluator with dynamic data capability
+evaluator, err := polyscript.FromRisorString(script, logHandler)
 
-// Prepare context with runtime data
+// Prepare context with runtime data for each request
 ctx := context.Background()
-userData := map[string]any{"userId": 123, "preferences": {"theme": "dark"}}
-enrichedCtx, _ := provider.AddDataToContext(ctx, userData)
+userData := map[string]any{"userId": 123, "preferences": map[string]string{"theme": "dark"}}
+enrichedCtx, err := evaluator.PrepareContext(ctx, userData)
+if err != nil {
+    // handle error
+}
 
-// Create evaluator with the provider
-evaluator, err := polyscript.FromRisorString(script, options.WithDataProvider(provider))
+// Execute with the enriched context
+result, err := evaluator.Eval(enrichedCtx)
 
 // In scripts, dynamic data is accessed via input_data:
 // userId := ctx["input_data"]["userId"]  // 123
 ```
 
-### CompositeProvider
+### Combining Static and Dynamic Data
 
-To combine static data with dynamic runtime data, you can use the `CompositeProvider`. This allows you to stack a `StaticProvider` with a `ContextProvider`, enabling both fixed and variable data to be available during evaluation:
+go-polyscript makes it easy to combine static configuration data with dynamic request data. This is a common pattern where you want both fixed configuration values and per-request variable data to be available during evaluation:
 
 ```go
-// Create providers for static and dynamic data
-staticProvider := data.NewStaticProvider(map[string]any{
+// Create static configuration data
+staticData := map[string]any{
     "appName": "MyApp",
     "version": "1.0",
-})
-ctxProvider := data.NewContextProvider(constants.EvalData)
+}
 
-// Combine them using CompositeProvider
-provider := data.NewCompositeProvider(staticProvider, ctxProvider)
+// Create evaluator with the static data
+evaluator, err := polyscript.FromRisorStringWithData(script, staticData, logHandler)
+if err != nil {
+    // handle error
+}
+
+// For each request, prepare dynamic data
+requestData := map[string]any{"userId": 123, "preferences": map[string]string{"theme": "dark"}}
+enrichedCtx, err := evaluator.PrepareContext(context.Background(), requestData)
+if err != nil {
+    // handle error
+}
 
-// Create evaluator with the composite provider
-evaluator, err := polyscript.FromRisorString(script, options.WithDataProvider(provider))
+// Execute with both static and dynamic data available
+result, err := evaluator.Eval(enrichedCtx)
 
 // In scripts, data can be accessed from both locations:
 // appName := ctx["appName"]  // Static data: "MyApp"
 // userId := ctx["input_data"]["userId"]  // Dynamic data: 123
 ```
 
-By using the `CompositeProvider`, you can ensure that your scripts have access to both constant configuration values and per-evaluation runtime data, making your evaluations more flexible and powerful.
+This pattern ensures that your scripts have access to both constant configuration values and per-evaluation runtime data, making your evaluations more flexible and powerful.
 
 ## Architecture
 
@@ -198,7 +201,7 @@ go-polyscript provides the `EvalDataPreparer` interface to separate data prepara
 
 ```go
 // Create an evaluator (implements EvaluatorWithPrep interface)
-evaluator, err := polyscript.FromRisorString(script, options...)
+evaluator, err := polyscript.FromRisorString(script, logHandler)
 if err != nil {
     // handle error
 }
@@ -224,22 +227,24 @@ For more detailed examples of this pattern, see the [data-prep examples](example
 ### Using Starlark
 
 ```go
-// Create a Starlark evaluator with options
-evaluator, err := polyscript.FromStarlarkString(
-    `
-    # Starlark has access to ctx variable
-    name = ctx["name"]
-    message = "Hello, " + name + "!"
-    
-    # Create the result dictionary
-    result = {"greeting": message, "length": len(message)}
-    
-    # Assign to _ to return the value
-    _ = result
-    `,
-    options.WithDefaults(),
-    options.WithDataProvider(data.NewStaticProvider(map[string]any{"name": "World"})),
-    starlark.WithGlobals([]string{constants.Ctx}),
+// Create a Starlark evaluator with static data
+scriptContent := `
+# Starlark has access to ctx variable
+name = ctx["name"]
+message = "Hello, " + name + "!"
+
+# Create the result dictionary
+result = {"greeting": message, "length": len(message)}
+
+# Assign to _ to return the value
+_ = result
+`
+
+staticData := map[string]any{"name": "World"}
+evaluator, err := polyscript.FromStarlarkStringWithData(
+    scriptContent,
+    staticData,
+    logHandler,
 )
 
 // Execute with a context
@@ -249,12 +254,13 @@ result, err := evaluator.Eval(context.Background())
 ### Using WebAssembly with Extism
 
 ```go
-// Create an Extism evaluator
-evaluator, err := polyscript.FromExtismFile(
+// Create an Extism evaluator with static data
+staticData := map[string]any{"input": "World"}
+evaluator, err := polyscript.FromExtismFileWithData(
     "/path/to/module.wasm",
-    options.WithDefaults(),
-    options.WithDataProvider(data.NewStaticProvider(map[string]any{"input": "World"})),
-    extism.WithEntryPoint("greet"),
+    staticData,
+    logHandler,
+    "greet",  // entryPoint
 )
 
 // Execute with a context

Diff for: benchmarks/README.md

@@ -1,9 +1,8 @@
-## Benchmarking VMs, and general optimization
+# Benchmark Documentation
 
-This directory contains benchmarking tools and historical benchmark records to track performance 
-characteristics of go-polyscript. These benchmarks serve as both documentation of optimization 
-effectiveness and protection against performance regressions. The data collected here demonstrates 
-the impact of various performance optimizations implemented throughout the package.
+This directory contains benchmarking tools and historical benchmark records for go-polyscript performance analysis. Benchmarks serve as documentation of optimization effectiveness and protection against performance regressions.
+
+## Performance Optimization Patterns
 
 ### 1. Compile Once, Run Many Times
 
@@ -31,23 +30,23 @@ enrichedCtx, _ := evaluator.PrepareContext(ctx, inputData)
 result, _ := evaluator.Eval(enrichedCtx)
 ```
 
-### 3. Provider Selection
+### 3. Provider Performance Comparison
 
-The benchmarks also show performance differences between `data.Provider` implementations:
+The benchmarks show performance differences between `data.Provider` implementations:
 
-- **StaticProvider**: Fastest overall - use when runtime data is not needed, and input data is static
-- **ContextProvider**: Needed for request-specific data that varies per execution, data stored in local memory
-- **CompositeProvider**: Meta-provider, enabling multiple `data.Provider` objects in a series
+- **StaticProvider**: Fastest overall (~5-10% faster than other providers) - use when input data is static
+- **ContextProvider**: Needed for request-specific data that varies per execution
+- **CompositeProvider**: Small overhead but enables both static configuration and dynamic request data
 
-### 4. VM Selection Trade-offs
+### 4. Script Engine Performance Characteristics
 
-Performance characteristics vary by VM implementation:
+Performance characteristics vary significantly by implementation:
 
-- **Risor**: Fast general-purpose scripting with broad Go compatibility
-- **Starlark**: Excellent for configuration processing with Python-like syntax
-- **Extism/WASM**: Best security isolation with pre-compiled modules
+- **Risor**: Generally fastest for general-purpose scripting with good Go interoperability
+- **Starlark**: Optimized for configuration processing with Python-like syntax
+- **Extism/WASM**: Best for security isolation with pre-compiled modules
 
-### Running Benchmarks
+## Running Benchmarks
 
 To benchmark go-polyscript performance in your environment:
 
@@ -56,11 +55,32 @@ To benchmark go-polyscript performance in your environment:
 make bench
 
 # Run specific benchmark pattern
-./benchmark.sh BenchmarkEvaluationPatterns
+./benchmarks/run.sh BenchmarkEvaluationPatterns
 
 # Quick benchmark without reports
 make bench-quick
 
 # Benchmark with specific iterations
 go test -bench=BenchmarkVMComparison -benchmem -benchtime=10x ./engine
 ```
+
+## Historical Results
+
+Benchmark results are stored in the `results/` directory with timestamps. This allows tracking performance changes over time and identifying performance regressions:
+
+- `benchmark_YYYY-MM-DD_HH-MM-SS.json` - Raw benchmark data
+- `benchmark_YYYY-MM-DD_HH-MM-SS.txt` - Human-readable summary
+- `comparison.txt` - Comparison of current results with previous runs
+- `latest.txt` - Most recent benchmark summary
+
+## Benchmarking Infrastructure
+
+The benchmarking infrastructure in go-polyscript automatically:
+
+1. Runs comprehensive benchmarks across all script engines
+2. Compares execution patterns (one-time vs. compile-once-run-many)
+3. Measures data provider performance differences
+4. Records results for historical comparison
+5. Generates human-readable reports
+
+For more detailed examples of optimized script usage patterns, see the [examples directory](../examples/).

Diff for: examples/data-prep/starlark/testdata/script.star

@@ -40,7 +40,7 @@ def process_data():
 
     return result
 
-# Call the function and store the result
 result = process_data()
-# The underscore variable is what gets returned to the VM
+
+# The underscore variable is returned to Go
 _ = result

Diff for: machines/extism/evaluator/evaluator.go

@@ -137,8 +137,6 @@ func (be *Evaluator) exec(
 	if err != nil {
 		return nil, fmt.Errorf("extism execution error: %w", err)
 	}
-
-	logger.InfoContext(ctx, "execution complete", "result", result)
 	return newEvalResult(be.logHandler, result, execTime, ""), nil
 }
 
@@ -201,12 +199,12 @@ func (be *Evaluator) Eval(ctx context.Context) (engine.EvaluatorResponse, error)
 		runtimeData,
 	)
 	if err != nil {
-		return nil, fmt.Errorf("execution error: %w", err)
+		return nil, fmt.Errorf("exec error: %w", err)
 	}
+	logger.DebugContext(ctx, "exec completed", "result", result)
 
 	// 5. Collect results
 	result.scriptExeID = exeID
-	logger.DebugContext(ctx, "execution complete")
 	return result, nil
 }
 

Diff for: machines/risor/evaluator/evaluator.go

@@ -78,16 +78,13 @@ func (be *Evaluator) exec(
 	bytecode *risorCompiler.Code,
 	options ...risorLib.Option,
 ) (*execResult, error) {
-	logger := be.logger.WithGroup("exec")
 	startTime := time.Now()
 	result, err := risorLib.EvalCode(ctx, bytecode, options...)
 	execTime := time.Since(startTime)
 
 	if err != nil {
 		return nil, fmt.Errorf("risor execution error: %w", err)
 	}
-
-	logger.InfoContext(ctx, "execution complete", "result", result)
 	return newEvalResult(be.logHandler, result, execTime, ""), nil
 }
 
@@ -136,9 +133,9 @@ func (be *Evaluator) Eval(ctx context.Context) (engine.EvaluatorResponse, error)
 	// 4. Execute the program
 	result, err := be.exec(ctx, risorByteCode, runtimeData...)
 	if err != nil {
-		return nil, fmt.Errorf("error returned from script: %w", err)
+		return nil, fmt.Errorf("exec error: %w", err)
 	}
-	logger.Debug("script execution complete", "result", result)
+	logger.DebugContext(ctx, "exec complete", "result", result)
 
 	// 5. Collect results
 	result.scriptExeID = exeID
@@ -155,7 +152,6 @@ func (be *Evaluator) Eval(ctx context.Context) (engine.EvaluatorResponse, error)
 		return result, fmt.Errorf("function object returned from script: %s", result.Inspect())
 	}
 
-	logger.DebugContext(ctx, "execution complete")
 	return result, nil
 }