kdeps · jjuliano · May 16, 2025 · May 13, 2025 · May 13, 2025 · May 13, 2025
diff --git a/README.md b/README.md
@@ -5,28 +5,33 @@ open-source LLM models out-of-the-box.
 
 ## Key Features
 
-Kdeps is loaded with features to streamline AI app development:
+Kdeps is loaded with powerful features to streamline AI app development. Here are the top highlights, sorted by desirability:
 
-- 🐳 Build [Dockerized full-stack AI apps](https://kdeps.com/getting-started/introduction/quickstart.html#quickstart) with [batteries included](https://kdeps.com/getting-started/configuration/workflow.html#ai-agent-settings).
-- 🔌 Create custom [AI APIs](https://kdeps.com/getting-started/configuration/workflow.html#api-server-settings) that serve [open-source LLMs](https://kdeps.com/getting-started/configuration/workflow.html#llm-models).
-- 🌐 Pair APIs with [frontend apps](https://kdeps.com/getting-started/configuration/workflow.html#web-server-settings) like Streamlit, NodeJS, and more.
-- 📁 Serve [static websites](https://kdeps.com/getting-started/configuration/workflow.html#static-file-serving) or [reverse-proxied apps](https://kdeps.com/getting-started/configuration/workflow.html#reverse-proxying).
-- 🔒 Configure [CORS rules](https://kdeps.com/getting-started/configuration/workflow.html#cors-configuration) directly in the workflow.
-- 🛡️ Set [trusted proxies](https://kdeps.com/getting-started/configuration/workflow.html#trustedproxies) for enhanced API and frontend security.
-- 🚀 Run in [Lambda mode](https://kdeps.com/getting-started/configuration/workflow.html#lambda-mode) or [API mode](https://kdeps.com/getting-started/configuration/workflow.html#api-server-settings).
+- 🛠️ **Let LLMs run tools automatically (aka MCP or A2A) with [external tools and chained tool workflows](https://kdeps.com/getting-started/resources/llm.html#tools-configuration)** to enhance functionality through scripts and sequential tool pipelines.
+- 🧩 **Low-code/no-code capabilities for building [operational full-stack AI apps](https://kdeps.com/getting-started/configuration/workflow.html)**, enabling accessible development for non-technical users and production-ready applications.
+- 🐳 **Build [Dockerized full-stack AI apps](https://kdeps.com/getting-started/introduction/quickstart.html#quickstart)** with [batteries included](https://kdeps.com/getting-started/configuration/workflow.html#ai-agent-settings) for seamless development and deployment.
+- 🌐 **Pair APIs with [frontend apps](https://kdeps.com/getting-started/configuration/workflow.html#web-server-settings)** like Streamlit, NodeJS, and more for interactive AI-driven user interfaces.
+- 🔌 **Create custom [AI APIs](https://kdeps.com/getting-started/configuration/workflow.html#api-server-settings)** that serve [open-source LLMs](https://kdeps.com/getting-started/configuration/workflow.html#llm-models) for robust AI-driven applications.
+- 🖼️ Support for [vision or multimodal LLMs](https://kdeps.com/getting-started/resources/multimodal.html), enabling processing of text, images, and other data types in a single workflow.
+
+## Additional Features
+
+- 📊 Generate [structured outputs](https://kdeps.com/getting-started/resources/llm.html#chat-block) from LLMs for consistent, machine-readable responses.
+- 📈 Enable context-aware [RAG workflows](https://kdeps.com/getting-started/resources/kartographer.html) for accurate, knowledge-intensive tasks.
+- 🗂️ Upload [documents or files](https://kdeps.com/getting-started/tutorials/files.html) for LLM processing, ideal for document analysis.
 - 🤖 Leverage multiple open-source LLMs from [Ollama](https://kdeps.com/getting-started/configuration/workflow.html#llm-models) and [Huggingface](https://github.com/kdeps/examples/tree/main/huggingface_imagegen_api).
-- 🐍 Execute Python in isolated environments using [Anaconda](https://kdeps.com/getting-started/resources/python.html).
-- 🖼️ Support for [multimodal LLMs](https://kdeps.com/getting-started/resources/multimodal.html).
-- ✅ Built-in [API request validations](https://kdeps.com/getting-started/resources/api-request-validations.html#api-request-validations), [custom validation checks](https://kdeps.com/getting-started/resources/validations.html), and [skip conditions](https://kdeps.com/getting-started/resources/skip.html).
 - 🔄 Use [reusable AI agents](https://kdeps.com/getting-started/resources/remix.html) for flexible workflows.
-- 🖥️ Run [shell scripts](https://kdeps.com/getting-started/resources/exec.html) seamlessly.
+- 🐍 Execute Python in isolated environments using [Anaconda](https://kdeps.com/getting-started/resources/python.html).
 - 🌍 Make [API calls](https://kdeps.com/getting-started/resources/client.html) directly from configuration.
+- 🖥️ Run [shell scripts](https://kdeps.com/getting-started/resources/exec.html) seamlessly.
 - 💾 Manage state with [memory operations](https://kdeps.com/getting-started/resources/memory.html) to store, retrieve, and clear persistent data.
-- 📊 Generate [structured outputs](https://kdeps.com/getting-started/resources/llm.html#chat-block) from LLMs.
+- ✅ Built-in [API request validations](https://kdeps.com/getting-started/resources/api-request-validations.html#api-request-validations), [custom validation checks](https://kdeps.com/getting-started/resources/validations.html), and [skip conditions](https://kdeps.com/getting-started/resources/skip.html).
+- 📁 Serve [static websites](https://kdeps.com/getting-started/configuration/workflow.html#static-file-serving) or [reverse-proxied apps](https://kdeps.com/getting-started/configuration/workflow.html#reverse-proxying).
+- 🔒 Configure [CORS rules](https://kdeps.com/getting-started/configuration/workflow.html#cors-configuration) directly in the workflow.
+- 🛡️ Set [trusted proxies](https://kdeps.com/getting-started/configuration/workflow.html#trustedproxies) for enhanced API and frontend security.
+- 🚀 Run in [Lambda mode](https://kdeps.com/getting-started/configuration/workflow.html#lambda-mode) or [API mode](https://kdeps.com/getting-started/configuration/workflow.html#api-server-settings).
 - 📦 Install [Ubuntu packages](https://kdeps.com/getting-started/configuration/workflow.html#ubuntu-packages) via configuration.
 - 📜 Define [Ubuntu repositories or PPAs](https://kdeps.com/getting-started/configuration/workflow.html#ubuntu-repositories).
-- 📈 Enable context-aware [RAG workflows](https://kdeps.com/getting-started/resources/kartographer.html).
-- 🗂️ Upload [documents or files](https://kdeps.com/getting-started/tutorials/files.html) for LLM processing.
 - ⚡ Written in high-performance Golang.
 - 📥 [Easy to install](https://kdeps.com/getting-started/introduction/installation.html) and use with a single command.
 

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -201,6 +201,7 @@ export default defineConfig({
       {
         text: "Reference",
         items: [
+          { text: "Open-source LLM Tool Calling (aka MCP)", link: "/getting-started/resources/tools" },
           {
             text: "Graph Dependency",
             link: "/getting-started/resources/kartographer",

diff --git a/docs/getting-started/resources/llm.md b/docs/getting-started/resources/llm.md
@@ -4,41 +4,35 @@ outline: deep
 
 # LLM Resource
 
-The `llm` resource facilitates the creation of a Large Language Model (LLM) session to interact with AI models
-effectively.
-
-Multiple LLM models can be declared and used across multiple LLM resources. For more information, see the
-[Workflow](../configuration/workflow.md) documentation.
+The `llm` resource facilitates the creation of a Large Language Model (LLM) session to interact with AI models effectively.
 
+Multiple LLM models can be declared and used across multiple LLM resources. For more information, see the [Workflow](../configuration/workflow.md) documentation.
 
 ## Creating a New LLM Resource
 
-To create a new `llm` chat resource, you can either generate a new AI agent using the `kdeps new` command or scaffold
-the resource directly.
+To create a new `llm` chat resource, you can either generate a new AI agent using the `kdeps new` command or scaffold the resource directly.
 
-Here’s how to scaffold an `llm` resource:
+Here's how to scaffold an `llm` resource:
 
-```bash
+``` bash
 kdeps scaffold [aiagent] llm
 ```
 
 This command will add an `llm` resource to the `aiagent/resources` folder, generating the following folder structure:
 
-```bash
+``` bash
 aiagent
 └── resources
     └── llm.pkl
 ```
 
-The file includes essential metadata and common configurations, such as [Skip Conditions](../resources/skip) and
-[Preflight Validations](../resources/validations). For more details, refer to the [Common Resource
-Configurations](../resources/resources#common-resource-configurations) documentation.
+The file includes essential metadata and common configurations, such as [Skip Conditions](../resources/skip) and [Preflight Validations](../resources/validations). For more details, refer to the [Common Resource Configurations](../resources/resources#common-resource-configurations) documentation.
 
 ## Chat Block
 
-Within the file, you’ll find the `chat` block, structured as follows:
+Within the file, you'll find the `chat` block, structured as follows:
 
-```apl
+``` apl
 chat {
     model = "tinydolphin" // Specifies the LLM model to use, defined in the workflow.
 
@@ -54,10 +48,25 @@ chat {
             role = "assistant"
             prompt = "You are a knowledgeable and supportive AI assistant with expertise in general information."
         }
-        new {
+o        new {
             role = "system"
             prompt = "Ensure responses are concise and accurate, prioritizing user satisfaction."
         }
+        new {
+            role = "system"
+            prompt = "If you are unsure and will just hallucinate your response, just lookup the DB"
+        }
+    }
+
+    tools {
+        new {
+            name = "lookup_db"
+            script = "@(data.filepath("tools/1.0.0", "lookup.py"))"
+            description = "Lookup information in the DB"
+            parameters {
+                ["keyword"] { required = true; type = "string"; description = "The string keyword to query the DB" }
+            }
+        }
     }
 
     // Determines if the LLM response should be a structured JSON.
@@ -88,6 +97,7 @@ chat {
 - **`model`**: Specifies the LLM model to be used, as defined in the workflow configuration.
 - **`role`**: Defines the role context for the prompt, such as `user`, `assistant`, or `system`. Defaults to `human` if not specified.
 - **`prompt`**: The input query sent to the LLM for processing.
+- **`tools`**: Available tools for open-source LLMs to automatically use.
 - **`scenario`**: Enables the inclusion of multiple prompts and roles to shape the LLM session's context. Each `new` block within `scenario` specifies a role (e.g., `assistant` or `system`) and a corresponding prompt to guide the LLM’s behavior or response.
 - **`files`**: Lists files to be processed by the LLM, particularly useful for vision-based LLM models.
 - **`JSONResponse`**: Indicates whether the LLM response should be formatted as structured JSON.
@@ -102,7 +112,7 @@ When the resource is executed, you can leverage LLM functions like `llm.response
 
 The `scenario` block is particularly useful for setting up complex interactions with the LLM. By defining multiple roles and prompts, you can create a conversational context that guides the LLM’s responses. For example:
 
-```apl
+``` apl
 scenario {
     new {
         role = "system"
@@ -125,7 +135,7 @@ This setup allows the LLM to maintain a consistent context across multiple inter
 
 The `files` block supports processing of various file types, such as images or documents, which is particularly beneficial for multimodal LLMs. For example:
 
-```apl
+``` apl
 files {
     "@(request.files()[0])" // Processes the first uploaded file
     "data/document.pdf"     // Processes a specific PDF file
@@ -138,7 +148,7 @@ Ensure that the files are accessible within the resource’s context and compati
 
 When `JSONResponse` is set to `true`, the LLM response is formatted as a JSON object with the keys specified in `JSONResponseKeys`. Type annotations can be used to enforce data types, ensuring the output meets specific requirements. For example:
 
-```apl
+``` apl
 JSONResponseKeys {
     "name__string"
     "age__integer"
@@ -149,6 +159,84 @@ JSONResponseKeys {
 
 This configuration ensures that the response contains a `name` (string), `age` (integer), `quotes` (array), and `bio` (markdown-formatted text).
 
+### Tools Configuration
+
+The `tools` block allows open-source LLMs to utilize external tools to enhance their functionality, such as querying databases or executing scripts. Each tool is defined within a `new` block, specifying its name, script, description, and parameters. Tools can be chained, where the output of one tool is used as the input parameters for the next tool in the sequence.
+
+For example:
+
+``` apl
+tools {
+    new {
+        name = "lookup_db"
+        script = "@(data.filepath("tools/1.0.0", "lookup.py"))"
+        description = "Lookup information in the DB"
+        parameters {
+            ["keyword"] { required = true; type = "string"; description = "The string keyword to query the DB" }
+        }
+    }
+    new {
+        name = "process_results"
+        script = "@(data.filepath("tools/1.0.0", "process.py"))"
+        description = "Process DB lookup results"
+        parameters {
+            ["lookup_data"] { required = true; type = "object"; description = "The output data from lookup_db tool" }
+        }
+    }
+}
+```
+
+#### Key Elements of the `tools` Block
+
+- **`name`**: A unique identifier for the tool, used by the LLM to reference it.
+- **`script`She's the path to the script or executable that the tool runs, often using a dynamic filepath like `@(data.filepath("tools/1.0.0", "lookup.py"))`.
+- **`description`**: A clear description of the tool’s purpose, helping the LLM decide when to use it.
+- **`parameters`**: Defines the input parameters the tool accepts, including:
+  - `required`: Whether the parameter is mandatory (`true` or `false`).
+  - `type`: The data type of the parameter (e.g., `string`, `integer`, `object`, `boolean`).
+  - `description`: A brief explanation of the parameter’s purpose.
+
+#### Tool Chaining
+
+Tools can be chained to create a pipeline where the output of one tool serves as the input for the next. The LLM automatically passes the output of a tool as the parameters for the subsequent tool, based on the order defined in the `tools` block. For instance, in the example above, the `lookup_db` tool’s output (e.g., a JSON object containing query results) is passed as the `lookup_data` parameter to the `process_results` tool.
+
+To enable chaining:
+- Ensure the output format of the first tool matches the expected input parameter type of the next tool (e.g., `object` for JSON data).
+- Define tools in the order of execution, as the LLM processes them sequentially.
+- Use clear `description` fields to guide the LLM on when to initiate the chain.
+
+#### Best Practices for Tools
+
+- **Clear Descriptions**: Provide detailed descriptions to ensure the LLM understands when and how to use each tool.
+- **Parameter Validation**: Specify parameter types and requirements to prevent errors, especially when chaining tools.
+- **Script Accessibility**: Verify that script paths are correct and accessible within the resource’s context.
+- **Minimal Tools**: Include only necessary tools to avoid complexity, and order them logically for chaining.
+- **Chaining Compatibility**: Ensure the output of one tool aligns with the input requirements of the next, using consistent data types.
+
+For example, a chained weather data pipeline might look like:
+
+``` apl
+tools {
+    new {
+        name = "get_weather"
+        script = "@(data.filepath("tools/1.0.0", "weather.py"))"
+        description = "Fetches current weather data for a location"
+        parameters {
+            ["location"] { required = true; type = "string"; description = "The city or region to fetch weather for" }
+            ["unit"] { required = false; type = "string"; description = "Temperature unit (e.g., Celsius or Fahrenheit)" }
+        }
+    }
+    new {
+        name = "format_weather"
+        script = "@(data.filepath("tools/1.0.0", "format_weather.py"))"
+        description = "Formats weather data into a user-friendly summary"
+        parameters {
+            ["weather_data"] { required = true; type = "object"; description = "The weather data from get_weather tool" }
+        }
+    }
+}
+```
+
 ## Error Handling and Timeouts
 
 The `timeoutDuration` parameter is critical for managing long-running LLM sessions. If the session exceeds the specified duration (e.g., `60.s`), it will be terminated to prevent resource overuse. Ensure the timeout is set appropriately based on the complexity of the prompt and the model’s performance.
@@ -162,12 +250,13 @@ Additionally, you can implement error handling using [Preflight Validations](../
 - **File Management**: Verify that files listed in the `files` block are accessible and compatible with the LLM model.
 - **Structured Outputs**: Use `JSONResponse` and `JSONResponseKeys` for applications requiring structured data, and validate the output format in downstream processes.
 - **Timeout Configuration**: Set a reasonable `timeoutDuration` to balance performance and resource usage, especially for complex queries.
+- **Tool Usage**: Configure tools with precise descriptions and parameters to ensure the LLM uses them effectively when needed.
 
 ## Example Use Case
 
-Suppose you want to create an LLM resource to retrieve structured information about a historical figure based on user input. The `chat` block might look like this:
+Suppose you want to create an LLM resource to retrieve structured information about a history figure based on user input, with a tool to query a database for additional details. The `chat` block might look like this:
 
-```apl
+``` apl
 chat {
     model = "tinydolphin"
     role = "user"
@@ -178,6 +267,16 @@ chat {
             prompt = "You are a history expert AI, providing accurate and concise information about historical figures."
         }
     }
+    tools {
+        new {
+            name = "lookup_db"
+            script = "@(data.filepath("tools/1.0.0", "lookup.py"))"
+            description = "Lookup historical figure details in the database"
+            parameters {
+                ["name"] { required = true; type = "string"; description = "The name of the historical figure" }
+            }
+        }
+    }
     JSONResponse = true
     JSONResponseKeys {
         "name__string"
@@ -189,6 +288,9 @@ chat {
 }
 ```
 
-This configuration ensures that the LLM returns a structured JSON response with details about the requested historical figure, formatted according to the specified keys and types.
+This configuration ensures that the LLM returns a structured JSON response with details about the requested historical
+figure, formatted according to the specified keys and types, and can use the `lookup_db` tool to fetch additional data
+if needed.
 
-For more advanced configurations and use cases, refer to the [Workflow](../configuration/workflow.md) and [LLM Functions](../resources/functions.md#llm-resource-functions) documentation.
+For more advanced configurations and use cases, refer to the [Workflow](../configuration/workflow.md) and [LLM
+Functions](../resources/functions.md#llm-resource-functions) documentation.