@falai/agent 3.4.4 → 4.0.0-alpha.1

package/examples/07-streaming.ts

@@ -1,69 +1,43 @@
 /**
- * Real-time streaming with respondStream and final-chunk metadata.
- * Teaches: respondStream, chunk consumption, appliedInstructions, triggeredSignals.
- * Read after: docs/guides/streaming.md
+ * Streaming: the reply arrives token by token, the result at the end.
+ *
+ * Teaches: `agent.turnStream`, `{ delta }` chunks, the `{ done, result }`
+ * chunk, `llmCalls`.
+ * Read next: docs/guides/streaming.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/07-streaming.ts
  */
 
-import { createAgent, GeminiProvider, createSession, type AgentResponseStreamChunk } from "@falai/agent";
+import { falai, GeminiProvider } from "@falai/agent";
 
-// ─── Schema ──────────────────────────────────────────────────────────────────
-
-interface AppData {
-    topic: string;
-}
-
-// ─── Agent setup ─────────────────────────────────────────────────────────────
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
 
-const agent = createAgent<{}, AppData>({
-    name: "StreamingDemo",
-    provider: new GeminiProvider({
-        apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.5-flash-lite",
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      on: [{ message: [] }],
+      steps: [
+        { id: "nome", collect: ["nome"] },
+        { id: "ajuda", prompt: "Agradeça pelo nome e pergunte como pode ajudar." },
+      ],
     }),
-    schema: {
-        type: "object",
-        properties: {
-            topic: { type: "string" },
-        },
-    },
-    instructions: [
-        { id: "concise", kind: "should", prompt: "Keep answers under 100 words" },
-    ],
-    flows: [
-        {
-            title: "Chat",
-            steps: [{ id: "talk", prompt: "Discuss the user's topic.", collect: ["topic"] }],
-        },
-    ],
+  ],
 });
 
