@genui-a3/create 0.1.8 → 0.1.9

package/template/docs/LOGGING.md

@@ -0,0 +1,104 @@
+# Logging
+
+A3 uses [LogLayer](https://loglayer.dev) as its logging abstraction and [tslog](https://tslog.js.org) as the default output backend.
+
+## For package users
+
+If you want A3's logs to flow through your own logging infrastructure, see [Custom Logging](./CUSTOM_LOGGING.md).
+
+---
+
+## Architecture
+
+### The `log` singleton
+
+All logging within the A3 package is done through a single `log` object exported from `src/utils/logger/`.
+
+```typescript
+import { log } from '@utils/logger'
+```
+
+Internally, `log` is a JavaScript `Proxy` that delegates every property access to `getLogger()` at call time.
+This means:
+
+- Any file can import `log` once at the top and use it directly — no need to call `getLogger()` at each use site.
+- If a user calls `configureLogger()` at application startup (before the first log statement fires), the new logger takes effect automatically.
+  The `log` reference does not need to be re-imported.
+
+### `getLogger()` and `configureLogger()`
+
+- `getLogger()` — lazily initialises and returns the active [`ILogLayer`](https://loglayer.dev) instance.
+  On first call, if no custom logger has been set, it creates the default tslog-backed logger.
+- `configureLogger(logger: ILogLayer)` — replaces the active logger.
+  Should be called once at application startup, before any `ChatSession` is created.
+
+Both are exported from `@genui-a3/core` as part of the public API.
+
+### Default logger
+
+The default logger is a `LogLayer` instance wrapping a `tslog` transport:
+
+- Pretty, human-readable output when `NODE_ENV !== 'production'`
+- Structured JSON output when `NODE_ENV === 'production'`
+- Log level controlled by the `A3_LOG_LEVEL` environment variable (default: `info`)
+
+---
+
+## Adding logs in A3 code
+
+Import `log` and use the [LogLayer API](https://loglayer.dev):
+
+```typescript
+import { log } from '@utils/logger'
+
+// Basic logging
+log.info('Hello world!')
+
+// Logging with metadata (attached to this log entry only)
+log.withMetadata({ agentId: 'greeting', sessionId: 'abc' }).debug('Agent selected')
+
+// Logging with context (persists across subsequent log calls on this instance)
+log.withContext({ sessionId: 'abc' })
+log.info('Processing request')
+
+// Logging errors
+log.withError(new Error('Something went wrong')).error('Failed to process request')
+```
+
+For the full LogLayer API — including `withPrefix`, child loggers, plugins, and multi-transport — see the [LogLayer documentation](https://loglayer.dev).
+
+### ⚠️ `withContext()` and shared server state
+
+`log` is a module-level singleton shared across all requests in a running process.
+`withContext()` mutates the logger instance and **persists across all subsequent log calls** — including those from other users' requests on the same pod.
+
+Use `withMetadata()` for any request-scoped data (agentId, sessionId, etc.).
+It applies only to the single log call it's chained on.
+
+```typescript
+// ✅ Safe — applies to this log call only
+log.withMetadata({ agentId: 'greeting', sessionId: 'abc' }).debug('Agent selected')
+
+// ❌ Dangerous in a server — persists on the shared instance across all requests
+log.withContext({ sessionId: 'abc' })
+```
+
+---
+
+## Log levels
+
+The `A3_LOG_LEVEL` environment variable accepts the following values (lowest to highest):
+
+`silly` → `trace` → `debug` → `info` _(default)_ → `warn` → `error` → `fatal`
+
+```bash
+A3_LOG_LEVEL=debug node your-app.js
+```
+
+---
+
+## Key files
+
+- `src/utils/logger/index.ts` — logger module: `log`, `getLogger()`, `configureLogger()`, default tslog setup
+- `src/index.ts` — public exports: `configureLogger`, `getLogger`, `ILogLayer`
+- `jest.setup.ts` — global Jest mock for `@utils/logger` (replaces `log` with a mock object in tests)

package/template/docs/PROVIDERS.md

@@ -0,0 +1,217 @@
+# Providers
+
+LLM provider implementations for the A3 agentic framework.
+
+A3 ships with **AWS Bedrock**, **Anthropic**, and **OpenAI** providers out of the box.
+All three support blocking and streaming modes, model fallback, and structured output via Zod schemas.
+
+## Quick Start
+
+### AWS Bedrock
+
+```typescript
+import { createBedrockProvider } from '@genui-a3/providers/bedrock'
+
+const provider = createBedrockProvider({
+  models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'],
+  region: 'us-east-1', // optional, defaults to AWS SDK default
+})
+```
+
+### Anthropic
+
+```typescript
+import { createAnthropicProvider } from '@genui-a3/providers/anthropic'
+
+const provider = createAnthropicProvider({
+  models: ['claude-sonnet-4-5-20250929', 'claude-haiku-4-5-20251001'],
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional, defaults to ANTHROPIC_API_KEY env var
+})
+```
+
+### OpenAI
+
+```typescript
+import { createOpenAIProvider } from '@genui-a3/providers/openai'
+
+const provider = createOpenAIProvider({
+  models: ['gpt-4o', 'gpt-4o-mini'],
+  apiKey: process.env.OPENAI_API_KEY, // optional, defaults to OPENAI_API_KEY env var
+})
+```
+
+### Use with A3
+
+```typescript
+import { ChatSession, MemorySessionStore } from '@genui-a3/core'
+
+const session = new ChatSession({
+  sessionId: 'user-123',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeting',
+  initialState: {},
+  provider, // any provider from above
+})
+
+// Blocking
+const response = await session.send({ message: 'Hello!' })
+
+// Streaming
+for await (const event of session.send({ message: 'Hello!', stream: true })) {
+  console.log(event)
+}
+```
+
+## Provider Reference
+
+### Bedrock — `createBedrockProvider(config)`
+
+Communicates with AWS Bedrock via the [Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html).
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `models` | `string[]` | Yes | Model IDs in preference order (first = primary, rest = fallbacks) |
+| `region` | `string` | No | AWS region. Defaults to AWS SDK default |
+| `resilience` | `ResilienceConfig` | No | Retry, backoff, and timeout settings. Uses defaults if omitted |
+
+**Behaviour:**
+
+- Uses **tool-based JSON extraction** (`structuredResponse` tool) for reliable structured output
+- **Streaming** yields text deltas in real-time, then emits a validated tool-call result at the end
+- **Merges sequential same-role messages** to satisfy Bedrock's alternating-role requirement
+- **Prepends an initial user message** (`"Hi"`) so the conversation always starts with a user turn
+
+**Prerequisites:** AWS credentials configured via environment variables, IAM role, or AWS profile — the same setup the AWS SDK expects.
+
+---
+
+### Anthropic — `createAnthropicProvider(config)`
+
+Communicates with the Anthropic Messages API using the [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic) (`@ai-sdk/anthropic`) for structured output.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `models` | `string[]` | Yes | Model IDs in preference order (first = primary, rest = fallbacks) |
+| `apiKey` | `string` | No | API key. Defaults to `ANTHROPIC_API_KEY` env var |
+| `baseURL` | `string` | No | Custom base URL for the Anthropic API |
+| `resilience` | `ResilienceConfig` | No | Retry, backoff, and timeout settings. Uses defaults if omitted |
+
+**Behaviour:**
+
+- Uses the Vercel AI SDK's `Output.object()` for structured output — Zod schema conversion and partial JSON parsing handled internally
+- **Streaming** yields text deltas in real-time via partial object tracking, then emits a validated tool-call result at the end
+- **Appends a `"Continue"` user message** if the last message has an assistant role, to satisfy the alternating-role requirement
+
+**Prerequisites:** An Anthropic API key, either passed directly or set as `ANTHROPIC_API_KEY`.
+
+---
+
+### OpenAI — `createOpenAIProvider(config)`
+
+Communicates with the OpenAI Chat Completions API using [structured output](https://platform.openai.com/docs/guides/structured-outputs) (`response_format: json_schema`).
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `models` | `string[]` | Yes | Model IDs in preference order (first = primary, rest = fallbacks) |
+| `apiKey` | `string` | No | API key. Defaults to `OPENAI_API_KEY` env var |
+| `baseURL` | `string` | No | Custom base URL for Azure OpenAI or compatible endpoints |
+| `organization` | `string` | No | OpenAI organization ID |
+| `resilience` | `ResilienceConfig` | No | Retry, backoff, and timeout settings. Uses defaults if omitted |
+
+**Behaviour:**
+
+- Uses **structured output** (`response_format` with `json_schema`) — no tool calls required
+- **Enforces strict schemas** automatically (`additionalProperties: false`, all properties `required`)
+- **Streaming** extracts `chatbotMessage` text progressively from the JSON response via a character-level state machine, yielding text deltas in real-time
+- Detects **truncated responses** (`finish_reason: length`) and surfaces them as errors
+
+**Prerequisites:** An OpenAI API key, either passed directly or set as `OPENAI_API_KEY`.
+
+## Model Fallback
+
+All providers support automatic model fallback.
+List models in order of preference:
+
+```typescript
+const provider = createBedrockProvider({
+  models: [
+    'us.anthropic.claude-sonnet-4-5-20250929-v1:0',  // primary
+    'us.anthropic.claude-haiku-4-5-20251001-v1:0',   // fallback
+  ],
+})
+```
+
+If the primary model fails, the provider automatically retries with the next model in the list.
+If all models fail, the last error is thrown.
+
+All providers include built-in resilience: automatic retries with exponential backoff, per-request and total timeouts, and model fallback.
+See the [Resilience documentation](./RESILIENCE.md) for configuration options and defaults.
+
+## Per-Agent Provider Override
+
+Each agent can override the session-level provider:
+
+```typescript
+import { createOpenAIProvider } from '@genui-a3/providers/openai'
+import { createBedrockProvider } from '@genui-a3/providers/bedrock'
+
+// Session uses Bedrock by default
+const session = new ChatSession({
+  provider: createBedrockProvider({ models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'] }),
+  // ...
+})
+
+// This agent uses OpenAI instead
+const premiumAgent = {
+  id: 'premium',
+  description: 'Handles premium tier requests using GPT-4o',
+  provider: createOpenAIProvider({ models: ['gpt-4o'] }),
+  // ...
+}
+```
+
+## Provider Interface
+
+All providers implement the `Provider` interface from `@genui-a3`:
+
+| Member | Description |
+|---|---|
+| `sendRequest(request)` | Blocking request → `Promise<ProviderResponse>` |
+| `sendRequestStream(request)` | Streaming request → `AsyncGenerator<StreamEvent>` |
+| `name` | Human-readable name (`'bedrock'`, `'anthropic'`, or `'openai'`) |
+
+To create a custom provider, implement this interface and pass it to `ChatSession` or an individual agent.
+See [Creating a Custom Provider](./CUSTOM_PROVIDERS.md) for a step-by-step guide.
+
+## Exports
+
+This package uses [subpath exports](https://nodejs.org/api/packages.html#subpath-exports).
+Import from the specific provider entry point:
+
+```typescript
+// Correct
+import { createBedrockProvider } from '@genui-a3/providers/bedrock'
+import { createAnthropicProvider } from '@genui-a3/providers/anthropic'
+import { createOpenAIProvider } from '@genui-a3/providers/openai'
+
+// No bare import
+import { ... } from '@genui-a3/providers'
+```
+
+| Entry point | Export | Description |
+|---|---|---|
+| `@genui-a3/providers/bedrock` | `createBedrockProvider` | Factory function returning a Bedrock `Provider` |
+| `@genui-a3/providers/bedrock` | `BedrockProviderConfig` | TypeScript config interface |
+| `@genui-a3/providers/anthropic` | `createAnthropicProvider` | Factory function returning an Anthropic `Provider` |
+| `@genui-a3/providers/anthropic` | `AnthropicProviderConfig` | TypeScript config interface |
+| `@genui-a3/providers/openai` | `createOpenAIProvider` | Factory function returning an OpenAI `Provider` |
+| `@genui-a3/providers/openai` | `OpenAIProviderConfig` | TypeScript config interface |
+
+## Requirements
+
+- Node.js 20.19.0+
+- TypeScript 5.9+
+- `@genui-a3/core` (peer dependency)
+- **Bedrock**: AWS credentials configured in the environment
+- **Anthropic**: `ANTHROPIC_API_KEY` environment variable or `apiKey` config option
+- **OpenAI**: `OPENAI_API_KEY` environment variable or `apiKey` config option

package/template/docs/QUICK-START-EXAMPLES.md

@@ -0,0 +1,197 @@
+# Quick Start
+
+The fastest way to get started with A3 is using the interactive CLI. It scaffolds a full Next.js application, configures your LLM providers, and installs dependencies.
+
+```bash
+npx @genui-a3/create@latest
+```
+
+Follow the prompts to name your project and provide your API keys. Once finished:
+
+```bash
+cd your-project-name
+npm run dev
+```
+
+For more details on the CLI, see the [@genui-a3/create README](https://www.npmjs.com/package/@genui-a3/create).
+
+---
+
+## Manual Installation
+
+If you are adding A3 to an existing project or prefer a manual setup, follow these steps.
+
+### Install
+
+```bash
+npm install @genui-a3/core
+```
+
+## Define an agent
+
+```typescript
+import { z } from 'zod'
+import { Agent, BaseState } from '@genui-a3/core'
+
+interface State extends BaseState {
+  userName?: string
+}
+
+export const greetingAgent: Agent<State> = {
+  id: 'greeting',
+  name: 'Greeting Agent',
+  description: 'Greets the user and collects their name',
+  prompt: async () => `
+    You are a friendly greeting agent. Your goal is to greet the user
+    and learn their name. Once you have their name, set goalAchieved to true.
+  `,
+  outputSchema: z.object({
+    userName: z.string().optional(),
+  }),
+  transition: (_state, goalAchieved) =>
+    goalAchieved ? 'end' : 'greeting',
+}
+```
+
+## Register and run
+
+```typescript
+import { AgentRegistry, ChatSession, MemorySessionStore } from '@genui-a3/core'
+import { createBedrockProvider } from '@genui-a3/providers/bedrock'
+
+const registry = AgentRegistry.getInstance<State>()
+registry.register(greetingAgent)
+
+const provider = createBedrockProvider({
+  models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'],
+})
+
+const session = new ChatSession<State>({
+  sessionId: 'demo',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeting',
+  initialState: { userName: undefined },
+  provider,
+})
+
+const response = await session.send({ message: 'Hi there!' })
+console.log(response.responseMessage)
+// => "Hello! I'd love to get to know you. What's your name?"
+```
+
+That's it.
+One agent, one session, one function call.
+
+## Multi-Agent Example
+
+Here's a pattern with three agents that route between each other, demonstrating how state flows across agent boundaries.
+
+### Define the agents
+
+```typescript
+import { z } from 'zod'
+import { Agent, BaseState } from '@genui-a3/core'
+
+interface AppState extends BaseState {
+  userName?: string
+  isAuthenticated: boolean
+  issueCategory?: string
+}
+
+// Agent 1: Greeting -- collects the user's name, then routes to auth
+const greetingAgent: Agent<AppState> = {
+  id: 'greeting',
+  name: 'Greeting Agent',
+  description: 'Greets the user and collects their name',
+  prompt: async () => `
+    Greet the user warmly. Ask for their name.
+    Once you have it, set goalAchieved to true.
+  `,
+  outputSchema: z.object({ userName: z.string().optional() }),
+  transition: (_state, goalAchieved) =>
+    goalAchieved ? 'auth' : 'greeting',
+}
+
+// Agent 2: Auth -- verifies identity, then routes to support
+const authAgent: Agent<AppState> = {
+  id: 'auth',
+  name: 'Auth Agent',
+  description: 'Verifies user identity',
+  prompt: async ({ sessionData }) => `
+    The user's name is ${sessionData.state.userName}.
+    Ask them to confirm their email to verify identity.
+    Set goalAchieved to true once verified.
+  `,
+  outputSchema: z.object({ isAuthenticated: z.boolean() }),
+  transition: (_state, goalAchieved) =>
+    goalAchieved ? 'support' : 'auth',
+}
+
+// Agent 3: Support -- handles the user's issue
+const supportAgent: Agent<AppState> = {
+  id: 'support',
+  name: 'Support Agent',
+  description: 'Helps resolve user issues',
+  prompt: async ({ sessionData }) => `
+    The user ${sessionData.state.userName} is authenticated.
+    Help them with their issue. Categorize it.
+    Set goalAchieved when resolved.
+  `,
+  outputSchema: z.object({
+    issueCategory: z.string().optional(),
+  }),
+  transition: (_state, goalAchieved) =>
+    goalAchieved ? 'end' : 'support',
+}
+```
+
+### Wire them up
+
+```typescript
+import { AgentRegistry, ChatSession, MemorySessionStore } from '@genui-a3/core'
+import { createBedrockProvider } from '@genui-a3/providers/bedrock'
+
+const registry = AgentRegistry.getInstance<AppState>()
+registry.register([greetingAgent, authAgent, supportAgent])
+
+const provider = createBedrockProvider({
+  models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'],
+})
+
+const session = new ChatSession<AppState>({
+  sessionId: 'user-456',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeting',
+  initialState: { isAuthenticated: false },
+  provider,
+})
+```
+
+### Conversation flow
+
+```typescript
+// Turn 1: User greets, greeting agent responds
+await session.send({ message: 'Hello!' })
+// => Greeting agent asks for name
+
+// Turn 2: User provides name, greeting agent completes and chains to auth
+await session.send({ message: "I'm Alex" })
+// => Auth agent asks for email verification
+// (greeting → auth happened automatically in one request)
+
+// Turn 3: User verifies, auth completes and chains to support
+await session.send({ message: 'alex@example.com' })
+// => Support agent asks how it can help
+// State now: { userName: 'Alex', isAuthenticated: true }
+
+// Turn 4: Support agent handles the issue
+await session.send({ message: 'I need help with my billing' })
+// => Support agent resolves the issue
+// State: { userName: 'Alex', isAuthenticated: true, issueCategory: 'billing' }
+```
+
+Notice that:
+
+- **State persists across agents**: `userName` set by the greeting agent is available to auth and support
+- **Agent chaining is automatic**: when greeting completes, auth starts in the same request
+- **Each agent has its own prompt and schema**: they extract different data but share the same state