EPulse - AI-Powered Event Discovery

About The Client

EPulse needed to identify conferences, trade shows, conventions, association events, professional meetings, niche industry gatherings, and exhibitor or sponsor opportunities that may be relevant sales channels for its massage therapy tools.

The client needed a research system that could turn scattered public event information into structured, reviewable opportunity data: find future events, inspect source pages, extract important details, qualify opportunities, avoid duplicates, and save results into a simple operating database for human review.

Project Detail	Information
Client	EPulse
Industry	Event Marketing, Sales Research Automation, AI Agent Workflow Automation
Location	USA
Duration	TODO: Confirm
Project Scope	Hermes event discovery agent, MCP tool server, Google Sheets review database, daily Kanban cron workflow, extraction and qualification services
Services Used	AI Agent Development, Workflow Automation, Custom Software Development, Data Pipeline Engineering, Research Automation, Docker Deployment
Engagement	Phase 1 event discovery automation agent
Live Link	Internal automation / TODO: Confirm public link if applicable
Client Contact / Testimonial	TODO: Confirm

---

The Objective

EPulse wanted to reduce the manual research required to find relevant event opportunities across many categories, states, associations, event calendars, exhibitor pages, sponsor pages, registration pages, and prospectus documents.

The goal was not simply to create a web scraper. The product needed to behave like a careful research analyst: search broadly, inspect public evidence, reject weak or past sources, extract only visible facts, score opportunities, dedupe against existing records, and keep final business decisions in human hands.

The platform needed to:

• Discover future conferences, trade shows, conventions, association meetings, expos, workshops, seminars, vendor days, and niche events
• Support category-based and state-by-state discovery from configurable Google Sheets rows
• Generate focused search queries for current and future years
• Use subcategory and opportunity terms such as exhibitor, sponsor, vendor, booth, prospectus, registration, and partnership
• Inspect official event, association, calendar, exhibitor, sponsor, registration, and prospectus pages
• Follow relevant public internal links up to a controlled depth
• Extract event details from public page text using Gemini
• Store unknown values as Unknown instead of guessing
• Reject past events, unsupported sources, low-score events, and disallowed Phase 1 statuses
• Score opportunities using business-controlled rules in Google Sheets
• Apply state-specific minimum score, attendee, query, result, candidate-domain, and link-depth policies
• Detect likely duplicate events and update existing rows instead of creating duplicates
• Save qualified events to Google Sheets for human review
• Log discovery runs with queries, inspected URLs, saved event IDs, errors, and summary data
• Run daily through Hermes cron and Hermes Kanban without requiring interactive guidance
• Keep Phase 1 focused on event discovery and review-ready event records

---

The Challenge

Event opportunity research is messy. Relevant details may be spread across event homepages, registration pages, association calendars, PDF prospectuses, sponsor packets, venue pages, and third-party event platforms. Some pages list past editions, some mention a future event without exhibitor details, and some contain registration or sponsor information several links away from the search result.

Before automation, this type of work usually required repeated manual searches, browser inspection, spreadsheet entry, and judgment calls about whether an event is worth reviewing. That created a lot of repetitive effort and left room for missed opportunities, duplicate records, stale past-event data, and inconsistent qualification decisions.

The key challenges included:

• Public event data is inconsistent across organizer sites, calendars, registration platforms, and documents
• Search result snippets are not reliable enough to save from directly
• Event pages often mix past and future editions
• Sponsor, exhibitor, vendor, booth, prospectus, and contact details may live on separate internal pages
• Many relevant events are smaller regional or association events, not only obvious national conferences
• Categories need to support configured subcategory terms without drifting into unrelated searches
• State-by-state discovery needs different thresholds and search budgets by operating priority
• Duplicate detection needs to consider names, websites, domains, city, state, dates, and source URLs
• AI extraction must avoid inventing details from page titles, URLs, or general knowledge
• Google Sheets is convenient for human review, but frequent one-by-one writes can become slow and quota-sensitive
• A daily agent workflow needs durable work tracking, retry behavior, preflight checks, and clear completion summaries
• Provider limits, Gemini quota errors, MCP availability issues, and long-running agent sessions need recoverable handling
• The system needed to stay focused on event discovery instead of expanding into downstream event operations

EPulse needed an AI-assisted research workflow that could handle the uncertainty of public web data while still producing structured, auditable records.

---

Our Approach

Bitontree designed EPulse Event Discovery as a Phase 1 AI-assisted research system built around Hermes Agent orchestration, a Python MCP tool server, Gemini extraction and search intelligence, and Google Sheets as the first human-review database.

