Development & Configuration
Local development and configuration guidance for the model server.
Development & Configuration
Run Model Server commands from model-server/. The repository's development and operational commands include installing requirements.txt, starting the Flask/Waitress service, starting platform-specific workers, and running pytest. Use the commands and process entry points defined by that repository rather than this documentation site.
Local Development Checklist
- Obtain the Model Server repository and its local environment file without committing secrets.
- Install its Python dependencies from
requirements.txtin an isolated environment. - Start Redis and make the shared-data directory available at the same path used by the integrated runtime.
- Configure the Model Server's Web App base URL and service credentials.
- Start the Flask service and every worker queue needed for the workflow being tested: analysis, collection/report generation, and notifications.
- Submit a safe test request from the Web App or an authenticated server-side client; do not expose the Model Server directly to browser code.
- Confirm the enqueue response, worker execution, generated output, callback delivery, and Web App-visible final state.
Configuration Ownership
| Configuration area | Model Server use | Requirements |
|---|---|---|
| API bearer credential | Authenticates trusted Web App requests. | Pair API_BEARER_TOKEN with the Web App's MODEL_API_TOKEN; store server-side and rotate both consumers together. |
| Callback URL and key | Sends authenticated callbacks to the Web App. | Use MAIN_APP_API_BASE_URL including /api and MAIN_APP_API_KEY; never log either value. |
| Redis connection | Enqueues and consumes asynchronous work. | Every API and worker process must point to the same intended Redis instance. |
| Shared-data location | Resolves inputs and stores outputs. | Must resolve the common /app/shared-data mount and exchange only forward-slash paths beginning with shared-data/. |
| Model-provider credentials | Calls an external model for the requested job. | Keep in process memory only when possible; do not persist, log, or return them. OpenRouter credentials are supplied for the individual job. |
| Collector credentials | Authenticates platform collectors and any stored sessions. | Keep server-only, encrypt persisted values, and maintain a rotation plan. |
| Runtime settings | Controls worker processes, limits, and service behavior. | Keep environment-specific values out of source control and record non-secret defaults in the Model Server repository. |
The shared values and path rules are canonical in Cross-Repository Contracts. Do not introduce host-specific absolute paths into requests, database-facing callbacks, or generated metadata.
Running the Required Processes
The API process alone only validates and enqueues work. Start the worker responsible for the work you request:
| Test scenario | Required processes |
|---|---|
| Analysis | Flask API, Redis, tasks worker, notifications worker, and any configured provider access. |
| Platform collection | Flask API, Redis, data_collection_tasks worker, notifications worker, shared-data mount, and the platform credential/session. |
| Report generation | Flask API, Redis, data_collection_tasks worker, notifications worker, and read/write access to the appropriate shared-data paths. |
Troubleshooting
| Symptom | Checks |
|---|---|
| Request is rejected | Verify server-to-server authentication, required fields, exclusive row range, requested gateway/model, and relative file path. |
| Request is accepted but never starts | Confirm Redis connectivity, queue name, and that the matching worker is alive and consuming. |
| Worker cannot find an input or output | Compare the container mount with the shared-data/ relative path; never patch the problem with a host-specific path. |
| Provider or collector fails | Record the provider/platform response category and stable job IDs, while redacting keys, tokens, prompts, and private content. |
| Work completes but the Web App is unchanged | Check the notifications worker, callback base URL/key, HTTP response, and callback payload for the matching job ID. |