ksopyla · ksopyla · Apr 12, 2026 · Mar 30, 2026 · Mar 31, 2026
@@ -10,7 +10,7 @@ description: >-
 
 ## Purpose
 
-Maintain a living record of the project's evolution in `docs/CHANGELOG.md`. This serves as:
+Maintain a living record of the project's evolution in `CHANGELOG.md` (root of the repository). This serves as:
 - A learning journal for the author
 - A reference for blog post writing
 - A history of architectural decisions

@@ -48,7 +48,7 @@ Use this order by default for example READMEs:
 ```markdown
 # Pattern NN: [Title]
 
-> One-sentence value proposition.
+> One-sentence value proposition -- mention the key pattern(s) introduced.
 
 Short positioning paragraph:
 - where this pattern fits in the series
@@ -57,58 +57,85 @@ Short positioning paragraph:
 
 ## Quick Start
 
-Show the fastest runnable path first.
+Fastest runnable path: .env setup, docker compose, curl. Include the
+verification request here so there's no need for a separate Verification section.
 
 ## What You Get Back
 
-Show the response shape, output artifact, or visible success criteria.
+Response shape or visible success criteria.
 
 ## At a Glance
 
-Compact table: agents, runtime, ports, endpoints, prerequisites, observability.
+Compact table: agents, graph topology, runtime, ports, data sources, observability.
 
 ## The Problem
 
-What breaks in the simpler approach? Why does this pattern exist?
+2-4 sentences. State the limitation(s) of the previous pattern. No comparison
+tables unless the comparison genuinely adds value that prose cannot.
 
 ## Architecture
 
-Use Mermaid when the topology or flow is not obvious. This is the important part, we are focusing on the architecture and flow not the code.
-
-
+Mermaid diagram + a paragraph explaining WHY it's structured this way (e.g. why
+two containers, why parallel), not just describing what exists.
 
 ## Key Concepts
 
-Short bullets only. Keep the deep explanation lower in the doc.
+4 bullets max, one line each, em-dashes not colons. If it reads like AI marketing
+copy, rewrite it shorter.
 
 ## Implementation Walkthrough
 
-Explain the important code in steps, with annotated snippets.
-Do not explain the code that is not part of the example, just present the main idea and flow.
+Link to source files so the reader can jump directly. Show code only when it's
+the actual working snippet that teaches the architecture (e.g. the MCP tool
+definition). For everything else, reference the file and explain the idea in
+prose. Never show pseudo-code or comment-only code blocks.
+
+## Connect Your MCP Client / Integration
+(if applicable -- combine all client tools into one section, CLI first, GUI last)
+
+## Local Development
 
-## What You Should See
+uv sync, test, lint commands.
 
-Expected logs, traces, response shape, or runtime behavior.
+## Exercises
 
-## Verification
+2 items max. One simple extension, one architectural extension. One sentence each.
 
-One or two concrete requests plus expected success and failure behavior.
+## Trade-offs
 
+Table of advantages vs. limitations. End with the bridge to the next pattern.
+
+## Further Reading
+
+Only link docs for technologies introduced in this pattern.
 ```
 
-You may merge `What You Get Back` and `At a Glance` when the example is very small, but do not move `Quick Start` far down the page unless the user explicitly wants a tutorial-first flow.
+**Sections to skip:**
+
+- **What You Should See** -- skip if Quick Start already shows expected output
+- **Verification** -- never duplicate Quick Start with the same curl commands
 
 ## README Quality Rules
 
-- **GitHub-first**: treat the README like a landing page first and a reference document second.
+- **GitHub-first**: treat the README like a landing page, not a reference manual.
 - **Self-contained**: a developer should understand the pattern without opening five other files.
 - **Use case consistency**: keep the crypto intelligence platform story and team evolution intact.
 - **Progressive narrative**: explain what limitation motivates the next pattern.
 - **Code-to-doc fidelity**: verify names, ports, env vars, response fields, validation, failure modes, and Docker UX against the implementation.
 - **No time bombs**: avoid hardcoded years or other values that drift over time unless the code also hardcodes them.
-- **No duplication**: do not explain the same concept twice at two different depths unless the second time adds new information.
-- **Show payoff early**: include an output example, trace snippet, or success criteria near the top half of the page.
-- **Keep code snippets selective**: show the parts that teach the architecture; do not dump full files.
+- **Say it once**: if a concept appears in Quick Start, don't repeat it in a Verification section. Every section must add information that no other section covers.
+- **Show payoff early**: include an output example or success criteria near the top half of the page.
+
+## Writing Style Rules
+
+- **Reference files, don't duplicate code**: link to source files (`[file.py](path)`) so readers can jump directly. Only inline a code snippet when it's the actual working code and it teaches the architecture. Never show pseudo-code, comment-only blocks, or partial extracts that don't compile.
+- **Architecture explanation helps, not just describes**: when mentioning infrastructure (containers, ports, networks), explain WHY it's structured that way, not just WHAT exists.
+- **Key Concepts are tight**: 4 bullets max. One line each with em-dash separators. Cut any bullet that restates the architecture diagram.
+- **The Problem is concise**: 2-4 sentences stating the limitation. No comparison tables unless truly needed.
+- **Exercises are short**: 2 items max. One sentence each. One simple extension, one architectural.
+- **Further Reading is scoped**: only link docs for technologies introduced by this specific pattern.
+- **Integration guides are combined**: don't split Claude Code / Cursor / Claude Desktop into separate sections. One section, multiple examples, developer-workflow order (CLI tools first, GUI apps last).
+- **No AI tone**: avoid marketing-speak, over-explanation, and restating the obvious. If a sentence doesn't add information, delete it.
 
 ## Fidelity Checklist
 

