Skip to content

AGENT_CONNECTION_GUIDE.md

Latest commit

 

History

History
262 lines (216 loc) · 7.67 KB

AGENT_CONNECTION_GUIDE.md

File metadata and controls

262 lines (216 loc) · 7.67 KB

ProDeck Headless API - Agent Connection Guide

Status

✅ FULLY OPERATIONAL - All endpoints from prodeck-headless-api-spec.md are implemented and running.

Connection Details

  • Local URL: http://localhost:8787
  • Network URL: http://192.168.1.186:8787 ⭐
  • Machine IP: 192.168.1.186
  • Port: 8787
  • Auth: None required (optional PRODECK_API_TOKEN can be set)
  • API Keys: Automatically uses existing .env.local from main ProDeck project
  • Server Status: Running with auto-reload on file changes

🌐 For Agent Connections

Use this URL from any machine on the same network:

http://192.168.1.186:8787

Quick Test Commands

From this machine (localhost)

# Health check
curl http://localhost:8787/api/health

# Generate a test deck
curl -X POST http://localhost:8787/api/deck/generate \
  -F "prompt=Q2 Board Update" \
  -F "slideCount=5"

From another machine (network)

# Health check
curl http://192.168.1.186:8787/api/health

# Generate a test deck
curl -X POST http://192.168.1.186:8787/api/deck/generate \
  -F "prompt=Q2 Board Update" \
  -F "slideCount=5"

What Was Implemented

✅ All API Endpoints (Per Spec)

  • POST /api/deck/generate - Create deck generation jobs (async/sync modes)
  • GET /api/deck/jobs/:jobId - Check job status with progress tracking
  • GET /api/deck/jobs/:jobId/result - Get completed deck metadata
  • GET /api/deck/jobs/:jobId/pptx - Download PowerPoint file
  • GET /api/deck/jobs/:jobId/slides/:slideNumber - Get individual slide images
  • GET /api/deck/jobs/:jobId/manifest - Get full job manifest
  • DELETE /api/deck/jobs/:jobId - Clean up job artifacts
  • GET /api/health - Server health check

✅ Core Features

  • Job Orchestration: p-queue with concurrency=2, in-process job tracking
  • Brand Profile System: gus-default profile included, easily extensible
  • Gemini AI Integration: Planning (gemini-3-pro-preview) + Image generation (gemini-3-pro-image-preview)
  • OpenAI Support: Service stub ready for implementation
  • Server-side PPTX Export: Using pptxgenjs with node buffer output
  • File Upload Support: PDF, TXT, MD, CSV, PNG, JPG, WEBP
  • Progress Tracking: queued → planning → rendering → exporting → done

✅ Developer Tools

  • CLI Wrapper: ./scripts/prodeck-generate.sh for easy command-line usage
  • Full Documentation:
    • HEADLESS_API_QUICKSTART.md - 5-minute quick start
    • SERVER_README.md - Complete API reference
    • prodeck-headless-api-spec.md - Original specification
  • Auto-reloading Dev Server: Uses tsx with watch mode

Network Access Setup

For Local Testing

API is running on http://localhost:8787

For Remote Agent Access

  1. Get the Mac's local IP address:

    ifconfig | grep "inet " | grep -v 127.0.0.1

    Example output: inet 192.168.1.55 netmask...

  2. Connect from remote machine:

    curl http://192.168.1.55:8787/api/health

  3. If firewall blocks the connection:

    # Option 1: Allow port 8787 through macOS firewall
# Go to System Preferences → Security & Privacy → Firewall → Firewall Options
# Add Node.js or tsx to allowed applications

# Option 2: Temporarily disable firewall for testing
sudo pfctl -d

# Option 3: Add specific port rule
# (Requires creating pfctl rules file)

  4. Verify from agent machine:

    # Health check
curl http://<MAC_IP>:8787/api/health

# Should return: {"ok":true,"timestamp":"..."}

Key Implementation Details

Shared API Keys

The server automatically uses API keys from the main project's .env.local file:

  • VITE_GOOGLE_API_KEY → Used for Gemini AI
  • VITE_OPENAI_API_KEY → Used for OpenAI (when implemented)