-// ─── Stream consumption ──────────────────────────────────────────────────────
-
-async function streamResponse() {
-    const session = createSession<AppData>("stream-demo");
-    const history = [{ role: "user" as const, content: "Explain how tides work" }];
-
-    const stream = agent.respondStream({ history, session });
-
-    let finalChunk: AgentResponseStreamChunk<AppData> | undefined;
-
-    for await (const chunk of stream) {
-        // Print each delta as it arrives (real-time UX)
-        process.stdout.write(chunk.delta);
-
-        if (chunk.done) {
-            finalChunk = chunk;
-        }
-    }
-
-    console.log("\n");
-
-    // ─── Final-chunk metadata ────────────────────────────────────────────────
-    if (finalChunk) {
-        console.log("Accumulated:", finalChunk.accumulated.length, "chars");
-        console.log("Applied instructions:", finalChunk.appliedInstructions ?? []);
-        console.log("Triggered signals:", finalChunk.triggeredSignals ?? []);
-    }
+// Only the AI's reply streams. `say` messages and everything else come whole,
+// in the final chunk's `result`, exactly as `turn()` would return them.
+for await (const chunk of agent.turnStream({ sessionId: "demo", message: "oi, sou o Rui" })) {
+  if ("delta" in chunk) {
+    process.stdout.write(chunk.delta);
+    continue;
+  }
+  process.stdout.write("\n");
+  console.log(`mensagens: ${chunk.result.messages.length}, chamadas ao modelo: ${chunk.result.llmCalls}`);
+  console.log(chunk.result.session.data); // { nome: 'Rui' }
 }
-
-streamResponse().catch(console.error);

package/examples/08-store-and-migration.ts

@@ -0,0 +1,97 @@
+/**
+ * Persistence: load, turn, save, and the one-time move of a 3.x session.
+ *
+ * Teaches: `Store`, `MemoryStore`, `save(session, expectedVersion)`,
+ * `SessionConflictError`, `migrateSession`, `InvalidSessionError`.
+ * Read next: docs/guides/persistence.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/08-store-and-migration.ts
+ */
+
+import {
+  falai,
+  GeminiProvider,
+  InvalidSessionError,
+  MemoryStore,
+  migrateSession,
+  SessionConflictError,
+  type DataOf,
+  type Session,
+  type TurnResult,
+} from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+type Data = DataOf<typeof f>;
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      on: [{ message: [] }],
+      steps: [{ id: "nome", collect: ["nome"] }],
+    }),
+  ],
+});
+
+// Any of the seven stores works here; all have the same two methods.
+// PostgresStore, PrismaStore, RedisStore, MongoStore, SQLiteStore, OpenSearchStore take a client.
+const store = new MemoryStore<Data>();
+
+// ─── The host's turn: load → turn → save ────────────────────────────────────
+// The framework never saves. You save when the turn changed something, with
+// the version you loaded, so two concurrent turns cannot both win.
+
+async function runTurn(sessionId: string, message: string): Promise<TurnResult<Data>> {
+  const session = (await store.load(sessionId)) ?? undefined;
+  const result = await agent.turn({ sessionId, session, message });
+  if (!result.changed) return result;
+  try {
+    // 0 means "insert if absent". Later saves pass the loaded version.
+    await store.save(result.session, session?.version ?? 0);
+  } catch (error) {
+    if (error instanceof SessionConflictError) {
+      // Someone saved first. Nothing was sent yet, so just play the same input again.
+      return runTurn(sessionId, message);
+    }
+    throw error;
+  }
+  // Only now: send result.messages, enqueue result.schedule.
+  return result;
+}
+
+const r = await runTurn("demo", "oi, sou a Bia");
+console.log(r.messages[0]?.text, r.session.data); // ... { nome: 'Bia' }
+
+// ─── Moving a 3.x session ───────────────────────────────────────────────────
+// A 3.x row holds `currentFlow`, `currentStep`, `signals.triggers`. Migrate it
+// once, where you deserialize, then save it into the new table. The migrated
+// session has version 0, so the usual save is the insert.
+
+const legacyRow: unknown = {
+  id: "conv-42",
+  version: 12,
+  data: { nome: "Rui" },
+  currentFlow: { id: "boas-vindas", title: "Boas-vindas" },
+  currentStep: { id: "nome" },
+  signals: { triggers: { pediu_humano: { firedAt: "2026-09-01T13:05:12.000Z" } } },
+};
+
+const migrated: Session<Data> = migrateSession<Data>(legacyRow, {
+  sessionId: "conv-42",
+  // Signal keys and old flow ids → v4 flow ids. Identity when you kept the ids.
+  flowIdOf: (key) => key,
+});
+console.log(migrated.runs[0]?.stepId, Object.keys(migrated.claims)); // 'nome' [ 'pediu_humano:conv-42:', 'boas-vindas:conv-42:' ]
+await store.save(migrated, migrated.version);
+
+// A row that is neither v4 nor 3.x is an error, never a fresh conversation.
+try {
+  migrateSession("garbage", { sessionId: "conv-43", flowIdOf: (key) => key });
+} catch (error) {
+  if (error instanceof InvalidSessionError) console.log(error.message);
+}

package/examples/09-flows-from-json.ts

