InvestigationService

# addContradictionInPlace(investigation, contradiction) → {Partial.<IInvestigation>}

Adds a contradiction to a specific field in an investigation.

Parameters:

Name	Type	Description
`investigation`	`Partial.<IInvestigation>`	The investigation object to update.
`contradiction`	`IContradictionInput`	The details of the contradiction to add.

View Source services/investigation.service.js, line 978

Throws:

If the field is not found in the investigation.

Type: Error

Returns:

The investigation object with the updated contradiction.

Type: Partial.<IInvestigation>

# async checkAndUnlockStaleLocks() → {Promise.<number>}

Check and unlock stale locks (investigations locked for more than 5 minutes).

View Source services/investigation.service.js, line 2611

Returns:

Number of investigations unlocked.

Type: Promise.<number>

# async cloneInvestigation(investigationId) → {Promise.<IInvestigation>}

Clones the current investigation by adding a "copy_N" postfix to its identifier.

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the current investigation to clone.

View Source services/investigation.service.js, line 1508

Throws:

If an error occurs during the cloning process.

Type: Error

Returns:

The cloned investigation object.

Type: Promise.<IInvestigation>

# async createInvestigation(createDto) → {Promise.<IInvestigation>}

Creates a new investigation.

Parameters:

Name	Type	Description
`createDto`	`ICreateInvestigationDto`	The data required to create the investigation.

View Source services/investigation.service.js, line 252

Returns:

The created investigation.

Type: Promise.<IInvestigation>

# async deleteInvestigationById(investigationId) → {Promise.<IDeleteInvestigationByIdResponse>}

Permanently deletes an investigation and its related chat history.

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation to delete.

View Source services/investigation.service.js, line 1630

Throws:

If an error occurs during the deletion process.

Type: Error

Returns:

An object summarizing the deletion status of the investigation and related chats.

Type: Promise.<IDeleteInvestigationByIdResponse>

# deleteInvestigationData(investigation) → {IInvestigation}

Deletes the data of a given investigation.

Parameters:

Name	Type	Description
`investigation`	`IInvestigation`	The investigation to clear.

View Source services/investigation.service.js, line 1590

Throws:

If an error occurs during the deletion process.

Type: Error

Returns:

The investigation object with its values emptied.

Type: IInvestigation

# async ensureInvestigationAuthor(investigationId, authorId) → {Promise.<(IInvestigation|null)>}

Ensures that the author of a given investigation is set.

If the investigation exists and does not already have a valid author, this method sets the author to the provided authorId and updates the dateModified field.

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation to check.
`authorId`	`Types.ObjectId`	The ObjectId of the author to set.

View Source services/investigation.service.js, line 946

Throws:

If there is an error during the process of fetching or saving the investigation.

Type: Error

Returns:

The updated investigation object, or null if the investigation does not exist or already has a valid author.

Type: Promise.<(IInvestigation|null)>

# async generateInvestigation(message, history, investigationMetadata) → {Promise.<(IAssistantInvestigationFormat|null)>}

Generates an entire investigation based on the provided metadata. If the investigation is not found, it throws an error.

Parameters:

Name	Type	Description
`message`	`string`	The user's message from which the lesson must be detected.
`history`	`FormattedHistory`	The chat history between the user and the assistant.
`investigationMetadata`	`string`	The metadata of the investigation.

View Source services/investigation.service.js, line 1466

Throws:

If the investigation is not found.

Type: Error

Returns:

The generated investigation.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# async generateInvestigationObjects(message, history, investigationMetadata, investigation) → {Promise.<(IAssistantInvestigationFormat|null)>}

Generates objects of investigation based on the provided metadata and plain investigation. If the objects are not found, it throws an error.

Parameters:

Name	Type	Description
`message`	`string`	The user's message from which the lesson must be detected.
`history`	`string`	The chat history between the user and the assistant.
`investigationMetadata`	`string`	The metadata of the investigation.
`investigation`	`string`	The plain investigation without steps and objects with yaml format.

View Source services/investigation.service.js, line 1367

Throws:

If the objects are not found.

Type: Error

Returns:

The generated objects of the provided investigation.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# async generateInvestigationSteps(message, history, investigationMetadata, investigation) → {Promise.<(IAssistantInvestigationFormat|null)>}

Generates steps of investigation based on the provided metadata and the provided investigation. If the steps are not found, it throws an error.

Parameters:

