Document Editing — Tools Reference

This document describes all tools involved in finding, loading, editing, and finalising documents in Thalabus. The intended audience is both developers maintaining these tools and LLM agents (via AgentToolPreparer) that must choose the right tool for a given user request.

Tool Landscape

Tool	Label	Purpose
`DocumentFetcher`	DocumentManagement	Search/list document metadata (ids, names, summaries). Does not load content. Supports filtering by dossier, explicit document ids, and semantic similarity.
`DocumentLoader`	DocumentManagement	Load a document or chapter into conversation memory so it can be edited. Prepares content for editing operations.
`DocumentEditor`	DocumentEditor, DocumentManagement	Perform structural and content edits on a loaded document/chapter. Supports 13 distinct editing operations (see Operations Reference below).
`DocumentChangeManager`	DocumentManagement	Finalise edits — COMMIT to accept all changes (strip `class="thalabus-edit"` markers), or REJECT to revert all edits. Applies to all chapters when document-level id is passed.
`DocumentVersionManager`	DocumentManagement	Manage document versions — RESET to restore original imported state, or DELETE_VERSIONS to purge all version history. Applies to all chapters when document-level id is passed.
`DocumentUnloader`	DocumentManagement	Remove a document or chapter from conversation memory when done. Frees up conversation context.
`DocumentCreator`	DocumentManagement	Create a new empty or pre-populated document in the repository. Links to dossier and auto-loads the new document.
`DocumentMover`	DocumentManagement	Move a document from its current dossier(s) to a target dossier. Updates CONTAINS relationships in Neo4j.
`DocumentInstantiateFromTemplate`	DocumentManagement	Create a new document from a template. Used for generating reasoning scratchpad documents and templated content.
`DocumentCreateReport`	DocumentManagement, Reporting	Generate a formatted report from one or more documents or chapters using LLM analysis. Supports parallel processing and grouping.
`DocumentCategorizer`	DocumentManagement, Categorization	Categorize documents using LLM-based analysis and ontology-driven List of Values (LoV) validation.
`DocumentSelector`	UserInteraction	Interactive UI component that allows users to select from a ranked list of documents. Supports custom title and subtitle.

Typical editing workflow

DocumentFetcher              →  find the document id
DocumentLoader               →  load it into memory
DocumentEditor (×N)          →  apply edits (each changed element gets class="thalabus-edit")
DocumentChangeManager        →  COMMIT to finalise all edits
DocumentUnloader             →  free it from conversation memory

DocumentEditor Operations Reference

DocumentEditor takes a mandatory operation string plus doc_or_chapter_id. All other arguments are operation-specific and described below.

Arguments common to many operations

Argument	Type	Description
`doc_or_chapter_id`	string	Target document (`docid-N`) or chapter (`docid-N-cM`) — always required
`elementIds`	string	Comma-separated HTML element IDs, e.g. `h1-3,p-2`. Sourced from the loaded document context.
`text`	string	New text or complete HTML element string, depending on operation
`text_to_be_replaced`	string	Anchor or target substring within an element
`new_tag`	string	Bare HTML tag name, e.g. `h2`, `ul`, `strong`
`merged_text_separator`	string	Separator inserted between texts when merging elements

ID scheme for auto-generated elements

New elements created by APPEND_ELEMENT_AFTER/BEFORE receive auto-generated IDs in the format {tagname}-{N} (e.g. p-3, h2-1, li-7), or {anchorId}-{tagInitial}-{N} when anchored to an existing element.

Full Operations Table

Edit-marking convention: Every operation that inserts or modifies HTML elements adds class="thalabus-edit" to the affected elements. Elements flagged for deletion additionally receive class="thalabus-edit thalabus-delete". Both classes are resolved by DocumentChangeManager: COMMIT finalises the changes (removes the classes, physically deletes marked elements); REJECT reverts them.

