Streamline walkthrough, add example queries screenshot, generalize CPU role section

Author: jaidev17

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

@@ -13,9 +13,9 @@ The `concierge_agent.py` script you downloaded earlier is organized into four pa
 | Part | Responsibility | Runs on |
 |---|---|---|
 | Part 1: Tools | Web search, page scraping, optional email | CPU |
-| Part 1.5: Orchestration pipeline | Query expansion, parallelism, ranking, deduplication, extraction | CPU |
 | Part 2: The brain | Calls the local Gemma model through Ollama | GPU |
-| Part 3: The agentic chain | Ties everything together into one query workflow | CPU + 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 |
 
 ## Part 1: The tools
 
@@ -58,67 +58,23 @@ Two details are worth highlighting:
 - `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. Everything else is CPU work.
+Because every model call goes through this one function, the agent only ever uses the GPU in clearly marked places.
 
-## Part 1.5: The CPU orchestration pipeline
+## Part 3: The CPU orchestration pipeline
 
-This is the heart of the Learning Path. Between the model calls, the CPU transforms a single user request into rich, structured context. Each function below is a distinct CPU stage.
+Between the model calls, the CPU prepares the context. Each stage below runs entirely on the CPU:
 
-### Expand one query into several
-
-A single search query rarely covers a topic well, so the CPU expands it into variants before searching:
-
-```python
-def generate_search_queries(base_query: str, goal: str) -> list:
-    variants = [base_query, f"best {base_query}", f"{base_query} 2026"]
-    ...
-```
-
-### Search and browse in parallel
-
-Network requests are slow, so the CPU runs them concurrently with a thread pool instead of one at a time. The same pattern is used for searching and for browsing:
-
-```python
-def parallel_browse(urls: list) -> list:
-    log_cpu(f"Dispatching {len(urls)} parallel browse threads...")
-    with concurrent.futures.ThreadPoolExecutor(max_workers=min(len(urls), 10)) as executor:
-        future_to_url = {executor.submit(browse_website, url): url for url in urls}
-        ...
-```
-
-This is a good example of orchestration: the CPU coordinates up to ten simultaneous downloads, then collects the results as each thread finishes.
-
-### Rank pages by relevance
-
-Not every page the agent opens is useful. The CPU scores each page against the user's goal using TF-IDF (term frequency–inverse document frequency) and sorts them so the most relevant content reaches the model first:
-
-```python
-def rank_and_filter_content(scraped_pairs: list, goal: str) -> list:
-    log_cpu("Running TF-IDF ranking on scraped content...")
-    ...
-    ranked.sort(key=lambda x: x[2], reverse=True)
-    return ranked
-```
-
-### Deduplicate and extract structured data
-
-Web pages repeat each other and bury the useful facts in boilerplate. Several CPU stages clean this up:
-
-- `deduplicate_sentences()` removes near-duplicate sentences across sources using sequence matching.
-- `compute_content_fingerprints()` and `find_near_duplicates()` use 5-word shingles and Jaccard similarity to detect near-duplicate pages.
-- `extract_entities()` pulls structured data, such as phone numbers, opening hours, and prices, out of the text with regular expressions.
-- `build_keyword_index()` builds an inverted index of the most frequent terms.
-
-The extracted entities are handed to the model as a clearly labeled block, so the model starts from facts the CPU already verified:
-
-```python
-aggregated_text = (
-    f"[CPU-Extracted Entities]\n{entity_summary}\n\n"
-    f"[Aggregated Web Content]\n{aggregated_text}"
-)
-```
+| Stage | Function | What it does |
+|---|---|---|
+| Expand queries | `generate_search_queries()` | Turns one query into several variants |
+| Search in parallel | `parallel_search()` | Runs all searches concurrently |
+| Browse in parallel | `parallel_browse()` | Fetches up to ten websites at once |
+| Rank by relevance | `rank_and_filter_content()` | Scores pages with TF-IDF |
+| Deduplicate | `deduplicate_sentences()`, `find_near_duplicates()` | Removes repeated sentences and near-duplicate pages |
+| Extract data | `extract_entities()` | Pulls out phone numbers, hours, and prices |
+| Build index | `build_keyword_index()` | Indexes the most frequent terms |
 
-## Part 3: The agentic chain
+## Part 4: The agentic chain
 
 `run_concierge_agent()` ties the pipeline together. Reading it top to bottom shows how CPU and GPU steps alternate:
 
@@ -128,23 +84,4 @@ aggregated_text = (
 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.
 
-A small helper, `time_cpu()`, wraps each CPU stage to measure how long it takes and record it on the timeline:
-
-```python
-def time_cpu(label: str, fn, *args, **kwargs):
-    start_ts = time.perf_counter()
-    result = fn(*args, **kwargs)
-    elapsed = time.perf_counter() - start_ts
-    timing["cpu_s"] += elapsed
-    timeline_events.append((start_ts, start_ts + elapsed, "cpu"))
-    log_cpu(f"Timing[{label}]: {elapsed:.3f}s")
-    return result
-```
-
-The matching GPU timing is captured inside `call_gemma_ollama()`. Together they produce the timeline and the timing breakdown you'll see when you run the agent in the next section.
-
-{{% notice Note %}}
-The script also contains an `send_email()` tool and commented-out email steps. They're disabled by default so the workflow stays focused on research. You can re-enable them later by configuring the `SMTP_*` environment variables and uncommenting the email steps.
-{{% /notice %}}
-
 Now that you understand the structure, 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

@@ -92,7 +92,7 @@ C=CPU (orchestration + web I/O) P=GPU input token processing G=GPU token generat
 Total: 9.803s
 ```
 
