@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.
- package/.build/mcp/server.js +3 -2
- package/.codex-plugin/plugin.json +1 -1
- package/index.json +12207 -216
- package/package.json +1 -1
- package/skills/e3/SKILL.md +29 -802
- package/skills/e3/reference/browser.md +93 -0
- package/skills/e3/reference/cli.md +120 -0
- package/skills/e3/reference/from-code.md +48 -0
- package/skills/e3/reference/rack.md +139 -0
- package/skills/e3/reference/record-indexes.md +326 -0
- package/skills/e3/reference/record-migrations.md +63 -0
- package/skills/e3/reference/repository.md +25 -0
- package/skills/east/SKILL.md +30 -459
- package/skills/east/reference/beast2.md +71 -0
- package/skills/east/reference/cross-language-and-json-schema.md +87 -0
- package/skills/east/reference/queries.md +46 -0
- package/skills/east/reference/runners-and-ir.md +148 -0
- package/skills/east/reference/trees-and-recursion.md +56 -0
- package/skills/east/reference/values-in-typescript.md +62 -0
- package/skills/east-py/SKILL.md +28 -1647
- package/skills/east-py/reference/beast2.md +108 -0
- package/skills/east-py/reference/cli.md +51 -0
- package/skills/east-py/reference/columns-and-platform-functions.md +87 -0
- package/skills/east-py/reference/control-flow-and-queries.md +147 -0
- package/skills/east-py/reference/cross-language.md +70 -0
- package/skills/east-py/reference/ir-and-diagnostics.md +150 -0
- package/skills/east-py/reference/patterns.md +369 -0
- package/skills/east-py/reference/performance.md +70 -0
- package/skills/east-py/reference/value-methods.md +306 -0
- package/skills/east-py/reference/values-construction-and-json.md +88 -0
- package/skills/east-py/reference/writing-east-functions.md +275 -0
- 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
|
|
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
|
|
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
|
|
178
|
+
## Common patterns
|
|
179
179
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
|
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** —
|
|
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
|