sutra-dev 0.2.0__py3-none-any.whl

sutra_compiler/stdlib/axons.su

@@ -0,0 +1,53 @@
+// Canonical Sutra declaration for the Axon class.
+//
+// Spec: planning/sutra-spec/axons.md.
+//
+// An axon is a bundle of named variables passed as a single value —
+// closer to a Haskell-monad-shaped structuring construct than a
+// runtime hash map (no runtime input → output lookup, no iteration,
+// no schema). The user-facing API resembles a dict in syntax only.
+//
+// At the substrate level the operations route to:
+//   axon_new()        → a zero vector at runtime dim
+//   axon_add(a, k, v) → a + bind(basis_vector(k), v)
+//   axon_item(a, k)   → unbind(basis_vector(k), a)
+//
+// String keys are compile-time identifiers; the runtime auto-embeds
+// them into basis vectors at the call boundary.
+//
+// Surface forms wired today:
+//   - `Axon a;`             → `a = _VSA.axon_new()`
+//   - `a.add(k, v);`        → `a = _VSA.axon_add(a, k, v)`
+//                              (statement form: augmented assignment;
+//                              the instance method is "void-returning"
+//                              from the user's POV — the compiler
+//                              rebinds `a` to the returned new axon)
+//   - `a.item(k)` (expr)    → `_VSA.axon_item(a, k)`
+//   - `Axon.axon_add(a, ...)` → `_VSA.axon_add(a, ...)` also works
+//                              (static-class-method form, in case
+//                              you want to be explicit)
+//
+// The augmented-assignment rule for void-returning instance methods
+// is conceptually general (every class should work this way), but
+// the wiring in codegen_base.py is currently axon-specific. Other
+// classes still error if you try `obj.method(args)` on a
+// non-class-namespace receiver. Generalizing the rule is a separate
+// piece of work.
+//
+// What is deferred:
+//   - Per-entry class tags (deemed an IDE-level concern; the user's
+//     idiom is to declare the retrieval type explicitly:
+//     `Cat c = a.item("cat");`).
+//   - Lazy evaluation across function/program boundaries — the spec
+//     says only receiver-referenced keys materialize at the
+//     boundary; today the full bundle crosses. Within a single
+//     function, the SSA-elision pass DOES drop adds whose keys are
+//     never read (and the axon doesn't escape). Cross-function
+//     analysis is the unimplemented piece.
+
+
+class Axon extends vector {
+    static intrinsic method Axon axon_new();
+    static intrinsic method Axon axon_add(Axon a, string key, vector value);
+    static intrinsic method vector axon_item(Axon a, string key);
+}

sutra_compiler/stdlib/embed.su

@@ -0,0 +1,48 @@
+// Canonical Sutra definition for the `embed` operation — turn a
+// string into a semantic vector by running it through the frozen
+// embedding model (Ollama / nomic-embed-text today).
+//
+// Today this is hardcoded as the `def embed(self, s)` method on the
+// runtime VSA class and batched via `def embed_batch` for the
+// compile-time prefetch pass. See `_emit_prelude` in codegen.py.
+// This file is the target shape for the inliner. See stdlib/README.md.
+//
+// `embed` is a pure intrinsic — it has no Sutra-level body. The
+// string goes to an external process (the embedding model), a
+// vector comes back. There's nothing to inline; the function call
+// is a leaf in the dataflow graph.
+//
+// Listing it here anyway for completeness — so the stdlib directory
+// is the single source of truth for every system function's
+// signature and status. Once the inliner lands, `embed` will be
+// marked `@intrinsic` (or whatever the chosen syntax is) and pass
+// through the inliner unchanged.
+
+
+// ==========================================================================
+// Section 3 — pure intrinsic (no Sutra body)
+// ==========================================================================
+//
+// embed — string → semantic vector.
+//
+//   @intrinsic
+//   function vector embed(string s) {
+//       // runtime: hits Ollama, caches to disk, mean-centers,
+//       // L2-normalizes, returns the semantic block padded with
+//       // zeros in the synthetic block.
+//   }
+//
+// Intrinsic primitive. The compile-time prefetch (collecting every
+// `basis_vector("...")` / `embed("...")` string literal at module
+// init and batching them into one Ollama call) stays a codegen-
+// level optimization — it's transparent to the .su-level semantics.
+//
+// basis_vector is an alias for embed with a different spelling (VSA-
+// role allocation vs. pure embedding). Both hit the same intrinsic.
+//
+// ==========================================================================
+
+
+class Embedding extends vector {
+    static intrinsic method vector embed(string s);
+}

