@elaraai/east-codex-plugin 1.0.99 → 1.0.100

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/.build/mcp/server.js +3 -2
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/index.json +12207 -216
  4. package/package.json +1 -1
  5. package/skills/e3/SKILL.md +29 -802
  6. package/skills/e3/reference/browser.md +93 -0
  7. package/skills/e3/reference/cli.md +120 -0
  8. package/skills/e3/reference/from-code.md +48 -0
  9. package/skills/e3/reference/rack.md +139 -0
  10. package/skills/e3/reference/record-indexes.md +326 -0
  11. package/skills/e3/reference/record-migrations.md +63 -0
  12. package/skills/e3/reference/repository.md +25 -0
  13. package/skills/east/SKILL.md +30 -459
  14. package/skills/east/reference/beast2.md +71 -0
  15. package/skills/east/reference/cross-language-and-json-schema.md +87 -0
  16. package/skills/east/reference/queries.md +46 -0
  17. package/skills/east/reference/runners-and-ir.md +148 -0
  18. package/skills/east/reference/trees-and-recursion.md +56 -0
  19. package/skills/east/reference/values-in-typescript.md +62 -0
  20. package/skills/east-py/SKILL.md +28 -1647
  21. package/skills/east-py/reference/beast2.md +108 -0
  22. package/skills/east-py/reference/cli.md +51 -0
  23. package/skills/east-py/reference/columns-and-platform-functions.md +87 -0
  24. package/skills/east-py/reference/control-flow-and-queries.md +147 -0
  25. package/skills/east-py/reference/cross-language.md +70 -0
  26. package/skills/east-py/reference/ir-and-diagnostics.md +150 -0
  27. package/skills/east-py/reference/patterns.md +369 -0
  28. package/skills/east-py/reference/performance.md +70 -0
  29. package/skills/east-py/reference/value-methods.md +306 -0
  30. package/skills/east-py/reference/values-construction-and-json.md +88 -0
  31. package/skills/east-py/reference/writing-east-functions.md +275 -0
  32. package/skills/east-py-datascience/SKILL.md +11 -28
