Cursor rule

1---
2description: 
3globs: 
4alwaysApply: true
5---
6# OpenSearch: AI-Powered Multi-Round Research Agent
7 
8## Project Overview
9 
10OpenSearch is an AI-powered research agent that conducts sophisticated multi-round web research by:
111. **Generating optimized search queries** from user research topics
122. **Executing web searches** via Exa API to gather information
133. **Reflecting on results** to identify knowledge gaps and determine sufficiency  
144. **Iteratively searching** with follow-up queries until comprehensive information is gathered
155. **Synthesizing comprehensive answers** with proper citations and footnotes
16 
17## Architecture Overview
18 
19The project implements **two parallel architectures** for different use cases:
20 
21### 1. CLI Application (`src/cli/`)
22- **Interactive terminal interface** using React + Ink
23- **Real-time progress visualization** for each research step
24- **Event-driven architecture** with EventEmitter for UI updates
25- **Direct BAML integration** for immediate AI function calls
26- **Entry point**: `bun run cli`
27 
28### 2. Inngest Workflow (`src/inngest/`)
29- **Scalable background processing** using Inngest functions
30- **Real-time pub/sub** with channels for live updates
31- **Workflow orchestration** with step functions and retry policies
32- **Production-ready** with proper error handling and concurrency limits
33- **API integration ready** for web applications
34 
35## Key Components & File Structure
36 
37```
38opensearch/
39├── src/cli/                    # CLI Application
40│   ├── app.tsx                 # Main React component with UI orchestration
41│   ├── agent.ts                # Core agent logic with EventEmitter
42│   ├── components/             # UI Components
43│   │   ├── research-input.tsx  # User input interface
44│   │   ├── query-generation.tsx # Query generation display
45│   │   ├── search-results.tsx  # Search execution progress
46│   │   ├── reflection.tsx      # Analysis & knowledge gap display
47│   │   ├── final-answer.tsx    # Answer synthesis display
48│   │   └── markdown-renderer.tsx # Markdown rendering with citations
49│   ├── types.ts                # TypeScript types for workflow steps
50│   └── index.tsx               # CLI entry point
51├── src/inngest/                # Backend Workflow
52│   ├── functions/
53│   │   ├── deep-research.ts    # Main research orchestration function
54│   │   ├── execute-searches.ts # Web search execution with rate limiting
55│   │   └── index.ts            # Function exports
56│   ├── client.ts               # Inngest client configuration
57│   └── connection.ts           # Function registration
58├── baml_src/                   # AI Function Definitions
59│   ├── generate_query.baml     # Search query generation
60│   ├── reflect.baml            # Result analysis & gap identification
61│   ├── create_answer.baml      # Answer synthesis with citations
62│   ├── types.baml              # Structured data schemas
63│   ├── clients.baml            # LLM client configurations
64│   └── generators.baml         # Code generation settings
65├── baml_client/                # Auto-generated (DO NOT EDIT)
66│   └── [generated TypeScript files]
67└── src/utils.ts                # Shared utilities
68```
69 
70## Research Workflow
71 
72### Step-by-Step Process
73 
741. **Input Collection**
75   - User provides research topic
76   - Topic validation and preprocessing
77 
782. **Query Generation** (`GenerateQuery` BAML function)
79   - AI analyzes research topic
80   - Generates optimized search queries
81   - Creates **query plan**: specific questions that need answering
82   - Returns `SearchQueryList` with queries, rationale, and query plan
83 
843. **Web Search Execution**
85   - Parallel execution of search queries via Exa API
86   - Rate limiting (5 requests/second) and error handling
87   - Collection of search results with highlights and full text
88 
894. **Reflection Analysis** (`Reflect` BAML function)
90   - AI analyzes search results for **knowledge gap closure assessment**
91   - Tracks answered vs. unanswered questions from query plan
92   - Identifies relevant sources containing useful information
93   - Determines if current knowledge gap was closed (if any)
94   - Assesses overall research sufficiency
95 
965. **Concurrent Processing Phase**
97   - **Knowledge Gap Analysis** (`AnalyzeKnowledgeGaps` BAML function):
98     - Strategic analysis of knowledge gap history and status
99     - Smart abandonment decisions (3-round rule, thoroughness assessment)
100     - Selection of next knowledge gap to research
101     - Decision on whether to continue research or generate final answer
102   - **Fact Extraction** (`ExtractRelevantFacts` BAML function):
103     - Extract concise, relevant facts from sources identified by reflection
104     - Reduce context length while preserving key information
105     - Maintain source attribution for proper citations
106 
1076. **Follow-up Query Generation** (`GenerateFollowUpQueries` BAML function)
108   - Generate diverse queries targeting specific knowledge gaps
109   - Avoid repetition of previous failed query attempts
110   - Strategic query diversity using different angles and terminology
111   - Focus on closing identified knowledge gaps
112 
1137. **Iteration Logic**
114   - If research insufficient AND gaps worth pursuing: continue with follow-up queries
115   - If research sufficient OR all gaps resolved/abandoned: proceed to answer generation
116   - Progress tracking with round numbers and knowledge gap status
117 
1188. **Answer Synthesis** (`CreateAnswer` or `CreateAnswerFromFacts` BAML functions)
119   - AI synthesizes comprehensive answer from extracted facts or search results
120   - Markdown formatting with proper structure
121   - Automatic footnote generation with source citations
122   - Confidence indicators and knowledge gap acknowledgments
123 
124## BAML Integration Details
125 
126### Core BAML Functions
127 
128#### `GenerateQuery(args: GenerateQueryArgs) -> SearchQueryList`
129- **Purpose**: Transform research topic into search queries + structured plan
130- **Model**: Gemini 2.5 Flash (fast, cost-effective)
131- **Output**: Search queries, rationale, and comprehensive question plan
132- **Key Features**: SMART question criteria, current date awareness
133 
134#### `Reflect(summaries, topic, date, queryPlan, answered, unanswered, currentGap, round, maxRounds) -> Reflection`
135- **Purpose**: Analyze search results for knowledge gap closure assessment
136- **Model**: Gemini 2.5 Flash (fast analysis)
137- **Focus**: Gap closure evaluation, question tracking, source identification
138- **Output**: Gap closure status, answered questions, relevant sources
139- **Key Features**: Conservative gap closure assessment, evidence-based evaluation
140 
141#### `AnalyzeKnowledgeGaps(gapHistory, reflection, queryPlan, currentRound) -> KnowledgeGapAnalysis`
142- **Purpose**: Strategic analysis of knowledge gap history and research continuation
143- **Model**: Gemini 2.5 Pro (advanced reasoning)
144- **Logic**: Smart abandonment criteria, gap prioritization, research strategy
145- **Output**: Continue/stop decision, next gap selection, updated gap history
146- **Key Features**: 3-round abandonment rule, thoroughness assessment, gap tracking
147 
148#### `ExtractRelevantFacts(relevantSources, topic, queryPlan, reflection, date) -> ExtractedFact[]`
149- **Purpose**: Extract concise facts from relevant sources to reduce context length
150- **Model**: Gemini 2.5 Flash (efficient extraction)
151- **Logic**: Extract only facts relevant to query plan, avoid duplication
152- **Output**: Concise facts with source attribution for citations
153- **Key Features**: Context optimization, fact relevance filtering, citation preservation
154 
155#### `GenerateFollowUpQueries(targetGap, previousQueries, reflection, queryPlan, currentRound) -> FollowUpQueryGeneration`
156- **Purpose**: Generate diverse queries for specific knowledge gaps
157- **Model**: Gemini 2.5 Flash (fast query generation)
158- **Logic**: Query diversity strategy, avoid repetition, gap-focused targeting
159- **Output**: Diverse follow-up queries with strategy explanation
160- **Key Features**: Query diversification, gap history awareness, strategic targeting
161 
162#### `CreateAnswer(date, topic, summaries) -> string`
163- **Purpose**: Synthesize comprehensive research answer from search results
164- **Model**: Gemini 2.5 Pro (high-quality generation)
165- **Output**: Markdown-formatted answer with citations
166- **Key Features**: Footnote system, confidence indicators, source attribution
167 
168#### `CreateAnswerFromFacts(date, topic, extractedFacts) -> string`
169- **Purpose**: Synthesize comprehensive research answer from extracted facts
170- **Model**: Gemini 2.5 Pro (high-quality generation)
171- **Output**: Markdown-formatted answer with citations
172- **Key Features**: Optimized for extracted facts, maintains citation accuracy
173 
174### Data Structures (baml_src/types.baml)
175 
176```typescript
177// Core workflow types
178SearchQueryList: { queryPlan: string[], query: string[], rationale: string }
179Reflection: { 
180  isSufficient: bool, 
181  answeredQuestions: int[], 
182  unansweredQuestions: int[],
183  relevantSummaryIds: string[],
184  currentGapClosed: bool,
185  newGapsIdentified?: string[]
186}
187SearchResult: { url, id, title, highlights, text, highlightScores }
188ExtractedFact: { sourceId, relevantFacts: string[], summary }
189 
190// Knowledge gap tracking types
191KnowledgeGapHistory: { gaps: AttemptedKnowledgeGap[], currentGapIndex?: int }
192AttemptedKnowledgeGap: { 
193  description, status: "active"|"abandoned"|"resolved", 
194  attemptCount, previousQueries: string[], 
195  relatedQuestionIds: int[], firstAttemptedRound, lastAttemptedRound 
196}
197KnowledgeGapAnalysis: { 
198  shouldContinueResearch: bool, nextGapToResearch?, 
199  gapStatus: "new"|"continuing"|"switching"|"complete", 
200  reasoning, updatedGapHistory: AttemptedKnowledgeGap[] 
201}
202FollowUpQueryGeneration: { queries: string[], rationale, queryStrategy }
203```
204 
205## CLI Application Architecture
206 
207### Event-Driven Flow (`src/cli/agent.ts` + `app.tsx`)
208 
209```typescript
210// Main workflow steps
211type Step = 
212  | 'input'                        // User input received
213  | 'queries-generated'            // Search queries created
214  | 'searching'                    // Web searches in progress  
215  | 'search-results'               // Search results collected
216  | 'reflection-complete'          // Gap closure analysis finished
217  | 'knowledge-gap-analysis'       // Strategic gap analysis complete
218  | 'followup-query-generation'    // Follow-up queries generated
219  | 'summarization'                // Fact extraction (generating/complete)
220  | 'max-steps-reached'            // Round limit reached
221  | 'answer'                       // Final answer ready
222```
223 
224**Key Features:**
225- **Real-time UI updates** via EventEmitter
226- **Progress visualization** with round tracking and gap status
227- **State management** for complex multi-step workflow with knowledge gap history
228- **Concurrent processing** of gap analysis and fact extraction
229- **Strategic follow-up query generation** with diversity optimization
230- **Error boundaries** and graceful degradation
231 
232### UI Components
233 
234- **ResearchInput**: Text input with submission handling
235- **QueryGeneration**: Shows initial + follow-up queries with rationale and round context
236- **SearchResults**: Real-time search progress with query status
237- **ReflectionStep**: Gap closure analysis and question progress tracking
238- **KnowledgeGapAnalysis**: Gap history, abandonment decisions, and next gap selection
239- **FollowUpQueryGeneration**: Targeted query generation with diversity strategy
240- **FactExtraction**: Concurrent fact extraction progress and results
241- **FinalAnswer**: Answer synthesis with extracted facts or search results
242- **MarkdownRenderer**: Citation rendering with link handling
243 
244### Event Emission Patterns (`src/cli/agent.ts` → `app.tsx`)
245 
246**CRITICAL**: The CLI uses two different event emission patterns that must be used correctly to avoid duplicate UI components:
247 
248#### `state-update` (Append Pattern)
249- **Purpose**: Adds new steps to the workflow
250- **Usage**: For genuinely new workflow steps or initial emissions
251- **Example**: `eventEmitter.emit('state-update', { type: 'input', data: topic })`
252 
253#### `state-replace` (Replace Pattern)  
254- **Purpose**: Updates existing steps of the same type (replaces the last occurrence)
255- **Usage**: For progress updates or when transitioning from "generating" to "complete" states
256- **Example**: `eventEmitter.emit('state-replace', { type: 'searching', data: updatedStatus })`
257 
258#### Common Anti-Patterns to Avoid
259 
2601. **Duplicate UI Components**: 
261   - ❌ **Wrong**: Emitting both `followup-query-generation` AND `queries-generated` with same data
262   - ✅ **Correct**: Only emit `followup-query-generation` for follow-up queries
263 
2642. **Progress Updates**:
265   - ❌ **Wrong**: Using `state-update` for search query status changes (creates multiple search components)
266   - ✅ **Correct**: Use `state-replace` to update search progress in-place
267 
2683. **Generating → Complete Transitions**:
269   - ❌ **Wrong**: `state-update` for fact extraction completion (shows both generating + complete)
270   - ✅ **Correct**: `state-replace` to transition from generating to complete state
271 
272#### UI Rendering Logic (`app.tsx`)
273 
274The UI handles "generating" states by checking if steps exist in future indices:
275```typescript
276const hasFollowUpStep = steps
277  .slice(index + 1)
278  .some((s) => s.type === 'followup-query-generation');
279 
280// Show generating state only if no complete step exists yet
281{!hasFollowUpStep && isLastStep && shouldContinue && (
282  <Component isGenerating={true} />
283)}
284```
285 
286**Key Rule**: If a UI component shows a "generating" state that will be replaced by a "complete" state, the complete state MUST use `state-replace`, not `state-update`.
287 
288## Inngest Workflow Architecture
289 
290### Function Structure (`src/inngest/functions/deep-research.ts`)
291 
292```typescript
293// Main orchestration function
294deepResearch = inngest.createFunction(
295  { 
296    id: 'deep-research',
297    concurrency: { limit: 20 }
298  },
299  async ({ event, step, logger, publish }) => {
300    // 1. Generate initial queries
301    // 2. Execute searches in parallel
302    // 3. Reflect on results
303    // 4. Generate follow-ups or final answer
304    // 5. Publish real-time updates
305  }
306)
307```
308 
309**Key Features:**
310- **Real-time channels** for live updates
311- **Step functions** with automatic retries
312- **Concurrent execution** with rate limiting
313- **Error handling** with NonRetriableError
314- **Logging** throughout workflow
315 
316### Real-time Channels
317 
318```typescript
319resultsChannel(uuid)
320  .addTopic('initialQueries', SearchQueryList)
321  .addTopic('webSearchResults', SearchResult[])
322  .addTopic('reflection', Reflection)
323  .addTopic('finalAnswer', string)
324```
325 
326## Key Utilities (`src/utils.ts`)
327 
328### Citation System
329- **processFootnotes()**: Converts random IDs to numbered footnotes
330- **insertCitationMarkers()**: Adds citation links to text
331- **getCitations()**: Extracts citations from Gemini responses
332 
333### Helper Functions
334- **nanoid()**: Generate unique IDs for search results
335- **requireEnvironment()**: Environment variable validation
336 
337## Configuration & Environment
338 
339### Required Environment Variables
340```bash
341EXA_API_KEY=           # Exa search API key
342GOOGLE_API_KEY=        # Google AI (Gemini) API key
343ANTHROPIC_API_KEY=     # Anthropic (Claude) API key (optional)
344OPENAI_API_KEY=        # OpenAI API key (optional)
345INNGEST_BASE_URL=      # Inngest endpoint (for workflow version)
346```
347 
348### LLM Client Options (baml_src/clients.baml)
349- **Primary**: Google AI (Gemini 2.5 Pro/Flash)
350- **Fallback**: OpenAI GPT-4o, Anthropic Claude 3.5 Sonnet
351- **Retry policies**: Exponential backoff, constant delay
352 
353## Testing Strategy
354 
355### Integration Tests
356- **Manual testing script**: `scripts/test-follow-up-queries.ts`
357- **BAML function tests**: `test/generate-query.test.ts`
358- **Real API integration**: Uses actual Exa + BAML calls
359 
360### Test Coverage
361- Follow-up query generation and execution
362- Multi-round workflow progression
363- Question tracking and completion
364- Citation processing and footnote generation
365 
366## Usage Examples
367 
368### CLI Usage
369```bash
370bun run cli                    # Start interactive CLI
371bun run dev                    # Development mode with watching
372bun test                       # Run all tests
373bun test test/specific.test.ts # Run specific test
374```
375 
376### Complex Research Example
377```
378Topic: "Compare fintech vs healthtech startup funding in 2024"
379 
380Round 1: General funding queries
381├── Reflection: Missing healthtech-specific data
382Round 2: Healthtech-focused follow-up queries  
383├── Reflection: Missing comparative analysis
384Round 3: Comparative analysis queries
385└── Final Answer: Comprehensive comparison with metrics
386```
387 
388## Production Considerations
389 
390### Rate Limiting
391- **Exa API**: 5 requests/second (handled automatically)
392- **LLM APIs**: Retry policies with exponential backoff
393- **Concurrency**: Limited to 20 concurrent workflows
394 
395### Error Handling
396- **Network failures**: Automatic retries with backoff
397- **API limits**: Graceful degradation and queuing
398- **Malformed responses**: Validation and fallbacks
399- **Max rounds**: Prevents infinite loops
400 
401### Monitoring
402- **Inngest dashboard**: Workflow execution monitoring
403- **Step-by-step logging**: Detailed execution traces
404- **Real-time channels**: Live progress updates
405 
406## Development Workflow
407 
408### Code Organization
409- **CLI logic**: Event-driven with React components
410- **Backend logic**: Step functions with proper error handling  
411- **BAML functions**: Declarative AI function definitions
412- **Shared utilities**: Citation processing and helpers
413- **Type safety**: Strict TypeScript throughout
414 
415### Key Design Principles
416- **Iterative research**: Multi-round approach mimics human research
417- **Conservative early, decisive late**: Reflection strategy adapts by round
418- **Source attribution**: Proper citations with footnotes
419- **Real-time feedback**: Progress visibility throughout process
420- **Graceful degradation**: Handles API failures and edge cases
421 
422This architecture provides both immediate interactive research (CLI) and scalable background processing (Inngest) while maintaining consistent AI-powered research quality through BAML function integration.
423