MeTTa TS 1.1.0

Author: MesTTo

.gitignore

@@ -11,3 +11,6 @@ packages/*/docs/
 website/.vitepress/dist/
 website/.vitepress/cache/
 packages/node/bench/lib
+
+# Local hyperon venv for the @metta-ts/py differential oracle (HYPERON_LIVE=1)
+.venv-hyperon/

README.md

@@ -21,6 +21,7 @@ Other packages, add as needed:
 npm install @metta-ts/hyperon     # a Python-hyperon-style class API
 npm install @metta-ts/node        # CLI + file import! + a parallel matcher
 npm install @metta-ts/browser     # web entry + in-memory virtual file system
+npm install @metta-ts/py          # call Python (py-call / py-atom) via pythonia
 ```
 
 For the command-line runner, install `@metta-ts/node` globally (or use `npx`):
@@ -201,14 +202,15 @@ node packages/node/dist/cli.js examples/factorial.metta
 
 ## Packages
 
-| Package                                       | What it is                                                                                    |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| [`@metta-ts/core`](packages/core)             | The interpreter, parser, type system, and standard library. Zero platform dependencies.       |
-| [`@metta-ts/hyperon`](packages/hyperon)       | A TypeScript class API over the core, modeled on Python's `hyperon`.                          |
-| [`@metta-ts/edsl`](packages/edsl)             | An ergonomic, typed eDSL: term builders, special-form combinators, and a tagged template.     |
-| [`@metta-ts/node`](packages/node)             | The `metta-ts` CLI, file `import!`, and a `SharedArrayBuffer` worker-thread parallel matcher. |
-| [`@metta-ts/browser`](packages/browser)       | Browser entry point with an in-memory virtual file system for `import!`.                      |
-| [`@metta-ts/das-client`](packages/das-client) | Optional client to SingularityNET's Distributed AtomSpace via a Connect gateway.              |
+| Package                                       | What it is                                                                                                 |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| [`@metta-ts/core`](packages/core)             | The interpreter, parser, type system, and standard library. Zero platform dependencies.                    |
+| [`@metta-ts/hyperon`](packages/hyperon)       | A TypeScript class API over the core, modeled on Python's `hyperon`.                                       |
+| [`@metta-ts/edsl`](packages/edsl)             | An ergonomic, typed eDSL: term builders, special-form combinators, and a tagged template.                  |
+| [`@metta-ts/node`](packages/node)             | The `metta-ts` CLI, file `import!`, and a `SharedArrayBuffer` worker-thread parallel matcher.              |
+| [`@metta-ts/browser`](packages/browser)       | Browser entry point with an in-memory virtual file system for `import!`.                                   |
+| [`@metta-ts/py`](packages/py)                 | Optional Python interop: PeTTa's `py-call` and Hyperon's `py-atom` over a caller-supplied pythonia bridge. |
+| [`@metta-ts/das-client`](packages/das-client) | Optional client to SingularityNET's Distributed AtomSpace via a Connect gateway.                           |
 
 ## Performance
 

RELEASE_NOTES.md

@@ -1,29 +1,40 @@
-# MeTTa TS 1.0.9
+# MeTTa TS 1.1.0
 
 A pure-TypeScript implementation of [MeTTa](https://metta-lang.dev) (Meta Type Talk), the OpenCog Hyperon language. It runs anywhere TypeScript runs: the browser, Node, Deno, Bun, and edge or serverless functions. No native addons, no WASM, no Rust.
 
 ## Tested on Linux
 
 This release is tested on Linux (Node 20, the CI matrix): lint, format, typecheck, the full test suite, and the build all run there. Because the engine is pure TypeScript with no native addon and no WASM, it is meant to be cross-platform and should run unchanged on any JavaScript runtime. Other operating systems are not yet part of the tested matrix.
 
-## What's new: a recovering CST for editors and language servers
+## What's new: Python interop
 
-1.0.8 added a span-tracking parse for the static analyzer. This release turns it into a concrete syntax tree an editor can build on. `parseCst` never throws, so a language server can keep offering features while a document is mid-edit: an unclosed `(` closes at end of input, an unexpected `)` and an unterminated string each become a diagnostic instead of an exception, and deep nesting is bounded without a recursive overflow. The tree also carries what an editor needs and the analyzer did not: the comments, a syntactic kind per node, the paren spans, and the span of a top-level `!` query.
+This release adds `@metta-ts/py`, an optional package that lets a MeTTa program call into Python. It carries two surfaces over one bridge: PeTTa's `py-call` and Hyperon's `py-atom` family.
 
-Leaf atoms still come from the interpreter's own reader primitives, so on valid input the CST is byte-identical to `parseAll`. A 1000-run differential checks the atoms and bang flags against the plain reader, and a 2000-run fuzz checks that the parser never throws on arbitrary input. The diagnostics are shaped as Language Server Protocol `Diagnostic`s with a range, a severity, and a stable code, so an editor consumes them directly. The static analyzer and `metta-ts --check` from 1.0.8 are unchanged and still read the interpreter's own signature table:
+`py-call` dispatches on the head of its argument, the way PeTTa does. A bare name is a builtin, a dotted name is a module function, and a leading-dot name is a method on a live object. `py-eval` runs a Python expression string and `py-str` folds a MeTTa list into a Python string:
 
+```metta
+!(py-call (math.gcd 12 18))   ; 6
+!(py-eval "2 ** 10")          ; 1024
 ```
-error[arity-mismatch]: prog.metta:1:2
-  |
-1 | !(car-atom 1 2)
-  |  ^^^^^^^^^^^^^^ car-atom expects 1 argument, got 2
+
+The `py-atom` family is Hyperon's surface over the same bridge. `py-atom` resolves a dotted path into an atom you can apply or read as a value, and `py-dot`, `py-list`, `py-tuple`, `py-dict`, and `py-chain` round it out:
+
+```metta
+!((py-atom operator.add) 40 2)   ; 42
+!(py-atom math.pi)               ; 3.141592653589793
 ```
 
-None of this touches the evaluator. `parseCst` is off the `runFile` hot path; the only change to shared code is that `readStringAt` now reports whether a string was terminated instead of throwing, and the plain parser re-throws exactly as before. The 270-assertion Hyperon oracle and every byte-identical experimental suite still pass, and a parse/eval microbench is within noise of 1.0.8.
+Python runs in a separate CPython process and MeTTa talks to it over IPC, so the interpreter stays pure TypeScript and as fast as before. The package ships no Python dependency of its own: you pass in a bridge, the way `MeTTaGrapher` takes a GIF encoder. The reference bridge wraps [pythonia](https://www.npmjs.com/package/pythonia). Because a call crosses a process boundary the ops are asynchronous, so you run with `runAsync`, or from the command line with `metta-ts --py program.metta`.
+
+Value conversions follow PeTTa and its `janus` bridge: numbers both ways, a Python string to a Symbol, `True`/`False`/`None` to `(@ true)`/`(@ false)`/`(@ none)`, a list to an expression, and anything else to a live handle. A raised Python error becomes an `(Error <expr> <message>)` atom carrying the real Python message, and evaluation continues, where PeTTa aborts. Enabling this grants the program the host's Python, so it is opt-in and meant for trusted source only.
+
+Two differential oracles pin the behaviour. A byte-parity suite runs the same corpus through a live PeTTa checkout and through this package, comparing the result lines exactly. A second suite runs the `py-atom` surface through pip `hyperon`, comparing results on the numeric surface where the two marshallings coincide. Both are gated behind environment flags so the default suite needs no Python.
+
+The one change to the engine is that a grounded atom's executor may now return a `Promise`, which is what lets an applied `py-atom` run asynchronously. Nothing returned a Promise from that path before, so the synchronous behaviour is unchanged: the 270-assertion Hyperon oracle is byte-identical and the corpus microbench is within noise of 1.0.9.
 
 ## Corpus benchmark
 
-The engine is unchanged in this release, so the PeTTa-corpus benchmark (107 shared programs, 97 both engines pass, median 2.01x, geomean 2.06x) is identical to 1.0.7. See [`packages/node/bench/RESULTS-corpus.md`](packages/node/bench/RESULTS-corpus.md) for the full per-program table.
+The engine is unchanged for pure-MeTTa programs, so the PeTTa-corpus benchmark (107 shared programs, 97 both engines pass, median 2.01x, geomean 2.06x) is identical to 1.0.9. See [`packages/node/bench/RESULTS-corpus.md`](packages/node/bench/RESULTS-corpus.md) for the full per-program table.
 
 ## Major performance gains (since 1.0.0)
 
@@ -36,16 +47,17 @@ The speed comes from general engine work:
 - automatic tabling of pure functions, including ones defined at runtime, and moded (variant) tabling for non-ground pure calls;
 - a native-code compiler for the pure deterministic int/bool/tuple subset, with tail-recursion compiled to loops and higher-order specialisation;
 - worker-thread parallelism: `(once (hyperpose ...))` races branches across CPU cores on Node, and a `SharedArrayBuffer` flat matcher scans large knowledge bases in parallel;
-- the compiled clause-skeleton and JavaScript-codegen search for match-free nondeterministic groups, added in 1.0.7.
+- the compiled clause-skeleton and JavaScript-codegen search for match-free nondeterministic groups.
 
 Every optimisation is verified byte-identical against the 270-assertion Hyperon oracle.
 
 ## What is in this release
 
-- `@metta-ts/core` is the interpreter, parser, type system, pattern matching, and standard library, as a single ESM bundle. It now also carries the static analyzer and its diagnostic model, described above. It passes all 270 assertions of Hyperon's oracle corpus (the full dependent-type tier, spaces and mutable state, nondeterminism, grounded operations, and documentation), cross-checked against [LeaTTa](https://github.com/MesTTo/LeaTTa), the machine-checked (Lean 4) MeTTa semantics pinned to the same commit.
+- `@metta-ts/core` is the interpreter, parser, type system, pattern matching, standard library, and static analyzer, as a single ESM bundle. It passes all 270 assertions of Hyperon's oracle corpus, cross-checked against [LeaTTa](https://github.com/MesTTo/LeaTTa), the machine-checked (Lean 4) MeTTa semantics pinned to the same commit.
 - `@metta-ts/hyperon` is a TypeScript class API modeled on Python's `hyperon`, with a JavaScript interop layer (`js-atom`, `js-dot`, `js-list`, `js-dict`) that calls into the host runtime directly.
 - `@metta-ts/edsl` is a typed eDSL with term builders, special-form combinators, and a tagged-template surface.
-- `@metta-ts/node` has the `metta-ts` CLI, now with `--check` for static analysis, plus file `import!` and the worker-thread parallel matcher.
+- `@metta-ts/py` is the new Python interop package, described above: `py-call` and the `py-atom` family over a caller-supplied pythonia bridge, opt-in and asynchronous.
+- `@metta-ts/node` has the `metta-ts` CLI, with `--check` for static analysis and `--py` for Python interop, plus file `import!` and the worker-thread parallel matcher.
 - `@metta-ts/browser` is a browser entry with an in-memory virtual file system for `import!`.
 - `@metta-ts/grapher` renders a MeTTa reduction as a node graph or a nested-block view, as static SVGs or an animated GIF, with a data-driven stylesheet for node size and colour.
 - `@metta-ts/das-client` and `@metta-ts/das-gateway` are an optional client to SingularityNET's Distributed AtomSpace, run end to end against a live cluster, with atom handles matching the AtomDB byte for byte.
@@ -55,19 +67,19 @@ Every optimisation is verified byte-identical against the 270-assertion Hyperon
 ```bash
 npm install @metta-ts/core        # the interpreter (works in any JS runtime)
 npm install -g @metta-ts/node     # the metta-ts CLI
+npm install @metta-ts/py pythonia # optional: call Python from MeTTa
 ```
 
-Check a file without running it:
+Run a Python-using program from the command line:
 
 ```bash
-metta-ts --check program.metta                       # arity errors, rustc-style
-metta-ts --check --undefined-symbols program.metta   # also "did you mean" on unknown heads
-metta-ts --check --json program.metta                # diagnostics as an LSP Diagnostic[]
+metta-ts --py program.metta       # needs pythonia installed and python3 on PATH
 ```
 
 ## Provenance
 
 - Semantics: [hyperon-experimental](https://github.com/trueagi-io/hyperon-experimental), pinned to commit `3f76dc4`.
+- Python interop surface: PeTTa's `py-call` and Hyperon's [`py-atom`](https://trueagi-io.github.io/hyperon-experimental/reference/atoms/) family, over [pythonia](https://www.npmjs.com/package/pythonia).
 - Verified spec and differential oracle: [LeaTTa](https://github.com/MesTTo/LeaTTa) (Lean 4).
 - Formal models: [Alloy](https://alloytools.org) specs in [`spec/`](spec/) for the matcher's deep loop rejection and the compiled search's occurs check.
 - License: [MIT](LICENSE).

examples/package.json

@@ -15,6 +15,7 @@
     "stdlib": "tsx stdlib.ts",
     "types": "tsx types.ts",
     "js-interop": "tsx js-interop.ts",
+    "python-interop": "tsx python-interop.ts",
     "json-module": "tsx json-module.ts",
     "custom-matching": "tsx custom-matching.ts",
     "concurrency": "tsx concurrency.ts",
@@ -28,7 +29,10 @@
     "@metta-ts/edsl": "workspace:*",
     "@metta-ts/grapher": "workspace:*",
     "@metta-ts/hyperon": "workspace:*",
-    "@metta-ts/node": "workspace:*"
+    "@metta-ts/node": "workspace:*",
+    "@metta-ts/py": "workspace:*",
+    "pythonia": "^1.2.6",
+    "ws": "^7.5.10"
   },
   "devDependencies": {
     "tsx": "^4.19.2",

examples/python-interop.metta

@@ -0,0 +1,20 @@
+; SPDX-FileCopyrightText: 2026 MesTTo
+; SPDX-License-Identifier: MIT
+
+; Python interop from MeTTa source. Run it with the CLI (needs pythonia installed and python3 on PATH):
+;   metta-ts --py examples/python-interop.metta
+
+; py-call dispatches on the head: a builtin, a module function, or a .method on a live object.
+!(py-call (abs -5))                       ; [5]
+!(py-call (math.gcd 12 18))               ; [6]
+
+; py-eval runs a Python expression; a returned list comes back as an expression.
+!(py-eval "2 ** 10")                      ; [1024]
+!(py-eval "[1, 2.5, 'x', True, None]")    ; [(1 2.5 x (@ true) (@ none))]
+
+; The py-atom family is Hyperon's surface over the same bridge.
+!((py-atom operator.add) 40 2)            ; [42]
+!(py-atom math.pi)                        ; [3.141592653589793]
+
+; A Python error becomes an (Error ...) atom and the run keeps going, where PeTTa would abort.
+!(py-eval "1 / 0")                        ; [(Error ... ZeroDivisionError: division by zero)]

examples/python-interop.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+// Python interop: a MeTTa program calling into CPython through @metta-ts/py. Python runs in a separate
+// process and MeTTa talks to it over IPC, so the interpreter stays pure TypeScript. The ops are async
+// (a call crosses a process boundary), so you run with `runAsync` and pass in a bridge yourself.
+//
+// Run it (after `pnpm build`, and with python3 on your PATH): npx tsx examples/python-interop.ts
+import { MeTTa } from "@metta-ts/hyperon";
+import { registerPyInterop, pythoniaBridge } from "@metta-ts/py";
+import { python } from "pythonia";
+
+const m = new MeTTa();
+const bridge = pythoniaBridge(python);
+registerPyInterop(m, bridge);
+
+const run1 = async (q: string): Promise<string[]> =>
+  (await m.runAsync(q))[0]!.map((a) => a.toString());
+
+// py-call dispatches on the head: a builtin, a module function, or a `.method` on a live object.
+console.log("abs(-5):", await run1(`!(py-call (abs -5))`)); // [ '5' ]
+console.log("math.gcd(12, 18):", await run1(`!(py-call (math.gcd 12 18))`)); // [ '6' ]
+
+// py-eval evaluates a Python expression string; a returned list converts to a MeTTa expression.
+console.log("2 ** 10:", await run1(`!(py-eval "2 ** 10")`)); // [ '1024' ]
+console.log("a list:", await run1(`!(py-eval "[1, 2.5, 'x', True, None]")`)); // [ '(1 2.5 x (@ true) (@ none))' ]
+
+// True/False/None come back as (@ true)/(@ false)/(@ none), kept distinct from MeTTa symbols.
+console.log("bool(1):", await run1(`!(py-call (bool 1))`)); // [ '(@ true)' ]
+
+// A non-primitive result stays a live handle you keep passing around.
+console.log("Fraction 1/3:", await run1(`!(py-call (str (py-call (fractions.Fraction 1 3))))`)); // [ '1/3' ]
+
+// The py-atom family is Hyperon's surface over the same bridge: resolve a path into an atom you apply.
+console.log("operator.add:", await run1(`!((py-atom operator.add) 40 2)`)); // [ '42' ]
+console.log("math.pi:", await run1(`!(py-atom math.pi)`)); // [ '3.141592653589793' ]
+
+// Errors do not crash the run. A raised Python exception (here ZeroDivisionError) and an unresolvable
+// path both come back as an (Error ...) atom the program can inspect, and evaluation continues. This is
+// a deliberate divergence from PeTTa, which aborts on a Python error.
+console.log("1 / 0:", await run1(`!(py-eval "1 / 0")`)); // [ '(Error ... ZeroDivisionError: division by zero)' ]
+console.log("bad path:", await run1(`!(py-atom nosuch.module)`)); // [ '(Error ... AttributeError: ... no attribute ...)' ]
+
+await bridge.dispose(); // stops the Python subprocess so the process can exit

packages/browser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/browser",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/core",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",