sutra_compiler/stdlib/javascript_object.su

@@ -0,0 +1,18 @@
+// JavaScriptObject — the catch-all class for values that come out of
+// JavaScript / TypeScript code without resolvable static types. A
+// transpiled `function f(x) { return x + x; }` parameter `x` is
+// declared `JavaScriptObject x` because the source had no type
+// annotation and the value could be anything.
+//
+// Today this is intentionally a near-empty class. Sutra's substrate
+// already handles vector arithmetic and the auto-promotion of
+// scalars to vectors, so for numeric JS code, treating
+// JavaScriptObject as "just a vector" is enough — `x + x` lowers to
+// tensor addition without further help. Real JS semantics (type
+// coercion in `+` between strings and numbers, ===-vs-==, prototype
+// chains, etc.) live in deferred work.
+//
+// Spec: planning/sutra-spec/javascript-object.md (TBD).
+
+class JavaScriptObject extends vector {
+}

sutra_compiler/stdlib/logic.su

@@ -0,0 +1,202 @@
+// Canonical Sutra definitions for truth-axis and logic operations.
+//
+// Today these are hardcoded as runtime methods in codegen.py —
+// see the `def defuzzify(...)`, `def logical_and(...)`, `def eq(...)`,
+// `def gt(...)` etc. sections of _emit_prelude. This file is where
+// they want to live: as Sutra source the compiler parses, inlines
+// into user programs, and unrolls/fuses at compile time. See
+// stdlib/README.md for the broader plan.
+//
+// Two sections below:
+//   1. IMPLEMENTED IN SUTRA — bodies the parser accepts today.
+//   2. BLOCKED ON INTRINSICS — bodies that reach into primitives
+//      (dot, sqrt, tanh, axis projectors, cached polynomial
+//      matrices) that aren't language-level yet. These stay as
+//      commented-out pseudo-Sutra until an `intrinsic` mechanism
+//      or primitive-op surface lands.
+
+
+// ==========================================================================
+// Section 1 — implemented in pure Sutra
+// ==========================================================================
+
+
+// defuzzy — polarize any value along the truth axis.
+//
+// Iterates cosine equality with `true` ten times. Under the
+// eps-guarded cosine form of `==`, inputs with truth=0 stay at 0
+// (unknown stays unknown — the neutral point is a fixed point of
+// equality-with-true) and inputs with truth!=0 sharpen toward ±1.
+//
+// Ten iterations is the spec-level definition. One pass mathematically
+// suffices for well-separated inputs; the loop is kept because the
+// fully-unrolled form is what the compiler targets for fusion.
+//
+// Historical note: the original formulation was just `v = v == true`
+// (one pass, no loop). That had a pathology where `unknown` (truth=0)
+// got pulled toward false because the zero-norm case in cosine
+// similarity was handled with a branch. The eps-guarded divide in
+// the current `==` fixes the fixed-point at 0 without branching, which
+// is why the loop is safe to unroll.
+function fuzzy defuzzy(fuzzy v) {
+    loop (10) {
+        v = v == true;
+    }
+    return v;
+}
+
+
+// logical_not — Kleene K₃ negation on the truth axis.
+//
+// Polynomial form: NOT(v) = -v. Exact on {-1, 0, +1}, preserves the
+// neutral point (NOT(unknown) = unknown), differentiable everywhere.
+// Sign-flip is the entirety of the operation.
+function fuzzy logical_not(fuzzy v) {
+    return 0 - v;
+}
+
+
+// logical_and — Kleene K₃ AND. Lagrange polynomial, exact on
+// {-1, 0, +1}², smooth everywhere:
+//
+//   a ∧ b = (a + b + ab - a² - b² + a²b²) / 2
+//
+// No absolute value → no compile-time kink → no branch. Every
+// subexpression stays a tensor op. This is the form the fusion pass
+// wants to see once user-written `a && b` inlines to this body.
+function fuzzy logical_and(fuzzy a, fuzzy b) {
+    return (a + b + a * b - a * a - b * b + a * a * b * b) * 0.5;
+}
+
+
+// logical_or — Kleene K₃ OR. Dual polynomial to AND:
+//
+//   a ∨ b = (a + b - ab + a² + b² - a²b²) / 2
+function fuzzy logical_or(fuzzy a, fuzzy b) {
+    return (a + b - a * b + a * a + b * b - a * a * b * b) * 0.5;
+}
+
+
+// logical_nand — NOT(AND). Composition over the existing primitives;
+// the inliner expands the !(...) wrapper and then the AND polynomial,
+// so the final emitted form is one polynomial subtracted from a
+// constant — no new substrate primitive is introduced.
+function fuzzy logical_nand(fuzzy a, fuzzy b) {
+    return !logical_and(a, b);
+}
+
+
+// logical_xor — Kleene K₃ XOR. Closed-form polynomial: -a·b.
+//
+// Verification on the K₃ grid {-1, 0, +1}²:
+//   (1,  1)   -> -1   (T XOR T = F)
+//   (1, -1)   -> +1   (T XOR F = T)
+//   (-1, 1)   -> +1   (F XOR T = T)
+//   (-1,-1)   -> -1   (F XOR F = F)
+//   (0,  1)   ->  0   (U XOR T = U — unknown is a fixed point)
+//   (1,  0)   ->  0   (T XOR U = U)
+//
+// Equivalent to the longer composition `(a && !b) || (!a && b)`,
+// which observation: reduces to `-a·b` after polynomial folding —
+// see docs/compilation.md § "Worked examples". Shipping the closed
+// form directly so the simplifier doesn't have to discover it.
+function fuzzy logical_xor(fuzzy a, fuzzy b) {
+    return 0 - a * b;
+}
+
+
+// logical_xnor — Kleene K₃ XNOR / IFF. NOT(XOR), which simplifies to
+// the bare product:
+//
+//   (1,  1)   -> +1   (T <-> T = T)
+//   (1, -1)   -> -1   (T <-> F = F)
+//   (-1,-1)   -> +1   (F <-> F = T)
+//   (0,  1)   ->  0   (unknown bilateral)
+//
+// Same shape as logical_xor with the sign flipped. `iff` is the
+// natural-language alias the lexer also accepts.
+function fuzzy logical_xnor(fuzzy a, fuzzy b) {
+    return a * b;
+}
+
+
+// neq lives in similarity.su — it's a composition over vector cosine
+// similarity, not a truth-axis primitive. Cross-referenced there.
+
+
+// lt — strictly less than. `>` with sides swapped.
+function fuzzy lt(complex a, complex b) {
+    return b > a;
+}
+
+
+// ge / le — on the differentiable-tanh scheme, `>=` and `<=` collapse
+// to `>` and `<`: both give tanh(0) = 0 on exact ties. Programs that
+// need to distinguish strict from tie compose with `==` (cosine
+// similarity, crisp on identical operands).
+function fuzzy ge(complex a, complex b) {
+    return a > b;
+}
+
+function fuzzy le(complex a, complex b) {
+    return a < b;
+}
+
+
+// ==========================================================================
+// Section 2 — blocked on intrinsics
+// ==========================================================================
+//
+// defuzzify_trit — three-way polarizer (true / false / unknown) with
+// a β-sharpening knob instead of the straight cosine-eq loop.
+//
+//   function trit defuzzify_trit(trit v, int iters, scalar beta) {
+//       vector t = truth_projector @ v;
+//       loop (iters) {
+//           t = sign_polarize(t, beta);
+//       }
+//       return t;
+//   }
+//
+// Blocked on: `truth_projector` as a matrix literal, `sign_polarize`
+// β primitive.
+
+
+// gt — differentiable smooth sign on real-axis difference.
+//
+//   function fuzzy gt(complex a, complex b) {
+//       vector diff   = a - b;
+//       vector diff_r = real_projector @ diff;
+//       vector signed = tanh(100.0 * diff_r);
+//       return truth_from_real @ signed;
+//   }
+//
+// Blocked on: axis-projector matrix literals, `tanh` on vectors,
+// `@` matmul as a Sutra operator.
+//
+// See also:
+//   similarity.su — `eq`, `neq`, cosine operations on vectors.
+//   numbers.su    — `complex_mul`, `make_real`, `make_complex`, `make_char`.
+//   vectors.su    — `bind`, `unbind`, `bundle`, permutation ops.
+//   memory.su     — `zero_vector`, hashmap ops.
+//   rotation.su   — rotation-matrix construction and eigenrotation loop.
+//   embed.su      — the `embed` LLM-call intrinsic.
+
+
+// ==========================================================================
+// Section 3 — intrinsic declarations
+// ==========================================================================
+//
+// `gt` and `make_truth` are runtime primitives. `gt` uses tanh on
+// the real-axis difference (not expressible in pure Sutra until
+// tanh has a language-level surface); `make_truth` writes a scalar
+// into the truth-axis slot (not expressible until axis-indexed
+// write lands).
+
+intrinsic function fuzzy gt(complex a, complex b);
+intrinsic function fuzzy make_truth(scalar t);
+// truth_axis — read AXIS_TRUTH from a fuzzy vector and return it as
+// a scalar. The transpiler-emitted if/else lowering uses this to
+// pull a scalar out of `defuzzy(cond)` for use as a softmax score
+// in `select`.
+intrinsic function scalar truth_axis(vector v);

