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:

```bash
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.