totem-llm 0.1.0

package/server/utils/agentFlows/executors/llm-instruction.js

@@ -0,0 +1,47 @@
+/**
+ * Execute an LLM instruction flow step
+ * @param {Object} config Flow step configuration
+ * @param {{introspect: Function, logger: Function}} context Execution context with introspect function
+ * @returns {Promise<string>} Processed result
+ */
+async function executeLLMInstruction(config, context) {
+  const { instruction, resultVariable } = config;
+  const { introspect, logger, aibitat } = context;
+  logger(
+    `\x1b[43m[AgentFlowToolExecutor]\x1b[0m - executing LLM Instruction block`
+  );
+  introspect(`Processing data with LLM instruction...`);
+
+  try {
+    logger(
+      `Sending request to LLM (${aibitat.defaultProvider.provider}::${aibitat.defaultProvider.model})`
+    );
+    introspect(`Sending request to LLM...`);
+
+    // Ensure the input is a string since we are sending it to the LLM direct as a message
+    let input = instruction;
+    if (typeof input === "object") input = JSON.stringify(input);
+    if (typeof input !== "string") input = String(input);
+
+    let completion;
+    const provider = aibitat.getProviderForConfig(aibitat.defaultProvider);
+    if (provider.supportsAgentStreaming) {
+      completion = await provider.stream(
+        [{ role: "user", content: input }],
+        [],
+        null
+      );
+    } else {
+      completion = await provider.complete([{ role: "user", content: input }]);
+    }
+
+    introspect(`Successfully received LLM response`);
+    if (resultVariable) config.resultVariable = resultVariable;
+    return completion.textResponse;
+  } catch (error) {
+    logger(`LLM processing failed: ${error.message}`, error);
+    throw new Error(`LLM processing failed: ${error.message}`);
+  }
+}
+
+module.exports = executeLLMInstruction;

package/server/utils/agentFlows/executors/web-scraping.js

@@ -0,0 +1,110 @@
+/**
+ * Execute a web scraping flow step
+ * @param {Object} config Flow step configuration
+ * @param {Object} context Execution context with introspect function
+ * @returns {Promise<string>} Scraped content
+ */
+async function executeWebScraping(config, context) {
+  const { CollectorApi } = require("../../collectorApi");
+  const { TokenManager } = require("../../helpers/tiktoken");
+  const Provider = require("../../agents/aibitat/providers/ai-provider");
+  const { summarizeContent } = require("../../agents/aibitat/utils/summarize");
+
+  const { url, captureAs = "text", enableSummarization = true } = config;
+  const { introspect, logger, aibitat } = context;
+  logger(
+    `\x1b[43m[AgentFlowToolExecutor]\x1b[0m - executing Web Scraping block`
+  );
+
+  if (!url) {
+    throw new Error("URL is required for web scraping");
+  }
+
+  const captureMode = captureAs === "querySelector" ? "html" : captureAs;
+  introspect(`Scraping the content of ${url} as ${captureAs}`);
+  const { success, content } = await new CollectorApi()
+    .getLinkContent(url, captureMode)
+    .then((res) => {
+      if (captureAs !== "querySelector") return res;
+      return parseHTMLwithSelector(res.content, config.querySelector, context);
+    });
+
+  if (!success) {
+    introspect(`Could not scrape ${url}. Cannot use this page's content.`);
+    throw new Error("URL could not be scraped and no content was found.");
+  }
+
+  introspect(`Successfully scraped content from ${url}`);
+  if (!content || content?.length === 0) {
+    introspect("There was no content to be collected or read.");
+    throw new Error("There was no content to be collected or read.");
+  }
+
+  if (!enableSummarization) {
+    logger(`Returning raw content as summarization is disabled`);
+    return content;
+  }
+
+  const tokenCount = new TokenManager(
+    aibitat.defaultProvider.model
+  ).countFromString(content);
+  const contextLimit = Provider.contextLimit(
+    aibitat.defaultProvider.provider,
+    aibitat.defaultProvider.model
+  );
+
+  if (tokenCount < contextLimit) {
+    logger(
+      `Content within token limit (${tokenCount}/${contextLimit}). Returning raw content.`
+    );
+    return content;
+  }
+
+  introspect(
+    `This page's content is way too long (${tokenCount} tokens). I will summarize it right now.`
+  );
+  const summary = await summarizeContent({
+    provider: aibitat.defaultProvider.provider,
+    model: aibitat.defaultProvider.model,
+    content,
+  });
+
+  introspect(`Successfully summarized content`);
+  return summary;
+}
+
+/**
+ * Parse HTML with a CSS selector
+ * @param {string} html - The HTML to parse
+ * @param {string|null} selector - The CSS selector to use (as text string)
+ * @param {{introspect: Function}} context - The context object
+ * @returns {Object} The parsed content
+ */
+function parseHTMLwithSelector(html, selector = null, context) {
+  if (!selector || selector.length === 0) {
+    context.introspect("No selector provided. Returning the entire HTML.");
+    return { success: true, content: html };
+  }
+
+  const Cheerio = require("cheerio");
+  const $ = Cheerio.load(html);
+  const selectedElements = $(selector);
+
+  let content;
+  if (selectedElements.length === 0) {
+    return { success: false, content: null };
+  } else if (selectedElements.length === 1) {
+    content = selectedElements.html();
+  } else {
+    context.introspect(
+      `Found ${selectedElements.length} elements matching selector: ${selector}`
+    );
+    content = selectedElements
+      .map((_, element) => $(element).html())
+      .get()
+      .join("\n");
+  }
+  return { success: true, content };
+}
+
+module.exports = executeWebScraping;

