AI-powered speaker discovery platform built on a knowledge graph of 70,000+ professional speakers.
SpeakerScout lets event organizers find the right speaker through natural language conversation. Ask questions like "Find me a female AI speaker under $10K in New York" and get curated recommendations backed by a Neo4j knowledge graph with 13 node types, 15 relationship types, and 70,000+ speakers.
The system uses a LangGraph ReAct agent that generates Cypher queries, self-corrects on errors, handles multi-criteria searches, and streams responses in real time via Server-Sent Events.
- Conversational AI Search — Natural language queries powered by a LangGraph ReAct agent with streaming responses
- Knowledge Graph — Neo4j graph with 13 node types and 15 relationship types, built from a hybrid ETL pipeline (deterministic mapping + LLM extraction)
- Interactive Graph Explorer — Force-directed visualization of the speaker knowledge graph with drill-down navigation
- Speaker Directory — Searchable catalog with 12 filters (topic, location, language, fee range, rating, gender, engagement type, and more)
- Graph Analytics — Real-time analytics showing graph statistics, topic distribution, and node/relationship breakdowns
- Public Landing Page — Showcases features, architecture, and tech stack for unauthenticated visitors
- 5-Layer Security — Input sanitization, prompt injection detection, off-topic filtering, Cypher allowlist validation, and output sanitization
- Full-Stack Authentication — Clerk-based auth on both frontend (middleware) and backend (JWT verification)
- Production Deployment — Docker Compose for local development, EC2 deployment script, AWS Amplify for frontend
graph LR
subgraph Data
A[(MongoDB<br/>70K+ speakers)] -->|Hybrid ETL| B[(Neo4j<br/>Knowledge Graph)]
end
subgraph Backend
C[FastAPI API] --> D[Guardrails<br/>5-layer security]
D --> E[LangGraph<br/>ReAct Agent]
E -->|Cypher queries| B
E -->|SSE stream| C
end
subgraph Frontend
F[Next.js 16] --> G[Chat UI]
F --> H[Graph Explorer]
F --> I[Speaker Directory]
F --> J[Graph Analytics]
end
C -->|REST + SSE| F
K[Clerk Auth] --> C
K --> F
| Step | Component | What Happens |
|---|---|---|
| 1. Ingest | ETL Pipeline | 70K+ speaker documents from MongoDB are mapped into Neo4j via deterministic field mapping (all structured data) and optional LLM extraction (relationship discovery from unstructured bios) |
| 2. Query | LangGraph Agent | User's natural language question passes through 5 guardrail layers, then a ReAct agent generates Cypher queries, executes them against Neo4j, self-corrects on errors, and synthesizes a natural language answer |
| 3. Stream | FastAPI + SSE | The agent's response streams token-by-token to the frontend via Server-Sent Events, with real-time status updates |
| 4. Display | Next.js Frontend | Chat UI renders the streamed response with clickable speaker names, profile panels, and an interactive knowledge graph explorer |
Try it: https://main.duyg3yq8kf94d.amplifyapp.com
The landing page is public — no sign-up required to explore the product. Sign up to access the full platform.
|
Landing Page (public)
|
Features Showcased on Landing
|
| Page | What It Does |
|---|---|
| Chat | Ask natural language questions, get streaming speaker recommendations with clickable profiles |
| Graph Explorer | Interactive force-directed visualization — click topics to discover speakers, click speakers to see their network |
| Speaker Directory | Browse 70,000+ speakers with 12 filters (topic, location, fee, rating, language, gender, and more) |
| Speaker Profile | Full profile with biography, videos, reviews, credentials, and an ego-graph visualization |
| Graph Analytics | Real-time stats — top topics bar chart, node/relationship distribution pie charts |
| How It Works | Architecture pipeline, security layers, live graph statistics, tech stack |
- Docker and Docker Compose
- Node.js 18+
- MongoDB instance with speaker data
- API key for Gemini or OpenRouter
git clone https://github.com/shafigill16/speakers-graph-rag.git
cd speakers-graph-rag
cp backend/.env.example backend/.env
# Edit backend/.env with your credentialscd backend
docker compose up -d # Starts Neo4j
pip install -r requirements.txt
python -m etl.run_etl --clean --skip-llm # Load speakers into Neo4j
uvicorn api.main:app --reload # Start API servercd frontend
npm install
echo "NEXT_PUBLIC_BACKEND_URL=http://localhost:8000" > .env.local
npm run devOpen http://localhost:3000 and start searching for speakers.
speakers-graph-rag/
├── backend/
│ ├── api/ # FastAPI application
│ │ ├── main.py # App factory, lifespan, route registration
│ │ ├── auth.py # Clerk JWT authentication
│ │ ├── models.py # Pydantic request/response models
│ │ ├── dependencies.py # Dependency injection
│ │ └── routes/ # API endpoints
│ │ ├── query.py # Natural language query + SSE streaming
│ │ ├── speakers.py # Speaker search and detail
│ │ ├── graph.py # Graph stats, topics, schema
│ │ ├── lookups.py # Language, location, engagement type lookups
│ │ └── health.py # Health check
│ ├── etl/ # Data pipeline
│ │ ├── pipeline.py # ETL orchestrator (deterministic + LLM phases)
│ │ ├── field_mapper.py # MongoDB → Neo4j deterministic mapping
│ │ ├── graph_extractor.py # LLM-based relationship extraction
│ │ ├── document_builder.py # Document construction for LLM
│ │ ├── graph_ingest.py # Neo4j graph document ingestion
│ │ ├── mongo_reader.py # MongoDB reader with pagination
│ │ └── run_etl.py # CLI entry point
│ ├── graphrag/ # Query engine
│ │ ├── query_engine.py # LangGraph ReAct agent orchestration
│ │ ├── agent_tools.py # Cypher execution tool
│ │ ├── agent_prompts.py # Agent system prompt with schema
│ │ ├── cypher_chain.py # Cypher cleaning and write rejection
│ │ ├── llm_provider.py # LLM provider factory (Gemini, OpenRouter)
│ │ ├── neo4j_graph.py # Neo4j connection management
│ │ ├── prompts.py # Cypher generation and QA prompts
│ │ └── guardrails/ # 5-layer security system
│ │ ├── input_guards.py # Sanitization, injection, off-topic
│ │ ├── cypher_validator.py # Tokenizer-based Cypher allowlist
│ │ ├── output_guards.py # Answer sanitization, error masking
│ │ ├── prompt_hardening.py # Security preamble for system prompt
│ │ ├── config.py # Feature flags (9 toggles)
│ │ └── exceptions.py # Custom guardrail exceptions
│ ├── tests/ # 17 test files, 300+ test cases
│ ├── config/settings.py # Pydantic settings with validation
│ ├── Dockerfile
│ ├── docker-compose.yml
│ └── deploy.sh # EC2 deployment script
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js 16 pages
│ │ │ ├── page.tsx # Public landing page
│ │ │ ├── chat/ # AI chat interface (protected)
│ │ │ ├── explore/ # Knowledge graph explorer
│ │ │ ├── dashboard/ # Graph analytics
│ │ │ ├── speakers/ # Speaker directory + profiles
│ │ │ ├── how-it-works/ # Architecture explanation
│ │ │ └── sign-in/, sign-up/ # Clerk auth pages
│ │ ├── components/
│ │ │ ├── chat/ # Chat UI (streaming, sidebar, profiles)
│ │ │ ├── graph/ # Graph visualization (force-directed)
│ │ │ ├── dashboard/ # Charts and stats cards
│ │ │ ├── speakers/ # Speaker cards, filters, profiles
│ │ │ ├── how-it-works/ # Architecture diagrams
│ │ │ └── layout/ # Navbar, footer
│ │ └── lib/ # API client, hooks, types, utilities
│ └── package.json
└── docs/ # Documentation
├── architecture.md
├── guardrails.md
├── etl-pipeline.md
├── api-reference.md
└── deployment.md
| Document | Description |
|---|---|
| Architecture | System design, component breakdown, knowledge graph schema, data flow diagrams |
| Guardrails | 5-layer security system: input validation, injection detection, Cypher allowlisting, output sanitization |
| ETL Pipeline | Data pipeline: MongoDB to Neo4j via deterministic mapping + LLM extraction |
| API Reference | All 11 endpoints with request/response schemas and SSE streaming protocol |
| Deployment | Local development, Docker, EC2 deployment, environment variables |
| Layer | Technologies |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS, Radix UI, Recharts, react-force-graph-2d |
| Backend | Python 3.10+, FastAPI, Pydantic v2, Uvicorn |
| AI/LLM | LangChain, LangGraph (ReAct agent), Gemini 2.5 Flash, OpenRouter |
| Database | Neo4j 5.15 (knowledge graph), MongoDB (source data) |
| Auth | Clerk (frontend middleware + backend JWT verification) |
| Infrastructure | Docker, Docker Compose, AWS EC2, AWS Amplify |
| Testing | pytest, httpx, 17 test files, 300+ test cases |
This project is for portfolio and demonstration purposes.