sutra_compiler/stdlib/math.su

@@ -0,0 +1,12 @@
+
+
+
+class Math extends vector {
+    static intrinsic method scalar log(scalar x);
+    static intrinsic method scalar sqrt(scalar x);
+    static intrinsic method scalar exp(scalar x);
+    static intrinsic method scalar sin(scalar x);
+    static intrinsic method scalar cos(scalar x);
+    static intrinsic method scalar tan(scalar x);
+    static intrinsic method scalar pow(scalar x, scalar y);
+}

sutra_compiler/stdlib/memory.su

@@ -0,0 +1,82 @@
+// Canonical Sutra definitions for memory / lookup operations:
+// `zero_vector`, the rotation-hashmap `hashmap_get` / `hashmap_set`,
+// and the identity-or-nearest-key map lookup.
+//
+// Today these are hardcoded as runtime methods in codegen.py — see
+// `def zero_vector`, `def hashmap_get`, `def hashmap_set`, and the
+// emitted `_vector_map_lookup` helper. This file is the target shape
+// for the inliner. See stdlib/README.md.
+//
+// Every function below is currently blocked on intrinsics — they
+// need indexed construction, cosine-based argmax, or functional-
+// update semantics that aren't Sutra-callable yet.
+
+
+// ==========================================================================
+// Section 2 — blocked on intrinsics
+// ==========================================================================
+//
+// zero_vector — the zero vector at runtime dim. Every component is 0,
+// including every synthetic slot. Used as the neutral element for
+// bundling and as the starting state for constructors like
+// `make_real` / `make_complex`.
+//
+//   function vector zero_vector() {
+//       return _VSA_zeros(runtime_dim);
+//   }
+//
+// Blocked on: `_VSA_zeros(N)` primitive — a d-dim zero vector
+// literal. Could alternatively be expressed as an axis-indexed
+// assignment starting from a fresh allocation once those surfaces
+// land.
+
+
+// hashmap_get — look up a key in a rotation hashmap, returning the
+// bound value. Keys are vectors; lookup is cosine-nearest against
+// the set of rotation-bound (key, value) pairs.
+//
+//   function vector hashmap_get(map m, vector key) {
+//       vector bound = unbind(key, m.state);
+//       return snap(bound, m.values);
+//   }
+//
+// Blocked on: `map` type's field access (`m.state`, `m.values`),
+// `unbind` inlining (see vectors.su), `snap` (substrate cleanup
+// primitive — see similarity.su).
+
+
+// hashmap_set — functional update. Returns a new map with the
+// (key, value) pair added or overwritten.
+//
+//   function map hashmap_set(map m, vector key, vector value) {
+//       vector fresh = bundle(m.state, bind(key, value));
+//       return map_with_state(m, fresh);
+//   }
+//
+// Blocked on: same as hashmap_get, plus `map_with_state` constructor
+// for the map-type update.
+
+
+// map_lookup — identity-first lookup over a list of (key, value)
+// pairs. Checks each key against the query by identity (same Python
+// object) first; falls back to cosine-nearest match against the
+// stored keys.
+//
+//   function vector map_lookup(pair[] pairs, vector key) {
+//       foreach (pair p in pairs) {
+//           if (p.key is key) {
+//               return p.value;
+//           }
+//       }
+//       return argmax_cosine(key, [p.key for p in pairs]).value;
+//   }
+//
+// Blocked on: `is` identity comparison, comprehension syntax,
+// tuple/pair destructuring, and the `argmax_cosine` composition
+// from similarity.su.
+
+
+
+class Memory extends vector {
+    static intrinsic method vector zero_vector();
+}

