apps/simulator/README.md

Workflow Factor OS - Simulator Service

This is the Simulator Service component of the Workflow Factor OS monorepo, deployed to Hugging Face Spaces.

Environment Variables

The following environment variables MUST be set in your Hugging Face Space settings:

• LLM_GATEWAY_URL: The URL of your custom LLM gateway (e.g., https://llm-routing-system.pyaesone-n8n.workers.dev/v1/chat/completions)
• LLM_API_KEY: Your API key for the LLM gateway. This will be used as the primary LLM key.
• N8N_BASE_URL: The base URL of your n8n instance (e.g., https://pyae1994-n8n-aiven-v1.hf.space/)
• N8N_API_KEY: Your API key for the n8n instance.
• INTERNAL_API_SECRET: A shared secret between the Cloudflare Worker and this Simulator service for internal API authentication (e.g., super-secret-PSA).

Deployment

This service is designed to be deployed as a Docker image to Hugging Face Spaces. The Dockerfile in this directory handles the build process.

Build and Run Locally (for testing)

To build and run this service locally using Docker, navigate to the apps/simulator directory and execute:

docker build -t wfo-simulator .
docker run -p 7860:7860 -e LLM_GATEWAY_URL="your_llm_gateway_url" -e LLM_API_KEY="your_llm_api_key" -e N8N_BASE_URL="your_n8n_base_url" -e N8N_API_KEY="your_n8n_api_key" -e INTERNAL_API_SECRET="your_internal_api_secret" wfo-simulator

Hugging Face Spaces Deployment

1. Create a new Space on Hugging Face.
2. Select "Docker" as the Space SDK.
3. Upload the contents of the apps/simulator directory (including the Dockerfile and .dockerignore) to your Hugging Face Space repository.
4. Configure the environment variables listed above in the Space settings.
5. Hugging Face Spaces will automatically build and deploy your Docker image.

Note: The service exposes port 7860 as required by Hugging Face Spaces for custom Docker applications.