feat(program): update execution strategy

dsgo.go

@@ -97,6 +97,17 @@ type (
 	ScoringFunction      = module.ScoringFunction
 	StreamResult         = module.StreamResult
 	MultiChainComparison = module.MultiChainComparison
+
+	// Program tracing and validation types
+	ExecutionID         = module.ExecutionID
+	StepStatus          = module.StepStatus
+	ExecutionStatus     = module.ExecutionStatus
+	StepExecution       = module.StepExecution
+	ProgramExecution    = module.ProgramExecution
+	ProgramMetrics      = module.ProgramMetrics
+	ProgramResult       = module.ProgramResult
+	SignatureMismatch   = module.SignatureMismatch
+	CompletionsConsumer = module.CompletionsConsumer
 )
 
 // Re-export logging types
@@ -191,6 +202,8 @@ var (
 	GenerateCacheKey                = core.GenerateCacheKey
 	GenerateCacheKeyWithIgnored     = core.GenerateCacheKeyWithIgnored
 	MarkCacheHit                    = core.MarkCacheHit
+	DeepCopyMap                     = core.DeepCopyMap
+	DeepCopySlice                   = core.DeepCopySlice
 	NewFallbackAdapter              = core.NewFallbackAdapter
 	NewFallbackAdapterWithChain     = core.NewFallbackAdapterWithChain
 	NewJSONAdapter                  = core.NewJSONAdapter
@@ -400,4 +413,16 @@ const (
 	MCPErrCodeMethodNotFound = mcp.ErrCodeMethodNotFound
 	MCPErrCodeInvalidParams  = mcp.ErrCodeInvalidParams
 	MCPErrCodeInternalError  = mcp.ErrCodeInternalError
+
+	// Program tracing and validation constants
+	StepStatusPending   = module.StepStatusPending
+	StepStatusRunning   = module.StepStatusRunning
+	StepStatusCompleted = module.StepStatusCompleted
+	StepStatusFailed    = module.StepStatusFailed
+	StepStatusSkipped   = module.StepStatusSkipped
+
+	ExecutionStatusPending   = module.ExecutionStatusPending
+	ExecutionStatusRunning   = module.ExecutionStatusRunning
+	ExecutionStatusCompleted = module.ExecutionStatusCompleted
+	ExecutionStatusFailed    = module.ExecutionStatusFailed
 )

examples/program_tracing/README.md

@@ -0,0 +1,108 @@
+# Program Tracing Examples
+
+This document demonstrates how to use DSGo's program tracing capabilities for debugging, observability, and progress reporting.
+
+## Key Use Cases
+
+### 1. Debugging Pipeline Issues
+- Access intermediate results to identify where problems occur
+- Check input/output compatibility between steps
+- View detailed error messages and timing information
+
+### 2. Observability and Monitoring
+- Track execution progress in real-time
+- Monitor resource usage (tokens, cost, latency)
+- Collect metrics for performance analysis
+
+### 3. UI/CLI Progress Reporting
+- Show step-by-step progress to users
+- Display estimated completion times
+- Provide detailed status updates
+
+### 4. Pipeline Optimization
+- Identify bottlenecks with per-step timing
+- Analyze cost distribution across steps
+- Compare performance between different configurations
+
+### 5. Testing and Validation
+- Verify intermediate outputs meet expectations
+- Test error handling and recovery
+- Validate data flow through the pipeline
+
+## Running the Examples
+
+```bash
+cd examples/program_tracing
+go run tracing_examples.go
+```
+
+This will run through several examples showing:
+1. **Basic Execution Tracing**: How to access execution traces and metrics
+2. **Intermediate Results**: How to retrieve step-by-step outputs even though `Forward()` only returns the final result
+3. **Error Debugging**: How to use execution traces to diagnose pipeline failures
+4. **Metrics Collection**: How to collect and analyze performance metrics
+
+## Key APIs Demonstrated
+
+### Accessing Execution Traces
+```go
+execution := program.GetExecution()
+metrics := execution.Metrics()
+```
+
+### Intermediate Results Access
+```go
+for i, step := range execution.Steps {
+    if step.Status == dsgo.StepStatusCompleted {
+        outputs := step.Prediction.Outputs
+        duration := step.Duration
+        // Process intermediate results
+    }
+}
+```
+
+### Error Diagnosis
+```go
+if execution.Status == dsgo.ExecutionStatusFailed {
+    for i, step := range execution.Steps {
+        if step.Status == dsgo.StepStatusFailed {
+            fmt.Printf("Step %d failed: %v\n", i, step.Error)
+            fmt.Printf("Inputs: %v\n", step.Inputs)
+        }
+    }
+}
+```
+
+### Performance Metrics
+```go
+metrics := execution.Metrics()
+fmt.Printf("Total duration: %v\n", metrics.TotalDuration)
+fmt.Printf("Slowest step: %d (%v)\n", metrics.SlowestStepIndex, metrics.SlowestStep)
+fmt.Printf("Total cost: $%.6f\n", metrics.TotalUsage.Cost)
+```
+
+## Understanding the Execution Model
+
+DSGo's `Program.Forward()` method always returns only the **last module's prediction** for backward compatibility. However, the complete execution trace containing all intermediate results is available via `program.GetExecution()`.
+
+This design allows:
+- **Simple API**: Most use cases only need the final result
+- **Full observability**: All intermediate data is accessible when needed
+- **Performance**: No overhead for users who don't need tracing
+- **Debugging**: Complete visibility into pipeline execution
+
+The execution trace includes:
+- Per-step timing information
+- Input/output data for each step
+- Error information and stack traces
+- Aggregated usage metrics (tokens, cost, latency)
+- Overall execution status and duration
+
+## Integration with Observability Systems
+
+The tracing data can be easily integrated with:
+- **Logging systems**: Structured logging of execution metrics
+- **Monitoring platforms**: Export metrics to Prometheus, etc.
+- **Progress bars**: Real-time UI updates during long executions
+- **Debugging tools**: Step-by-step pipeline analysis
+- **Cost tracking**: Detailed cost breakdown per step

examples/program_tracing/go.mod

@@ -0,0 +1,20 @@
+module github.com/assagman/dsgo/examples/program_tracing
+
+go 1.25
+
+require (
+	github.com/assagman/dsgo v0.0.0
+	github.com/assagman/dsgo/examples/shared v0.0.0
+)
+
+require (
+	github.com/openai/openai-go/v3 v3.13.0 // indirect
+	github.com/tidwall/gjson v1.18.0 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.1 // indirect
+	github.com/tidwall/sjson v1.2.5 // indirect
+)
+
+replace github.com/assagman/dsgo => ../..
+
+replace github.com/assagman/dsgo/examples/shared => ../shared

examples/program_tracing/go.sum

@@ -0,0 +1,12 @@
+github.com/openai/openai-go/v3 v3.13.0 h1:arSFmVHcBHNVYG5iqspPJrLoin0Qqn2JcCLWWcTcM1Q=
+github.com/openai/openai-go/v3 v3.13.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
+github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
+github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
+github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=