@elaraai/east-codex-plugin 1.0.99 → 1.0.101
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 +37 -809
- package/skills/e3/reference/browser.md +93 -0
- package/skills/e3/reference/cli.md +123 -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/e3-ui/SKILL.md +273 -3623
- package/skills/e3-ui-cli/SKILL.md +1 -5
- package/skills/east/SKILL.md +31 -464
- 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 +29 -1652
- 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 +12 -33
- package/skills/east-py-io/SKILL.md +1 -5
- package/skills/east-py-std/SKILL.md +1 -5
- package/skills/east-ui/SKILL.md +220 -1332
|
@@ -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).
|
|
@@ -1,12 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: east-py-datascience
|
|
3
|
-
description: "Data science and machine learning platform functions for the East language (TypeScript types
|
|
3
|
+
description: "Data science and machine learning platform functions for the East language (TypeScript types plus directly callable Python implementations). Use when an East program needs (1) optimization: MADS (derivative-free), Optuna (Bayesian), SimAnneal / ALNS (combinatorial), Scipy, coordinate descent (Optimization), Google OR-Tools (constraint programming, vehicle routing, LP/MIP, graphs); (2) machine learning: XGBoost, LightGBM, NGBoost, Gaussian processes, Torch MLP, Lightning; (3) Bayesian and hierarchical models with PyMC; (4) causal inference with DoWhy, EconML DML and ALE, or one declarative experiment with Causal.experiment (naive vs adjusted effect, overlap, robustness, an honesty verdict); (5) discrete event simulation of an economic ontology (Simulation); (6) Sklearn preprocessing, metrics and splits, MAPIE conformal intervals, SHAP explanations; (7) calling the east_py_datascience functions (xgboost_train_regressor, mads_optimize, …) from python or inside an East.function body."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
## Detailed skill scope
|
|
7
|
-
|
|
8
|
-
Data science and machine learning platform functions for the East language (TypeScript types + directly-callable Python implementations). Use when writing East programs that need optimization (MADS, Optuna, SimAnneal, ALNS, Scipy, Optimization, GoogleOr), machine learning (XGBoost, LightGBM, NGBoost, Torch MLP, Lightning, GP), Bayesian inference (PyMC), causal inference (Causal: DoWhy, EconML DML, ALE), simulation (Simulation DES), ML utilities (Sklearn preprocessing, metrics, splits), conformal prediction (MAPIE), or model explainability (SHAP). Triggers for: (1) Writing East programs with @elaraai/east-py-datascience, (2) Derivative-free optimization with MADS, (3) Bayesian optimization with Optuna, (4) Discrete/combinatorial optimization with SimAnneal or ALNS, (5) Gradient boosting with XGBoost or LightGBM, (6) Probabilistic predictions with NGBoost or GP, (7) Neural networks with Torch MLP or Lightning, (8) Data preprocessing and metrics with Sklearn, (9) Conformal prediction intervals with MAPIE, (10) Model explainability with Shap, (11) Iterative coordinate descent with Optimization, (12) Constraint programming, vehicle routing, LP/MIP, or graph algorithms with GoogleOr, (13) Bayesian regression, hierarchical models, and multi-layer estimation with PyMC, (14) Economic ontology simulation via discrete event simulation with Simulation, (15) One declarative causal experiment — naive vs adjusted effect, overlap, robustness, and an honesty verdict — with Causal.experiment, (16) Calling the east_py_datascience functions (xgboost_train_regressor, mads_optimize, …) from a project's own Python @East.platform_function, or inside an East.function body — the same object does both.
|
|
9
|
-
|
|
10
6
|
# East Data Science
|
|
11
7
|
|
|
12
8
|
Data science and machine learning platform functions for East: optimisation,
|
|
@@ -72,7 +68,7 @@ Task → What do you need?
|
|
|
72
68
|
│ ├─ .iterative(objective, paramSpaces, config) — the whole objective per move
|
|
73
69
|
│ ├─ .iterativeIncremental(elementObjective, paramSpaces, config) — a per-element contribution, recomputed only
|
|
74
70
|
│ │ where a move changed it (coordinate or swap mode)
|
|
75
|
-
│ └─ .iterativeGrouped(groupObjective, paramSpaces, config) — contributions grouped by
|
|
71
|
+
│ └─ .iterativeGrouped(groupObjective, paramSpaces, config) — contributions grouped by value (employees, bins,
|
|
76
72
|
│ vehicles): a move from A to B recomputes groups A and B
|
|
77
73
|
├─ GoogleOr (OR-Tools)
|
|
78
74
|
│ ├─ CP-SAT → .cpsatSolve(), .cpsatSolveAll()
|
|
@@ -130,7 +126,7 @@ Task → What do you need?
|
|
|
130
126
|
│ │ not_estimable; `adjusted` is none when the engine refuses. DoWhy / EconML / PyALE are internal.)
|
|
131
127
|
│ └─ What real trial would confirm it? → .designValidation([Row], data, config, result, designConfig)
|
|
132
128
|
│ (a randomised-trial recipe: sample size, split options, match-on categories, power curve, rationale)
|
|
133
|
-
│ Honesty caveats: `causal` means robust to the
|
|
129
|
+
│ Honesty caveats: `causal` means robust to the observed backdoor set and the refuters that ran — not correctly
|
|
134
130
|
│ signed, free of reverse causation or of unobserved confounding. overlap.support_strength (refused / thin /
|
|
135
131
|
│ strong vs config.strong_overlap, default 0.55) tempers thin support to modest; opt-in config.evalue_floor folds
|
|
136
132
|
│ a weak E-value (risk-ratio scale) into modest; opt-in config.expected_sign flags an implausibly signed effect
|
|
@@ -175,31 +171,14 @@ A model blob round-trips: what a train function returns is exactly what the
|
|
|
175
171
|
predict and explain functions take — store it in a dataset, pass it between
|
|
176
172
|
tasks, or hand it to `Shap`.
|
|
177
173
|
|
|
178
|
-
## Common
|
|
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
|
|
174
|
+
## Common patterns
|
|
198
175
|
|
|
199
|
-
|
|
200
|
-
`
|
|
201
|
-
|
|
202
|
-
|
|
176
|
+
Search the index for a module's worked examples (`XGBoost train predict`,
|
|
177
|
+
`MADS optimize`, …); each config is a struct whose every field is an Option,
|
|
178
|
+
spelled `some(value)` or `none`. An optimiser's objective is an East function
|
|
179
|
+
of the decision vector, `East.function([VectorType(FloatType)], FloatType, …)`,
|
|
180
|
+
bound with `$.const` and passed with the start point, the bounds and the
|
|
181
|
+
config; the result carries `x_best` and `f_best` (see the Quick Start).
|
|
203
182
|
|
|
204
183
|
## Calling from Python (the functions directly)
|
|
205
184
|
|
|
@@ -249,7 +228,7 @@ Rules:
|
|
|
249
228
|
xgboost_predict(xgboost_train_regressor(X, y, cfg), X))` — the calls are
|
|
250
229
|
`Platform` nodes; `East.compile(fn, platform=east_py_datascience.platform)`
|
|
251
230
|
runs it (the list the e3 python runner registers).
|
|
252
|
-
- **The generic ones take the type argument
|
|
231
|
+
- **The generic ones take the type argument first in a body**, as TypeScript
|
|
253
232
|
reads: `causal_experiment(RowType, rows, config)`,
|
|
254
233
|
`alns_optimize(SolutionType, initial, objective, destroy, repair, config)`.
|
|
255
234
|
From python they take the values alone (`causal_experiment(rows, config)`):
|
|
@@ -266,7 +245,7 @@ For the East-value API (eager methods, `coerce_to`, `to_numpy` / `to_torch`,
|
|
|
266
245
|
|
|
267
246
|
## Related skills
|
|
268
247
|
|
|
269
|
-
- **e3** —
|
|
248
|
+
- **e3** — required to run these: they need the python runtime, so wrap each
|
|
270
249
|
call in an `e3.task` with a python runner (`{ runner: { runtime: 'east-py',
|
|
271
250
|
platforms: ['east-py-datascience'] } }` — the typed runner resolves east-py
|
|
272
251
|
from the project's `.venv`, no `uv run` wrapper needed). They do not run on
|
|
@@ -1,12 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: east-py-io
|
|
3
|
-
description: "I/O platform functions for the East language on the Python runtime
|
|
3
|
+
description: "I/O platform functions for the East language on the Python runtime: SQL databases (SQLite, PostgreSQL, MySQL, Access), NoSQL (Redis, MongoDB), S3 storage, file transfers (FTP, SFTP), file formats (XLSX, XML) and compression (Gzip, Zip, Tar). Use when writing Python (not the TypeScript DSL) that (1) calls east_py_io functions (sqlite_select, mongo_find, s3_put_object, ftp_get, xlsx_read, gzip_compress, …) from a project's own @East.platform_function or inside an East.function body — the same object does both; (2) registers the east_py_io platform list with compile(); (3) builds connection configs (SqliteConfigType, PostgresConfigType, RedisConfigType, S3ConfigType, …); (4) follows the connect → handle → operate → close lifecycle. For East programs in TypeScript against these functions, use east-node-io."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
## Detailed skill scope
|
|
7
|
-
|
|
8
|
-
I/O platform functions for the East language on the Python runtime - SQL databases (SQLite, PostgreSQL, MySQL, Access), NoSQL (Redis, MongoDB), S3 storage, file transfers (FTP, SFTP), file formats (XLSX, XML), and compression (Gzip, Zip, Tar). Use when writing Python (not the TypeScript DSL) that calls or registers these platform functions. Triggers for: (1) Calling east_py_io functions (sqlite_select, mongo_find, s3_put_object, ftp_get, xlsx_read, gzip_compress, ...) from a project's own Python @East.platform_function, or inside an East.function body — the same object does both, (2) Registering the east_py_io platform list with compile() so East programs can use SQL/NoSQL/Storage/Transfer/Format/Compression on the Python runtime, (3) Building connection configs (SqliteConfigType, PostgresConfigType, RedisConfigType, S3ConfigType, FtpConfigType, ...) in Python, (4) The connect -> handle -> operate -> close connection lifecycle. For authoring East programs in TypeScript against these functions, use the east-node-io skill instead.
|
|
9
|
-
|
|
10
6
|
# East.py I/O Platform Functions
|
|
11
7
|
|
|
12
8
|
`east_py_io` is the Python implementation of the East I/O platform: SQL and
|
|
@@ -1,12 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: east-py-std
|
|
3
|
-
description: "Standard platform functions for the East language on the Python runtime
|
|
3
|
+
description: "Standard platform functions for the East language on the Python runtime: console, environment variables, filesystem, HTTP fetch, crypto, time, path, random, large-JSON reading and testing. Use when writing Python (not the TypeScript DSL) that (1) calls east_py_std functions (env_get, fs_read_file, fetch_request, crypto_uuid, random_normal, …) from python or inside an East.function body — the same object does both; (2) registers the east_py_std platform list with compile(); (3) builds FetchRequestConfigType requests; (4) draws deterministic random streams with random_seed; (5) reads a JSON document too large to decode whole with json_open / json_more / json_next, against a published contract. For East programs in TypeScript against these functions, use east-node-std."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
## Detailed skill scope
|
|
7
|
-
|
|
8
|
-
Standard platform functions for the East language on the Python runtime - console, environment variables, filesystem, HTTP fetch, crypto, time, path, random, large-JSON reading, testing. Use when writing Python (not the TypeScript DSL) that calls or registers these platform functions. Triggers for: (1) Calling east_py_std functions (env_get, fs_read_file, fetch_request, crypto_uuid, random_normal, ...) from python or inside an East.function body — the same object does both, (2) Registering the east_py_std platform list with compile() so East programs can use Console/Env/FileSystem/Fetch/Crypto/Time/Path/Random/Json/Test on the Python runtime, (3) Building FetchRequestConfigType requests in Python, (4) Deterministic random streams with random_seed, (5) Reading a JSON document too large to decode whole — ingesting a multi-gigabyte payload from another system — with json_open / json_more / json_next, strictly against a published contract. For authoring East programs in TypeScript against these functions, use the east-node-std skill instead.
|
|
9
|
-
|
|
10
6
|
# East.py Standard Platform Functions
|
|
11
7
|
|
|
12
8
|
`east_py_std` is the Python implementation of the East standard platform:
|