first commit

pigo/agent/doc.go

@@ -0,0 +1,63 @@
+// Package agent is the public, embeddable SDK for driving a pigo agent from
+// your own Go program. It wraps pigo's internal run-assembly, provider, and
+// agent-loop packages behind a small surface whose every exported type is a Go
+// primitive (string, []string, bool, func) — so importing this package never
+// pulls an internal type into your code, and pigo can evolve its internals
+// without breaking you.
+//
+// # Quick start
+//
+//	sess, err := agent.New(
+//		agent.WithModel("claude-opus-4-8"),
+//		agent.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
+//	)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//	defer sess.Close()
+//
+//	reply, err := sess.Prompt(context.Background(), "Say hello in one word.")
+//	fmt.Println(reply)
+//
+// # Model, provider, credentials
+//
+// The model id selects the provider the same way the pigo CLI does:
+// "claude-opus-4-8" resolves to Anthropic, "openrouter/free" to OpenRouter,
+// and so on. Point at any OpenAI- or Anthropic-compatible endpoint with
+// [WithBaseURL] + [WithProtocol], or a named provider from your config with
+// [WithProvider]. The API key comes from [WithAPIKey] or, if unset, the
+// provider's usual environment variable (e.g. ANTHROPIC_API_KEY). Keys are
+// never logged.
+//
+// # Tools run automatically — read this
+//
+// By default a session is created with pigo's full built-in tool set (read,
+// write, edit, bash, find, grep, and more) and those tools are executed WITHOUT
+// any per-call confirmation prompt — equivalent to running the CLI with
+// --approve. An agent can therefore read, modify, and delete files under its
+// working directory and run shell commands on the host. This is the right
+// default for an automated SDK, but it means you should only send prompts you
+// trust, and run in a directory (and, ideally, a sandbox) you are willing to let
+// the agent modify. To constrain or remove that capability use [WithTools] (an
+// allowlist), [WithDisallowedTools] (a denylist, which always wins), or
+// [WithoutTools] (a pure text completion with no tools at all).
+//
+// # Conversation state
+//
+// A [Session] keeps the running conversation: each [Session.Prompt] or
+// [Session.Stream] call appends to the same history, so follow-up prompts see
+// what came before. Call [Session.Reset] to start a fresh conversation on the
+// same session, or [Session.Close] when you are done. A Session is NOT safe for
+// concurrent use — drive it from one goroutine, or create one Session per
+// goroutine.
+//
+// # Defaults
+//
+//   - Tools: on (full built-in set, auto-executed; see the safety note above).
+//   - Skills: off — enable discovery of on-disk skills with [WithSkills].
+//   - Memory: off — enable the persistent memory store with [WithMemory].
+//   - Thinking: "medium" — override with [WithThinkingLevel].
+//
+// Skills and memory are off by default so an embedded session is hermetic: it
+// does not read or write the machine's shared pigo state unless you ask it to.
+package agent