This guide explains how to deploy the Prompt Improver as a modular Val Town application with separate worker vals.

The application is split into multiple independent vals that communicate via Val Town's API:

┌─────────────────────────────────────────┐
│     Main Orchestrator Val (HTTP)        │
│   @toowired/prompt_improver             │
└────────────┬────────────────────────────┘
             │ API Calls
    ┌────────┴────────┬────────────┬────────────┐
    ▼                 ▼            ▼            ▼
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│Clarifier │  │Condenser │  │ Includer │  │  Future  │
│  Worker  │  │  Worker  │  │  Worker  │  │  Workers │
└──────────┘  └──────────┘  └──────────┘  └──────────┘

Deploy each worker val separately on Val Town:

1. Go to Val Town
2. Create a new val named prompt_improver_Clarifier
3. Copy contents from vals/prompt_improver_Clarifier.ts
4. Save as a Function Val (not HTTP)
5. Make it Public so the main val can call it

1. Create a new val named prompt_improver_Condenser
2. Copy contents from vals/prompt_improver_Condenser.ts
3. Save as a Function Val
4. Make it Public

1. Create a new val named prompt_improver_Includer
2. Copy contents from vals/prompt_improver_Includer.ts
3. Save as a Function Val
4. Make it Public

1. Create a new val named prompt_improver
2. Copy contents from vals/prompt_improver_main.http.ts
3. Save as an HTTP Val
4. This will be your main application endpoint

In your Val Town settings:

1. Go to Settings → Environment Variables
2. Ensure OPENAI_API_KEY is set
3. The valtown API key is automatically available

1. Visit your main val URL: https://[username]-prompt-improver.web.val.run
2. Check the worker status indicator at the top of the page
3. Test with a sample prompt

GET  https://[username]-prompt-improver.web.val.run
     → Frontend interface

POST https://[username]-prompt-improver.web.val.run/api/improve
Content-Type: application/json

{
  "prompt": "Your prompt to improve"
}

GET  https://[username]-prompt-improver.web.val.run/api/workers
     → Returns status of all worker vals

GET  https://[username]-prompt-improver.web.val.run/health
     → Returns system health status

You can also call worker vals directly via Val Town API:

curl -X POST https://api.val.town/v1/run/@[username]/prompt_improver_Clarifier \
  -H "Authorization: Bearer YOUR_VAL_TOWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": ["Your prompt to clarify"]}'

To add a new worker to the system:

1. Create the Worker Val:

   // @[username]/prompt_improver_NewWorker
   export default async function(prompt: string): Promise<string> {
     // Your worker logic here
     return processedPrompt;
   }

2. Update Main Val:

   • Add the new worker name to the workers array
   • Update the health check endpoint
   • Update the frontend to show the new worker

3. Test Integration:

   • Check /api/workers endpoint
   • Verify the worker appears in processing

1. Independent Scaling: Each worker can be updated independently
2. Fault Isolation: If one worker fails, others continue working
3. Easy Testing: Test each worker in isolation
4. Reusability: Workers can be used in other projects
5. Version Control: Each val has its own version history
6. Collaboration: Different team members can own different workers

1. Go to each val's page on Val Town
2. Click the "Logs" tab
3. Monitor execution and errors

Use Val Town's built-in test interface:

1. Go to the worker val page
2. Click "Run"
3. Provide test input
4. View output directly

• Check the /health endpoint for system status
• Monitor /api/workers for worker availability
• Review Val Town's usage dashboard for API calls

• Ensure worker vals are set to Public
• Verify exact naming: prompt_improver_[WorkerName]
• Check your username is correct in API calls

• Verify valtown or VAL_TOWN_API_KEY is available
• Check API key permissions in Val Town settings
• Ensure you're on a paid plan for API access

• Val Town has rate limits based on your plan
• Implement caching if needed
• Consider batching requests

1. Cache Results: Store frequently used prompts
2. Batch Processing: Process multiple prompts together
3. Conditional Workers: Skip workers based on prompt type
4. Monitor Usage: Track API calls in Val Town dashboard

1. API Keys: Never expose keys in public vals
2. Input Validation: Always validate user input
3. Rate Limiting: Implement per-user limits
4. Error Handling: Don't expose internal errors to users

Consider adding:

• Caching layer for repeated prompts
• Custom worker configurations
• A/B testing different worker combinations
• Analytics and usage tracking
• User preference storage
• Webhook notifications for long-running processes