@@ -0,0 +1,107 @@
+/**
+ * Flows as JSON: store them in a database, let an editor draw them, let a
+ * model write them. The JSON form is the same object the code form is.
+ *
+ * Teaches: `FlowSpec`, `f.fromSpec`, `toSpec`, `validateFlow`,
+ * `flowSpecSchema` as the response schema of a generation call.
+ * Read next: docs/reference/flow-spec.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/09-flows-from-json.ts
+ */
+
+import {
+  falai,
+  FlowConfigurationError,
+  flowSpecSchema,
+  GeminiProvider,
+  toSpec,
+  validateFlow,
+  type FlowSpec,
+} from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+  empresa: { type: "string", ask: "Pergunte a empresa." },
+});
+
+// Everything a stored flow may name is registered once, by name.
+const registries = {
+  fields: f.fields,
+  actions: {
+    notify: f.action({
+      parameters: { recipient: { type: "string" }, message: { type: "string" } },
+      run: (params) => {
+        console.log(`[notify] ${params.recipient}: ${params.message}`);
+        return { ok: true };
+      },
+    }),
+    add_tags: f.action({
+      parameters: { tags: { type: "array", items: { type: "string" } } },
+      run: (params) => {
+        console.log("[add_tags]", params.tags);
+        return { ok: true };
+      },
+    }),
+  },
+};
+
+// ─── A rule typed in a chat, stored as a row ─────────────────────────────────
+// Flat steps with a `kind`; predicates in JSON; no functions anywhere.
+
+const concorrente: FlowSpec = {
+  id: "concorrente",
+  name: "Lead falou de concorrente",
+  on: [{ mention: ["o lead cita ou compara com um concorrente"], extract: { trecho: { type: "string" } }, repeat: "once" }],
+  steps: [
+    { id: "tag", kind: "do", do: "add_tags", with: { tags: ["concorrente"] } },
+    { id: "avisa", kind: "do", do: "notify", with: { recipient: "owner", message: '{{data.nome}} falou de concorrente: "{{input.trecho}}"' } },
+  ],
+};
+
+// Validate on save: the error names the unknown field, action, event, condition or step.
+const { warnings } = validateFlow(concorrente, registries);
+console.log("avisos:", warnings);
+
+try {
+  validateFlow({ ...concorrente, steps: [{ id: "x", kind: "do", do: "send_email", with: {} }] }, registries);
+} catch (error) {
+  if (error instanceof FlowConfigurationError) console.log(error.message);
+}
+
+// ─── The same flow written in TypeScript is the same object ─────────────────
+
+const triagem = f.flow({
+  id: "triagem",
+  name: "Triagem",
+  on: [{ message: ["quer um orçamento"] }],
+  steps: [
+    { id: "quem", prompt: "Descubra quem é.", collect: ["nome", "empresa"] },
+    { id: "avisa", do: "notify", with: { recipient: "owner", message: "Lead: {{data.nome}} ({{data.empresa}})" } },
+  ],
+});
+console.log(JSON.stringify(toSpec(triagem).steps[0])); // {"id":"quem","kind":"collect","prompt":"Descubra quem é.","collect":["nome","empresa"]}
+
+// ─── Letting a model write one ───────────────────────────────────────────────
+// `flowSpecSchema` is closed and lists this agent's fields, actions, events and
+// conditions, so the model can only write a flow that validates.
+
+const provider = new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" });
+const generated = await provider.generateMessage<undefined, FlowSpec>({
+  prompt: "Write a flow, as JSON, for this request: 'quando o lead pedir para falar com uma pessoa, avise o dono e marque a tag humano'. Write the texts in Brazilian Portuguese.",
+  history: [],
+  context: undefined,
+  parameters: { jsonSchema: flowSpecSchema(registries), schemaName: "flow" },
+});
+// The schema shapes the answer; `validateFlow` is what proves it. Never trust the JSON before that.
+const spec = generated.structured;
+if (!spec) throw new Error("The model returned no JSON.");
+validateFlow(spec, registries);
+
+// Rows load into the agent like any other flow.
+const agent = f.agent({
+  name: "Ana",
+  provider,
+  ...registries,
+  flows: [triagem, f.fromSpec(concorrente), f.fromSpec(spec)],
+});
+console.log(agent.options.flows?.map((flow) => flow.id)); // [ 'triagem', 'concorrente', '<generated id>' ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "3.4.4",
+  "version": "4.0.0-alpha.1",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -46,17 +46,20 @@
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "typecheck:examples": "tsc --noEmit --project examples/tsconfig.json",
+    "check:docs": "bun run scripts/check-docs-snippets.ts",
+    "eval:understand": "bun run scripts/eval/understand.ts",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "clean": "rm -rf dist",
     "prebuild": "bun run clean",
-    "prepublishOnly": "bun run lint && bun run typecheck && bun run typecheck:examples && bun run build && bun run test",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run typecheck:examples && bun run check:docs && bun run build && bun run test",
     "release:patch": "bun pm version patch && bun publish",
     "release:minor": "bun pm version minor && bun publish",
     "release:major": "bun pm version major && bun publish",
     "release:alpha": "bun publish --tag alpha",
     "release": "bun publish",
-    "test": "bun test tests/*.test.ts"
+    "test": "bun test tests/*.test.ts tests/scenarios/*.test.ts",
+    "eval:live": "bun run scripts/eval/live.ts"
   },
   "keywords": [
     "ai",
@@ -73,8 +76,8 @@
     "framework",
     "flows",
     "schema",
-    "directives",
-    "signals"
+    "state-machine",
+    "automation"
   ],
   "author": "Gustavo Salomé <gusnips>",
   "license": "MIT",
@@ -92,7 +95,7 @@
     "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
-    "@providerkit/core": "^0.10.0",
+    "@providerkit/core": "^0.11.0",
     "loglevel": "^1.9.2"
   },
   "peerDependencies": {