@@ -45,7 +45,9 @@ Do not use it to:
 - Use `verbose_log()` in meaningful places
 - Keep one shared `LANGSMITH_PROJECT` across the repo and differentiate examples with run tags and metadata, not extra per-example env vars
 - For public graph entrypoints, pass a `build_langsmith_run_config(...)` result into `invoke()` or `ainvoke()`
+- Prefer one small shared runtime helper when multiple transport adapters need the same timeout or LangSmith run config
 - Use FastAPI `lifespan` instead of startup/shutdown decorators
+- Avoid module-level side effects in transport modules; initialize tracing, graphs, and clients in lifespan or explicit lazy helpers
 - Expose `/health` returning `{"status": "ok"}`
 - Keep modules focused and easy to test in isolation
 
@@ -94,6 +96,7 @@ class AgentState(TypedDict, total=False):
 Guidance:
 - Use `Required[...]` for fields the entrypoint must provide
 - Keep field names business-oriented and easy to inspect in traces
+- Prefer typed fields for machine-consumed downstream data such as generated query lists instead of encoding them into free-text blobs
 - Do not overload state with framework-specific objects unless necessary
 - Keep internal graph state separate from public API schemas when those concerns differ
 
@@ -134,9 +137,11 @@ async def agent_node(state: AgentState) -> dict[str, str]:
 Guidance:
 - Keep one clear responsibility per node
 - Return only the state updates produced by that node
+- Prefer structured LLM output when downstream nodes need deterministic machine-readable fields
 - If the node uses tools, log both the action and a concise outcome
 - Catch provider/tool failures only when graceful degradation is part of the example goal
 - Keep prompts, parsing, and tool orchestration inside the node or its helper module, not in FastAPI handlers
+- When two nodes share the same mechanics but differ in prompts or fallback queries, extract the shared mechanics into a helper module and keep the node-specific reasoning local
 
 ## Graph Template
 
@@ -232,12 +237,14 @@ Guidance:
 - Keep LangSmith project selection simple: reuse the repo-wide `LANGSMITH_PROJECT` and rely on tags plus metadata for per-example filtering
 - Include stable tags such as `example:...`, `pattern:...`, `env:...`, `runtime:...`, and `provider:...`
 - Add structured error handling when the pattern needs resilience or external dependencies
+- Add an explicit timeout boundary for public HTTP or MCP entrypoints that call external providers
 - Keep endpoint handlers thin; they should validate, call the graph or service layer, and map output
 
 ## Protocol-Specific Notes
 
 - For direct tools, keep setup inside the node or helper module that owns the capability.
-- For MCP-based tools, isolate client or connection lifecycle in a dedicated module and prefer explicit typed schemas for exposed workflows.
+- For MCP-based tools, isolate client or connection lifecycle in a dedicated module, avoid import-time initialization, and prefer explicit typed schemas for exposed workflows.
+- When REST and MCP expose the same workflow, keep shared execution config in one place and document any intentional response-shape asymmetry.
 - For A2A-compatible agents, keep message-based state with a `messages` key and isolate transport-specific request or response handling at the boundary.
 - Add streaming only when the example is explicitly about streaming or the UX needs incremental progress.
 - Use compose `command:` overrides to run extra services from the same image when only the entrypoint changes.

@@ -27,7 +27,7 @@
 - [ ] `README.md` follows the documentation template
 - [ ] Architecture diagram (Mermaid) included
 - [ ] "Running the Example" section with exact commands
-- [ ] `docs/CHANGELOG.md` updated
+- [ ] `CHANGELOG.md` updated
 
 ### Testing
 - [ ] Tests added/updated in `tests/`

@@ -2,6 +2,35 @@
 
 All notable changes to this project are documented here.
 
