Portal Semantic Enrichment

Purpose

This functional area lets administrators request AI-assisted refinement of mappings.

Its role is to accelerate mapping authoring by generating better names, descriptions, and field suggestions from onboarded API content.

Main Capabilities

• request semantic enrichment for a mapping, with an optional choice of which LLM model to use for that specific run
• target specific enrichment scopes
• select which endpoints to include in a given enrichment run
• watch live progress for mappings currently in the Enriching state
• review enrichment proposals and selectively accept or discard suggestions
• review enrichment outcomes through dedicated governance views
• monitor enrichment runs and per-chunk LLM activity

What Can Be Enriched

The platform can assist with:

• mapping name suggestions
• mapping description suggestions
• endpoint naming suggestions
• endpoint annotation hints (read-only, destructive, idempotent, open-world)
• input field name and description suggestions
• output field name and description suggestions

This helps make the resulting tools more understandable and more usable for AI callers.

Field Coverage

Every field of every selected operation is sent to the model. An API whose payloads are too large for a single prompt is split across several prompts rather than having its field list cut short, so a large contract cannot silently arrive with only its first fields named.

Fields belonging to a shared type are enriched once for that type and applied to every operation that uses it. Enterprise contracts commonly return the same document from a dozen operations; naming those fields once is both cheaper and more consistent, because the same field cannot end up with a different name on each operation. This applies to OpenAPI, OData, and SOAP contracts alike.

If any field ends up without a suggestion, the run reports it as a warning naming the operation and examples of the fields affected. Those fields keep their source names and descriptions — an incomplete enrichment is always visible rather than looking like a complete one.

Enrichment Advanced Settings

Both the Create mapping proposal dialog and the Request semantic enrichment dialog include an expandable Enrichment advanced settings panel. It is collapsed by default and every field is optional: leaving the panel untouched uses the platform defaults configured for the deployment.

The panel shows how many overrides are active. Values outside the accepted range are rejected with a message rather than silently corrected. When a run is interrupted and resumed, it resumes with the same settings it started with.

Raising the prompt budget suits models with large context windows and reduces the number of calls; lowering it suits stricter providers. Turning off "enrich each shared schema once" makes every operation enrich its own fields independently — this costs more and can produce different names for the same field on different operations, so it is best reserved for contracts where a reused type genuinely means different things in different places.

Endpoint Name Collisions

A model asked to name several structurally similar operations will often propose the same name for all of them — every "read the related document" navigation on an entity-oriented contract reads the same way. Tool names must be unique within a mapping, so the platform keeps the proposed name for the first endpoint and makes the others unique by appending a short stable suffix. The run reports which endpoints were renamed, and the names can be edited in the mapping editor afterwards.

The suffix is derived from the endpoint's own method and path, so re-running enrichment produces the same names rather than shuffling them.

LLM Model Selection

When requesting enrichment, administrators can optionally select a specific LLM model profile to use for that run. The drop-down lists all enabled model profiles accessible to the mapping's own tenant — not the current viewer's scope. This matters when a global super-admin manages mappings for a specific tenant, because the effective model list and default label reflect the tenant's actual LLM configuration.

Leaving the model set to "Use default" submits the job without a specific model selection. The background job worker then resolves the effective default for the mapping's tenant at job execution time:

1. If the tenant has a per-tenant default configured, that model is used.
2. Otherwise, the global platform default is used.

This means the default shown in the enrichment modal is accurate for the mapping's tenant, and the resolved model at execution time will always match what was shown.

Reference Attachments

When requesting enrichment, administrators can attach one or more reference documents to provide the LLM with additional context beyond the imported API definition. Attachments can be supplied in two places: on the Create mapping proposal dialog when "run enrichment immediately" is enabled, and on the Request semantic enrichment dialog for an existing mapping. Both flows go through the same attachment pipeline and the same limits below.

Supported file types and limits

• Accepted formats: .txt, .md, and .pdf.
• Maximum total size across all attached files: 1 MB. A client-side guard enforces this limit before submission and shows an inline error if exceeded.
• Maximum file count: 5 files per enrichment request.

How files are processed

Attachment processing happens before the enrichment run is queued for background processing:

