Merge branch 'main' into feat/ai-assistant

Author: elie222

.cursor/rules/api-routes.mdc

@@ -6,6 +6,7 @@ alwaysApply: false
 # API Routes
 
 ## Standard Format
+
 Use this format for API routes:
 
 ```ts
@@ -15,9 +16,9 @@ import { auth } from "@/app/api/auth/[...nextauth]/auth";
 import prisma from "@/utils/prisma";
 import { withError } from "@/utils/middleware";
 
-const ApiNameBody = z.object({ id: z.string(), message: z.string() });
-export type ApiNameBody = z.infer<typeof ApiNameBody>;
-export type updateApiNameResponse = Awaited<ReturnType<typeof updateApiName>>;
+const apiNameBody = z.object({ id: z.string(), message: z.string() });
+export type ApiNameBody = z.infer<typeof apiNameBody>;
+export type UpdateApiNameResponse = Awaited<ReturnType<typeof updateApiName>>;
 
 async function updateApiName(body: ApiNameBody, options: { email: string }) {
   const { email } = options;
@@ -26,28 +27,49 @@ async function updateApiName(body: ApiNameBody, options: { email: string }) {
       id: body.id,
       email,
     },
-    data: body
-  })
+    data: body,
+  });
 
   return { result };
-};
+}
 
+// For routes without params
 export const POST = withError(async (request: Request) => {
   const session = await auth();
-  if (!session?.user.email) return NextResponse.json({ error: "Not authenticated" });
+  if (!session?.user.email)
+    return NextResponse.json({ error: "Not authenticated" });
 
   const json = await request.json();
-  const body = ApiNameBody.parse(json);
+  const body = apiNameBody.parse(json);
 
   const result = await updateApiName(body, { email: session.user.email });
 
   return NextResponse.json(result);
 });
+
+// For routes with params (note the params promise which is how Next.js 15+ works)
+export const GET = withError(
+  async (
+    request: Request,
+    { params }: { params: Promise<{ slug: string }> }
+  ) => {
+    const session = await auth();
+    if (!session?.user.email)
+      return NextResponse.json({ error: "Not authenticated" });
+
+    const { slug } = await params;
+    // Use the slug parameter...
+
+    return NextResponse.json({ result });
+  }
+);
 ```
 
 ## Implementation Guidelines
+
 - Use Zod for request body validation
 - Create separate functions for business logic
 - Wrap route handlers with `withError` middleware
 - Always validate authentication with `auth()`
-- Export typed responses for client usage 
+- Export typed responses for client usage
+- For routes with dynamic parameters, use the new Next.js 15+ params format with async params

.cursor/rules/cursor-rules.mdc

@@ -37,7 +37,7 @@ How to add new cursor rules to the project
 
 5. Cursor rules have the following structure:
 
