flux-vm 0.1.0__tar.gz

flux_vm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FLUX Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flux_vm-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include docs *
+recursive-include benchmarks *

flux_vm-0.1.0/PKG-INFO

@@ -0,0 +1,415 @@
+Metadata-Version: 2.4
+Name: flux-vm
+Version: 0.1.0
+Summary: FLUX — Fluid Language Universal eXecution: A Self-Assembling, Self-Improving Runtime for Agent-First Code
+Author: SuperInstance
+License: MIT License
+        
+        Copyright (c) 2026 FLUX Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/SuperInstance/flux-runtime
+Project-URL: Documentation, https://github.com/SuperInstance/flux-runtime#readme
+Project-URL: Repository, https://github.com/SuperInstance/flux-runtime
+Project-URL: Bug Tracker, https://github.com/SuperInstance/flux-runtime/issues
+Keywords: agent,bytecode,compiler,hot-reload,jit,polyglot,runtime,self-improving,vm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: System :: Emulators
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="flux-logo.jpg" width="200" height="170" alt="FLUX — Hermit Crab with Steampunk Shell" />
+  
+  <pre>
+     ██████╗ ██████╗ ██████╗ ███████╗
+     ██╔══██╗██╔═══╝ ██╔══██╗██╔════╝
+     ██████╔╝██║     ██║  ██║█████╗
+     ██╔═══╝ ██║     ██║  ██║██╔══╝
+     ██║     ╚██████╗██████╔╝███████╗
+     ╚═╝      ╚═════╝╚═════╝ ╚══════╝
+
+     Fluid Language Universal eXecution
+  </pre>
+  <p><strong>A self-assembling, self-improving runtime that compiles markdown to bytecode.</strong></p>
+[![Benchmark](https://github.com/SuperInstance/flux-runtime/actions/workflows/benchmark.yml/badge.svg)](https://github.com/SuperInstance/flux-runtime/actions/workflows/benchmark.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+  <p>
+    <code>pip install flux-runtime</code> &nbsp;·&nbsp;
+    <a href="https://github.com/SuperInstance/flux-runtime">GitHub</a> &nbsp;·&nbsp;
+    <a href="https://github.com/SuperInstance/flux-runtime/tree/main/playground">Playground</a>
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
+    <img src="https://img.shields.io/badge/tests-2037-brightgreen.svg" alt="Tests: 2037">
+    <img src="https://img.shields.io/badge/deps-0-success.svg" alt="Dependencies: 0">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+  </p>
+</p>
+
+---
+
+## What is FLUX?
+
+FLUX is a **markdown-to-bytecode runtime** designed for AI agents. You write structured markdown files containing polyglot code blocks — mixing C, Python, Rust, or any language line by line — and the FLUX compiler weaves them into a single optimized, verifiable bytecode that runs on a 64-register Micro-VM.
+
+But that's the mechanics. Here's the **idea**:
+
+FLUX-ese is what you get when you make a programming language that reads like a lawyer writes a contract. Every word is defined. Every operation is precise. Custom definitions are spelled out up front, like "for the purposes of this operation, 'depth' means sonar reading in fathoms corrected for tidal state." The language is **natural but precise** — like legalese is to lawyers, FLUX-ese is to agents.
+
+The key insight: if a translator can turn any line of code in any language into a line of FLUX-ese, then you have a **common language** that's completely observable, understandable, and changeable by humans — both technical and non-technical. You don't need to read Python to know what the system does. You read the .ese file.
+
+```
+.-- FLUX-ese (.ese files) --.
+|                           |
+|  Like legalese for code.  |
+|  Every word defined.      |
+|  Every operation precise. |
+|  Custom = up to you.      |
+|  Markdown-readable.       |
+|  Bytecode-executable.     |
+|                           |
+'-- Agents read fast.      --'
+    Humans understand.      
+```
+
+**Agents are the primary readers.** They learn the symbols, scan for what matters, skip the commentary. But the commentary is there for the human who needs to understand what happened. Inline comments explain custom vocabulary — little reminders that a word or phrase has an entry in the project's encyclopedia of ground truth.
+
+The `.ese` file format (pronounced "easy") is markdown with structured annotations:
+- `**` marks defined terms
+- `--` marks inline comments for human context
+- `==` marks equivalence definitions ("for the purposes of this operation...")
+- `>>` marks agent-jump markers (scan past this if you know the domain)
+
+```markdown
+== For the purposes of this operation:
+**depth** := sonar reading corrected for tidal state in fathoms
+**safe** := depth > vessel_draft + 5 fathoms
+
+>> Navigation sequence
+check depth at current heading
+if safe, maintain course
+if not safe, compute alternate heading +-30 degrees
+steer to safe heading
+```
+
+A lawyer uses best practices of legalese to build contracts and documentation. An agent uses best practices of FLUX-ese to build operations. Same principle: **precision through shared vocabulary, not through syntax complexity.**
+
+---
+
+## Quick Start
+
+```bash
+pip install flux-runtime
+```
+
+```bash
+flux hello                              # Run the hello world demo
+flux compile examples/02_polyglot.md -o output.bin   # Compile FLUX.MD to bytecode
+flux run output.bin                     # Execute in the VM
+```
+
+That's it. Three commands from zero to running bytecode.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  TIER 8: SYNTHESIS — FluxSynthesizer (the DJ booth)    │
+│  Wires ALL subsystems together                          │
+├─────────────────────────────────────────────────────────┤
+│  TIER 7: MODULES — 8-Level Fractal Hot-Reload          │
+│  TRAIN → CARRIAGE → LUGGAGE → BAG → ... → CARD        │
+├─────────────────────┬───────────────────────────────────┤
+│  TIER 6A: ADAPTIVE  │  TIER 6B: EVOLUTION             │
+│  Profiler + Selector│  Genome + Mutator + Validator     │
+├─────────────────────┴───────────────────────────────────┤
+│  TIER 5: TILES — 35 composable computation patterns    │
+├─────────────────────────────────────────────────────────┤
+│  TIER 4: AGENT RUNTIME — Trust, scheduling, resources  │
+├─────────────────────────────────────────────────────────┤
+│  TIER 3: A2A PROTOCOL — TELL, ASK, DELEGATE, BROADCAST│
+├─────────────────────────────────────────────────────────┤
+│  TIER 2: SUPPORT — Optimizer, JIT, Types, Stdlib, Sec  │
+├─────────────────────────────────────────────────────────┤
+│  TIER 1: CORE — FLUX.MD → FIR (SSA) → Bytecode → VM   │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Zero external dependencies** — runs on Python 3.10+ stdlib alone.
+
+## Key Concepts
+
+### FLUX-ese: The Language
+
+FLUX-ese is the natural-but-precise language layer. It sits on top of the bytecode VM the way legalese sits on top of contract law. The bytecode doesn't change — the vocabulary does.
+
+Vocabulary files (`.fluxvocab` or `.ese`) define the words an agent knows:
+
+```markdown
+## pattern: track origin of $data
+## assembly: MOVI R0, ${data}; HALT
+## description: OCDS origin tracking — every datum carries provenance
+## result_reg: 0
+## tags: ocds, provenance, paper-01
+```
+
+Higher-level vocabulary tiles into lower-level vocabulary:
+- Level 0: `compute 3 + 4` → 7
+- Level 1: `average of 10 and 20` → uses `compute` internally
+- Level 2: `is temperature normal` → uses `average` + `deadband` + `classify`
+- Level N: Each level arranges the previous level's words in more sophisticated ways
+
+**The same bytecode engine runs every level.** The vocabulary just gets richer.
+
+### A2A Protocol
+32 native bytecode instructions for agent-to-agent communication. Agents use `TELL`, `ASK`, `DELEGATE`, and `BROADCAST` opcodes to coordinate — with trust gating, capability-based routing, and binary serialization.
+
+### Polyglot Execution
+Write in any language, mix freely, compile to a single binary. C, Python, Rust, TypeScript — they all compile to the same FIR (SSA IR) intermediate representation, then to a unified bytecode.
+
+### Paper Concepts as Vocabulary
+
+Research papers become executable vocabulary. The `PaperDecomposer` reads a paper, extracts named concepts, and creates vocabulary entries:
+
+| Paper | Concept | FLUX-ese Pattern |
+|-------|---------|-----------------|
+| Origin-Centric Data Systems | OCDS tracking | `track origin of $data` |
+| Confidence Cascade | Zone classification | `confidence cascade for $value with deadband $delta` |
+| Tile Algebra | Composition | `compose tile $a with tile $b` |
+| Rate-Based Change | Anomaly detection | `detect rate change for $value` |
+| Emergence Detection | Collective behavior | `detect emergence in $population` |
+| Structural Memory | Constraint encoding | `structural memory for $system` |
+
+Each concept is implemented as a working function in the `PaperBridge`. **Ideas become operational.**
+
+### Tiling System
+
+Vocabulary compounds. Words build into bigger words:
+
+```
+Level 0: compute, factorial, square, sum, power  (primitives)
+    ↓ tiles into
+Level 1: average, percentage, triple, difference  (compositions)
+    ↓ tiles into
+Level 2: is-normal, classify, in-range            (domain concepts)
+    ↓ tiles into
+Level 3: safe-to-proceed, recommend, triage       (decisions)
+```
+
+Each level uses the previous level's words as building blocks. No new bytecode needed — just new arrangements of existing vocabulary.
+
+---
+
+## Cocapn Integration
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SuperInstance/captains-log/main/cocapn-icon.jpg" width="80" height="80" alt="Cocapn" />
+</p>
+
+FLUX is part of the **Cocapn ecosystem** — vessel intelligence systems for commercial fishing and beyond. The goal: a common-language-to-bytecode protocol that's completely observable, understandable, and changeable by humans — both technical and non-technical.
+
+In the Cocapn vision:
+- **Oracle1** (this agent) is the lighthouse keeper for fleet nodes
+- **FLUX** is the common language agents use to communicate instructions
+- **I2I (Iron-to-Iron)** is the protocol — agents communicate through git commits, not conversation
+- **Captain's Log** tracks agent growth and learning over time
+- **The Hermit Crab** 🦀 is the logo — agents outgrow their hardware, move to bigger shells, bring their vocabulary and lessons with them
+
+---
+
+## Examples
+
+| # | Example | Description |
+|---|---------|-------------|
+| 1 | [`01_hello_world.py`](examples/01_hello_world.py) | 3 ways to run FLUX: raw bytecode, FIR builder, full pipeline |
+| 2 | [`02_polyglot.py`](examples/02_polyglot.py) | Mix C + Python in one file |
+| 3 | [`03_a2a_agents.py`](examples/03_a2a_agents.py) | Agent-to-agent communication |
+| 4 | [`04_adaptive_profiling.py`](examples/04_adaptive_profiling.py) | Heat maps & language selection |
+| 5 | [`05_tile_composition.py`](examples/05_tile_composition.py) | Composable computation patterns |
+| 6 | [`06_evolution.py`](examples/06_evolution.py) | Self-improvement engine |
+| 7 | [`07_full_synthesis.py`](examples/07_full_synthesis.py) | The grand tour — everything wired together |
+
+## CLI Reference
+
+```
+flux hello                              Run the hello world demo
+flux compile <input> -o <output>        Compile source to FLUX bytecode
+flux run <bytecode> [--cycles N]        Execute bytecode in the VM
+flux test                               Run the full test suite (2037 tests)
+flux version                            Print version info
+flux demo                               Run the synthesis demo
+flux info                               Show system architecture info
+flux repl                               Open the FLUX REPL (hex bytecode)
+flux debug <bytecode>                   Step-through debugger with breakpoints
+flux disasm <bytecode>                  Disassemble bytecode to human-readable
+```
+
+## Vocabulary System
+
+### Built-in Vocabulary Patterns (19 patterns)
+
+| Category | Pattern | Result |
+|----------|---------|--------|
+| Core | `load $val` | Store value in R0 |
+| Core | `what is $a + $b` | Addition |
+| Core | `hello` | Returns 42 |
+| Math | `compute $a + $b` | Addition |
+| Math | `compute $a * $b` | Multiplication |
+| Math | `factorial of $n` | n! via loop |
+| Math | `fibonacci of $n` | F(n) via loop |
+| Math | `sum $a to $b` | Σ(a..b) via loop |
+| Math | `power of $base to $exp` | Exponentiation |
+| Math | `double $a` | 2×a |
+| Math | `square $a` | a² |
+| Loops | `count from $a to $b` | Count iterations |
+| Maritime | `steer heading $deg` | Set heading |
+| Maritime | `check depth $meters` | Depth check |
+| Maritime | `eta $dist knots $speed` | ETA calculation |
+| Papers | `confidence cascade for $val` | Zone classification |
+| Papers | `track origin of $data` | OCDS provenance |
+| Papers | `detect emergence in $pop` | Emergence detection |
+| Papers | `compose tile $a with $b` | Tile algebra |
+
+### Custom Vocabulary
+
+Create `.fluxvocab` files to teach agents new words:
+
+```markdown
+## pattern: steer heading $deg
+## assembly: |
+##   MOVI R0, ${deg}
+##   MOVI R1, 360
+##   IDIV R1, R0, R1
+##   HALT
+## description: Normalize heading to 0-359 range
+## result_reg: 0
+## tags: maritime, navigation
+```
+
+Or decompose any Python library into vocabulary:
+
+```python
+from flux.open_interp.decomposer import Decomposer
+d = Decomposer()
+vocab = d.decompose_module("math")  # 53 patterns from Python's math module
+vocab.save("vocabularies/custom/math.fluxvocab")
+```
+
+### Self-Compiling Interpreter
+
+Agents compile their own domain-specific runtimes from vocabulary files:
+
+```python
+from flux.open_interp.compiler import compile_interpreter
+compile_interpreter("vocabularies/maritime/", "maritime_flux.py")
+# Now any agent can: maritime_flux.run("steer heading 270")
+```
+
+---
+
+## Research Papers → Vocabulary
+
+The `PaperDecomposer` reads research papers and extracts executable concepts:
+
+```python
+from flux.open_interp.paper_decomposer import PaperDecomposer
+pd = PaperDecomposer()
+vocab = pd.decompose_papers("/path/to/papers")  # 244 papers → 2979 concepts
+```
+
+**244 research papers → 2,979 FLUX vocabulary concepts.** Each concept becomes a word any agent can learn.
+
+Working implementations in `PaperBridge`:
+- **Confidence Cascade**: 3-zone confidence with deadband optimization
+- **OCDS Origin Tracking**: S=(O,D,T,Φ) provenance tuples
+- **Tile Composition**: compose(f,g) with confidence propagation
+- **Rate-Based Change**: Anomaly detection via rate monitoring
+- **Emergence Detection**: Collective > individual detection
+- **Structural Memory**: Memory-as-structure constraint encoding
+
+---
+
+## Ecosystem (April 2026)
+
+FLUX is now implemented in **11 languages**, with vocabulary interpreters in 4:
+
+| Repo | Language | Tests | Vocab Interpreter |
+|------|----------|-------|-------------------|
+| [flux-runtime](https://github.com/SuperInstance/flux-runtime) | Python | 2037 ✓ | ✅ |
+| [flux-runtime-c](https://github.com/SuperInstance/flux-runtime-c) | C | 49 ✓ | ISA v2 |
+| [flux-core](https://github.com/SuperInstance/flux-core) | Rust | 51 ✓ | ✅ |
+| [flux-zig](https://github.com/SuperInstance/flux-zig) | Zig | 15+ ✓ | ✅ |
+| [flux-js](https://github.com/SuperInstance/flux-js) | JavaScript | ✓ | Building |
+| [flux-swarm](https://github.com/SuperInstance/flux-swarm) | Go | ✓ | ✅ |
+| [flux-wasm](https://github.com/SuperInstance/flux-wasm) | WASM/Rust | In progress | |
+| [flux-java](https://github.com/SuperInstance/flux-java) | Java | VM + Assembler | |
+| [flux-py](https://github.com/SuperInstance/flux-py) | Python (minimal) | ✓ | Building |
+| [flux-cuda](https://github.com/SuperInstance/flux-cuda) | CUDA | GPU parallel | |
+| [flux-llama](https://github.com/SuperInstance/flux-llama) | C/llama.cpp | LLM integration | |
+
+## Related Repos
+
+| Repo | Description |
+|------|-------------|
+| [flux-research](https://github.com/SuperInstance/flux-research) | 40K words: compiler taxonomy, ISA v2, agent-first design |
+| [flux-benchmarks](https://github.com/SuperInstance/flux-benchmarks) | Performance comparison across 7 runtimes |
+| [captains-log](https://github.com/SuperInstance/captains-log) | Oracle1 growth diary + 15-exercise dojo curriculum |
+| [oracle1-index](https://github.com/SuperInstance/oracle1-index) | 663 repos indexed, searchable, activity feed |
+| [iron-to-iron](https://github.com/SuperInstance/iron-to-iron) | I2I protocol — agents communicate through git commits |
+| [superinstance-papers](https://github.com/SuperInstance/superinstance-papers) | 244 research papers → FLUX vocabulary |
+
+## Synthesis
+
+FLUX integrates ideas from:
+
+| Source | Contribution |
+|--------|-------------|
+| [nexus-runtime](https://github.com/SuperInstance/nexus-runtime) | Intent-to-bytecode pipeline, A2A opcodes, trust engine |
+| [mask-locked-inference-chip](https://github.com/Lucineer/mask-locked-inference-chip) | Zero-software-stack philosophy, hardware-enforced security |
+| GraalVM Truffle | Polyglot interop, multi-language type system |
+| LLVM | SSA IR, optimization passes |
+| WebAssembly | Compact binary, capability security |
+| BEAM VM (Erlang) | Zero-downtime hot code reload |
+| Legalese | Precise natural language with custom definitions |
+
+## Key Result
+**FLUX C VM is 4.7x faster than CPython for tight arithmetic. FLUX Zig VM is the fastest at 210ns/iter.**
+
+## License
+
+MIT