feat: add type-safe SharedStore helpers

- Add type-specific getters (GetString, GetInt, GetFloat64, GetBool, GetSlice, GetMap)
- Add getters with custom defaults (GetStringOr, GetIntOr, etc.)
- Add Bind/MustBind methods for complex type binding (similar to Echo framework)
- Add utility methods (Has, Delete, Clear, Keys, Len)
- Automatic numeric type conversions for GetInt and GetFloat64
- Comprehensive test coverage for all new methods
- Update documentation and cookbook examples to use new helpers
- 100% backward compatible - existing Get/Set methods unchanged

This enhancement makes SharedStore access safer and more ergonomic by eliminating
the need for manual type assertions and reducing boilerplate code.

Author: ezynda3

README.md

@@ -165,15 +165,49 @@ err := flow.Run(ctx, shared)
 
 ### Shared Store
 
-Thread-safe data sharing between nodes:
+Thread-safe data sharing between nodes with type-safe helpers:
 
 ```go
 shared := flyt.NewSharedStore()
 
-// Set and get individual values
+// Basic get/set operations
 shared.Set("key", "value")
 value, ok := shared.Get("key")
 
+// Type-safe getters (return zero values if not found or wrong type)
+str := shared.GetString("name")           // Returns "" if not found
+num := shared.GetInt("count")             // Returns 0 if not found
+price := shared.GetFloat64("price")       // Returns 0.0 if not found
+enabled := shared.GetBool("enabled")      // Returns false if not found
+items := shared.GetSlice("items")         // Returns nil if not found
+config := shared.GetMap("config")         // Returns nil if not found
+
+// Type-safe getters with custom defaults
+str = shared.GetStringOr("name", "anonymous")
+num = shared.GetIntOr("count", -1)
+price = shared.GetFloat64Or("price", 99.99)
+enabled = shared.GetBoolOr("enabled", true)
+
+// Bind complex types (similar to Echo framework)
+type User struct {
+    ID   int    `json:"id"`
+    Name string `json:"name"`
+}
+
+shared.Set("user", map[string]any{"id": 123, "name": "Alice"})
+
+var user User
+err := shared.Bind("user", &user)  // Binds map to struct
+// Or panic on failure (for required data)
+shared.MustBind("user", &user)
+
+// Utility methods
+exists := shared.Has("key")       // Check if key exists
+shared.Delete("key")               // Remove a key
+keys := shared.Keys()              // Get all keys
+length := shared.Len()             // Get number of items
+shared.Clear()                     // Remove all items
+
 // Get all data as a map (returns a copy)
 allData := shared.GetAll()
 
@@ -184,6 +218,11 @@ shared.Merge(map[string]any{
 })
 ```
 
+The type-safe getters handle numeric conversions automatically:
+- `GetInt()` converts from int8, int16, int32, int64, uint variants, and float types
+- `GetFloat64()` converts from all numeric types including int and float32
+- `GetSlice()` uses the same conversion logic as `ToSlice()` utility
+
 ## Intermediate Patterns
 
 ### Configuration via Closures

cookbook/agent/main.go

@@ -46,9 +46,8 @@ func main() {
 		log.Fatalf("Error running agent: %v", err)
 	}
 