sutra_compiler/stdlib/numbers.su

@@ -0,0 +1,99 @@
+// Canonical Sutra definitions for the number family (int / float /
+// complex / char). All four share the synthetic[AXIS_REAL] and
+// synthetic[AXIS_IMAG] slots at the vector level; `complex` is the
+// only one that occupies both, while `int` and `float` leave imag at
+// 0 and `char` additionally sets synthetic[AXIS_CHAR_FLAG] = 1.
+//
+// Today the constructors (make_real, make_complex, make_char) and
+// the arithmetic primitives (complex_mul and the three cached
+// mul-matrices) are hardcoded as runtime methods in codegen.py —
+// see `def make_real`, `def make_complex`, `def make_char`, and the
+// complex_mul block. This file is the target shape for the inliner
+// to consume. See stdlib/README.md.
+//
+// Every function here is currently blocked on intrinsics — the
+// primitives they need (writing a scalar into a specific synthetic
+// slot; matrix literals; the `@` matmul operator on a Sutra-level
+// matrix) aren't exposed at the language level yet.
+
+
+// ==========================================================================
+// Section 2 — blocked on intrinsics
+// ==========================================================================
+//
+// make_real — scalar on the real axis, zero elsewhere.
+//
+//   function complex make_real(scalar x) {
+//       vector v                    = zero_vector();
+//       v[semantic_dim + AXIS_REAL] = x;
+//       return v;
+//   }
+//
+// Blocked on: `zero_vector()` surface, indexed write to a synthetic
+// slot.
+
+
+// make_complex — two scalars placed on the real and imag axes.
+//
+//   function complex make_complex(scalar r, scalar i) {
+//       vector v                    = zero_vector();
+//       v[semantic_dim + AXIS_REAL] = r;
+//       v[semantic_dim + AXIS_IMAG] = i;
+//       return v;
+//   }
+//
+// Blocked on: same as make_real.
+
+
+// make_char — integer code point on the real axis + char flag on the
+// synthetic axis.
+//
+//   function char make_char(int code) {
+//       vector v                          = zero_vector();
+//       v[semantic_dim + AXIS_REAL]       = code;
+//       v[semantic_dim + AXIS_CHAR_FLAG]  = 1.0;
+//       return v;
+//   }
+//
+// Blocked on: same as make_real.
+
+
+// complex_mul — pure-matmul complex multiplication using three cached
+// matrices: `_swap_ri` (real-imag swap), `_cm_real` (extract real
+// product into real slot), `_cm_imag` (extract imag product into
+// imag slot).
+//
+//   function complex complex_mul(complex a, complex b) {
+//       vector ab         = a * b;
+//       vector swapped_ab = (_swap_ri @ a) * b;
+//       return _cm_real @ ab + _cm_imag @ swapped_ab;
+//   }
+//
+// Blocked on: matrix literals for the three cached matrices, `@`
+// matmul as a Sutra operator. The matrices themselves are
+// d×d sparse with a handful of entries — the fusion pass wants
+// to see them as compile-time constants so chains of complex_mul
+// collapse into a single cached matrix.
+
+
+// conj — complex conjugate. Flips the imag-axis sign, leaves the real
+// axis and everything else alone.
+//
+//   function complex conj(complex c) {
+//       vector out                           = c;
+//       out[semantic_dim + AXIS_IMAG]        = -c[semantic_dim + AXIS_IMAG];
+//       return out;
+//   }
+//
+// Blocked on: indexed read/write to synthetic slots. Alternative
+// formulation as a matrix (diag of 1s with a -1 at the imag slot)
+// needs matmul + matrix-literal surfaces.
+
+
+
+class Numbers extends vector {
+    static intrinsic method complex make_real(scalar x);
+    static intrinsic method complex make_complex(scalar r, scalar i);
+    static intrinsic method char make_char(int code);
+    static intrinsic method complex complex_mul(complex a, complex b);
+}

