Use a struct with receiver methods to encapsulate state (#6)

Author: fogfish

README.md

@@ -51,6 +51,7 @@ In this library, an agent is defined as a side-effect function `ƒ: A ⟼ B`, wh
   - [Commands \& Tools](#commands--tools)
     - [Supported commands](#supported-commands)
   - [Chaining agents](#chaining-agents)
+- [FAQ](#faq)
 - [How To Contribute](#how-to-contribute)
   - [commit message](#commit-message)
   - [bugs](#bugs)
@@ -205,6 +206,40 @@ The `thinker` library does not provide built-in mechanisms for chaining agents.
 The [chain example](./examples/chain/chain.go) demostrates off-the-shelf techniques for agents chaining.
 
 
+## FAQ
+
+<details>
+<summary>Do agents support concurrent execution?</summary>
+
+This design does not support concurency on the purpose - the pure actor architecture is used. The agent follows a sequential decision-making loop:
+* Inner for {} loop causes each step depends on the previous result to maintain conversational causal effect
+* While memory is thread-safe and sharable among agents in the pipeline. It is not design to support multiple isolated session.
+* LLM calls are synchronous.
+
+To enable concurrency, the application have to implement worker pools.
+</details>
+
+
+<details>
+<summary>How can an agent maintain a global state accessible to the encoder, decoder, and reasoner?</summary>
+
+Use a struct with receiver methods to encapsulate state and provide direct access to the encoder, decoder, and reasoner. This keeps state management simple and idiomatic in Go.
+
+```go
+type Agent struct{
+  // declare global state
+}
+
+func (*Agent) Encode(string) (prompt chatter.Prompt, err error) { /* ... */ }
+
+func (*Agent) Decode(chatter.Reply) (float64, string, error) { /* ... */ }
+
+func (*Agent) Deduct(thinker.State[string]) (thinker.Phase, chatter.Prompt, error) { /* ... */ }
+```
+</details>
+
+
+
 ## How To Contribute
 
 The library is [MIT](LICENSE) licensed and accepts contributions via GitHub pull requests:

agent.go

@@ -29,16 +29,13 @@ const (
 )
 
 // State of the agent, maintained by the agent and used by Reasoner.
-type State[A, B any] struct {
+type State[B any] struct {
 	// Execution phase of the agent
 	Phase Phase
 
 	// Current epoch of execution phase
 	Epoch int
 
-	// Input to LLM
-	Input A
-
 	// Reply from LLM
 	Reply B
 

agent/automata.go

@@ -19,15 +19,15 @@ import (
 type Automata[A, B any] struct {
 	llm      chatter.Chatter
 	memory   thinker.Memory
-	reasoner thinker.Reasoner[A, B]
+	reasoner thinker.Reasoner[B]
 	encoder  thinker.Encoder[A]
 	decoder  thinker.Decoder[B]
 }
 
 func NewAutomata[A, B any](
 	llm chatter.Chatter,
 	memory thinker.Memory,
-	reasoner thinker.Reasoner[A, B],
+	reasoner thinker.Reasoner[B],
 	encoder thinker.Encoder[A],
 	decoder thinker.Decoder[B],
 ) *Automata[A, B] {
@@ -42,7 +42,7 @@ func NewAutomata[A, B any](
 
 func (automata *Automata[A, B]) Prompt(ctx context.Context, input A, opt ...chatter.Opt) (B, error) {
 	var nul B
-	state := thinker.State[A, B]{Phase: thinker.AGENT_ASK, Epoch: 0, Input: input}
+	state := thinker.State[B]{Phase: thinker.AGENT_ASK, Epoch: 0}
 
 	prompt, err := automata.encoder.Encode(input)
 	if err != nil {
@@ -75,7 +75,7 @@ func (automata *Automata[A, B]) Prompt(ctx context.Context, input A, opt ...chat
 
 		switch phase {
 		case thinker.AGENT_ASK:
-			state = thinker.State[A, B]{Phase: thinker.AGENT_ASK, Epoch: 0}
+			state = thinker.State[B]{Phase: thinker.AGENT_ASK, Epoch: 0}
 			prompt = request
 			shortMemory = automata.memory.Context(prompt)
 			continue

examples/chain/chain.go

@@ -36,7 +36,7 @@ func NewAgentA(llm chatter.Chatter) *AgentA {
 	agt := &AgentA{}
 	agt.Automata = agent.NewAutomata(llm,
 		memory.NewVoid(),
-		reasoner.NewVoid[string, string](),
+		reasoner.NewVoid[string](),
 		codec.FromEncoder(agt.story),
 		codec.DecoderID,
 	)
@@ -69,15 +69,15 @@ func NewAgentB(llm chatter.Chatter) *AgentB {
 			You are automomous agent who uses tools to perform required tasks.
 			You are using and remember context from earlier chat history to execute the task.
 		`),
-		reasoner.NewEpoch(4, reasoner.From(agt.deduct)),
-		codec.FromEncoder(agt.encode),
+		reasoner.NewEpoch(4, agt),
+		agt,
 		agt.registry,
 	)
 
 	return agt
 }
 
-func (agt AgentB) encode(string) (prompt chatter.Prompt, err error) {
+func (agt AgentB) Encode(string) (prompt chatter.Prompt, err error) {
 	prompt.WithTask(`
 		Use available tools to complete the workflow:
 		(1) Use available tools to read files one by one.
@@ -89,7 +89,7 @@ func (agt AgentB) encode(string) (prompt chatter.Prompt, err error) {
 	return
 }
 
-func (AgentB) deduct(state thinker.State[string, thinker.CmdOut]) (thinker.Phase, chatter.Prompt, error) {
+func (AgentB) Deduct(state thinker.State[thinker.CmdOut]) (thinker.Phase, chatter.Prompt, error) {
 	// the registry has failed to execute command, we have to supply the feedback to LLM
 	if state.Feedback != nil && state.Confidence < 1.0 {
 		var prompt chatter.Prompt

examples/helloworld/hw.go

@@ -63,7 +63,7 @@ func main() {
 		// 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, string](),
+		reasoner.NewVoid[string](),
 
 		// Configures the encoder to transform input of type A into a `chatter.Prompt`.
 		// Here, we use an encoder that converts string expressions into prompt.

examples/rainbow/rainbow.go

@@ -67,7 +67,7 @@ func validate(seq []string) error {
 }
 
 // deduct new goal for the agent to pursue.
-func deduct(state thinker.State[any, []string]) (thinker.Phase, chatter.Prompt, error) {
+func deduct(state thinker.State[[]string]) (thinker.Phase, chatter.Prompt, error) {
 	// Provide feedback to LLM if there are no confidence about the results
 	if state.Feedback != nil && state.Confidence < 1.0 {
 		var prompt chatter.Prompt

examples/script/script.go

@@ -42,7 +42,7 @@ func encode(q string) (prompt chatter.Prompt, err error) {
 
 // deduct new goal for the agent to pursue.
 // Note, the agent uses registry as decoder therefore agent  is string -> thinker.CmdOut
-func deduct(state thinker.State[string, thinker.CmdOut]) (thinker.Phase, chatter.Prompt, error) {
+func deduct(state thinker.State[thinker.CmdOut]) (thinker.Phase, chatter.Prompt, error) {
 	// the registry has failed to execute command, we have to supply the feedback to LLM
 	if state.Feedback != nil && state.Confidence < 1.0 {
 		var prompt chatter.Prompt

reasoner.go

@@ -17,7 +17,7 @@ import (
 // or non-deterministic analysis of immediate results and past experiences.
 // Based on this assessment, it determines whether the goal has been achieved
 // and, if not, suggests the best new goal for the agent to pursue.
-type Reasoner[A, B any] interface {
+type Reasoner[B any] interface {
 	// Deduct new goal for the agent to pursue.
-	Deduct(State[A, B]) (Phase, chatter.Prompt, error)
+	Deduct(State[B]) (Phase, chatter.Prompt, error)
 }

reasoner/command.go

@@ -16,16 +16,19 @@ import (
 	"github.com/kshard/thinker/command"
 )
 
+// State of Command reasoner
+type StateCmd = thinker.State[thinker.CmdOut]
+
 // The cmd (command) reasoner set the goal for agent to execute a single command.
 // It returns right after the command return results.
-type Cmd[A any] struct{}
+type Cmd struct{}
 
 // Creates new command reasoner.
-func NewCmd[A any]() *Cmd[A] {
-	return &Cmd[A]{}
+func NewCmd() *Cmd {
+	return &Cmd{}
 }
 
-func (task *Cmd[A]) Deduct(state thinker.State[A, thinker.CmdOut]) (thinker.Phase, chatter.Prompt, error) {
+func (task *Cmd) Deduct(state StateCmd) (thinker.Phase, chatter.Prompt, error) {
 	if state.Feedback != nil && state.Confidence < 1.0 {
 		var prompt chatter.Prompt
 		prompt.WithTask("Refine the previous operation using the feedback below.")
@@ -45,13 +48,13 @@ func (task *Cmd[A]) Deduct(state thinker.State[A, thinker.CmdOut]) (thinker.Phas
 
 // The sequence of cmd (commands) reasoner set the goal for agent to execute a sequence of commands.
 // The reason returns only after LLM uses return command.
-type CmdSeq[A any] struct{}
+type CmdSeq struct{}
 
-func NewCmdSeq[A any]() *CmdSeq[A] {
-	return &CmdSeq[A]{}
+func NewCmdSeq() *CmdSeq {
+	return &CmdSeq{}
 }
 
-func (task *CmdSeq[A]) Deduct(state thinker.State[A, thinker.CmdOut]) (thinker.Phase, chatter.Prompt, error) {
+func (task *CmdSeq) Deduct(state StateCmd) (thinker.Phase, chatter.Prompt, error) {
 	if state.Feedback != nil && state.Confidence < 1.0 {
 		var prompt chatter.Prompt
 		prompt.WithTask("Refine the previous workflow step using the feedback below.")

reasoner/command_test.go

@@ -19,10 +19,10 @@ import (
 )
 
 func TestCmdDeduct(t *testing.T) {
-	r := reasoner.NewCmd[string]()
+	r := reasoner.NewCmd()
 
 	t.Run("Refine", func(t *testing.T) {
-		phase, prompt, err := r.Deduct(thinker.State[string, thinker.CmdOut]{
+		phase, prompt, err := r.Deduct(reasoner.StateCmd{
 			Feedback:   chatter.Feedback("feedback"),
 			Confidence: 0.1,
 		})
@@ -35,7 +35,7 @@ func TestCmdDeduct(t *testing.T) {
 	})
 
 	t.Run("Return", func(t *testing.T) {
-		phase, _, err := r.Deduct(thinker.State[string, thinker.CmdOut]{
+		phase, _, err := r.Deduct(reasoner.StateCmd{
 			Reply: thinker.CmdOut{Cmd: command.BASH, Output: "Bash Output"},
 		})
 
@@ -46,7 +46,7 @@ func TestCmdDeduct(t *testing.T) {
 	})
 
 	t.Run("Abort", func(t *testing.T) {
-		phase, _, _ := r.Deduct(thinker.State[string, thinker.CmdOut]{})
+		phase, _, _ := r.Deduct(reasoner.StateCmd{})
 
 		it.Then(t).Should(
 			it.Equal(phase, thinker.AGENT_ABORT),
@@ -56,10 +56,10 @@ func TestCmdDeduct(t *testing.T) {
 }
 
 func TestCmdSeqDeduct(t *testing.T) {
-	r := reasoner.NewCmdSeq[string]()
+	r := reasoner.NewCmdSeq()
 
 	t.Run("Refine", func(t *testing.T) {
-		phase, prompt, err := r.Deduct(thinker.State[string, thinker.CmdOut]{
+		phase, prompt, err := r.Deduct(reasoner.StateCmd{
 			Feedback:   chatter.Feedback("feedback"),
 			Confidence: 0.1,
 		})
@@ -72,7 +72,7 @@ func TestCmdSeqDeduct(t *testing.T) {
 	})
 
 	t.Run("Return", func(t *testing.T) {
-		phase, _, err := r.Deduct(thinker.State[string, thinker.CmdOut]{
+		phase, _, err := r.Deduct(reasoner.StateCmd{
 			Reply: thinker.CmdOut{Cmd: command.RETURN},
 		})
 
@@ -83,7 +83,7 @@ func TestCmdSeqDeduct(t *testing.T) {
 	})
 
 	t.Run("Continue", func(t *testing.T) {
-		phase, prompt, err := r.Deduct(thinker.State[string, thinker.CmdOut]{
+		phase, prompt, err := r.Deduct(reasoner.StateCmd{
 			Reply: thinker.CmdOut{Cmd: command.BASH, Output: "Bash Output"},
 		})
 
@@ -96,11 +96,10 @@ func TestCmdSeqDeduct(t *testing.T) {
 	})
 
 	t.Run("Abort", func(t *testing.T) {
-		phase, _, _ := r.Deduct(thinker.State[string, thinker.CmdOut]{})
+		phase, _, _ := r.Deduct(reasoner.StateCmd{})
 
 		it.Then(t).Should(
 			it.Equal(phase, thinker.AGENT_ABORT),
 		)
 	})
-
 }