1. Each file's text content is extracted from the supported formats.
2. The extracted text is fingerprinted so the platform can detect duplicate or altered content.
3. The extracted text is scanned for prompt-injection attempts before it is used in enrichment. Content identified as a clear attempt to hijack the model's behavior causes the upload to be rejected outright, naming the offending file, before any enrichment run is queued. Certain lower-risk phrasing is instead redacted from the extracted text, which is otherwise kept and used.
4. Validated attachments are bundled into the enrichment run and handed off to background processing.

During background processing, the extracted text from all attachments is assembled into a dedicated reference-context block and forwarded to the enrichment pipeline separately from custom instructions. By default the pipeline distills this material once into a compact glossary, and each operation chunk then draws only the glossary entries relevant to its own fields, parameters and endpoints — rather than re-embedding the full document into every chunk. Each glossary entry records which endpoints its meaning applies to, so a token that means different things on different endpoints produces a separate scoped entry per meaning, with notes capturing constraints or endpoint-specific logic drawn from the document. This preserves the document's authoritative meaning while keeping each chunk within the prompt budget. Deployments can also configure the pipeline to inject the reference material verbatim into every chunk instead of distilling it.

UX: incremental file picking and individual removal

• Files can be added across multiple picks. Each pick merges the new selection with the existing list, deduplicating by filename.
• Individual files can be removed from the list before submitting.
• The total-size guard is evaluated client-side after each merge; the enrichment request action is blocked until the total size is within the 1 MB limit.

Traceability

Each processed attachment is retained alongside its enrichment run with enough detail for an administrator to audit what was used: the filename, content type, size, a content fingerprint, the extracted text (truncated for very large documents, and stored already redacted where the scan found redactable content), a truncation indicator, a summary of what the scan found, and when it was processed.

The enrichment run detail modal in the governance dashboard shows a Reference attachments section listing each file's name, size, a content fingerprint, and a Truncated badge when the extracted text was cut off.

Security

Uploaded content is scanned for prompt-injection attempts before it is used in enrichment. Depending on what the scan finds, an upload is either rejected outright (naming the offending file, before any enrichment run is queued) or has the risky portion redacted from the extracted text while the rest of the document is kept and used. The scan is tuned to leave ordinary API documentation alone, so routine descriptive text in a reference document is not flagged.

Redaction happens before the text is stored, so no unredacted copy is retained. When a document was redacted, that fact is surfaced back to the administrator — visible on the upload response, recorded in the governance audit trail, and called out in the enrichment run's warnings — so it's clear the reference document was not used verbatim.

The model's output is scanned too. Any proposed name, description, alias, or rationale that trips the same protections is dropped before it is persisted, with a warning explaining what was removed. This matters because enriched descriptions are published into tool definitions that AI clients read — an injection surviving the run would otherwise reach an agent that does have tools.

Scanning runs within operational time limits; an input crafted to make the scan itself hang is treated as a failure and the upload is rejected, because a scan that did not complete has proven nothing about the document.

Deployments can tune the scan's sensitivity and, where appropriate, adjust or disable specific protections, though disabling scanning is not recommended for production.

Endpoint Selection

When requesting enrichment, administrators can choose which of the mapping's current endpoints to send to the LLM. The endpoint list defaults to all endpoints selected. Unchecking specific endpoints removes them from the LLM prompt for that run. Endpoints that are not selected are preserved in the resulting proposal exactly as they exist in the current draft — the LLM does not see them and does not generate suggestions for them.

This is useful when a mapping has many endpoints but only some need to be renamed or re-described, or when a previous enrichment pass already produced acceptable results for part of the mapping.

The selection is applied before the chunk planner runs. Only the selected operations are grouped into prompt chunks and sent to the LLM. The final proposal still includes all mapping endpoints, with non-selected ones carrying forward their current names and descriptions unchanged.

At least one endpoint must be selected before the start enrichment action becomes available.

How It Fits Into The Workflow

Semantic enrichment is not the source of truth by itself. Functionally, it acts as an accelerator inside the broader mapping lifecycle:

