rolemule-core

RoleMule Core Conventions

App Name

The product name is RoleMule. Use settings.app_name in templates. The repo/folder name is rolemule.

Standardized Error System

Never raise bare HTTPException — always use APIError or the factory functions from utils/error_responses.py.

from utils.error_responses import APIError, ErrorCode, create_error_response
from utils.error_responses import unauthorized_error, forbidden_error, not_found_error, validation_error, rate_limit_error, internal_error, no_api_key_error

# Raise typed errors
raise APIError(ErrorCode.AUTH_INVALID_CREDENTIALS, "Invalid email or password", status_code=401)

# Or use convenience constructors
raise not_found_error("Workflow session")
raise unauthorized_error()
raise rate_limit_error(retry_after=3600)
raise no_api_key_error()   # when neither user key nor server key is configured

Error codes follow a namespace pattern:

• AUTH_1xxx — authentication/authorization
• VAL_2xxx — validation
• RES_3xxx — resource not found/conflict
• RATE_4xxx — rate limiting
• EXT_5xxx — external service errors
• CFG_6xxx — configuration errors (e.g. missing API key)
• INT_9xxx — internal server errors

Personal access tokens (PAT)

Long-lived CLI/automation auth (rm_pat_ prefix). Implementation: utils/personal_access_tokens.py, migration 20260708_024, API POST/GET/DELETE /api/v1/auth/tokens. get_current_user and WebSocket auth check PAT before JWT. Plaintext shown once on create; SHA-256 hash stored. Revoke all user PATs on password change, password reset, and account delete (with JWT invalidation).

CFG_6001 — No API Key (no_api_key_error())

Use no_api_key_error() (HTTP 422, error_code: "CFG_6001") whenever an LLM-backed endpoint is called but the user is not ready to run LLM. Never use validation_error() for this case — the dedicated code lets the frontend detect it and render a targeted "Add your API key → Settings" prompt instead of a generic error toast.