feat(api): clarify character-first agent creation (#29)

Author: lucasnevespereira

README.md

@@ -44,7 +44,7 @@ Go users can also install from source:
 go install github.com/snowztech/vikusha/cmd/vikusha@latest
 ```
 
-### Option 1: YAML
+### Character YAML
 
 Create `character.yaml`.
 
@@ -77,38 +77,20 @@ For structured turn logs, pass `-log-json`. Named agents append logs to `~/.viku
 vikusha chat -log-json writer
 ```
 
-You can load the same YAML from Go.
+You can load the same character from Go.
 
 ```go
-a, err := vikusha.LoadAgent("character.yaml", vikusha.Options{})
+a, err := vikusha.LoadAgent("character.yaml", vikusha.BuildOptions{})
 reply, err := a.Chat(ctx, "lucas", "hello")
 _ = reply
 
 // From another goroutine or transport command:
 a.Cancel("lucas")
 ```
 
-### Option 2: Go
+For advanced Go usage where you want to wire provider instances, tool registries, or memory yourself, use `agent.New`; see [examples/file_read](examples/file_read).
 
-Use `agent.New` when you want to pass the provider and tools yourself.
-
-```go
-reg := tool.NewRegistry()
-reg.Register(file.NewList())
-reg.Register(file.NewRead())
-
-a, err := agent.New(agent.Options{
-	Name:         "Helper",
-	Model:        "gpt-4o-mini",
-	SystemPrompt: "You are helpful.",
-	Provider:     llm.NewOpenAI(os.Getenv("OPENAI_API_KEY")),
-	Tools:        reg,
-})
-```
-
-Both paths return an `*agent.Agent`; call `Chat(ctx, userID, msg)` to run a turn and `Cancel(userID)` to stop that user's active turn.
-
-## Character YAML
+## YAML Fields
 
 The fields implemented today are:
 
@@ -133,8 +115,8 @@ If `provider` is omitted, Vikusha infers Anthropic for models beginning with `cl
 See:
 
 - [examples/from_yaml](examples/from_yaml): create an agent from YAML.
-- [examples/hello](examples/hello): create the smallest agent with `agent.New`.
-- [examples/file_read](examples/file_read): create an agent with registered file tools.
+- [examples/hello](examples/hello): load a character and run one turn.
+- [examples/file_read](examples/file_read): advanced manual construction with registered file tools.
 
 ---
 

cmd/vikusha/main.go

@@ -201,7 +201,7 @@ func defaultAPIKeyEnv(provider string) string {
 }
 
 func buildAgent(path string, logger agent.TurnLogger) (*agent.Agent, error) {
-	return vikusha.LoadAgent(path, vikusha.Options{
+	return vikusha.LoadAgent(path, vikusha.BuildOptions{
 		Workspace: workspaceForCharacter(path),
 		Logger:    logger,
 	})

core/agent/agent.go

@@ -37,6 +37,8 @@ type turnCancel struct {
 	cancel context.CancelFunc
 }
 
+// Options contains the runtime dependencies required to construct an Agent
+// directly. Most users should prefer vikusha.LoadAgent or vikusha.NewAgent.
 type Options struct {
 	Name          string
 	Model         string

docs/ARCHITECTURE.md

@@ -10,19 +10,18 @@ This document describes Vikusha's target architecture. When a concept is not imp
 4. **Flat conceptual model.** Tools, transports, memory backends, and LLM providers are distinct, named concepts.
 5. **Character as data.** A YAML file is the entire assistant definition. Same binary, different YAML = different assistant.
 6. **Observability over magic.** The user should be able to see which tool ran, which model was called, and which memory was injected.
-7. **Two modes of use.** Go framework for developers who embed Vikusha, YAML runtime for configured assistants.
+7. **Character-first creation.** A character definition is built into the agent runtime. YAML is the normal user-facing format.
 
 ## Target System Flow
 
-Vikusha has two entry paths that meet at the same agent loop:
+Vikusha's normal path is character YAML into the agent loop:
 
 ```mermaid
 flowchart LR
     yaml[character.yaml] --> loader[character loader]
     cli[vikusha CLI] --> loader
-    app[Go app] --> manual[agent.New options]
     loader --> build[provider + tools + memory]
-    manual --> build
+    manual[advanced agent.New] --> agent[Agent]
     build --> agent[Agent]
     transport[CLI / future transports] --> chat[agent.Chat(ctx, userID, msg)]
     agent --> chat
@@ -34,7 +33,7 @@ flowchart LR
     tools -- no --> reply[reply]
 ```
 
-The framework path is explicit Go construction: the caller passes providers, tools, and memory. The runtime path starts from YAML and lets Vikusha wire those pieces. Both paths produce the same `Agent` runtime.
+The primary path is character-first: YAML describes the assistant, and Vikusha wires providers, tools, memory, workspace, and logging. The lower-level `agent.New` path remains available for advanced Go users who want to pass runtime dependencies themselves.
 
 ## Core concepts
 

docs/NORTHSTAR.md

@@ -4,23 +4,9 @@ Vikusha is a Go framework and runtime for always-on AI assistants.
 
 The goal is simple: define an assistant once, then run it wherever people need it.
 
-## Two Paths
+## Core Idea
 
-### Go framework
-
-Go developers can import Vikusha, wire providers and tools, and call:
-
-```go
-reply, err := agent.Chat(ctx, userID, msg)
-```
-
-This path is for custom binaries, SaaS backends, internal tools, and tests.
-
-### YAML runtime
-
-Users can define an assistant in a character YAML and run it with the `vikusha` CLI.
-
-Today that starts with:
+Vikusha turns a character into a runnable agent. The normal user-facing character format is YAML:
 
 ```bash
 vikusha chat character.yaml
@@ -36,6 +22,8 @@ vikusha chat writer
 
 In that model, `writer` is backed by a character YAML and has its own tools, memory, workspace, logs, secrets, and transports.
 
+Go developers can load the same character from code, or use lower-level APIs when they need custom wiring.
+
 ## Always-On Assistants
 
 Always-on means the assistant is a long-running process, not just a one-off prompt.

examples/file_read/main.go

@@ -1,5 +1,5 @@
-// file_read shows an agent using a tool. The agent is given the file_read
-// tool and asked a question that requires reading a file to answer.
+// file_read shows advanced manual construction. The agent is given file tools
+// directly and asked a question that requires reading a file to answer.
 //
 //	OPENROUTER_API_KEY=... go run ./examples/file_read
 package main
@@ -26,6 +26,7 @@ func main() {
 	}
 
 	reg := tool.NewRegistry()
+	reg.Register(file.NewList())
 	reg.Register(file.NewRead())
 
 	a, err := agent.New(agent.Options{

examples/from_yaml/main.go

@@ -17,7 +17,7 @@ import (
 func main() {
 	_ = godotenv.Load()
 
-	a, err := vikusha.LoadAgent("examples/character.yaml", vikusha.Options{})
+	a, err := vikusha.LoadAgent("examples/character.yaml", vikusha.BuildOptions{})
 	if err != nil {
 		log.Fatal(err)
 	}

examples/hello/main.go

@@ -1,5 +1,4 @@
-// hello shows the smallest possible vikusha agent: no tools, one turn,
-// answer a question.
+// hello shows the normal Go path: load a character YAML and run one turn.
 //
 //	OPENROUTER_API_KEY=... go run ./examples/hello
 package main
@@ -8,27 +7,15 @@ import (
 	"context"
 	"fmt"
 	"log"
-	"os"
 	"time"
 
 	"github.com/joho/godotenv"
-	"github.com/snowztech/vikusha/core/agent"
-	"github.com/snowztech/vikusha/core/llm"
+	"github.com/snowztech/vikusha"
 )
 
 func main() {
 	_ = godotenv.Load()
-	apiKey := os.Getenv("OPENROUTER_API_KEY")
-	if apiKey == "" {
-		log.Fatal("OPENROUTER_API_KEY not set")
-	}
-
-	a, err := agent.New(agent.Options{
-		Name:         "hello",
-		Model:        "openai/gpt-4o-mini",
-		SystemPrompt: "You are a friendly assistant. Reply in one short sentence.",
-		Provider:     llm.NewOpenRouter(apiKey),
-	})
+	a, err := vikusha.LoadAgent("examples/character.yaml", vikusha.BuildOptions{})
 	if err != nil {
 		log.Fatal(err)
 	}

vikusha.go

@@ -14,23 +14,28 @@ import (
 	"github.com/snowztech/vikusha/core/tools/file"
 )
 
-type Options struct {
-	Env           func(string) string
-	Tools         map[string]tool.Tool
-	Workspace     string
-	ToolResultCap int
-	Logger        agent.TurnLogger
+// BuildOptions controls how Vikusha wires character YAML into a runtime agent.
+//
+// The character file describes the assistant. BuildOptions describes the host
+// process: env lookup, custom tool implementations, workspace, logging, and
+// runtime limits.
+type BuildOptions struct {
+	Env            func(string) string
+	AvailableTools map[string]tool.Tool
+	Workspace      string
+	ToolResultCap  int
+	Logger         agent.TurnLogger
 }
 
-func LoadAgent(path string, opts Options) (*agent.Agent, error) {
+func LoadAgent(path string, opts BuildOptions) (*agent.Agent, error) {
 	c, err := character.Load(path)
 	if err != nil {
 		return nil, err
 	}
-	return NewAgent(c, opts)
+	return newAgent(c, opts)
 }
 
-func NewAgent(c *character.Character, opts Options) (*agent.Agent, error) {
+func newAgent(c *character.Character, opts BuildOptions) (*agent.Agent, error) {
 	p, err := provider(c, opts)
 	if err != nil {
 		return nil, err
@@ -55,7 +60,7 @@ func NewAgent(c *character.Character, opts Options) (*agent.Agent, error) {
 	})
 }
 
-func provider(c *character.Character, opts Options) (llm.Provider, error) {
+func provider(c *character.Character, opts BuildOptions) (llm.Provider, error) {
 	lookup := opts.Env
 	if lookup == nil {
 		lookup = os.Getenv
@@ -95,13 +100,13 @@ func buildMemory(c *character.Character) (memory.Memory, error) {
 	}
 }
 
-func registry(names []string, opts Options) (*tool.Registry, error) {
+func registry(names []string, opts BuildOptions) (*tool.Registry, error) {
 	reg := tool.NewRegistry()
 	available := map[string]tool.Tool{
 		"file_list": file.NewList(opts.Workspace),
 		"file_read": file.NewRead(opts.Workspace),
 	}
-	for name, t := range opts.Tools {
+	for name, t := range opts.AvailableTools {
 		available[name] = t
 	}
 

vikusha_test.go

@@ -7,6 +7,9 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/snowztech/vikusha/core/character"
+	"github.com/snowztech/vikusha/core/tool"
 )
 
 func TestLoadAgentFromCharacter(t *testing.T) {
@@ -21,7 +24,7 @@ tools:
 		t.Fatal(err)
 	}
 
-	a, err := LoadAgent(path, Options{
+	a, err := LoadAgent(path, BuildOptions{
 		Env: func(name string) string {
 			if name == "OPENAI_API_KEY" {
 				return "test-key"
@@ -37,6 +40,69 @@ tools:
 	}
 }
 
+func TestBuildAgentFromCharacter(t *testing.T) {
+	a, err := newAgent(&character.Character{
+		Name:         "Helper",
+		Model:        "gpt-4o-mini",
+		SystemPrompt: "Be useful.",
+		Provider: character.ProviderConfig{
+			Name:      "openai",
+			APIKeyEnv: "OPENAI_API_KEY",
+		},
+		Tools: []string{"file_list", "file_read"},
+	}, BuildOptions{
+		Env: func(name string) string {
+			if name == "OPENAI_API_KEY" {
+				return "test-key"
+			}
+			return ""
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if a.Name() != "Helper" {
+		t.Fatalf("agent name = %q, want Helper", a.Name())
+	}
+}
+
+type customTool struct{}
+
+func (customTool) Name() string { return "custom" }
+
+func (customTool) Description() string { return "custom tool" }
+
+func (customTool) Schema() json.RawMessage { return json.RawMessage(`{"type":"object"}`) }
+
+func (customTool) Run(ctx context.Context, input json.RawMessage) (string, error) {
+	return "ok", nil
+}
+
+func TestBuildAgentUsesAvailableTools(t *testing.T) {
+	a, err := newAgent(&character.Character{
+		Name:         "Helper",
+		Model:        "gpt-4o-mini",
+		SystemPrompt: "Be useful.",
+		Tools:        []string{"custom"},
+	}, BuildOptions{
+		Env: func(name string) string {
+			if name == "OPENAI_API_KEY" {
+				return "test-key"
+			}
+			return ""
+		},
+		AvailableTools: map[string]tool.Tool{
+			"custom": customTool{},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if a.Name() != "Helper" {
+		t.Fatalf("agent name = %q, want Helper", a.Name())
+	}
+}
+
 func TestLoadAgentRequiresFileMemoryPath(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "character.yaml")
 	if err := os.WriteFile(path, []byte(`
@@ -49,7 +115,7 @@ memory:
 		t.Fatal(err)
 	}
 
-	_, err := LoadAgent(path, Options{
+	_, err := LoadAgent(path, BuildOptions{
 		Env: func(name string) string {
 			if name == "OPENAI_API_KEY" {
 				return "test-key"
@@ -78,7 +144,7 @@ func TestRegistryScopesBuiltInFileToolsToWorkspace(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	reg, err := registry([]string{"file_list", "file_read"}, Options{Workspace: workspace})
+	reg, err := registry([]string{"file_list", "file_read"}, BuildOptions{Workspace: workspace})
 	if err != nil {
 		t.Fatal(err)
 	}