1. an API is onboarded
2. a mapping is created
3. enrichment is requested with selected targets and optionally a subset of endpoints
4. a background enrichment run is created and the job is enqueued
5. background processing generates suggestions through a chunked LLM pipeline
6. the completed proposal is stored as a side-car alongside the user's draft — the draft is never overwritten automatically
7. an administrator reviews the proposal, selects the suggestions they want to keep, and saves or discards

This keeps human administrators in control while still using AI to reduce manual effort.

Enrichment Runs

Each enrichment request creates a tracked enrichment run. The run captures which provider and model were used, how many operations were processed, how many chunks succeeded and failed, and the full timeline from request to completion.

The enrichment pipeline divides the imported API into operation chunks and executes each chunk as a separate LLM call. An optional overview pass can also enrich mapping-level metadata. Results are preserved progressively so completed work remains available for review.

Canceling An Enrichment Run

Operators can stop an in-progress enrichment run at any time from the mapping list.

Clicking the cancel action on an enriching mapping shows a confirmation dialog before proceeding. This prevents accidental interruption of long-running enrichment jobs.

On confirmation, the Portal:

1. Resets the mapping out of the Enriching state.
2. Marks the active enrichment run as Canceled.
3. Signals background processing to abort the run.

The abort signal is received promptly and the in-flight enrichment work stops before any additional processing continues.

Canceled runs appear in the Enrichment Dashboard with a Canceled status. The mapping returns to the state it was in before enrichment was requested, so it can be enriched again or edited normally.

Operator Experience During Processing

While enrichment is running, the mapping remains in the Enriching state and is treated as a background operation rather than an inline editing task.

Functionally, the Portal supports:

• live chunk progress directly in the mapping list
• automatic refresh of mappings while enrichment is still in progress
• transient real-time progress updates showing processed item counts and cumulative token usage
• final notification and dashboard refresh when the run completes, fails, or is canceled

Progress updates are throttled rather than sent for every processed step: the first update and the final update always appear, but updates in between are sent only when meaningful progress has occurred, keeping the mapping list responsive without flooding it during large, fast-running enrichment jobs. Delivery of these updates is best-effort — a delivery failure is logged and does not interrupt the enrichment run itself.

Reviewing And Accepting The Proposal

When enrichment completes, the Portal shows a notification banner inside the mapping editor signaling that a proposal is ready for review.

The review flow:

1. The Portal opens an Enrichment Proposal Panel showing a diff between the current draft and the suggestions.
2. Each endpoint that has at least one change is shown in a collapsible section. Changes include endpoint name, endpoint description, annotation hints, exposed field names, and field descriptions.
3. Each change is shown as a before/after comparison with strikethrough for the removed value and bold for the proposed value.
4. Every change has its own checkbox. All changes start as selected. Administrators deselect what they do not want to apply.
5. Acceptance is granular — administrators can accept all changes, accept changes per endpoint, or accept individual field changes.
6. Clicking Save applies the selected changes to the current draft and removes the accepted items from the pending proposal.
7. If any items remain un-accepted after a partial save, the proposal persists and can be reviewed again.
8. Clicking Discard proposal removes the entire proposal without altering the draft.

This means the administrator always chooses what enters the draft. The LLM output is a suggestion, not an automatic rewrite.

Enrichment Warnings

Separately from the proposal itself, an enrichment run can surface warning messages describing issues encountered while generating suggestions (for example, fields that received no suggestion, or a prompt budget too small for the reference context). These warnings are shown as their own alert in the mapping editor, next to the "Last enrichment" summary — they are not mixed into the change-summary text, so administrators can tell at a glance what changed versus what the run flagged as needing attention. Warnings are reset whenever the version is next edited or re-enriched.

Governance And Visibility

Enrichment is observable through dedicated governance views.

Operators can review:

• a paginated list of enrichment runs with status, chunk progress, provider, model, suggestion counts, and cumulative token totals
• detailed run records including provider information, timing, and chunk-level activity
• for each pass within a run: pass kind, prompt content, raw LLM output, suggestion counts, warnings, retries, token counts, and outcome. The one-time reference-digest pass is labelled Reference Documentation Digest rather than as a numbered chunk.

This is important because AI-assisted content generation needs traceability and operator oversight.

Operational Importance

This area improves documentation quality and tool usability while reducing the time required to prepare publishable mappings.