Operation	Category	Purpose	Required args	Example user prompt
`REPLACE_TAG`	Structure	Replace the HTML tag of one or more elements, keeping content	`elementIds`, `new_tag`	"Turn paragraph p-4 into an h2 heading."
`REPLACE_TEXT`	Content	Replace the full text content of element(s), or a specific substring if `text_to_be_replaced` is given	`elementIds`, `text`; optionally `text_to_be_replaced`	"In p-9, change 'January 2023' to 'March 2024'."
`REPLACE_ELEMENT`	Structure + Content	Replace both tag and full content in one call (combines REPLACE_TAG + REPLACE_TEXT)	`elementIds`, `new_tag`, `text`	"Turn p-7 into a bullet list with these items."
`APPEND_TEXT_AFTER`	Inline text edit	Within the text of the element(s), insert `text` immediately after the anchor `text_to_be_replaced`	`elementIds`, `text_to_be_replaced`, `text`	"After 'January' in p-7, add ' 2024'."
`APPEND_TEXT_BEFORE`	Inline text edit	Within the text of the element(s), insert `text` immediately before the anchor `text_to_be_replaced`	`elementIds`, `text_to_be_replaced`, `text`	"Before 'fur' in p-3, insert 'orange '."
`APPEND_ELEMENT_AFTER`	Structure	Insert a complete HTML element (tag embedded in `text`) after the specified element(s)	`elementIds` (opt.), `text` (full HTML, e.g. `<p>...</p>`)	"After p-12, add a note paragraph."
`APPEND_ELEMENT_BEFORE`	Structure	Insert a complete HTML element (tag embedded in `text`) before the specified element(s)	`elementIds` (opt.), `text` (full HTML)	"Before p-5, add a warning div."
`SURROUND_WITH_TAG`	Inline structure	Wrap a substring inside an element with a new HTML tag	`elementIds`, `text` (substring), `new_tag`	"Make the word 'critical' bold in p-9."
`MERGE_TEXT`	Structure	Merge the content of multiple elements into the first	`elementIds`; optionally `merged_text_separator`	"Merge paragraphs p-3, p-4, p-5 into one."
`DELETE_ELEMENTS`	Structure	Mark elements as pending deletion (adds `class="thalabus-edit thalabus-delete"`). Actual removal occurs when changes are committed via DocumentChangeManager.	`elementIds`	"Delete paragraphs p-2 and p-6."
`CREATE_LIST`	List management	Convert a set of existing elements into a `ul` (unordered/bullet) or `ol` (ordered/numbered) list. Each element's text becomes a `<li>`. The new list is inserted where the first element was and receives `class="thalabus-edit"`; original elements receive `class="thalabus-edit thalabus-delete"` (pending deletion).	`elementIds`; `new_tag` = `ul` (default) or `ol`	"Transform the subchapters h3-2, h3-4, h3-6 into a bullet list."
`DISSOLVE_LIST`	List management	Reverse a list: extract each `<li>` from the `ul` or `ol` identified by `elementIds` into individual block elements inserted after the list. Each new element receives `class="thalabus-edit"`; the list receives `class="thalabus-edit thalabus-delete"` (pending deletion).	`elementIds` (the list id); `new_tag` = target tag per item (default `p`)	"Convert the bullet list ul-1 back into paragraphs."
`MOVE_ELEMENTS`	Structure	Move one or more elements to a new position relative to an anchor element. Clones are inserted at the destination with `class="thalabus-edit"`; originals receive `class="thalabus-edit thalabus-delete"` (pending deletion).	`elementIds`; `target_element_id`; `position` = `BEFORE` \| `AFTER` \| `INSIDE_FIRST` \| `INSIDE_LAST`	"Move p-7 and p-8 after h2-5."

DocumentChangeManager Operations Reference

DocumentChangeManager manages pending changes on documents. It supports two operations:

Operation	Purpose	Required args	Example user prompt
`COMMIT`	Accept and finalise all pending edits by removing `class="thalabus-edit"` markers from the HTML	`doc_or_chapter_id`	"Commit all changes." or "Save edits."
`REJECT`	Revert all pending edits, restoring content to its pre-edit state	`doc_or_chapter_id`	"Reject changes." or "Discard all edits."

When a document-level id is passed, the operation applies to all chapters at once.

DocumentVersionManager Operations Reference

DocumentVersionManager manages document versions and history. It supports two operations:

Operation	Purpose	Required args	Example user prompt
`RESET`	Reset the document or chapter to its original imported state, discarding all HTML edits	`doc_or_chapter_id`	"Restore the original version." or "Undo all edits."
`DELETE_VERSIONS`	Permanently delete all saved version history (DocumentVersion / ChapterVersion nodes)	`doc_or_chapter_id`	"Delete all version history." or "Clean up versions."

