IntelliSense Auto-Mapping¶

IntelliSense is BizMetry's AI-assisted auto-mapping engine that analyzes your source API fields and target Frame components and automatically suggests — or directly populates — the most semantically appropriate mappings between them.

It is powered by sentence-transformers running on the bizmetry-llm service, which computes vector embeddings for field names and component names, clusters them by semantic similarity, and proposes the highest-confidence matches.

🧠 How It Works¶

1. Embedding generation — BizMetry sends the names and descriptions of all source fields (from all selected operations) and all target frame components to the bizmetry-llm service.
2. Semantic similarity scoring — the LLM service computes cosine similarity between each source/target pair using sentence-transformer embeddings.
3. Clustering — fields are grouped into similarity clusters. High-confidence matches (above a configurable threshold) are proposed as direct mappings.
4. BMEL generation — for target components that require a computed value or where multiple source fields are strong candidates, IntelliSense generates a BMEL expression (e.g., CONCAT(...) for composite fields, FIRST(...) for array-to-scalar extraction).
5. Canvas population — the mapper canvas is auto-populated with connector lines for all proposed mappings. Low-confidence matches are shown with a visual indicator so you can review them.

sequenceDiagram
    participant User
    participant Mapper
    participant LLM as bizmetry-llm
    participant Canvas

    User->>Mapper: Click "IntelliSense"
    Mapper->>LLM: POST /api/intellisense/suggest\n{sourceFields, targetComponents}
    LLM-->>Mapper: Similarity scores + suggested mappings
    Mapper->>Canvas: Populate connectors
    Canvas-->>User: Auto-mapped canvas (review mode)

⚡ Running IntelliSense¶

1. In the mapping canvas (Step 6 of the wizard), click the "IntelliSense" button in the toolbar.
2. BizMetry sends the field schema to the LLM service — this may take 1–3 seconds.
3. The canvas is populated with auto-generated connectors.

🎯 Confidence Indicators¶

After IntelliSense runs, each auto-generated connector shows a confidence indicator:

📋 Reviewing Auto-Mappings¶

After IntelliSense runs, you should:

1. Scan all connectors — verify that each auto-generated mapping makes semantic sense for your business domain.
2. Check BMEL expressions — click the ƒ icon on any BMEL connector to review the generated expression in the editor.
3. Delete wrong mappings — click a connector and press Delete to remove an incorrect auto-mapping.
4. Add missing mappings — manually draw connectors for any target components that IntelliSense left unmapped.
5. Adjust expressions — open the BMEL editor on any connector to refine an auto-generated expression.

🔁 Re-running IntelliSense¶

You can run IntelliSense multiple times. Each run replaces existing auto-generated connectors but preserves any connectors you manually added or edited.

🐛 Nested Array Fields¶

When a source field is the child of an array (e.g., $.orders[].total), IntelliSense handles it differently from scalar fields:

• The array parent is listed as a source with a badge showing its child count.
• Child fields of the array are shown expanded below the parent.
• When IntelliSense matches an array child to a scalar target component, it generates a BMEL expression using FIRST() or SUM() depending on the target type.

⚙️ IntelliSense Architecture¶

IntelliSense runs as a scatter-gather parallel operation on the backend:

• Each operation's fields are sent to the LLM service concurrently via a ThreadPoolExecutor.
• Results are gathered and merged, deduplicated, and ranked by score.
• The final ranked list is returned to the frontend in a single response.

This parallelization means IntelliSense performance scales with the number of operations selected, not with the total number of fields — making it fast even for large API schemas.

🔗 Related Sections¶

• Configure Mapping
• BMEL Expression Language
• Creating a Business Event