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 - High-level architecture overview
2. INTENT_DRIVEN_RESEARCH_GUIDE.md - Comprehensive guide to intent-driven research
3. .cursor/rules/researcher-architecture.mdc - Authoritative architecture rules (for developers)

---

📖 Current Architecture Documentation

Core Documentation

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

Implementation Documentation

Document	Purpose	Status
PHASE2_IMPLEMENTATION_SUMMARY.md	Phase 2 persona enhancements	✅ Current
PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md	Phase 3 features and UI indicators	✅ Current
RESEARCH_PERSONA_DATA_SOURCES.md	Persona data sources	✅ Current
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	⚠️ Outdated	Describes old 4-step wizard (StepKeyword, StepOptions, etc.)
RESEARCH_COMPONENT_INTEGRATION.md	⚠️ Outdated	Mentions Basic/Comprehensive/Targeted modes and strategy pattern
PHASE1_IMPLEMENTATION_REVIEW.md	⚠️ Partial	Some features accurate, but missing intent-driven research
RESEARCH_IMPROVEMENTS_SUMMARY.md	⚠️ Partial	Some features accurate, but missing intent-driven research
COMPLETE_IMPLEMENTATION_SUMMARY.md	⚠️ Partial	Phase 1-3 persona features accurate, but missing intent-driven research

For current architecture, see:

• CURRENT_ARCHITECTURE_OVERVIEW.md
• INTENT_DRIVEN_RESEARCH_GUIDE.md
• .cursor/rules/researcher-architecture.mdc

---

🔍 Finding Documentation

By Topic

Architecture & Design:

• CURRENT_ARCHITECTURE_OVERVIEW.md
• .cursor/rules/researcher-architecture.mdc

Intent-Driven Research:

• INTENT_DRIVEN_RESEARCH_GUIDE.md
• INTENT_RESEARCH_API_REFERENCE.md

Research Persona:

• PHASE2_IMPLEMENTATION_SUMMARY.md
• PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md
• RESEARCH_PERSONA_DATA_SOURCES.md

API Reference:

• INTENT_RESEARCH_API_REFERENCE.md

Implementation Details:

• PHASE2_IMPLEMENTATION_SUMMARY.md
• PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md

By Role

Developers:

1. Start with .cursor/rules/researcher-architecture.mdc
2. Read CURRENT_ARCHITECTURE_OVERVIEW.md
3. Reference INTENT_RESEARCH_API_REFERENCE.md

Frontend Developers:

1. INTENT_DRIVEN_RESEARCH_GUIDE.md (Frontend Integration section)
2. CURRENT_ARCHITECTURE_OVERVIEW.md (Component Structure)

Backend Developers:

1. INTENT_DRIVEN_RESEARCH_GUIDE.md (Architecture Components)
2. INTENT_RESEARCH_API_REFERENCE.md
3. .cursor/rules/researcher-architecture.mdc

Product/Design:

1. INTENT_DRIVEN_RESEARCH_GUIDE.md (User Experience Flow)
2. 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 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.