The architecture separates the reasoning agent from deterministic backend operations. Hermes performs the research workflow, while the EPulse MCP server owns query generation, candidate extraction, validation, scoring, dedupe, save policy, sheet buffering, and audit logging.

Our approach focused on:

• Treating Google Sheets as the Phase 1 source of truth for categories, states, scoring rules, events, and discovery runs
• Giving Hermes a strict skill with clear research limits, save rules, and final JSON output requirements
• Using MCP tools for operations that must stay deterministic, such as validation, scoring, duplicate checks, and persistence
• Supporting two discovery flows: a Gemini Search flow and a Tavily/Firecrawl/Gemini extraction flow
• Using Gemini where natural-language interpretation is valuable, such as grounded discovery, event extraction, query expansion, and structured save decisions
• Using configurable scoring rules and state thresholds instead of hiding business policy inside prompts
• Using Hermes Kanban as a durable queue for category/state discovery units
• Buffering Google Sheets writes locally so runs can recover from crashes and reduce API pressure
• Keeping humans in control of final decisions by saving opportunities as reviewable research records

---

Core Features Developed

Two Event Discovery Flows

We built EPulse with two supported discovery paths that both end in the same validation, scoring, duplicate-check, state-policy, and Google Sheets save workflow.

The first path is the Gemini Search flow. In this mode, Gemini uses Google Search grounding and URL Context to find future events for a category/state unit, returns structured candidate event data and source URLs, and then the backend processes each candidate through qualification and save rules.

The second path is the Tavily/Firecrawl/Gemini extraction flow. In this mode, Hermes generates search queries, uses web search to find candidate event sources, retains relevant public URLs, discovers internal event/sponsor/exhibitor links, uses Firecrawl to extract page text, uses Gemini to convert that page text into structured event data, and then validates, scores, dedupes, and saves qualified events.

Both flows are intentionally routed through the same backend policy layer so EPulse gets consistent save behavior regardless of how the candidate was discovered.

Hermes Event Discovery Agent

We created a dedicated Hermes skill for EPulse event discovery.

The skill defines the agent's research behavior, target event types, source rules, search limits, state handling, candidate inspection workflow, scoring behavior, duplicate rules, evidence rules, completion summary format, and discovery-only scope boundaries.

The agent is instructed to act as a source-driven research analyst: inspect public evidence, avoid assumptions, keep missing values as Unknown, reject past events, and produce review-ready event records.

MCP Tool Server For Deterministic Workflow Operations

We built a Python MCP server that exposes EPulse-specific tools to Hermes.

The tool surface includes health checks, category reads, state reads, event queries, query generation, candidate-link discovery, candidate extraction and scoring, validation, scoring, duplicate checks, event saving, discovery-run logging, and text-based event extraction.

This lets Hermes use natural-language reasoning for research while delegating important state changes and business rules to backend code.

Category And State-Based Discovery Planning

The system reads enabled categories from Google Sheets and combines them with configured discovery states.

Each category/state pair becomes a discovery unit with its own priority, minimum score, minimum attendee threshold, query budget, result budget, candidate-domain target, and link-depth setting.

Starter categories include behavioral health, law enforcement, narcotics officers, child safety, healthcare, restaurant industry, pickleball, professional associations, and government organizations.

Hybrid Search Query Generation

We built a query generation service that combines reliable static query templates with optional Gemini-generated variants.

The query set is validated, deduplicated, limited, and balanced across multiple intent groups:

• Core event searches
• Sponsor, exhibitor, vendor, booth, registration, and prospectus opportunity searches
• Association and society searches
• Event calendar searches
• Category and subcategory searches

This prevents discovery from relying only on obvious conference searches and helps the agent find smaller, niche, and regional opportunities.

Public Candidate Link Discovery

We built a link crawler that inspects candidate pages and identifies relevant public internal links.

The crawler prioritizes links containing event, calendar, annual, conference, expo, meeting, agenda, program, exhibitor, sponsor, vendor, prospectus, booth, registration, pricing, contact, venue, packet, and PDF signals.

It supports controlled Level 1 and Level 2 discovery so Hermes can inspect event detail, sponsor, exhibitor, registration, prospectus, and contact pages without wandering through unrelated sites.

Tavily, Firecrawl, And Gemini Candidate Extraction Flow

We built a compact candidate extraction workflow for the Tavily/Firecrawl/Gemini path.

In this flow, Hermes uses generated category/state queries with web search, including Tavily-backed search where configured, to collect promising event sources. The system then discovers relevant public internal links, uses Firecrawl for public page text extraction, and uses Gemini for structured event extraction.

