kdeps · jjuliano · Apr 29, 2025 · Apr 26, 2025 · Apr 26, 2025 · Apr 28, 2025
diff --git a/README.md b/README.md
@@ -1,32 +1,38 @@
 # What is Kdeps?
 
-Kdeps is a no-code framework for building self-hosted RAG AI Agents powered by open-source LLMs.
-
-1. It uses open-source LLMs by default.
-2. Has a built-in context-aware RAG workflow system.
-3. Builds a Docker image of the AI Agent.
-
-<img alt="Kdeps - Overview" src="/docs/public/overview.png" />
-
-Kdeps is packed with features:
-- 🚀 run in [Lambda](https://kdeps.github.io/kdeps/getting-started/configuration/workflow.html#lambda-mode) or [API Mode](https://kdeps.github.io/kdeps/getting-started/configuration/workflow.html#api-server-settings)
-- 🤖 use multiple open-source LLMs from [Ollama](https://kdeps.github.io/kdeps/getting-started/configuration/workflow.html#llm-models) and [Huggingface](https://github.com/kdeps/examples/tree/main/huggingface_imagegen_api)
-- 🐍 run Python in isolated environments using [Anaconda](https://kdeps.github.io/kdeps/getting-started/resources/python.html)
-- 🖼️ [multimodal](https://kdeps.github.io/kdeps/getting-started/resources/multimodal.html) LLMs ready
-- 💅 built-in [validation](https://kdeps.github.io/kdeps/getting-started/resources/validations.html) checks and [skip](https://kdeps.github.io/kdeps/getting-started/resources/skip.html) conditions
-- 🔄 [reusable](https://kdeps.github.io/kdeps/getting-started/resources/remix.html) AI Agents
-- 🖥️ run [shell-scripts](https://kdeps.github.io/kdeps/getting-started/resources/exec.html)
-- 🌐 make [API calls](https://kdeps.github.io/kdeps/getting-started/resources/client.html) from configuration
-- 📊 generate [structured outputs](https://kdeps.github.io/kdeps/getting-started/resources/llm.html#chat-block) from LLMs
-- 📦 install [Ubuntu packages](https://kdeps.github.io/kdeps/getting-started/configuration/workflow.html#ubuntu-packages) from configuration
-- 📜 define [Ubuntu repos or PPAs](https://kdeps.github.io/kdeps/getting-started/configuration/workflow.html#ubuntu-repositories)
-- 📈 context-aware [RAG workflow](https://kdeps.github.io/kdeps/getting-started/resources/kartographer.html)
-- 🗂️ upload any [documents or files](https://kdeps.github.io/kdeps/getting-started/tutorials/files.html) for LLM processing
-- ⚡ Written in Golang
-- 📦 [easy to install](https://kdeps.github.io/kdeps/getting-started/introduction/installation.html) and use
-
-I know, that's a lot. Let's dive into the details.
-
-You can get started with Kdeps [via installing it](https://kdeps.github.io/kdeps/getting-started/introduction/installation.html) with a single command.
-
-See the [examples](https://github.com/kdeps/examples).
+Kdeps is an all-in-one AI framework for building Dockerized full-stack AI applications (FE and BE) that includes
+open-source LLM models out-of-the-box.
+
+**It is the only AI framework that doesn't require you to write Python to build a full-stack AI app.**
+
+## Key Features
+
+Kdeps is loaded with features to streamline AI app development:
+
+- 🐳 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).
+- 🤖 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.
+- 🌍 Make [API calls](https://kdeps.com/getting-started/resources/client.html) directly from configuration.
+- 📊 Generate [structured outputs](https://kdeps.com/getting-started/resources/llm.html#chat-block) from LLMs.
+- 📦 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.
+
+## Getting Started
+
+Ready to explore Kdeps? Install it with a single command: [Installation Guide](https://kdeps.com/getting-started/introduction/installation.html).
+
+Check out practical [examples](https://github.com/kdeps/examples) to jumpstart your projects.
diff --git a/docs/getting-started/configuration/webserver.md b/docs/getting-started/configuration/webserver.md
@@ -108,12 +108,12 @@ WebServer {
     trustedProxies { "192.168.1.0/24" }
 
     routes {
-        web {
+        new {
             path = "/dashboard"
             serverType = "static"
             publicPath = "/agentX/1.0.0/dashboard/"
         }
-        web {
+        new {
             path = "/app"
             serverType = "app"
             appPort = 8501

diff --git a/docs/getting-started/configuration/workflow.md b/docs/getting-started/configuration/workflow.md
@@ -224,15 +224,15 @@ enabling frontend integration with Kdeps' AI workflows.
 ##### Static File Serving
 
 - **`static`**: Serves files like HTML, CSS, or JS from a specified directory, ideal for hosting dashboards or
-  frontends. The `web` block with `serverType = "static"` defines the path and directory relative to `/data/`,
+  frontends. The block with `serverType = "static"` defines the path and directory relative to `/data/`,
   delivering files directly to clients.
 
 Example:
 
 ```apl
 WebServer {
     routes {
-        web {
+        new {
             path = "/dashboard"
             serverType = "static"
             publicPath = "/agentX/1.0.0/dashboard/"
@@ -246,18 +246,18 @@ This serves files from `/data/agentX/1.0.0/dashboard/` at `http://<host>:8080/da
 ##### Reverse Proxying
 
 - **`app`**: Forwards requests to a local web application (e.g., Streamlit, Node.js) running on a specified port. The
-  `web` block with `serverType = "app"` defines the path, port, and optional command to start the app, proxying client
+  block with `serverType = "app"` defines the path, port, and optional command to start the app, proxying client
   requests to the app’s server.
 
-
 Example:
 
 ```apl
 WebServer {
     routes {
-        web {
+        new {
             path = "/app"
             serverType = "app"
+            publicPath = "/agentX/1.0.0/streamlit-app/"
             appPort = 8501
             command = "streamlit run app.py"
         }
@@ -330,6 +330,8 @@ Python packages can also be installed even without Anaconda installed.
 ```apl
 pythonPackages {
     "diffusers[torch]"
+    "streamlit"
+    "openai-whisper"
 }
 ```
 
@@ -353,6 +355,8 @@ Specify the Ubuntu packages that should be pre-installed when building this imag
 packages {
     "tesseract-ocr"
     "poppler-utils"
+    "npm"
+    "ffmpeg"
 }
 ```
 

diff --git a/docs/getting-started/resources/llm.md b/docs/getting-started/resources/llm.md
@@ -4,14 +4,17 @@ outline: deep
 
 # LLM Resource
 
-The `llm` resource facilitates the creation of a Large Language Model (LLM) session to interact with AI models effectively.
+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 resource. For more information, see the
+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:
 
@@ -27,7 +30,9 @@ aiagent
     └── 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
 
@@ -36,8 +41,25 @@ Within the file, you’ll find the `chat` block, structured as follows:
 ```apl
 chat {
     model = "tinydolphin" // Specifies the LLM model to use, defined in the workflow.
+
+    // Send the dedicated prompt and role to the LLM or utilize the scenario block.
+    // Specifies the LLM role context for this prompt, e.g., "user", "assistant", or "system".
+    // Defaults to "human" if no role is specified.
+    role = "user"
     prompt = "Who is @(request.data())?"
 
+    // Scenario block allows adding multiple prompts and roles for this LLM session.
+    scenario {
+        new {
+            role = "assistant"
+            prompt = "You are a knowledgeable and supportive AI assistant with expertise in general information."
+        }
+        new {
+            role = "system"
+            prompt = "Ensure responses are concise and accurate, prioritizing user satisfaction."
+        }
+    }
+
     // Determines if the LLM response should be a structured JSON.
     JSONResponse = true
 
@@ -61,18 +83,112 @@ chat {
 }
 ```
 
-Key Elements of the `chat` Block
-
-- **`model`**: Specifies the LLM model to be used.
-- **`prompt`**: The input prompt sent to the model.
-- **`files`**: List all the files for use by the LLM model. This feature is particularly beneficial for vision-based
-  LLM models.
-- **`JSONResponse`**: Indicates if the response should be structured as JSON.
-- **`JSONResponseKeys`**: Lists the required keys for the structured JSON response. To ensure the output conforms to
-  specific data types, you can define the keys with their corresponding types. For example: `first_name__string`,
-  `famous_quotes__array`, `details__markdown`, or `age__integer`.
-- **`timeoutDuration`**: Sets the exectuion timeout in s (seconds), min (minutes), etc., after which the session is terminated.
-
-When the resource is executed, you can leverage LLM functions like `llm.response("id")` to retrieve the generated
-response. For further details, refer to the [LLM Functions](../resources/functions.md#llm-resource-functions)
-documentation.
+### Key Elements of the `chat` Block
+
+- **`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.
+- **`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.
+- **`JSONResponseKeys`**: Lists the required keys for the structured JSON response. Keys can include type annotations (e.g., `first_name__string`, `famous_quotes__array`, `details__markdown`, `age__integer`) to enforce specific data types.
+- **`timeoutDuration`**: Sets the execution timeout (e.g., in seconds `s` or minutes `min`), after which the LLM session is terminated.
+
+When the resource is executed, you can leverage LLM functions like `llm.response("id")` to retrieve the generated response. For further details, refer to the [LLM Functions](../resources/functions.md#llm-resource-functions) documentation.
+
+## Advanced Configuration
+
+### Scenario Block Usage
+
+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
+scenario {
+    new {
+        role = "system"
+        prompt = "You are an expert in historical facts and provide detailed, accurate information."
+    }
+    new {
+        role = "user"
+        prompt = "Tell me about the Renaissance period."
+    }
+    new {
+        role = "assistant"
+        prompt = "The Renaissance was a cultural movement that spanned roughly from the 14th to the 17th century..."
+    }
+}
+```
+
+This setup allows the LLM to maintain a consistent context across multiple interactions, improving response coherence.
+
+### Handling Files
+
+The `files` block supports processing of various file types, such as images or documents, which is particularly beneficial for multimodal LLMs. For example:
+
+```apl
+files {
+    "@(request.files()[0])" // Processes the first uploaded file
+    "data/document.pdf"     // Processes a specific PDF file
+}
+```
+
+Ensure that the files are accessible within the resource’s context and compatible with the LLM model’s capabilities.
+
+### Structured JSON Responses
+
+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
+JSONResponseKeys {
+    "name__string"
+    "age__integer"
+    "quotes__array"
+    "bio__markdown"
+}
+```
+
+This configuration ensures that the response contains a `name` (string), `age` (integer), `quotes` (array), and `bio` (markdown-formatted text).
+
+## 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.
+
+Additionally, you can implement error handling using [Preflight Validations](../resources/validations) to check for valid inputs or model availability before executing the session.
+
+## Best Practices
+
+- **Model Selection**: Choose an LLM model that aligns with your use case (e.g., text generation, image processing) and is defined in the workflow configuration.
+- **Prompt Design**: Craft clear and specific prompts to improve the quality of LLM responses. Use the `scenario` block to provide additional context where needed.
+- **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.
+
+## 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:
+
+```apl
+chat {
+    model = "tinydolphin"
+    role = "user"
+    prompt = "Provide details about @(request.data('person'))"
+    scenario {
+        new {
+            role = "assistant"
+            prompt = "You are a history expert AI, providing accurate and concise information about historical figures."
+        }
+    }
+    JSONResponse = true
+    JSONResponseKeys {
+        "name__string"
+        "birth_year__integer"
+        "known_for__array"
+        "biography__markdown"
+    }
+    timeoutDuration = 30.s
+}
+```
+
+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.
+
+For more advanced configurations and use cases, refer to the [Workflow](../configuration/workflow.md) and [LLM Functions](../resources/functions.md#llm-resource-functions) documentation.
diff --git a/go.mod b/go.mod
@@ -23,7 +23,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/joho/godotenv v1.5.1
 	github.com/kdeps/kartographer v0.0.0-20240808015651-b2afd5d97715
-	github.com/kdeps/schema v0.2.17
+	github.com/kdeps/schema v0.2.20
 	github.com/kr/pretty v0.3.1
 	github.com/spf13/afero v1.14.0
 	github.com/spf13/cobra v1.9.1
@@ -40,10 +40,10 @@ require (
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/charmbracelet/bubbles v0.21.0 // indirect
 	github.com/charmbracelet/bubbletea v1.3.4 // indirect
-	github.com/charmbracelet/colorprofile v0.3.0 // indirect
+	github.com/charmbracelet/colorprofile v0.3.1 // indirect
 	github.com/charmbracelet/x/ansi v0.8.0 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
-	github.com/charmbracelet/x/exp/strings v0.0.0-20250417172821-98fd948af1b1 // indirect
+	github.com/charmbracelet/x/exp/strings v0.0.0-20250424195755-e256bf9b4ee5 // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/cloudwego/base64x v0.1.5 // indirect
 	github.com/cucumber/gherkin/go/v26 v26.2.0 // indirect