AI Classifier Service API

Status: P6-038 input context groundwork

Legacy Evidence

• apps/api/src/modules/questions/questions.controller.ts:649 exposes POST /api/questions/ai-classify/suggestions.
• apps/api/src/modules/questions/questions.controller.ts:668 exposes POST /api/questions/ai-classify/jobs.
• apps/api/src/modules/questions/questions.controller.ts:683 exposes GET /api/questions/ai-classify/jobs.
• apps/api/src/modules/questions/questions.controller.ts:703 exposes GET /api/questions/ai-classify/jobs/:id.
• apps/api/src/modules/questions/questions.controller.ts:717 exposes GET /api/questions/ai-classify/jobs/:id/errors.
• apps/api/src/modules/questions/questions.controller.ts:740 streams SSE events with snapshot, heartbeat, job.updated, and error.
• apps/api/src/modules/questions/questions.controller.ts:807 exposes POST /api/questions/ai-classify/jobs/:id/cancel.
• apps/api/src/modules/questions/question-classification.queue.ts uses BullMQ job id question-classification-{jobId}, 3 attempts, exponential backoff, and REDIS_URL.
• apps/api/src/modules/questions/question-classification.service.ts defines classification fields, job status values, progress/result shapes, idempotency, batch/concurrency limits, provider timeout, and provider fallback rules.
• apps/api/prisma/schema.prisma defines QuestionClassificationJob, AiProviderSetting, and AiProviderUsageEvent.

Native Foundation

P6-005 implements internal /v1/ai-classifier/* endpoints for a service-owned job foundation. P6-006 adds pgx-backed persistence for jobs and provider usage events when DATABASE_URL is configured and healthy, with in-memory fallback for local/dev runs without Postgres. P6-037 adds env-configured provider adapters while keeping mock as the default. P6-038 adds the question-bank service-owned /v1/questions/ai-classify/context endpoint that will supply bounded question prompt rows and taxonomy candidates to classifier providers in a later service-to-service client slice.

Method	Path	Purpose
POST	/v1/ai-classifier/jobs	Create or reuse a pending/running classification job for the same actor, organization, filters, fields, mode, overwrite, and threshold.
GET	/v1/ai-classifier/jobs	List jobs by optional status with limit/offset pagination.
GET	/v1/ai-classifier/jobs/{id}	Read one job scoped by actor/organization headers.
GET	/v1/ai-classifier/jobs/{id}/errors	Read paged errors from the job result payload.
GET	/v1/ai-classifier/jobs/{id}/events	Stream a legacy-shaped SSE snapshot, heartbeat, and job update.
POST	/v1/ai-classifier/jobs/{id}/cancel	Cancel a pending/running job.

Compatibility Notes

• Public /api/questions/ai-classify/* remains legacy-proxied.
• The native foundation returns the existing success envelope shape used by other Go services: { success, data, message }.
• Job statuses preserve legacy values: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED.
• AI_CLASSIFIER_PROVIDER controls provider runtime. Supported values are mock, openai, 9router, gemini, local, and ollama; default is mock.
• AI_CLASSIFIER_API_KEY, AI_CLASSIFIER_BASE_URL, and AI_CLASSIFIER_MODEL override provider-specific env such as OPENAI_API_KEY, GEMINI_API_KEY, OLLAMA_BASE_URL, and NINE_ROUTER_MODEL.
• AI_PROVIDER_TIMEOUT_MS remains the legacy-compatible timeout default source. AI_CLASSIFIER_TIMEOUT_MS, AI_CLASSIFIER_MAX_RETRIES, AI_CLASSIFIER_CIRCUIT_FAILURES, and AI_CLASSIFIER_CIRCUIT_COOLDOWN_MS provide native runtime overrides.
• Non-mock providers record success/failure usage telemetry with provider, base URL, model, operation, latency, token counts when returned by the provider, and retry/circuit metadata.
• Native question prompt input is provided by question-bank-service POST /v1/questions/ai-classify/context; ai-classifier-service does not yet consume it directly in this slice.
• Job scope/progress/result payloads persist to service-owned JSONB columns in classification_jobs; provider telemetry persists to provider_usage_events.
• Applying classification results to questions remains a later question-bank adapter; this slice does not mutate question-bank-service data.
• make test-ai-classification-job-route-guard verifies gateway route tables do not accidentally expose public job, suggestion, SSE, error, or cancel routes to this internal foundation. The existing exact apply route is allowed because it targets question-bank-service instead.
• Full public cutover still requires BullMQ/job worker parity, taxonomy-rich prompt context, gateway RBAC/maintenance behavior, and browser parity.

Rollback

Keep or set /api/questions/ai-classify/* gateway routes to legacy_proxy. The P6-006 native endpoints are internal-only and can be disabled by not routing traffic to ai-classifier-service.