# AI Search Expanded File Support Phase 5: Google Workspace Export Prompt

**Status:** Implemented in the current working tree
**Priority:** Medium  
**Dependencies:** Phase 1 PDF, Phase 2 DOCX, Phase 3 XLSX, Phase 4 PPTX

---

## Implementation Summary

Phase 5 Google Workspace export is implemented for AI indexing only.

### What Was Implemented

**Core export + extraction:**

- Google Drive API `files.export()` integration for AI indexing
- Export-to-standard-format flow: Docs→DOCX, Sheets→XLSX, Slides→PPTX, Drawings→PDF
- Reuses existing DOCX/XLSX/PPTX/PDF extractors from Phases 2-4
- 30-second default export timeout with configurable override
- Original metadata preservation (name, mimeType, modifiedTime, size) while extracting from exported bytes
- No caching: fresh export per indexing run
- Typed `GoogleWorkspaceExportError` codes: `EXPORT_NETWORK`, `EXPORT_QUOTA_OR_PERMISSION`, `EXPORT_TIMEOUT`, `EXPORT_UNSUPPORTED_TYPE`, and `EXPORT_INVALID_PROVIDER`

**Files added:**

- `src/lib/search/ai/extraction/google-workspace-export.ts` — export helper with Drive API integration
- `src/lib/search/ai/extraction/google-workspace-export.test.ts` — unit tests (export logic)
- `src/lib/search/ai/extraction/extract-document-google-workspace.test.ts` — integration tests (export + extraction)
- `src/lib/search/ai/extraction/google-workspace-file-policies.ts` — Google Workspace policy definitions
- `src/lib/search/ai/indexing/backend-indexing-runner-google-workspace.test.ts` — runner tests (end-to-end)

**Files modified:**

- `src/lib/search/ai/extraction/extract-document.ts` — added Google Workspace detection + export branch
- `src/lib/search/ai/extraction/supported-file-policies.ts` — integrated Google Workspace policies
- `src/lib/search/ai/adapters/google-drive-indexing-adapter.ts` — export instead of download for Google Workspace files
- `README.md`, `public/docs/SEARCH_FEATURES.md`, `public/docs/PRIVACY_ARCHITECTURE.md`, `public/docs/API_REFERENCE.md`, `public/docs/developer/modules/AI_SEARCH_INDEXING_ADAPTERS.md`, `9.AI_Search_Plan_Consolidated_Implementation_Spec.md`

**Test coverage:**

- Focused Google Workspace, extraction, adapter, runner, policy, and taxonomy coverage passes
- Google Workspace-specific tests cover export, extraction, runner integration, typed errors, timeout, multi-account account IDs, metadata preservation, and maxBytes enforcement

**No dependency changes:**

- Reuses existing `googleapis` package
- Reuses existing OAuth/token infrastructure
- Reuses existing DOCX/XLSX/PPTX/PDF extractors

### Supported Cases

✅ **Google Docs** → DOCX export → text extraction  
✅ **Google Sheets** → XLSX export → visible cell value extraction  
✅ **Google Slides** → PPTX export → slide text + speaker notes extraction  
✅ **Google Drawings** → PDF export → embedded text extraction  
✅ **Multi-account Google Drive** via `accountId` parameter  
✅ **Original metadata preservation** (name, mimeType, modifiedTime, size)  
✅ **Configurable export timeout** (default 30s)  
✅ **Byte limit enforcement** against exported content before extraction

### Unsupported/Skipped Cases

❌ **Google Forms** → `unsupported` (no viable export format)  
❌ **Google Sites** → `unsupported` (no viable export format)  
❌ **Google Maps** → `unsupported` (no viable export format)  
❌ **Google Fusion Tables** → `unsupported` (no viable export format)
❌ **Google Jamboard** → `unsupported` (no viable export format)  
❌ **Google Apps Script** → `unsupported` (not user content)  
❌ **Google Shortcuts** → `unsupported` (not user content)  
❌ **Third-party Google Drive apps** → `unsupported` (no export access)  
❌ **Empty exported content** → `unsupported` (no extractable text after export)

### Failed Cases

⚠️ **Export timeout** (>30s default) → `failed` with `google_export_timeout`
⚠️ **Quota/permission errors** → `failed` with `google_export_quota_or_permission`
⚠️ **Network/provider failures** → `failed` with `google_export_network`
⚠️ **Unsupported Workspace type** → `failed` with `google_export_unsupported_type`
⚠️ **Non-Google providers** → `failed` with `google_export_invalid_provider`
⚠️ **Exported bytes over `maxBytes`** → `failed` with size limit error  
⚠️ **Extraction failures after export** → `failed` with format-specific error (DocxExtractionError, etc.)

