An intelligent agent that matches Bluesky posts expressing volunteering intent with NYC volunteering opportunities using AI-powered intent detection and local vector embeddings for semantic search.
The latest version uses OpenAI's GPT-4 for intelligent intent detection:
- 🧠 Smart Intent Detection: Uses GPT-4o-mini to analyze batches of posts
- 🎯 Semantic Query Extraction: AI extracts the perfect search query from each post
- 📦 Batch Processing: Analyzes 30 seconds of posts at a time for efficiency
- 🔍 Local Vector Matching: Uses local embeddings for fast, offline matching
- 💰 Cost Effective: Batching reduces API calls (~$0.001 per 100 posts)
- 🎨 Higher Precision: Better intent detection than keyword matching
Fully offline version with keyword-based detection:
- 📚 Vectorizes opportunities using local AI model (no API needed!)
- 🎯 Keyword-based intent detection
- ⚡ Runs completely offline once embeddings are generated
- Node.js 18+ installed
- OpenAI API key (for OpenAI version)
- ~2GB free disk space (for embedding model on first run)
- Install dependencies:
npm install- Configure API key (for OpenAI version):
cp .env.example .envEdit .env and add your OpenAI API key:
OPENAI_API_KEY=your_openai_api_key_here
OpenAI-powered version (recommended):
node volunteer-matcher-openai.jsLocal-only version:
node volunteer-matcher-local.jsFirst run: The agent will download the embedding model (~90MB) and vectorize all opportunities (~30 seconds)
Subsequent runs: Loads vectors from disk instantly (<1 second)
The agent will:
- Load or create local vector database with all 15 opportunities
- Connect to Bluesky Jetstream
- Collect posts in 30-second batches (OpenAI version) or process in real-time (local version)
- Detect volunteering intent (AI or keywords)
- Match posts with relevant opportunities using vector search
- Save matches to
matches.json
.
├── volunteer-matcher-openai.js # OpenAI + local vectors (RECOMMENDED)
├── volunteer-matcher-local.js # Fully local with keywords
├── volunteer-matcher.js # Alternative: Senso API version
├── vector-db.js # Local vector database implementation
├── jetstream.js # Standalone Jetstream viewer
├── volunteering.json # 15 NYC volunteering opportunities
├── vector-db.json # Generated: vectorized opportunities
├── matches.json # Generated: matched posts
├── package.json # Node.js dependencies
├── .env # API keys (create from .env.example)
└── README.md # This file
Uses Xenova/all-MiniLM-L6-v2 (a lightweight 80MB embedding model) to convert each opportunity into a 384-dimensional vector:
"City Harvest - Food Rescue & Distribution" → [0.023, -0.145, 0.891, ...]
The vectors capture semantic meaning, allowing similarity matching even when exact keywords don't match.
- Collects all posts from Jetstream for 30 seconds
- Typical batch size: 50-150 posts per batch
- Batches sent to OpenAI for analysis
OpenAI analyzes the entire batch and for each post:
- Detects volunteering intent with confidence score
- Extracts semantic search query optimized for vector matching
- Returns structured JSON with results for all posts
Example OpenAI output:
{
"results": [
{
"post_index": 0,
"has_volunteering_intent": true,
"search_query": "animal shelter dog walking weekend Manhattan",
"confidence": 0.92
}
]
}For posts with detected intent:
- Use the AI-generated search query (not the original post text)
- Generate embedding for the optimized query
- Calculate cosine similarity with all 15 opportunity vectors
- Return top 3 matches sorted by relevance score
Example:
- Post: "I want to help dogs in NYC"
- Top match: "Animal Haven - Dog Walking" (85% similarity)
Matches are saved with complete metadata:
{
"timestamp": "2025-10-04T19:30:00.000Z",
"post": {
"text": "Looking to volunteer with kids in Brooklyn...",
"author_did": "did:plc:abc123...",
"post_uri": "at://did:plc:abc123.../app.bsky.feed.post/xyz",
"post_url": "https://bsky.app/profile/did:plc:abc123.../post/xyz"
},
"matches": [
{
"title": "826 NYC - Writing & Tutoring",
"organization": "826 NYC",
"category": "Education & Youth",
"borough": "Brooklyn",
"relevance_score": 0.72,
"contact": {...}
}
],
"ai_summary": "Based on your interest, here are relevant volunteering opportunities..."
}The dataset includes opportunities across 5 categories:
- Community & Social Services (6 opportunities)
- Education & Youth (4 opportunities)
- Environment & Parks (3 opportunities)
- Animals & Wildlife (2 opportunities)
- Health & Medical (1 opportunity)
Modify volunteering keywords in volunteer-matcher-local.js:
const VOLUNTEERING_KEYWORDS = [
'volunteer', 'volunteering', 'help out',
// Add your own keywords here
];Adjust match limit in vector-db.js:
async search(queryText, topK = 3) { // Change topK for more/fewer matchesForce re-vectorization (if you update volunteering.json):
rm vector-db.json
node volunteer-matcher-local.js🤖 Volunteer Matching Agent Starting...
================================================================================
🔧 Initializing embedding model...
✅ Embedding model ready!
📂 Loading existing vector database...
✅ Loaded 15 opportunities from disk
📅 Last updated: 2025-10-04T19:15:30.000Z
🌊 Connecting to Bluesky Jetstream...
📊 Stats will update every 100 posts
================================================================================
📈 Processed 100 posts | Found 0 volunteering posts
📈 Processed 200 posts | Found 0 volunteering posts
================================================================================
🎯 VOLUNTEERING INTENT DETECTED!
================================================================================
👤 Author: did:plc:xyz789...
📝 Post: I'd love to volunteer at an animal shelter this weekend
🔗 URI: at://did:plc:xyz789.../app.bsky.feed.post/abc
🔗 URL: https://bsky.app/profile/did:plc:xyz789.../post/abc
🔍 Searching for: "I'd love to volunteer at an animal shelter this weekend..."
✅ Found 3 matches
💡 AI Summary:
Based on your interest, here are relevant volunteering opportunities in
Animals & Wildlife. The best match is "ASPCA - Animal Care Assistance"
with ASPCA in Manhattan.
📋 Top Matches:
1. ASPCA - Animal Care Assistance
🏢 ASPCA
📍 Manhattan | Animals & Wildlife
🎯 Relevance: 78.2%
⏰ 4 hours per week, 6-month commitment
📧 volunteer@aspca.org
2. Animal Haven - Dog Walking & Cat Socialization
🏢 Animal Haven
📍 Manhattan | Animals & Wildlife
🎯 Relevance: 75.8%
⏰ 2-3 hours per week
📧 volunteer@animalhavenshelter.org
3. GrowNYC - Community Garden Support
🏢 GrowNYC
📍 All boroughs | Environment & Parks
🎯 Relevance: 42.1%
⏰ 2-4 hours, flexible
📧 volunteer@grownyc.org
================================================================================
"Command not found: node"
- Install Node.js from nodejs.org
"Connection closed"
- The agent auto-reconnects to Jetstream after 5 seconds
- Check your internet connection
Model download is slow
- First run downloads ~90MB model from HuggingFace
- Subsequent runs use cached model (no download needed)
Getting too many false positives
- Adjust the keyword list to be more specific
- Increase minimum relevance score threshold in the code
@xenova/transformers- Local AI embeddings (runs in Node.js, no GPU needed)ws- WebSocket client for Jetstream
Embedding Model: Xenova/all-MiniLM-L6-v2
- 384-dimensional vectors
- Trained on 1 billion sentence pairs
- Optimized for semantic similarity
- Runs entirely locally (CPU-only, no GPU needed)
Vector Database:
- Simple JSON file storage
- Cosine similarity search
- O(n) search complexity (fine for 15 items)
- For larger datasets, consider using a proper vector DB (Pinecone, Qdrant, etc.)
- Automatic reply bot to post opportunities
- User preference tracking
- Geographic filtering (only match with user's borough)
- Schedule-based filtering (match availability)
- Multi-language support
- Web dashboard for matches
- Upgrade to proper vector DB for scale (Qdrant, Weaviate)
- Fine-tune embedding model on volunteering-specific data
MIT
This is a hackathon project. Feel free to fork and improve!
Built with ❤️ for connecting volunteers with NYC opportunities