Report Generator Agent

An AI-powered report generation system that processes documents, creates structured report plans, and generates professional reports using multiple LLM providers with real-time synchronization.

What This Skill Does

This project implements a sophisticated report generation workflow that:

Technical Stack

Architecture Overview

Core Workflow

1. **Document Upload**: User uploads documents and provides context

2. **Plan Generation**: AI agent generates structured report plan with chapters

3. **User Approval**: Workflow suspends for user review/modification

4. **Parallel Generation**: Multiple AI providers generate chapter content simultaneously

5. **Report Assembly**: Final report compiled and PDF generated

Key Architectural Patterns

**Real-time Data Layer**: Convex provides real-time synchronization

**AI Agent Orchestration**: Mastra framework manages complex workflows

**RAG Implementation**: Upstash Vector for semantic search

**State Architecture**:

Development Setup

Prerequisites

Installation

```bash

Install dependencies (ALWAYS use pnpm)

pnpm install

Copy and configure environment variables

cp env.template .env.local

Edit .env.local with your API keys

```

Required Environment Variables

Create `.env.local` with:

```bash

AI Provider APIs

GEMINI_API_KEY=your_gemini_key

OPENAI_API_KEY=your_openai_key

Search APIs

EXA_API_KEY=your_exa_key

TAVILY_API_KEY=your_tavily_key

Convex Backend

CONVEX_DEPLOYMENT=your_deployment

NEXT_PUBLIC_CONVEX_URL=your_convex_url

Vector Database

UPSTASH_VECTOR_REST_URL=your_upstash_url

UPSTASH_VECTOR_REST_TOKEN=your_upstash_token

```

Running the Application

```bash

Terminal 1: Start Convex backend

pnpm convex dev

Terminal 2: Start Next.js development server

pnpm dev

```

Access the application at `http://localhost:3000`

Project Structure

```

/app # Next.js App Router pages and API routes

/api # API route handlers

/(dashboard) # Dashboard pages

/components # Shared UI components

/ui # shadcn/ui base components

/convex # Convex backend schema and functions

/lib # Utility libraries

/actions # Server actions

/hooks # React hooks

/stores # Zustand stores

/task # Mastra agent workflow definitions

/agent # AI agent configurations

/workflow # Workflow orchestration

```

Key Implementation Details

Database Schema (Convex)

**reports**: Report metadata and generated content

```typescript

{

title: string

description: string

content: string

status: "draft" | "generating" | "completed"

workflowId?: string

}

```

**workflows**: Mastra workflow execution state

```typescript

{

workflowId: string

status: "pending" | "running" | "suspended" | "completed"

stepResults: Record<string, any>

}

```

**attachments**: Uploaded file metadata

```typescript

{

reportId: string

storageId: string

filename: string

contentType: string

}

```

AI Agent System

**Mastra Agents** (`/task/agent`):

**Workflow Orchestration** (`/task/workflow`):

Server Actions Pattern

All server actions follow this convention:

```typescript

// Server action

export async function createReport(data: CreateReportInput): ServerActionReturnType<Report> {

try {

const report = await convex.mutation(api.reports.create, data);

return { data: report, error: null };

} catch (error) {

return { data: null, error: getErrorMessage(error) };

}

}

// Client usage

const { data, error } = await handleServerAction(createReport(input));

```

Component Conventions

PDF Generation

LaTeX-based PDF generation using MiKTeX:

Development Commands

```bash

Install dependencies

pnpm install

Development servers

pnpm dev # Next.js development server

pnpm convex dev # Convex backend

Build and production

pnpm build # Build for production

pnpm start # Start production server

Code quality

pnpm lint # Run ESLint

pnpm type-check # TypeScript type checking

```

MCP Server Integration

The project supports Model Context Protocol (MCP) servers:

Important Notes

1. **Package Manager**: ALWAYS use `pnpm` (never npm or yarn)

2. **Real-time Updates**: Convex provides automatic UI updates when data changes

3. **Workflow Suspension**: User approval gates are implemented via Mastra workflow suspension

4. **Parallel Execution**: Chapter generation runs concurrently for performance

5. **Cache Management**: TanStack Query cache keys defined in `queryCacheKeys`

6. **Error Handling**: Consistent pattern across server actions with typed returns

Common Tasks

Adding a New Report Type

1. Update Convex schema in `/convex/schema.ts`

2. Create new agent configuration in `/task/agent`

3. Define workflow steps in `/task/workflow`

4. Add UI components in `/app/(dashboard)`

Integrating New LLM Provider

1. Add API key to environment variables

2. Configure provider in Mastra agent setup

3. Update workflow to include new provider option

4. Test with existing report generation flow

Modifying Report Structure

1. Update report plan generation agent

2. Adjust chapter generation workflow

3. Update PDF template if needed

4. Test full workflow end-to-end

Troubleshooting

**PDF Generation Fails**: Ensure MiKTeX is installed and accessible in PATH

**Convex Connection Issues**: Verify `CONVEX_DEPLOYMENT` and `NEXT_PUBLIC_CONVEX_URL` are correct

**AI Generation Errors**: Check API keys are valid and have sufficient quota

**Real-time Updates Not Working**: Ensure Convex dev server is running alongside Next.js dev server