Name	Type	Description
`message`	`string`	The user's message from which the lesson must be detected.
`history`	`string`	The chat history between the user and the assistant.
`investigationMetadata`	`string`	The metadata of the investigation.
`investigation`	`string`	The provided investigation without steps with yaml format.

View Source services/investigation.service.js, line 1417

Throws:

If the steps are not found.

Type: Error

Returns:

The generated steps of the provided investigation.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# async generateInvestigationWithoutStepsAndObjects(message, history, investigationMetadata) → {Promise.<(IAssistantInvestigationFormat|null)>}

Generates an investigation without steps and objects based on the provided metadata. If the investigation is not found, it throws an error.

Parameters:

Name	Type	Description
`message`	`string`	The user's message from which the lesson must be detected.
`history`	`string`	The chat history between the user and the assistant.
`investigationMetadata`	`string`	The metadata of the investigation.

View Source services/investigation.service.js, line 1299

Throws:

If the investigation is not found.

Type: Error

Returns:

The generated investigation without steps and objects.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# async getFieldHistory(investigationId, fieldPath, limit) → {Promise.<{fieldPath: string, history: Array.<unknown>, totalCount: number}>}

Gets the history for a specific field in an investigation.

Parameters:

Name	Type	Default	Description
`investigationId`	`string`		The ID of the investigation.
`fieldPath`	`string`		The path to the field (e.g., "title", "steps.0.title", "objects.0.name").
`limit`	`number`	50	Maximum number of history entries to return (default: 50).

View Source services/investigation.service.js, line 756

Throws:

If the investigation is not found.

Type: Error

Returns:

The field history.

Type: Promise.<{fieldPath: string, history: Array.<unknown>, totalCount: number}>

# async getInvestigationById(investigationId) → {Promise.<IInvestigation>}

Retrieves a single investigation by its ID.

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation to retrieve.

View Source services/investigation.service.js, line 323

Throws:

If the investigation is not found.

Type: Error

Returns:

The investigation data.

Type: Promise.<IInvestigation>

# async getInvestigationVersions(investigationId, limit) → {Promise.<IInvestigationVersionListResponse>}

Gets the versions of an investigation.

Parameters:

Name	Type	Default	Description
`investigationId`	`string`		The ID of the investigation.
`limit`	`number`	20	The number of versions to return (default: 20).

View Source services/investigation.service.js, line 806

Throws:

If the investigation is not found.

Type: Error

Returns:

The investigation versions.

Type: Promise.<IInvestigationVersionListResponse>

# async getInvestigations(searchDto) → {Promise.<IInvestigationListResponseDto>}

Retrieves investigations with filtering, sorting, and grouping.

Parameters:

Name	Type	Description
`searchDto`	`IInvestigationSearchDto`	The search and pagination parameters.

View Source services/investigation.service.js, line 1119

Returns:

The investigations with sections/items.

Type: Promise.<IInvestigationListResponseDto>

# async lockInvestigation(investigationId, userId) → {Promise.<IInvestigation>}

Lock an investigation for editing by a specific user.

Parameters:

Name	Type	Description
`investigationId`	`string`	The investigation ID to lock.
`userId`	`string`	The user ID who is locking the investigation.

View Source services/investigation.service.js, line 2559

Returns:

The updated investigation.

Type: Promise.<IInvestigation>

# async redoInvestigation(investigationId) → {Promise.<IInvestigation>}

Redo investigation - increment currentVersionIndex and return investigation at that version

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation.

View Source services/investigation.service.js, line 892

Throws:

If the investigation is not found or if the index is out of bounds.

Type: Error

Returns:

The investigation at the new index.

Type: Promise.<IInvestigation>

# async regenerateOtherFields(investigationId, fieldName, updatedBy, historyopt) → {Promise.<IInvestigation>}

Regenerates other fields in an investigation based on a specific field. This operation uses a 3-step process: text fields → objects → steps.

Parameters:

Name	Type	Attributes	Default	Description
`investigationId`	`string`			The ID of the investigation to update.
`fieldName`	`string`			The name of the field to base regeneration on (e.g., "title", "curriculum", "objectives").
`updatedBy`	`Types.ObjectId` \| `null`		null	The user making the change (optional).
`history`	`string`	<optional>	-	Chat history in YAML format (optional, defaults to "-").

View Source services/investigation.service.js, line 2034

Throws:

If the investigation is not found or the field is invalid.

Type: Error

Returns:

The updated investigation.

Type: Promise.<IInvestigation>

# async regenerateOtherFieldsObjects(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

