h2o-server

Resume generation server for H2O.

Requirements

• Node.js 18+
• Cursor CLI agent available as agent

Install

cd /Users/chandu/Work/my_git_repos/H2O/h2o-server
npm install

Run

npx h2o-server

By default the server listens on port 3000. Override with PORT.

On first run, the server will:

1. Prompt for your name (used in PDF filenames)
2. Create career_profile.md (edit this with your info)
3. Create .h2o-resume-prompt.md (AI agent instructions - fully customizable)

All files are created in your current working directory.

Customizing the AI Prompt

The .h2o-resume-prompt.md file contains the instructions for the AI agent. The latest version includes:

• ATS-optimized formatting guidelines
• Structured bullet point framework with methodology and quantifiable results
• Mandatory self-review process to ensure accuracy
• Industry best practices for resume writing

You can edit this file to customize how resumes are generated. The server will detect changes and ask before overwriting your customizations during updates.

See: docs/PROMPT_ENHANCEMENT_ATS.md for detailed information about the ATS optimization features.

Endpoints

GET /health

Simple health check.

GET /themes

Get available PDF styling themes.

Response:

{
  "themes": ["classic", "modern", "minimal", "executive"],
  "default": "classic",
  "descriptions": {
    "classic": "Traditional professional with uppercase section headers and subtle line separators",
    "modern": "Contemporary with accent color and custom bullet points",
    "minimal": "Clean and simple with maximum readability",
    "executive": "Sophisticated serif headers with centered name"
  }
}

POST /generate

Submit a resume generation job. Returns immediately with a request ID.

Body (Full Generation):

{
  "name": "company/role",
  "description": "Job description text",
  "theme": "modern"
}

Body (PDF Regeneration Only):

{
  "name": "company/role",
  "theme": "executive",
  "pdf_only": true
}

Fields:

• name (required): Job identifier
• description (required for full generation): Job description text
• theme (optional): One of classic, modern, minimal, executive. Defaults to classic.
• pdf_only (optional): If true, regenerates PDFs from existing markdown files without running AI agent. Defaults to false.

Response:

{
  "requestId": "a1b2c3d4e5f6g7h8",
  "name": "company/role",
  "theme": "modern",
  "pdf_only": false,
  "status": "pending",
  "message": "Job accepted and queued for processing"
}

GET /status/:requestId

Poll for job status using the request ID.

Response (pending):

{
  "requestId": "a1b2c3d4e5f6g7h8",
  "name": "company/role",
  "status": "pending",
  "step": "Initializing",
  "createdAt": "2026-01-26T00:00:00.000Z",
  "completedAt": null
}

Response (processing):

{
  "requestId": "a1b2c3d4e5f6g7h8",
  "name": "company/role",
  "status": "processing",
  "step": "Running agent",
  "createdAt": "2026-01-26T00:00:00.000Z",
  "completedAt": null
}

Response (completed):

{
  "requestId": "a1b2c3d4e5f6g7h8",
  "name": "company/role",
  "status": "completed",
  "step": "Done",
  "createdAt": "2026-01-26T00:00:00.000Z",
  "completedAt": "2026-01-26T00:01:30.000Z",
  "result": {
    "path": "/path/to/company/role",
    "theme": "modern",
    "regenerated": false
  }
}

The regenerated field indicates whether existing markdown files were used (true) or new ones were generated (false).

Response (failed):

{
  "requestId": "a1b2c3d4e5f6g7h8",
  "name": "company/role",
  "status": "failed",
  "step": "Error",
  "createdAt": "2026-01-26T00:00:00.000Z",
  "completedAt": "2026-01-26T00:01:00.000Z",
  "error": "Agent command failed (exit 1)"
}

Themes

The server supports multiple professional PDF styling themes:

• classic - Traditional professional (default)
• modern - Contemporary with accent colors
• minimal - Clean and simple
• executive - Sophisticated with serif headers

See themes/README.md for detailed theme descriptions and selection guide.

Sample curl commands

Health check:

curl -s http://localhost:3000/health

Get available themes:

curl -s http://localhost:3000/themes

Submit a generation job:

curl -s -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme/senior-frontend-engineer",
    "description": "We are looking for a senior frontend engineer to build...",
    "theme": "modern"
  }'

Regenerate PDFs with a different theme (fast):

curl -s -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme/senior-frontend-engineer",
    "theme": "executive",
    "pdf_only": true
  }'

Check job status:

# Use the requestId from the previous response
curl -s http://localhost:3000/status/a1b2c3d4e5f6g7h8

Complete workflow:

# 1. Get available themes
curl -s http://localhost:3000/themes | jq

# 2. Submit job with theme
RESPONSE=$(curl -s -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme/senior-frontend-engineer",
    "description": "Senior frontend engineer with React and AWS experience",
    "theme": "modern"
  }')

# 3. Extract request ID
REQUEST_ID=$(echo $RESPONSE | jq -r '.requestId')
echo "Job submitted: $REQUEST_ID"

# 4. Poll for completion
while true; do
  STATUS=$(curl -s http://localhost:3000/status/$REQUEST_ID | jq -r '.status')
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    curl -s http://localhost:3000/status/$REQUEST_ID | jq
    break
  fi
  
  sleep 5
done