When a document-level id is passed, the operation applies to all chapters at once.

DocumentMover Operations Reference

DocumentMover handles document relocation within the dossier hierarchy. It performs a single operation:

Operation	Purpose	Required args	Example user prompt
Move operation	Move a document from its current dossier(s) to a target dossier. All existing OWNS relationships are removed and a new one is created.	`document_id`, `target_dossier_id`	"Move document docid-12 to dossier dossier-7."

Return value: Success confirmation includes the document id, previous dossier ids, and target dossier id.

DocumentCreator Operations Reference

DocumentCreator creates new documents with optional initial content. It performs a single operation:

Operation	Purpose	Required args	Optional args	Example user prompt
Create operation	Create a new empty or pre-populated document in the repository. The document is automatically linked to the specified dossier (or session dossier), and loaded into memory.	`document_name`	`document_text`, `dossier_id`	"Create a new document called 'Analysis Report' with some initial text."

Behavior: The new document receives a unique docid-N identifier, is written to the file system, linked to a dossier if available, and automatically loaded into the conversation memory.

DocumentSelector Operations Reference

DocumentSelector provides an interactive UI for document selection. It supports a single parameterized operation:

Operation	Purpose	Required args	Optional args
Selection UI	Display an interactive component allowing users to select from a ranked list of documents.	Either `selected_doc_ids` (dict) or `dossier_id`	`title`, `subtitle`

Parameters: - selected_doc_ids: Dictionary mapping document ids to rank (0.5–1.0). Rank indicates relevance: 1.0 = highly relevant, 0.5 = somewhat relevant. - dossier_id: Auto-populates the selection UI with all documents from the specified dossier. - title / subtitle: Custom text for the selection UI (displayed in conversation language).

Return value: A Blazor component response with user selections and metadata.

DocumentCreateReport and DocumentCategorizer

These tools are specialized for advanced document operations:

DocumentCreateReport: Generates formatted reports by analyzing one or more documents or chapters using LLM reasoning. Supports parallel processing, grouping by size, and custom reporting instructions.
DocumentCategorizer: Applies LLM-based categorization to documents, enforcing ontology-driven Lists of Values (LoV) for category validation.

See the respective skill implementations for detailed parameter documentation.

Concrete Examples

Load → edit → commit → unload

User: "Load chapter 1 of docid-16, fix the date, and commit."

1. DocumentLoader          doc_or_chapter_id=docid-16-c1
2. DocumentEditor          operation=REPLACE_TEXT, elementIds=p-9,
                           text_to_be_replaced="January 2023", text="March 2024"
3. DocumentChangeManager   operation=COMMIT, doc_or_chapter_id=docid-16    # document level
4. DocumentUnloader        doc_or_chapter_id=docid-16-c1

Delete elements

User: "Delete paragraphs p-2 and p-6 from the loaded document."

DocumentEditor   operation=DELETE_ELEMENTS
                 elementIds=p-2,p-6
# Elements are marked as pending deletion; actual removal occurs on COMMIT
DocumentChangeManager   operation=COMMIT, doc_or_chapter_id=docid-16

Create a new document and move it

User: "Create a new document called 'Evidence Analysis' and move it to dossier-5."

1. DocumentCreator   document_name="Evidence Analysis", document_text="Initial findings...",
                     dossier_id=dossier-3
2. DocumentMover     document_id=docid-42, target_dossier_id=dossier-5

Select documents from a dossier

User: "Let the user choose which documents to review."

DocumentSelector   dossier_id=dossier-7, title="Select Documents to Review",
                   subtitle="Choose which documents to include in the analysis"

Paragraph → bullet list conversion

DocumentEditor   operation=REPLACE_ELEMENT
                 elementIds=p-7
                 new_tag=ul
                 text=<li>A manual</li><li>A USB cable</li><li>A power adapter</li>

Convert subchapter headings into a bullet list

# User: "Transform the subchapters of 'draft ideas' into a bullet list."
# The h3 elements h3-2, h3-4, h3-6, h3-8 become <li> items inside a new <ul>.

