engram

type BatchEngram[C any, I any] interface {
	Engram[C]
	// Process contains the core business logic of the Engram. It is called exactly
	// once per execution. The SDK provides the typed inputs `I`, and expects a
	// `Result` in return, which it uses to report the output and status of the
	// StepRun. An error should be returned for any failures.
	Process(ctx context.Context, execCtx *ExecutionContext, inputs I) (*Result, error)
}

type Engram[C any] interface {
	// Init is called once at the start of an Engram's lifecycle. It is the ideal
	// place for setting up connections, validating configuration, or performing
	// any other one-time setup.
	Init(ctx context.Context, config C, secrets *Secrets) error
}

type ExecutionContext struct {
	// contains filtered or unexported fields
}

type Impulse[C any] interface {
	Engram[C]
	// Run is the main entry point for the Impulse's long-running process. The SDK
	// calls this method after `Init`, providing a pre-configured Kubernetes client
	// for interacting with bobrapet resources (like creating StoryRuns). The method
	// should block until the Impulse's work is complete or the context is canceled.
	Run(ctx context.Context, client *k8s.Client) error
}

type Result struct {
	// Data is the output of the Engram. This can be any serializable type.
	// The SDK will automatically handle JSON marshaling and, if configured,
	// transparently offload the data to external storage if it exceeds the
	// size threshold.
	Data any
}

type Secrets struct {
	// contains filtered or unexported fields
}

type StoryInfo struct {
	StoryName        string `json:"storyName"`
	StoryRunID       string `json:"storyRunID"`
	StepName         string `json:"stepName"`
	StepRunID        string `json:"stepRunID"`
	StepRunNamespace string `json:"stepRunNamespace"`
}

type StreamMessage struct {
	// Metadata contains tracing information (StoryRunID, StepName, etc.) from DataPacket.
	// This should be propagated through the streaming pipeline to maintain observability.
	Metadata map[string]string
	// Payload is the JSON-encoded data to be processed.
	Payload []byte
	// Inputs contains the evaluated step 'with:' configuration (CEL-resolved per packet).
	// This is analogous to BUBU_INPUTS in batch mode - dynamic configuration that can
	// reference outputs from previous steps. The Hub evaluates this before forwarding.
	// Empty if the step has no 'with:' block or evaluation failed.
	Inputs []byte
}

type StreamingEngram[C any] interface {
	Engram[C]
	// Stream is the core method for handling bidirectional data flow with metadata.
	// The SDK provides channels for receiving and sending StreamMessage which includes
	// both payload and metadata. Metadata should be propagated to enable tracing across
	// the streaming pipeline. The method should process messages from `in` and write
	// results to `out` until the input channel is closed or the context is canceled.
	Stream(ctx context.Context, in <-chan StreamMessage, out chan<- StreamMessage) error
}