ezzabuzaid · October 13, 2025 20:01
diff --git a/reverse-user-story.ts b/reverse-user-story.ts
 import { groq } from '@ai-sdk/groq';
 import { openai } from '@ai-sdk/openai';
 import { readFile, writeFile } from 'node:fs/promises';
 import z from 'zod';

 import { agent, execute, toOutput } from '@deepagents/agent';
 import { fastembed, nodeSQLite, similaritySearch } from '@deepagents/retrieval';
 import * as connectors from '@deepagents/retrieval/connectors';

 const searchQueryAgent = agent({
  name: 'search-query-generator',
  model: groq('openai/gpt-oss-20b'),
  prompt: [
    `You are an expert research assistant. Given the user's query, generate up to four distinct precise search queries that would help gather comprehensive information from github repository content.`,
    `The repository is a codebase for a web application that is stored in a vector database for semantic search. The content includes code files, documentation, and comments.`,
    'Your goal is to create search queries that will yield relevant and diverse results to help answer the user query thoroughly.',
  ],
  output: z.object({ items: z.array(z.string()).max(4) }),
 });

 const newSearchQueriesAgent = agent({
  name: 'research-continuation-planner',
  model: groq('openai/gpt-oss-120b'),
  prompt:
    'You are an analytical research assistant. Based on the original query, the search queries performed so far, and the extracted contexts, determine if further research is needed.',
  output: z.object({
    needsMoreResearch: z
      .boolean()
      .describe('Whether additional research is needed'),
    newQueries: z
      .array(z.string())
      .max(4)
      .describe(
        'Up to four new search queries if more research is needed, empty array otherwise',
      ),
    reasoning: z
      .string()
      .optional()
      .describe('Brief explanation of the decision'),
  }),
 });

 const pageUsefulnessAgent = agent({
  name: 'page-usefulness-evaluator',
  model: groq('openai/gpt-oss-20b'),
  prompt: [
    'You are a strict and concise evaluator of research relevance.',
    "Given the user's query and the content of a repository file, determine if the file contains information relevant and useful for addressing the query.",
    "Respond with exactly one word: 'Yes' if the file is useful, or 'No' if it is not.",
  ],
  output: z.object({ answer: z.enum(['Yes', 'No']) }),
 });

 const extractRelevantContextAgent = agent({
  name: 'relevant-context-extractor',
  model: groq('openai/gpt-oss-20b'),
  prompt: [
    'You are an expert in extracting and summarizing relevant information.',
    "Given the user's query, the search query that led to this page, and the file content, extract all pieces of information that are relevant to answering the user's query.",
    'Return only the relevant context as plain text without commentary.',
  ],
  output: z.object({ context: z.string() }),
 });

 const finalReportAgent = agent({
  name: 'final-report-writer',
  model: openai('gpt-4.1'),
  prompt: `You are an expert product manager that is working on reversing existing product to user stories based on a developer question/inquiry. Based on the gathered contexts below and the original query, write a comprehensive, well-structured, and detailed report that addresses the query thoroughly.\nInclude all relevant insights and conclusions without extraneous commentary.`,
 });

 async function generateSearchQueries(input: string): Promise<string[]> {
  const output = await toOutput<{ items: string[] }>(
    execute(searchQueryAgent, input, {}),
  );
  return output.items;
 }

 async function performSearch(query: string) {
  const results = await similaritySearch(query, {
    connector: connectors.repo(
      '/Users/ezzabuzaid/Desktop/mo/virtual-care',
      ['.ts', '.tsx', '.md', '.prisma'],
      'never',
    ),
    store: nodeSQLite('deepsearch.sqlite', 384),
    embedder: fastembed(),
  });
  return results.map((it) => ({
    snippet: it.content,
    source: it.document_id,
    similarity: it.similarity,
  }));
 }

 export async function getNewSearchQueries(
  userQuery: string,
  previousSearchQueries: string[],
  allContexts: string[],
 ): Promise<string[]> {
  const contextCombined = allContexts.join('\n\n');
  const prompt = `User Query: ${userQuery}

 Previous Search Queries: ${JSON.stringify(previousSearchQueries)}

 Extracted Relevant Contexts:
 ${contextCombined}

 Based on the above information, determine if further research is needed. If yes, provide up to four new search queries. If the research is complete and sufficient, indicate that no more research is needed.`;

  try {
    const output = await toOutput<{
      needsMoreResearch: boolean;
      newQueries: string[];
      reasoning?: string;
    }>(execute(newSearchQueriesAgent, prompt, {}));

    if (!output.needsMoreResearch) {
      console.log(
        'Research assessment: No further research needed.',
        output.reasoning,
      );
      return [];
    }

    console.log(
      `Research assessment: ${output.newQueries.length} new queries generated.`,
      output.reasoning,
    );
    return output.newQueries;
  } catch (error) {
    console.error('Error generating new search queries:', error);
    return [];
  }
 }

 export async function generateFinalReport(
  userQuery: string,
  formatting: string,
  allContexts: string[],
 ): Promise<string> {
  const contextCombined = allContexts.join('\n\n');
  const prompt = `
 Developer Query: ${userQuery}
 Formatting: ${formatting}

 Gathered Relevant Contexts:
 ${contextCombined}`;

  return execute(finalReportAgent, prompt, {}).text;
 }

 async function isPageUseful(userQuery: string, pageText: string) {
  const prompt = `User Query: ${userQuery}\n\nRepo file content\n\n${pageText}\n\nDecide if the page is useful.`;
  const { answer } = await toOutput<{ answer: 'Yes' | 'No' }>(
    execute(pageUsefulnessAgent, prompt, {} as const),
  );
  return answer === 'Yes';
 }

 async function extractRelevantContext(
  userQuery: string,
  searchQuery: string,
  pageText: string,
 ): Promise<string> {
  const prompt = `User Query: ${userQuery}\nSearch Query: ${searchQuery}\n\nRepo file content\n\n${pageText}\n\nExtract the relevant context.`;
  const { context } = await toOutput<{ context: string }>(
    execute(extractRelevantContextAgent, prompt, {} as const),
  );
  return context.trim();
 }

 async function processFile(
  filePath: string,
  userQuery: string,
  searchQuery: string,
 ) {
  const content = await readFile(filePath, 'utf-8');
  // const useful = await isPageUseful(userQuery, content);
  // return extractRelevantContext(userQuery, searchQuery, content);
  // if (useful) {
  //   return extractRelevantContext(userQuery, searchQuery, content);
  // }
  // return '';
  return {source:filePath,content};
 }

 const userQuery =
  'How does the b2b works here? we recently added it but I need to understand the full flow and how it integrates with the rest of the system including payment.';

 const formatting = `
 1. use ascii markdown diagrams to illustrate. I am visual learner and I love markdown.
 2. use "user stories" to illustrate flows. we are not looking for only text or techical explanation.
 3. user story scenario should be divided by actors and steps.
 4. when referencing code snippets, include file path.
 `;

 const iterLimit = 5;
 const aggregatedContexts: string[] = [];
 const allSearchQueries = [];
 let iteration = 0;
 let searchQueriesResult = await generateSearchQueries(userQuery);

 while (iteration < iterLimit) {
  const uniqueLinks: Record<string, string> = {};
  const iterationContexts: string[] = [];

  allSearchQueries.push(...searchQueriesResult);
  const searchResults: Awaited<ReturnType<typeof performSearch>>[] = [];
  for (const sq of searchQueriesResult) {
    const results = await performSearch(sq);
    searchResults.push(results);
  }
  for (let i = 0; i < searchResults.length; i++) {
    const query = searchQueriesResult[i];
    for (const result of searchResults[i]) {
      if (!uniqueLinks[result.source]) {
        uniqueLinks[result.source] = query;
      }
    }
  }

  await Promise.all(
    Object.entries(uniqueLinks).map(async ([link, query]) => {
      const context = await processFile(link, userQuery, query);
      if (context) {
        iterationContexts.push(`Source: ${context.source}\n\nContent: ${context.content}\n\n`);
      }
    }),
  );

  // for (const link in uniqueLinks) {
  //   const context = await processFile(link, userQuery, uniqueLinks[link]);
  //   if (!context) continue;
  //   iterationContexts.push(context);
  // }

  if (iterationContexts.length === 0) {
    console.log('No useful contexts were found in this iteration.');
  } else {
    aggregatedContexts.push(...iterationContexts);
  }
  console.dir(uniqueLinks, { depth: null });

  searchQueriesResult = await getNewSearchQueries(
    userQuery,
    allSearchQueries,
    aggregatedContexts,
  );
  if (searchQueriesResult.length === 0) {
    console.log('No further research needed. Exiting loop.');
    break;
  } else {
    allSearchQueries.push(...searchQueriesResult);
  }

  iteration += 1;
 }

 console.log('\nGenerating final report...');
 console.log('Search queries performed:', allSearchQueries);
 const finalReport = await generateFinalReport(
  userQuery,
  formatting,
  aggregatedContexts,
 );

 await writeFile('final_report.md', finalReport);