### Architecture Decisions

**Export-based approach:**

- Google Workspace files are **native Google formats** that cannot be directly parsed
- Export to standard OpenXML/PDF formats before extraction
- Reuses existing extractors: no duplicate parsing logic

**No caching:**

- Each indexing run exports fresh content
- Ensures up-to-date content but increases API usage and latency
- Trade-off: correctness over performance

**Metadata preservation:**

- Original file metadata (name, mimeType, modifiedTime, size) preserved in indexed records
- Exported format metadata (DOCX/XLSX/PPTX/PDF) used only for extraction routing
- Users see "Google Docs" in search results, not "DOCX"

**Error handling:**

- Export failures → item-level `failed` status with sanitized error message
- Unsupported types → item-level `unsupported` status with reason
- Extraction failures → item-level `failed` status with format-specific error
- No fallback: if export succeeds but extraction fails, item is marked failed

### Known Limitations

1. **Export fidelity:** Complex Google Workspace files may lose formatting during export (charts, SmartArt, embedded objects)
2. **No caching:** Each indexing run exports fresh, increasing API usage and latency (1-5s per file)
3. **Quota limits:** Google Drive API has quota limits (1,000 requests per 100s per user); high-volume indexing may hit limits
4. **Timeout tuning:** 30s default may need adjustment for very large files (100+ page Docs, 50+ sheet Sheets, 100+ slide Slides)
5. **Shared Drive permissions:** May require additional OAuth scopes or permissions for Shared Drive files
6. **View-only restrictions:** Some Google Workspace files may have export restrictions based on sharing settings
7. **Exported size:** Exported content may exceed `maxBytes` even if original file metadata shows smaller size
8. **No fallback:** If extraction fails after successful export, item is marked failed (no retry with different format)

### Verification Results

```powershell
✅ pnpm env:guard — passed (WSL warning only)
✅ pnpm vitest run src/lib/search/ai/extraction/google-workspace-export.test.ts src/lib/search/ai/extraction/extract-document-google-workspace.test.ts src/lib/search/ai/adapters/google-drive-indexing-adapter.test.ts src/lib/search/ai/indexing/backend-indexing-runner-google-workspace.test.ts src/lib/search/ai/indexing/error-taxonomy.test.ts src/lib/search/ai/extraction/supported-file-policies.test.ts src/lib/search/ai/extraction/extract-document.test.ts — 77 tests passed (7 files)
✅ pnpm vitest run src/lib/search/ai/adapters/google-drive-indexing-adapter.test.ts — 6 tests passed (1 file)
✅ pnpm typecheck — passed
✅ pnpm exec eslint --config .eslintrc.json src/lib/search/ai/extraction src/lib/search/ai/indexing src/lib/search/ai/adapters — passed
✅ pnpm check — passed
✅ pnpm build — passed
✅ git diff --check — passed
✅ pnpm exec prettier --check [changed files] — passed
✅ pnpm audit --prod — no known vulnerabilities found
✅ git diff -- package.json pnpm-lock.yaml — no dependency changes
```

### Export Flow Diagram

```
Google Workspace File (native format)
         ↓
Detect Google Workspace MIME type
         ↓
Export via Drive API files.export()
  • Google Docs → DOCX
  • Google Sheets → XLSX
  • Google Slides → PPTX
  • Google Drawings → PDF
         ↓
Enforce maxBytes on exported content
         ↓
Route to existing extractor
  • DOCX → extractDocxText()
  • XLSX → extractXlsxText()
  • PPTX → extractPptxText()
  • PDF → extractPdfText()
         ↓
Return extraction result with original metadata
```

---

## Original Planning Prompt (Archived)

The prompt below is preserved for reproducibility.

<details>
<summary>Click to expand original prompt</summary>

