-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathsetup.html
More file actions
220 lines (207 loc) · 12.1 KB
/
Copy pathsetup.html
File metadata and controls
220 lines (207 loc) · 12.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Setting up</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,800&display=swap" rel="stylesheet">
<style>
:root{
--ink:#1a1a2e; --paper:#faf8f3; --panel:#ffffff; --line:#ddd8cd;
--muted:#6f7583; --body:rgba(26,26,46,.80);
--orange:#d13d0e; --teal:#00947d;
--display:'Fraunces',Georgia,'Iowan Old Style',serif;
--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
}
*{box-sizing:border-box}
body{margin:0; background:var(--paper); color:var(--ink);
font:16.5px/1.65 var(--sans); -webkit-font-smoothing:antialiased}
.wrap{max-width:820px; margin:0 auto; padding:44px 20px 90px}
.kicker{font:600 12.5px/1 var(--sans); letter-spacing:.14em;
text-transform:uppercase; color:var(--orange); margin-bottom:14px}
h1{font-family:var(--display); font-weight:800; font-size:clamp(34px,5.4vw,52px);
line-height:1.05; letter-spacing:-.02em; margin:0 0 16px}
h2{font-family:var(--display); font-weight:600; font-size:clamp(22px,2.9vw,31px);
line-height:1.2; margin:44px 0 12px}
h2 .n{display:block; font:600 11.5px var(--sans); letter-spacing:.14em;
text-transform:uppercase; color:var(--orange); margin-bottom:5px}
h3{font-size:18px; margin:26px 0 8px}
p{color:var(--body); margin:0 0 15px}
.lead{font-size:19.5px; line-height:1.55; max-width:620px}
.meta{margin-top:26px; padding-top:18px; border-top:1px solid var(--line);
display:flex; flex-wrap:wrap; gap:6px 30px; font-size:14px; color:var(--muted)}
ul,ol{color:var(--body); margin:0 0 15px; padding-left:22px}
li{margin-bottom:7px}
code{font-family:var(--mono); font-size:.88em;
background:rgba(26,26,46,.06); padding:2px 6px; border-radius:5px}
pre{font-family:var(--mono); font-size:14px; line-height:1.6;
background:#20232e; color:#e6e3da; padding:16px 18px; border-radius:11px;
overflow:auto; margin:0 0 16px}
pre code{background:none; padding:0; font-size:1em; color:inherit}
blockquote{margin:0 0 16px; padding:12px 16px; background:var(--panel);
border:1px solid var(--line); border-left:3px solid var(--teal);
border-radius:0 10px 10px 0; color:var(--ink); font-size:15.5px}
.warn{margin:0 0 16px; padding:12px 16px; background:var(--panel);
border:1px solid var(--line); border-left:3px solid var(--orange);
border-radius:0 10px 10px 0; font-size:15.5px}
.warn b{color:var(--orange)}
a{color:var(--teal)}
footer{margin-top:60px; padding-top:18px; border-top:1px solid var(--line);
font-size:14px; color:var(--muted)}
</style>
</head>
<body>
<div class="wrap">
<header>
<div class="kicker">DisSysLab · before the first class</div>
<h1>Setting up</h1>
<p class="lead">You do not need to know anything about distributed systems
to start. You need some Python, and something you would like watched.
Everything below has been run start to finish on a clean machine; where a
step has a catch, the catch is written down rather than left for you to
hit.</p>
<div class="meta">
<span><b>Time</b> ~30 minutes</span>
<span><b>You need</b> Cowork, Python 3.10+</span>
<span><b>No API key</b> for any of this</span>
</div>
</header>
<h2><span class="n">Before you start</span>On your computer, not in the cloud</h2>
<p>When you begin a task in Cowork you can run it <b>on your computer</b> or
<b>in the cloud</b>. Choose on your computer. A cloud task gets a fresh
machine that is thrown away afterwards, so the office you build today
would not be there tomorrow.</p>
<h2><span class="n">Step 1</span>Let Cowork install it</h2>
<blockquote>The project is at
https://github.com/kmchandy/DisSysLab. Install its Python package
<code>dissyslab</code> for me, then run <code>dsl list</code> and show me
what offices come with it.</blockquote>
<p><b>Name the repository, every time.</b> <i>Install dissyslab</i> on its own
asks an assistant to trust a name it cannot check. Given the address it can
read the project's own instructions, confirm the package it is about to
install is this one, and find the skill, which lives in that repository and
not on PyPI.</p>
<p>You should get a list of around forty offices — a morning brief, a news
situation room, a bird-call classifier, a stock watcher. These are working
programs, not examples in a book.</p>
<p>If anything looks wrong: <i>run <code>dsl doctor</code> and tell me what it
says.</i> Its first line is a verdict — <code>Ready. You can build an
office.</code>, or <code>Not ready:</code> and the one thing that is wrong.
Everything under it is detail.</p>
<h2><span class="n">Step 2</span>Watch one run</h2>
<blockquote>Make me my own copy of the <code>periodic_brief</code> office in a
folder called <code>my_brief</code>, then run it and open the result.</blockquote>
<p>In ten to twenty seconds you get <code>brief.html</code>: real news
headlines and real weather. No key, no model download.</p>
<div class="warn"><b>Why the copy matters.</b> If you skip it and run
<code>dsl run periodic_brief</code>, it works — but it writes
<code>brief.html</code> inside the installed package, somewhere in your
Python site-packages, not in the folder you are standing in. You will not
find it. Make a copy first. Always.</div>
<h2><span class="n">Step 3</span>Read what you just ran</h2>
<p>Open <code>my_brief/office.md</code>. It is not code:</p>
<pre><code>Sources: bbc_world(max_articles=5), npr_news(max_articles=5)
Sinks: brief_html
Agents:
Sasha is a deduplicator(by="url").
Riley is a writer.
Connections:
bbc_world's destination is Sasha.
npr_news's destination is Sasha.
Sasha's out is Riley.
Riley's out is brief_html.</code></pre>
<p>That is the whole program. <b>Sources</b> fetch things from the world.
<b>Sinks</b> do something with the result. <b>Agents</b> are workers, each
with one job. <b>Connections</b> is the network — who sends what to whom.</p>
<p>Each agent's job is described in <code>roles/<name>.md</code>, in
English, or <code>roles/<name>.py</code>, in Python. English when the
job needs judgment; Python when the job is exact. Python roles cost nothing
to run; English roles call a language model.</p>
<p>Change something small and run it again. Add a third source. Break
something on purpose and see what happens — that is allowed, and it is how
you find the edges.</p>
<h2><span class="n">Step 4</span>Give your assistant the skill</h2>
<p>A <b>skill</b> is a folder of instructions that teaches your assistant how
to build offices correctly. Without it your assistant will improvise, and
improvised concurrency is exactly what this course is trying to spare you.</p>
<p><b>Either</b> download
<a href="https://github.com/kmchandy/DisSysLab/blob/main/skills/office-builder.skill">office-builder.skill</a>
and add it to Cowork as a skill. <b>Or</b> clone the repository and say:</p>
<blockquote>Clone https://github.com/kmchandy/DisSysLab. Read
<code>skills/office-builder/SKILL.md</code> and its <code>references/</code>
folder, and follow it when you build offices for me.</blockquote>
<div class="warn"><b>Then check it took, and check properly.</b> Installing a
skill can fail quietly — the button reports success and the old version
stays loaded. Ask: <i>does your office-builder skill list the roles that
ship with dissyslab, and what does it say to do if <code>dsl check</code> is
missing from my installed version?</i> You want both halves: it should name
roles like <code>relevance_filter</code>, and it should say to report the
missing command and carry on <b>without patching your installation</b>.
"What does <code>dsl check</code> do?" is a bad test — every version answers
that, so it tells you a skill is loaded, not which one.</div>
<h2><span class="n">Step 5</span>Build your own</h2>
<blockquote>I want an office that checks the campus events page every hour,
keeps only the events about music, and writes them to a file. Build it as a
DisSysLab office in a folder called <code>gig_watch</code>.</blockquote>
<p>Read what it wrote before you run it. You should be able to follow the
network, because it is four sections of English. Good first projects are
the ones you would actually check: something you keep refreshing a browser
tab for, a deadline or a price you are tired of watching by hand, a folder
of photos or recordings you want sorted.</p>
<h2><span class="n">Step 6</span>Check the wiring before you run</h2>
<blockquote>Run <code>dsl check</code> on my office.</blockquote>
<p>This reads your network and reports problems <i>without running
anything</i>: an agent nothing can reach, usually a name spelled two
different ways; an agent whose output goes nowhere; a sink nothing sends
to; a role you named with no file behind it; a feedback loop with nothing
to stop it. It reports everything at once, not just the first thing.</p>
<p><b>What it cannot tell you.</b> <code>dsl check</code> reads the network,
not the run. A wiring diagram can be perfectly correct and the office can
still get stuck, because getting stuck can depend on what actually arrives
and in what order. That difference — what you can know from the diagram
versus what you can only know by watching it run — is one of the real
ideas in this subject, and you have just met it on your own program.</p>
<h2><span class="n">If it goes wrong</span>The three usual ones</h2>
<p><b>It hangs and nothing happens.</b> Some agent is waiting for a message
that is not coming. Run <code>dsl check</code> first. If that is clean the
fault is in the run, not the diagram — say <i>my office hangs, help me work
out which agent is waiting and what for.</i></p>
<p><b>It finishes but produces nothing.</b> Look at the per-agent message
counts <code>dsl run</code> prints at the end. The first agent showing zero
is where the flow stops. A sink that no connection feeds is the usual
cause, and <code>dsl check</code> names it.</p>
<p><b>An English role does something odd.</b> Language models are literal. If
the job description is vague, the output will be too. Say what to keep,
what to add, and always where to send it.</p>
<h2><span class="n">Honest limits</span>What this does not do yet</h2>
<ul>
<li>An office runs on one machine, in one process, each agent in its own
thread. Separate processes are being built.</li>
<li>Checkpoint-and-resume is real, but an office only gets it where the
author switched it on.</li>
<li>There is no web interface. Offices produce files — HTML, JSONL, text.</li>
<li>Offices with English roles call a language model, which costs money.
Every shipped office stops after a few cycles by default, so you cannot
run up a bill by accident. Leave those limits until you mean to remove
them.</li>
</ul>
<h2><span class="n">Then</span>The interesting part</h2>
<p>Once your office runs you have a small distributed system you understand
completely, because you wrote it. The questions that follow are the
subject of the course. How does an office know it has <i>finished</i>, when
no single agent can see the whole system? How do you photograph a system
whose parts are all still moving, so you can restart from it after a crash?
If agents wait on each other, how do you tell "still working" from "stuck
forever"?</p>
<p>Those have real answers, they are decades old, and they are running inside
the thing you just built.</p>
<footer>
Course index: <a href="index.html">index.html</a> ·
Repository: <a href="https://github.com/kmchandy/DisSysLab">github.com/kmchandy/DisSysLab</a>
</footer>
</div>
</body>
</html>