Skip to content

The Open Standard for Generative UI

Update Fino tutorial (#54)

Rabi Shanker Guha87fad9c3391e
diff --git a/docs/docs/tutorials/Fino/001-types.md b/docs/docs/tutorials/Fino/001-types.md
new file mode 100644
index 000000000..679021740
--- /dev/null
+++ b/docs/docs/tutorials/Fino/001-types.md
@@ -0,0 +1,55 @@
+# Interface definitions
+
+Before we begin writing any code, we'd need to setup the interface for our backend to UI communication.
+communication.
+In a traditional setup this would be defined via an OpenAPI spec or GraphQL schema but
+since in an conversational setup there'd only be a single request and response, we'd need to define the
+request and response types in a way that's easy to use in the frontend and can be be easily converted
+to JSON Schema so that we can pass it to an LLM.
+
+```typescript title="src/types/reponseTemplates/templates.ts"
+export const BreakdownExpensesSummarySchema = z.object({
+ expenses: z.array(
+ z.object({
+ category: z.string(),
+ amount: z.number(),
+ })
+ ),
+ total_spent: z.number(),
+});
+
+export type BreakdownExpensesSummaryProps = z.infer<typeof BreakdownExpensesSummarySchema>;
+
+export const templates = [
+ {
+ name: "breakdown_expenses",
+ description: "Renders a summary of the user's financial situation.",
+ parameters: BreakdownExpensesSummarySchema,
+ },
+];
+
+export const TemplatesJsonSchema = {
+ type: "object",
+ properties: {
+ response: {
+ type: "array",
+ items: {
+ oneOf: [
+ TextResponseSchema, // A simple text response for when no template is needed
+ ...templates.map((template) => ({
+ type: "object",
+ description: template.description,
+ properties: {
+ type: { const: "template" },
+ name: { const: template.name },
+ templateProps: zodToJsonSchema(template.parameters),
+ },
+ required: ["name", "templateProps", "type"],
+ additionalProperties: false,
+ })),
+ ],
+ },
+ },
+ },
+} as const;
+```
diff --git a/docs/docs/tutorials/Fino/002-database.md b/docs/docs/tutorials/Fino/002-database.md
new file mode 100644
index 000000000..7d3c533fe
--- /dev/null
+++ b/docs/docs/tutorials/Fino/002-database.md
@@ -0,0 +1,111 @@
+# Database Setup
+
+In the real world, we'd want to use a database to store the user's personal finance history.
+
+For this tutorial, we'll use a local SQLite database.
+
+## Creating the database
+
+```typescript title="src/lib/db/index.ts"
+import { PrismaClient } from "@prisma/client";
+import { initializeDb } from "./init";
+
+declare global {
+ // eslint-disable-next-line no-var
+ var prisma: PrismaClient | undefined;
+}
+
+const prisma = global.prisma || new PrismaClient();
+
+if (process.env.NODE_ENV !== "production") {
+ global.prisma = prisma;
+}
+
+// Initialize the database when this module is imported
+(async () => {
+ try {
+ await initializeDb(prisma);
+ } catch (error) {
+ console.error("Failed to initialize database:", error);
+ }
+})();
+
+// Handle cleanup when the Node process is terminated
+process.on("beforeExit", async () => {
+ await prisma?.$disconnect();
+});
+
+export default prisma;
+```
+
+## Filling it up with mock data
+Since we don't have a real database, we'll need to fill it up with mock data.
+
+```typescript title="src/lib/db/init.ts"
+import { PrismaClient } from "@prisma/client";
+import { randomInt } from "crypto";
+
+export async function initializeDb(prisma: PrismaClient) {
+ // Check if there are any existing transactions
+ const existingTransaction = await prisma.transaction.findFirst();
+
+ if (!existingTransaction) {
+ const debitCategories = [
+ "Food",
+ "Transportation",
+ "Entertainment",
+ "Utilities",
+ "Healthcare",
+ "Shopping",
+ "Education",
+ ];
+
+ const creditCategories = [
+ "Salary",
+ "Investment",
+ "Refund",
+ "Gift",
+ "Bonus",
+ ];
+
+ let balance = 0;
+ // Generate transactions with approximately 5:1 ratio of debits to credits
+ const transactions = Array.from({ length: 100 }, (_, i) => {
+ const transactionType = i % 6 === 0 ? "credit" : "debit";
+ const amount = Number((Math.random() * 490 + 10).toFixed(2)); // Random amount between 10 and 500, rounded to 2 decimal places
+ const finalAmount = transactionType === "credit" ? amount : -amount;
+ balance += finalAmount;
+
+ const category =
+ transactionType === "credit"
+ ? creditCategories[
+ Math.floor(Math.random() * creditCategories.length)
+ ]
+ : debitCategories[Math.floor(Math.random() * debitCategories.length)];
+
+ const date = new Date();
+ date.setDate(date.getDate() - randomInt(1, 365)); // Random date within the last year
+
+ return {
+ date,
+ amount: finalAmount,
+ balance,
+ category,
+ description: "Mock transaction",
+ transaction_type: transactionType,
+ };
+ });
+
+ // Create all transactions in a single transaction
+ await prisma.transaction.createMany({
+ data: transactions,
+ });
+ }
+}
+```
+
+## Check that the database is setup correctly
+
+```sh
+npx prisma studio
+```
diff --git a/docs/docs/tutorials/Fino/003-backend.md b/docs/docs/tutorials/Fino/003-backend.md
index 781894a4f..52469453d 100644
--- a/docs/docs/tutorials/Fino/003-backend.md
+++ b/docs/docs/tutorials/Fino/003-backend.md
@@ -1 +1,107 @@
-# Backend
+# Chat Endpoint
+
+## System Prompt
+Add a system prompt to the assistant that will help it answer questions about the user's personal finance history.
+
+```typescript title="src/api/chat/route.ts"
+const SYSTEM_MESSAGE: ChatCompletionMessageParam = {
+ role: "system",
+ content:
+ "You are Fino, an AI financial advisor. " +
+ "You help users understand their finances, analyze transactions, and provide personalized financial advice. " +
+ "Be concise, professional, and focus on providing actionable insights. " +
+ "IMPORTANT: Your response must ALWAYS follow this structure:\n" +
+ "1. Start with an explanatory text string in the response array\n" +
+ "2. Follow with the appropriate template object\n" +
+ "3. End with additional insights or recommendations as text string\n" +
+ "You have access to tools to analyze transaction data. " +
+ "Use these tools when appropriate to provide data-driven insights. " +
+ "Always respond with a single JSON object containing a 'response' array which contains text or template object " +
+ "Example response structure:\n" +
+ '{"response": [\n' +
+ ' {"name": "breakdown_expenses", "templateProps": {...},\n' +
+ ' "Based on this breakdown, your highest spending is in Food category. Consider setting a budget to reduce these expenses."\n' +
+ "]}\n"
+};
+```
+
+## Add data execution tool
+Add a SQL execution tool to the assistant that will allow it to analyze the user's personal finance history.
+
+```typescript title="src/api/chat/route.ts"
+import { z } from "zod";
+
+export const SQLArgsSchema = z.object({
+ query: z
+ .string()
+ .describe(
+ "SQL query to execute on the Transaction table. Use the Transaction table. " +
+ "quote the table name. "
+ ),
+ description: z
+ .string()
+ .describe(
+ "Human readable description of the intent of this tool call to be shown to the user. Do not include any sensitive information or PII. Construct the sentence in present participle tense."
+ ),
+});
+
+type SQLArgs = z.infer<typeof SQLArgsSchema>;
+
+export async function execute_sql(args: SQLArgs): Promise<string> {
+ const result = await prisma.$queryRawUnsafe(args.query);
+ return JSON.stringify(result);
+}
+```
+
+## Connecting the LLM
+
+We pass the tools along with the templates to OpenAI.
+Tools are functions that the LLM can call to get data whereas templates
+represent the possible responses that the LLM can return along with their parameters.
+
+Templates are defined in the `templates.ts` file and are passed to OpenAI as a JSON Schema
+by using the `response_format` option. This way the LLM can choose the appropriate template
+to use based on the user's query.
+
+```typescript title="src/api/chat/route.ts"
+import { TemplatesJsonSchema } from "@/types/reponseTemplates/templates";
+
+const completion = openai.beta.chat.completions.runTools({
+ model: "gpt-4o",
+ messages: [SYSTEM_MESSAGE, ...historicalMessages, userMessage],
+ temperature: 0.5,
+ max_tokens: 1000,
+ stream: true,
+ tools: [
+ {
+ type: "function",
+ function: {
+ function: execute_sql,
+ description:
+ "Execute SQL lite queries on the Transaction table. \n" +
+ `id Int @id @default(autoincrement())
+ date DateTime
+ amount Float
+ balance Float
+ category String
+ transaction_type "credit" | "debit"`
+ .split("\n")
+ .map((line) => line.trim())
+ .join("\n"),
+ parameters: zodToJsonSchema(SQLArgsSchema) as object,
+ parse: (params: string) => {
+ return SQLArgsSchema.parse(JSON.parse(params));
+ },
+ strict: true,
+ },
+ },
+ ],
+ response_format: {
+ type: "json_schema",
+ json_schema: {
+ name: "json_schema",
+ schema: TemplatesJsonSchema,
+ },
+ },
+ });
+```
diff --git a/docs/docs/tutorials/Fino/004-frontend.md b/docs/docs/tutorials/Fino/004-frontend.md
index 41d391914..ce7064b21 100644
--- a/docs/docs/tutorials/Fino/004-frontend.md
+++ b/docs/docs/tutorials/Fino/004-frontend.md
@@ -1,7 +1,44 @@
-# Frontend
+# Generative UI
## Creating a response template for breakdown_expense
+Now that we have a response template, we need to create a component that will render it.
+
+```tsx title="src/app/reponseTemplates/templates.tsx"
+"use client";
+import { Card, CardHeader } from "@crayonai/react-ui";
+import { PieChart } from "@crayonai/react-ui/Charts/PieChart";
+import { BreakdownExpensesSummaryProps } from "@/types/responseTemplates/templates";
+
+export const BreakdownExpenses: React.FC<BreakdownExpensesSummaryProps> = ({
+ expenses,
+ total_spent: totalSpent,
+}) => {
+ const chartData = expenses.map((expense) => ({
+ category: expense.category,
+ amount: expense.amount,
+ }));
+
+ return (
+ <Card className="items-center">
+ <CardHeader title={`Breakdown of expenses, Total Spent: ${totalSpent}`} />
+ <div className="w-[400px]">
+ <PieChart data={chartData} categoryKey="category" dataKey="amount" />
+ </div>
+ </Card>
+ );
+};
+```
## Passing response templates to CrayonChat
+Lastly, we need to pass the response templates to the CrayonChat component so that it can render them.
+
+```tsx title="src/app/page.tsx"
+import { BreakdownExpenses } from "@/app/reponseTemplates/templates";
-## Handling input from user
+export default function Home() {
+ return <CrayonChat processMessage={processMessage} templates={[{
+ name: "breakdown_expenses",
+ Component: BreakdownExpenses,
+ }]} />;
+}
+```
diff --git a/docs/docs/tutorials/Fino/005-deployment.md b/docs/docs/tutorials/Fino/005-deployment.md
deleted file mode 100644
index d36c65e59..000000000
--- a/docs/docs/tutorials/Fino/005-deployment.md
+++ /dev/null
@@ -1 +0,0 @@
-# Deployment
diff --git a/docs/docs/tutorials/Fino/index.md b/docs/docs/tutorials/Fino/index.md
index a25d50cb1..55b43b027 100644
--- a/docs/docs/tutorials/Fino/index.md
+++ b/docs/docs/tutorials/Fino/index.md
@@ -15,4 +15,10 @@ For this tutorial, we'll build a personal finance assistant that helps the user
## Setup
-Follow the [Getting Started](/docs/quickstart/python-fastapi) guide to set up your project.
+Follow the [Getting Started](/docs/quickstart/nextjs) guide to set up your project.
+
+## Next Steps
+- Add a system prompt to the assistant that will help it answer questions about the user's personal finance history.
+- Add a SQL execution tool to the assistant that will allow it to analyze the user's personal finance history.
+- Add a template to the assistant that will allow it to render the user's personal finance history in a structured format.
+- Render the template in the frontend based on the parameters returned by the LLM.
diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml
index b6cafdcaa..b407015c8 100644
--- a/docs/pnpm-lock.yaml
+++ b/docs/pnpm-lock.yaml
@@ -2059,6 +2059,11 @@ packages:
peerDependencies:
webpack: ^5.0.0
+ '@storybook/[email protected]':
+ resolution: {integrity: sha512-yjzDgoErmzzkesA7goiAi4zi4dMSZAS9KVoRwjIyW/w/uzldLJmp+EIg7pHRtZPDsNYGwEiHfsHIz/hwYCgaHA==}
+ peerDependencies:
+ storybook: ^8.2.0 || ^8.3.0-0 || ^8.4.0-0 || ^8.5.0-0 || ^8.6.0-0
+
'@storybook/[email protected]':
resolution: {integrity: sha512-rCOpXZo2XbdKVnZiv8oC9FId/gLkStpKGGL7hhdg/RyjcyUyTfhsvaf7LXKZH2A0n/UpwFxhF3idRfhgc1XiSg==}
peerDependencies:
@@ -7428,6 +7433,7 @@ snapshots:
'@storybook/addon-styling-webpack': 1.0.1([email protected])([email protected]([email protected]))
+ '@storybook/core-events': 8.5.8([email protected])
'@storybook/manager-api': 8.5.3([email protected])
'@storybook/theming': 8.5.3([email protected])
clsx: 2.1.1
@@ -9225,6 +9231,10 @@ snapshots:
transitivePeerDependencies:
- storybook
+ dependencies:
+ storybook: 8.5.2
+
'@storybook/[email protected]':
dependencies:
'@storybook/csf': 0.1.12