🔍 Event Scout AI — Autonomous Tech Event Research Agent

Event Scout AI is a state-of-the-art autonomous research agent designed to discover, scrape, extract, validate, deduplicate, and digest upcoming tech events, hackathons, conferences, and startup meetups.

Powered by Google Gemini, LangGraph, FastAPI, and React + TypeScript, Event Scout AI brings complete automation and deep observability to event discovery.

---

✨ Key Features

• 🧠 Intelligent Intent Planning: Uses Google Gemini to analyze search criteria (cities, domains, look-ahead timeframe) and construct precise search intents.
• 🌐 Multi-Platform Scrapers & Search Fallback: Direct scraping support for major event platforms (Meetup, Eventbrite, Devfolio, Unstop) with dynamic DuckDuckGo fallback for maximum discovery breadth.
• 🤖 LLM-Based Validation & Semantic Deduplication: Employs structured Pydantic schemas via Gemini to validate domain relevance (e.g. software, AI, tech startups), correct/assign custom category tags (e.g., Startup Pitch, AI Demo Day), and merge semantic duplicates.
• 💻 Modern React + TypeScript UI: A high-contrast dashboard featuring real-time timeline progress trackers, live log feeds, category filtering badges, modal overlays, and full responsiveness.
• 🎨 Dual Theme Support: Toggle seamlessly between Midnight Dark and Bright Slate (Light Mode) design systems.
• ⚡ FastAPI REST Backend: Asynchronous REST API providing endpoints for running pipeline executions, polling status updates, inspecting history logs, and downloading markdown digests.
• 📊 LangSmith Observability: Automatic environment mapping for seamless tracing of LangChain/LangGraph node executions and LLM calls.
• ⏱️ Scheduled Daemon & Resilient Checkpointing: Built-in APScheduler for periodic automated scans, with state persistence (event_scout_checkpoint.json) for seamless auto-resume on interruption.

---

⚙️ Agent Architecture & Graph Workflow

The core discovery pipeline is orchestrated as a cyclic LangGraph workflow:

graph TD
    START([🚀 Start Scan]) --> intent_planning_node[🧠 intent_planning_node]
    intent_planning_node --> retrieval_node[🌐 retrieval_node]
    
    retrieval_node -- "Events >= 3" --> dedup_rank_node[🔄 dedup_rank_node]
    retrieval_node -- "Events < 3 (Fallback)" --> web_search_node[🔍 web_search_node]
    
    web_search_node --> extract_node[📋 extract_node]
    extract_node --> dedup_rank_node
    
    dedup_rank_node --> digest_node[✍️ digest_node]
    digest_node --> END([🏁 Save & End])

    style START fill:#00c853,stroke:#333,stroke-width:2px,color:#fff
    style END fill:#d50000,stroke:#333,stroke-width:2px,color:#fff
    style intent_planning_node fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
    style retrieval_node fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
    style web_search_node fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#f8fafc
    style extract_node fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#f8fafc
    style dedup_rank_node fill:#1e293b,stroke:#34d399,stroke-width:2px,color:#f8fafc
    style digest_node fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#f8fafc

Loading

Node Responsibilities

1. intent_planning_node: Formulates search intent parameters (target keywords, domain rules, time boundaries) based on user inputs.
2. retrieval_node: Executes multi-platform direct scrapers to discover listed events.
3. web_search_node (Conditional Fallback): Triggers search engine fallback queries if initial platform retrieval yields fewer than 3 events.
4. extract_node: Uses Gemini structured extraction to convert raw search landing pages into unified event JSON models.
5. dedup_rank_node: Applies heuristic pre-filters (URL dedup, fuzzy title match, past date filter, city check) followed by a structured LLM validation batch pass to filter out spam, assign custom categories, merge duplicates, and compute composite rank scores.
6. digest_node: Compiles verified events into a markdown report document.

---

📁 Repository Structure

Event_Scout_Reasearch_Agent/
├── backend/                  # FastAPI Application & REST API
│   ├── core/                 # Server settings & environment configs
│   ├── routers/              # Search, Health, and History API endpoints
│   ├── schemas/              # Pydantic request/response payload schemas
│   └── services/             # Background task runner & agent execution service
├── react-frontend/           # React + TypeScript Frontend Web Application
│   ├── src/                  # React components, theme systems, and API client
│   ├── index.html            # Application HTML shell
│   └── package.json          # Node.js dependencies (Vite, Lucide Icons, Canvas Confetti)
├── src/event_scout/          # Core Agent Engine & LangGraph Workflow
│   ├── nodes/                # Graph node implementations (intent, retrieval, dedup, etc.)
│   ├── models/               # Domain data models (intent, event)
│   ├── scrapers/             # Direct platform web scrapers (Meetup, Eventbrite, etc.)
│   ├── config.py             # LLM factories, API key accessors, LangSmith mapping
│   ├── graph.py              # LangGraph workflow definition & runner
│   └── cli.py                # Command Line Interface runner
├── frontend/                 # Streamlit UI alternative
├── tests/                    # Pytest unit & node integration test suites
├── reports/                  # Generated markdown event digest reports
└── pyproject.toml            # Python dependencies (uv workspace config)

---

🛠️ Installation & Setup

Prerequisites

• Python 3.12+
• Node.js 18+ & npm
• uv (fast Python package manager)

1. Backend Setup

Clone the repository and install Python dependencies:

git clone https://github.com/Jethva-Parthiv/autonomous-event-scout-agent.git
cd Event_Scout_Reasearch_Agent

# Sync dependencies using uv
uv sync

2. Frontend Setup

Install Node.js dependencies for the React dashboard:

cd react-frontend
npm install
cd ..

---

📝 Environment Configuration

Create a .env file in the project root based on the template below:

# Required: Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.1-flash-lite

# Optional: Search & Scraper API Keys
TAVILY_API_KEY=your_tavily_key_here
EVENTBRITE_API_TOKEN=your_eventbrite_token_here
EXA_API_KEY=your_exa_key_here

# Optional: LangSmith Tracing & Observability
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_PROJECT=Event_Scout_Agent

# Agent Defaults
EVENT_SCOUT_CITIES=Ahmedabad,Bangalore,Mumbai
EVENT_SCOUT_REPORTS_DIR=reports

---

🚀 Running the Application

Option A: Web Dashboard (FastAPI Backend + React Frontend)

1. Start the FastAPI Backend:

   uv run uvicorn backend.app:app --reload

   Backend server running at: http://localhost:8000

2. Start the React Frontend:

   cd react-frontend
   npm run dev

   Open browser at: http://localhost:5173

---

Option B: Command Line Interface (CLI)

Run single-shot or scheduled scans directly from your terminal:

# Run with default settings (.env)
uv run event-scout

# Customize target cities and look-ahead timeframe
uv run event-scout --cities Ahmedabad Bangalore --days-ahead 30

# Start a fresh scan (clearing previous checkpoints)
uv run event-scout --fresh

# Run as a scheduled daemon loop (APScheduler)
uv run event-scout --schedule --cron "0 9 * * 1"

---

Option C: Streamlit Dashboard

Alternatively, launch the Streamlit interface:

uv run streamlit run frontend/app.py

---

🧪 Testing & Validation

Run the pytest test suite to verify graph nodes, scrapers, and heuristic/LLM deduplication pipelines:

uv run pytest

---

📄 License

Distributed under the MIT License. See LICENSE for details.