schema.go

package flowengine

import (
	"encoding/json"
	"reflect"
	"strings"
)

// ===========================================================================
// Action - RPC-style Action Definition
// ===========================================================================

// Action defines a Function Call action.
type Action struct {
	// Name is the action identifier (function name).
	Name string

	// Description explains what this action does.
	Description string

	// Schema is the JSON Schema for action parameters.
	Schema map[string]any

	// Example shows sample parameters for this action (for debugging).
	Example string
}

// ===========================================================================
// ActionRegistry - Manages Action Definitions
// ===========================================================================

// ActionRegistry manages action definitions for a step.
type ActionRegistry struct {
	actions []Action
}

// NewActionRegistry creates a new action registry.
func NewActionRegistry() *ActionRegistry {
	return &ActionRegistry{
		actions: make([]Action, 0),
	}
}

// Register adds an action from a struct prototype.
// Struct fields become JSON Schema properties.
// Use `desc` tag to add field descriptions.
func (r *ActionRegistry) Register(name string, prototype any) *ActionRegistry {
	schema := structToSchema(prototype)
	r.actions = append(r.actions, Action{
		Name:    name,
		Schema:  schema,
		Example: schemaToExample(schema),
	})
	return r
}

// RegisterWithDesc adds an action with description.
func (r *ActionRegistry) RegisterWithDesc(name, description string, prototype any) *ActionRegistry {
	schema := structToSchema(prototype)
	r.actions = append(r.actions, Action{
		Name:        name,
		Description: description,
		Schema:      schema,
		Example:     schemaToExample(schema),
	})
	return r
}

// Actions returns all registered actions.
func (r *ActionRegistry) Actions() []Action {
	return r.actions
}

// Names returns all action names.
func (r *ActionRegistry) Names() []string {
	names := make([]string, len(r.actions))
	for i, a := range r.actions {
		names[i] = a.Name
	}
	return names
}

// IsEmpty returns true if no actions are registered.
func (r *ActionRegistry) IsEmpty() bool {
	return len(r.actions) == 0
}

// ValidateAction checks if an action name is registered.
func (r *ActionRegistry) ValidateAction(name string) bool {
	for _, a := range r.actions {
		if a.Name == name {
			return true
		}
	}
	return false
}

// ===========================================================================
// Tool Definition Generation (Function Call)
// ===========================================================================

// ToToolDefs converts actions to ToolDef slice for Function Call.
func (r *ActionRegistry) ToToolDefs() []ToolDef {
	if len(r.actions) == 0 {
		return nil
	}

	tools := make([]ToolDef, len(r.actions))
	for i, a := range r.actions {
		tools[i] = ToolDef{
			Name:        a.Name,
			Description: a.Description,
			Parameters:  a.Schema,
		}
	}
	return tools
}

// ===========================================================================
// Schema Generation (Zero External Dependencies)
// ===========================================================================

// structToSchema generates JSON Schema from a Go struct.
// Supports `json` tag for field names, `desc` tag for descriptions.
func structToSchema(v any) map[string]any {
	if v == nil {
		return map[string]any{"type": "object"}
	}

	t := reflect.TypeOf(v)
	if t.Kind() == reflect.Ptr {
		t = t.Elem()
	}
	if t.Kind() != reflect.Struct {
		return map[string]any{"type": "object"}
	}

	props := make(map[string]any)
	required := make([]string, 0)

	for i := 0; i < t.NumField(); i++ {
		field := t.Field(i)
		if field.PkgPath != "" { // unexported
			continue
		}

		jsonTag := field.Tag.Get("json")
		if jsonTag == "-" {
			continue
		}

		name, opts := parseJSONTag(jsonTag)
		if name == "" {
			name = field.Name
		}

		prop := buildFieldSchema(field.Type)

		// Add description from desc tag
		if desc := field.Tag.Get("desc"); desc != "" {
			prop["description"] = desc
		}

		props[name] = prop

		// Non-omitempty and non-pointer fields are required
		if !strings.Contains(opts, "omitempty") && field.Type.Kind() != reflect.Ptr {
			required = append(required, name)
		}
	}

	schema := map[string]any{
		"type":       "object",
		"properties": props,
	}
	if len(required) > 0 {
		schema["required"] = required
	}
	return schema
}

// buildFieldSchema creates schema for a single field type.
func buildFieldSchema(t reflect.Type) map[string]any {
	if t.Kind() == reflect.Ptr {
		t = t.Elem()
	}

	switch t.Kind() {
	case reflect.String:
		return map[string]any{"type": "string"}
	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
		return map[string]any{"type": "integer"}
	case reflect.Float32, reflect.Float64:
		return map[string]any{"type": "number"}
	case reflect.Bool:
		return map[string]any{"type": "boolean"}
	case reflect.Slice, reflect.Array:
		items := buildFieldSchema(t.Elem())
		return map[string]any{"type": "array", "items": items}
	case reflect.Map:
		return map[string]any{"type": "object"}
	case reflect.Struct:
		return structToSchema(reflect.New(t).Elem().Interface())
	default:
		return map[string]any{"type": "string"}
	}
}

// parseJSONTag parses json struct tag.
func parseJSONTag(tag string) (name string, opts string) {
	if tag == "" {
		return "", ""
	}
	parts := strings.SplitN(tag, ",", 2)
	name = parts[0]
	if len(parts) > 1 {
		opts = parts[1]
	}
	return
}

// schemaToExample generates an example JSON string from schema.
func schemaToExample(schema map[string]any) string {
	props, ok := schema["properties"].(map[string]any)
	if !ok {
		return "{}"
	}

	example := make(map[string]any)
	for name, propRaw := range props {
		prop, _ := propRaw.(map[string]any)
		propType, _ := prop["type"].(string)

		switch propType {
		case "string":
			if desc, ok := prop["description"].(string); ok && len(desc) <= 20 {
				example[name] = desc
			} else {
				example[name] = "..."
			}
		case "integer":
			example[name] = 0
		case "number":
			example[name] = 0.0
		case "boolean":
			example[name] = false
		case "array":
			example[name] = []any{}
		case "object":
			example[name] = map[string]any{}
		default:
			example[name] = nil
		}
	}

	data, _ := json.Marshal(example)
	return string(data)
}