Skip to content

DEMO_GUIDE.md

Latest commit

 

History

History
185 lines (146 loc) · 5.4 KB

DEMO_GUIDE.md

File metadata and controls

185 lines (146 loc) · 5.4 KB

Prompt Hero x402 — Demo Guide

Prerequisites

  • Node.js 18+
  • MongoDB (local binary or Docker)
  • (Optional) Replicate API token for real image generation
  • (Optional) Anthropic API key for LLM-powered composition

1. Environment Setup

cd prompt-hero-x402
cp .env.example .env   # or use the existing .env

Key .env variables:

MONGODB_URI=mongodb://localhost:27017/prompthero
PAY_TO_ADDRESS=0x0000000000000000000000000000000000000001
REPLICATE_API_TOKEN=demo          # "demo" → placeholder images
ANTHROPIC_API_KEY=demo            # "demo" → fallback composition
PROMPT_STORAGE_URL=http://localhost:4001
PROMPT_BACKEND_URL=http://localhost:4000
AGENT_ENDPOINT=http://localhost:4002
AGENT_API_KEY=demo-agent-key-001

2. Start MongoDB

# Option A: Local binary
mongod --dbpath ./mongodb-data --port 27017 --fork --logpath ./mongodb.log

# Option B: Docker
docker run -d --name mongo -p 27017:27017 mongo:7

3. Install Dependencies

cd prompt-storage && npm install && cd ..
cd prompt-backend && npm install && cd ..
cd external-agent && npm install && cd ..
cd validation-agent && npm install && cd ..

4. Start All 3 Servers

Open 3 terminals (or use & for background):

# Terminal 1 — Prompt Storage (port 4001)
cd prompt-storage && npx tsx src/server.ts

# Terminal 2 — External Agent (port 4002)
cd external-agent && npx tsx src/server.ts

# Terminal 3 — Prompt Backend (port 4000)
cd prompt-backend && npx tsx src/server.ts

5. Seed Sample Recipes

cd prompt-storage && npx tsx src/seed.ts

This inserts 20 sample prompt recipes (cinematic, anime, portrait, etc.).

6. Register the Composition Agent

curl -X POST http://localhost:4000/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CinematicComposer",
    "endpoint": "http://localhost:4002",
    "categories": ["cinematic", "photorealistic", "portrait"],
    "compositionFee": 0.01,
    "paymentWallet": "0x0000000000000000000000000000000000000002",
    "model": "flux",
    "description": "Cinematic prompt composition agent"
  }'

7. Run the E2E Demo

Step 1: Request without payment → 402

curl -X POST http://localhost:4000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cat in rainy Tokyo at night"}'
# → 402 Payment Required with USDC payment info

Step 2: Request with demo payment → Full flow

curl -X POST http://localhost:4000/api/generate \
  -H "Content-Type: application/json" \
  -H "X-Payment: demo" \
  -d '{"prompt": "a cat in rainy Tokyo at night"}'

Response includes:

  • imageUrl — generated image (placeholder if no Replicate token)
  • finalPrompt — LLM-composed prompt using recipe references
  • compositionAgent — which agent was selected
  • promptRefs — creator attribution with reward amounts
  • settlement — fee breakdown (Agent 20%, Creators 50%, Platform 30%)

Step 3: Submit feedback

curl -X POST http://localhost:4000/api/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "generationId": "test-001",
    "agentId": "<agentId from response>",
    "score": 9,
    "tags": ["creative", "accurate"]
  }'

Step 4: Check agent reputation

curl http://localhost:4000/api/agents

8. Run Validation Agent

The validation agent runs 25 automated checks across all services:

cd validation-agent && npx tsx src/validate.ts

Tests cover:

  • Health — all 3 servers are up
  • Storage — recipe CRUD, search, deduplication
  • Backend — 402 flow, agent routing, feedback
  • Agent — compose with auth, rejection without auth
  • E2E — full generate flow, settlement math, prompt diversity
  • Integrity — SHA-256 hashes, wallet addresses, fee constants

9. Useful API Endpoints

Endpoint Method Description
localhost:4000/api/generate POST Generate image (x402 payment)
localhost:4000/api/agents GET List registered agents
localhost:4000/api/agents/register POST Register new agent
localhost:4000/api/feedback POST Submit quality feedback
localhost:4001/api/recipes GET List all recipes (metadata)
localhost:4001/api/recipes/search?q=cinematic GET Search recipes (full content)
localhost:4001/api/recipes/register POST Register new recipe
localhost:4002/api/compose POST Compose prompt (needs auth)
localhost:4002/health GET Agent health check

10. Real Image Generation

To generate actual images instead of placeholders, set a real Replicate API token:

REPLICATE_API_TOKEN=r8_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Get a token at https://replicate.com/account/api-tokens

Architecture Reference

Consumer Agent ──(x402 $0.05)──▶ Prompt Backend ──(x402 $0.01)──▶ External Agent
                                        │                              │
                                        │                              ▼
                                        │                        Prompt Storage
                                        │                         (recipe DB)
                                        ▼
                                   Replicate FLUX
                                  (image generation)

Fee split per generation ($0.05 total):

  • Agent: $0.010 (20%)
  • Creators: $0.025 (50%)
  • Platform: $0.015 (30%)