Contributing
Change guidance for the model-server repository.
Contributing to the Model Server
Keep Model Server changes scoped to request handling, collectors, analysis and report pipelines, provider adapters, shared-storage helpers, and worker behavior. Test the affected service behavior with the validation workflow defined by the model-server/ repository.
Choose the Right Change Scope
| Change | Primary owner | Required coordination |
|---|---|---|
| Internal processor, collector, adapter, or worker refactor | Model Server | Preserve the existing contract and add focused tests. |
| Provider capability or retry behavior | Model Server | Review pipeline behavior, credential handling, and user-visible failure implications. |
| HTTP route, request field, response field, or validation status | Model Server and Web App | Update Cross-Repository Contracts and both consumers compatibly. |
| Callback payload, job status, queue, timeout, or retry policy | Model Server and Web App | Validate duplicate delivery and the full asynchronous lifecycle. |
| Shared-data path, generated file, or retention behavior | Model Server and Web App | Confirm ownership, authorization, active-job safety, and cleanup rules. |
| Product workflow or user-facing text | Web App and Product docs | Keep Model Server detail here; update product behavior in the appropriate scope. |
Before Changing Code
- Trace the request from the Web App endpoint through validation, queue selection, worker execution, shared-data reads/writes, and callback delivery.
- Identify the stable Web App job ID or file meta ID used for correlation.
- Confirm the intended failure behavior: rejected before enqueue, failed during work, retryable provider/platform failure, or callback-delivery failure.
- Review secret flow and logging. Credentials, OAuth/session tokens, prompts, private input data, and callback bodies must remain server-side and redacted.
- If an external contract changes, design a compatible transition before removing the previous behavior.
Validation
For every changed pipeline, run the Model Server repository's relevant pytest tests and exercise the narrowest end-to-end path available. Include the following where applicable:
- request authentication and schema/range/path validation;
- duplicate submission and idempotent enqueue behavior;
- the correct RQ queue and worker execution;
- successful output at the expected shared-data location;
- provider or collector failure handling, including retry decisions;
- callback delivery, redacted logging, and Web App handling of the resulting status; and
- a regression test for the fixed behavior or contract.
Do not treat an HTTP 202 or enqueue response as sufficient validation. Confirm that the worker runs and the Web App receives the expected final or progress state.
Documentation Updates
Update the Model Server pages when repository-owned architecture, local configuration, pipelines, or validation expectations change. Update Cross-Repository Contracts for any shared boundary change, and link to it rather than duplicating shared schemas or status tables here. Update the relevant System data flow for a materially changed end-to-end workflow.