[book-figures] Use plantuml instead

.gitignore

@@ -26,12 +26,10 @@ runpod.sh
 # Virtual environments
 .venv
 
-
 # coverage
 .coverage
 coverage.xml
 htmlcov/
 
 # uml diagrams
-uml/*/*.png
-uml/*/*.svg
+uml/rendered

Makefile

@@ -19,3 +19,17 @@ coverage-report: ## Show coverage summary in terminal
 
 coverage-html: ## Generate HTML coverage report
 	coverage html
+
+diagrams:	## Generate UML diagrams from PlantUML files
+	@echo "Generating UML diagrams..."
+	@mkdir -p uml/rendered
+	@find uml -name "*.puml" -not -path "uml/common/*" -exec dirname {} \; | sed 's|^uml|uml/rendered|' | sort -u | xargs mkdir -p
+	@find uml -name "*.puml" -not -path "uml/common/*" -exec sh -c 'java -jar ~/plantuml.jar -SDPI=300 -o "$$(dirname "{}" | sed "s|^uml|$(PWD)/uml/rendered|")" "{}"' \;
+	@echo "Diagrams generated in uml/rendered/ directory with chapter structure!"
+
+diagrams-svg:	## Generate SVG diagrams (for web)
+	@echo "Generating SVG diagrams..."
+	@mkdir -p uml/rendered
+	@find uml -name "*.puml" -not -path "uml/common/*" -exec dirname {} \; | sed 's|^uml|uml/rendered|' | sort -u | xargs mkdir -p
+	@find uml -name "*.puml" -not -path "uml/common/*" -exec sh -c 'java -jar ~/plantuml.jar -tsvg -o "$$(dirname "{}" | sed "s|^uml|$(PWD)/uml/rendered|")" "{}"' \;
+	@echo "SVG diagrams generated in uml/rendered/ directory with chapter structure!"

uml/README.md

@@ -1,31 +1,79 @@
 # UML Diagrams
 
-To generate diagrams for this book, I've used [D2](https://d2lang.com/). D2
-stands for Declarative Diagramming and is a declarative scripting language for
-generating diagrams, such as UML class and sequence diagrams.
+To generate diagrams for this book, I've used [PlantUML](https://plantuml.com/). PlantUML is a mature, open-source tool for creating UML diagrams from plain text descriptions, supporting class diagrams, sequence diagrams, activity diagrams, and more.
 
-To generate the UML diagrams of this book, you'll need to have D2 installed on
-your machine. Use the command found below to perform the installation:
+## Installation
+
+### Prerequisites
+
+PlantUML requires Java to be installed on your machine.
+
+### Installing PlantUML
+
+#### Option 1: Package Manager (may have older version)**
+
+```sh
+# Ubuntu/Debian
+sudo apt install plantuml
+
+# macOS
+brew install plantuml
+```
+
+#### Option 2: Latest JAR (recommended)**
 
 ```sh
-curl -fsSL https://d2lang.com/install.sh | sh -s --
+# Download the latest PlantUML JAR
+wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar -O ~/plantuml.jar
+
+# Add alias to your shell configuration (~/.bashrc or ~/.zshrc)
+echo "alias plantuml-new='java -jar ~/plantuml.jar'" >> ~/.zshrc
+
+# Reload your shell configuration
+source ~/.zshrc
 ```
 
 ## Generating Diagrams
 
-After installing `d2` on your machine, you can now generate any UML image from
-the `*.d2` files contained in this folder.
+After installing PlantUML, you can generate UML images from the `*.puml` files in this folder.
+
+### Individual Files
 
 ```sh
+# Generate PNG (default, good for print)
+plantuml-new uml/ch04/llm_agent_class.puml
+
 # Generate SVG (vector format, good for web)
-d2 uml/ch04/llm_agent.d2 uml/ch04/llm_agent.svg --sketch
+plantuml-new -tsvg uml/ch04/llm_agent_class.puml
+
+# High resolution for print
+plantuml-new -SDPI=300 uml/ch04/llm_agent_class.puml
+```
 
-# Generate PNG (raster format, good for print)
-d2 uml/ch04/llm_agent.d2 uml/ch04/llm_agent.png --sketch
+### Batch Generation
 
-# Watch mode - automatically regenerates when .d2 file changes
-d2 -w uml/ch04/llm_agent.d2 uml/ch04/llm_agent.png --sketch
+```sh
+# Generate all diagrams using make
+make diagrams      # PNG files
+make diagrams-svg  # SVG files
+
+# Or manually generate all files
+plantuml-new -SDPI=300 uml/**/*.puml
+```
 
