chat.engine.find-similar-failures

Look up previously-resolved Lumen error groups similar to a query error message so the agent can reuse prior root_cause/solution knowledge instead of re-investigating from scratch.

Find previously-resolved Lumen error groups similar to a given error message.

Inputs:

• organization_id: UUID of the organization (required)
• error_message: raw error text, 5-8000 chars (required)
• project: optional project hint
• workflow_type: optional workflow-type hint
• limit: 1-20, default 5
• min_similarity: 0.0-1.0, default 0.6

Outputs (terminal state_data):

• matches: list of similar error-group records, sorted by similarity DESC
• total_matches: int, count of returned matches
• query_embedding_ref: optional embedding identifier (or null)

Overview

Property	Value
Workflow type	Atomic
Library	App-chat
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization that scopes the similarity search. Error groups outside this org are never returned.
error_message	string	Yes	—	Raw error message used as the similarity query. Must be 5-8000 characters.
project	string	No	—	Optional project hint (e.g. 'ltinteg-api-core') to bias the search to errors from a specific Lumen project.
workflow_type	string	No	—	Optional workflow-type hint (e.g. 'agents.session-create') to scope the search to errors emitted by a specific workflow.
limit	integer	No	5	Max number of similar matches to return. 1-20, defaults to 5.
min_similarity	float	No	0.6	Minimum similarity score (0.0-1.0) a match must meet to be returned. Defaults to 0.6.

Output Schema

Field	Type	Required	Default	Description
matches	list	Yes	—	List of similar error-group matches, each carrying {error_group_ref, similarity, summary, root_cause, solution, resolved_by, resolution_method, resolved_at, ticket_ref, occurrences_count}. Sorted by similarity DESC.
total_matches	integer	Yes	—	Count of matches returned (always <= input.limit).
query_embedding_ref	string	No	—	Optional embedding identifier returned by the underlying Lumen lookup, surfaced for telemetry/auditing. Null when not provided.
error	string	No	—	Engine-stamped failure message (from the raised exception).
error_type	string	No	—	Engine-stamped failure type (exception class name).
failed_at_state	string	No	—	Engine-stamped name of the state where the failure occurred.
failed_layer	string	No	—	Engine-stamped DAG layer name (atomic workflows: null).
failed_step	string	No	—	Engine-stamped step name within the failed layer.
failure_reason	string	No	—	Stable failure code: organization_not_found
failure_detail	string	No	—	Human-readable detail mirrored from action_fail.
failed_action	string	No	—	Name of the action method that raised.
organization_uuid	uuid	No	—	organization_id echoed on the failure path for diagnostics.

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Resolve organization, locate lumen lookup, run similarity query
completed	No	Yes	Yes	—	Similarity search succeeded; matches returned
failed	No	Yes	No	—	Similarity search failed; matches=[] returned for shape parity

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "chat.engine.find-similar-failures",
  "initial_data": {
    "organization_uuid": "value",
    "error_message": "value"
  }
}