+## [2026-03-30] Pattern 02: MCP Tool Integration -- Architecture Redesign
+
+### Added
+- Parallel fan-out/fan-in graph: research_planner -> [news_scanner | project_profiler | community_analyst] -> intelligence_compiler
+- Research planner extracts `project_name` and `coin_ticker` via LLM, generates tailored `NEWS_QUERIES` and `COMMUNITY_QUERIES` for downstream nodes
+- CoinGecko retry with exponential backoff (3 attempts, handles 429 rate limits and 5xx errors)
+- Project profiler ticker fallback resolution (search by name, then by ticker symbol)
+- News scanner fires 3-4 targeted queries per run and deduplicates results by URL
+- Community analyst uses DuckDuckGo with site:reddit.com and Twitter-focused queries for social sentiment
+
+### Changed
+- P02 architecture from outcome-oriented MCP tool (one `research_crypto_project` tool wraps the full pipeline) instead of raw API wrappers as MCP tools
+- Sequential graph (5 steps, ~61s) replaced with parallel graph (3 steps, ~51s)
+- Community analyst no longer calls CoinGecko -- eliminated data duplication with project profiler
+- All agent prompts improved with anti-hallucination rules and explicit output structure
+- Intelligence compiler prompt demands source attribution and "Data not available" instead of guessing
+
+### Architecture Decisions
+- **Parallel over sequential**: news, profiler, and community have zero data dependencies -- running them in parallel is strictly better. LangGraph native `add_edge` fan-out/fan-in used (no Send API needed)
+- **Data source ownership**: each node owns exactly one external data source. Profiler owns CoinGecko (market + dev data). News and community own DuckDuckGo (with different query strategies). Compiler is LLM-only synthesis
+- **LLM query generation over regex**: research planner uses the LLM to understand user intent and generate search-engine-optimized queries, replacing brittle `_normalize_query` regex
+- **Retry over fail-fast for external APIs**: CoinGecko free tier has aggressive rate limits; retry with backoff prevents silent data loss that was observed in production traces
+- **Outcome-oriented MCP**: the MCP server exposes `research_crypto_project` (the full pipeline result) rather than raw API wrappers -- this is the Software 3.0 lesson: expose capabilities, not plumbing
+
+### Dependencies
+- No new dependencies added; removed `langchain-mcp-adapters` (MCP client no longer needed inside agents)
+
+---
+
 ## [2026-03-29] Pattern 02: MCP Tool Integration -- complete
 
 ### Summary

@@ -13,7 +13,7 @@
 <br/>
 *From a single LangGraph pipeline to enterprise-grade, cloud-deployed agent architectures.*
 
-[Curriculum](docs/curriculum.md) · [Vision & Roadmap](docs/vision.md) · [Blog](https://ai.ksopyla.com) · [Changelog](docs/CHANGELOG.md)
+[Curriculum](docs/curriculum.md) · [Vision & Roadmap](docs/vision.md) · [Blog](https://ai.ksopyla.com) · [Changelog](CHANGELOG.md)
 
 </div>
 
@@ -27,7 +27,7 @@ This project closes that gap with **9 design patterns**, each solving a named ar
 
 ## The Approach
 
-This is a set of exmaples you can call it **Design Patterns** presenting practical design and implementation  for multi-agent systems. Each pattern:
+This is a set of examples you can call it **Design Patterns** presenting practical design and implementation for multi-agent systems. Each pattern:
 
 - Solves a **real architectural problem** that the previous pattern cannot handle
 - Has clear **"when to use / when to avoid"** criteria
@@ -89,7 +89,7 @@ Team 2 moves to an external partner. Implicit trust is gone -- JWT authenticatio
 <td>02</td>
 <td><a href="examples/02-mcp-tool-integration/">MCP Tool Integration</a></td>
 <td>Standardized tool access for agents & AI clients</td>
-<td>MCP servers/clients, Claude Code integration</td>
+<td>FastMCP, outcome-oriented tools, parallel fan-out/fan-in</td>
 </tr>
 <tr>
 <td>03</td>
@@ -242,9 +242,9 @@ agent-patterns-lab/
 │   └── src/agent_common/      # LLM config, tracing, MCP, A2A, auth helpers
 ├── docs/
 │   ├── curriculum.md          # Technical pattern-by-pattern breakdown
-│   ├── vision.md              # Full narrative, philosophy, and roadmap
-│   └── CHANGELOG.md
+│   └── vision.md              # Full narrative, philosophy, and roadmap
 ├── infra/                     # Docker base images, Azure Bicep templates
+├── CHANGELOG.md               # What changed and when
 └── .github/                   # CI/CD workflows, PR templates
 ```
 
@@ -294,7 +294,7 @@ uv run pre-commit install --install-hooks --hook-type pre-commit --hook-type com
 - **[Full Curriculum](docs/curriculum.md)** -- detailed technical breakdown of each pattern with architecture diagrams
 - **[Vision & Roadmap](docs/vision.md)** -- the complete narrative, architectural philosophy, and future direction
 - **[Blog](https://ai.ksopyla.com)** -- in-depth write-ups for each pattern
-- **[Changelog](docs/CHANGELOG.md)** -- what changed and when
+- **[Changelog](CHANGELOG.md)** -- what changed and when
 
 ## License