-Reading left to right, you can see the pattern of an agentic query: long stretches of CPU work (`C`) for searching, browsing, and processing, punctuated by short GPU bursts where the model reads a prompt (`P`) and generates text (`G`).
+Reading left to right, you can see the pattern of an agentic query: long stretches of CPU work (<code style="color:#00aa00"><strong>C</strong></code>) for searching, browsing, and processing, punctuated by GPU bursts where the model reads a prompt (<code style="color:#aa00aa"><strong>P</strong></code>) and generates text (<code style="color:#cc0000"><strong>G</strong></code>).
 
 <!-- TODO: replace with a real screenshot of the colored timeline output -->
 ![Color-coded timeline showing long CPU stretches between short GPU bursts alt-text#center](agent_timeline.png "The timeline shows the CPU active for most of the query, with the GPU running in short bursts.")
@@ -109,6 +109,10 @@ Compare the battery life of the three most recommended noise-cancelling headphon
 Summarize the key differences between the latest Raspberry Pi models
 ```
 
+The screenshot below shows example queries and the answers the agent returns:
+
+![Example of search queries to the agent and the answers it returns #center](queries-and-results.png "Example queries sent to the local concierge agent and the responses it generates.")
+
 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.

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

@@ -6,44 +6,31 @@ weight: 7
 layout: learningpathall
 ---
 
-## The CPU does most of the work
+## How the CPU and GPU share the work
 
-When people picture an AI agent, they usually picture the model generating text. The timeline from the previous section tells a different story: for a typical research query, the CPU is active far longer than the GPU. The model is fast and focused; the CPU does the broad, continuous work of turning one question into a useful answer.
+When people picture an AI agent, they usually picture an AI model generating text using just the GPU. In practice, the model is only one stage of an agentic workflow. The CPU and GPU work in tandem, each handling the part of the workload it does best: the GPU runs the model's reasoning, while the CPU does the broad, continuous work of orchestration that turns a single request into a useful answer.
 
-This section steps back from the code to explain *why* that happens and why it matters on Arm platforms.
+This section looks at the CPU's role in agentic workflows, and why it matters on Arm platforms.
 
-## Where the CPU time goes
+## What the CPU does in an agentic workflow
 
-Every stage between the model calls runs on the CPU. Grouped by purpose, the CPU is responsible for:
+Most agentic systems share the same shape, regardless of the task. Between model calls, the CPU is responsible for the work that surrounds inference:
 
-| Category | What the CPU does | Functions involved |
-|---|---|---|
-| Orchestration | Expands one query into variants, schedules parallel tasks, coordinates the workflow | `generate_search_queries`, `parallel_search`, `parallel_browse` |
-| Web I/O | Calls the search API, downloads pages, parses HTML into clean text | `search_web`, `browse_website` |
-| Relevance | Scores and sorts pages so the best content reaches the model | `compute_tfidf_score`, `rank_and_filter_content` |
-| Cleanup | Removes duplicate sentences and near-duplicate pages | `deduplicate_sentences`, `compute_content_fingerprints`, `find_near_duplicates` |
-| Structuring | Extracts entities and builds a keyword index | `extract_entities`, `build_keyword_index` |
+- **Orchestration** – deciding what to do next, scheduling tasks, coordinating tools and services, and routing work between multiple AI agents and subagents.
+- **Tool calls and I/O** – calling APIs, querying databases, reading files, and fetching web pages, often many at once.
+- **Data preparation** – cleaning, filtering, ranking, deduplicating, and structuring raw data before it reaches the model.
+- **Memory and state** – tracking conversation history, caching results, and managing context across steps.
 
-Only after all of this does the model receive a compact, deduplicated, fact-rich prompt. The quality of the final answer depends heavily on this preparation.
-
-## Why this matters: garbage in, garbage out
-
-A model can only reason about the context it's given. If the agent fed every raw page directly to the model, three problems would follow:
-
-- **Cost and latency** – long, repetitive prompts take much longer for the model to read (the input-token processing time you saw in the breakdown).
-- **Lower quality** – boilerplate and duplicated text crowd out the facts that actually answer the question.
-- **Hallucination risk** – without extracted, verified entities, the model is more likely to guess.
-
-The CPU pipeline addresses all three. Parallel I/O keeps latency down, deduplication and ranking keep the prompt focused, and entity extraction gives the model concrete facts to ground its answer.
+These stages are mostly classical computing: concurrency, networking, parsing, and text processing. They run continuously throughout a query, while the GPU is used in focused bursts only when the model reasons. As agents call more tools and handle more data, this CPU-side work grows.
 
 ## Why this is a good fit for Arm
 
-The CPU work in this agent, coordinating parallel tasks, handling network I/O, and running classical text processing, is exactly the kind of broad, concurrent workload that Arm CPUs handle efficiently.
+This kind of broad, concurrent orchestration and I/O is exactly the workload Arm CPUs handle efficiently. The same pattern scales across Arm platforms:
 
-- On an **Apple silicon MacBook** or an **Arm Linux laptop**, the same Arm CPU runs all orchestration and I/O while the integrated GPU accelerates the model. The whole agent runs on one device with no cloud dependency.
-- On an **NVIDIA DGX Spark**, the Arm Grace CPU coordinates the agentic workflow while the Blackwell GPU runs inference. The division of labor in this small agent mirrors how larger AI systems are built: CPUs orchestrate, GPUs accelerate.
+- On an **Apple silicon MacBook** or an **Arm Linux laptop**, the Arm CPU runs orchestration and I/O while the integrated GPU accelerates the model, so the whole agent runs on one device with no cloud dependency.
+- On an **NVIDIA DGX Spark**, the Arm Grace CPU coordinates the agentic workflow while the Blackwell GPU runs inference, mirroring how larger AI systems are built: CPUs orchestrate, GPUs accelerate.
 
-The key takeaway is that an agent is an *orchestration system*, not just an inference system. The model is one important stage, but the CPU is what turns a single question into searches, reading, ranking, and structured facts, and that orchestration is where most of the work happens.
+The key takeaway is that an agent is an *orchestration system*, not just an inference system. The model is one important stage, but the CPU is what turns a single request into tool calls, data, and structured context, and that orchestration is a large part of the work.
 
 ## Experiment
 
@@ -63,5 +50,3 @@ You've built and run a local AI concierge agent end to end on Arm hardware, and
 - Run an agentic workflow that searches, browses, ranks, deduplicates, and extracts data before each model call
 - Read the timing breakdown and timeline to measure how much of each query runs on the CPU
 - Connected the CPU's orchestration role to why Arm platforms suit agentic workloads
-
-The main idea to carry forward is that an AI agent is an orchestration system: the model reasons in short bursts, while the CPU does the broad, continuous work that turns one question into a grounded answer.