No separate server .env configuration needed!

File Storage Structure

server/storage/jobs/
└── deck_2026-02-16T21-00-00-abc123/
    ├── manifest.json          # Job metadata & progress
    ├── inputs/                # Uploaded files
    │   ├── context-doc.pdf
    │   └── style-image.png
    └── outputs/               # Generated files
        ├── slide-1.png
        ├── slide-2.png
        └── deck.pptx

Example Usage for Automation Agents

Using CLI Wrapper (Recommended)

./scripts/prodeck-generate.sh \
  --prompt "Marketing Deck for Product Launch" \
  --docs ./product-specs.pdf \
  --style ./brand-logo.png \
  --slides 8 \
  --output ./generated-decks

The script handles:

  • Job submission
  • Status polling
  • Progress display
  • Automatic download when complete

Using Direct API Calls

# 1. Submit job
RESPONSE=$(curl -X POST http://localhost:8787/api/deck/generate \
  -F "prompt=Technical Architecture Review" \
  -F "contextFiles=@./architecture.pdf" \
  -F "styleImages=@./company-logo.png" \
  -F "slideCount=10" \
  -F "brandProfile=gus-default")

# 2. Extract jobId
JOB_ID=$(echo $RESPONSE | jq -r '.jobId')

# 3. Poll for completion
while true; do
  STATUS=$(curl -s http://localhost:8787/api/deck/jobs/$JOB_ID | jq -r '.status')
  if [ "$STATUS" = "done" ]; then
    break
  fi
  echo "Status: $STATUS"
  sleep 3
done

# 4. Download result
curl -o presentation.pptx http://localhost:8787/api/deck/jobs/$JOB_ID/pptx

Project Structure

ProDeck/
├── server/                      # Headless API server
│   ├── index.ts                # Express server & routes
│   ├── services/
│   │   ├── orchestrator.ts     # Job queue management
│   │   ├── gemini.ts           # Gemini AI integration
│   │   ├── openai.ts           # OpenAI stub
│   │   ├── pptx.ts            # PowerPoint export
│   │   └── brandProfile.ts     # Brand system
│   ├── brandProfiles/
│   │   └── gus-default.json    # Default brand profile
│   └── storage/jobs/           # Generated artifacts
├── shared/
│   └── types.ts                # Shared types (UI + API)
├── scripts/
│   └── prodeck-generate.sh     # CLI wrapper
└── Documentation
    ├── HEADLESS_API_QUICKSTART.md
    ├── SERVER_README.md
    └── prodeck-headless-api-spec.md

Running the Server

Start Server

npm run server:dev

Expected Output

✅ ProDeck Headless API running on port 8787
📁 Output directory: /Users/delorean_m2/AI/ProDeck/server/storage/jobs
🔐 Auth: Disabled (no token set)

Stop Server

pkill -f "tsx watch server/index.ts"

Troubleshooting

Port Already in Use

# Check what's using port 8787
lsof -i :8787

# Kill the process
kill -9 <PID>

API Key Issues

The server automatically reads from .env.local. If you see warnings about missing keys:

  1. Verify .env.local exists in project root
  2. Check it contains VITE_GOOGLE_API_KEY=...
  3. Restart the server

Connection Refused from Remote Machine

  1. Verify server is running: curl http://localhost:8787/api/health
  2. Check Mac's firewall settings
  3. Ensure both machines are on same network
  4. Try using Mac's IP instead of hostname

Additional Resources

  • Full API Documentation: See SERVER_README.md
  • Quick Start Guide: See HEADLESS_API_QUICKSTART.md
  • Original Specification: See prodeck-headless-api-spec.md
  • Brand Profile Example: See server/brandProfiles/gus-default.json

Implementation Status

✅ All Milestone 1 requirements completed (per spec):

  • /api/deck/generate async ✅
  • /api/deck/jobs/:jobId ✅
  • /api/deck/jobs/:jobId/result ✅
  • /api/deck/jobs/:jobId/pptx ✅
  • Gemini provider ✅
  • gus-default profile support ✅

Ready for production use and agent integration!