Improve chaining (#16)

* Improve chaining

Use Golang idiomatic functions to chain agents. Support chaining
at AWS using Step Functions. Add utility for chaining agents over
file system.

Author: fogfish

README.md

@@ -53,7 +53,7 @@ In this library, an agent is defined as a side-effect function `ƒ: A ⟼ B`, wh
   - [Encoder \& Decoder](#encoder--decoder)
   - [Commands \& Tools](#commands--tools)
   - [Agent profiles](#agent-profiles)
-- [Agent chains](#agent-chains)
+- [Agent composition (chaining)](#agent-composition-chaining)
 - [FAQ](#faq)
 - [How To Contribute](#how-to-contribute)
   - [commit message](#commit-message)
@@ -266,12 +266,13 @@ The application assembles agents from three elements: memory, reasoner and codec
 * `Worker` uses LLMs and external tools to solve the task. 
 
 
-## Agent chains
+## Agent composition (chaining)
 
-The `thinker` library does not provide built-in mechanisms for chaining agents. Instead, it encourages the use of standard Go techniques either pure functional chaining or chaining of go routines (e.g. [golem/pipe](https://github.com/fogfish/golem)). 
+The `thinker` library does not provide built-in mechanisms for chaining agents. Instead, it encourages the use of ideomatic Go, pure functional chaining. 
 
-The [chain example](./examples/05_chain/chain.go) demostrates off-the-shelf techniques for agents chaining.
+The ["Chain" example](./examples/05_chain/chain.go) demonstrates off-the-shelf techniques for agents chaining.
 
+The ["Text Processor" example](./06_text_processor/processor.go) demonstrates chaining agnet with file system I/O.
 
 ## FAQ
 
@@ -305,6 +306,14 @@ func (*Agent) Deduct(thinker.State[string]) (thinker.Phase, chatter.Prompt, erro
 ```
 </details>
 
+<details>
+<summary>How to deploy agents to AWS?</summary>
+You might consider a AWS Serverless solution for hosting agents.
+AWS Step Functions makes chaining of agents out-of-the-box, which is recommended approach.
+
+You might consider [typestep library](https://github.com/fogfish/typestep) that provides a simplistic approach for defining AWS Step Functions using a type-safe notation in Go.
+</details>
+
 
 
 ## How To Contribute

agent/automata.go

@@ -28,9 +28,9 @@ type Automata[A, B any] struct {
 func NewAutomata[A, B any](
 	llm chatter.Chatter,
 	memory thinker.Memory,
-	reasoner thinker.Reasoner[B],
 	encoder thinker.Encoder[A],
 	decoder thinker.Decoder[B],
+	reasoner thinker.Reasoner[B],
 ) *Automata[A, B] {
 	return &Automata[A, B]{
 		llm:      llm,
@@ -41,25 +41,18 @@ func NewAutomata[A, B any](
 	}
 }
 
-// Prompting agent to perform a work and forgeting the state.
-// The operation is composable using Go-channels
-func (automata *Automata[A, B]) Echo(in A) (B, error) {
-	automata.Purge()
-	return automata.Prompt(context.Background(), in)
-}
-
-// Prompting agent to perform a work and prerve the state.
-// The operation is composable using Go-channels
-func (automata *Automata[A, B]) Seek(in A) (B, error) {
-	return automata.Prompt(context.Background(), in)
-}
-
 // Purge automata's memory
 func (automata *Automata[A, B]) Purge() {
 	automata.reasoner.Purge()
 	automata.memory.Purge()
 }
 
+// Forget the agent state and prompt within a new session
+func (automata *Automata[A, B]) PromptOnce(ctx context.Context, input A, opt ...chatter.Opt) (B, error) {
+	automata.Purge()
+	return automata.Prompt(ctx, input, opt...)
+}
+
 // Prompt agent
 func (automata *Automata[A, B]) Prompt(ctx context.Context, input A, opt ...chatter.Opt) (B, error) {
 	var nul B

agent/prompter.go

@@ -30,18 +30,18 @@ func NewPrompter[A any](llm chatter.Chatter, f func(A) (chatter.Prompt, error))
 		// observations are retained.
 		memory.NewVoid(""),
 
-		// Configures the reasoner, which determines the agent's next actions and prompts.
-		// Here, we use a void reasoner, meaning no reasoning is performed—the agent
-		// simply returns the result.
-		reasoner.NewVoid[string](),
-
 		// Configures the encoder to transform input of type A into a `chatter.Prompt`.
 		// Here, we use an encoder that converts input into prompt.
 		codec.FromEncoder(f),
 
 		// Configure the decoder to transform output of LLM into type B.
 		// Here, we use the identity decoder that returns LLMs output as-is.
 		codec.DecoderID,
+
+		// Configures the reasoner, which determines the agent's next actions and prompts.
+		// Here, we use a void reasoner, meaning no reasoning is performed—the agent
+		// simply returns the result.
+		reasoner.NewVoid[string](),
 	)
 
 	return w

agent/worker.go

@@ -44,18 +44,18 @@ func NewWorker[A any](
 			You are using and remember context from earlier chat history to execute the task.
 		`),
 
-		// Configures the reasoner, which determines the agent's next actions and prompts.
-		// Here, we use a sequence of command reasoner, it assumes that input prompt is
-		// the workflow based on command. LLM guided to execute entire workflow.
-		reasoner.NewEpoch(attempts, reasoner.NewCmdSeq()),
-
 		// Configures the encoder to transform input of type A into a `chatter.Prompt`.
 		// Here, it is defined by application
 		codec.FromEncoder(w.encode),
 
 		// Configure the decoder to transform output of LLM into type B.
 		// The registry knows how to interpret the LLM's reply and executed the command.
 		registry,
+
+		// Configures the reasoner, which determines the agent's next actions and prompts.
+		// Here, we use a sequence of command reasoner, it assumes that input prompt is
+		// the workflow based on command. LLM guided to execute entire workflow.
+		reasoner.NewEpoch(attempts, reasoner.NewCmdSeq()),
 	)
 
 	return w

command/xfs/xfs.go

@@ -97,18 +97,18 @@ func main() {
 		// the agent's observations. Here, we use a stream memory that holds all observations.
 		memory.NewStream(memory.INFINITE, "You are agent who remembers and uses earlier chat history."),
 
-		// Configures the reasoner, which determines the agent's next actions and prompts.
-		// Here, we use custom (app specific) reasoner. The agent is restricted to execute
-		// 4 itterattions before it fails.
-		reasoner.NewEpoch(4, reasoner.From(deduct)),
-
 		// Configures the encoder to transform input of type A into a `chatter.Prompt`.
 		// Here, we use an encoder that builds prompt.
 		codec.FromEncoder(encode),
 
 		// Configure the decoder to transform output of LLM into type B.
 		// Here, we use custom (app specific) codec that parses LLM response into []string.
 		codec.FromDecoder(decode),
+
+		// Configures the reasoner, which determines the agent's next actions and prompts.
+		// Here, we use custom (app specific) reasoner. The agent is restricted to execute
+		// 4 itterattions before it fails.
+		reasoner.NewEpoch(4, reasoner.From(deduct)),
 	)
 
 	// We ask agent about the rainbow colors.

examples/02_rainbow/rainbow.go

@@ -98,18 +98,18 @@ func main() {
 			You are using and remember context from earlier chat history to execute the task.
 		`),
 
-		// Configures the reasoner, which determines the agent's next actions and prompts.
-		// Here, we use custom (app specific) reasoner. The agent is restricted to execute
-		// 4 itterattions before it fails.
-		reasoner.NewEpoch(4, reasoner.From(deduct)),
-
 		// Configures the encoder to transform input of type A into a `chatter.Prompt`.
 		// Here, we use an encoder that builds prompt.
 		codec.FromEncoder(encode),
 
 		// Configure the decoder to transform output of LLM into type B.
 		// Here, we use the tool registry to "decode" output into command call.
 		registry,
+
+		// Configures the reasoner, which determines the agent's next actions and prompts.
+		// Here, we use custom (app specific) reasoner. The agent is restricted to execute
+		// 4 itterattions before it fails.
+		reasoner.NewEpoch(4, reasoner.From(deduct)),
 	)
 
 	// Execute agent

examples/03_script/script.go

@@ -13,8 +13,6 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/fogfish/golem/pipe/v2"
-	"github.com/fogfish/golem/pure/monoid"
 	"github.com/kshard/chatter"
 	"github.com/kshard/chatter/llm/autoconfig"
 	"github.com/kshard/thinker"
@@ -81,48 +79,38 @@ func main() {
 	agtB := NewAgentB(llm)
 
 	//
-	// chaining agents using Go channels and fogfish/golem/pipe
-
-	// create context to manage the chain
-	ctx, close := context.WithCancel(context.Background())
-
-	// Input to the chain
-	who := pipe.Seq("Cat", "Dog", "Cow", "Pig")
-
-	// Use agent to transform input into story
-	story := pipe.StdErr(pipe.Map(ctx, who, pipe.Lift(agtA.Seek)))
-
-	// Write stories into file system
-	file := pipe.StdErr(pipe.Map(ctx, story, pipe.Lift(txt2file)))
-
-	// Wait until all files are written
-	syn := pipe.Fold(ctx, file, mString)
+	// chaining agents using pure Go
+	for _, who := range []string{"Cat", "Dog", "Cow", "Pig"} {
+		// Use agent to transform animal input into story
+		story, err := agtA.PromptOnce(context.Background(), who)
+		if err != nil {
+			panic(err)
+		}
+
+		// Write stories into file system
+		err = txt2file(story)
+		if err != nil {
+			panic(err)
+		}
+	}
 
 	// Use agent to conduct analysis of local files
-	act := pipe.StdErr(pipe.Map(ctx, syn, pipe.Lift(agtB.Echo)))
-
-	// Output the result of the pipeline
-	<-pipe.ForEach(ctx, act, pipe.Pure(stdout))
+	reply, err := agtB.PromptOnce(context.Background(), "")
+	if err != nil {
+		panic(err)
+	}
 
-	close()
+	fmt.Printf("==> %s\n", reply.Output)
 }
 
-func txt2file(x string) (string, error) {
+func txt2file(x string) error {
 	fd, err := os.CreateTemp("/tmp/script", "*.txt")
 	if err != nil {
-		return "", err
+		return err
 	}
 	defer fd.Close()
 	if _, err := fd.WriteString(x); err != nil {
-		return "", err
+		return err
 	}
-	return fd.Name(), nil
-}
-
-// naive string monoid
-var mString = monoid.FromOp("", func(a string, b string) string { return a + " " + b })
-
-func stdout(x thinker.CmdOut) thinker.CmdOut {
-	fmt.Printf("==> %s\n", x.Output)
-	return x
+	return nil
 }