Studio Backend

Knowledge Processing

A knowledge source is a document or a web page an agent can search during a conversation. The platform turns it into text chunks and embeddings; the engine searches those embeddings when the agent needs them. The specification of a source lives in the project document (Asset Specifications); the processing is in KnowledgeService, AzureParserService, BasicParserService and KnowledgeEmbeddingService.

Source Types

Type Behavior

Type	Behavior
`file`	An uploaded document. Supported extensions: `pdf`, `doc`, `docx`, `pptx`, `xlsx`, `html`, `jpg`, `jpeg`, `png`, `tiff` (Document Intelligence) and `csv`, `txt` (plain parser).
`url`	A public web page. Only the page at the URL is fetched — there is no crawling — and it must be served as `text/html`.
`url` with `live`	Nothing is ingested; the engine fetches the page whenever the knowledge is used, so the agent always sees its current content.

file

An uploaded document. Supported extensions: pdf, doc, docx, pptx, xlsx, html, jpg, jpeg, png, tiff (Document Intelligence) and csv, txt (plain parser).

url

A public web page. Only the page at the URL is fetched — there is no crawling — and it must be served as text/html.

url with live

Nothing is ingested; the engine fetches the page whenever the knowledge is used, so the agent always sees its current content.

Every source has the retrieval settings topK (how many chunks a search returns), similarity (the minimum score) and language, and the isGlobal flag that decides whether all agents of the project get it.

Ingestion

Files are uploaded with POST /api/v1/project/{projectId}/knowledgeSpecifications/file (multipart); web pages are added with POST .../knowledgeSpecifications/url. The MCP server’s upload_knowledge_file hands out a one-time upload link that ends in the same pipeline.

Specification — the source is added to the project with a generated ref.
Parsing — the parser is chosen by file extension:
- AzureParserService sends the document to Azure AI Document Intelligence (prebuilt-layout) and builds chunks from the returned layout: paragraphs are grouped by their section path, each chunk is prefixed with that path and limited to promethist.parser.max-chunk-size characters (2000), and keeps the page and position it came from. When Document Intelligence rejects a Word document, Apache Tika converts it to HTML as a fallback.
- BasicParserService reads csv and txt directly.
- A web page is fetched by WebService, sanitized with Jsoup and parsed as html.
Description — a language-model call summarizes the chunks into a description and detects their language. A description the user wrote is kept.
Embedding — KnowledgeEmbeddingService adds the chunks to the Elasticsearch vector store of Spring AI in batches of 50. The embeddings are computed with OpenAI’s text-embedding-ada-002, and every chunk carries the metadata knowledgeRef and projectRef.
Storage — the chunks (the first 200) and the description are saved as a Knowledge document, and the specification is updated with the detected description and language.

Progress is reported to the caller as ProgressInformation elements — stages Initializing, Uploading, Parsing, Indexing (with the fraction done), and finally Finished or Failed. When the ingestion of a new source fails, the source is removed from the project again and the failure is reported with its reason — for documents Document Intelligence rejects: "The document could not be parsed. Please make sure the file is not corrupted or password-protected and try again."

Editing a source’s name, description or isGlobal flag (PUT /api/v1/project/{projectId}/knowledgeSpecification/{ref}) does not re-process it. Uploading a new file or re-fetching a URL (PUT .../knowledgeSpecifications/{file|url}/{ref}) runs the pipeline again and replaces the stored chunks.

Retrieval

Retrieval happens in the engine (KnowledgeMemory in promethist-common): it embeds the query and runs a vector search over the same Elasticsearch index, filtered to the source’s knowledgeRef and projectRef, returning at most topK chunks above the similarity threshold. The index name (spring.ai.vectorstore.elasticsearch.index-name) and the embedding model therefore have to be the same on both sides.

A source is offered to every agent of the project when it is global; otherwise only to agents whose instructions reference it as @knowledge:{ref};.

Reading What Was Stored

GET /api/v1/project/{projectId}/knowledge/{ref} returns the stored chunks with their metadata, which the Studio shows on the knowledge detail page and which the MCP tool get_knowledge returns, so that the extraction quality of a document can be judged before an agent relies on it.