ALTERNATIVE-APPROACH.md

Approach: Customize Guide Directly

This is now the primary approach! We've pivoted from reimplementing Guide to directly customizing Guide. Here's why and how:

Why Customize Guide Instead?

What Guide Already Has:

1. ✅ Full Embabel integration - All agent framework, RAG, search operations
2. ✅ ChatActions - Complete chat functionality with @Action triggers
3. ✅ DataManager - Has ingestDirectory(String dir) method that can index local directories
4. ✅ DrivineStore - Complete RAG infrastructure with vector search
5. ✅ WebSocket/SSE support - Full frontend integration
6. ✅ Embabel Hub frontend - Already integrated

What You'd Need to Change:

1. Configuration - Point to codebase directory instead of URLs
2. Data ingestion - Use ingestDirectory() instead of ingestPage() for URLs
3. Reference configuration - Point to codebase instead of docs

That's it! Everything else (RAG, chat, agent framework, frontend) stays the same.

How to Customize Guide

Option 1: Fork and Customize Guide

1. Fork Guide repository:

   git clone https://github.com/embabel/guide.git
   cd guide

2. Modify GuideProperties to support codebase path:

   public record GuideProperties(
       String referencesFile,
       List<String> urls,  // Keep for docs
       String codebasePath,  // ADD: Your codebase path
       boolean useCodebase   // ADD: Toggle between docs and codebase
   ) {}

3. Modify DataManager.loadReferences():

   public void loadReferences() {
       if (guideProperties.useCodebase() && guideProperties.codebasePath() != null) {
           // Use codebase directory
           logger.info("⏳Loading codebase from: {}...", guideProperties.codebasePath());
           ingestDirectory(guideProperties.codebasePath());
           logger.info("✅ Loaded codebase from: {}", guideProperties.codebasePath());
       } else {
           // Original URL-based ingestion
           for (var url : guideProperties.urls()) {
               ingestPage(url);
           }
       }
   }

4. Configuration - Update application.yml:

   guide:
     codebase-path: /path/to/your/codebase
     use-codebase: true
     urls: []  # Empty for codebase mode

Option 2: Extend Guide as a Library

1. Use Guide as a dependency:

   <dependency>
       <groupId>com.embabel.agent</groupId>
       <artifactId>guide</artifactId>
       <version>0.1.0-SNAPSHOT</version>
   </dependency>

2. Override DataManager to use codebase:

   @Service
   @Primary
   public class CodebaseDataManager extends DataManager {
       @Override
       public void loadReferences() {
           // Use ingestDirectory() for your codebase
           ingestDirectory("/path/to/codebase");
       }
   }

3. Keep all Guide components - ChatActions, frontend, everything

Comparison: Customize vs Reimplement

Aspect	Customize Guide	Reimplement (Current)
Complexity	Very Low	High
Maintenance	Low (upstream updates)	High (maintain everything)
Features	All Guide features	Need to implement
Frontend	Already integrated	Need to integrate
RAG Infrastructure	Already working	Need to build
Time to Value	Fast	Slow
Customization	Minimal changes needed	Full control but more work

Recommendation

Definitely customize Guide! Here's why:

1. Guide already has ingestDirectory() - It can index local directories
2. Minimal changes needed - Just configuration and maybe DataManager
3. All features included - RAG, chat, frontend, WebSockets
4. Easy to maintain - Pull upstream updates from Guide
5. Proven code - Guide is battle-tested

What to Change in Guide

Minimal Changes Needed:

1. GuideProperties.java - Add codebase path configuration
2. DataManager.java - Modify loadReferences() to use ingestDirectory() for codebase
3. application.yml - Configure codebase path instead of URLs

That's literally it! Everything else (ChatActions, RAG store, frontend, agent framework) works as-is.

Implementation Path

1. Copy Guide to your repo or fork it
2. Add codebase configuration to GuideProperties
3. Use ingestDirectory() instead of ingestPage()
4. Configure path in application.yml
5. Done! Everything else works

This would give you the same "talk to docs" experience but for your codebase, with minimal code changes.

---

Conclusion: You're right to question this. Customizing Guide is definitely the better approach than reimplementing. The current project structure could serve as documentation of what needs to be customized, or you could pivot to directly customizing Guide instead.