DocumentEditor   operation=CREATE_LIST
                 doc_or_chapter_id=docid-3
                 element_ids=h3-2,h3-4,h3-6,h3-8
                 new_tag=ul           # ul = bullet list (default); use ol for numbered

Create a numbered list from selected elements

DocumentEditor   operation=CREATE_LIST
                 doc_or_chapter_id=docid-3
                 element_ids=p-2,p-4,p-6
                 new_tag=ol

Dissolve a list back into paragraphs

DocumentEditor   operation=DISSOLVE_LIST
                 doc_or_chapter_id=docid-3
                 element_ids=ul-1
                 new_tag=p            # each <li> becomes a <p> (default)

Move elements to a new position

# User: "Move p-7 and p-8 to after h2-5."
DocumentEditor   operation=MOVE_ELEMENTS
                 doc_or_chapter_id=docid-3
                 element_ids=p-7,p-8
                 target_element_id=h2-5
                 position=AFTER

# User: "Move the disclaimer div-2 to the top of the conclusions section div-9."
DocumentEditor   operation=MOVE_ELEMENTS
                 doc_or_chapter_id=docid-3
                 element_ids=div-2
                 target_element_id=div-9
                 position=INSIDE_FIRST

position values:

Value	Meaning
`BEFORE`	Insert before the anchor element
`AFTER`	Insert after the anchor element
`INSIDE_FIRST`	Insert as first child inside the anchor
`INSIDE_LAST`	Insert as last child inside the anchor

Insert text at a specific position inside a paragraph

# "Charly has a clear fur." → "Charly has a clear orange fur."
DocumentEditor   operation=APPEND_TEXT_BEFORE
                 elementIds=p-3
                 text_to_be_replaced=fur
                 text="orange "

Insert a whole new element after another

DocumentEditor   operation=APPEND_ELEMENT_AFTER
                 elementIds=p-12
                 text=<p>See appendix A for further details.</p>

Reset a document to its original state

DocumentVersionManager   operation=RESET
                         doc_or_chapter_id=docid-16

Delete all version history

DocumentVersionManager   operation=DELETE_VERSIONS
                         doc_or_chapter_id=docid-16

Document Node Attributes (Neo4j `:Document`)

Attribute Reference

Attribute	Description
`type`	Identifies the original file format. Controls parsing, editing, and filesystem-write behaviour. See Document Types below.
`text`	The raw extracted content as ingested — or the back-converted plain representation after edits. Back-conversion is applied based on `type` on every save: `Text`/`Csv` → HTML stripped; `MD` → converted to Markdown; `Html` → kept as HTML.
`enhanced_text`	An HTML rendering of `text` with structural tags and unique element IDs added (e.g. `<p id="p-3">…</p>`). All `DocumentEditor` operations mutate this field only.

Document Types

Defined by DocumentType in src/core/base/enums.py:

Enum member	Neo4j `type` value	File extension	Filesystem-writable
`DocumentType.PDF`	`"PDF"`	`.pdf`	No
`DocumentType.TEXT`	`"Text"`	`.txt`	Yes
`DocumentType.IMAGE`	`"Image"`	`.png` / `.jpg` / …	No
`DocumentType.DOCX`	`"Docx"`	`.docx`	No
`DocumentType.XML`	`"Xml"`	`.xml`	No
`DocumentType.HTML`	`"Html"`	`.html`	Yes
`DocumentType.CSV`	`"Csv"`	`.csv`	Yes
`DocumentType.OTHER`	`"Other"`	—	No
`DocumentType.MD`	`"MD"`	`.md`	Yes

Content consistency after edits

After any edit operation, all three representations are kept consistent by save_enhanced_content() in documents_service.py:

`type` value	`enhanced_text`	`text` after edit	Filesystem file
`Text` / `txt`	HTML with element IDs	Plain text (HTML stripped)	Plain text
`MD` / `markdown`	HTML with element IDs	Markdown (converted from HTML)	Markdown
`Html`	HTML with element IDs	Same as `enhanced_text`	HTML
`Csv`	HTML with element IDs	Plain text (HTML stripped)	Plain text
`PDF` / `Docx` / `Image` / `Xml` / `Other`	HTML with element IDs	(not updated)	(not written)