The extraction service returns event fields such as event name, website, start date, end date, city, state, venue, attendee estimate, exhibitor availability, booth cost, sponsorship cost, prospectus URL, registration URL, contact email, source URL, confidence, and notes.

The extraction prompt is strict: it must use only facts explicitly written in the inspected page text and must return Unknown for missing or implied values.

Gemini Search Discovery Flow

In addition to the Tavily/Firecrawl/Gemini extraction path, the backend supports a Gemini Search discovery flow.

This mode uses Google Search grounding and URL Context through Gemini to find future events for a category/state unit, then passes discovered events through the same validation, scoring, state policy, duplicate detection, and save workflow.

This gives the system an alternate discovery provider while preserving the same downstream quality controls.

Event Validation And Phase 1 Safety Rules

We built validation rules that reject unsupported or unsafe records before save.

The validator enforces recognized Phase 1 statuses, accepted confidence values, required event name, category, and source URL fields, public http(s) source URLs, and future-event checks against the current date.

Disallowed statuses such as Approved, Booked, and Paid are rejected because Phase 1 is discovery only.

Configurable Scoring Rules

The platform scores events from 0 to 100 using configurable scoring rules stored in Google Sheets.

Starter scoring parameters include audience relevance, attendance size, category match, exhibitor cost, event date, and data confidence.

Supported rule types include date-future checks, field completeness, field presence, numeric minimums, numeric growth, numeric maximums, lower-cost scoring, data confidence, truthy or present values, confidence levels, keyword matching, and value matching.

This lets business users adjust qualification behavior from the ScoringRules tab instead of requiring code changes for every priority shift.

State-Specific Qualification Policy

We implemented state policy evaluation so each state can have its own minimum score, attendee threshold, query budget, result depth, candidate-domain target, and link depth.

If an event passes scoring but has an unknown attendee estimate in a state where attendance matters, the system can save it as Needs Review with a clear state-policy note. If it fails the score or attendance threshold, it is rejected before persistence.

Duplicate Detection And Event Updates

The system compares candidate events against existing Events rows before creating new records.

Duplicate detection considers exact source URL, website, domain, event name similarity, city, state, and start date. When a duplicate is found, the existing row can be updated with stronger new information instead of creating another event.

The merge behavior preserves stronger existing data where appropriate and updates fields such as pricing, registration links, contact information, scoring data, and last-checked timestamps.

Google Sheets Review Database

We built the Google Sheets repository layer around a Phase 1 schema.

The active tabs are:

• Events
• Categories
• States
• ScoringRules
• DiscoveryRuns

The repository can create and format tabs, write headers, seed starter categories, seed starter states, seed starter scoring rules, apply dropdown validation, migrate discovery-run headers, query saved events, append or update event rows, and record discovery-run history.

Durable Local Sheet Buffer

We added a local JSONL buffer for Google Sheets writes.

Instead of writing every discovered event or discovery run directly to Google Sheets one by one, EPulse queues rows locally and flushes them in batches based on row count, elapsed time, card completion policy, or process exit.

The buffer rotates active files into .flushing.jsonl snapshots, archives flushed rows, recovers from interrupted flushes, re-checks duplicates during flush, and avoids appending duplicate discovery-run records by run_id.

This makes the cron faster, reduces Sheets API calls, and improves crash recovery.

Read Cache For Sheet-Heavy Runs

We added a local read cache for common Google Sheets reads.

Categories, states, scoring rules, and events are cached with short TTLs so large discovery runs do not repeatedly read the same data from Google Sheets.

This reduces latency and API usage during multi-category, multi-state research cycles.

Kanban-Based Daily Discovery Cron

Daily automation uses Hermes cron and Hermes Kanban as the durable work queue.

The Python tick runner seeds or reuses one card for every enabled category/state unit, claims the next ready card, runs Hermes with the EPulse discovery skill, parses the required final JSON marker, and moves the card to done or blocked based on completion quality.

Each card is tied to a stable EPulse unit and includes metadata for category, state, priority, query budgets, run date, retry state, and run-window timing.

Run Completion Auditing

We built completion auditing so a cron unit is not marked successful merely because the agent stopped.

The runner checks whether Hermes generated queries, searched the expected query budget, retained candidate URLs, inspected candidates, handled Level 2 link evidence where required, and returned the required EPULSE_RUN_RESULT_JSON marker.

If Hermes saves events but omits the marker, the runner can recover some completion evidence from logs. If the unit lacks required evidence, it blocks or retries instead of silently marking incomplete work as done.

DiscoveryRuns Audit Trail

