AI-powered report generation system with document processing, workflow orchestration, and multi-provider LLM integration
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.
This project implements a sophisticated report generation workflow that:
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
**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**:
```bash
pnpm install
cp env.template .env.local
```
Create `.env.local` with:
```bash
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
EXA_API_KEY=your_exa_key
TAVILY_API_KEY=your_tavily_key
CONVEX_DEPLOYMENT=your_deployment
NEXT_PUBLIC_CONVEX_URL=your_convex_url
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```
```bash
pnpm convex dev
pnpm dev
```
Access the application at `http://localhost:3000`
```
/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
```
**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
}
```
**Mastra Agents** (`/task/agent`):
**Workflow Orchestration** (`/task/workflow`):
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));
```
LaTeX-based PDF generation using MiKTeX:
```bash
pnpm install
pnpm dev # Next.js development server
pnpm convex dev # Convex backend
pnpm build # Build for production
pnpm start # Start production server
pnpm lint # Run ESLint
pnpm type-check # TypeScript type checking
```
The project supports Model Context Protocol (MCP) servers:
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
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)`
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
1. Update report plan generation agent
2. Adjust chapter generation workflow
3. Update PDF template if needed
4. Test full workflow end-to-end
**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
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/report-generator-agent/raw