# raribeirobold/dcloud_ai_training architecture

> Architecture diagram of the GitHub repository raribeirobold/dcloud_ai_training, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raribeirobold/dcloud_ai_training
- Repository: https://github.com/raribeirobold/dcloud_ai_training

## Overview

This repository is a set of hands-on workshops progressing from local LLM fundamentals (WS2), through local RAG (WS3), to an operational assistant demo (WS4). The WS4 path supports asking an agent for operational help, using local data and tools, and drafting—not submitting—a ticket. Source excerpts document several helpers and tools; notebooks, agent prompts, and skills are unsampled, so their internal links are left unverified.

Main entry points: [`WS4/rag/build_chroma.py`](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/rag/build_chroma.py) (Runbook index builder), [`WS3/K + N - W3 - Notebook/kn_w3_rag.ipynb`](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/kn_w3_rag.ipynb) (RAG exercises), [`WS2/K + N - W2 - Notebook/kn_w2_how_llms_work.ipynb`](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS2/K%20%2B%20N%20-%20W2%20-%20Notebook/kn_w2_how_llms_work.ipynb) (LLM exercises), [`WS2/K + N - W2 - Notebook/helpers.py`](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS2/K%20%2B%20N%20-%20W2%20-%20Notebook/helpers.py) (LLM session helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fundamentals["WS2 LLM Fundamentals"]
  node_w2notebook["LLM exercises"]
  node_w2helpers["LLM session helpers<br/>[helpers.py]"]
end

subgraph group_rag["WS3 Local RAG"]
  node_w3notebook["RAG exercises<br/>[kn_w3_rag.ipynb]"]
  node_w3helpers["RAG session helpers<br/>[helpers.py]"]
  node_w3content["Runbooks and corpus"]
  node_embedcheck["Embedding check"]
end

subgraph group_assistant["WS4 Ops Assistant"]
  node_agentconfig["Agent instructions<br/>[AGENTS.md]"]
  node_skills["Agent skills"]
  node_disktool["Disk usage tool<br/>[disk_usage.ts]"]
  node_diskscript["Disk log parser<br/>[disk_usage.py]"]
  node_logs["Operational logs"]
  node_calculator["Calculator tool<br/>[calculator.ts]"]
  node_tickettool["Ticket draft tool<br/>[create_ticket.ts]"]
  node_tickets["Ticket drafts"]
  node_ragbuilder["Runbook index builder<br/>[build_chroma.py]"]
  node_w4runbooks["Operational runbooks"]
  node_chromadb[("Chroma collection")]
end

subgraph group_local["Local Runtime"]
  node_opencode["OpenCode agent host"]
  node_localmodels["Local model runtime"]
end

node_learner(("Workshop participant"))

node_learner -.->|"works through"| node_w2notebook
node_learner -.->|"works through"| node_w3notebook
node_learner -.->|"asks for help"| node_opencode
node_w2notebook -.->|"uses helpers"| node_w2helpers
node_w2helpers -.->|"calls locally"| node_localmodels
node_w3notebook -.->|"uses helpers"| node_w3helpers
node_w3notebook -.->|"uses corpus"| node_w3content
node_w3helpers -.->|"calls locally"| node_localmodels
node_embedcheck -->|"checks embeddings"| node_localmodels
node_opencode -.->|"uses instructions"| node_agentconfig
node_opencode -.->|"uses skills"| node_skills
node_opencode -.->|"dispatches tool"| node_disktool
node_disktool -->|"runs script"| node_diskscript
node_diskscript -->|"reads logs"| node_logs
node_opencode -.->|"dispatches tool"| node_calculator
node_opencode -.->|"dispatches tool"| node_tickettool
node_tickettool -->|"writes draft"| node_tickets
node_ragbuilder -->|"reads runbooks"| node_w4runbooks
node_ragbuilder -->|"writes collection"| node_chromadb
node_ragbuilder -->|"queries collection"| node_chromadb

click node_w2notebook "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS2/K%20%2B%20N%20-%20W2%20-%20Notebook/kn_w2_how_llms_work.ipynb"
click node_w2helpers "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS2/K%20%2B%20N%20-%20W2%20-%20Notebook/helpers.py"
click node_w3notebook "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/kn_w3_rag.ipynb"
click node_w3helpers "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/helpers.py"
click node_w3content "https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/data"
click node_embedcheck "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/check_embeddings.py"
click node_agentconfig "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/AGENTS.md"
click node_skills "https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/solutions/skills"
click node_disktool "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/plugins/disk_usage.ts"
click node_diskscript "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/disk_usage.py"
click node_logs "https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/logs"
click node_calculator "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/plugins/calculator.ts"
click node_tickettool "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/plugins/create_ticket.ts"
click node_tickets "https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/tickets"
click node_ragbuilder "https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/rag/build_chroma.py"
click node_w4runbooks "https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/runbooks"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_w2notebook,node_w2helpers toneBlue
class node_w3notebook,node_w3helpers,node_w3content,node_embedcheck toneAmber
class node_agentconfig,node_skills,node_disktool,node_diskscript,node_logs,node_calculator,node_tickettool,node_tickets,node_ragbuilder,node_w4runbooks,node_chromadb toneMint
class node_opencode,node_localmodels toneRose
class node_learner toneIndigo
```

## Components

### WS2 LLM Fundamentals

- [LLM exercises](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS2/K%20%2B%20N%20-%20W2%20-%20Notebook/kn_w2_how_llms_work.ipynb): `WS2/K + N - W2 - Notebook/kn_w2_how_llms_work.ipynb`
- [LLM session helpers](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS2/K%20%2B%20N%20-%20W2%20-%20Notebook/helpers.py): `WS2/K + N - W2 - Notebook/helpers.py`

### WS3 Local RAG

- [RAG exercises](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/kn_w3_rag.ipynb): `WS3/K + N - W3 - Notebook/kn_w3_rag.ipynb`
- [RAG session helpers](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/helpers.py): `WS3/K + N - W3 - Notebook/helpers.py`
- [Runbooks and corpus](https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/data): `WS3/K + N - W3 - Notebook/data`
- [Embedding check](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS3/K%20%2B%20N%20-%20W3%20-%20Notebook/check_embeddings.py): `WS3/K + N - W3 - Notebook/check_embeddings.py`

### WS4 Ops Assistant

- [Agent instructions](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/AGENTS.md): `WS4/solutions/AGENTS.md`
- [Agent skills](https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/solutions/skills): `WS4/solutions/skills`
- [Disk usage tool](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/plugins/disk_usage.ts): `WS4/solutions/plugins/disk_usage.ts`
- [Disk log parser](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/disk_usage.py): `WS4/solutions/disk_usage.py`
- [Operational logs](https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/logs): `WS4/logs`
- [Calculator tool](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/plugins/calculator.ts): `WS4/solutions/plugins/calculator.ts`
- [Ticket draft tool](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/solutions/plugins/create_ticket.ts): `WS4/solutions/plugins/create_ticket.ts`
- [Ticket drafts](https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/tickets): `WS4/tickets`
- [Runbook index builder](https://github.com/raribeirobold/dcloud_ai_training/blob/main/WS4/rag/build_chroma.py): `WS4/rag/build_chroma.py`
- [Operational runbooks](https://github.com/raribeirobold/dcloud_ai_training/tree/main/WS4/runbooks): `WS4/runbooks`
- **Chroma collection**

### Local Runtime

- **OpenCode agent host**
- **Local model runtime**

### Other components

- **Workshop participant**

## Connections

- Workshop participant → LLM exercises: works through
- Workshop participant → RAG exercises: works through
- Workshop participant → OpenCode agent host: asks for help
- LLM exercises → LLM session helpers: uses helpers
- LLM session helpers → Local model runtime: calls locally
- RAG exercises → RAG session helpers: uses helpers
- RAG exercises → Runbooks and corpus: uses corpus
- RAG session helpers → Local model runtime: calls locally
- Embedding check → Local model runtime: checks embeddings (evidence: `WS3/K + N - W3 - Notebook/check_embeddings.py`)
- OpenCode agent host → Agent instructions: uses instructions
- OpenCode agent host → Agent skills: uses skills
- OpenCode agent host → Disk usage tool: dispatches tool
- Disk usage tool → Disk log parser: runs script (evidence: `WS4/solutions/plugins/disk_usage.ts`)
- Disk log parser → Operational logs: reads logs (evidence: `WS4/solutions/disk_usage.py`)
- OpenCode agent host → Calculator tool: dispatches tool
- OpenCode agent host → Ticket draft tool: dispatches tool
- Ticket draft tool → Ticket drafts: writes draft (evidence: `WS4/solutions/plugins/create_ticket.ts`)
- Runbook index builder → Operational runbooks: reads runbooks (evidence: `WS4/rag/build_chroma.py`)
- Runbook index builder → Chroma collection: writes collection (evidence: `WS4/rag/build_chroma.py`)
- Runbook index builder → Chroma collection: queries collection (evidence: `WS4/rag/build_chroma.py`)
