sutra-dev 0.9.1__tar.gz → 0.9.3__tar.gz

{sutra_dev-0.9.1/sutra_dev.egg-info → sutra_dev-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sutra-dev
-Version: 0.9.1
+Version: 0.9.3
 Summary: Compiler for the Sutra programming language — tensor ops on frozen-LLM embedding vectors.
 Author: Emma Leonhart
 License-Expression: AGPL-3.0-only
@@ -23,6 +23,9 @@ License-File: LICENSE
 Requires-Dist: numpy>=1.26
 Provides-Extra: runtime
 Requires-Dist: torch>=2.1; extra == "runtime"
+Provides-Extra: embed
+Requires-Dist: sentence-transformers>=3.0; extra == "embed"
+Requires-Dist: einops>=0.7; extra == "embed"
 Provides-Extra: ts
 Requires-Dist: sutra-from-ts>=0.1.0; extra == "ts"
 Provides-Extra: fv

{sutra_dev-0.9.1 → sutra_dev-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sutra-dev"
-version = "0.9.1"
+version = "0.9.3"
 description = "Compiler for the Sutra programming language — tensor ops on frozen-LLM embedding vectors."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -44,6 +44,16 @@ dependencies = [
 runtime = [
   "torch>=2.1",
 ]
+# In-process embedding backend. sentence-transformers loads the SAME frozen
+# nomic-embed-text model HuggingFace serves, so semantic Sutra programs run with
+# NO Ollama daemon — this is the default backend (sutra_compiler/embedding.py).
+# einops is needed by nomic-bert's custom modeling code. Pure make_real / matrix
+# / arithmetic programs embed nothing and need none of this.
+# Install with: pip install sutra-dev[runtime,embed]
+embed = [
+  "sentence-transformers>=3.0",
+  "einops>=0.7",
+]
 # TypeScript→Sutra transpiler. `pip install sutra-dev[ts]` pulls in
 # the working ts2su CLI from the sister package, so the recommended
 # way to get a complete Sutra dev environment for browser-layer work

{sutra_dev-0.9.1 → sutra_dev-0.9.3}/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.1"
+__version__ = "0.9.3"
 
 from .diagnostics import Diagnostic, DiagnosticLevel, DiagnosticBag
 from .lexer import Lexer, Token, TokenKind

{sutra_dev-0.9.1 → sutra_dev-0.9.3}/sutra_compiler/__main__.py

@@ -23,6 +23,7 @@ from typing import List
 
 from . import __version__
 from . import ast_nodes as ast
+from .codegen_base import CodegenNotSupported
 from .codegen_pytorch import translate_module as translate_pytorch
 from .diagnostics import Diagnostic, DiagnosticLevel
 from .lexer import Lexer
@@ -292,10 +293,20 @@ def _compile_to_python(path: str, *, runtime_dim: int,
     tabulate_module(module)
     if loop_T is None:
         loop_T = _read_atman_loop_T(path) or 50
-    return translate_pytorch(
-        module, runtime_dim=runtime_dim, runtime_seed=runtime_seed,
-        loop_max_iterations=loop_T,
-    )
+    try:
+        return translate_pytorch(
+            module, runtime_dim=runtime_dim, runtime_seed=runtime_seed,
+            loop_max_iterations=loop_T,
+        )
+    except CodegenNotSupported as exc:
+        # The backend can't lower this construct (an unsupported builtin like
+        # `snap`, an unsupported node, etc.). `exc` already formats as
+        # `line:col: codegen: <message>`; prepend the file path so it reads
+        # like every other Sutra diagnostic (`file:line:col: …`) instead of
+        # surfacing to the user as an uncaught Python traceback. Single choke
+        # point: --run / --emit / runtime-viz all route through here.
+        print(f"{path}:{exc}", file=sys.stderr)
+        return None
 
 
 def _run_execute(path: str, *, runtime_dim: int, runtime_seed: int,
@@ -314,26 +325,48 @@ 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
 
 
 def _decode_terminal_result(mod, result):
-    """Terminal/output boundary: decode a number-vector `main()` result to its
-    real-axis value for display. The language itself has no scalar-readout
-    accessor (`real()` was removed — substrate purity); the host reading the
-    FINAL result for display is the one external terminal boundary, the same as
-    printing a returned value in any runtime. A number-vector is a 1-D tensor of
-    length `_VSA.dim`; anything else (string, int, already-decoded) prints as-is."""
+    """Terminal/output boundary: decode a `main()` result to a host value for
+    display. The language has no scalar-readout accessor (`real()` was removed —
+    substrate purity); the host reading the FINAL result for display is the one
+    external terminal boundary, the same as printing a returned value in any
+    runtime.
+
+    Both a String and a number-vector are 1-D tensors of length `_VSA.dim`; the
+    AXIS_STRING_FLAG tells them apart. The string check MUST come first: a String
+    stores its codepoints on synthetic axes and the real axis coincides with the
+    first codepoint, so a String read as a number prints that char's codepoint
+    (e.g. `return "hello world"` would print 104.0 = 'h'). A String decodes to its
+    Python text via the sanctioned `string_to_python` terminal decode; a
+    number-vector decodes to its real-axis value; anything else prints as-is."""
     try:
         import torch as _t
         vsa = getattr(mod, "_VSA", None)
         if (vsa is not None and isinstance(result, _t.Tensor)
                 and result.ndim == 1 and result.shape[0] == vsa.dim):
+            if vsa.is_string(result):
+                return vsa.string_to_python(result)
             return float(result[vsa.semantic_dim + vsa.AXIS_REAL])
     except Exception:
         pass
@@ -367,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
@@ -397,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')
@@ -483,9 +516,30 @@ def _emit_thrml(path: str) -> int:
 
 
 def main(argv: List[str] | None = None) -> int:
+    # `sutrac repl` (or `--repl`) launches the interactive evaluator. Intercepted
+    # before argparse because the validator requires a `paths` positional and the
+    # REPL takes no file.
+    _args = argv if argv is not None else sys.argv[1:]
+    if _args and _args[0] in ("repl", "--repl"):
+        from .repl import main_repl
+        return main_repl()
+
     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",
@@ -513,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."
         ),
@@ -536,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.1 → sutra_dev-0.9.3}/sutra_compiler/codegen.py

@@ -89,7 +89,7 @@ class Codegen(BaseCodegen):
         self._semantic_dim = runtime_dim
         self._synthetic_dim = (synthetic_dim if synthetic_dim is not None
                                else self.DEFAULT_SYNTHETIC_DIM)
-        # List of strings that appear in `basis_vector("...")` calls,
+        # List of strings that appear in `embed("...")` calls,
         # populated by translate_module() between simplify and codegen.
         # The codegen emits a batched Ollama pre-fetch at module init
         # to replace N sequential HTTP round-trips with one call.
@@ -119,6 +119,18 @@ class Codegen(BaseCodegen):
         "array_filter",
     })
 
+    # Steering hints attached to the CodegenNotSupported error for
+    # spec'd-but-unimplemented builtins. `snap` is the cleanup primitive
+    # backed by an attractor circuit the substrate doesn't have yet;
+    # argmax_cosine against an explicit codebook is the implemented form
+    # the demos use today (tutorial 03). Keeps the rejection message from
+    # being a dead end.
+    _UNSUPPORTED_BUILTIN_HINTS = {
+        "snap": "use `argmax_cosine(query, [a, b, c])` to clean a vector up "
+                "against an explicit codebook; `snap` (attractor-circuit "
+                "cleanup) is a future substrate primitive",
+    }
+
     def _char_literal_src(self, expr: ast.CharLiteral) -> str:
         """Lower `'a'` to a runtime make_char call with the code point."""
         return f"_VSA.make_char({int(expr.value)})"
@@ -444,10 +456,12 @@ class Codegen(BaseCodegen):
         callee = call.callee
         if isinstance(callee, ast.Identifier):
             if callee.name in self._UNSUPPORTED_BUILTINS:
+                hint = self._UNSUPPORTED_BUILTIN_HINTS.get(callee.name)
+                detail = f" — {hint}" if hint else ""
                 raise CodegenNotSupported(
                     call,
-                    f"`{callee.name}` is not supported on the pure-numpy "
-                    f"substrate (no cleanup circuit at runtime)",
+                    f"`{callee.name}` is not yet supported on the substrate "
+                    f"(no runtime lowering on this backend){detail}",
                 )
         if (isinstance(callee, ast.MemberAccess)
                 and callee.member in self._REMOVED_SCALAR_ACCESSORS):
@@ -512,7 +526,7 @@ class Codegen(BaseCodegen):
         self._emit("# repeated bind/unbind with the same role O(d^2) lookup + matmul.")
         self._emit("self._rot_cache = {}")
         self._emit("# On-disk embedding cache. Second-and-later runs load every")
-        self._emit("# previously-seen basis_vector(...) string from disk instead of")
+        self._emit("# previously-seen embed(...) string from disk instead of")
         self._emit("# hitting Ollama. Cache is keyed by (model, dim) so changing")
         self._emit("# either invalidates cleanly (different cache file).")
         self._emit("import os as _os")
@@ -524,9 +538,13 @@ class Codegen(BaseCodegen):
         self._emit("_os.makedirs(self._cache_dir, exist_ok=True)")
         self._emit("# Sanitize model name for use as filename.")
         self._emit("_safe_model = llm_model.replace('/', '_').replace(':', '_')")
+        self._emit("# Backend-aware: in-process (transformers) and ollama realize the")
+        self._emit("# same model with slightly different geometry, so they must not")
+        self._emit("# share a cache file or one backend reads the other's vectors.")
+        self._emit("_emb_backend = _os.environ.get('SUTRA_EMBED_BACKEND', 'auto').strip().lower() or 'auto'")
         self._emit("self._cache_path = _os.path.join(")
         self._indent += 1
-        self._emit("self._cache_dir, f'{_safe_model}-d{self.dim}.npz')")
+        self._emit("self._cache_dir, f'{_safe_model}-d{self.dim}-{_emb_backend}.npz')")
         self._indent -= 1
         self._emit("self._load_disk_cache()")
         self._emit("# Transcendental lookup tables — substrate-pure interpolation per")
@@ -641,9 +659,9 @@ class Codegen(BaseCodegen):
         self._emit('starts at zero."""')
         self._emit("if name not in self._codebook:")
         self._indent += 1
-        self._emit("import ollama")
-        self._emit("r = ollama.embed(model=self.llm_model, input=name)")
-        self._emit("v = _np.array(r['embeddings'][0], dtype=_np.float64)")
+        self._emit("from sutra_compiler.embedding import embed_texts as _embed_texts")
+        self._emit("r = _embed_texts([name], self.llm_model)")
+        self._emit("v = _np.array(r[0], dtype=_np.float64)")
         self._emit("# Mean-center. Raw LLM embeddings cluster in a cone (all-")
         self._emit("# positive-ish); centering keeps rotation/bind algebra")
         self._emit("# well-behaved.")
@@ -685,11 +703,11 @@ class Codegen(BaseCodegen):
         self._indent += 1
         self._emit("return")
         self._indent -= 1
-        self._emit("import ollama")
-        self._emit("r = ollama.embed(model=self.llm_model, input=missing)")
+        self._emit("from sutra_compiler.embedding import embed_texts as _embed_texts")
+        self._emit("r = _embed_texts(missing, self.llm_model)")
         self._emit("for i, name in enumerate(missing):")
         self._indent += 1
-        self._emit("v = _np.array(r['embeddings'][i], dtype=_np.float64)")
+        self._emit("v = _np.array(r[i], dtype=_np.float64)")
         self._emit("v = v - _np.mean(v)")
         self._emit("n = _np.linalg.norm(v)")
         self._emit("if n > 0: v = v / n")
@@ -1682,7 +1700,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)")
@@ -2146,7 +2164,7 @@ class Codegen(BaseCodegen):
             f"seed={self.runtime_seed}, "
             f"llm_model={self._llm_model!r})"
         )
