An intelligent building management assistant that monitors HVAC systems, discovers anomalies, and provides persona-based insights.
Features · Architecture · Getting Started · Documentation
Jeeves is an AI-powered butler for building management systems. It continuously monitors HVAC Fan Coil Units (FCUs), analyzes telemetry data, discovers anomalies, and notifies relevant stakeholders with personalized insights.
Current Focus: FCU-01_04 monitoring with real-time data ingestion from MQTT broker.
- Jeeves AI Butler: Autonomous discovery agent that analyzes telemetry streams
- Anomaly Detection: Automatically identifies unusual patterns (e.g., setpoint gaps, temperature anomalies)
- Persona-Based Notifications: Tailored insights for different stakeholders (Facility Manager, Building Engineer, etc.)
- Chat Interface: Ask Jeeves about current conditions, historical trends, and discoveries
- MQTT Integration: Connects to HiveMQ Cloud broker for live FCU data
- Live Charts: Real-time visualization of temperature, valve positions, and HVAC status
- Telemetry Streams: Dynamic discovery of all available data streams from database
- 48-Hour Data Retention: Automatic cleanup prevents database bloat
- Next.js 15 with App Router and React Server Components
- AI SDK 5 for LLM integration (Anthropic Claude)
- Inngest for background job orchestration
- Vercel Postgres for telemetry and state persistence
- Redis for deduplication and caching
- shadcn/ui + Tailwind CSS for beautiful UI
- FCU Data Parser: Handles LonWorks protocol field names (nvoSpaceTemp, nviSetpoint, etc.)
- Multi-Mode Support: Adapts to FCU's detailed mode (20-30 fields) and minimal mode (7 fields)
- Field Name Flexibility: Recognizes multiple variations of field names
- Original Timestamps: Preserves FCU data generation time vs. receive time
FCU-01_04 Hardware
↓
HiveMQ Cloud MQTT Broker
↓
Inngest Worker (every 5 min) ──→ Vercel Postgres
↓ ↓
Jeeves AI Analyzer (every 1 hour) Telemetry Streams
↓ ↓
Discoveries & Notifications Real-Time Charts
↓
Persona Dashboards & Emails
lib/inngest/functions/fcu-data-ingestion.ts: MQTT data ingestion worker (cron: every 5 minutes)lib/inngest/functions/jeeves-auto-scheduler.ts: Jeeves analysis scheduler (cron: checks every 5 minutes)lib/inngest/functions/telemetry-cleanup.ts: Database cleanup (cron: daily at 3 AM UTC)lib/mqtt/fcu-parser.ts: Parser for FCU MQTT messages with LonWorks field namescomponents/mqtt/mqtt-live-charts.tsx: Real-time charts using Server-Sent Eventsscripts/mqtt-monitor.py: Local Python script for debugging MQTT messages
- TelemetryTick: Raw sensor data (sensorId, timestamp, value)
- TelemetryAnomaly: Detected anomalies
- JeevesState: Jeeves configuration (enabled, interval, monitored streams)
- JeevesDiscovery: AI-discovered insights
- JeevesNotification: Persona-specific notifications
- JeevesLearning: Feedback and learning data
- Node.js 18+ and pnpm
- Vercel account (for deployment)
- MQTT broker access (or use HiveMQ Cloud)
- Redis instance (optional, for deduplication)
-
Clone and install dependencies:
git clone <repository-url> cd jeeves pnpm install
-
Set up environment variables:
cp .env.example .env.local
Required variables:
# Database POSTGRES_URL=<your-vercel-postgres-url> # AI Provider ANTHROPIC_API_KEY=<your-anthropic-key> # Authentication (optional for local dev) AUTH_SECRET=<generate-with-openssl-rand> # Inngest (for background jobs) INNGEST_SIGNING_KEY=<from-inngest-dashboard> INNGEST_EVENT_KEY=<from-inngest-dashboard> # Redis (optional, for deduplication) REDIS_REDIS_URL=<your-redis-url>
-
Run database migrations:
pnpm db:migrate
-
Start development server:
pnpm dev
-
Access the application:
- Web UI: http://localhost:3000
- Inngest Dev Server: http://localhost:3000/api/inngest
To monitor MQTT messages locally:
# Install Python dependencies
pip install paho-mqtt
# Run the monitor
python scripts/mqtt-monitor.pyThis will display live MQTT messages and save complete payloads to JSON files.
Comprehensive documentation is available in the /docs directory:
- JEEVES_ARCHITECTURE.md: System architecture and design
- FCU_JEEVES_INTEGRATION.md: MQTT integration guide
- MQTT_MONITOR_SETUP.md: Setting up MQTT monitoring
- JEEVES_BACKGROUND_PROCESSING.md: Inngest worker configuration
- JEEVES_DEDUPLICATION.md: Redis-based deduplication
- JEEVES_EMAIL_NOTIFICATIONS.md: Email notification setup
- DISCOVERY_CHAT_FEATURE.md: Chat with Jeeves about discoveries
- JEEVES_PERSONA_VISUAL_REPORTS_PLAN.md: Visual dashboards
| Variable | Required | Description |
|---|---|---|
POSTGRES_URL |
Yes | Vercel Postgres connection string |
ANTHROPIC_API_KEY |
Yes | Anthropic API key for Claude |
AUTH_SECRET |
Optional | NextAuth.js secret (required for auth) |
INNGEST_SIGNING_KEY |
Yes | Inngest signing key |
INNGEST_EVENT_KEY |
Yes | Inngest event key |
REDIS_REDIS_URL |
Optional | Redis URL for deduplication |
RESEND_API_KEY |
Optional | Resend API key for emails |
-
Connect to Vercel:
vercel link
-
Set environment variables in Vercel dashboard
-
Deploy:
vercel --prod
-
Set up Inngest:
- Create Inngest app at inngest.com
- Configure webhook:
https://your-domain.vercel.app/api/inngest - Add
INNGEST_SIGNING_KEYandINNGEST_EVENT_KEYto Vercel
# Generate new migration
pnpm db:generate
# Run migrations
pnpm db:migrate
# Open Drizzle Studio
pnpm db:studio- MQTT data ingestion (FCU-01_04)
- Real-time charts with SSE
- Jeeves autonomous analysis
- Discovery logging and storage
- Persona-based notifications
- Chat interface with Jeeves
- Telemetry cleanup (48h TTL)
- Field name flexibility (handles FCU mode changes)
- Expanding to all 49 FCUs (currently focusing on FCU-01_04)
- Email notifications via Resend
- Advanced anomaly detection algorithms
- Historical data export
- Custom alert thresholds per persona
- Mobile app notifications
- Multi-building support
This is a private project. For questions or issues, contact the project maintainer.
Private - All rights reserved.
Built with ❤️ using Next.js, Anthropic Claude, and Inngest