sutra_compiler/stdlib/rotation.su

@@ -0,0 +1,83 @@
+// Canonical Sutra definitions for rotation construction and the
+// eigenrotation loop that runs behind runtime-conditional `loop` /
+// `while` constructs.
+//
+// Today these are hardcoded as runtime methods in codegen.py — see
+// `def make_random_rotation`, `def compile_prototypes`, and `def loop`
+// (the `_VSA.loop` geometric-rotation runner). This file is the
+// target shape for the inliner. See stdlib/README.md.
+//
+// All of this is deeply substrate-level: block-diagonal Haar rotations
+// built from QR decomposition of a Gaussian matrix, eigendecomposition
+// for fractional powers, prototype codebooks with per-frame random
+// rotations. Every function below is currently blocked on intrinsics.
+
+
+// ==========================================================================
+// Section 2 — blocked on intrinsics
+// ==========================================================================
+//
+// make_random_rotation — block-diagonal Haar rotation scaled so its
+// largest eigenphase ≈ `angle`. Haar-uniform in the semantic block,
+// identity in the synthetic block — matches the bind-rotation layout
+// so eigenrotation loops walk the semantic subspace while the
+// synthetic subspace (real / imag / truth / char-flag) stays untouched.
+//
+//   function matrix make_random_rotation(scalar angle, int n_planes,
+//                                        int seed) {
+//       matrix A        = randn(semantic_dim, semantic_dim, seed);
+//       (Q_sem, _)      = qr(A);
+//       (w, V)          = eig(Q_sem);
+//       matrix phases   = angle_of(w) * (angle / pi);
+//       matrix R_sem    = real(V @ diag(exp(i * phases)) @ inverse(V));
+//       matrix R        = identity(dim);
+//       R[:semantic_dim, :semantic_dim] = R_sem;
+//       return R;
+//   }
+//
+// Blocked on: `randn`, `qr`, `eig`, complex exponential, matrix slice
+// assignment, `@` matmul. Whole-pipeline primitive.
+
+
+// compile_prototypes — take a set of prototype vectors, apply a
+// frame-seeded random rotation to each, and bundle the results into
+// a codebook the eigenrotation loop can match against.
+//
+//   function vector compile_prototypes(vector[] prototype_vectors,
+//                                      int frame_seed) {
+//       matrix frame = make_random_rotation(pi / 4, 20, frame_seed);
+//       vector[] framed = [frame @ p for p in prototype_vectors];
+//       return bundle(framed);
+//   }
+//
+// Blocked on: comprehension syntax, `@` matmul, variadic bundle.
+
+
+// eigenrotation loop — what `loop(condition)` / `while` compile to.
+// Takes a state vector, a rotation matrix, and a compiled prototype
+// codebook; iterates `state = R @ state` until the state matches a
+// prototype by the substrate's cleanup metric (cosine on the default
+// CPU runtime).
+//
+//   function (string, vector, int) eigenrotation_loop(
+//       vector initial_state,
+//       matrix R,
+//       vector prototype_codebook,
+//       int max_iters,
+//       scalar match_threshold) {
+//       vector state = initial_state;
+//       int    i     = 0;
+//       loop (max_iters as i) {
+//           state = R @ state;
+//           string match = match_prototype(state, prototype_codebook,
+//                                          match_threshold);
+//           if (match != unknown) {
+//               return (match, state, i);
+//           }
+//       }
+//       return (unknown, state, max_iters);
+//   }
+//
+// Blocked on: `@` matmul, `match_prototype` substrate primitive,
+// tuple return types, early-return inside `loop`, `unknown` as a
+// Sutra-level sentinel for the string type.