Jobs Worker Semantic Enrichment Processing

Purpose

This functional area processes background requests for mapping enrichment.

Each enrichment request corresponds to a tracked enrichment run that moves through a defined lifecycle as the LLM pipeline executes.

Main Capabilities

• receive queued enrichment work carrying a run identifier
• validate mapping state before processing
• generate and apply enrichment output through a chunked LLM pipeline
• distill an attached reference document once into a compact glossary, then inject only the relevant slice into each chunk
• enrich a field that is shared by a named type across multiple operations once and reuse the result everywhere that type appears, instead of re-enriching it per operation
• record per-chunk LLM activity for operator review
• publish real-time progress snapshots as work completes
• apply partial success when only some chunks succeed
• mark runs as completed, canceled, or failed with a clear status
• support operator-initiated cancellation of an in-progress run
• filter the LLM prompt to an operator-specified subset of endpoints, leaving unselected endpoints unchanged
• resume an interrupted run from where it left off instead of re-spending its token budget
• detect and recover runs abandoned by a worker that never reported an outcome

Functional Value

This keeps AI-assisted mapping refinement asynchronous and operationally manageable, with fine-grained visibility into every LLM call within an enrichment request.

Enrichment Runs

Every enrichment request creates a top-level enrichment run before the job is processed.

A run has a lifecycle:

• Requested — run was created and queued for processing
• Processing — the run is actively making LLM calls
• Completed — all applicable enrichment was applied successfully
• Canceled — the operator canceled the run before or during execution; any partial LLM work is discarded
• Failed — the run could not complete, either due to a precondition failure or a processing error

The run tracks the provider, model, item counts, suggestion counts, and start/completion timestamps, along with enough recent activity to distinguish a slow-but-healthy run from an abandoned one (see Interrupted Run Recovery).

If the enrichment context is no longer valid by the time processing starts, the run is marked failed with a descriptive error and no changes are applied to the mapping.

Interrupted Run Recovery

An enrichment run can be interrupted without the worker ever reporting an outcome — for example if the process crashes mid-run. The platform is designed so this never leaves a run stuck: interrupted runs are detected automatically, resumed from their last completed step without repeating LLM calls that already succeeded, and — if they genuinely cannot be recovered after a bounded number of attempts — are failed cleanly with a status the operator can act on. Enrichment jobs are resilient to timeouts and will not silently redo work or leave a mapping locked indefinitely.

Enrichment Cancellation

Operators can cancel an in-progress enrichment run from the Portal. The cancellation takes effect promptly: the mapping is released, the run is marked canceled, and the in-flight LLM work is stopped as soon as the running job observes the cancellation. A cancellation that arrives before processing begins is honored immediately, preventing unnecessary LLM calls.

Chunked LLM Pipeline

Rather than sending an entire mapping in a single LLM call, the enrichment pipeline breaks the work into discrete passes and chunks, sized to stay within prompt limits.

At a high level:

1. When a reference document is attached, its content is distilled once into a compact glossary of key terms relevant to the mapping, rather than being re-sent in full with every chunk. This keeps the authoritative document meaning available to the LLM while keeping prompts efficient. If distillation is turned off, or the distillation pass is unable to produce a usable glossary, the pipeline falls back to sending the reference document directly with each chunk instead.
2. The API operations to enrich are divided into groups, honoring any operator-selected subset of endpoints.
3. Each group is checked against the platform's prompt size limits and split further if needed, so no chunk is sent oversized.
4. When mapping name or description enrichment is requested, that runs as its own pass ahead of the per-endpoint work.
5. Chunks execute in sequence (or with limited concurrency, depending on configuration), each drawing only the glossary context relevant to its own fields and endpoints.
6. Each chunk's activity — prompt, output, and outcome — is recorded for operator review.
7. Transient LLM failures are retried automatically.
8. Once all chunks have run, results are merged and deduplicated into a single proposal.
9. The merged proposal is filtered to the enrichment targets the operator requested, then applied to the mapping as a system-generated draft.

Chunks that fail after retries are counted as failed items but do not prevent successful chunks from being applied, so enrichment can produce useful partial results even when some chunks fail.

Real-Time Progress Reporting

As each pass or chunk completes, the worker publishes a progress snapshot for the active run — covering item counts processed so far and cumulative token usage. This drives live progress bars and in-progress dashboard metrics in the Portal while the worker is still executing, complementing the historical run and chunk records available after completion.

Validation Before Processing

Before starting work, the job claims the run exclusively, which is what prevents a duplicate or redelivered message from re-spending a token budget another attempt already paid for. Once claimed, the job confirms the mapping and its imported API definition are still valid and that the mapping is in the expected state for enrichment. If any check fails, the job returns early and the run is marked failed, with the mapping's status reset so it remains available for a future enrichment attempt.

Enrichment Targets

The job request carries a set of enrichment targets specifying which parts of the mapping the operator wants to improve.

Supported targets:

• mapping name
• mapping description
• endpoint names
• input field names
• input field descriptions
• output field names
• output field descriptions

The proposal is filtered to only the requested targets before it is applied. If the filtered proposal contains no applicable content, the run is marked failed and no changes are written.

Operators can also scope enrichment to a specific subset of endpoints from the mapping's current version rather than enriching every operation in the imported API.

Attachment Context Injection

When an enrichment request includes attached reference documents, the platform extracts their text and makes it available to the enrichment pipeline as reference context, separate from any operator-supplied custom instructions. Rather than embedding the full document into every chunk, the pipeline distills it once into a compact glossary of key terms and injects only the relevant portion into each chunk. This keeps the authoritative document meaning available to the LLM while keeping prompt sizes efficient across a large mapping.

Configuration

Enrichment behavior — chunk sizing, prompt limits, concurrency, retry behavior, and recovery thresholds for interrupted runs — is configurable by platform administrators to suit deployment size and provider characteristics. Sensible defaults are applied out of the box.

A subset of these settings (chunk sizing, prompt limits, and whether shared fields are enriched once per type) can also be overridden for an individual enrichment run from the Portal's enrichment advanced settings panel. Overrides are validated against an accepted range before use, and the chosen values are kept with the run so that a resumed run continues with the same sizing it started with.