Regenerates objects based on regenerated text fields. This is Step 2 of the 3-step regeneration process.

Parameters:

Name	Type	Attributes	Default	Description
`fieldName`	`string`			The name of the field to base regeneration on.
`fieldValue`	`string`			The value of the field to base regeneration on.
`investigation`	`string`			The regenerated investigation from Step 1 (YAML format).
`investigationMetadata`	`string`			The metadata/guide in YAML format.
`history`	`string`	<optional>	-	Chat history in YAML format (optional, defaults to "-").
`contradictionInfo`	`object`	<optional>		Optional contradiction information.
`contradictionReason`	`string` \| `null`	<optional>		Reason for contradiction.
`targetFieldName`	`string` \| `null`	<optional>		Target field name for contradiction.
`isContradicting`	`boolean`	<optional>		Whether the field is contradicting.

View Source services/investigation.service.js, line 1845

Throws:

If the prompt is not found or regeneration fails.

Type: Error

Returns:

The regenerated objects only.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# async regenerateOtherFieldsSteps(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

Regenerates steps based on regenerated text fields and objects. This is Step 3 of the 3-step regeneration process.

Parameters:

Name	Type	Attributes	Default	Description
`fieldName`	`string`			The name of the field to base regeneration on.
`fieldValue`	`string`			The value of the field to base regeneration on.
`investigation`	`string`			The regenerated investigation from Step 1 + Step 2 (YAML format).
`investigationMetadata`	`string`			The metadata/guide in YAML format.
`history`	`string`	<optional>	-	Chat history in YAML format (optional, defaults to "-").
`contradictionInfo`	`object`	<optional>		Optional contradiction information.
`contradictionReason`	`string` \| `null`	<optional>		Reason for contradiction.
`targetFieldName`	`string` \| `null`	<optional>		Target field name for contradiction.
`isContradicting`	`boolean`	<optional>		Whether the field is contradicting.

View Source services/investigation.service.js, line 1942

Throws:

If the prompt is not found or regeneration fails.

Type: Error

Returns:

The regenerated steps only.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# async regenerateOtherFieldsWithoutStepsAndObjects(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

Regenerates text fields (without steps and objects) based on a specific field value. This is Step 1 of the 3-step regeneration process.

Parameters:

Name	Type	Attributes	Default	Description
`fieldName`	`string`			The name of the field to base regeneration on.
`fieldValue`	`string`			The value of the field to base regeneration on.
`investigation`	`string`			The current investigation in YAML format.
`investigationMetadata`	`string`			The metadata/guide in YAML format.
`history`	`string`	<optional>	-	Chat history in YAML format (optional, defaults to "-").
`contradictionInfo`	`object`	<optional>		Optional contradiction information.
`contradictionReason`	`string` \| `null`	<optional>		Reason for contradiction.
`targetFieldName`	`string` \| `null`	<optional>		Target field name for contradiction.
`isContradicting`	`boolean`	<optional>		Whether the field is contradicting.

View Source services/investigation.service.js, line 1744

Throws:

If the prompt is not found or regeneration fails.

Type: Error

Returns:

The regenerated text fields only.

Type: Promise.<(IAssistantInvestigationFormat|null)>

# removeAiGeneratedValues(obj)

Recursively sets all aiGeneratedValue fields to null.

This method is schema-agnostic and works regardless of changes to the investigation structure.

Parameters:

Name	Type	Description
`obj`	`Record.<string, unknown>`	The object whose `aiGeneratedValue` fields should be cleared.

View Source services/investigation.service.js, line 219

# async toggleInvestigationDevelopment(investigationId) → {Promise.<IInvestigation>}

Sends/return investigation to/from InDevelopment.

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation.

View Source services/investigation.service.js, line 2532

Throws:

If the investigation is not found.

Type: Error

Returns:

The modified investigation.

Type: Promise.<IInvestigation>

# async undoInvestigation(investigationId) → {Promise.<IInvestigation>}

Undo investigation - decrement currentVersionIndex and return investigation at that version

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation.

View Source services/investigation.service.js, line 840

Throws:

If the investigation is not found or if the index is out of bounds.

Type: Error

Returns:

The investigation at the new index.

Type: Promise.<IInvestigation>

# async unlockInvestigation(investigationId, userId) → {Promise.<IInvestigation>}

Unlock an investigation. Only the user who locked it can unlock it.

Parameters:

Name	Type	Description
`investigationId`	`string`	The investigation ID to unlock.
`userId`	`string`	The user ID attempting to unlock (must be the lock owner).