-	answerVal, _ := shared.Get("answer")
-	answer, ok := answerVal.(string)
-	if !ok || answer == "" {
+	answer := shared.GetString("answer")
+	if answer == "" {
 		log.Fatal("No answer found")
 	}
 	fmt.Println("\n🎯 Final Answer:")

cookbook/agent/nodes.go

@@ -14,16 +14,9 @@ import (
 func NewDecideActionNode(llm *LLM) flyt.Node {
 	return flyt.NewNode(
 		flyt.WithPrepFunc(func(ctx context.Context, shared *flyt.SharedStore) (any, error) {
-			question, _ := shared.Get("question")
-			context, _ := shared.Get("context")
-			if context == nil {
-				context = "No previous search"
-			}
-
-			searchCount, _ := shared.Get("search_count")
-			if searchCount == nil {
-				searchCount = 0
-			}
+			question := shared.GetString("question")
+			context := shared.GetStringOr("context", "No previous search")
+			searchCount := shared.GetInt("search_count")
 
 			return map[string]any{
 				"question":     question,
@@ -112,7 +105,7 @@ Example responses:
 func NewSearchWebNode(searcher Searcher) flyt.Node {
 	return flyt.NewNode(
 		flyt.WithPrepFunc(func(ctx context.Context, shared *flyt.SharedStore) (any, error) {
-			query, _ := shared.Get("search_query")
+			query := shared.GetString("search_query")
 
 			return map[string]any{
 				"query": query,
@@ -140,13 +133,9 @@ func NewSearchWebNode(searcher Searcher) flyt.Node {
 			results := data["results"].(string)
 			query := data["query"].(string)
 
-			previousContext, _ := shared.Get("context")
-			previousStr := ""
-			if previousContext != nil {
-				previousStr = previousContext.(string)
-			}
+			previousContext := shared.GetString("context")
 
-			newContext := fmt.Sprintf("%s\n\nSEARCH: %s\nRESULTS: %s", previousStr, query, results)
+			newContext := fmt.Sprintf("%s\n\nSEARCH: %s\nRESULTS: %s", previousContext, query, results)
 			shared.Set("context", newContext)
 
 			fmt.Println("📚 Found information, analyzing results...")
@@ -160,8 +149,8 @@ func NewSearchWebNode(searcher Searcher) flyt.Node {
 func NewAnswerQuestionNode(llm *LLM) flyt.Node {
 	return flyt.NewNode(
 		flyt.WithPrepFunc(func(ctx context.Context, shared *flyt.SharedStore) (any, error) {
-			question, _ := shared.Get("question")
-			context, _ := shared.Get("context")
+			question := shared.GetString("question")
+			context := shared.GetString("context")
 
 			return map[string]any{
 				"question": question,

cookbook/slack-bot/main.go

@@ -231,10 +231,8 @@ func (b *SlackBot) processWithFlyt(ctx context.Context, message, channel, thread
 	}
 
 	// Get response from shared store
-	if response, ok := shared.Get("response"); ok {
-		if responseStr, ok := response.(string); ok {
-			b.sendMessage(channel, responseStr, threadTS)
-		}
+	if response := shared.GetString("response"); response != "" {
+		b.sendMessage(channel, response, threadTS)
 	}
 }
 

cookbook/slack-bot/nodes.go

@@ -16,16 +16,11 @@ type ParseMessageNode struct {
 }
 
 func (n *ParseMessageNode) Prep(ctx context.Context, shared *flyt.SharedStore) (any, error) {
-	message, ok := shared.Get("message")
-	if !ok {
+	messageStr := shared.GetString("message")
+	if messageStr == "" {
 		return nil, fmt.Errorf("no message found in shared store")
 	}
 
-	messageStr, ok := message.(string)
-	if !ok {
-		return nil, fmt.Errorf("message is not a string")
-	}
-
 	// Clean up the message (remove bot mentions, extra spaces, etc.)
 	cleanedMessage := strings.TrimSpace(messageStr)
 	cleanedMessage = strings.ReplaceAll(cleanedMessage, "  ", " ")
@@ -67,16 +62,17 @@ type LLMNode struct {
 
 func (n *LLMNode) Prep(ctx context.Context, shared *flyt.SharedStore) (any, error) {
 	// Check if we're processing tool responses
-	if toolResponses, ok := shared.Get("tool_responses"); ok {
+	if shared.Has("tool_responses") {
+		toolResponses, _ := shared.Get("tool_responses")
 		return map[string]interface{}{
 			"type":           "tool_response",
 			"tool_responses": toolResponses,
 		}, nil
 	}
 
 	// Otherwise, process user message
-	message, ok := shared.Get("cleaned_message")
-	if !ok {
+	message := shared.GetString("cleaned_message")
+	if message == "" {
 		return nil, fmt.Errorf("no cleaned message found")
 	}
 
@@ -203,8 +199,8 @@ type FormatResponseNode struct {
 }
 
 func (n *FormatResponseNode) Prep(ctx context.Context, shared *flyt.SharedStore) (any, error) {
-	response, ok := shared.Get("response")
-	if !ok {
+	response := shared.GetString("response")
+	if response == "" {
 		return nil, fmt.Errorf("no response found")
 	}
 	return response, nil