Submit a Generation Work Item

Before you begin

Audience: Support engineer, validator

You need the following before submitting a generation work item:

question_text — the full text of the unanswered or Flow B question. This typically comes from a post-meeting assessment or a direct support case.
source_segment_id — the ID of the conversation segment that produced this question. Retrieve it from the intake candidate record.
customer_scope (optional) — if your organization uses scope isolation, supply the customer scope identifier so the generated answer is attributed correctly.

Confluence and Jira must be configured as RAG source connectors. If neither is connected, every work item will escalate with reason no_content. Contact your platform administrator to verify connector status before submitting.

Steps

1. Submit the work item

POST to the generation work items endpoint with the required fields:

curl -s -X POST http://localhost:8000/v1/generation/work-items \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "What is the maximum payload size for a webhook delivery in the v3 API?",
    "source_segment_id": "seg-1a2b3c4d",
    "customer_scope": "acme-corp"
  }'

The service returns HTTP 202 Accepted:

{
  "work_item_id": "wi-9f0a1b2c",
  "state": "NEW",
  "question_text": "What is the maximum payload size for a webhook delivery in the v3 API?",
  "source_segment_id": "seg-1a2b3c4d",
  "customer_scope": "acme-corp",
  "created_at": "2026-06-07T14:22:00Z"
}

Record the work_item_id. You will poll this ID to track progress.

Note: Each source_segment_id can only have one active work item at a time. If you submit a request for a segment that already has an active work item, the service returns the existing work item rather than creating a duplicate. Check the state of the returned item before assuming a new one was created.

2. Monitor the work item state

The Celery worker picks up the work item asynchronously. Poll the state endpoint until the item leaves the NEW or GENERATING state:

curl -s http://localhost:8000/v1/generation/work-items/wi-9f0a1b2c

The work item moves through the following states:

stateDiagram-v2
    [*] --> NEW : Work item submitted
    NEW --> GENERATING : Celery worker picks up task
    GENERATING --> PENDING_VALIDATION : Answer generated successfully
    GENERATING --> ESCALATED : Insufficient sources or LLM failure
    PENDING_VALIDATION --> CLOSED : Validator approves or rejects
    ESCALATED --> CLOSED : Resolved manually

Intermediate classification states (IN_CLASSIFICATION, READY_FOR_REVIEW) may appear briefly during processing. These are transient and do not require action.

3. Handle PENDING_VALIDATION

If state is PENDING_VALIDATION, a draft answer has been generated and is ready for human review:

curl -s http://localhost:8000/v1/generation/work-items/wi-9f0a1b2c/candidate

Review the candidate's generated_text, citations, and origin field. See Review a Generated Answer for the full validation procedure.

4. Handle ESCALATED

If state is ESCALATED, check the escalation_reason field in the work item response:

Reason	Meaning	Recommended action
`no_content`	Fewer than 2 source documents found in Confluence or Jira	Source the answer manually; the knowledge does not exist in internal systems
`llm_circuit_open`	The LLM is temporarily unavailable (circuit breaker tripped after 5 failures in 60 seconds)	Wait for the recovery window to pass, then resubmit
`known_answer_exists`	A Weaviate match at similarity ≥ 0.92 was found; LLM generation was bypassed	Review the existing answer referenced in the candidate response; no new generation is needed

Important: no_content escalation is expected behavior, not a system error. It means the knowledge gap is real — the answer is not available in your Confluence or Jira instance and must be sourced manually, authored by a subject-matter expert, or deferred. Do not retry a no_content escalation without first adding source content.

Note: When escalation_reason is known_answer_exists, the candidate response includes an answer_candidate_id that points to the existing approved registry entry. Review that entry before deciding whether it fully answers the question.

5. Check all work items in the queue (optional)

To see all work items and their current states:

curl -s "http://localhost:8000/v1/generation/work-items"

Filter by state:

curl -s "http://localhost:8000/v1/generation/work-items?state=escalated"

Result

The question is queued for the AGWMP generation pipeline. Once it reaches PENDING_VALIDATION, a draft answer with citations is ready for validator review. If it reaches ESCALATED, you have a documented reason for the gap and a clear next step. In both cases, the knowledge gap is tracked and visible in the dashboard work item backlog.