Every automated unit can record a DiscoveryRuns row with run ID, date, category, state, priority, query settings, status, timestamps, queries, Hermes exit code, usage JSON, Gemini cost JSON, saved event IDs, summary, error, and Google Sheets API call count.

This gives EPulse an operational history of what was searched, what was saved, what failed, and why.

Preflight, Retry, Quota, And Recovery Controls

The cron runner performs MCP and chat preflight checks before processing discovery cards.

It supports retry limits, blocked-card handling, stale-card archiving, claim TTLs, max runtime windows, Gemini quota pause files, cooldowns, same-run resume behavior, final buffer flushes, and manual buffer-flush commands.

This makes the automation more resilient to real-world failures such as provider quota errors, MCP startup delays, missing tool access, or interrupted runs.

Docker And Cron Deployment Support

We built Docker support for local or server deployment.

The Docker setup installs Python, project dependencies, Hermes Agent, the EPulse MCP server, and a cron gateway container. Runtime data, Hermes state, logs, and secrets are separated through Docker volumes and mounted secret paths.

The setup guide includes build, configuration, preflight, cron creation, gateway startup, manual tick execution, log watching, and cleanup commands.

---

Technology Stack

Layer	Technology
Agent Orchestration	Hermes Agent, Hermes skills, Hermes chat, Hermes web toolset
MCP Server	Python, FastMCP, MCP tools
Backend Services	Python 3.11, Pydantic, pydantic-settings, dotenv
AI / LLM	Google Gemini / Google GenAI, Gemini Search grounding, URL Context
Search And Extraction	Gemini Search grounding, Tavily-backed web search where configured, Firecrawl, custom link crawler
Data Store	Google Sheets
Queue / Scheduling	Hermes Kanban, Hermes cron, no-agent cron wrapper
Persistence Reliability	Local JSONL sheet buffer, read cache, archive files, recovery snapshots
Observability	Python logging, Hermes run logs, Google Sheets API audit log
Authentication	Google OAuth or service account credentials for Sheets
Deployment	Docker, Docker Compose, Python slim image, Hermes gateway container
Testing	pytest

---

Product Architecture

System	Technology	Role
EPulse Hermes Skill	Hermes skill markdown	Defines research behavior, save rules, source rules, run limits, and discovery-only scope boundaries
EPulse MCP Server	Python, FastMCP	Exposes deterministic event discovery tools to Hermes
Gemini Search Flow	Gemini Search grounding, URL Context, EPulse MCP tools	Finds event candidates directly with Gemini grounding, then sends them through the shared qualification and save workflow
Tavily/Firecrawl/Gemini Flow	Web search, Firecrawl, Gemini extraction, EPulse MCP tools	Finds candidate URLs through web search, extracts public page text, converts it into structured event data, then qualifies and saves events
Discovery Services	Python, Gemini, Firecrawl, custom crawlers	Generate queries, inspect pages, extract event data, score records, dedupe candidates, and apply state policy
Google Sheets Repository	Google Sheets API	Manages Events, Categories, States, ScoringRules, and DiscoveryRuns tabs
Sheet Buffer	Local JSONL files	Buffers event and discovery-run writes, supports recovery, dedupe on flush, and API reduction
Hermes Kanban Runner	Python, Hermes CLI	Seeds category/state units, claims cards, runs Hermes, audits completion, and records results
Docker Runtime	Docker Compose, Hermes gateway	Runs EPulse cron and MCP configuration in a repeatable deployment environment

---

The Result

Bitontree delivered a dedicated Phase 1 event discovery automation system for EPulse.

The system turns public web research into structured, reviewable opportunity data while keeping qualification rules, source evidence, duplicate handling, and final human decisions visible.

Outcome	Result
Event discovery	Category/state event research is handled by a dedicated Hermes agent workflow
Search planning	Hybrid static and Gemini query generation creates broader, more balanced search coverage
Candidate inspection	Public candidate pages and relevant internal links are inspected within controlled limits
Event extraction	Gemini converts public page text into structured event records with explicit unknown handling
Qualification	Validation, scoring, and state policy decide whether events are saved, reviewed, or rejected
Duplicate protection	Existing events are detected and updated instead of duplicated
Human review	Google Sheets remains the Phase 1 source of truth for reviewable event opportunities
Run auditability	DiscoveryRuns records what was searched, saved, rejected, or blocked
Cron reliability	Hermes Kanban gives daily discovery durable category/state work units
Sheets reliability	Local buffering reduces direct API writes and supports recovery after interruptions
Deployment foundation	Docker setup supports repeatable local or server-based scheduled operation

---

Business Impact

