Heating Schedule Optimizer

An agentic workflow system that monitors weather forecasts and energy prices, then generates personalized heating schedules using LLM-based reasoning, with retries, state machines, event orchestration, and Postgres/pgvector context memory.

Getting Started

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose

1. Install Dependencies

npm install

2. Set Up Environment

cp .env.example .env
# Edit .env with your API keys (OpenAI/Anthropic, etc.)
# DATABASE_URL is already configured for Docker Compose

3. Start Database (Docker Compose)

# Start Postgres with pgvector extension
docker-compose up -d

# Verify database is running
docker-compose ps

# View logs if needed
docker-compose logs postgres

The database will be available at localhost:5432 with:

• Database: heating_schedule
• User: heating_user
• Password: heating_password

4. Initialize Database Schema

# Push Prisma schema to database
npm run db:push

# Generate Prisma client
npm run db:generate

5. Create Test User

npx tsx scripts/create-test-user.ts

This creates a test user with:

• ID: test-user-123
• Location: London
• Temperature preferences: 18°C - 21°C

6. Run Development Servers

You need to run both Next.js and Inngest:

Option A: Run everything together (recommended)

npm run dev:all

Option B: Run separately in different terminals

# Terminal 1: Inngest dev server
npm run dev:inngest

# Terminal 2: Next.js dev server
npm run dev

What's running:

• Next.js UI: http://localhost:3000
• Inngest Dashboard: http://localhost:8288

7. Generate Your First Schedule

1. Open http://localhost:3000
2. Click "Generate Schedule"
3. Wait 5-10 seconds for the workflow to complete
4. View your optimized heating schedule!

Stopping Services

# Stop database
npm run db:down

# Stop Next.js + Inngest (Ctrl+C in the terminal)

# Delete database data (optional)
docker-compose down -v

Specifications

This project uses a spec-driven approach where all system design is documented in /specs directory. Any LLM can read these specs to understand how to implement or extend the system.

See specs/index.md for the complete specification index.

Development Commands

Running the App

• npm run dev:all - Start Next.js + Inngest together (recommended)
• npm run dev - Start Next.js only
• npm run dev:inngest - Start Inngest dev server only

Database

• npm run db:up - Start Docker Compose (Postgres + pgvector)
• npm run db:down - Stop Docker Compose
• npm run db:push - Push Prisma schema to database
• npm run db:generate - Generate Prisma client
• npm run db:studio - Open Prisma Studio

Build & Quality

• npm run build - Build for production
• npm run lint - Run ESLint

Testing

• npx tsx test-tools.ts - Test weather & energy APIs
• npx tsx test-rag.ts - Test RAG/embedding system
• npx tsx test-ui-flow.ts - Test full workflow end-to-end

License

ISC