What This Library Does

AgenticChunkingHelpers is a stateless C# External Logic library for OutSystems Developer Cloud. It handles the text processing work on either side of your AI Gateway calls for Level 5 Agentic Chunking workflows.

The library exposes three Server Actions: PreChunkForExtraction, ParsePropositions, and NormaliseAgenticOutput. Each is stateless and side-effect free. The library does not call the AI Gateway, store state, or validate business rules. All of that belongs in your ODC App.

Installation

From the Forge (recommended)

The easiest way to install this library is through the Agentic Chunking ODC component on the OutSystems Forge. Installing that component automatically installs AgenticChunkingHelpers as a dependency. No separate steps required.

Manual installation from GitHub

If you need to install the library directly:

1. Download the latest AgenticChunkingLibrary.zip from the Releases page on GitHub.
2. Open ODC Portal.
3. Go to External Logic.
4. Click Upload and select AgenticChunkingLibrary.zip.
5. Wait for validation and publishing to complete.

The library will appear as AgenticChunkingHelpers in your ODC tenant's External Logic list.

Actions

PreChunkForExtraction

Call this before your first AI Gateway call. It splits a large source text into token-safe batches, respecting paragraph and sentence boundaries so the extraction model receives coherent input.

Input parameters

• sourceText (Text): The full source text to batch. Pass the concatenated text of all input chunks.
• maxTokensPerBatch (Integer): Maximum tokens per batch. Use 2000 as a safe default. The library estimates 1 token per 4 characters.

Output

• List of Text: Ordered list of batch strings. Each batch is within the token limit. Iterate this list and call your extraction AI Gateway action once per batch.

Configuration notes

Set maxTokensPerBatch conservatively. The 2000 default leaves headroom for the system prompt and user message wrapper your AI Gateway call adds around the batch text. If your extraction system prompt is longer than average, reduce this value.

ParsePropositions

Call this immediately after each extraction AI Gateway call, before moving to the next batch. It parses the raw response string into a clean list of proposition strings.

The action handles the response variations the model commonly produces: Markdown code fences around the JSON array, doubled quotes from ODC's string escaping, and outer-quoted responses. You do not need to pre-process the response before passing it in.

Input parameters

• rawExtractionJson (Text): The raw Content string from the AI Gateway response. Pass Response.Messages[0].Content directly.

Output

• List of Text: Clean proposition strings. Returns an empty list if the response cannot be parsed.

Expected AI Gateway response shape

The extraction prompt must instruct the model to return a plain JSON array of strings with no preamble and no code fences. The expected shape is:

["Proposition one.", "Proposition two.", "Proposition three."]

If the model returns anything outside this shape, ParsePropositions returns an empty list. Check the list length before accumulating into your AllPropositions list.

NormaliseAgenticOutput

Call this after your grouping AI Gateway call. It parses the raw grouping response and maps it to typed AgenticChunk structures ready for use in ODC.

Input parameters

• rawGroupingJson (Text): The raw Content string from the grouping AI Gateway response. Pass Response.Messages[0].Content directly.
• documentId (Text): A document identifier you supply. This is embedded in each ChunkId as the prefix (for example DOC-001 produces chunk IDs DOC-001-0001, DOC-001-0002, and so on).

Output

Returns an AgenticResponse structure containing:

• Chunks (List of AgenticChunk): The thematic chunks produced by the grouping model.
• TotalChunks (Integer): Total number of chunks.
• TotalPropositions (Integer): Total propositions across all chunks.
• TotalTokenEstimate (Integer): Approximate total token count.
• IsSuccess (Boolean): True if parsing succeeded. Check this before using Chunks.
• ErrorDetail (Text): Error description when IsSuccess is false.

Each AgenticChunk contains:

• ChunkId (Text): Unique identifier in the format DocumentId-sequence (e.g. DOC-001-0001).
• DocumentId (Text): The documentId you passed in.
• ThematicCategory (Text): The category label the grouping model assigned.
• MergedContent (Text): All propositions joined by a single space. This is the field to pass to your embedding model.
• PropositionCount (Integer): Number of propositions in this chunk.
• CharacterCount (Integer): Character count of MergedContent.
• TokenEstimate (Integer): Approximate token count (CharacterCount divided by 4).
• Hash (Text): SHA-256 hash of MergedContent, prefixed with sha256-.

Expected AI Gateway response shape

The grouping prompt must instruct the model to return a JSON array of objects. Each object must have a category field (string) and a facts field (array of strings). The expected shape is:

[{"category": "Cloud Infrastructure", "facts": ["Kubernetes is a container orchestration platform.", "Kubernetes automates deployment of containerised applications."]}]