ALwrity/docs/ALwrity Researcher/README.md

# ALwrity Researcher Documentation

**Last Updated**: 2025-01-29

---

## 📚 Documentation Index

This directory contains documentation for the ALwrity Research Engine. Use this index to find the right documentation for your needs.

---

## 🎯 Quick Start

**New to the Research Engine?** Start here:

1. **[CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md)** - High-level architecture overview
2. **[INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md)** - Comprehensive guide to intent-driven research
3. **[.cursor/rules/researcher-architecture.mdc](../../../.cursor/rules/researcher-architecture.mdc)** - Authoritative architecture rules (for developers)

---

## 📖 Current Architecture Documentation

### Core Documentation

| Document | Purpose | Status |
|----------|---------|--------|
| **[CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md)** | Single source of truth for current architecture | ✅ Current |
| **[INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md)** | Comprehensive guide to intent-driven research | ✅ Current |
| **[INTENT_RESEARCH_API_REFERENCE.md](./INTENT_RESEARCH_API_REFERENCE.md)** | Complete API endpoint documentation | ✅ Current |
| **[.cursor/rules/researcher-architecture.mdc](../../../.cursor/rules/researcher-architecture.mdc)** | Authoritative architecture rules | ✅ Current |

### Implementation Documentation

| Document | Purpose | Status |
|----------|---------|--------|
| **[PHASE2_IMPLEMENTATION_SUMMARY.md](./PHASE2_IMPLEMENTATION_SUMMARY.md)** | Phase 2 persona enhancements | ✅ Current |
| **[PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md](./PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md)** | Phase 3 features and UI indicators | ✅ Current |
| **[RESEARCH_PERSONA_DATA_SOURCES.md](./RESEARCH_PERSONA_DATA_SOURCES.md)** | Persona data sources | ✅ Current |
| **[RESEARCH_PERSONA_DATA_RETRIEVAL_REVIEW.md](./RESEARCH_PERSONA_DATA_RETRIEVAL_REVIEW.md)** | Persona data retrieval | ✅ Current |

---

## ⚠️ Outdated Documentation

The following documents describe an **older architecture** and should be used for historical reference only:

| Document | Status | Notes |
|----------|--------|-------|
| **[RESEARCH_WIZARD_IMPLEMENTATION.md](./RESEARCH_WIZARD_IMPLEMENTATION.md)** | ⚠️ Outdated | Describes old 4-step wizard (StepKeyword, StepOptions, etc.) |
| **[RESEARCH_COMPONENT_INTEGRATION.md](./RESEARCH_COMPONENT_INTEGRATION.md)** | ⚠️ Outdated | Mentions Basic/Comprehensive/Targeted modes and strategy pattern |
| **[PHASE1_IMPLEMENTATION_REVIEW.md](./PHASE1_IMPLEMENTATION_REVIEW.md)** | ⚠️ Partial | Some features accurate, but missing intent-driven research |
| **[RESEARCH_IMPROVEMENTS_SUMMARY.md](./RESEARCH_IMPROVEMENTS_SUMMARY.md)** | ⚠️ Partial | Some features accurate, but missing intent-driven research |
| **[COMPLETE_IMPLEMENTATION_SUMMARY.md](./COMPLETE_IMPLEMENTATION_SUMMARY.md)** | ⚠️ Partial | Phase 1-3 persona features accurate, but missing intent-driven research |

**For current architecture**, see:
- **[CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md)**
- **[INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md)**
- **[.cursor/rules/researcher-architecture.mdc](../../../.cursor/rules/researcher-architecture.mdc)**

---

## 🔍 Finding Documentation

### By Topic

**Architecture & Design**:
- [CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md)
- [.cursor/rules/researcher-architecture.mdc](../../../.cursor/rules/researcher-architecture.mdc)

**Intent-Driven Research**:
- [INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md)
- [INTENT_RESEARCH_API_REFERENCE.md](./INTENT_RESEARCH_API_REFERENCE.md)

**Research Persona**:
- [PHASE2_IMPLEMENTATION_SUMMARY.md](./PHASE2_IMPLEMENTATION_SUMMARY.md)
- [PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md](./PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md)
- [RESEARCH_PERSONA_DATA_SOURCES.md](./RESEARCH_PERSONA_DATA_SOURCES.md)

**API Reference**:
- [INTENT_RESEARCH_API_REFERENCE.md](./INTENT_RESEARCH_API_REFERENCE.md)

**Implementation Details**:
- [PHASE2_IMPLEMENTATION_SUMMARY.md](./PHASE2_IMPLEMENTATION_SUMMARY.md)
- [PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md](./PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md)

### By Role