-        # Batched pre-fetch of every basis_vector("...") string argument
+        # Batched pre-fetch of every embed("...") string argument
         # the program uses. One Ollama round-trip instead of N sequential
         # ones. Collected by the simplify pass (see translate_module).
         if self._prefetch_strings:
@@ -2233,11 +2251,11 @@ def translate_module(module: ast.Module, **kwargs) -> str:
     Runs the simplification pass over the AST before handing to the
     codegen so identity rewrites (bundle(v) -> v, bundle flattening)
     happen in source-to-source form rather than in the emitted
-    Python. Also collects every `basis_vector("...")` string literal
+    Python. Also collects every `embed("...")` string literal
     so the codegen can emit a batched Ollama pre-fetch at module init
     (N HTTP round-trips collapse into one batched embed call).
     """
-    from .simplify import simplify_module, collect_basis_vector_strings
+    from .simplify import simplify_module, collect_embedded_strings
     from .inliner import inline_stdlib_calls
     from .promise_desugar import desugar_promises
     from .loop_desugar import desugar_implicit_loops
@@ -2263,7 +2281,7 @@ def translate_module(module: ast.Module, **kwargs) -> str:
     # absorption, which can fold parts of the inlined form.
     inline_stdlib_calls(module)
     simplify_module(module)
-    strings = collect_basis_vector_strings(module)
+    strings = collect_embedded_strings(module)
     cg = Codegen(**kwargs)
     cg._prefetch_strings = strings
     cg._axon_keys_bound = bound_keys