Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
294
crates/rvlite/examples/dashboard/docs/README.md
Normal file
294
crates/rvlite/examples/dashboard/docs/README.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Bulk Vector Import Documentation
|
||||
|
||||
Complete implementation guide for adding CSV/JSON bulk vector import to the RvLite dashboard.
|
||||
|
||||
## Quick Start (3 Steps)
|
||||
|
||||
1. **Read Integration Guide**
|
||||
```bash
|
||||
cat docs/INTEGRATION_GUIDE.md
|
||||
```
|
||||
|
||||
2. **Run Automation Script**
|
||||
```bash
|
||||
chmod +x apply-bulk-import.sh
|
||||
./apply-bulk-import.sh
|
||||
```
|
||||
|
||||
3. **Copy Code Snippets**
|
||||
- Open `docs/bulk-import-code.tsx`
|
||||
- Copy sections 4-10 into `src/App.tsx` at specified locations
|
||||
|
||||
## Documentation Files
|
||||
|
||||
### 📖 Core Guides
|
||||
|
||||
#### 1. **INTEGRATION_GUIDE.md** - Start Here
|
||||
Complete step-by-step integration instructions with testing procedures.
|
||||
|
||||
**Use Case**: You want to integrate the feature into your dashboard.
|
||||
|
||||
**Contains**:
|
||||
- Quick integration (3 steps)
|
||||
- Manual integration (detailed)
|
||||
- Testing instructions
|
||||
- Troubleshooting
|
||||
- Integration checklist
|
||||
|
||||
#### 2. **BULK_IMPORT_IMPLEMENTATION.md** - Reference
|
||||
Detailed implementation with exact line numbers and code blocks.
|
||||
|
||||
**Use Case**: You need to know exactly what code goes where.
|
||||
|
||||
**Contains**:
|
||||
- Line-by-line implementation guide
|
||||
- All code blocks with context
|
||||
- Format specifications (CSV/JSON)
|
||||
- Testing samples
|
||||
|
||||
#### 3. **IMPLEMENTATION_SUMMARY.md** - Overview
|
||||
High-level overview of the entire implementation.
|
||||
|
||||
**Use Case**: You want to understand the feature before implementing.
|
||||
|
||||
**Contains**:
|
||||
- Feature list
|
||||
- Architecture overview
|
||||
- Code structure
|
||||
- File locations
|
||||
- Success criteria
|
||||
|
||||
#### 4. **VISUAL_INTEGRATION_MAP.md** - Visual Guide
|
||||
Visual diagrams showing integration points and data flow.
|
||||
|
||||
**Use Case**: You prefer visual learning or need to see the big picture.
|
||||
|
||||
**Contains**:
|
||||
- App.tsx structure diagram
|
||||
- Integration points map
|
||||
- Code flow diagrams
|
||||
- Data flow diagrams
|
||||
- Component hierarchy
|
||||
|
||||
### 💻 Code Files
|
||||
|
||||
#### 5. **bulk-import-code.tsx** - Copy-Paste Ready
|
||||
All code snippets organized by section, ready to copy.
|
||||
|
||||
**Use Case**: You want to copy-paste code directly.
|
||||
|
||||
**Contains**:
|
||||
- 10 sections of code
|
||||
- Import statements
|
||||
- State management
|
||||
- Functions (5 handlers)
|
||||
- UI components (button + modal)
|
||||
|
||||
### 📊 Sample Data
|
||||
|
||||
#### 6. **sample-bulk-import.csv** - CSV Test Data
|
||||
Sample CSV file with 8 vectors for testing.
|
||||
|
||||
**Format**:
|
||||
```csv
|
||||
id,embedding,metadata
|
||||
vec_001,"[0.12, 0.45, 0.78, 0.23, 0.91]","{""category"":""product""}"
|
||||
```
|
||||
|
||||
**Use Case**: Test CSV import functionality.
|
||||
|
||||
#### 7. **sample-bulk-import.json** - JSON Test Data
|
||||
Sample JSON file with 8 vectors for testing.
|
||||
|
||||
**Format**:
|
||||
```json
|
||||
[
|
||||
{ "id": "json_vec_001", "embedding": [0.15, 0.42], "metadata": {} }
|
||||
]
|
||||
```
|
||||
|
||||
**Use Case**: Test JSON import functionality.
|
||||
|
||||
## Automation Script
|
||||
|
||||
### **apply-bulk-import.sh** - Automated Setup
|
||||
Bash script that automatically adds basic code to App.tsx.
|
||||
|
||||
**Adds**:
|
||||
- Icon import
|
||||
- Modal disclosure hook
|
||||
- State variables
|
||||
|
||||
**Requires Manual**:
|
||||
- Functions (copy from bulk-import-code.tsx)
|
||||
- Button (copy from bulk-import-code.tsx)
|
||||
- Modal (copy from bulk-import-code.tsx)
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md ← You are here
|
||||
├── INTEGRATION_GUIDE.md ← Start here for integration
|
||||
├── BULK_IMPORT_IMPLEMENTATION.md ← Detailed code reference
|
||||
├── IMPLEMENTATION_SUMMARY.md ← Feature overview
|
||||
├── VISUAL_INTEGRATION_MAP.md ← Visual diagrams
|
||||
├── bulk-import-code.tsx ← Copy-paste snippets
|
||||
├── sample-bulk-import.csv ← Test CSV data
|
||||
└── sample-bulk-import.json ← Test JSON data
|
||||
```
|
||||
|
||||
## Integration Path
|
||||
|
||||
### For First-Time Users
|
||||
```
|
||||
1. Read IMPLEMENTATION_SUMMARY.md (5 min - understand feature)
|
||||
2. Read INTEGRATION_GUIDE.md (10 min - learn process)
|
||||
3. Run apply-bulk-import.sh (1 min - automated setup)
|
||||
4. Copy from bulk-import-code.tsx (5 min - add functions/UI)
|
||||
5. Test with sample data (5 min - verify works)
|
||||
Total: ~25 minutes
|
||||
```
|
||||
|
||||
### For Experienced Developers
|
||||
```
|
||||
1. Skim VISUAL_INTEGRATION_MAP.md (2 min - see structure)
|
||||
2. Run apply-bulk-import.sh (1 min - automated setup)
|
||||
3. Copy from bulk-import-code.tsx (5 min - add code)
|
||||
4. Test with sample data (2 min - verify)
|
||||
Total: ~10 minutes
|
||||
```
|
||||
|
||||
### For Visual Learners
|
||||
```
|
||||
1. Read VISUAL_INTEGRATION_MAP.md (10 min - see diagrams)
|
||||
2. Read IMPLEMENTATION_SUMMARY.md (5 min - understand approach)
|
||||
3. Follow INTEGRATION_GUIDE.md (10 min - step-by-step)
|
||||
4. Use bulk-import-code.tsx (5 min - copy code)
|
||||
Total: ~30 minutes
|
||||
```
|
||||
|
||||
## What Gets Added to App.tsx
|
||||
|
||||
| Section | Lines | What |
|
||||
|---------|-------|------|
|
||||
| Imports | 1 | FileSpreadsheet icon |
|
||||
| Hooks | 1 | Modal disclosure |
|
||||
| State | 5 | Import state variables |
|
||||
| Functions | ~200 | 5 handler functions |
|
||||
| UI Button | 4 | Bulk Import button |
|
||||
| UI Modal | ~155 | Full modal component |
|
||||
| **Total** | **~366** | **Complete feature** |
|
||||
|
||||
## Features Implemented
|
||||
|
||||
✅ **CSV Import** - Standard comma-separated format
|
||||
✅ **JSON Import** - Array of vector objects
|
||||
✅ **File Upload** - Direct file selection
|
||||
✅ **Text Paste** - Paste data directly
|
||||
✅ **Preview** - See first 5 vectors before import
|
||||
✅ **Progress Tracking** - Real-time import status
|
||||
✅ **Error Handling** - Validation and error recovery
|
||||
✅ **Auto-close** - Modal closes on success
|
||||
✅ **Dark Theme** - Matches dashboard styling
|
||||
✅ **Accessibility** - Keyboard navigation, screen readers
|
||||
|
||||
## Testing Your Implementation
|
||||
|
||||
### Step 1: Upload CSV
|
||||
```bash
|
||||
# In dashboard, click "Bulk Import Vectors"
|
||||
# Select "CSV" format
|
||||
# Upload docs/sample-bulk-import.csv
|
||||
# Click "Preview" - should show 5 vectors
|
||||
# Click "Import" - should import 8 vectors
|
||||
```
|
||||
|
||||
### Step 2: Upload JSON
|
||||
```bash
|
||||
# Click "Bulk Import Vectors"
|
||||
# Select "JSON" format
|
||||
# Upload docs/sample-bulk-import.json
|
||||
# Click "Preview" - should show 5 vectors
|
||||
# Click "Import" - should import 8 vectors
|
||||
```
|
||||
|
||||
### Step 3: Test Errors
|
||||
```bash
|
||||
# Try invalid CSV (no header)
|
||||
# Try invalid JSON (malformed)
|
||||
# Verify error messages appear
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Import button not visible
|
||||
- Check FileSpreadsheet icon imported (line ~78)
|
||||
- Check onBulkImportOpen defined (line ~527)
|
||||
- Check button added to Quick Actions (line ~1964)
|
||||
|
||||
### Modal not opening
|
||||
- Check useDisclosure hook added (line ~527)
|
||||
- Check isBulkImportOpen variable exists
|
||||
- Check modal component added (line ~2306)
|
||||
|
||||
### Preview fails
|
||||
- Check parseCsvVectors function added
|
||||
- Check parseJsonVectors function added
|
||||
- Check handleGeneratePreview function added
|
||||
|
||||
### Import fails
|
||||
- Check insertVectorWithId in dependency array
|
||||
- Check refreshVectors in dependency array
|
||||
- Check handleBulkImport function added
|
||||
|
||||
## Support Resources
|
||||
|
||||
1. **Integration Issues**
|
||||
- See `INTEGRATION_GUIDE.md` → Troubleshooting section
|
||||
- Check browser console for errors
|
||||
|
||||
2. **Code Questions**
|
||||
- See `bulk-import-code.tsx` → Commented code
|
||||
- See `BULK_IMPORT_IMPLEMENTATION.md` → Detailed explanations
|
||||
|
||||
3. **Architecture Questions**
|
||||
- See `VISUAL_INTEGRATION_MAP.md` → Flow diagrams
|
||||
- See `IMPLEMENTATION_SUMMARY.md` → Design decisions
|
||||
|
||||
4. **Testing Issues**
|
||||
- Use provided sample data files
|
||||
- Check logs in dashboard
|
||||
- Verify vector count updates
|
||||
|
||||
## Next Steps After Integration
|
||||
|
||||
1. **Test thoroughly**
|
||||
- Upload sample CSV
|
||||
- Upload sample JSON
|
||||
- Test error cases
|
||||
|
||||
2. **Customize** (optional)
|
||||
- Adjust styling to match your theme
|
||||
- Add custom validation rules
|
||||
- Modify progress display
|
||||
|
||||
3. **Extend** (optional)
|
||||
- Add export functionality
|
||||
- Add batch size limits
|
||||
- Add duplicate detection
|
||||
|
||||
## Questions?
|
||||
|
||||
Refer to:
|
||||
- `INTEGRATION_GUIDE.md` - How to integrate
|
||||
- `BULK_IMPORT_IMPLEMENTATION.md` - What code to add
|
||||
- `VISUAL_INTEGRATION_MAP.md` - Where things go
|
||||
- `bulk-import-code.tsx` - Code to copy
|
||||
|
||||
---
|
||||
|
||||
**Total Documentation**: 8 files
|
||||
**Total Code**: ~366 lines
|
||||
**Integration Time**: 10-30 minutes
|
||||
**Testing Time**: 5-10 minutes
|
||||
Reference in New Issue
Block a user