Talk to Your Repo

A working setup for using Embabel Guide to enable "talk to your codebase" functionality. This repository documents the workarounds and configuration needed to get Guide working with custom repository URLs.

✅ It Works!

The screenshot above demonstrates Guide successfully answering questions about the datadog-drilldown repository, proving the setup works correctly.

Overview

Goal: Customize Embabel Guide to work with your own repository URLs instead of (or in addition to) the default documentation URLs.

Current Status: ✅ Working with workarounds documented below

Prerequisites

• Java 21+
• Maven 3.6+
• Neo4j (running on localhost:7687)
• Node.js and npm (for frontend)

Required Workarounds

During setup, we discovered several workarounds needed to get Guide working properly:

1. Component Scan Fix

Problem: ChatActions class (which contains the @Action method for responding to messages) wasn't being discovered by Guide's ComponentConfiguration, even though it was annotated with @EmbabelComponent.

Solution: Added explicit @ComponentScan annotation to GuideApplication.java:

@SpringBootApplication
@ComponentScan(basePackages = {"com.embabel"})  // ← REQUIRED WORKAROUND
@ConfigurationPropertiesScan
@EnableScheduling
@EnableDrivine
@EnableDrivinePropertiesConfig
public class GuideApplication {
    // ...
}

File: guide/src/main/java/com/embabel/GuideApplication.java

Why: Tests work because TestAppContext has this annotation. The main application needs it too for Spring to discover components in com.embabel.guide package.

2. Port Conflicts

Problem: Port 1337 may be in use by a Docker container or previous Guide instance.

Solution: Check and stop any processes using port 1337:

# Check what's using port 1337
docker ps | grep guide
lsof -ti:1337

# Stop Docker container if running
docker stop embabel-guide

# Or kill processes
pkill -f "spring-boot:run"
lsof -ti:1337 | xargs kill -9

3. Frontend Configuration

Problem: Frontend needs to connect to the correct Guide instance port.

Solution: Configure frontend to use port 1337:

// frontend/src/App.js
const API_BASE_URL = process.env.REACT_APP_API_BASE_URL || 'http://localhost:1337';

Setup Instructions

1. Clone and Build Guide

git clone https://github.com/embabel/guide.git
cd guide
mvn clean install

2. Apply Component Scan Fix

Edit src/main/java/com/embabel/GuideApplication.java and ensure it has:

@ComponentScan(basePackages = {"com.embabel"})

3. Configure Repository URLs

Edit src/main/resources/application.yml to add your repository URLs:

guide:
  urls:
    - https://docs.embabel.com/embabel-agent/guide/0.3.1-SNAPSHOT/  # Default docs
    - https://github.com/menkelabs/datadog-drilldown                 # Your repo
    # Add more URLs here

4. Start Neo4j

Ensure Neo4j is running (default: localhost:7687):

# Using Docker
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/brahmsian \
  neo4j:latest

# Or use existing Neo4j instance

5. Start Guide

cd guide
mvn spring-boot:run

Guide will start on port 1337 by default. Check logs:

tail -f guide.log

Look for:

• Started GuideApplication
• Tomcat started on port 1337
• ComponentConfiguration initialized

6. Start Frontend (Optional)

cd frontend
npm install
npm start

Frontend will start on http://localhost:3000 and connect to Guide on port 1337.

Adding a New Repository URL

To add a new repository or documentation URL to Guide:

Option 1: Add to Main Configuration

Edit guide/src/main/resources/application.yml:

guide:
  urls:
    - https://docs.embabel.com/embabel-agent/guide/0.3.1-SNAPSHOT/
    - https://github.com/menkelabs/datadog-drilldown
    - https://github.com/yourusername/your-repo  # ← Add your new URL here

Option 2: Use Profile-Specific Configuration

Create or edit guide/src/main/resources/application-custom.yml:

server:
  port: 1337

guide:
  urls:
    - https://github.com/yourusername/your-repo-1
    - https://github.com/yourusername/your-repo-2

logging:
  level:
    com.embabel.agent.rag: INFO
    com.embabel.guide.chat: DEBUG

Run with profile:

mvn spring-boot:run -Dspring-boot.run.profiles=custom

Option 3: Add URLs Without Removing Existing

Edit application.yml and append to the urls list:

guide:
  urls:
    # Existing URLs
    - https://docs.embabel.com/embabel-agent/guide/0.3.1-SNAPSHOT/
    - https://medium.com/@springrod/build-better-agents-in-java-vs-python-embabel-vs-langgraph-f7951a0d855c
    
    # Add new URLs here (without removing existing ones)
    - https://github.com/menkelabs/datadog-drilldown
    - https://github.com/yourusername/another-repo