**Developers**:
1. Start with [.cursor/rules/researcher-architecture.mdc](../../../.cursor/rules/researcher-architecture.mdc)
2. Read [CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md)
3. Reference [INTENT_RESEARCH_API_REFERENCE.md](./INTENT_RESEARCH_API_REFERENCE.md)

**Frontend Developers**:
1. [INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md) (Frontend Integration section)
2. [CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md) (Component Structure)

**Backend Developers**:
1. [INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md) (Architecture Components)
2. [INTENT_RESEARCH_API_REFERENCE.md](./INTENT_RESEARCH_API_REFERENCE.md)
3. [.cursor/rules/researcher-architecture.mdc](../../../.cursor/rules/researcher-architecture.mdc)

**Product/Design**:
1. [INTENT_DRIVEN_RESEARCH_GUIDE.md](./INTENT_DRIVEN_RESEARCH_GUIDE.md) (User Experience Flow)
2. [CURRENT_ARCHITECTURE_OVERVIEW.md](./CURRENT_ARCHITECTURE_OVERVIEW.md) (UI Components)

---

## 📋 Documentation Status

### ✅ Current & Accurate

- ✅ **CURRENT_ARCHITECTURE_OVERVIEW.md** - Single source of truth
- ✅ **INTENT_DRIVEN_RESEARCH_GUIDE.md** - Comprehensive guide
- ✅ **INTENT_RESEARCH_API_REFERENCE.md** - Complete API docs
- ✅ **.cursor/rules/researcher-architecture.mdc** - Authoritative rules
- ✅ **PHASE2_IMPLEMENTATION_SUMMARY.md** - Persona enhancements
- ✅ **PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md** - Phase 3 features
- ✅ **RESEARCH_PERSONA_DATA_SOURCES.md** - Persona data sources

### ⚠️ Needs Update

- ⚠️ **RESEARCH_WIZARD_IMPLEMENTATION.md** - Describes old wizard structure
- ⚠️ **RESEARCH_COMPONENT_INTEGRATION.md** - Mentions old architecture
- ⚠️ **PHASE1_IMPLEMENTATION_REVIEW.md** - Missing intent-driven research
- ⚠️ **RESEARCH_IMPROVEMENTS_SUMMARY.md** - Missing intent-driven research
- ⚠️ **COMPLETE_IMPLEMENTATION_SUMMARY.md** - Missing intent-driven research

### 📝 Update Plan

See **[DOCUMENTATION_REVIEW_AND_UPDATE_PLAN.md](./DOCUMENTATION_REVIEW_AND_UPDATE_PLAN.md)** for detailed update plan.

---

## 🎯 Key Concepts

### Intent-Driven Research

The Research Engine uses **intent-driven research** instead of traditional keyword-based searches:

1. **Intent Analysis**: AI understands what user wants before searching
2. **Unified Analysis**: Single AI call for intent + queries + params
3. **Intent-Aware Analysis**: Results analyzed through lens of user intent
4. **Structured Deliverables**: Returns exactly what users need (statistics, quotes, case studies, etc.)

### Architecture Evolution

**Old Architecture** (Documented in outdated files):
- Basic/Comprehensive/Targeted modes
- Strategy pattern
- 4-step wizard

**Current Architecture** (Documented in current files):
- Intent-driven research
- UnifiedResearchAnalyzer
- 3-step wizard with intent analysis

---

## 🔗 Related Documentation

- **Architecture Rules**: `.cursor/rules/researcher-architecture.mdc` (Authoritative)
- **Documentation Review**: `DOCUMENTATION_REVIEW_AND_UPDATE_PLAN.md`

---

## 📌 Quick Reference

### Main Components

- **UnifiedResearchAnalyzer**: Single AI call for intent + queries + params
- **IntentAwareAnalyzer**: Analyzes results based on intent
- **ResearchEngine**: Orchestrates provider calls (Exa → Tavily → Google)

### Key Endpoints

- `POST /api/research/intent/analyze` - Analyze user intent
- `POST /api/research/intent/research` - Execute intent-driven research

### Key Patterns

1. Always use `UnifiedResearchAnalyzer` for new intent-driven research
2. Always pass `user_id` to all LLM calls
3. Always use `IntentAwareAnalyzer` for result analysis
4. Provider priority: Exa → Tavily → Google

---

## ✅ Best Practices

1. **Use Current Documentation**: Always refer to current architecture docs
2. **Check Architecture Rules**: `.cursor/rules/researcher-architecture.mdc` is authoritative
3. **Update Outdated Docs**: When referencing outdated docs, verify against current architecture
4. **Follow Patterns**: Use documented patterns for consistency

---

**Status**: Documentation Index - Use this to navigate all Researcher documentation.