@@ -0,0 +1,275 @@
1
+ # Writing East functions in Python
2
+
3
+ The four authoring calls, the block `b` and its statements, the expression surface type by type, and the standard library. Part of the `east-py` skill.
4
+
5
+ ## Contents
6
+
7
+ - Declare, implement, build, compile — the four authoring calls
8
+ - Every body takes the block first — the TypeScript `$` twin
9
+ - The expression surface, type by type
10
+ - The standard library — the TypeScript `East.<Type>.*` functions
11
+
12
+ A python body becomes East IR by being CAPTURED: it runs ONCE against typed
13
+ expression proxies, exactly like the TypeScript builder; east-c compiles the
14
+ recorded IR, and from then on only the compiled function runs. A body East
15
+ cannot express raises at build time, so the same source always costs and means
16
+ the same thing.
17
+
18
+ ## Declare, implement, build, compile — the four authoring calls
19
+
20
+ The TypeScript names, name for name. Two are about **platform functions** —
21
+ python the program calls out to, paired **by name** — and two about **East
22
+ functions**, the program itself:
23
+
24
+ | Step | Call | What it is |
25
+ |---|---|---|
26
+ | **Implement** a platform function in python | `@East.platform_function(inputs=…, output=…)` (`@East.generic_platform_function(type_parameters=, inputs=, output=)`; `East.platform_functions(__name__)` collects a module's) | the host side AND the body's spelling: a plain python function over East VALUES, its result validated against `output` — and, called inside a body, the `Platform` node with this very signature. Its name — the `def`'s, or `name=` — is what every runtime pairs the call with |
27
+ | **Declare** one implemented elsewhere | `East.platform(name, inputs, output)` (`East.asyncPlatform`, `East.genericPlatform`, `East.asyncGenericPlatform`) | a handle a body CALLS — it emits the `Platform` node; nothing runs here. For a function implemented in another package or runtime; a python implementation you hold needs no declaration |
28
+ | **Build** an East function | `East.function(inputs, out, body)` / `@East.function(inputs, out)` (`East.asyncFunction`) | runs `body` once over expression proxies and records IR; a pure one is already callable |
29
+ | **Compile** with the implementations | `East.compile(fn, platform=[…])` (`East.compileAsync`) | analyzes the IR against the implementations — a declaration no implementation matches by name is `Platform function '<name>' not found` — and returns the native callable |
30
+
31
+ An `East.function` has no name of its own: it is a VALUE, called through the
32
+ binding that holds it (`score(x)`, `rows.map(score)`), stored in a struct or an
33
+ array, exported under a name (`east_functions = {"score": score}`) — its IR
34
+ carries its parameters' names, never its own, as in TypeScript. A platform
35
+ function is the opposite: the name IS the pairing, on every runtime.
36
+
37
+ ```python
38
+ from east import East, ArrayType, FloatType, IntegerType, NullType, StringType, StructType
39
+ from east_py_std import fs_read_file, platform as std
40
+
41
+ Row = StructType([("sku", StringType), ("qty", IntegerType)])
42
+
43
+ # BUILD — `out` is REQUIRED and enforced; every body takes the block `b` first
44
+ score = East.function([Row], FloatType, lambda b, r: r.qty.to_float() * 1.5)
45
+ score({"sku": "a", "qty": 2}) # 3.0 — a pure artifact is a callable on values
46
+
47
+ # IMPLEMENT — python over East values; `name=` because "t.log" is not an identifier.
48
+ # The decorated function is DUAL-MODE: log_line("x") runs the python;
49
+ # inside a body, log_line(name) IS the Platform node 't.log' with this signature.
50
+ @East.platform_function(inputs=[StringType], output=NullType, name="t.log")
51
+ def log_line(line):
52
+ print(line)
53
+
54
+ greet = East.function([StringType], NullType,
55
+ lambda b, name: log_line(East.String.concat("hello ", name)))
56
+ greet("bob") # EastError: Platform function 't.log' is not
57
+ # available — compile with East.compile(fn, platform=[...])
58
+
59
+ # COMPILE — the implementation, by name (the same record the decorator registered)
60
+ run = East.compile(greet, platform=East.platform_functions(__name__))
61
+ run("bob") # prints "hello bob"
62
+
63
+ # A stock implementation is called the same way — no East.platform line restates it
64
+ first = East.function([StringType], StringType, lambda b, path: fs_read_file(path).split("\n").get(0))
65
+ East.compile(first, platform=std)("hosts.txt")
66
+
67
+ # DECLARE — only for a function implemented elsewhere (another package or runtime):
68
+ remote = East.platform("t.remote", [StringType], NullType)
69
+ ```
70
+
71
+ **An East function inside a platform function.** The implementation is
72
+ ordinary python over East values, and an `East.function` is a callable on
73
+ values that every eager method accepts — so that is how the implementation
74
+ does its East work, with the loop and the body running in east-c:
75
+
76
+ ```python
77
+ Rows = ArrayType(Row)
78
+
79
+ @East.platform_function(inputs=[Rows], output=FloatType) # its name: "total", the def's
80
+ def total(rows):
81
+ return rows.map(score).sum() # `score` from above — an East function on values
82
+
83
+ report = East.function([Rows], StringType, # `total(rows)` in the body IS the
84
+ lambda b, rows: East.str("total: ", # Platform node — no declaration
85
+ East.Float.print_currency(total(rows))))
86
+ East.compile(report, platform=East.platform_functions(__name__))(rows) # "total: $9.00"
87
+ ```
88
+
89
+ Each call in detail:
90
+
91
+ | Call | Builds | Notes |
92
+ |---|---|---|
93
+ | `East.function(param_types, out, body)` | a `Function` artifact | `param_types` is a LIST (`[]` for none); the body takes the block first — `lambda b, x: …` / `def f(b, x)`, as EVERY body does (`lambda x: …` is refused with the fix-it); `out` is required, and a body whose expression has another type raises naming both; with `body` omitted it is a DECORATOR |
94
+ | `East.asyncFunction(param_types, out, body)` | an `AsyncFunction` artifact | for bodies calling async platform declarations; compile with `East.compileAsync` |
95
+ | `East.platform(name, inputs, output, optional=False)` | a declaration handle | callable INSIDE a body (emits the `Platform` node); calling one outside raises `expression-level`; `East.genericPlatform(name, ["T"], inputs, output)` is the type-parameterised form (`East.asyncGenericPlatform` the async one). Needed only for a function implemented elsewhere: a `@East.platform_function` you hold emits the same node itself |
96
+ | `East.asyncPlatform(name, inputs, output)` | an async declaration | calling it from a SYNC body is a build error naming `East.asyncFunction` |
97
+ | `East.compile(fn, platform=[])` / `East.compileAsync(...)` | a native callable | takes an artifact or a raw IR value; the IR is analyzed against `platform` first (`east.ir.analyze`, the TS `analyzeIR`): a signature mismatch or a missing implementation is an `EastError` naming the call — unless the declaration is `optional=True`, which compiles to a stub that raises at the call (TS parity) |
98
+
99
+ A **pure** artifact needs no compile step: it is already a native callable,
100
+ `.bind(*values)` pre-binds trailing parameters by reference, and calling it
101
+ inside another body is a `Call` of its inline `Function` node — TypeScript's
102
+ shape — so it runs in ITS OWN frame: a `b.return_` returns from it, an
103
+ artifact used as an `East.if_else` arm evaluates only when that arm is taken,
104
+ an error inside it names its own lines, and a profile lists it as an entry of
105
+ its own, placed where it was written and where it was called. (One called with
106
+ arguments narrower than its parameters — a column projection's narrowed rows —
107
+ re-runs its source in its own frame and splices in instead.) An artifact that
108
+ mutates or raises, called and DISCARDED, is the build's "evaluated and thrown
109
+ away" error — spell it `b.do(push(xs))` / `East.block(push(xs), result)`, as
110
+ with any mutation. An artifact that calls platform functions stays first-class
111
+ (composable, serializable) but raises until `East.compile` pairs it with
112
+ implementations.
113
+ `East.function(...)` spelled INSIDE a body is the inline `Function` node, a
114
+ Function-typed expression: bind it with `b.const`, hand it to a callback slot,
115
+ or call it (a `Call`; in an `East.asyncFunction`, calling an async one is a
116
+ `CallAsync`).
117
+
118
+ **Error locations.** A build records the python frames that built each node,
119
+ so a runtime error names its authoring site: `EastError.location` is the stack —
120
+ the lambda's `file:line:column` first, then any helper between, then the
121
+ `East.function(...)` call — and a platform-signature mismatch at `East.compile`
122
+ names the call the same way. The stack stops at that call: the code that
123
+ imported or called the module is not recorded. A recorded path is relative to
124
+ its file's project root, the nearest directory above it holding a
125
+ `pyproject.toml`, so a function's IR is the same whichever module imported it
126
+ and whatever directory the process ran in. A file in no project is relative to
127
+ the working directory, and `set_location_base_path(dir)` (from `east`) pins one
128
+ base for every path, for reproducible fixtures (`None` restores the default);
129
+ `east-py check` names a refusal's frames relative to the working directory, as
130
+ an editor opens them. The map rides the function's beast2 encoding, so the
131
+ error reads the same on east-c or east-node. An error inside a callback a
132
+ builtin invokes (`arr.map(...)` and friends) resolves to the builtin's call
133
+ site, on every runner.
134
+ `set_location_capture(False)` (from `east`) builds without recording any
135
+ locations: there is then no stack walk per node, and an error raised by such a
136
+ function carries no location. Binding names are read separately and keep
137
+ working. The TypeScript twin is `setLocationCapture`.
138
+
139
+ ## Every body takes the block first — the TypeScript `$` twin
140
+
141
+ A TypeScript body receives `$` and appends statements to it; a python body
142
+ receives **`b`**, the block, as its FIRST parameter and does the same. EVERY
143
+ body does — an `East.function` body, a builtin's callback, a branch, a loop, a
144
+ handler — exactly as every TypeScript body is `($, …) => …`: `lambda x: …` is
145
+ refused with the fix-it, a body that uses the block as the element fails on the
146
+ block's first use, and each nested body receives ITS OWN block first, so a
147
+ statement on any other block is a build-time error. Python `None` returned from a
148
+ body is TypeScript's "no return"; the `east_null` sentinel is an explicit `null`:
149
+
150
+ ```python
151
+ from east import East, IntegerType, StringType
152
+
153
+ @East.function([IntegerType], StringType)
154
+ def classify(b, n):
155
+ acc = b.let(0) # $.let — reassignable
156
+ limit = b.const(n * 2) # $.const
157
+ def loop(b, label): # $.while body: (b, label)
158
+ b.if_(acc >= limit, lambda b: b.break_(label))
159
+ b.assign(acc, acc + 1) # $.assign
160
+ b.while_(True, loop)
161
+ b.if_(acc > 10, lambda b: b.return_("big")) \
162
+ .else_if(acc > 5, lambda b: b.return_("mid")) \
163
+ .else_(lambda b: b.return_("small")) # every arm returns → Never
164
+
165
+ classify(3) # "mid"
166
+ ```
167
+
168
+ A one-statement body is a `lambda b: …`; a longer one is a `def` written
169
+ just before the statement that uses it. Name the block `_b` when the body
170
+ does not use it.
171
+
172
+ | Body | Spelling |
173
+ |---|---|
174
+ | `East.function` / `East.asyncFunction` body | `lambda b, x: …`, `def f(b, x)` — the block plus exactly the function's parameters; `lambda x: …` is refused (`a body takes the block first`) |
175
+ | a builtin's callback (`xs.map(...)`, `reduce`, …) | `xs.map(lambda b, el, i: …)` — the block, then the builtin's callback signature (map's `(element, index)`; `xs.reduce(lambda b, acc, el, i: …, 0)`; a Dict's `(value, key)`); trailing parameters may be omitted, the block cannot |
176
+ | a statement construct's body (`b.if_`/`.else_if`/`.else_`, `b.match_`, `b.while_`, `b.for_`, `b.try_`/`.catch`/`.finally_`) and `East.block(fn)` | `b.for_(xs, lambda b, v, i, label: …)`, `b.match_(v, {"some": lambda b, x: …})`, `East.block(lambda b: …)` |
177
+ | an expression form's handler (`.match({...})`, `East.try_catch`, `East.let`, the `East.while_`/`for_` bodies, `.and_`/`.or_`/`.if_else`) | bodies too: `v.match({"some": lambda b, x: …})`, `East.try_catch(lambda b: …, lambda b, msg: …)` — statements inside them go in `East.block(lambda b: …)`; `East.if_else` arms are expressions, not bodies |
178
+ | a function VALUE — a compiled `East.function`, a `.bind` result, a Function-typed expression, a platform declaration | takes NO block: a slot invokes what it holds body-style and the value drops the block, so `xs.map(amount)` and `xs.map(lambda b, el: amount(el))` both work (TS: an `Expr<FunctionType>` wherever a `($, …) => …` is accepted); a value declaring fewer parameters than the slot passes takes the prefix |
179
+
180
+ | Statement | Emits | Notes |
181
+ |---|---|---|
182
+ | `b.let(value[, type])` / `b.const(value[, type])` | `Let` (Null) | the variable, mutable / not; a declared `type` widens a narrower literal (a `Variable` of a subtype gets an `As`) |
183
+ | `b.assign(var, value)` | `Assign` (Null) | `var` must come from `b.let` — a python `x = …` rebinds the NAME and changes nothing |
184
+ | `b.return_([value])` | `Return` (Never) | checked against the declared output; a `do` of the same expression just before is not duplicated |
185
+ | `b.if_(pred, fn).else_if(pred, fn).else_(fn)` | `IfElse` (Null; Never when every arm diverges) | each `fn(b)` runs in its own frame; a branch ending in a non-Null value pads with `null`; a body may return the chain itself (`lambda b: b.if_(…)`) |
186
+ | `b.match_(variant, {case: fn(b, data)})` | `Match` (Null) | a case without a handler does nothing |
187
+ | `b.while_(pred, fn)` / `b.for_(coll, fn)` | `While` / `ForArray`/`ForSet`/`ForDict` (Null) | `fn(b, label)`; Array `fn(b, value, index, label)`, Set `fn(b, key, label)`, Dict `fn(b, value, key, label)` |
188
+ | `b.break_(label)` / `b.continue_(label)` | `Break` / `Continue` (Never) | the loop's `label` is what the body received; a bare `East.break_()` (the expression form's jump) inside a statement loop targets it too |
189
+ | `b.try_(fn).catch(fn(b, message, stack)).finally_(fn)` | `TryCatch` (Null) | `.catch` at most once; Never when both bodies diverge |
190
+ | `b.do(expr)` | the expression as a statement | `$(expr)` — a platform call or mutation evaluated for its effect; a bare `arr.push_last(x)` line is thrown away, and the build says so |
191
+ | `b.error(msg)` | `Error` (Never) | `$.error` — raise now; `East.error(msg)` is the expression twin (return it, or use it as an `if_else` arm) |
192
+ | `East.block(fn)` | `Block` | the EXPRESSION form: `fn(b)`'s statements, then the value it returns (a block returning nothing must diverge) |
193
+
194
+ A statement after one that never completes raises `Unreachable statement
195
+ detected`, as in TypeScript; a statement on an OUTER block from inside a nested
196
+ body, or on a block whose body has returned, raises naming it (TypeScript's
197
+ `no-cross-block-builder` lint is a hard error here). Every other IR node kind has
198
+ a spelling too, so any program TypeScript can build, python builds name for
199
+ name: `East.value(v, T)` (a typed literal / struct / list / dict), `East.as_(v,
200
+ T)` (an explicit widening `As`), `East.wrap_recursive(v, R)` and `expr.unwrap()`
201
+ on a recursive-typed expression, and `East.builtin(name, [T…], [args], out)` (a
202
+ raw builtin, for the few with no named spelling — `east.codegen.RAW_ONLY`).
203
+
204
+ **The analyzer.** Every build and every `East.compile` runs
205
+ `east.ir.analyze.analyze_ir`, the twin of TypeScript's `analyzeIR`: scope, exact
206
+ types (a `Let`/`Assign`/argument/element/field has exactly its slot's type;
207
+ subtyping is spelled with `As`), divergence and node well-formedness, with the
208
+ TypeScript messages at the python `file:line:column`. A body that fails it never
209
+ compiles.
210
+
211
+ ## The expression surface, type by type
212
+
213
+ One class per East type in `east.expression.expr`, each the twin of
214
+ `libs/east/src/expr/<type>.ts`: the same methods snake_cased, the same builtin
215
+ and argument order behind each, and the same aliases where TypeScript has them
216
+ (`plus`/`minus`/…, `eq`/`equal`/`equals`). Every TypeScript method exists on the
217
+ expression class AND on the eager value class (a scalar's eager twin is the
218
+ `East.<Type>` function of the same name, value first: `d.add_days(n)` ↔
219
+ `East.DateTime.add_days(d, n)`), and each python-only name is a deprecated
220
+ python-idiom alias, a python protocol twin, or a convenience. Python departs from
221
+ TypeScript only where the language forces it: operators where they agree (`+ - *
222
+ / ** & | ^ ~`, the comparisons), `and_`/`or_`/`not_`, `as_`, and keyword
223
+ arguments (`out=`, `key=`, `combine=`) where TypeScript overloads.
224
+
225
+ | Type | Operators | Methods (the TypeScript names) |
226
+ |---|---|---|
227
+ | **Boolean** | `&` `\|` `^` `~` — never `and`/`or`/`not`/`if` (python collapses them to `bool`) · `==` `!=` | `.bit_and(y) .bit_or(y) .bit_xor(y) .not_()` (the builtins — both operands evaluate) · `.and_(fn(b))` `.or_(fn(b))` (TS `and`/`or`: SHORT-CIRCUIT, the other operand is a body) · `.if_else(fn(b), fn(b))` (TS `ifElse`; `East.if_else(cond, value, …, otherwise)` is the value form — pairs then the else, one `IfElse` node) · `.equals/.equal/.eq` `.not_equals/.not_equal/.ne` |
228
+ | **Integer** | `+` `-` `*` and unary `-`; `==` `!=` `<` `<=` `>` `>=` (East total order) · ❗ `//` `%` `**` `/` RAISE at build time with the fix-it: python floors/takes the divisor's sign/promotes a negative exponent where East truncates/takes the dividend's sign/yields 0 — spell `.divide(y)` / `East.Integer.divide`, `.remainder(y)` / `East.Integer.remainder`, `.pow(y)` / `East.Integer.pow`, `.to_float() / y` | `.add .subtract .multiply .divide .remainder .pow` (a Float argument widens `self`, like TS; aliases `.plus .sub .minus .mul .times .div .mod .rem .modulo`) · `.negate() .abs() .sign() .log(base)` · `.to_float()` · `.less_than/.less/.lt .greater_than/.greater/.gt .less_than_or_equal/.less_equal/.lte/.le .greater_than_or_equal/.greater_equal/.gte/.ge .equals/.equal/.eq .not_equals/.not_equal/.ne` |
229
+ | **Float** | `+` `-` `*` `/` `**` and unary `-`; comparisons · ❗ `//` `%` RAISE (`.remainder(y)` / `East.Float.remainder`) · `math.floor/ceil/trunc(x)` build the stdlib `East.Float.round_floor/round_ceil/round_trunc`; python `round(x)` raises (its tie rule differs — `East.Float.round_half(x)`) | the same named arithmetic and aliases (an Integer argument widens) · `.negate .abs .sign .sqrt .exp .log .sin .cos .tan` · `.to_integer()` ❗ errors at run time on a non-integral/NaN/infinite value · Float → Integer rounding is the stdlib `East.Float.round_floor/round_ceil/round_trunc/round_half(x)` (`round_half` = ties AWAY from zero; `.floor() .ceil() .trunc() .round()` are deprecated aliases) · comparisons as Integer |
230
+ | **String** | `+` (concat); comparisons | `.concat(s) .repeat(n) .substring(a, b) .upper_case() .lower_case() .trim() .trim_start() .trim_end()` · `.replace(old, new) .split(sep)` · `.length() .starts_with(p) .ends_with(s) .contains(s) .index_of(s)` · `.parse(T)` ❗ (strict whole-string) `.parse_json(T)` · `.try_parse(T) -> Option<T>` (none on any failure) · `.encode_utf8() .encode_utf16()` · `.regex_contains(pat, flags="") .regex_index_of(pat, flags="") .regex_replace(pat, repl, flags="")` (the builtins TypeScript has no method for) · never an f-string (it would constant-fold the proxy) — `East.str(…)` or `+` |
231
+ | **DateTime** | comparisons; a python `datetime` literal lifts as a DateTime | `.get_year() .get_month() .get_day_of_month() .get_day_of_week()` (Monday = 1) `.get_hour() .get_minute() .get_second() .get_millisecond()` · `.add_milliseconds(n) .add_seconds .add_minutes .add_hours .add_days .add_weeks` and `.subtract_milliseconds … .subtract_weeks` (an Integer or Float `n`) · `.duration_milliseconds(other) -> Integer`, `.duration_seconds/minutes/hours/days/weeks(other) -> Float` ❗ `a.duration_days(b)` is `b − a` (positive when `b` is later — the TS method; the namespace `East.DateTime.duration_milliseconds(a, b)` is the raw builtin, `a − b`) · `.to_epoch_milliseconds()` · `.print_formatted(fmt)` (Day.js tokens) |
232
+ | **Blob** | comparisons | `.size() .get_uint8(i)` · `.decode_utf8() .decode_utf16()` · `.decode_beast(T, version="v1")` (`"v2"` = the beast2 family) · `.open_beast(T)` (TS `openBeast`: an indexed beast2 `Array`/`Set`/`Dict` blob as a FROZEN paged value — `size`, keyed reads and `for_` decode one segment; an index-less blob or a Ref-/function-bearing element shape decodes whole; the header's type must equal `T`, checked before any decode) · `.decode_csv(RowT, config=None, **options)` |
233
+ | **Array / Set / Dict / Vector / Matrix** | `xs[i]` (a negative LITERAL index raises — spell `xs.get(xs.size() - 1)`) · `d[k]` ❗missing · comparisons | The eager surface, name for name and signature for signature — [EastArray](value-methods.md#eastarray--complete-method-surface) · [EastSet](value-methods.md#eastset--complete-method-surface) · [EastDict](value-methods.md#eastdict--complete-method-surface) · [EastVector](value-methods.md#eastvector--complete-method-surface) · [EastMatrix](value-methods.md#eastmatrix--complete-method-surface) — less what only a value has: the python protocol (Array `insert`/`remove`/`count`/`index`, Set `add`/`remove`/`discard`, Dict `values`/`items`), the columnar hatches (`to_columns`, `from_columns`, `map_batches`, `update_many`), the numpy/torch bridges, the classmethod generators (`East.Array.range` and kin are their twins) and the deprecated `map_elements`. A mutator yields Null or Boolean — sequence it with `b.do` or `East.block`. A Dict callback is `(value, key)`: `fn(b, v)` or `fn(b, v, k)`, a fold step `fn(b, acc, v[, k])`, a collision handler `combine(b, existing, incoming[, key])` |
234
+ | **Struct** | `r.field` / `r["field"]` (both build IR, both work on real rows) | build a row with a dict literal `{"k": expr, …}` or `struct({…}, T)` (dual-mode) |
235
+ | **Variant** | — | `.match({case: fn(b, payload)}, default=fn(b))` (TS's partial match; the arms must agree on one East type — a `some(x)` arm types its `none` sibling) · `.match_tag(tag, fn, default)` · `.unwrap(tag="some", on_other=None)` ❗ · `.has_tag(tag) .get_tag()` · Option: `.is_some() .is_none() .unwrap_or(d)` · build with `some(expr)` / `none` / `variant(case, payload)`, typed from context (the build's declared output, a typed `if_else` sibling, a declared struct field, or an `out=` pin) |
236
+ | **Ref** | — | `East.ref(v)` builds one · `.get()` · `.update(v)` (TS `RefUpdate`; `.set` and the read-modify-write `update(fn)` are deprecated — write `r.update(f(r.get()))`) · `.merge(v, fn(b, current, patch))` |
237
+ | **Function** | `f(x, …)` — a `Call` node (a `CallAsync` inside an async body) | a Function-typed parameter or a `b.const(East.function(…))` is callable in the body; `FunctionType` parameters bind with `.bind(fn_value)` |
238
+
239
+ The expression methods take the eager keywords — `out=` (`map`, `filter_map`,
240
+ `map_reduce`, `flat_map`, `flatten_to_set`, `to_array`, `to_set`), `key_out=` /
241
+ `value_out=` (`to_dict`), `key_out=` / `acc_out=` (`group_reduce`), `pred=`,
242
+ `key=`, `value_fn=` — and an `out=`-family pin also TYPES the callback's build, so
243
+ a pinned callback can build a general variant with no other context. Result
244
+ types come from the build, never a data sample: `out=` is optional everywhere,
245
+ and an EMPTY collection derives what a full one does. `some`/`every`/`first_map`
246
+ compile to the native short-circuiting FirstMap scans (`some([])` is False,
247
+ `every([])` True). An unsupported method raises `ExpressionError` naming the
248
+ supported set.
249
+
250
+ ## The standard library — the TypeScript `East.<Type>.*` functions
251
+
252
+ Every namespace carries the East standard library — TypeScript's
253
+ `libs/east/src/expr/libs/*.ts`, body for body, snake_cased (`printCompact` →
254
+ `print_compact`; the TS misspelling `printCommaSeperated` stays
255
+ `print_comma_seperated`, with `print_comma_separated` as a python twin). Each is
256
+ an `East.function` built on first use: on plain values it runs natively, inside a
257
+ body it is a call of its inline Function node like any artifact — as
258
+ TypeScript's is:
259
+
260
+ ```python
261
+ @East.function([IntegerType, FloatType, DateTimeType], StringType)
262
+ def label(b, n, x, d):
263
+ return East.str(East.Integer.print_compact(n), " / ", # "1.23M"
264
+ East.Float.print_currency(x), " @ ", # "$1,234.57"
265
+ East.DateTime.print_formatted(East.DateTime.round_down_hour(d, 6), "HH:mm"))
266
+ ```
267
+
268
+ The outputs are TypeScript's exactly — a Float prints with its point
269
+ (`East.Float.print_percentage(1.0, 0)` is `"100.0%"`), the Integer compact forms
270
+ carry two decimals below ten units (`print_compact(1500)` is `"1.50K"`), and
271
+ `round_nearest`'s Integer half-step truncates (`round_nearest(17, 5)` is `20`).
272
+ Every function, with its outputs, is in
273
+ [East.<Type> namespaces](value-methods.md#easttype-namespaces--the-builtins-and-the-standard-library);
274
+ the dual-mode generators (`East.Array.range`, `East.Set.generate`,
275
+ `East.Vector.zeros`, …) are in [Container generators](value-methods.md#container-generators-classmethods).
@@ -72,7 +72,7 @@ Task → What do you need?
72
72
  │ ├─ .iterative(objective, paramSpaces, config) — the whole objective per move
73
73
  │ ├─ .iterativeIncremental(elementObjective, paramSpaces, config) — a per-element contribution, recomputed only
74
74
  │ │ where a move changed it (coordinate or swap mode)
75
- │ └─ .iterativeGrouped(groupObjective, paramSpaces, config) — contributions grouped by VALUE (employees, bins,
75
+ │ └─ .iterativeGrouped(groupObjective, paramSpaces, config) — contributions grouped by value (employees, bins,
76
76
  │ vehicles): a move from A to B recomputes groups A and B
77
77
  ├─ GoogleOr (OR-Tools)
78
78
  │ ├─ CP-SAT → .cpsatSolve(), .cpsatSolveAll()
@@ -130,7 +130,7 @@ Task → What do you need?
130
130
  │ │ not_estimable; `adjusted` is none when the engine refuses. DoWhy / EconML / PyALE are internal.)
131
131
  │ └─ What real trial would confirm it? → .designValidation([Row], data, config, result, designConfig)
132
132
  │ (a randomised-trial recipe: sample size, split options, match-on categories, power curve, rationale)
133
- │ Honesty caveats: `causal` means robust to the OBSERVED backdoor set and the refuters that ran — NOT correctly
133
+ │ Honesty caveats: `causal` means robust to the observed backdoor set and the refuters that ran — not correctly
134
134
  │ signed, free of reverse causation or of unobserved confounding. overlap.support_strength (refused / thin /
135
135
  │ strong vs config.strong_overlap, default 0.55) tempers thin support to modest; opt-in config.evalue_floor folds
136
136
  │ a weak E-value (risk-ratio scale) into modest; opt-in config.expected_sign flags an implausibly signed effect
@@ -175,31 +175,14 @@ A model blob round-trips: what a train function returns is exactly what the
175
175
  predict and explain functions take — store it in a dataset, pass it between
176
176
  tasks, or hand it to `Shap`.
177
177
 
178
- ## Common Patterns
178
+ ## Common patterns
179
179
 
180
- ### Train and predict
181
-
182
- ```typescript
183
- const fit = East.function([], VectorType(FloatType), $ => {
184
- const X = $.let(East.Matrix.fromArray([[1.0, 2.0], [2.0, 1.0], [3.0, 4.0], [4.0, 3.0]]));
185
- const y = $.let(East.Vector.fromArray([3.0, 3.0, 7.0, 7.0]));
186
- const config = $.let({ // every field an Option: some(value) / none
187
- n_estimators: some(100n), max_depth: some(3n), learning_rate: none, min_child_weight: none,
188
- subsample: none, colsample_bytree: none, reg_alpha: none, reg_lambda: none, gamma: none,
189
- random_state: some(42n), n_jobs: none, sample_weight: none, categorical_features: none,
190
- categorical_n: none, max_cat_to_onehot: none, max_cat_threshold: none, scale_pos_weight: none,
191
- }, XGBoost.Types.XGBoostConfigType);
192
- const model = $.let(XGBoost.trainRegressor(X, y, config));
193
- $.return(XGBoost.predict(model, X));
194
- });
195
- ```
196
-
197
- ### Optimisation
198
-
199
- The objective is an East function of the decision vector —
200
- `East.function([VectorType(FloatType)], FloatType, …)` — bound with `$.const`
201
- and passed with the start point, the bounds and the config; the result
202
- carries `x_best` and `f_best` (see the Quick Start).
180
+ Search the index for a module's worked examples (`XGBoost train predict`,
181
+ `MADS optimize`, …); each config is a struct whose every field is an Option,
182
+ spelled `some(value)` or `none`. An optimiser's objective is an East function
183
+ of the decision vector, `East.function([VectorType(FloatType)], FloatType, …)`,
184
+ bound with `$.const` and passed with the start point, the bounds and the
185
+ config; the result carries `x_best` and `f_best` (see the Quick Start).
203
186
 
204
187
  ## Calling from Python (the functions directly)
205
188
 
@@ -249,7 +232,7 @@ Rules:
249
232
  xgboost_predict(xgboost_train_regressor(X, y, cfg), X))` — the calls are
250
233
  `Platform` nodes; `East.compile(fn, platform=east_py_datascience.platform)`
251
234
  runs it (the list the e3 python runner registers).
252
- - **The generic ones take the type argument FIRST in a body**, as TypeScript
235
+ - **The generic ones take the type argument first in a body**, as TypeScript
253
236
  reads: `causal_experiment(RowType, rows, config)`,
254
237
  `alns_optimize(SolutionType, initial, objective, destroy, repair, config)`.
255
238
  From python they take the values alone (`causal_experiment(rows, config)`):
@@ -266,7 +249,7 @@ For the East-value API (eager methods, `coerce_to`, `to_numpy` / `to_torch`,
266
249
 
267
250
  ## Related skills
268
251
 
269
- - **e3** — **required to run these**: they need the python runtime, so wrap each
252
+ - **e3** — required to run these: they need the python runtime, so wrap each
270
253
  call in an `e3.task` with a python runner (`{ runner: { runtime: 'east-py',
271
254
  platforms: ['east-py-datascience'] } }` — the typed runner resolves east-py
272
255
  from the project's `.venv`, no `uv run` wrapper needed). They do not run on