Event Concierge Agent 2.0

An intelligent event discovery system powered by Hugging Face transformers and MCP protocol.

Two Versions Available:

• Classic (v1.0): spaCy + web scraping (fast, simple)
• Enhanced (v2.0): HF transformers + semantic search + MCP (accurate, powerful)

Features

Classic Version (v1.0)

• Natural Language Understanding: spaCy NER for entity extraction
• Web Search Integration: SerpAPI for finding event pages
• Smart Scraping: JSON-LD + heuristic extraction
• REST API: FastAPI service

Enhanced Version (v2.0) ⭐ NEW

• Advanced NLP: Hugging Face transformers (BART, BERT, DistilBERT)
• Intent Classification: Zero-shot learning for query understanding
• QA-Based Extraction: Extract events from messy HTML using question-answering
• Semantic Ranking: Sentence transformers for relevance scoring
• Semantic Deduplication: Embedding-based duplicate detection
• MCP Protocol: Expose capabilities as orchestratable tools

Architecture

User Query → NLP Parser → Search Query Builder → Web Search API → 
  → Web Scraper → Event Extractor → Structured Results

Quick Start

Classic Version

# 1. Install
pip install -r requirements.txt  # Classic deps only
python -m spacy download en_core_web_sm

# 2. Configure
cp env.example .env
# Edit .env: SERP_API_KEY=your_key_here

# 3. Run
python app.py  # Classic API
# OR
python example.py "Find AI meetups in Boston"

Enhanced Version ⭐

# 1. Install (includes HF transformers)
pip install -r requirements.txt  # ~2GB of models will download

# 2. Configure (same as classic)
cp env.example .env

# 3. Run
python app_enhanced.py  # Enhanced API with HF models
# OR
python event_finder_enhanced.py  # Enhanced CLI
# OR
python mcp_server.py  # MCP server for tool orchestration

The enhanced version downloads models automatically on first use (~2GB, ~60s)

Usage

Command Line

python example.py "Find AI meetups in Boston this weekend"

API

curl -X POST "http://localhost:8000/events" \
  -H "Content-Type: application/json" \
  -d '{"text": "Find AI meetups in Boston this weekend"}'

Python Client

from event_finder import EventFinder

finder = EventFinder()
events = finder.find_events("Find hackathons in NYC in December")

for event in events:
    print(f"{event['title']} - {event['start_date']}")
    print(f"Register: {event['register_url']}\n")

Project Structure

events-extract/
├── requirements.txt          # Python dependencies
├── README.md                # This file
├── .env                     # Environment variables (create this)
├── app.py                   # FastAPI web service
├── event_finder.py          # Main orchestrator
├── nlp_parser.py            # Query parsing logic
├── search_client.py         # Web search integration
├── event_scraper.py         # Web scraping and extraction
└── example.py               # Example usage script

Components

1. NLP Parser (nlp_parser.py)

• Uses spaCy for named entity recognition
• Extracts locations (cities, countries)
• Identifies date/time expressions
• Isolates topic keywords

2. Search Client (search_client.py)

• Builds search queries from parsed slots
• Integrates with SerpAPI (Google, Bing, etc.)
• Returns candidate URLs with snippets

3. Event Scraper (event_scraper.py)

• Fetches and parses HTML content
• Extracts JSON-LD structured data (schema.org/Event)
• Falls back to heuristic-based extraction
• Normalizes event data into standard format

4. Event Finder (event_finder.py)

• Orchestrates the entire pipeline
• Filters and deduplicates results
• Handles errors gracefully

Example Queries

• "Find AI meetups in Boston this weekend"
• "Python conferences in San Francisco in December"
• "Hackathons in NYC next month"
• "Machine learning workshops in London"
• "Tech events in Seattle this week"

Improvements Roadmap

• Better date range normalization
• Event deduplication by title similarity
• Ranking by relevance and date proximity
• Caching for popular queries
• Support for online vs in-person filtering
• Multi-location support
• Custom site-specific scrapers (Meetup, Eventbrite)
• User preference learning

License

MIT License - Feel free to use and modify for your projects!