View Source services/investigation.service.js, line 2584

Returns:

The updated investigation.

Type: Promise.<IInvestigation>

# async updateInvestigation(investigationId, updateData, obj) → {Promise.<IUpdateInvestigationResponse>}

Updates an investigation using the new API format.

Parameters:

Name	Type	Description
`investigationId`	`string`	The ID of the investigation to update.
`updateData`	`IUpdateInvestigationDto`	The update data in the new format, including string/number fields and step updates.
`obj`	`object`	Optional object used to determine if the update data should be built from scratch.
`needsBuildUpdate`	`boolean`	Whether the update data should be built from scratch.
`updatedBy`	`Types.ObjectId` \| `null`	The user making the change (optional).
`isAiGenerated`	`boolean`	Whether this update is AI-generated (default: false).
`skipVersioning`	`boolean`	Whether to skip versioning (default: false).

View Source services/investigation.service.js, line 607

Throws:

If the investigation is not found or is locked.

Type: Error

Returns:

The result of the update operation.

Type: Promise.<IUpdateInvestigationResponse>

# async updateInvestigationByVersion(oldInvestigation, investigation, userId, isUserChangeExist) → {Promise.<IInvestigation>}

Updates investigation by adding new version.

Parameters:

Name	Type	Default	Description
`oldInvestigation`	`IInvestigation`		The latest investigation version.
`investigation`	`IInvestigation`		The entire investigation model.
`userId`	`ObjectId` \| `null`		The ID of the user.
`isUserChangeExist`	`boolean`	false	Whether the change was made by the user (true) or AI (false). Defaults to false.

View Source services/investigation.service.js, line 1669

Throws:

If an error occurs during the update process.

Type: Error

Returns:

An investigation updated with new version.

Type: Promise.<IInvestigation>

K12 Backend Core

# new InvestigationService()

Classes

Methods

# addContradictionInPlace(investigation, contradiction) → {Partial.<IInvestigation>}

Parameters:

# async checkAndUnlockStaleLocks() → {Promise.<number>}

# async cloneInvestigation(investigationId) → {Promise.<IInvestigation>}

Parameters:

# async createInvestigation(createDto) → {Promise.<IInvestigation>}

Parameters:

# async deleteInvestigationById(investigationId) → {Promise.<IDeleteInvestigationByIdResponse>}

Parameters:

# deleteInvestigationData(investigation) → {IInvestigation}

Parameters:

# async ensureInvestigationAuthor(investigationId, authorId) → {Promise.<(IInvestigation|null)>}

Parameters:

# async generateInvestigation(message, history, investigationMetadata) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# async generateInvestigationObjects(message, history, investigationMetadata, investigation) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# async generateInvestigationSteps(message, history, investigationMetadata, investigation) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# async generateInvestigationWithoutStepsAndObjects(message, history, investigationMetadata) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# async getFieldHistory(investigationId, fieldPath, limit) → {Promise.<{fieldPath: string, history: Array.<unknown>, totalCount: number}>}

Parameters:

# async getInvestigationById(investigationId) → {Promise.<IInvestigation>}

Parameters:

# async getInvestigationVersions(investigationId, limit) → {Promise.<IInvestigationVersionListResponse>}

Parameters:

# async getInvestigations(searchDto) → {Promise.<IInvestigationListResponseDto>}

Parameters:

# async lockInvestigation(investigationId, userId) → {Promise.<IInvestigation>}

Parameters:

# async redoInvestigation(investigationId) → {Promise.<IInvestigation>}

Parameters:

# async regenerateOtherFields(investigationId, fieldName, updatedBy, historyopt) → {Promise.<IInvestigation>}

Parameters:

# async regenerateOtherFieldsObjects(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# async regenerateOtherFieldsSteps(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# async regenerateOtherFieldsWithoutStepsAndObjects(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

Parameters:

# removeAiGeneratedValues(obj)

Parameters:

# async toggleInvestigationDevelopment(investigationId) → {Promise.<IInvestigation>}

Parameters:

# async undoInvestigation(investigationId) → {Promise.<IInvestigation>}

Parameters:

# async unlockInvestigation(investigationId, userId) → {Promise.<IInvestigation>}

Parameters:

# async updateInvestigation(investigationId, updateData, obj) → {Promise.<IUpdateInvestigationResponse>}

Parameters:

# async updateInvestigationByVersion(oldInvestigation, investigation, userId, isUserChangeExist) → {Promise.<IInvestigation>}

Parameters: