I Built an AI-Powered TTRPG Adventure Generator (Because Generic Hallucinations Are Boring)

// src/app/api/generate/route.ts
const adventureSchema = {
  type: 'object',
  required: ['adventure_title', 'summary', 'plot_hooks', 'npcs', 'locations'],
  properties: {
    adventure_title: {type: 'string'},
    summary: {type: 'string'},
    plot_hooks: {type: 'array', items: {type: 'string'}},
    npcs: {
      type: 'array',
      items: {
        type: 'object',
        properties: {name: {type: 'string'}, description: {type: 'string'}},
        required: ['name', 'description'],
      },
    },
    locations: {
      type: 'array',
      items: {
        type: 'object',
        properties: {name: {type: 'string'}, description: {type: 'string'}},
        required: ['name', 'description'],
      },
    },
  },
};

// src/app/api/generate/route.ts
import Exa from 'exa-js';
import {NextRequest, NextResponse} from 'next/server';

const exa = new Exa(process.env.EXA_API_KEY);

// ... adventureSchema definition ...

export async function POST(req: NextRequest) {
  const {prompt} = await req.json();

  const instructions = `You are a creative assistant for a TTRPG Game Master. 
  Use the user's prompt to find ideas from blogs, forums, and wikis to generate a compelling adventure.
  Please generate a title, a summary, a few plot hooks, some interesting NPCs, and some key locations for the adventure.
  Each one of the story components should be put into their respective schema.
  Something like the summary should not have the title, plot hooks, NPCs, etc... Those should be in their own schemas.
  For context, here is the user's prompt: ${prompt}`;

  // Create the research task, but don't wait for it to complete.
  const researchTask = await exa.research.create({
    instructions,
    outputSchema: adventureSchema,
  });

  // Immediately return the task ID to the client.
  return NextResponse.json({taskId: researchTask.researchId});
}

// src/app/api/adventure/[taskId]/route.ts
import Exa from 'exa-js';
import {NextRequest, NextResponse} from 'next/server';

import {CitationProcessor} from '@/lib/citation-processor';

const exa = new Exa(process.env.EXA_API_KEY);

export async function GET(_req: NextRequest, context: any) {
  const taskId = (await context.params).taskId;

  // We'll stream the progress from Exa.
  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();
      const citationProcessor = new CitationProcessor();
      const taskStream = await exa.research.get(taskId, {stream: true});

      for await (const event of taskStream) {
        citationProcessor.processEvent(event);

        if (
          event.eventType === 'task-operation' ||
          event.eventType === 'plan-operation'
        ) {
          const op = event.data;
          let message: string;
          switch (op.type) {
            case 'search':
              message = `Searching: "${op.query}"`;
              break;
            case 'crawl':
              message = `Crawling: ${new URL(op.result.url).hostname}`;
              break;
            case 'think':
              message = op.content;
              break;
            default:
              message = 'Starting an unknown journey...';
          }
          controller.enqueue(
            encoder.encode(
              `data: ${JSON.stringify({type: 'message', content: message})}\n\n`,
            ),
          );
        } else if (
          event.eventType === 'research-output' &&
          event.output.outputType === 'completed'
        ) {
          const finalResult = event.output;
          const deduplicatedCitations = citationProcessor.getCitations();
          const resultData = {
            ...finalResult.parsed,
            citations: deduplicatedCitations,
          };

          controller.enqueue(
            encoder.encode(
              `data: ${JSON.stringify({type: 'result', content: resultData})}\n\n`,
            ),
          );
          break;
        }
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    },
  });
}

// src/lib/citation-processor.ts
export class CitationProcessor {
  private taskIdToSection = new Map<string, string>();
  private citationsBySection: Record<string, Citation[]> = {};

  processEvent(event: any) {
    // 1. Identify which section (NPCs, Plot Hooks, etc.) the agent is working on
    if (event.eventType === 'task-definition') {
      const instructions = event.instructions.toLowerCase();
      
      if (instructions.includes('npc')) {
         this.taskIdToSection.set(event.taskId, 'npcs');
      }
      // ... map other sections (locations, plot hooks, etc.)
    } 
    // 2. Capture search results and assign them to that section
    else if (event.data.type === 'search' && event.data.results) {
      const section = this.taskIdToSection.get(event.taskId);
      
      if (section) {
        // Add the found URLs to the specific section's citation list
        this.citationsBySection[section].push(...event.data.results);
      }
    }
  }
}

git clone https://github.com/MichaelSolati/adventure-weaver.git
cd adventure-weaver

npm install

EXA_API_KEY=your_exa_api_key_here
LLM_API_KEY=your_openai_api_key_here
LLM_MODEL=gpt-4o  # or your preferred model

npm run dev