engram

type AudioFrame struct {
	// PCM contains raw little-endian PCM audio bytes for the frame.
	PCM []byte
	// SampleRateHz is the sampling rate in hertz (for example, 16000).
	SampleRateHz int32
	// Channels is the number of audio channels in PCM (for example, 1 for mono).
	Channels int32
	// Codec optionally names the codec when the frame is encoded instead of raw PCM.
	Codec string
	// Timestamp is the media timeline position for this frame.
	Timestamp time.Duration
}

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 BinaryFrame struct {
	// Payload carries opaque binary bytes.
	Payload []byte
	// MimeType identifies the payload media type (for example, "application/octet-stream").
	MimeType string
	// Timestamp is an optional media timeline position for this frame.
	Timestamp time.Duration
}

type ControlDirective struct {
	// Type identifies the control instruction, such as "start", "stop", or "codec-select".
	Type string
	// Metadata carries optional directive-specific key/value hints from the connector.
	Metadata map[string]string
}

type ControlDirectiveHandler interface {
	// HandleControlDirective processes an inbound directive. Returning a non-nil directive
	// sends a response back to the connector. Implementations may return nil to skip replies.
	HandleControlDirective(ctx context.Context, directive ControlDirective) (*ControlDirective, 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 InboundMessage struct {
	StreamMessage
	// contains filtered or unexported fields
}

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 {
	// Kind declares the semantic intent of the packet (e.g., "data", "heartbeat").
	Kind string
	// MessageID is an optional caller-defined identifier that assists with deduplication.
	MessageID string
	// Timestamp captures when the packet was produced. Zero-value timestamps are omitted.
	Timestamp time.Time
	// 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. Prefer Binary for new code paths.
	Payload []byte
	// Audio carries PCM audio frames when present.
	Audio *AudioFrame
	// Video carries encoded or raw video frames when present.
	Video *VideoFrame
	// Binary carries arbitrary non-audio/video frames when present.
	Binary *BinaryFrame
	// Inputs contains the evaluated step 'with:' configuration (CEL-resolved per packet).
	// This is analogous to BUBU_TRIGGER_DATA 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
	// Transports mirrors the Story's declared transports, allowing engrams to decide whether
	// to keep payloads on the hot path (e.g., LiveKit) or fall back to storage without
	// rereading pod environment.
	Transports []TransportDescriptor
	// Envelope carries optional stream sequencing metadata from the transport layer.
	// When set, it can be used for ordering and replay-aware processing.
	Envelope *transportpb.StreamEnvelope
}

type StreamingEngram[C any] interface {
	Engram[C]
	// Stream is the core method for handling bidirectional data flow with metadata.
	// The SDK provides inbound messages plus an outbound StreamMessage channel.
	// Metadata should be propagated to enable tracing across the streaming pipeline.
	// The method should process messages from `in`, call Done on messages it handled
	// successfully (or intentionally dropped), and write results to `out` until the
	// input channel is closed or the context is canceled.
	Stream(ctx context.Context, in <-chan InboundMessage, out chan<- StreamMessage) error
}

type TransportDescriptor struct {
	// Name is the transport binding name referenced by the Story.
	Name string `json:"name"`
	// Kind identifies the transport driver kind, such as "livekit" or "storage".
	Kind string `json:"kind"`
	// Mode selects the runtime behavior for the transport binding.
	Mode string `json:"mode,omitempty"`
	// Config carries arbitrary transport-specific settings.
	Config map[string]any `json:"config,omitempty"`
}

type VideoFrame struct {
	// Payload contains encoded bytes or raw pixel data for the frame.
	Payload []byte
	// Codec identifies the encoded video format (for example, "h264"), if applicable.
	Codec string
	// Width is the frame width in pixels.
	Width uint32
	// Height is the frame height in pixels.
	Height uint32
	// Timestamp is the media timeline position for this frame.
	Timestamp time.Duration
	// Raw reports whether Payload carries raw video pixels instead of encoded bytes.
	Raw bool
}