sutra-dev 0.9.2__tar.gz → 0.9.4__tar.gz

{sutra_dev-0.9.2/sutra_dev.egg-info → sutra_dev-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sutra-dev
-Version: 0.9.2
+Version: 0.9.4
 Summary: Compiler for the Sutra programming language — tensor ops on frozen-LLM embedding vectors.
 Author: Emma Leonhart
 License-Expression: AGPL-3.0-only

{sutra_dev-0.9.2 → sutra_dev-0.9.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sutra-dev"
-version = "0.9.2"
+version = "0.9.4"
 description = "Compiler for the Sutra programming language — tensor ops on frozen-LLM embedding vectors."
 readme = "README.md"
 requires-python = ">=3.11"

{sutra_dev-0.9.2 → sutra_dev-0.9.4}/sutra_compiler/__init__.py

@@ -28,7 +28,7 @@ The compiler is intentionally liberal where the spec is still open
 forms and flags the clearly-forbidden ones.
 """
 
-__version__ = "0.9.2"
+__version__ = "0.9.4"
 
 from .diagnostics import Diagnostic, DiagnosticLevel, DiagnosticBag
 from .lexer import Lexer, Token, TokenKind

{sutra_dev-0.9.2 → sutra_dev-0.9.4}/sutra_compiler/__main__.py

@@ -325,11 +325,24 @@ def _run_execute(path: str, *, runtime_dim: int, runtime_seed: int,
         return 1
     mod = types.ModuleType("_sutra_run")
     mod.__file__ = f"<generated from {path}>"
-    exec(compile(py_src, mod.__file__, "exec"), mod.__dict__)
-    if hasattr(mod, "main") and callable(mod.main):
-        result = mod.main()
-        if result is not None:
-            print(_decode_terminal_result(mod, result))
+    try:
+        exec(compile(py_src, mod.__file__, "exec"), mod.__dict__)
+        if hasattr(mod, "main") and callable(mod.main):
+            result = mod.main()
+            if result is not None:
+                print(_decode_terminal_result(mod, result))
+        else:
+            # The substrate program is the body of main(); a file without one
+            # has nothing to run. Say so rather than exiting silently with no
+            # output (a newcomer otherwise can't tell why nothing happened).
+            print(f"{path}: no main() found - nothing to run", file=sys.stderr)
+    except Exception as exc:
+        # A runtime error in the generated module — e.g. a type mismatch the v0.1
+        # validator can't catch yet — should read like a Sutra diagnostic, not an
+        # uncaught Python traceback. KeyboardInterrupt / SystemExit are not caught
+        # (they subclass BaseException, not Exception), so Ctrl-C still works.
+        print(f"{path}: runtime error: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
     return 0
 
 
@@ -387,7 +400,7 @@ def _run_viz(path: str, *, runtime_dim: int, runtime_seed: int,
     # Inject tracing shim: after the _VSA = _TorchVSA(...) line,
     # wrap every method with a tracing version.
     shim = '''
-# ── Tracing shim (injected by --run-viz) ──
+# -- Tracing shim (injected by --run-viz) --
 _orig_embed = _VSA.embed
 _orig_bind = _VSA.bind
 _orig_unbind = _VSA.unbind
@@ -417,7 +430,7 @@ _VSA.embed = _traced_embed
 _VSA.bind = _traced_bind
 _VSA.unbind = _traced_unbind
 _VSA.bundle = _traced_bundle
-# ── End tracing shim ──
+# -- End tracing shim --
 '''
     # Find the _VSA = _TorchVSA(...) line and inject after it
     lines = py_src.split('\n')
@@ -514,6 +527,19 @@ def main(argv: List[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="sutrac",
         description="Validate Sutra (.su) source files.",
+        epilog=(
+            "interactive REPL:\n"
+            "  sutrac repl          Launch the interactive evaluator (takes no\n"
+            "                       file). Type an expression to see its value;\n"
+            "                       declarations accumulate as session state.\n"
+            "\n"
+            "examples:\n"
+            "  sutrac file.su               Validate a source file.\n"
+            "  sutrac --run file.su         Compile and execute (needs torch).\n"
+            "  sutrac --emit file.su        Print the generated PyTorch module.\n"
+            "  sutrac repl                  Explore interactively."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
         "paths",
@@ -541,7 +567,7 @@ def main(argv: List[str] | None = None) -> int:
         help=(
             "Compile the first input file to self-contained torch Python and "
             "print it to stdout. Picks CUDA at module init if available; "
-            "falls back to CPU otherwise. This is the one main codegen target — "
+            "falls back to CPU otherwise. This is the one main codegen target - "
             "PyTorch is the runtime and the tensor-op library Sutra compiles "
             "against."
         ),
@@ -564,7 +590,7 @@ def main(argv: List[str] | None = None) -> int:
             "stdout. The default PyTorch path (--emit/--run) is untouched; this is "
             "the Extropic thermodynamic-sampling compile target (queue.md approach "
             "G). Requires jax + the thrml submodule. Lowering coverage is the "
-            "validated subset only — see codegen_thrml.py."
+            "validated subset only - see codegen_thrml.py."
         ),
     )
     parser.add_argument(

{sutra_dev-0.9.2 → sutra_dev-0.9.4}/sutra_compiler/codegen.py

@@ -246,6 +246,18 @@ class Codegen(BaseCodegen):
         meaningful signal there.
         """
         assert op in ("eq", "neq")
+        # Number-family operands (int/number, incl. arithmetic results
+        # like `n % 3`) route through the exact relu indicator (Emma
+        # 2026-07-08): cosine is degenerate at the zero vector, so a
+        # runtime zero could never == anything — zero-testing was
+        # unreachable. Torch-runtime only (the deprecated numpy backend
+        # keeps its old routing).
+        if (getattr(self, "supports_cast_lowering", False)
+                and self._CAST_FAMILY.get(
+                    self._infer_cast_operand_type(expr.left)) == "number"
+                and self._CAST_FAMILY.get(
+                    self._infer_cast_operand_type(expr.right)) == "number"):
+            return f"_VSA.num_{op}({left_src}, {right_src})"
         if (self._is_synthetic_axis_expr(expr.left)
                 and self._is_synthetic_axis_expr(expr.right)):
             return f"_VSA.{op}_synthetic({left_src}, {right_src})"
@@ -1700,7 +1712,7 @@ class Codegen(BaseCodegen):
         self._emit("distinguish `'a'` (97 with flag) from `97` (97 without).")
         self._emit("Arithmetic on chars works the same as on ints — both")
         self._emit("live on the number axis. Downstream code that cares")
-        self._emit("about the distinction can read the flag via `is_char`.")
+        self._emit("about the distinction can read the flag via `is_string`.")
         self._emit('"""')
         self._emit("v = _np.zeros(self.dim, dtype=_np.float64)")
         self._emit("v[self.semantic_dim + self.AXIS_REAL] = float(codepoint)")

{sutra_dev-0.9.2 → sutra_dev-0.9.4}/sutra_compiler/codegen_base.py

@@ -702,6 +702,19 @@ class BaseCodegen:
     def translate(self, module: ast.Module) -> str:
         self._emit_prelude()
         self._emit()
+        # Pre-pass 0: record every top-level user function's declared
+        # return type, so expression-type checks (e.g. the text-concat
+        # dispatch asking "does f(x) return a string?") can resolve
+        # FORWARD references — a call site is often translated before
+        # its callee. _resolved_return_type only knows class methods and
+        # the stdlib; without this map, `f(1) + " "` with a user
+        # `function string f` fell to the numeric path and crashed at
+        # runtime (round-23 audit).
+        self._user_fn_return_types: dict[str, str] = {}
+        for item in module.items:
+            if (isinstance(item, ast.FunctionDecl)
+                    and item.return_type is not None):
+                self._user_fn_return_types[item.name] = item.return_type.name
         # Pre-pass A: pull in stdlib class intrinsics (e.g.
         # `Tensor.MatrixMul`, `Tensor.matmul`, etc.) so namespaced
         # stdlib calls dispatch to `_VSA.<name>` even though the
@@ -2634,10 +2647,21 @@ class BaseCodegen:
                 f"unroll by hand.",
             )
         if isinstance(stmt, ast.IfStmt):
+            # Design commitment, not a gap (control-flow.md § "`if` /
+            # `else` is parsed but rejected at codegen"): Sutra
+            # conditionals are weighted superpositions, not discrete
+            # branches. The message must hand the newcomer the actual
+            # rewrite, not just the philosophy (round-23 audit).
             raise CodegenNotSupported(
                 stmt,
-                "if/else is not supported by the V1 codegen — the whole "
-                "point is to compile it away into a prototype-table lookup",
+                "`if`/`else` never compiles — by design, Sutra "
+                "conditionals are weighted superpositions, not discrete "
+                "branches. Write `select([score_a, score_b, ...], "
+                "[result_a, result_b, ...])`: the highest score's result "
+                "dominates the output. A boolean two-way branch is "
+                "`select([is_true(cond), is_true(!cond)], [then_value, "
+                "else_value])`. See the control-flow docs and "
+                "examples/fuzzy_dispatch.su for the idiom.",
             )
         if isinstance(stmt, ast.TryStmt):
             self._translate_try_catch(stmt)
@@ -3021,6 +3045,34 @@ class BaseCodegen:
          "char", "Character", "string", "String"}
     )
 