diff --git a/user_stories.md b/user_stories.md
	import { groq } from '@ai-sdk/groq';
	import { openai } from '@ai-sdk/openai';
	import { readFile, writeFile } from 'node:fs/promises';
	import z from 'zod';

	import { agent, execute, toOutput } from '@deepagents/agent';
	import { fastembed, nodeSQLite, similaritySearch } from '@deepagents/retrieval';
	import * as connectors from '@deepagents/retrieval/connectors';

	const searchQueryAgent = agent({
	name: 'search-query-generator',
	model: groq('openai/gpt-oss-20b'),
	prompt: [
	`You are an expert research assistant. Given the user's query, generate up to four distinct precise search queries that would help gather comprehensive information from github repository content.`,
	`The repository is a codebase for a web application that is stored in a vector database for semantic search. The content includes code files, documentation, and comments.`,
	'Your goal is to create search queries that will yield relevant and diverse results to help answer the user query thoroughly.',
	],
	output: z.object({ items: z.array(z.string()).max(4) }),
	});

	const newSearchQueriesAgent = agent({
	name: 'research-continuation-planner',
	model: groq('openai/gpt-oss-120b'),
	prompt:
	'You are an analytical research assistant. Based on the original query, the search queries performed so far, and the extracted contexts, determine if further research is needed.',
	output: z.object({
	needsMoreResearch: z
	.boolean()
	.describe('Whether additional research is needed'),
	newQueries: z
	.array(z.string())
	.max(4)
	.describe(
	'Up to four new search queries if more research is needed, empty array otherwise',
	),
	reasoning: z
	.string()
	.optional()
	.describe('Brief explanation of the decision'),
	}),
	});

	const pageUsefulnessAgent = agent({
	name: 'page-usefulness-evaluator',
	model: groq('openai/gpt-oss-20b'),
	prompt: [
	'You are a strict and concise evaluator of research relevance.',
	"Given the user's query and the content of a repository file, determine if the file contains information relevant and useful for addressing the query.",
	"Respond with exactly one word: 'Yes' if the file is useful, or 'No' if it is not.",
	],
	output: z.object({ answer: z.enum(['Yes', 'No']) }),
	});

	const extractRelevantContextAgent = agent({
	name: 'relevant-context-extractor',
	model: groq('openai/gpt-oss-20b'),
	prompt: [
	'You are an expert in extracting and summarizing relevant information.',
	"Given the user's query, the search query that led to this page, and the file content, extract all pieces of information that are relevant to answering the user's query.",
	'Return only the relevant context as plain text without commentary.',
	],
	output: z.object({ context: z.string() }),
	});

	const finalReportAgent = agent({
	name: 'final-report-writer',
	model: openai('gpt-4.1'),
	prompt: `You are an expert product manager that is working on reversing existing product to user stories based on a developer question/inquiry. Based on the gathered contexts below and the original query, write a comprehensive, well-structured, and detailed report that addresses the query thoroughly.\nInclude all relevant insights and conclusions without extraneous commentary.`,
	});

	async function generateSearchQueries(input: string): Promise<string[]> {
	const output = await toOutput<{ items: string[] }>(
	execute(searchQueryAgent, input, {}),
	);
	return output.items;
	}

	async function performSearch(query: string) {
	const results = await similaritySearch(query, {
	connector: connectors.repo(
	'/Users/ezzabuzaid/Desktop/mo/virtual-care',
	['.ts', '.tsx', '.md', '.prisma'],
	'never',
	),
	store: nodeSQLite('deepsearch.sqlite', 384),
	embedder: fastembed(),
	});
	return results.map((it) => ({
	snippet: it.content,
	source: it.document_id,
	similarity: it.similarity,
	}));
	}

	export async function getNewSearchQueries(
	userQuery: string,
	previousSearchQueries: string[],
	allContexts: string[],
	): Promise<string[]> {
	const contextCombined = allContexts.join('\n\n');
	const prompt = `User Query: ${userQuery}

	Previous Search Queries: ${JSON.stringify(previousSearchQueries)}

	Extracted Relevant Contexts:
	${contextCombined}

	Based on the above information, determine if further research is needed. If yes, provide up to four new search queries. If the research is complete and sufficient, indicate that no more research is needed.`;

	try {
	const output = await toOutput<{
	needsMoreResearch: boolean;
	newQueries: string[];
	reasoning?: string;
	}>(execute(newSearchQueriesAgent, prompt, {}));

	if (!output.needsMoreResearch) {
	console.log(
	'Research assessment: No further research needed.',
	output.reasoning,
	);
	return [];
	}

	console.log(
	`Research assessment: ${output.newQueries.length} new queries generated.`,
	output.reasoning,
	);
	return output.newQueries;
	} catch (error) {
	console.error('Error generating new search queries:', error);
	return [];
	}
	}

	export async function generateFinalReport(
	userQuery: string,
	formatting: string,
	allContexts: string[],
	): Promise<string> {
	const contextCombined = allContexts.join('\n\n');
	const prompt = `
	Developer Query: ${userQuery}
	Formatting: ${formatting}

	Gathered Relevant Contexts:
	${contextCombined}`;

	return execute(finalReportAgent, prompt, {}).text;
	}

	async function isPageUseful(userQuery: string, pageText: string) {
	const prompt = `User Query: ${userQuery}\n\nRepo file content\n\n${pageText}\n\nDecide if the page is useful.`;
	const { answer } = await toOutput<{ answer: 'Yes' \| 'No' }>(
	execute(pageUsefulnessAgent, prompt, {} as const),
	);
	return answer === 'Yes';
	}

	async function extractRelevantContext(
	userQuery: string,
	searchQuery: string,
	pageText: string,
	): Promise<string> {
	const prompt = `User Query: ${userQuery}\nSearch Query: ${searchQuery}\n\nRepo file content\n\n${pageText}\n\nExtract the relevant context.`;
	const { context } = await toOutput<{ context: string }>(
	execute(extractRelevantContextAgent, prompt, {} as const),
	);
	return context.trim();
	}

	async function processFile(
	filePath: string,
	userQuery: string,
	searchQuery: string,
	) {
	const content = await readFile(filePath, 'utf-8');
	// const useful = await isPageUseful(userQuery, content);
	// return extractRelevantContext(userQuery, searchQuery, content);
	// if (useful) {
	// return extractRelevantContext(userQuery, searchQuery, content);
	// }
	// return '';
	return {source:filePath,content};
	}

	const userQuery =
	'How does the b2b works here? we recently added it but I need to understand the full flow and how it integrates with the rest of the system including payment.';

	const formatting = `
	1. use ascii markdown diagrams to illustrate. I am visual learner and I love markdown.
	2. use "user stories" to illustrate flows. we are not looking for only text or techical explanation.
	3. user story scenario should be divided by actors and steps.
	4. when referencing code snippets, include file path.
	`;

	const iterLimit = 5;
	const aggregatedContexts: string[] = [];
	const allSearchQueries = [];
	let iteration = 0;
	let searchQueriesResult = await generateSearchQueries(userQuery);

	while (iteration < iterLimit) {
	const uniqueLinks: Record<string, string> = {};
	const iterationContexts: string[] = [];

	allSearchQueries.push(...searchQueriesResult);
	const searchResults: Awaited<ReturnType<typeof performSearch>>[] = [];
	for (const sq of searchQueriesResult) {
	const results = await performSearch(sq);
	searchResults.push(results);
	}
	for (let i = 0; i < searchResults.length; i++) {
	const query = searchQueriesResult[i];
	for (const result of searchResults[i]) {
	if (!uniqueLinks[result.source]) {
	uniqueLinks[result.source] = query;
	}
	}
	}

	await Promise.all(
	Object.entries(uniqueLinks).map(async ([link, query]) => {
	const context = await processFile(link, userQuery, query);
	if (context) {
	iterationContexts.push(`Source: ${context.source}\n\nContent: ${context.content}\n\n`);
	}
	}),
	);

	// for (const link in uniqueLinks) {
	// const context = await processFile(link, userQuery, uniqueLinks[link]);
	// if (!context) continue;
	// iterationContexts.push(context);
	// }

	if (iterationContexts.length === 0) {
	console.log('No useful contexts were found in this iteration.');
	} else {
	aggregatedContexts.push(...iterationContexts);
	}
	console.dir(uniqueLinks, { depth: null });

	searchQueriesResult = await getNewSearchQueries(
	userQuery,
	allSearchQueries,
	aggregatedContexts,
	);
	if (searchQueriesResult.length === 0) {
	console.log('No further research needed. Exiting loop.');
	break;
	} else {
	allSearchQueries.push(...searchQueriesResult);
	}

	iteration += 1;
	}

	console.log('\nGenerating final report...');
	console.log('Search queries performed:', allSearchQueries);
	const finalReport = await generateFinalReport(
	userQuery,
	formatting,
	aggregatedContexts,
	);

	await writeFile('final_report.md', finalReport);
Actor	Action	System Behavior (B2B)	Payment Handling	Usage Limit
Coordinator	Create B2B Patient	Registers, sets usage limit	N/A	Set
B2B Patient	Book Appointment	Checks usage, skips payment	Skipped/Custom	Decrement
B2B Patient	View Profile	Shows org & usage limit	N/A	Display
Coordinator	List/Manage Patients	CRUD, search, paginate	N/A	Manage