-# High resolution for print (2x scale)
-d2 uml/ch04/llm_agent.d2 uml/ch04/llm_agent.png --sketch --scale 2
+## Directory Structure
+
+```sh
+uml/
+├── common/
+│   └── book-clean.puml     # Shared styling
+├── ch04/
+│   ├── llm_agent_class.puml
+│   └── llm_agent_sequence.puml
+└── rendered/               # Generated images
+    └── ch04/
+        ├── llm_agent_class.png
+        ├── llm_agent_class.svg
+        ├── llm_agent_sequence.png
+        └── llm_agent_sequence.svg
 ```

uml/ch04/llm_agent_class.puml

@@ -0,0 +1,70 @@
+@startuml llm_agent_uml_class
+!include ../common/book-clean.puml
+
+' External dependencies
+package "external_dependencies" <<Folder>> {
+    class "asyncio.Future" as Future
+    class "pydantic.BaseModel" as BaseModel
+}
+
+
+package "llm_agents_from_scratch.data_structures.agent" <<Folder>> {
+
+  class Task {
+    +id_: str
+    +instruction: str
+  }
+
+  class TaskStep {
+    +id_: str
+    +task_id: str
+    +instruction: str
+  }
+
+  class TaskStepResult {
+    +task_step_id: str
+    +content: str
+  }
+
+  class TaskResult {
+    +task_id: str
+    +content: str
+  }
+}
+
+package "llm_agents_from_scratch.agent" <<Folder>> {
+  class LLMAgent {
+    +llm: LLM
+    +tool_registry: dict[str, Tool]
+    +templates: LLMAgentTemplates
+    --
+    +<<property>> tools(): list[Tool]
+    +add_tool(tool: Tool)
+    +run(task: Task): LLMAgent.TaskHandler
+  }
+
+  class "LLMAgent.TaskHandler" as TaskHandler {
+    +llm_agent: LLMAgent
+    +task: Task
+    +templates: TaskHandlerTemplates
+    +rollout: str
+    +step_counter: int
+    -_background_task: ~asyncio.Task
+    --
+    -_rollout_contribution_from_single_run_step()
+    +get_next_step(): TaskStep | TaskResult
+    +run_step(step: TaskStep): TaskStepResult
+  }
+
+  LLMAgent +-- TaskHandler : <<nested>>
+}
+llm_agents_from_scratch.data_structures.agent -[hidden]down- llm_agents_from_scratch.agent
+llm_agents_from_scratch -[hidden]up- external_dependencies
+
+BaseModel <|.. Task
+BaseModel <|.. TaskStep
+BaseModel <|.. TaskStepResult
+BaseModel <|.. TaskResult
+Future <|.. TaskHandler
+
+@enduml

uml/ch04/llm_agent_sequence.puml

@@ -0,0 +1,31 @@
+@startuml
+!include ../common/book-clean.puml
+
+actor user
+participant "llm_agent: LLMAgent" as LLMAgent
+
+user -> user : creates task: Task
+
+user -> LLMAgent : wants to run task
+
+activate LLMAgent
+create participant "task_handler: TaskHandler" as TaskHandler
+LLMAgent -> TaskHandler : <<creates>>
+
+LLMAgent --> user : task_handler
+deactivate LLMAgent
+
+activate TaskHandler
+loop until completion
+    TaskHandler -> TaskHandler : get_next_step()
+    TaskHandler -> TaskHandler : run_step()
+end
+
+alt success
+    TaskHandler -> TaskHandler : set_result()
+else exception
+    TaskHandler -> TaskHandler : set_exception()
+end
+deactivate TaskHandler
+
+@enduml

uml/common/book-clean.puml

@@ -0,0 +1,40 @@
+' Clean, professional theme for print
+skinparam shadowing false
+skinparam roundcorner 12
+skinparam dpi 300
+
+' Background and borders
+skinparam backgroundcolor white
+skinparam arrowcolor #333
+skinparam linecolor #333
+skinparam arrowthickness 1.2
+
+' Participants
+skinparam participantbackgroundcolor #f9fafb
+skinparam participantbordercolor #222
+skinparam participantpadding 12
+
+' Lifelines
+skinparam sequencelifelinebackgroundcolor white
+skinparam sequencelifelinebordercolor #ccc
+
+' Notes
+skinparam noteBackgroundColor #fffbe6
+skinparam noteBorderColor #e0d97a
+skinparam noteBorderThickness 1
+
+' Fonts
+skinparam defaultfontname "Inter, Arial"
+skinparam defaultfontsize 16
+skinparam titleFontSize 20
+skinparam titleFontColor #222
+
+' Alignment
+skinparam SequenceMessageAlign center
+
+' Visibility Symbols
+skinparam classAttributeIconSize 0
+skinparam classOperationIconSize 0
+skinparam classFontName Courier
+skinparam classAttributeFontName Courier
+skinparam classFontSize 14