200 lines
8.3 KiB
Markdown
200 lines
8.3 KiB
Markdown
# 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.
|