Reloading Content

By default, Guide only reloads content from snapshots. To reload from URLs on startup:

guide:
  reload-content-on-startup: true  # ← Set to true to reload URLs on startup

Note: Content ingestion happens on first access or when reload-content-on-startup: true. This may take several minutes for large repositories.

Testing the Setup

1. Start Guide: mvn spring-boot:run in the guide directory
2. Open Frontend: Navigate to http://localhost:3000 (or use Guide's built-in frontend)
3. Send Test Message: Try asking "what is datadog-drilldown" or any question about your repository
4. Check Logs: Look for ChatActions.respond being called in the logs

Verify Component Discovery

Check logs for:

ComponentConfiguration initialized: Scanning com.embabel.agent and com.embabel.example packages.

Even though it says "com.embabel.example", with the @ComponentScan fix, ChatActions in com.embabel.guide will be discovered via Spring's ApplicationContext.

Verify URL Ingestion

Check logs for ingestion messages or query Neo4j:

MATCH (n:ContentChunk) 
RETURN count(n) as total_chunks

Troubleshooting

"no available actions to progress"

Cause: ChatActions not being discovered.

Fix: Ensure @ComponentScan(basePackages = {"com.embabel"}) is in GuideApplication.java.

Port 1337 already in use

Fix:

docker stop embabel-guide  # If Docker container
pkill -f "spring-boot:run"  # If Maven process
lsof -ti:1337 | xargs kill -9  # Force kill

Frontend not receiving responses

Check:

1. Frontend is connecting to http://localhost:1337
2. Guide is running and responding to /api/hub/personas
3. WebSocket connection is established (check browser console)
4. ChatActions is discovered (check Guide logs)

Content not being ingested

Check:

1. URLs are valid and accessible
2. reload-content-on-startup: true is set, or manually trigger ingestion
3. Neo4j is running and accessible
4. Check Guide logs for ingestion errors

Architecture

┌─────────────────┐
│   React         │
│   Frontend      │
│   (Port 3000)   │
└────────┬────────┘
         │ WebSocket/STOMP
         │
┌────────▼────────┐
│   Guide         │
│   (Port 1337)   │
│                 │
│  ┌───────────┐  │
│  │ChatActions│  │  ← Requires @ComponentScan fix
│  │@Action    │  │
│  └───────────┘  │
│                 │
│  ┌───────────┐  │
│  │DataManager│  │  ← Ingests URLs
│  └───────────┘  │
└────────┬────────┘
         │
┌────────▼────────┐
│   Neo4j         │
│   (Port 7687)   │
│                 │
│  RAG Store      │
│  Content Chunks │
└─────────────────┘

Key Files

• guide/src/main/java/com/embabel/GuideApplication.java - Main application (requires @ComponentScan fix)
• guide/src/main/java/com/embabel/guide/ChatActions.java - Action handler for chat messages
• guide/src/main/resources/application.yml - Main configuration (add URLs here)
• frontend/src/App.js - React frontend (configured for port 1337)

Known Issues

1. ComponentConfiguration log message: Logs still say "Scanning com.embabel.agent and com.embabel.example packages" but this is just the log message. With @ComponentScan, components are discovered from Spring's ApplicationContext.

2. Port conflicts: If you have a Docker container running Guide, it will block port 1337. Always check docker ps first.

3. Content ingestion time: Large repositories can take several minutes to ingest. Be patient on first startup.

Success Criteria

✅ Guide starts without errors
✅ Port 1337 is listening
✅ ChatActions is discovered (check logs for incoming requests)
✅ Frontend connects and sends/receives messages
✅ Guide responds to questions about your repository
✅ Neo4j contains ingested content chunks

Example: datadog-drilldown Setup

As shown in the screenshot above, here's how we configured Guide for the datadog-drilldown repository:

1. Added URL to configuration:

   guide:
     urls:
       - https://github.com/menkelabs/datadog-drilldown

2. Applied Component Scan fix (see workaround #1 above)

3. Started Guide and waited for ingestion

4. Tested with query: "what is datadog-drilldown"

5. Verified response: Guide correctly identified it as a project involving "Embabel and DICE for Root Cause Analysis (RCA) with Datadog"

License

[Add your license here]

References

• Embabel Guide - Original Guide repository
• Embabel Agent Framework - Core agent framework
• Embabel Documentation - Official documentation