kdeps · jjuliano · May 25, 2025 · May 23, 2025 · May 23, 2025 · May 24, 2025
diff --git a/README.md b/README.md
@@ -51,7 +51,7 @@ run {
   HTTPClient {
     method = "GET"
     url = "https://crm.example.com/api/ticket/@(request.data().ticket_id)"
-    headers { ["Authorization"] = "Bearer @(session.getItem('crm_token'))" }
+    headers { ["Authorization"] = "Bearer @(session.getRecord('crm_token'))" }
     timeoutDuration = 30.s
   }
 }
@@ -141,7 +141,6 @@ volumes:
   <summary>🖼️ Support for vision or multimodal LLMs</summary>
   Process text, images, and other data types in a single workflow with <a href="https://kdeps.com/getting-started/resources/multimodal.html">vision or multimodal LLMs</a>.
 
-
 ```pkl
 // workflow.pkl
 name = "visualTicketAnalyzer"
@@ -180,7 +179,7 @@ run {
   HTTPClient {
     method = "GET"
     url = "https://crm.example.com/api/ticket/@(request.data().ticket_id)"
-    headers { ["Authorization"] = "Bearer @(session.getItem('crm_token'))" }
+    headers { ["Authorization"] = "Bearer @(session.getRecord('crm_token'))" }
     timeoutDuration = 30.s
   }
 }
@@ -320,7 +319,6 @@ run {
   <summary>🛠️ Let LLMs run tools automatically (aka MCP or A2A)</summary>
   Enhance functionality through scripts and sequential tool pipelines with <a href="https://kdeps.com/getting-started/resources/llm.html#tools-configuration">external tools and chained tool workflows</a>.
 
-
 ```pkl
 // workflow.pkl
 name = "toolChainingAgent"
