Documentation
¶
Overview ¶
Package maestro is the canonical embedding API for Maestro.
Typical application flow:
rt, err := maestro.Load("workflow.yaml")
in, err := rt.NewInstance(maestro.InstanceOptions{...})
res := in.RunUntilBlocked()
// when res.Status == engine.RunBlocked:
sub := in.SubmitInput(map[string]any{...})
Persist and resume across requests with pkg/run.Store, run.RecordFromInstance, and rt.RestoreInstance (preferred over run.InstanceFromRecord in application code).
Use pkg/engine and pkg/run directly for advanced or custom integrations.
Index ¶
- type InstanceOptions
- type Runtime
- func Compile(def *definition.WorkflowDefinition, vopts validate.Options) (*Runtime, error)
- func Load(path string) (*Runtime, error)
- func LoadJSON(data []byte) (*Runtime, error)
- func LoadJSONWithValidate(data []byte, vopts validate.Options) (*Runtime, error)
- func LoadWithValidate(path string, vopts validate.Options) (*Runtime, error)
- func LoadYAML(data []byte) (*Runtime, error)
- func LoadYAMLWithValidate(data []byte, vopts validate.Options) (*Runtime, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InstanceOptions ¶
type InstanceOptions struct {
// RunID overrides the run id; when empty on restore, RunRecord.RunID is used.
RunID string
// InitialVariables are applied only when creating a new instance (not on restore).
InitialVariables map[string]any
// TraceGuards enables transition guard events in the execution trace.
TraceGuards bool
// ActionRegistry provides action runners; nil uses engine.DefaultRegistry().
ActionRegistry *engine.Registry
}
InstanceOptions configures Runtime.NewInstance and Runtime.RestoreInstance. A zero value uses DefaultRegistry (stub only).
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime is a validated workflow definition ready to instantiate with Runtime.NewInstance.
Runtime is safe to reuse concurrently after it is created. Callers must not mutate the definition returned by Runtime.Definition.
func Compile ¶
func Compile(def *definition.WorkflowDefinition, vopts validate.Options) (*Runtime, error)
Compile validates an in-memory definition (codegen, tests) without reading bytes from disk.
func LoadJSONWithValidate ¶
LoadJSONWithValidate is LoadJSON with custom validate.Options.
func LoadWithValidate ¶
LoadWithValidate is like Load but uses custom validation options (schema path, verbose, etc.).
func LoadYAML ¶
LoadYAML decodes and validates workflow YAML bytes (for //go:embed, config services, tests).
Example ¶
package main
import (
"fmt"
"log"
"github.com/justinush/maestro/pkg/engine"
"github.com/justinush/maestro/pkg/maestro"
)
const exampleWorkflowYAML = `
schemaVersion: "0.1"
id: example
version: "1"
initialStepId: start
terminalStepIds: [done]
steps:
- id: start
kind: action
- id: done
kind: end
transitions:
- from: start
to: done
priority: 0
`
func main() {
rt, err := maestro.LoadYAML([]byte(exampleWorkflowYAML))
if err != nil {
log.Fatal(err)
}
in, err := rt.NewInstance(maestro.InstanceOptions{})
if err != nil {
log.Fatal(err)
}
res := in.RunUntilBlocked()
fmt.Println(res.Status == engine.RunCompleted)
}
Output: true
func LoadYAMLWithValidate ¶
LoadYAMLWithValidate is LoadYAML with custom validate.Options.
func (*Runtime) Definition ¶
func (rt *Runtime) Definition() *definition.WorkflowDefinition
Definition returns the validated workflow. Callers must not mutate it.
func (*Runtime) NewInstance ¶
func (rt *Runtime) NewInstance(opts InstanceOptions) (*engine.Instance, error)
NewInstance builds an engine.Instance for this workflow at initialStepId.
func (*Runtime) RestoreInstance ¶
func (rt *Runtime) RestoreInstance(rec *run.RunRecord, opts InstanceOptions) (*engine.Instance, error)
RestoreInstance rebuilds an engine.Instance from a stored RunRecord.
This is the preferred restore path for application code. Use the same ActionRegistry and TraceGuards semantics as when the run was created. RunID is taken from opts when set, otherwise from rec.RunID.
run.InstanceFromRecord offers the same restore at the persistence layer for custom Store implementations.
Source Files