package/server/utils/agentFlows/flowTypes.js

@@ -0,0 +1,85 @@
+const FLOW_TYPES = {
+  START: {
+    type: "start",
+    description: "Initialize flow variables",
+    parameters: {
+      variables: {
+        type: "array",
+        description: "List of variables to initialize",
+      },
+    },
+  },
+  API_CALL: {
+    type: "apiCall",
+    description: "Make an HTTP request to an API endpoint",
+    parameters: {
+      url: { type: "string", description: "The URL to make the request to" },
+      method: { type: "string", description: "HTTP method (GET, POST, etc.)" },
+      headers: {
+        type: "array",
+        description: "Request headers as key-value pairs",
+      },
+      bodyType: {
+        type: "string",
+        description: "Type of request body (json, form)",
+      },
+      body: {
+        type: "string",
+        description:
+          "Request body content. If body type is json, always return a valid json object. If body type is form, always return a valid form data object.",
+      },
+      formData: { type: "array", description: "Form data as key-value pairs" },
+      responseVariable: {
+        type: "string",
+        description: "Variable to store the response",
+      },
+      directOutput: {
+        type: "boolean",
+        description:
+          "Whether to return the response directly to the user without LLM processing",
+      },
+    },
+    examples: [
+      {
+        url: "https://api.example.com/data",
+        method: "GET",
+        headers: [{ key: "Authorization", value: "Bearer 1234567890" }],
+      },
+    ],
+  },
+  LLM_INSTRUCTION: {
+    type: "llmInstruction",
+    description: "Process data using LLM instructions",
+    parameters: {
+      instruction: {
+        type: "string",
+        description: "The instruction for the LLM to follow",
+      },
+      resultVariable: {
+        type: "string",
+        description: "Variable to store the processed result",
+      },
+    },
+  },
+  WEB_SCRAPING: {
+    type: "webScraping",
+    description: "Scrape content from a webpage",
+    parameters: {
+      url: {
+        type: "string",
+        description: "The URL of the webpage to scrape",
+      },
+      resultVariable: {
+        type: "string",
+        description: "Variable to store the scraped content",
+      },
+      directOutput: {
+        type: "boolean",
+        description:
+          "Whether to return the scraped content directly to the user without LLM processing",
+      },
+    },
+  },
+};
+
+module.exports.FLOW_TYPES = FLOW_TYPES;

package/server/utils/agentFlows/index.js