The platform gives EPulse a stronger research engine for identifying event-based sales opportunities.

Instead of relying only on manual search and spreadsheet entry, the team can run a repeatable discovery workflow where search coverage, evidence inspection, scoring, dedupe, and review status are handled consistently.

The final solution helped EPulse:

• Reduce repetitive manual research across event categories and states
• Expand coverage beyond obvious conferences into association events, sponsor pages, exhibitor opportunities, calendars, workshops, seminars, vendor days, and niche events
• Keep event research source-backed with public URLs and explicit confidence levels
• Avoid saving past events as active opportunities
• Score events using configurable business rules instead of ad hoc judgment alone
• Apply different qualification thresholds by operating priority and state
• Reduce duplicate spreadsheet rows through source, domain, name, location, and date matching
• Save incomplete but promising opportunities as Needs Review instead of forcing false certainty
• Keep unknown event fields visible for human review
• Track discovery runs, saved event IDs, query activity, errors, and operational summaries
• Reduce Google Sheets API pressure with batching, caching, and replay-protected writes
• Recover safer from failed runs, interrupted flushes, quota pauses, and missing completion markers
• Build a scalable foundation for future event review, CRM, calendar, and sales workflow extensions

---

Key Engineering Problems We Solved

Turning Public Event Research Into Structured Workflow Data

Public event information is scattered across pages, calendars, platforms, and documents. We built a workflow that searches, inspects, extracts, validates, scores, and stores structured records while preserving source URLs and confidence metadata.

Keeping AI Extraction Source-Driven

The extraction prompts and validation rules prevent the agent from inventing city, state, venue, date, attendance, cost, contact, or sponsor details. Missing values stay as Unknown, which keeps review honest and avoids false precision.

Preventing Search Snippets From Becoming Saved Records

The system explicitly disallows saving from search snippets. A candidate must be inspected, extracted from public page text, validated, scored, deduped, and accepted by save policy before it reaches Google Sheets.

Balancing Broad Discovery With Bounded Runs

The query service balances core event, opportunity, association, calendar, and subcategory searches, while runtime limits control query count, results reviewed, candidate domains, page inspection depth, and run duration.

Making State-By-State Research Durable

Hermes Kanban turns each category/state pair into a durable work unit. Cards can be seeded, claimed, retried, promoted, completed, blocked, or archived without losing the larger daily discovery cycle.

Making Google Sheets Work As A Phase 1 Database

Google Sheets is practical for human review, but direct row-by-row writes are fragile at scale. We added read caching, local write buffering, batch flushes, crash recovery, duplicate re-checks on flush, and API audit logging.

Combining Business Rules With AI Research

Gemini helps with query expansion and event extraction, but qualification is controlled by backend scoring rules, state thresholds, validation checks, and duplicate logic. This keeps AI useful without making hidden business decisions.

Handling Provider Quota And Runtime Failures

The runner detects Gemini quota and capacity errors, supports cooldown pause files, can resume within a run window, and avoids marking incomplete agent work as successful. MCP and chat preflight checks catch tool availability issues before expensive runs begin.

Keeping The Discovery Scope Clear

The workflow is intentionally focused on event discovery and review-ready research records. That boundary keeps the system useful for the current goal without turning it into a broader event operations platform.

---

Development Timeline

Phase	Deliverables
Phase 1	Event data model, configuration layer, Google Sheets schema, starter categories, starter states, starter scoring rules
Phase 2	MCP server tools, Gemini extraction service, validation, duplicate detection, Google Sheets save/query workflows
Phase 3	Hybrid query generation, scoring service, state threshold policy, candidate link discovery, Firecrawl extraction integration
Phase 4	Hermes event-discovery skill, Kanban discovery units, no-agent cron runner, card claiming, run summary parsing, completion auditing
Phase 5	DiscoveryRuns logging, local sheet buffer, read cache, API audit logging, startup recovery, final flush behavior
Phase 6	Gemini Search discovery mode, quota pause/resume handling, runtime logging, Docker deployment support, setup documentation

---

Why This Project Stands Out

EPulse needed more than a generic scraper or a one-off AI prompt. Event discovery requires careful judgment: future dates, source quality, exhibitor relevance, sponsor signals, category fit, state priority, duplicate handling, and review readiness all matter.

Bitontree built EPulse Event Discovery around that real workflow. Hermes provides the research intelligence, MCP tools provide deterministic operations, Google Sheets keeps the review process accessible, and the Kanban cron runner makes discovery durable enough for scheduled daily use.

The result is an AI-assisted research agent that can explore messy public event data while keeping the business in control of qualification, review, and next-step decisions.