+    #: Types whose values are substrate Strings (text family).
+    _TEXT_TYPES = frozenset({"string", "String", "char", "Character"})
+
+    def _is_text_expr(self, expr: ast.Expr) -> bool:
+        """True iff expr is provably a text (String) value at compile
+        time. Conservative — unknown falls through to the numeric /
+        element-wise `+` paths, same posture as _is_number_expr."""
+        if isinstance(expr, (ast.StringLiteral, ast.CharLiteral,
+                             ast.InterpolatedString)):
+            return True
+        if isinstance(expr, ast.Identifier):
+            return self._var_type.get(expr.name) in self._TEXT_TYPES
+        if isinstance(expr, ast.Parenthesized):
+            return self._is_text_expr(expr.inner)
+        if isinstance(expr, (ast.CastExpr, ast.UnsafeCastExpr)):
+            return (expr.target_type is not None
+                    and expr.target_type.name in self._TEXT_TYPES)
+        if isinstance(expr, ast.BinaryOp) and expr.op == "+":
+            return (self._is_text_expr(expr.left)
+                    and self._is_text_expr(expr.right))
+        if isinstance(expr, ast.Call):
+            if (isinstance(expr.callee, ast.Identifier)
+                    and getattr(self, "_user_fn_return_types", {}).get(
+                        expr.callee.name) in self._TEXT_TYPES):
+                return True
+            return self._resolved_return_type(expr.callee) in self._TEXT_TYPES
+        return False
+
     def _is_synthetic_axis_expr(self, expr: ast.Expr) -> bool:
         """True iff expr is provably a synthetic-axis-encoded value at
         compile time — int, float, complex, scalar, char, or string.
@@ -3380,6 +3432,21 @@ class BaseCodegen:
             )
             if user_op_name is not None:
                 return f"{user_op_name}({left}, {right})"
+            # Text concatenation: `+` with BOTH operands provably text
+            # dispatches to the substrate string_concat (round-17 audit
+            # fix). Without this, lowercase-`string`-typed operands fell
+            # through to ELEMENT-WISE VECTOR ADD — 'ab' + 'cd' silently
+            # summed codepoint axes into garbage — and two string
+            # literals crashed at runtime (host strs reached
+            # string_concat). The String CLASS `operator +` still wins
+            # above for class-typed operands. Literals re-translate with
+            # dest_type="string" so they cross as substrate Strings.
+            if (expr.op == "+" and self.supports_string_runtime
+                    and self._is_text_expr(expr.left)
+                    and self._is_text_expr(expr.right)):
+                lt = self._translate_expr(expr.left, dest_type="string")
+                rt = self._translate_expr(expr.right, dest_type="string")
+                return f"_VSA.string_concat({lt}, {rt})"
             # Logical operators dispatch through the substrate so they
             # work uniformly on bool / fuzzy / trit / truth-axis-vector
             # inputs. Zadeh fuzzy logic — min for AND, max for OR — on
@@ -3589,10 +3656,214 @@ class BaseCodegen:
             return self._embed_expr_src(expr)
         if isinstance(expr, ast.DefuzzyExpr):
             return self._defuzzy_expr_src(expr)
+        if isinstance(expr, ast.InterpolatedString):
+            # `$"hello {s}!"` desugars to a make_string / string_concat
+            # chain — every piece a substrate String, every join a
+            # substrate op (strings.md). Only STRING-TYPED interpolants
+            # are lowerable today: a number/fuzzy interpolant needs the
+            # substrate number→string formatter, which is not built, so
+            # those reject with a steer (same wall as the text casts).
+            if not self.supports_string_runtime:
+                raise CodegenNotSupported(
+                    expr,
+                    "interpolated strings need the substrate String "
+                    "runtime; use the PyTorch backend (codegen_pytorch)."
+                )
+            pieces: list[str] = []
+            for part in expr.parts:
+                if isinstance(part, str):
+                    if part:
+                        pieces.append(f"_VSA.make_string({part!r})")
+                    continue
+                part_t = self._infer_cast_operand_type(part)
+                if self._CAST_FAMILY.get(part_t) == "text":
+                    pieces.append(
+                        self._translate_expr(part, dest_type="string"))
+                    continue
+                if part_t == "int":
+                    # strings.md § Integer formatting: the substrate
+                    # int→string formatter. int ONLY — a fractional
+                    # `number` rendering as its rounded integer would
+                    # silently lie, so it keeps rejecting below.
+                    pieces.append(
+                        f"_VSA.int_to_string("
+                        f"{self._translate_expr(part)})")
+                    continue
+                if part_t is None:
+                    raise CodegenNotSupported(
+                        part,
+                        "interpolated expression must be string- or "
+                        "int-typed and statically inferable — assign it "
+                        "to a `string` (or `int`) variable first, or "
+                        "build the text with make_string / string_concat."
+                    )
+                raise CodegenNotSupported(
+                    part,
+                    f"cannot interpolate a `{part_t}` value: only string- "
+                    "and int-typed interpolants lower (int_to_string is "
+                    "integer-shaped; fractional rendering is not built). "
+                    "For an integer value, declare it `int`; otherwise "
+                    "build the text with make_string / string_concat."
+                )
+            if not pieces:
+                return "_VSA.make_string('')"
+            src = pieces[0]
+            for nxt in pieces[1:]:
+                src = f"_VSA.string_concat({src}, {nxt})"
+            return src
+        if isinstance(expr, ast.UnsafeCastExpr):
+            # types.md § "Casting — relabeling, not transformation":
+            # unsafeCast<T>(x) is ALWAYS the pure relabel — the value
+            # crosses unchanged and only the static type changes. It
+            # never axis-moves; `(fuzzy) n` converts, `unsafeCast<fuzzy>(n)`
+            # reinterprets (truth reading of a real-axis value is 0).
+            return self._translate_expr(expr.expr)
+        if isinstance(expr, ast.UnsafeOverrideExpr):
+            # `unsafeOverride(v)` suppresses a type-check at the call
+            # site and does not change the value — the runtime lowering
+            # is the pure passthrough (same class as unsafeCast, minus
+            # the type argument). Round-19 audit: was the last special
+            # call form with no codegen.
+            return self._translate_expr(expr.expr)
+        if isinstance(expr, ast.CastExpr):
+            return self._translate_cast(expr)
         raise CodegenNotSupported(
             expr, f"unsupported expression: {type(expr).__name__}"
         )
 
+    # ---- cast lowering (types.md § "Casting — relabeling, not
+    # transformation") -------------------------------------------------
+    #
+    # The default cast is a NO-OP relabel: every Sutra value is already a
+    # d-dim substrate vector (or a 0-d number at the entry boundary), and
+    # downstream ops project the axes they need, so relabeling is free.
+    # The ONE genuine axis-move pair is numeric↔truth: a number carries
+    # its value on AXIS_REAL, a fuzzy/bool/trit on AXIS_TRUTH — a pure
+    # relabel would strand the value on the wrong axis and every read
+    # would see 0 (neutral). Text is walled off: number→string needs the
+    # unbuilt substrate formatter; string→vector is the spec's "embedding
+    # cast" whose real implementation is `embed()` at the entry boundary.
+
+    #: Sutra type name → cast family. Types not in the map (user classes,
+    #: generics) relabel as "geometric" — the spec's free no-op default.
+    _CAST_FAMILY = {
+        "int": "number", "number": "number",
+        "fuzzy": "truth", "bool": "truth", "trit": "truth",
+        "complex": "geometric", "vector": "geometric", "role": "geometric",
+        "matrix": "geometric",
+        "string": "text", "String": "text",
+        "char": "text", "Character": "text",
+    }
+
+    #: Whether this backend's runtime carries the numeric↔truth cast
+    #: helpers (cast_number_to_truth / cast_truth_to_number / _cnum).
+    #: The deprecated numpy backend does not; it keeps rejecting casts.
+    supports_cast_lowering = False
+
+    #: Whether this backend's runtime carries the substrate String ops
+    #: (make_string / string_concat). Gates InterpolatedString lowering;
+    #: the deprecated numpy backend has no String runtime.
+    supports_string_runtime = False
+
+    def _infer_cast_operand_type(self, expr: ast.Expr) -> str | None:
+        """Conservative static type of a cast operand: literals, typed
+        locals/params (via _var_type), nested casts, parenthesized
+        exprs. None when unknown — the caller decides whether the
+        target makes the relabel/axis-move distinction load-bearing."""
+        from .symbol_table import _LITERAL_TYPES
+        kind = type(expr).__name__
+        if kind in _LITERAL_TYPES:
+            return _LITERAL_TYPES[kind]
+        if isinstance(expr, ast.Identifier):
+            return self._var_type.get(expr.name)
+        if isinstance(expr, (ast.CastExpr, ast.UnsafeCastExpr)):
+            return expr.target_type.name if expr.target_type else None
+        if type(expr).__name__ == "Parenthesized" and hasattr(expr, "inner"):
+            return self._infer_cast_operand_type(expr.inner)
+        if isinstance(expr, ast.BinaryOp):
+            if expr.op in ("==", "!=", "<", ">", "<=", ">=", "&&", "||"):
+                return "bool"
+            if expr.op in ("+", "-", "*", "/", "%"):
+                lt = self._infer_cast_operand_type(expr.left)
+                rt = self._infer_cast_operand_type(expr.right)
+                if (self._CAST_FAMILY.get(lt) == "number"
+                        and self._CAST_FAMILY.get(rt) == "number"):
+                    return "number"
+        return None
+
+    def _translate_cast(self, expr: ast.CastExpr) -> str:
+        if not self.supports_cast_lowering:
+            raise CodegenNotSupported(
+                expr,
+                "`(Type) expr` casts are not supported by this backend; "
+                "use the PyTorch backend (codegen_pytorch)."
+            )
+        dst = expr.target_type.name if expr.target_type else None
+        dst_family = self._CAST_FAMILY.get(dst, "geometric")
+        src = self._infer_cast_operand_type(expr.expr)
+        src_family = self._CAST_FAMILY.get(src, "geometric") if src else None
+
+        # --- text walls -------------------------------------------------
+        if dst_family == "text" and src_family != "text":
+            if src == "int":
+                # strings.md § Integer formatting: `(string) n` on an
+                # int is the integer formatter — the one number→text
+                # cast with a real substrate implementation.
+                return (f"_VSA.int_to_string("
+                        f"{self._translate_expr(expr.expr)})")
+            raise CodegenNotSupported(
+                expr,
+                f"cannot cast to `{dst}`: only `int` values format "
+                "(int_to_string — integer-shaped; fractional rendering is "
+                "not built). For a literal, use `make_string(\"...\")`; "
+                "join strings with `string_concat`."
+            )
+        if src_family == "text" and dst_family != "text":
+            if dst_family == "geometric":
+                raise CodegenNotSupported(
+                    expr,
+                    f"cannot cast a string to `{dst}`: that is the embedding "
+                    "cast, and its implementation is `embed(...)` at the "
+                    "program boundary — a String vector encodes codepoints, "
+                    "not semantics."
+                )
+            raise CodegenNotSupported(
+                expr,
+                f"cannot cast a string to `{dst}`: a String vector encodes "
+                "packed codepoints, so its numeric axes are not a number. "
+                "Use the string operations (string_length, char_at, ...) "
+                "instead."
+            )
+
+        inner = self._translate_expr(expr.expr)
+
+        # --- same family / text→text: the free relabel --------------------
+        if src_family == dst_family:
+            return inner
+
+        # --- the one genuine axis-move pair -------------------------------
+        if src_family == "number" and dst_family == "truth":
+            return f"_VSA.cast_number_to_truth({inner})"
+        if src_family == "truth" and dst_family == "number":
+            return f"_VSA.cast_truth_to_number({inner})"
+
+        # --- unknown source: only reject when the move/relabel choice
+        # --- is load-bearing (truth/number targets read a single axis) ----
+        if src_family is None and dst_family in ("truth", "number"):
+            raise CodegenNotSupported(
+                expr,
+                f"cannot cast to `{dst}` here: the operand's static type "
+                "can't be inferred, and truth/number casts need it to pick "
+                "between relabel and axis-move. Assign the operand to a "
+                "typed variable first."
+            )
+
+        # --- every remaining pair relabels; _cnum canonicalizes a 0-d
+        # --- number at the entry boundary and passes vectors through ------
+        if src_family == "number" or src is None:
+            return f"_VSA._cnum({inner})"
+        return inner
+
     def _embed_expr_src(self, expr: ast.EmbedExpr) -> str:
         """Override point for per-backend `embed(<expr>)` lowering.