-```
+````
 ---
 description: Short description of the rule's purpose
 globs: optional/path/pattern/**/* 
@@ -62,4 +62,5 @@ function goodExample() {
 function badExample() {
   // Implementation not following guidelines
 }
-```
+```
+````

.cursor/rules/data-fetching.mdc

@@ -1,5 +1,5 @@
 ---
-description: 
+description: Fetching data from the API using SWR
 globs: 
 alwaysApply: false
 ---

.cursor/rules/features/cleaner.mdc

@@ -0,0 +1,30 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+## Inbox Cleaner
+
+This file explains the Inbox Cleaner feature and how it's implemented.
+
+The inbox cleaner helps users do a deep clean of their inbox.
+It helps them get from 10,000 items in their inbox to only a few.
+It works by archiving/marking read low priority emails.
+It uses a combination of static and AI rules to do the clean up.
+It uses both Postgres (Prisma) and Redis.
+We store short term memory in Redis that expires after a few hours. This is data like email subject so we can quickly show it to the user, but this isn't data we want stored long term to enhance privacy for the user while balancing this with a faster experience.
+Once the cleaning process has started we show the emails streamed in with the action taken on the email (archive/keep).
+
+The main files and directories for this are:
+
+- apps/web/utils/actions/clean.ts
+- apps/web/app/api/clean/
+- apps/web/app/(app)/clean/page.tsx
+- apps/web/app/(app)/clean/
+- apps/web/prisma/schema.prisma
+- apps/web/utils/redis/clean.ts
+
+The database models to look at are:
+
+- CleanupThread
+- CleanupJob

.cursor/rules/features/knowledge.mdc

@@ -0,0 +1,92 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Knowledge Base
+
+This file explains the Knowledge Base feature and how it's implemented.
+
+The knowledge base helps users store and manage information that can be used to help draft responses to emails. It acts as a personal database of information that can be referenced when composing replies.
+
+## Overview
+
+Users can create, edit, and delete knowledge base entries. Each entry consists of:
+
+- A title for quick reference
+- Content that contains the actual information
+- Metadata like creation and update timestamps
+
+## Database Schema
+
+The `Knowledge` model in Prisma:
+
+```prisma
+model Knowledge {
+  id        String   @id @default(cuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  title     String
+  content   String
+
+  userId String
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+```
+
+Each knowledge entry belongs to a specific user and is automatically deleted if the user is deleted (cascade).
+
+## Main Files and Directories
+
+The knowledge base functionality is implemented in:
+
+- `apps/web/app/(app)/automation/knowledge/KnowledgeBase.tsx` - Main UI component
+- `apps/web/app/(app)/automation/knowledge/KnowledgeForm.tsx` - Form for creating/editing entries
+- `apps/web/utils/actions/knowledge.ts` - Server actions for CRUD operations
+- `apps/web/utils/actions/knowledge.validation.ts` - Zod validation schemas
+- `apps/web/app/api/knowledge/route.ts` - API route for fetching entries
+
+### AI Integration Files
+
+- `apps/web/utils/ai/knowledge/extract.ts` - Extract relevant knowledge from knowledge base entries
+- `apps/web/utils/ai/knowledge/extract-from-email-history.ts` - Extract context from previous emails
+- `apps/web/utils/ai/reply/draft-with-knowledge.ts` - Generate email drafts using extracted knowledge
+- `apps/web/utils/reply-tracker/generate-reply.ts` - Coordinates the extraction and drafting process
+- `apps/web/utils/llms/model-selector.ts` - Economy LLM selection for high-volume tasks
+
+## Features
+
+- **Create**: Users can add new knowledge entries with a title and content
+- **Read**: Entries are displayed in a table with title and last updated date
+- **Update**: Users can edit existing entries
+- **Delete**: Entries can be deleted with a confirmation dialog
+
+## Usage in Email Responses
+
+The knowledge base entries are used to help draft responses to emails. When composing a reply, the system can reference these entries to include relevant information, ensuring consistent and accurate responses.
+
+When drafting responses, we use two LLMs:
+
+1. A cheaper LLM that can process a lot of data (e.g. Google Gemini 2 Flash)
+2. A more expensive LLM to draft the response (e.g. Anthropic Sonnet 3.7)
+
+The cheaper LLM is an agent that extracts the key information needed for the drafter LLM.
+For example, the knowledge base may include 100 pages of content, and the LLM extracts half a page of knowledge to pass to the more expensive drafter LLM.
+
+## Dual LLM Architecture
+
+The dual LLM approach is implemented as follows:
+
+1. **Knowledge Extraction (Economy LLM)**:
+
+   - Uses a more cost-efficient model like Gemini Flash for processing large volumes of knowledge base content
+   - Analyzes all knowledge entries and extracts only relevant information based on the email content
+   - Configured via environment variables (`ECONOMY_LLM_PROVIDER` and `ECONOMY_LLM_MODEL`)
+   - If no specific economy model is configured, defaults to Gemini Flash when Google API key is available
+
+2. **Email Draft Generation (Core LLM)**:
+   - Uses the default model (e.g., Anthropic Claude 3.7 Sonnet) for high-quality content generation
+   - Receives the extracted relevant knowledge from the economy LLM
+   - Generates the final email draft based on the provided context
+
+This architecture optimizes for both cost efficiency (using cheaper models for high-volume tasks) and quality (using premium models for user-facing content).

.cursor/rules/features/reply-tracker.mdc

@@ -0,0 +1,25 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Reply Tracker
+
+Reply Tracker (also known as Reply Zero) lets the user which emails need a reply for them and those they're awaiting a reply on.
+It updates the labels for the thread automatically in Gmail.
+
+The database models and fields that are used for this feature:
+
+- ThreadTracker
+- User.outboundReplyTracking
+- ActionType.TRACK_THREAD
+
+The system uses rules. The AI can choose which rule to use each time an email comes in. Rules are for incoming emails only. Not ongoing.
+When enabling the reply tracker, we create a rule for the user that has the following actions associated with it:
+- LABEL: "To Reply"
+- TRACK_THREAD
+- DRAFT_EMAIL (optional)
+
+We'll draft a reply for the user automatically if DRAFT_EMAIL is set. The draft will be generated using the email history for this sender as well as the Knowledge base. See `.cursor/rules/features/knowledge.mdc` for more on the Knowledge Base feature.
+
+Enabling `User.outboundReplyTracking` means that when a user sends an email, we'll run an LLM over the email and check if it needs a reply. If it does we'll mark it as Awaiting Reply.

.cursor/rules/form-handling.mdc

@@ -9,23 +9,33 @@ alwaysApply: false
 - The same validation should be done in the server action too
 
 ## Form Example
+
 ```tsx
+import { zodResolver } from "@hookform/resolvers/zod";
 import { Input } from "@/components/Input";
 import { Button } from "@/components/ui/button";
+import { toastSuccess, toastError } from "@/components/Toast";
+import { createExampleAction } from "@/utils/actions/example";
+import { type CreateExampleBody } from "@/utils/actions/example.validation";
 
-export const ProcessHistory = () => {
+export const ExampleForm = () => {
   const {
     register,
     handleSubmit,
     formState: { errors, isSubmitting },
-  } = useForm<ProcessHistoryOptions>({
+  } = useForm<CreateExampleBody>({
     resolver: zodResolver(processHistorySchema),
   });
 
-  const onSubmit: SubmitHandler<ProcessHistoryOptions> = useCallback(
+  const onSubmit: SubmitHandler<CreateExampleBody> = useCallback(
     async (data) => {
-      const result = await processHistoryAction(data.email);
-      handleActionResult(result, `Processed history for ${data.email}`);
+      const result = await createExampleAction(data.email);
+      
+      if (isActionError(result)) {
+        toastError({ title: "Error", description: result.error });
+      } else {
+        toastSuccess({ description: "Created example!" });
+      }
     },
     []
   );
@@ -40,8 +50,17 @@ export const ProcessHistory = () => {
         error={errors.email}
       />
       <Button type="submit" loading={isSubmitting}>
-        Process History
+        Save
       </Button>
     </form>
   );
-}; 
+};
+```
+
+## Validation Guidelines
+
+- Define validation schemas using Zod
+- Apply the same validation in both client and server
+- Use descriptive error messages
+- Validate form inputs before submission
+- Show validation errors inline next to form fields