agentlang 0.10.1 → 0.10.3

package/src/runtime/modules/ai.ts

@@ -26,6 +26,7 @@ import {
   asJSONSchema,
   Decision,
   fetchModule,
+  getAllDocumentsForTopics,
   getDecision,
   getGlobalRetry,
   Instance,
@@ -37,7 +38,9 @@ import {
   newInstanceAttributes,
   objectToInstanceAttributes,
   Record,
+  registerTopic as registerTopicInRegistry,
   resolveDocumentAliases,
+  resolveTopicNames,
   Retry,
 } from '../module.js';
 import { provider } from '../agents/registry.js';
@@ -70,11 +73,11 @@ import {
 } from '../agents/common.js';
 import { logger } from '../logger.js';
 import { FlowStep } from '../agents/flows.js';
-import Handlebars from 'handlebars';
 import { Statement } from '../../language/generated/ast.js';
-import { isMonitoringEnabled, TtlCache } from '../state.js';
+import { getKnowledgeGraphConfig, isMonitoringEnabled, TtlCache } from '../state.js';
 import { isNodeEnv } from '../../utils/runtime.js';
 import { getFileSystem } from '../../utils/fs-utils.js';
+import { getDocumentRetriever } from '../document-retriever.js';
 
 export const CoreAIModuleName = makeCoreModuleName('ai');
 export const AgentEntityName = 'Agent';
@@ -83,6 +86,50 @@ export const AgentLearnerType = 'learner';
 
 const AgentEvalType = 'eval';
 
+// --- Agent cancellation infrastructure ---
+
+export class AgentCancelledException extends Error {
+  constructor(chatId: string) {
+    super(`Agent cancelled for chatId: ${chatId}`);
+    this.name = 'AgentCancelledException';
+  }
+}
+
+export async function cancelAgent(chatId: string): Promise<string> {
+  const t = `${CoreAIModuleName}/${CancelledAgentEntity}`;
+  await parseAndEvaluateStatement(`{${t} {chatId "${chatId}"}, @upsert}`);
+  return `Cancellation requested for chatId: ${chatId}`;
+}
+
+export async function checkCancelled(chatId: string): Promise<void> {
+  if (!chatId) return;
+  try {
+    const results: Instance[] = await parseAndEvaluateStatement(
+      `{${CoreAIModuleName}/${CancelledAgentEntity} {chatId? "${chatId}"}}`
+    );
+    if (results && results.length > 0) {
+      await parseAndEvaluateStatement(
+        `purge {${CoreAIModuleName}/${CancelledAgentEntity} {chatId? "${chatId}"}}`
+      );
+      throw new AgentCancelledException(chatId);
+    }
+  } catch (err: any) {
+    if (err instanceof AgentCancelledException) throw err;
+    logger.debug(`checkCancelled DB error for ${chatId}: ${err}`);
+  }
+}
+
+export async function clearCancellation(chatId: string): Promise<void> {
+  if (!chatId) return;
+  try {
+    await parseAndEvaluateStatement(
+      `purge {${CoreAIModuleName}/${CancelledAgentEntity} {chatId? "${chatId}"}}`
+    );
+  } catch (err: any) {
+    logger.debug(`clearCancellation DB error for ${chatId}: ${err}`);
+  }
+}
+
 export default `module ${CoreAIModuleName}
 
 import "./modules/ai.js" @as ai
@@ -101,12 +148,14 @@ entity ${AgentEntityName} {
     stateless Boolean @default(false),
     instruction String @optional,
     tools String @optional, // comma-separated list of tool names
-    documents String @optional, // comma-separated list of document names
+    documents String @optional, // list of document names
+    topics String @optional, // list of topic names
     channels String @optional, // comma-separated list of channel names
     role String @optional,
     flows String @optional,
     validate String @optional,
     retry String @optional,
+    saveResponseAs String @optional,
     llm String
 }
 
@@ -147,6 +196,15 @@ workflow processDoc {
   await ai.fetchAndCreateDocument(doc.title, doc.url, doc.retrievalConfig, doc.embeddingConfig)
 }
 
+event topic {
+  name String,
+  documents String @optional // comma-separated or array of document titles
+}
+
+workflow processTopic {
+  await ai.registerTopic(topic.name, topic.documents)
+}
+
 entity Directive {
   id UUID @id @default(uuid()),
   agentFqName String @indexed,
@@ -202,6 +260,10 @@ entity AgentFlowStep {
     suspensionId String
 }
 
+entity CancelledAgent {
+    chatId String @id
+}
+
 @public event restartFlow {
   chatId String,
   step String,
@@ -214,6 +276,14 @@ workflow restartFlow {
     {${DefaultModuleName}/restartSuspension {id fs.suspensionId, data restartFlow.userInput}}
   }
 }
+
+@public event cancelAgent {
+  chatId String
+}
+
+workflow cancelAgent {
+  await ai.cancelAgent(cancelAgent.chatId)
+}
 `;
 
 enum AgentCacheType {
@@ -317,12 +387,14 @@ export class AgentInstance {
   type: string = 'chat';
   tools: string | undefined;
   documents: string | undefined;
+  topics: string | undefined;
   channels: string | undefined;
   runWorkflows: boolean = true;
   role: string | undefined;
   flows: string | undefined;
   validate: string | undefined;
   retry: string | undefined;
+  saveResponseAs: string | undefined;
   stateless: boolean = false;
   private toolsArray: string[] | undefined = undefined;
   private hasModuleTools = false;
@@ -645,7 +717,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     const spad = env.getScratchPad();
     if (spad !== undefined && Object.keys(spad).length > 0) {
       if (finalInstruction.indexOf('{{') > 0) {
-        return AgentInstance.maybeRewriteTemplatePatterns(spad, finalInstruction, env);
+        return env.maybeRewriteTemplatePatterns(finalInstruction, spad);
       } else {
         const ctx = JSON.stringify(spad);
         return `${finalInstruction}\nSome additional context:\n${ctx}`;
@@ -657,6 +729,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
   }
 
   private static UserTag = 'user';
+  private static FileTag = 'file';
 
   private async getFullInstructions(
     env: Environment,
@@ -670,13 +743,21 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     }
   }
 
-  private static maybeRewriteTemplatePatterns(
-    scratchPad: any,
-    instruction: string,
-    env: Environment
-  ): string {
-    const templ = Handlebars.compile(env.rewriteTemplateMappings(instruction));
-    return templ(scratchPad);
+  private async maybeFillInFileContents(instructions: string, env: Environment): Promise<string> {
+    const chatId = env.getActiveChatId();
+    const FC = '$FC';
+    if (chatId && instructions.indexOf(`<${AgentInstance.FileTag}>`) > 0) {
+      const ext = extractAndRemoveAllXmlTaggedText(instructions, AgentInstance.FileTag, FC);
+      if (ext.extracted) {
+        instructions = ext.updatedText;
+        for (let i = 0; i < ext.extracted.length; ++i) {
+          const fileName = ext.extracted[i];
+          const contents = await loadLocalAgentResult(chatId, fileName);
+          if (contents) instructions = instructions.replace(FC, contents);
+        }
+      }
+    }
+    return instructions;
   }
 
   maybeValidateJsonResponse(response: string | undefined): object | undefined {
@@ -812,6 +893,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     const p = await findProviderForLLM(this.llm, env);
     const agentName = this.name;
     const chatId = env.getAgentChatId() || agentName;
+    await checkCancelled(chatId);
     let isplnr = this.isPlanner();
     const isflow = !isplnr && this.isFlowExecutor();
     const iseval = !isplnr && !isflow && this.isEvaluator();
@@ -875,7 +957,8 @@ Only return a pure JSON object with no extra text, annotations etc.`;
         }
         let tmpMsg = message;
         if (extractedText?.extracted) {
-          tmpMsg = `${tmpMsg}\n${extractedText.extracted.join('\n')}`;
+          const s = await this.maybeFillInFileContents(extractedText.extracted.join('\n'), env);
+          tmpMsg = `${tmpMsg}\n${s}`;
         }
         const hmsg = await this.maybeAddRelevantDocuments(
           this.maybeAddFlowContext(tmpMsg, env),
@@ -909,7 +992,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
         let response: AIResponse = await p.invoke(msgs, externalToolSpecs);
         const v = this.getValidationEvent();
         if (v) {
-          response = await this.handleValidation(response, v, msgs, p);
+          response = await this.handleValidation(response, v, msgs, p, chatId);
         }
         if (!iseval)
           await AgentInstance.maybeEvaluateResponse(
@@ -927,6 +1010,13 @@ Only return a pure JSON object with no extra text, annotations etc.`;
           await saveAgentChatSession(chatId, msgs, env);
         }
         if (monitoringEnabled) env.setMonitorEntryLlmResponse(response.content);
+        if (monitoringEnabled && response.sysMsg.usage_metadata) {
+          const u = response.sysMsg.usage_metadata;
+          env.setMonitorEntryLlmTokenUsage(u.input_tokens, u.output_tokens, u.total_tokens);
+        }
+        if (this.saveResponseAs) {
+          await saveAgentResponse(this.saveResponseAs, response.content, env);
+        }
         env.setLastResult(response.content);
       } catch (err: any) {
         logger.error(`Error while invoking ${agentName} - ${err}`);
@@ -987,7 +1077,8 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     response: AIResponse,
     validationEventName: string,
     msgs: BaseMessage[],
-    provider: AgentServiceProvider
+    provider: AgentServiceProvider,
+    chatId?: string
   ): Promise<AIResponse> {
     let r: Instance = await this.invokeValidator(response, validationEventName);
     const status = r.lookup('status');
@@ -999,6 +1090,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
         let attempt = 0;
         let delay = this.retryObj.getNextDelayMs(attempt);
         while (delay) {
+          if (chatId) await checkCancelled(chatId);
           msgs.push(assistantMessage(resp.content));
           const vs = JSON.stringify(r.asSerializableObject());
           msgs.push(
@@ -1050,93 +1142,139 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     return result;
   }
 
-  private async maybeAddRelevantDocuments(message: string, env: Environment): Promise<string> {
-    if (this.documents && this.documents.length > 0) {
-      try {
-        const docNames = this.documents.split(',').map(d => d.trim());
-        const docTitles = resolveDocumentAliases(docNames);
+  private async maybeAddRelevantDocuments(message: string, _env: Environment): Promise<string> {
+    const hasDocuments = this.documents && this.documents.length > 0;
+    const hasTopics = this.topics && this.topics.length > 0;
 
-        const searchQuery = message;
+    if (!hasDocuments && !hasTopics) {
+      return message;
+    }
 
-        try {
-          const semanticResult: any[] = await parseHelper(
-            `{${CoreAIModuleName}/Document {content? "${searchQuery.replace(/"/g, '\\"')}"}}`,
-            env
-          );
+    try {
+      let containerTags: string[] = [];
+      let topicDocumentTitles: string[] = [];
 
-          if (semanticResult && semanticResult.length > 0) {
-            const docs: Instance[] = [];
-            for (const doc of semanticResult) {
-              const docTitle = doc.lookup ? doc.lookup('title') : doc.title;
-              if (AgentInstance.docTitlesMatch(docTitle, docTitles)) {
-                docs.push(
-                  doc instanceof Instance
-                    ? doc
-                    : Instance.newWithAttributes(doc, new Map(Object.entries(doc)))
-                );
-              }
-            }
+      if (hasTopics) {
+        const topicNames = resolveTopicNames(this.topics!);
+        containerTags = topicNames;
+        topicDocumentTitles = getAllDocumentsForTopics(topicNames);
+      }
 
-            if (docs.length > 0) {
-              return message.concat('\n\nRelevant context from documents:\n').concat(
-                docs
-                  .map((v: Instance) => {
-                    return `Document: ${v.lookup('title')}\n${v.lookup('content') as string}`;
-                  })
-                  .join('\n\n---\n\n')
-              );
-            }
-          }
-        } catch (semanticErr) {
-          logger.debug(
-            `Semantic search is not available, falling back to title-based filtering: ${semanticErr}`
-          );
-        }
+      if (containerTags.length === 0) {
+        containerTags = [this.getFqName()];
+      }
 
-        const result: any[] = await parseHelper(`{${CoreAIModuleName}/Document? {}}`, env);
-        if (result && result.length > 0) {
-          const docs: Instance[] = [];
-          for (let i = 0; i < result.length; ++i) {
-            const v: any = result[i];
-            const docTitle: string | undefined = AgentInstance.getDocumentTitle(v);
-
-            if (docTitle && docTitles.includes(docTitle)) {
-              if (v instanceof Instance) {
-                docs.push(v);
-              }
-            }
-          }
+      let documentTitles: string[] = [];
+      let documentRefs: string[] = [];
 
-          if (docs.length > 0) {
-            return message.concat('\n\nRelevant context from documents:\n').concat(
-              docs
-                .map((v: Instance) => {
-                  return v.lookup('content') as string;
-                })
-                .join('\n\n')
-            );
+      if (hasDocuments) {
+        const documentEntries = this.documents!.split(',')
+          .map(d => d.trim())
+          .filter(Boolean);
+        documentTitles = resolveDocumentAliases(documentEntries);
+        documentRefs = documentEntries.filter(d => d.startsWith('document-service://'));
+      }
+
+      const allDocumentTitles = [...new Set([...topicDocumentTitles, ...documentTitles])];
+
+      const kgConfig = getKnowledgeGraphConfig();
+      const serviceUrl = kgConfig?.serviceUrl?.trim() || process.env.KNOWLEDGE_SERVICE_URL || null;
+
+      if (serviceUrl) {
+        return await this.queryRemoteKnowledgeService(
+          message,
+          serviceUrl,
+          containerTags,
+          allDocumentTitles,
+          documentRefs
+        );
+      }
+
+      // Local mode: embed documents into pgvector/lancedb and query
+      const retriever = getDocumentRetriever();
+      const aiModule = isModule(DefaultModuleName + '.ai')
+        ? fetchModule(DefaultModuleName + '.ai')
+        : null;
+      if (aiModule) {
+        for (const title of allDocumentTitles) {
+          const url = aiModule.getDocument(title);
+          if (url) {
+            await retriever.processDocument(title, url);
           }
         }
-      } catch (err) {
-        logger.debug(`Error retrieving documents: ${err}`);
       }
+
+      const contextString = await retriever.query(
+        message,
+        allDocumentTitles.length > 0 ? allDocumentTitles : undefined,
+        10
+      );
+
+      if (contextString.trim().length > 0) {
+        return message.concat('\n\nRelevant context from documents:\n').concat(contextString);
+      }
+    } catch (err) {
+      logger.debug(`[KNOWLEDGE] Knowledge retrieval failed: ${err}`);
     }
+
     return message;
   }
 
-  private static docTitlesMatch(title: string | undefined, docNames: string[]): boolean {
-    return title !== undefined && docNames.includes(title);
-  }
+  private async queryRemoteKnowledgeService(
+    message: string,
+    serviceUrl: string,
+    containerTags: string[],
+    documentTitles: string[],
+    documentRefs: string[]
+  ): Promise<string> {
+    const options = {
+      chunkLimit: 10,
+      entityLimit: 20,
+      includeChunks: true,
+      includeEntities: true,
+      includeEdges: true,
+      documentTitles: documentTitles.length > 0 ? documentTitles : undefined,
+      documentRefs: documentRefs.length > 0 ? documentRefs : undefined,
+    };
 
-  private static getDocumentTitle(doc: any): string | undefined {
-    if (typeof doc.lookup === 'function') {
-      return doc.lookup('title') as string | undefined;
-    } else if (doc.attributes) {
-      return doc.attributes.get('title') as string | undefined;
-    } else if (doc.title) {
-      return doc.title;
+    let response = await fetch(`${serviceUrl}/api/knowledge/query`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query: message, containerTags, ...options }),
+    });
+
+    if (!response.ok) {
+      response = await fetch(`${serviceUrl}/knowledge.core/ApiKnowledgeQuery`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          queryText: message,
+          containerTagsJson: JSON.stringify(containerTags),
+          documentTitlesJson: JSON.stringify(options.documentTitles || []),
+          documentRefsJson: JSON.stringify(options.documentRefs || []),
+          optionsJson: JSON.stringify({
+            includeChunks: options.includeChunks,
+            includeEntities: options.includeEntities,
+            includeEdges: options.includeEdges,
+            chunkLimit: options.chunkLimit,
+            entityLimit: options.entityLimit,
+          }),
+        }),
+      });
     }
-    return undefined;
+
+    if (response.ok) {
+      const rawPayload: any = await response.json();
+      const first = Array.isArray(rawPayload) ? rawPayload[0] : rawPayload;
+      const payload =
+        first && typeof first === 'object' && first.KnowledgeQuery ? first.KnowledgeQuery : first;
+      const contextString = payload?.contextString || '';
+      if (contextString.trim().length > 0) {
+        return message.concat('\n\nRelevant context from documents:\n').concat(contextString);
+      }
+    }
+
+    return message;
   }
 
   private static ToolsCache = new Map<string, string>();
@@ -1443,20 +1581,15 @@ export async function processAgentLearning(
 const LocalAgentgFlow = true;
 const LocalFlowStepsRootDirName = 'flows';
 const AgentFlowStep = 'AgentFlowStep';
+const CancelledAgentEntity = 'CancelledAgent';
 
 export async function saveFlowStepResultLocally(
   chatId: string,
   step: string,
   result: string,
-  suspensionId: string
-): Promise<Instance | undefined> {
+  suspensionId?: string | undefined
+): Promise<string> {
   const fs = await getFileSystem();
-  const attrs = newInstanceAttributes()
-    .set('chatId', chatId)
-    .set('step', step)
-    .set('result', result)
-    .set('suspensionId', suspensionId);
-  const inst = makeInstance(CoreAIModuleName, AgentFlowStep, attrs);
   const rootDirName = LocalFlowStepsRootDirName;
   if (!(await fs.exists(rootDirName))) {
     await fs.mkdir(rootDirName);
@@ -1469,8 +1602,18 @@ export async function saveFlowStepResultLocally(
   if (await fs.exists(fileName)) {
     await fs.unlink(fileName);
   }
-  await fs.writeFile(fileName, JSON.stringify(inst.attributesAsObject(true)));
-  return inst;
+  let s = result;
+  if (suspensionId) {
+    const attrs = newInstanceAttributes()
+      .set('chatId', chatId)
+      .set('step', step)
+      .set('result', result)
+      .set('suspensionId', suspensionId);
+    const inst = makeInstance(CoreAIModuleName, AgentFlowStep, attrs);
+    s = JSON.stringify(inst.attributesAsObject(true));
+  }
+  await fs.writeFile(fileName, s);
+  return s;
 }
 
 export async function saveFlowStepResult(
@@ -1479,9 +1622,10 @@ export async function saveFlowStepResult(
   result: string,
   suspensionId: string,
   env: Environment
-): Promise<Instance | undefined> {
+): Promise<boolean> {
   if (LocalAgentgFlow) {
-    return await saveFlowStepResultLocally(chatId, step, result, suspensionId);
+    await saveFlowStepResultLocally(chatId, step, result, suspensionId);
+    return true;
   } else {
     const t = `${CoreAIModuleName}/${AgentFlowStep}`;
     try {
@@ -1495,11 +1639,11 @@ export async function saveFlowStepResult(
         undefined,
         env
       );
-      if (isInstanceOfType(inst, t)) return inst;
-      else return undefined;
+      if (isInstanceOfType(inst, t)) return true;
+      else return false;
     } catch (reason: any) {
       logger.error(`failed to save flow result for step ${step} - ${reason}`);
-      return undefined;
+      return false;
     }
   }
 }
@@ -1537,10 +1681,10 @@ export async function loadFlowStepResults(chatId: string): Promise<Instance[]> {
   }
 }
 
-export async function loadLocalFlowStep(
+export async function loadLocalAgentResult(
   chatId: string,
   step: string
-): Promise<Instance | undefined> {
+): Promise<string | undefined> {
   const fs = await getFileSystem();
   const dirName = `${LocalFlowStepsRootDirName}/${chatId}`;
   if (await fs.exists(dirName)) {
@@ -1548,10 +1692,7 @@ export async function loadLocalFlowStep(
     for (let i = 0; i < fileNames.length; ++i) {
       const fileName = fileNames[i];
       if (fileName === step) {
-        const attrs = objectToInstanceAttributes(
-          JSON.parse(await fs.readFile(`${dirName}/${fileName}`))
-        );
-        return makeInstance(CoreAIModuleName, AgentFlowStep, attrs);
+        return await fs.readFile(`${dirName}/${fileName}`);
       }
     }
     return undefined;
@@ -1560,6 +1701,19 @@ export async function loadLocalFlowStep(
   }
 }
 
+export async function loadLocalFlowStep(
+  chatId: string,
+  step: string
+): Promise<Instance | undefined> {
+  const contents = await loadLocalAgentResult(chatId, step);
+  if (contents) {
+    const attrs = objectToInstanceAttributes(JSON.parse(contents));
+    return makeInstance(CoreAIModuleName, AgentFlowStep, attrs);
+  } else {
+    return undefined;
+  }
+}
+
 export async function loadFlowStep(chatId: string, step: string): Promise<Instance | undefined> {
   if (LocalAgentgFlow) {
     return await loadLocalFlowStep(chatId, step);
@@ -1580,6 +1734,72 @@ export async function loadFlowStep(chatId: string, step: string): Promise<Instan
   }
 }
 
+export async function registerTopic(
+  name: string,
+  documents: string | undefined,
+  _env: Environment
+): Promise<any> {
+  // Register in local registry
+  registerTopicInRegistry(name, documents ?? undefined);
+
+  // Sync to knowledge service if configured
+  const kgConfig = getKnowledgeGraphConfig();
+  const serviceUrl = kgConfig?.serviceUrl?.trim() || process.env.KNOWLEDGE_SERVICE_URL || null;
+
+  if (serviceUrl) {
+    try {
+      // Parse document list
+      const docList = documents
+        ? documents
+            .split(',')
+            .map(d => d.trim())
+            .filter(Boolean)
+        : [];
+
+      // Create or update topic in knowledge service
+      let response = await fetch(`${serviceUrl}/api/knowledge/topics`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          name,
+          description: `Topic ${name} with ${docList.length} documents`,
+          documentTitles: docList,
+        }),
+      });
+
+      if (!response.ok) {
+        // Fallback to Agentlang entity path for deployed knowledge-service
+        response = await fetch(`${serviceUrl}/knowledge.core/Topic`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            name,
+            description: `Topic ${name} with ${docList.length} documents`,
+            type: 'manual',
+            documentCount: docList.length,
+          }),
+        });
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger.debug(`[KNOWLEDGE] Failed to sync topic to service: ${errorText}`);
+      } else {
+        logger.debug(`[KNOWLEDGE] Synced topic "${name}" to knowledge service`);
+      }
+    } catch (err) {
+      // Don't fail topic registration if service sync fails
+      logger.debug(`[KNOWLEDGE] Error syncing topic to service: ${err}`);
+    }
+  }
+
+  return { topic: { name, documents: documents ?? '' } };
+}
+
 export async function fetchAndCreateDocument(
   title: string,
   url: string,
@@ -1639,3 +1859,17 @@ export async function fetchAndCreateDocument(
     throw new Error(`Failed to fetch document: ${title} from ${url}`);
   }
 }
+
+export async function saveAgentResponse(
+  fileName: string,
+  response: string,
+  env: Environment
+): Promise<string> {
+  const chatId = env.getActiveChatId();
+  if (chatId) {
+    await saveFlowStepResultLocally(chatId, fileName, response);
+  } else {
+    logger.warn(`No chatId set, ${fileName} was not saved.`);
+  }
+  return response;
+}

package/src/runtime/modules/core.ts

@@ -749,5 +749,9 @@ export function migrationDowns(inst: Instance): string[] | undefined {
 
 export async function doRawQuery(q: any): Promise<any> {
   const qs = objectToQueryPattern(q);
-  return await parseAndEvaluateStatement(qs);
+  const result = await parseAndEvaluateStatement(qs);
+  return {
+    query: qs,
+    result: result.map((res: any) => (res.attributes ? Object.fromEntries(res.attributes) : res)),
+  };
 }