```text
You are working in C:\code\stratofusion on Windows 11 PowerShell. Do not use WSL or bare bash. Use pnpm.

First:
- Run `git status --short` and inspect relevant `git diff`.
- If there are unrelated uncommitted changes, summarize them and ask before committing, overwriting, reverting, or cleaning them up.
- Do not commit user changes unless explicitly approved.
- Run `pnpm env:guard`.
- Read README.md and the relevant canonical docs under public/docs/ before coding.
- For this non-trivial feature, read public/docs/developer/AI_OPERATING_PROTOCOL.md and public/docs/prompts/INDEX.md before editing.
- Review existing Google Workspace export logic:
  - src/app/api/google-workspace/copy/route.ts (copy endpoint)
  - src/lib/download/google-export.ts (download helpers)
  - src/hooks/useGoogleWorkspaceCopy.ts (UI hook)
- Review AI indexing pipeline:
  - src/lib/search/ai/indexing/backend-indexing-runner.ts
  - src/lib/search/ai/extraction/extract-document.ts
  - src/lib/search/ai/extraction/supported-file-policies.ts
- Review existing extraction implementations:
  - src/lib/search/ai/extraction/docx-text.ts (Phase 2)
  - src/lib/search/ai/extraction/xlsx-text.ts (Phase 3)
  - src/lib/search/ai/extraction/pptx-text.ts (Phase 4)
- Follow the same extraction architecture: dedicated export module, typed export error, narrow policy routing, existing DOCX/XLSX/PPTX extractors, and byte-limit enforcement.

Goal: implement Expanded File Support Phase 5 for AI Search: Google Workspace export + extraction for AI indexing only.

Scope:
1. Add Google Workspace export helper in src/lib/search/ai/extraction/google-workspace-export.ts.
2. Add typed export error in src/lib/search/ai/extraction/google-workspace-export.ts.
3. Update src/lib/search/ai/extraction/extract-document.ts.
4. Add Google Workspace file policies in src/lib/search/ai/extraction/google-workspace-file-policies.ts.
5. Update src/lib/search/ai/extraction/supported-file-policies.ts.
6. Update src/lib/search/ai/adapters/google-drive-indexing-adapter.ts.
7. Add error taxonomy codes in src/lib/search/ai/indexing/error-taxonomy-catalog.ts.
8. Add comprehensive tests for export, extraction, runner behavior, taxonomy, and policies.
9. Update README.md, public/docs/SEARCH_FEATURES.md, public/docs/PRIVACY_ARCHITECTURE.md, public/docs/API_REFERENCE.md, public/docs/developer/modules/AI_SEARCH_INDEXING_ADAPTERS.md, and 9.AI_Search_Plan_Consolidated_Implementation_Spec.md.
10. Create prompt documentation at public/docs/prompts/ai-search-phase5-google-workspace-export.md and link it from public/docs/prompts/INDEX.md.

Supported Google Workspace inputs:
- Google Docs (application/vnd.google-apps.document) → export as DOCX
- Google Sheets (application/vnd.google-apps.spreadsheet) → export as XLSX
- Google Slides (application/vnd.google-apps.presentation) → export as PPTX
- Google Drawings (application/vnd.google-apps.drawing) → export as PDF

Unsupported Google Workspace types:
- Google Forms (application/vnd.google-apps.form)
- Google Sites (application/vnd.google-apps.site)
- Google Maps (application/vnd.google-apps.map)
- Google Apps Script (application/vnd.google-apps.script)
- Google Fusion Tables (application/vnd.google-apps.fusiontable)
- Google Jamboard (application/vnd.google-apps.jam)
- Any other Google Workspace types not explicitly supported

Export behavior:
- Use Drive API files.export() with the appropriate export MIME type.
- Return exported bytes as Buffer.
- Preserve original file metadata (name, mimeType, modifiedTime, size).
- Do not cache exported content.
- Enforce configurable export timeout (default: 30 seconds).
- Handle export errors and map to typed GoogleWorkspaceExportError.

Extraction routing after export:
- Google Docs → DOCX bytes → extractDocxText()
- Google Sheets → XLSX bytes → extractXlsxText()
- Google Slides → PPTX bytes → extractPptxText()
- Google Drawings → PDF bytes → extractPdfText()
- Enforce maxBytes on exported content before extraction.
- Preserve original metadata in extraction result.

Error handling:
- Export network failures → google_export_network (retryable)
- Export quota/permission errors → google_export_quota_or_permission (retryable after cooldown)
- Export timeout → google_export_timeout (retryable)
- Unsupported Google Workspace type → google_export_unsupported_type (not retryable)
- Invalid provider → google_export_invalid_provider (not retryable)
- Extraction failures after export → format-specific extraction codes

Deliverable:
- Do not commit unless the user explicitly asks for a commit or PR.
- Summarize changed files, export helper API/error codes, extraction routing changes, test coverage, verification command results, and remaining risks.
```

</details>

---

## Next Steps

Phase 5 is complete. Consider:

### 1. Monitor Production Usage

**Export performance:**

- Track export latency distribution (p50, p95, p99)
- Monitor export timeout rate
- Watch for quota limit errors

**Export success rates:**

- Track export success vs. failure by Google Workspace type
- Monitor quota/permission error frequency
- Watch for network timeout patterns

**Search quality:**

- Evaluate search relevance for Google Workspace content
- Compare Google Docs vs. DOCX search quality
- Monitor user feedback on Google Workspace search results

**API usage:**

- Track Google Drive API quota consumption
- Monitor export request volume
- Watch for quota limit warnings

### 2. Performance Optimization (Future)

**Caching strategy:**

