Merge pull request #3489 from anupras-mohapatra-arm/cross-platform

Visualizing CPU orchestration for local AI agent LP documentation review

Author: pareenaverma

content/learning-paths/cross-platform/ai-agent-cpu-orchestration/1-overview.md

@@ -1,17 +1,17 @@
 ---
-title: Understand the agent and the CPU/GPU split
+title: Understand the agent and how work is split between CPU and GPU
+description: See how a local Ollama AI concierge agent on Arm splits search, web I/O, text processing, and model reasoning between the CPU and GPU.
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## What you'll build
+## What you will run
 
-In this Learning Path, you'll build and run a *local concierge agent*: a terminal application that answers research-style questions, such as finding restaurants, comparing products, or summarizing a topic, by searching the web, reading multiple pages, and writing a fact-checked summary.
-
-Everything runs on your own Arm machine. The agent uses an LLM served locally by [Ollama](https://ollama.com/), so your prompts and the pages you browse never leave the device. The same code runs on an Apple silicon MacBook, an Arm Linux laptop, or an NVIDIA DGX Spark.
+You'll run a local concierge agent: a terminal application that answers research-style questions, such as finding restaurants, comparing products, or summarizing a topic. The agent answers these questions by searching the web, reading multiple pages, and writing a fact-checked summary.
 
+You'll run everything on your local Arm machine. The agent uses an LLM served locally by [Ollama](https://ollama.com/), so your prompts and the pages you browse never leave the device. The same code runs on an Apple silicon MacBook, an Arm Linux laptop, or an NVIDIA DGX Spark.
 
 The agent is interesting not just because it runs locally, but because of *how the work is divided*. A common assumption is that an AI agent is "just the model." In practice, the model is only one stage in a longer pipeline, and most of the surrounding work runs on the CPU.
 
@@ -30,7 +30,7 @@ Your question
     -> Write a fact-checked summary         (GPU: model reasoning)
 ```
 
-The model is called several times, but between every model call the CPU does a large amount of orchestration: generating query variants, dispatching parallel network requests, merging and deduplicating results, scoring pages for relevance, and extracting structured data.
+The model is called several times, but between every model call, the CPU does a large amount of orchestration. The CPU generates query variants, dispatches parallel network requests, merges and deduplicates results, scores pages for relevance, and extracts structured data.
 
 ## Why the CPU matters in an agentic workflow
 
@@ -43,7 +43,8 @@ It's easy to focus only on token generation, because that's the visible "thinkin
 | Web I/O | CPU | Calling the search API, downloading and parsing web pages |
 | Text processing | CPU | TF-IDF ranking, deduplication, entity extraction, indexing |
 
-This division is a natural fit for Arm platforms. On an Apple silicon MacBook or an Arm Linux machine, the CPU handles all orchestration and I/O while the GPU accelerates the model. On an NVIDIA DGX Spark, the Arm CPU coordinates the workflow while the GPU runs inference. In every case, the model is only as good as the context the CPU prepares for it.
+This division is a natural fit for Arm platforms. On an Apple silicon MacBook or an Arm Linux machine, the CPU handles all orchestration and I/O and the GPU accelerates the model.
+On an NVIDIA DGX Spark, the Arm CPU coordinates the workflow while the GPU runs inference. In every case, the model is only as good as the context the CPU prepares for it.
 
 ## How the agent shows you the split
 
@@ -56,6 +57,8 @@ The program is instrumented so you can see this division directly. As it runs, i
 
 By the end of this Learning Path, you'll be able to look at a single query and see exactly how much of the work happened on the CPU before and after the model produced its answer.
 
-## What's next
+## What you've learned and what's next
+
+You've now learned about the agent you'll build and the role the CPU plays in orchestrating the agent's workflow.
 
-In the next section, you'll set up your environment: create a Python virtual environment, install the required packages, and get a Serper API key for web search.
+Next, you'll set up your environment: create a Python virtual environment, install the required packages, and get a Serper API key for web search.

content/learning-paths/cross-platform/ai-agent-cpu-orchestration/2-setup.md

@@ -1,18 +1,19 @@
 ---
-title: Set up your environment
+title: Set up your environment before running the agent
+description: Set up a Python virtual environment, Serper API key, required packages, and the concierge agent script before running the local AI agent on Arm.
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Set up your environment
+## Install and configure prerequisites for the agent
 
-In this section, you'll prepare everything the agent needs before running it: a Serper API key for web search, a Python virtual environment, the required packages, and the agent script itself.
+Prepare the following before running the agent: a Serper API key for web search, a Python virtual environment, the required packages, and the agent script.
 
 These steps are identical on an Apple silicon MacBook, an Arm Linux machine, and an NVIDIA DGX Spark.
 
-## Create a project directory and virtual environment
+### Create a project directory and virtual environment
 
 A virtual environment keeps the agent's dependencies isolated from your system Python, so you always run against the right package versions.
 
@@ -30,9 +31,9 @@ python3 -m venv .venv
 source .venv/bin/activate
 ```
 
-Your shell prompt now shows `(.venv)`, which confirms the environment is active.
+Your shell prompt will now show `(.venv)`, which confirms the environment is active.
 
-## Install the required packages
+### Install the required packages
 
 The agent uses `requests` for HTTP calls and `beautifulsoup4` to parse web pages.
 
@@ -47,21 +48,21 @@ pip install requests beautifulsoup4
 The agent searches the web through [Serper](https://serper.dev/), a Google Search API. The free tier is enough to complete this Learning Path.
 
 1. Go to [serper.dev](https://serper.dev/) and create a free account.
-2. Once logged in, you will see the dashboard. On the left, click **API Keys**.
+2. After logging in, you'll see the dashboard. On the left, select **API Keys**.
 3. Copy the Default key.
 4. Export your API key as an environment variable in the same terminal session as your virtual environment:
 
-```bash
-export SERPER_API_KEY="your-serper-api-key"
-```
+    ```bash
+    export SERPER_API_KEY="your-serper-api-key"
+    ```
 
 {{% notice Tip %}}
 This variable only lasts for the current terminal session. To keep it across sessions, add the same line to your shell profile, for example `~/.zshrc` on macOS or `~/.bashrc` on Linux.
 {{% /notice %}}
 
-## Download the agent script
+### Download the agent script
 
-Download the complete agent script, <a href="/learning-paths/cross-platform/ai-agent-cpu-orchestration/concierge_agent.py" download>concierge_agent.py</a>, and move it into your `concierge-agent` directory. You'll run it at the end of this Learning Path, and the next sections walk through how the important parts work.
+Download the complete agent script <a href="/learning-paths/cross-platform/ai-agent-cpu-orchestration/concierge_agent.py" download>concierge_agent.py</a>, and move it into your `concierge-agent` directory.
 
 Alternatively, download it directly from the command line:
 
@@ -75,4 +76,8 @@ Confirm the file is in your project directory:
 ls concierge_agent.py
 ```
 
-With the environment ready and the script in place, the next step is to serve a model locally with Ollama.
+## What you've accomplished and what's next
+
+You've now obtained and set a Serper API key, created a virtual environment, and downloaded the agent script. 
+
+Next, you'll serve the model locally with Ollama.

content/learning-paths/cross-platform/ai-agent-cpu-orchestration/3-ollama.md

@@ -1,5 +1,6 @@
 ---
 title: Serve a model locally with Ollama
+description: Install Ollama, pull Gemma 3, and verify the local model endpoint before connecting it to the Arm-based concierge agent.
 weight: 4
 
 ### FIXED, DO NOT MODIFY
@@ -8,15 +9,15 @@ layout: learningpathall
 
 ## Run AI models locally with Ollama
 
-The agent's reasoning steps, such as choosing search terms, selecting URLs, and writing the final summary, are handled by an LLM. Instead of calling a cloud API, this Learning Path serves the model locally with [Ollama](https://ollama.com/).
+The agent's reasoning steps, such as choosing search terms, selecting URLs, and writing the final summary, are handled by an LLM. Instead of calling a cloud API, you'll serve the model locally with [Ollama](https://ollama.com/).
 
-Ollama is a lightweight runtime that downloads open models, loads them into memory, and exposes a local HTTP API at `http://localhost:11434`. When the agent calls that endpoint, the model runs directly on your machine: the CPU and GPU on your MacBook, Arm Linux laptop, or NVIDIA DGX Spark. Nothing is sent to an external service or cloud.
+Ollama is a lightweight runtime that downloads open models, loads them into memory, and exposes a local HTTP API at `http://localhost:11434`. When the agent calls that endpoint, the model runs directly on your machine: the CPU and GPU on your MacBook, Arm Linux laptop, or NVIDIA DGX Spark.
 
 Running locally has three benefits that matter for an agent:
 
-- **Privacy**: your prompts and the web content the agent reads stay on the device.
-- **Cost**: there are no per-token API charges, so you can run many queries freely.
-- **Control**: you choose the exact model and keep it resident in memory for fast repeated calls.
+- Privacy: your prompts and the web content the agent reads stay on the device.
+- Cost: there are no per-token API charges, so you can run many queries freely.
+- Control: you choose the exact model and keep it resident in memory for fast repeated calls.
 
 ## Install and start Ollama
 
@@ -50,7 +51,7 @@ With the install script, `ollama serve` runs in the foreground. Keep that termin
 
 ## Pull the Gemma model
 
-This Learning Path uses [Gemma 3](https://ai.google.dev/gemma), Google's family of open models, in its 4-billion-parameter size (`gemma3:4b`). This size is a good default: it's capable enough for the agent's reasoning steps and small enough to run on a laptop.
+You'll use [Gemma 3](https://ai.google.dev/gemma), Google's family of open models. The 4-billion-parameter size (`gemma3:4b`) is a good default: it's capable enough for the agent's reasoning steps and small enough to run on a laptop.
 
 Download the model:
 
@@ -66,7 +67,7 @@ ollama list
 
 You'll see `gemma3:4b` in the list of installed models.
 
-## Choose a different model (optional)
+## (Optional) Choose a different model
 
 The agent reads the model name from the `OLLAMA_MODEL` environment variable, so you can switch models without editing the code. The default in the script is `gemma3:4b`.
 
@@ -75,7 +76,9 @@ The agent reads the model name from the `OLLAMA_MODEL` environment variable, so
 | `gemma3:4b` | 4B | Laptops and modest hardware; the default |
 | `gemma3:27b` | 27B | High-memory systems such as DGX Spark, for stronger reasoning |
 
-To use a larger model on a DGX Spark, pull it and set the environment variable before running the agent:
+To use a larger model on a DGX Spark, pull it and set the environment variable before running the agent. 
+
+For example, to use a model with 27 billion parameters:
 
 ```bash
 ollama pull gemma3:27b
@@ -102,4 +105,8 @@ Summarize what a local AI agent does in one sentence.
 
 Type `/bye` to exit the model session.
 
-With Ollama serving `gemma3:4b`, you're ready to look at how the agent code uses it.
+## What you've accomplished and what's next
+
+You've now set up Ollama, served a Google `gemma3:4b` model locally, and tested the model. 
+
+Next, you'll look at how the agent code uses the model.

content/learning-paths/cross-platform/ai-agent-cpu-orchestration/4-code-walkthrough.md

@@ -1,5 +1,6 @@
 ---
-title: Walk through the agent code
+title: Understand the concierge agent code
+description: Review the concierge agent code to see where web search, page scraping, Ollama model calls, and CPU orchestration happen in the workflow.
 weight: 5
 
 ### FIXED, DO NOT MODIFY
@@ -8,18 +9,18 @@ layout: learningpathall
 
 ## How the code is organized
 
-The `concierge_agent.py` script you downloaded earlier is organized into four parts. This section walks through the important pieces so you understand what runs on the CPU, what runs on the GPU, and how the agent chains them together.
+The `concierge_agent.py` script you downloaded earlier is organized into four parts. You'll understand what runs on the CPU, what runs on the GPU, and how the agent chains them together.
 
 | Part | Responsibility | Runs on |
 |---|---|---|
-| Part 1: Tools | Web search, page scraping, optional email | CPU |
-| Part 2: The brain | Calls the local Gemma model through Ollama | GPU |
-| Part 3: Orchestration pipeline | Query expansion, parallelism, ranking, deduplication, extraction | CPU |
-| Part 4: The agentic chain | Ties everything together into one query workflow | CPU + GPU |
+| Tools | Web search, page scraping, optional email | CPU |
+| The brain | Calls the local Gemma model through Ollama | GPU |
+| Orchestration pipeline | Query expansion, parallelism, ranking, deduplication, extraction | CPU |
+| The agentic chain | Ties everything together into one query workflow | CPU + GPU |
 
-## Part 1: The tools
+### The tools
 
-The tools are the agent's connection to the outside world. `search_web()` calls the Serper API and returns the top five results; `browse_website()` downloads a page and strips it down to clean text. Both run entirely on the CPU and both log their activity with `log_cpu()`:
+The tools are the agent's connection to the outside world. `search_web()` calls the Serper API and returns the top five results. `browse_website()` downloads a page and strips it down to clean text. Both run entirely on the CPU and both log their activity with `log_cpu()`:
 
 ```python
 def search_web(query: str) -> str:
@@ -36,7 +37,7 @@ def browse_website(url: str) -> str:
 
 `browse_website()` uses BeautifulSoup to remove `<script>` and `<style>` tags, collapse whitespace, and cap the result at 8,000 characters so a single large page can't dominate the pipeline.
 
-## Part 2: The brain
+### The brain
 
 A single function, `call_gemma_ollama()`, is the only place the model is used. It sends a prompt to the local Ollama API and streams the response back token by token:
 
@@ -53,16 +54,16 @@ def call_gemma_ollama(prompt, output_format="json", timing=None,
     ...
 ```
 
-Two details are worth highlighting:
+Two details are worth noting:
 
 - `keep_alive: -1` tells Ollama to keep the model resident in memory between calls. The agent calls the model several times per query, so this avoids reloading the weights each time.
 - The function records timing as it streams. The time until the *first* token arrives is the model's input-token processing (prefill); the time spent streaming the rest is token generation. Separating these two values is what lets the agent show you the GPU breakdown later.
 
 Because every model call goes through this one function, the agent only ever uses the GPU in clearly marked places.
 
-## Part 3: The CPU orchestration pipeline
+### The CPU orchestration pipeline
 
-Between the model calls, the CPU prepares the context. Each stage below runs entirely on the CPU:
+Between the model calls, the CPU prepares the context. Each of the following stages runs entirely on the CPU:
 
 | Stage | Function | What it does |
 |---|---|---|
@@ -74,14 +75,18 @@ Between the model calls, the CPU prepares the context. Each stage below runs ent
 | Extract data | `extract_entities()` | Pulls out phone numbers, hours, and prices |
 | Build index | `build_keyword_index()` | Indexes the most frequent terms |
 
-## Part 4: The agentic chain
+### The agentic chain
 
-`run_concierge_agent()` ties the pipeline together. Reading it top to bottom shows how CPU and GPU steps alternate:
+`run_concierge_agent()` ties the pipeline together. When you read the function from top to bottom, you can see how CPU and GPU steps alternate:
 
-1. **GPU** – `call_gemma_ollama()` turns your question into a search query.
-2. **CPU** – `generate_search_queries()` and `parallel_search()` expand and run the searches.
-3. **GPU** – the model selects which URLs to open.
-4. **CPU** – `parallel_browse()`, `rank_and_filter_content()`, `deduplicate_sentences()`, `extract_entities()`, and the indexing stages prepare the context.
-5. **GPU** – the model writes the final, fact-checked summary.
+1. GPU – `call_gemma_ollama()` turns your question into a search query.
+2. CPU – `generate_search_queries()` and `parallel_search()` expand and run the searches.
+3. GPU – the model selects which URLs to open.
+4. CPU – `parallel_browse()`, `rank_and_filter_content()`, `deduplicate_sentences()`, `extract_entities()`, and the indexing stages prepare the context.
+5. GPU – the model writes the final, fact-checked summary.
 
-Now that you understand the structure, you'll run the agent and watch the CPU and GPU work in real time.
+## What you've learned and what's next
+
+You've now learned about the structure of the agent code and what functions work on the CPU and the GPU respectively. 
+
+Next, you'll run the agent and watch the CPU and GPU work in real time.

content/learning-paths/cross-platform/ai-agent-cpu-orchestration/5-run-and-examples.md

@@ -1,16 +1,17 @@
 ---
 title: Run the agent and read the timeline
+description: Run the local concierge agent, ask research questions, and interpret the CPU and GPU timing breakdown produced for each query.
 weight: 6
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Run the agent
+## Start the agent
 
-Make sure both pieces are in place before you start:
+Make sure the following are in place before you start:
 
-- Ollama is running and serving `gemma3:4b` (from the previous section).
+- Ollama is running and serving `gemma3:4b`.
 - Your virtual environment is active and `SERPER_API_KEY` is set in the current terminal.
 
 From your project directory, start the agent:
@@ -39,7 +40,7 @@ Type a question that benefits from searching and reading several pages. For exam
 Find three highly rated ramen restaurants in San Francisco that are open late
 ```
 
-As the agent works, watch the log lines. Cyan `[CPU]` lines show orchestration and web I/O; yellow `[GPU]` lines show each model call:
+As the agent works, watch the log lines. Cyan <code style="color:#00aaaa"><strong>[CPU]</strong></code> lines show orchestration and web I/O; yellow <code style="color:#aaaa00"><strong>[GPU]</strong></code> lines show each model call:
 
 ```output
 [GPU] Thinking with local Gemma model...
@@ -71,17 +72,17 @@ GPU total:                  4.991s
 
 These numbers separate the three kinds of work:
 
-- **CPU operations** – every orchestration and text-processing stage combined.
-- **GPU input token processing** – the time the model spends reading each prompt before producing output (prefill).
-- **GPU token generation** – the time spent writing the answers.
+- `CPU operations` – every orchestration and text-processing stage combined.
+- `GPU input token processing` – the time the model spends reading each prompt before producing output (prefill).
+- `GPU token generation` – the time spent writing the answers.
 
 {{% notice Note %}}
 Your exact numbers depend on your hardware, the model size, and how many pages the agent reads. The point isn't the absolute values, but the fact that CPU work is a substantial share of every query.
 {{% /notice %}}
 
 ## Read the timeline
 
-Below the breakdown, the agent prints a text-based timeline. Each character is a slice of wall-clock time, color-coded by what was active:
+The agent also prints a text-based timeline. Each character is a slice of wall-clock time, color-coded by what was active:
 
 ```output
 CCCCCCCPGGGGCCCCCCCCCCCCCCPGGGGGGGGCCCCCCCCCCCCCCCCCCCPGGGGGGGGGGGG
@@ -111,4 +112,8 @@ The screenshot shows example queries and the answers the agent returns:
 
 Type `quit` or `exit` to end the session.
 
-In the next section, you'll look more closely at why the CPU does so much of the work in an agentic workflow.
+## What you've accomplished and what's next
+
+You've now started the agent and asked questions to see how query response steps are split between the CPU and the GPU.
+
+Next, you'll learn why the CPU does so much of the work in an agentic workflow.