@@ -0,0 +1,288 @@
+const fs = require("fs");
+const path = require("path");
+const { v4: uuidv4 } = require("uuid");
+const { FlowExecutor, FLOW_TYPES } = require("./executor");
+const { normalizePath, isWithin } = require("../files");
+const { safeJsonParse } = require("../http");
+
+/**
+ * @typedef {Object} LoadedFlow
+ * @property {string} name - The name of the flow
+ * @property {string} uuid - The UUID of the flow
+ * @property {Object} config - The flow configuration details
+ * @property {string} config.description - The description of the flow
+ * @property {Array<{type: string, config: Object, [key: string]: any}>} config.steps - The steps of the flow. Each step has at least a type and config
+ */
+
+class AgentFlows {
+  static flowsDir = process.env.STORAGE_DIR
+    ? path.join(process.env.STORAGE_DIR, "plugins", "agent-flows")
+    : path.join(process.cwd(), "storage", "plugins", "agent-flows");
+
+  constructor() {}
+
+  /**
+   * Ensure flows directory exists
+   * @returns {Boolean} True if directory exists, false otherwise
+   */
+  static createOrCheckFlowsDir() {
+    try {
+      if (fs.existsSync(AgentFlows.flowsDir)) return true;
+      fs.mkdirSync(AgentFlows.flowsDir, { recursive: true });
+      return true;
+    } catch (error) {
+      console.error("Failed to create flows directory:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Helper to get all flow files with their contents
+   * @returns {Object} Map of flow UUID to flow config
+   */
+  static getAllFlows() {
+    AgentFlows.createOrCheckFlowsDir();
+    const files = fs.readdirSync(AgentFlows.flowsDir);
+    const flows = {};
+
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const filePath = path.join(AgentFlows.flowsDir, file);
+        const content = fs.readFileSync(normalizePath(filePath), "utf8");
+        const config = JSON.parse(content);
+        const id = file.replace(".json", "");
+        flows[id] = config;
+      } catch (error) {
+        console.error(`Error reading flow file ${file}:`, error);
+      }
+    }
+
+    return flows;
+  }
+
+  /**
+   * Load a flow configuration by UUID
+   * @param {string} uuid - The UUID of the flow to load
+   * @returns {LoadedFlow|null} Flow configuration or null if not found
+   */
+  static loadFlow(uuid) {
+    try {
+      const flowJsonPath = normalizePath(
+        path.join(AgentFlows.flowsDir, `${uuid}.json`)
+      );
+      if (
+        !uuid ||
+        !fs.existsSync(flowJsonPath) ||
+        !isWithin(AgentFlows.flowsDir, flowJsonPath)
+      )
+        return null;
+      const flow = safeJsonParse(fs.readFileSync(flowJsonPath, "utf8"), null);
+      if (!flow) return null;
+
+      return {
+        name: flow.name,
+        uuid,
+        config: flow,
+      };
+    } catch (error) {
+      console.error("Failed to load flow:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Save a flow configuration
+   * @param {string} name - The name of the flow
+   * @param {Object} config - The flow configuration
+   * @param {string|null} uuid - Optional UUID for the flow
+   * @returns {Object} Result of the save operation
+   */
+  static saveFlow(name, config, uuid = null) {
+    try {
+      AgentFlows.createOrCheckFlowsDir();
+
+      if (!uuid) uuid = uuidv4();
+      const normalizedUuid = normalizePath(`${uuid}.json`);
+      const filePath = path.join(AgentFlows.flowsDir, normalizedUuid);
+      if (!isWithin(AgentFlows.flowsDir, filePath)) return null;
+
+      // Prevent saving flows with unsupported blocks or importing
+      // flows with unsupported blocks (eg: file writing or code execution on Desktop importing to Docker)
+      const supportedFlowTypes = Object.values(FLOW_TYPES).map(
+        (definition) => definition.type
+      );
+      const supportsAllBlocks = config.steps.every((step) =>
+        supportedFlowTypes.includes(step.type)
+      );
+      if (!supportsAllBlocks)
+        throw new Error(
+          "This flow includes unsupported blocks. They may not be supported by your version of AnythingLLM or are not available on this platform."
+        );
+
+      fs.writeFileSync(filePath, JSON.stringify({ ...config, name }, null, 2));
+      return { success: true, uuid };
+    } catch (error) {
+      console.error("Failed to save flow:", error);
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * List all available flows
+   * @returns {Array} Array of flow summaries
+   */
+  static listFlows() {
+    try {
+      const flows = AgentFlows.getAllFlows();
+      return Object.entries(flows).map(([uuid, flow]) => ({
+        name: flow.name,
+        uuid,
+        description: flow.description,
+        active: flow.active !== false,
+      }));
+    } catch (error) {
+      console.error("Failed to list flows:", error);
+      return [];
+    }
+  }
+
+  /**
+   * Delete a flow by UUID
+   * @param {string} uuid - The UUID of the flow to delete
+   * @returns {Object} Result of the delete operation
+   */
+  static deleteFlow(uuid) {
+    try {
+      const filePath = normalizePath(
+        path.join(AgentFlows.flowsDir, `${uuid}.json`)
+      );
+      if (!fs.existsSync(filePath) || !isWithin(AgentFlows.flowsDir, filePath))
+        throw new Error(`Flow ${uuid} not found`);
+      fs.rmSync(filePath);
+      return { success: true };
+    } catch (error) {
+      console.error("Failed to delete flow:", error);
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Execute a flow by UUID
+   * @param {string} uuid - The UUID of the flow to execute
+   * @param {Object} variables - Initial variables for the flow
+   * @param {Object} aibitat - The aibitat instance from the agent handler
+   * @returns {Promise<Object>} Result of flow execution
+   */
+  static async executeFlow(uuid, variables = {}, aibitat = null) {
+    const flow = AgentFlows.loadFlow(uuid);
+    if (!flow) throw new Error(`Flow ${uuid} not found`);
+    const flowExecutor = new FlowExecutor();
+    return await flowExecutor.executeFlow(flow, variables, aibitat);
+  }
+
+  /**
+   * Get all active flows as plugins that can be loaded into the agent
+   * @returns {string[]} Array of flow names in @@flow_{uuid} format
+   */
+  static activeFlowPlugins() {
+    const flows = AgentFlows.getAllFlows();
+    return Object.entries(flows)
+      .filter(([_, flow]) => flow.active !== false)
+      .map(([uuid]) => `@@flow_${uuid}`);
+  }
+
+  /**
+   * Sanitize a flow name into a valid OpenAI-compatible tool name.
+   * Must match ^[a-zA-Z0-9_-]{1,64}$
+   * @param {string} flowName - The human-readable flow name
+   * @returns {string|null} Sanitized tool name, or null if empty after sanitization
+   */
+  static sanitizeToolName(flowName) {
+    const sanitized = flowName
+      .toLowerCase()
+      .trim()
+      .replace(/\s+/g, "_")
+      .replace(/[^a-z0-9_-]/g, "")
+      .replace(/_+/g, "_")
+      .replace(/^[-_]+|[-_]+$/g, "");
+    if (!sanitized) return null;
+    return sanitized.slice(0, 64);
+  }
+
+  /**
+   * Load a flow plugin by its UUID
+   * @param {string} uuid - The UUID of the flow to load
+   * @returns {Object|null} Plugin configuration or null if not found
+   */
+  static loadFlowPlugin(uuid) {
+    const flow = AgentFlows.loadFlow(uuid);
+    if (!flow) return null;
+
+    const startBlock = flow.config.steps?.find((s) => s.type === "start");
+    const variables = startBlock?.config?.variables || [];
+    const toolName = AgentFlows.sanitizeToolName(flow.name) || `flow_${uuid}`;
+
+    return {
+      name: toolName,
+      description: `Execute agent flow: ${flow.name}`,
+      plugin: (_runtimeArgs = {}) => ({
+        name: toolName,
+        description:
+          flow.config.description || `Execute agent flow: ${flow.name}`,
+        setup: (aibitat) => {
+          aibitat.function({
+            name: toolName,
+            description:
+              flow.config.description || `Execute agent flow: ${flow.name}`,
+            parameters: {
+              type: "object",
+              properties: variables.reduce((acc, v) => {
+                if (v.name) {
+                  acc[v.name] = {
+                    type: "string",
+                    description:
+                      v.description || `Value for variable ${v.name}`,
+                  };
+                }
+                return acc;
+              }, {}),
+            },
+            handler: async (args) => {
+              aibitat.introspect(`Executing flow: ${flow.name}`);
+              const result = await AgentFlows.executeFlow(uuid, args, aibitat);
+              if (!result.success) {
+                aibitat.introspect(
+                  `Flow failed: ${result.results[0]?.error || "Unknown error"}`
+                );
+                return `Flow execution failed: ${result.results[0]?.error || "Unknown error"}`;
+              }
+              aibitat.introspect(`${flow.name} completed successfully`);
+
+              // If the flow result has directOutput, return it
+              // as the aibitat result so that no other processing is done
+              if (!!result.directOutput) {
+                aibitat.skipHandleExecution = true;
+                return AgentFlows.stringifyResult(result.directOutput);
+              }
+
+              return AgentFlows.stringifyResult(result);
+            },
+          });
+        },
+      }),
+      flowName: flow.name,
+    };
+  }
+
+  /**
+   * Stringify the result of a flow execution or return the input as is
+   * @param {Object|string} input - The result to stringify
+   * @returns {string} The stringified result
+   */
+  static stringifyResult(input) {
+    return typeof input === "object" ? JSON.stringify(input) : String(input);
+  }
+}
+
+module.exports.AgentFlows = AgentFlows;

package/server/utils/agents/aibitat/error.js

@@ -0,0 +1,18 @@
+class AIbitatError extends Error {}
+
+class APIError extends AIbitatError {
+  constructor(message) {
+    super(message);
+  }
+}
+
+/**
+ * The error when the AI provider returns an error that should be treated as something
+ * that should be retried.
+ */
+class RetryError extends APIError {}
+
+module.exports = {
+  APIError,
+  RetryError,
+};

package/server/utils/agents/aibitat/example/beginner-chat.js

@@ -0,0 +1,56 @@
+// You must execute this example from within the example folder.
+const AIbitat = require("../index.js");
+const { cli } = require("../plugins/cli.js");
+const { NodeHtmlMarkdown } = require("node-html-markdown");
+require("dotenv").config({ path: `../../../../.env.development` });
+
+const Agent = {
+  HUMAN: "🧑",
+  AI: "🤖",
+};
+
+const aibitat = new AIbitat({
+  provider: "openai",
+  model: "gpt-4o",
+})
+  .use(cli.plugin())
+  .function({
+    name: "aibitat-documentations",
+    description: "The documentation about aibitat AI project.",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    handler: async () => {
+      return await fetch(
+        "https://raw.githubusercontent.com/wladiston/aibitat/main/README.md"
+      )
+        .then((res) => res.text())
+        .then((html) => NodeHtmlMarkdown.translate(html))
+        .catch((e) => {
+          console.error(e.message);
+          return "FAILED TO FETCH";
+        });
+    },
+  })
+  .agent(Agent.HUMAN, {
+    interrupt: "ALWAYS",
+    role: "You are a human assistant.",
+  })
+  .agent(Agent.AI, {
+    functions: ["aibitat-documentations"],
+  });
+
+async function main() {
+  if (!process.env.OPEN_AI_KEY)
+    throw new Error(
+      "This example requires a valid OPEN_AI_KEY in the env.development file"
+    );
+  await aibitat.start({
+    from: Agent.HUMAN,
+    to: Agent.AI,
+    content: `Please, talk about the documentation of AIbitat.`,
+  });
+}
+
+main();

package/server/utils/agents/aibitat/example/blog-post-coding.js

@@ -0,0 +1,55 @@
+const AIbitat = require("../index.js");
+const {
+  cli,
+  webBrowsing,
+  fileHistory,
+  webScraping,
+} = require("../plugins/index.js");
+require("dotenv").config({ path: `../../../../.env.development` });
+
+const aibitat = new AIbitat({
+  model: "gpt-4o",
+})
+  .use(cli.plugin())
+  .use(fileHistory.plugin())
+  .use(webBrowsing.plugin()) // Does not have introspect so will fail.
+  .use(webScraping.plugin())
+  .agent("researcher", {
+    role: `You are a Researcher. Conduct thorough research to gather all necessary information about the topic 
+    you are writing about. Collect data, facts, and statistics. Analyze competitor blogs for insights. 
+    Provide accurate and up-to-date information that supports the blog post's content to @copywriter.`,
+    functions: ["web-browsing"],
+  })
+  .agent("copywriter", {
+    role: `You are a Copywriter. Interpret the draft as general idea and write the full blog post using markdown, 
+    ensuring it is tailored to the target audience's preferences, interests, and demographics. Apply genre-specific 
+    writing techniques relevant to the author's genre. Add code examples when needed. Code must be written in 
+    Typescript. Always mention references. Revisit and edit the post for clarity, coherence, and 
+    correctness based on the feedback provided. Ask for feedbacks to the channel when you are done`,
+  })
+  .agent("pm", {
+    role: `You are a Project Manager. Coordinate the project, ensure tasks are completed on time and within budget. 
+    Communicate with team members and stakeholders.`,
+    interrupt: "ALWAYS",
+  })
+  .channel("content-team", ["researcher", "copywriter", "pm"]);
+
+async function main() {
+  if (!process.env.OPEN_AI_KEY)
+    throw new Error(
+      "This example requires a valid OPEN_AI_KEY in the env.development file"
+    );
+  await aibitat.start({
+    from: "pm",
+    to: "content-team",
+    content: `We have got this draft of the new blog post, let us start working on it.
+    --- BEGIN DRAFT OF POST ---
+    
+    Maui is a beautiful island in the state of Hawaii and is world-renowned for its whale watching season. Here are 2 additional things to do in Maui, HI:
+    
+    --- END DRAFT OF POST ---
+    `,
+  });
+}
+
+main();