- Consider caching exported content keyed by (fileId, modifiedTime)
- Trade-off: reduced API usage vs. storage cost
- Invalidate cache on file modification

**Parallel exports:**

- Consider parallel export for batch indexing
- Respect Google Drive API rate limits
- Monitor quota usage with parallel requests

**Timeout tuning:**

- Analyze export latency by file size and type
- Adjust timeout based on production data
- Consider dynamic timeout based on file size

### 3. Future Enhancements

**Additional Google Workspace types:**

- **Google Forms** → export to CSV/JSON (if API supports)
- **Google Sites** → export to HTML (if API supports)
- **Google Jamboard** → export to PDF (if API supports)

**Export format alternatives:**

- **Google Drawings** → SVG export (requires image text extraction)
- **Google Docs** → HTML export (may preserve more formatting)
- **Google Sheets** → CSV export (simpler but loses multi-sheet structure)

**Shared Drive support:**

- Test Shared Drive file export permissions
- Handle Shared Drive-specific quota limits
- Support Shared Drive-specific OAuth scopes

**View-only restrictions:**

- Detect and handle export-restricted files
- Provide clear error messages for restricted files
- Consider fallback to OCR for restricted PDFs

**Export retry logic:**

- Retry transient export failures (network, timeout)
- Exponential backoff for quota errors
- Circuit breaker for persistent failures

### 4. Follow-Up Phases

**Phase 6: OCR for scanned PDFs and image-only slides**

- Extract text from scanned PDFs using OCR
- Extract text from image-only PPTX slides
- Extract text from Google Drawings exported as PNG/SVG

**Phase 7: RTF/ODT support**

- RTF text extraction for legacy documents
- ODT text extraction for LibreOffice documents

**Phase 8: Legacy Office formats**

- Legacy PPT support (if demand exists)
- Legacy XLS support (if demand exists)
- Legacy DOC support (if demand exists)

**Phase 9: Advanced extraction**

- Image alt text extraction (PDF, DOCX, PPTX)
- Chart/table structure preservation
- Embedded object text extraction

---

## Related Documentation

- [AI Search Features](../SEARCH_FEATURES.md)
- [Privacy Architecture](../PRIVACY_ARCHITECTURE.md)
- [API Reference](../API_REFERENCE.md)
- [AI Search Indexing Adapters](../developer/modules/AI_SEARCH_INDEXING_ADAPTERS.md)
- [AI Search Implementation Spec](../developer/modules/AI_SEARCH_ARCHITECTURE.md)
- [PDF Extraction Status](../developer/modules/AI_SEARCH_ARCHITECTURE.md)
- [Phase 2: DOCX Extraction](./ai-search-phase2-docx-extraction.md)
- [Phase 3: XLSX Extraction](./ai-search-phase3-xlsx-extraction.md)
- [Phase 4: PPTX Extraction](./ai-search-phase4-pptx-extraction.md)

---

## Appendix: Export MIME Type Mappings

```typescript
// Source MIME → Export MIME
const GOOGLE_WORKSPACE_AI_EXPORTS = {
  "application/vnd.google-apps.document": {
    exportMimeType:
      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    extension: ".docx",
    googleWorkspaceType: "Google Docs",
  },
  "application/vnd.google-apps.spreadsheet": {
    exportMimeType:
      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    extension: ".xlsx",
    googleWorkspaceType: "Google Sheets",
  },
  "application/vnd.google-apps.presentation": {
    exportMimeType:
      "application/vnd.openxmlformats-officedocument.presentationml.presentation",
    extension: ".pptx",
    googleWorkspaceType: "Google Slides",
  },
  "application/vnd.google-apps.drawing": {
    exportMimeType: "application/pdf",
    extension: ".pdf",
    googleWorkspaceType: "Google Drawings",
  },
};
```

## Appendix: Error Messages

**Export timeout:**

```
Google Workspace export exceeded the 30000 ms timeout
```

**Quota/permission:**

```
Google Workspace export failed due to Drive API quota or permissions
```

**Network error:**

```
Google Workspace export failed due to a network or provider error
```

**Unsupported type:**

```
Google Forms files cannot be indexed for AI search
Google Sites files cannot be indexed for AI search
Google Maps files cannot be indexed for AI search
Google Fusion Tables files cannot be indexed for AI search
Google Jamboard files cannot be indexed for AI search
Google Apps Script files cannot be indexed for AI search
Google Shortcuts files cannot be indexed for AI search
Third-party Google Drive app files cannot be indexed for AI search
```

**Empty exported content:**

```
Google Workspace file exported successfully but contained no extractable text for AI indexing
```

**Non-Google provider:**

```
Google Workspace export requires Google Drive provider
```