@@ -444,11 +442,91 @@ run {
 ```
 </details>
 
+<details>
+  <summary>🔄 Items iteration</summary>
+  Iterate over multiple items in a resource to process them sequentially, using <a href="https://kdeps.com/getting-started/resources/items.html">items iteration</a> with `item.current()`, `item.prev()`, and `item.next()`.
+
+```pkl
+// workflow.pkl
+name = "mtvScenarioGenerator"
+description = "Generates MTV video scenarios based on song lyrics."
+version = "1.0.0"
+targetActionID = "responseResource"
+settings {
+  APIServerMode = true
+  APIServer {
+    hostIP = "127.0.0.1"
+    portNum = 3000
+    routes {
+      new { path = "/api/v1/mtv-scenarios"; methods { "GET" } }
+    }
+    cors { enableCORS = true; allowOrigins { "http://localhost:8080" } }
+  }
+  agentSettings {
+    timezone = "Etc/UTC"
+    models { "llama3.2:1b" }
+    ollamaImageTag = "0.6.8"
+  }
+}
+```
+
+```pkl
+// resources/llm.pkl
+actionID = "llmResource"
+name = "MTV Scenario Generator"
+description = "Generates MTV video scenarios for song lyrics."
+items {
+  "A long, long time ago"
+  "I can still remember"
+  "How that music used to make me smile"
+  "And I knew if I had my chance"
+}
+run {
+  restrictToHTTPMethods { "GET" }
+  restrictToRoutes { "/api/v1/mtv-scenarios" }
+  skipCondition {
+    "@(item.current())" == "And I knew if I had my chance" // Skip this lyric
+  }
+  chat {
+    model = "llama3.2:1b"
+    role = "assistant"
+    prompt = """
+    Based on the lyric @(item.current()) from the song "American Pie," generate a suitable scenario for an MTV music video. The scenario should include a vivid setting, key visual elements, and a mood that matches the lyric's tone.
+    """
+    scenario {
+      new { role = "system"; prompt = "You are a creative director specializing in music video production." }
+    }
+    JSONResponse = true
+    JSONResponseKeys { "setting"; "visual_elements"; "mood" }
+    timeoutDuration = 60.s
+  }
+}
+```
+
+```pkl
+// resources/response.pkl
+actionID = "responseResource"
+name = "API Response"
+description = "Returns MTV video scenarios."
+requires { "llmResource" }
+run {
+  restrictToHTTPMethods { "GET" }
+  restrictToRoutes { "/api/v1/mtv-scenarios" }
+  APIResponse {
+    success = true
+    response {
+      data { "@(llm.response('llmResource'))" }
+    }
+    meta { headers { ["Content-Type"] = "application/json" } }
+  }
+}
+```
+</details>
+
 <details>
   <summary>🤖 Leverage multiple open-source LLMs</summary>
   Use LLMs from <a href="https://kdeps.com/getting-started/configuration/workflow.html#llm-models">Ollama</a> and <a href="https://github.com/kdeps/examples/tree/main/huggingface_imagegen_api">Huggingface</a> for diverse AI capabilities.
 
-
 ```pkl
 // workflow.pkl
 models {
@@ -467,7 +545,6 @@ models {
   <summary>🗂️ Upload documents or files</summary>
   Process documents for LLM analysis, ideal for document analysis tasks, as shown in the <a href="https://kdeps.com/getting-started/tutorials/files.html">file upload tutorial</a>.
 
-
 ```pkl
 // workflow.pkl
 name = "docAnalysisAgent"
@@ -613,7 +690,7 @@ run {
     method = "POST"
     url = "https://dms.example.com/api/documents"
     data { "@(python.stdout('pythonResource'))" }
-    headers { ["Authorization"] = "Bearer @(session.getItem('dms_token'))" }
+    headers { ["Authorization"] = "Bearer @(session.getRecord('dms_token'))" }
     timeoutDuration = 30.s
   }
 }
@@ -629,7 +706,6 @@ run {
   <summary>✅ Built-in validations and checks</summary>
   Utilize <a href="https://kdeps.com/getting-started/resources/api-request-validations.html#api-request-validations">API request validations</a>, <a href="https://kdeps.com/getting-started/resources/validations.html">custom validation checks</a>, and <a href="https://kdeps.com/getting-started/resources/skip.html">skip conditions</a> for robust workflows.
 
-
 ```pkl
 restrictToHTTPMethods { "POST" }
 restrictToRoutes { "/api/v1/scan-document" }
@@ -686,20 +762,18 @@ settings {
   <summary>💾 Manage state with memory operations</summary>
   Store, retrieve, and clear persistent data using <a href="https://kdeps.com/getting-started/resources/memory.html">memory operations</a>.
 
-
 ```pkl
 expr {
-  "@(memory.setItem('user_data', request.data().data))"
+  "@(memory.setRecord('user_data', request.data().data))"
 }
-local user_data = "@(memory.getItem('user_data'))"
+local user_data = "@(memory.getRecord('user_data'))"
 ```
 </details>
 
 <details>
   <summary>🔒 Configure CORS rules</summary>
   Set <a href="https://kdeps.com/getting-started/configuration/workflow.html#cors-configuration">CORS rules</a> directly in the workflow for secure API access.
 
-
 ```pkl
 // workflow.pkl
 cors {
@@ -714,7 +788,6 @@ cors {
   <summary>🛡️ Set trusted proxies</summary>
   Enhance API and frontend security with <a href="https://kdeps.com/getting-started/configuration/workflow.html#trustedproxies">trusted proxies</a>.
 
-
 ```pkl
 // workflow.pkl
 APIServerMode = true
@@ -795,7 +868,6 @@ brew install kdeps/tap/kdeps
 # Windows, Linux, and macOS
 curl -LsSf https://raw.githubusercontent.com/kdeps/kdeps/refs/heads/main/install.sh | sh
 ```
-
 </details>
 
 ## Getting Started

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -212,6 +212,7 @@ export default defineConfig({
           },
           { text: "API Request Validations", link: "/getting-started/resources/api-request-validations" },
           { text: "Skip Conditions", link: "/getting-started/resources/skip" },
+          { text: "Item Iterations", link: "/getting-started/resources/items" },
           {
             text: "Preflight Validations",
             link: "/getting-started/resources/validations",

diff --git a/docs/getting-started/resources/expr.md b/docs/getting-started/resources/expr.md
@@ -13,7 +13,7 @@ scripting within a configuration.
 
 The `expr` block is designed to evaluate PKL expressions in a straightforward manner. Its key uses include:
 
-- **Side-Effecting Operations**: Executing functions like `memory.setItem` that modify resources or state without
+- **Side-Effecting Operations**: Executing functions like `memory.setRecord` that modify resources or state without
   returning significant values.
 
 - **Inline Scripting**: Evaluating arbitrary PKL expressions to implement logic, assignments, or procedural tasks
@@ -37,8 +37,8 @@ The `expr` block is well-suited for operations that update state, such as settin
 
 ```apl
 expr {
-  "@(memory.setItem("status", "active"))"
+  "@(memory.setRecord("status", "active"))"
 }
 ```
 
-In this example, the memory store is updated to indicate an active status. The `memory.setItem` function is executed as a side effect, and no return value is required. This also applies to `memory.clear()`.
+In this example, the memory store is updated to indicate an active status. The `memory.setRecord` function is executed as a side effect, and no return value is required. This also applies to `memory.clear()`.
diff --git a/docs/getting-started/resources/global-functions.md b/docs/getting-started/resources/global-functions.md
@@ -32,28 +32,36 @@ Below is a list of the global functions available for each resource:
 | request.path()                  | Retrieves the URI path of the API request.                                     |
 | request.method()                | Retrieves the HTTP method (e.g., GET, POST) of the API request.                |
 
+## Item Loop Interaction
+
+| **Function**   | **Description**                       |
+|:---------------|:--------------------------------------|
+| item.current() | Fetches the current item in the loop  |
+| item.prev()    | Fetches the previous item in the loop |
+| item.next()    | Fetches the next item in the loop     |
+
 ## Manual LLM Tool Execution
 
-| **Function**                               | **Description**                                   |
-|:-------------------------------------------|:--------------------------------------------------|
-| tool.getItem("key")                        | Fetches the results of the tool execution of key  |
-| tool.runScript("key", "path", "arg1,arg2") | Execute the script with arguments                 |
-| tool.history("key")                        | Fetches the output history execution of the key   |
+| **Function**                               | **Description**                                  |
+|:-------------------------------------------|:-------------------------------------------------|
+| tool.getOutput("key")                      | Fetches the results of the tool execution of key |
+| tool.runScript("key", "path", "arg1,arg2") | Execute the script with arguments                |
+| tool.history("key")                        | Fetches the output history execution of the key  |
 
 ## Memory Operation Functions
 
-| **Function**                    | **Description**                                   |
-|:--------------------------------|:--------------------------------------------------|
-| memory.getItem("key")           | Fetches the value of key from persistent memory   |
-| memory.deleteItem("key")        | Delete the memory item from the persistent memory |
-| memory.setItem("key", "value")  | Stores the value of key to the persistent memory  |
-| memory.clear()                  | Clears all persistent memory (CAUTION!)           |
-| session.getItem("key")          | Fetches the value of key from session memory      |
-| session.deleteItem("key")       | Delete the memory item from the session memory    |
-| session.setItem("key", "value") | Stores the value of key to the session memory     |
-| session.clear()                 | Clears all session memory (CAUTION!)              |
-
-> *Note:* The `setItem`, `deleteItem` and `clear` are side-effecting functions—it performs an action but doesn't return a
+| **Function**                      | **Description**                                   |
+|:----------------------------------|:--------------------------------------------------|
+| memory.getRecord("key")           | Fetches the value of key from persistent memory   |
+| memory.deleteRecord("key")        | Delete the memory item from the persistent memory |
+| memory.setRecord("key", "value")  | Stores the value of key to the persistent memory  |
+| memory.clear()                    | Clears all persistent memory (CAUTION!)           |
+| session.getRecord("key")          | Fetches the value of key from session memory      |
+| session.deleteRecord("key")       | Delete the memory item from the session memory    |
+| session.setRecord("key", "value") | Stores the value of key to the session memory     |
+| session.clear()                   | Clears all session memory (CAUTION!)              |
+
+> *Note:* The `setRecord`, `deleteRecord` and `clear` are side-effecting functions—it performs an action but doesn't return a
 > meaningful value. That is why it is recommended to placed them inside an `expr` block: to ensure the expression is
 > evaluated for its effect.
 
@@ -80,8 +88,8 @@ Below is a list of the global functions available for each resource:
 
 ## Document JSON, YAML and XML Generators
 
-| **Function**            | **Description**                                      |
-|:------------------------|:-----------------------------------------------------|
+| **Function**                     | **Description**                                      |
+|:---------------------------------|:-----------------------------------------------------|
 | document.JSONRenderDocument(Any) | Parse `Any` object and returns a JSON `String`       |
 | document.JSONRenderValue(Any)    | Parse `Any` object and returns a JSON `String` Value |
 | document.yamlRenderDocument(Any) | Parse `Any` object and returns a Yaml `String`       |