mycelium-ei-language 0.2.2__tar.gz

mycelium_ei_language-0.2.2/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+## 0.2.2 (2026-09-11)
+
+First release on PyPI, published as `mycelium-ei-language`.
+
+### Changed
+
+- The distribution is renamed from `mycelium-ei-lang` to `mycelium-ei-language`.
+  The PyPI project `mycelium-ei-lang` belongs to an account whose two-factor
+  device and email were lost with a laptop, so it cannot receive releases and
+  its 0.1.x uploads stay broken. The import name `mycelium_ei`, the `myc` and
+  `mycelium` commands and the repository name are unchanged. `myc --version`
+  prints the distribution name: `mycelium-ei-language 0.2.2`.
+
+## 0.2.1 (2026-09-11)
+
+The license fix release, and the first version uploaded to PyPI. 0.2.0 was
+published only as a GitHub release (tag v0.2.0) while the PyPI upload waited
+on an account permission; it never reached PyPI.
+
+### Fixed
+
+- Every surface now says proprietary. `compiler/Cargo.toml` claimed
+  Apache-2.0 and `vscode-extension/package.json` claimed MIT; both point at
+  the one `LICENSE` now. Two marketing drafts called the language open
+  source and the Solidity template header said MIT.
+- `LICENSE` had a placeholder contact (`michael.benjamin.crowe@[domain]`) and
+  a support address on a domain that does not resolve. It now gives
+  michael@crowelogic.com and the GitHub issue tracker, and the copyright
+  year covers 2024-2026.
+
+## 0.2.0 (2026-09-11)
+
+The first release whose `pip install` runs the documented language.
+
+### Fixed
+
+- Releases 0.1.0 to 0.1.2 shipped a `mycelium_ei` module that parsed input with
+  Python's `ast` module, so every `.myc` program failed with `invalid syntax`,
+  and they declared no dependencies while importing numpy, so `import mycelium_ei`
+  failed on a clean install. 0.2.0 ships a lexer, parser and tree-walking
+  interpreter for the `.myc` grammar and has no runtime dependencies.
+- `examples/cultivation.myc` called `adapt_environment()`, which did not exist.
+  It now calls the `adjust_to_environment()` adapt function it defines.
+- `examples/neural_network.myc` called four functions that existed nowhere
+  (`create_signal`, `ecological_loss`, `update_mycelial_connections`,
+  `adapt_to_environment`). It is rewritten as a complete, smaller program that
+  uses the same constructs: a `network` record, a `signal` type, a `mycelium`
+  with methods and an `adapt function`, `new`, method calls and array methods.
+- Version strings agreed nowhere (pyproject 0.1.0, package 0.1.1, PyPI 0.1.2).
+  The version now lives only in `mycelium_ei/__init__.py`; `setup.py` is gone.
+- The Rust workspace listed members that were not in the repository, so
+  `cargo` could not start. The workspace now lists only `compiler`, which
+  builds and passes its one test after a logos 0.13 migration and a borrow fix.
+  It is still a library skeleton and the Python package does not use it.
+
+### Added
+
+- Language: `else if` chains, `null`, `const` (assignment is an error), object
+  literals `{key: value}` with identifier or string keys, indexing `a[i]`,
+  property access `a.b` and assignment to indexed and property targets,
+  method calls on arrays (`append`, `pop`, `insert`, `remove`, `contains`,
+  `index_of`, `sort`, `reverse`, `join`, `slice`, `copy`, `length`), strings
+  (`upper`, `lower`, `trim`, `split`, `contains`, `starts_with`, `ends_with`,
+  `replace`, `index_of`, `length`) and objects (`keys`, `values`, `has`,
+  `remove`, `copy`, `length`), block comments `/* */`, string escapes,
+  exponent literals, `for` over arrays, objects, strings and ints.
+- `mycelium` blocks are classes: `signal` fields with defaults or types,
+  inline or typed `network` fields, methods, an optional `init` method that
+  receives the `new` arguments, and `adapt function` methods. Inside a method
+  the fields and the other methods are reachable by bare name.
+- Top-level `network Name { ... }` declares a named record and `signal Name
+  { field: type }` declares a record type; a typed field gets a copy of the
+  record or a zero-filled instance.
+- `adapt` functions run once each time `set_env` or `update_global_env`
+  changes a parameter; an adapt function that itself calls `set_env` does not
+  retrigger the pass.
+- Error messages carry `file:line:column`, and the `myc` command prints them
+  as `runtime error:` or `syntax error:` lines and exits 1.
+- Runaway recursion is reported as `Maximum call depth (N) exceeded` instead
+  of crashing the process. The cap is 200 nested calls from Python and 2000
+  from the `myc` command, which runs the program on a thread with a 256 MB
+  stack (CPython 3.10 and older overflow the main thread's stack far earlier).
+- `print` shows `true`, `false` and `null`, quotes strings inside arrays and
+  objects, and joins arguments with one space.
+- New builtins: `sqrt`, `pow`, `exp`, `log`, `tan`, `floor`, `ceil`, `round`,
+  `sum`, `sorted`, `random`, `random_range`, `random_int`, `clock`, `bool`,
+  `type_of`, `keys`, `values`, `has`, `contains`, `join`, `split`, `env`.
+- CLI: `--check`, `--tokens`, `--ast`, `--no-sleep` (or `MYCELIUM_NO_SLEEP=1`),
+  `--seed N`, `--traceback`, and `-` to read a program from standard input.
+  `--help` is plain text. Exit codes: 0 ran, 1 error, 2 no file given.
+- Python API: `mycelium_ei.run_file`, `run_source`, `Interpreter(write=,
+  no_sleep=, seed=)`, `parse`, `tokenize`.
+- A test suite (134 tests) covering the lexer, parser, interpreter, builtins,
+  the CLI, every example program, and the absence of third-party imports.
+
+### Changed
+
+- The optimizers (`genetic_optimize`, `swarm_optimize`, `ant_optimize`,
+  `bio_compare`) are pure Python; particle swarm and ant colony no longer use
+  numpy. Results differ numerically from 0.1.x runs.
+- A fitness function may take one array parameter or one parameter per
+  dimension; it must return a number.
+- `add_node()` connects each new node to the previously added node, so
+  `broadcast_signal` reaches the nodes an example creates. Node ids are
+  `node_01`, `node_02`, ... instead of random UUID prefixes.
+- `get_env` of an undeclared parameter is an error instead of returning 0.0.
+- Assigning to a variable that was never declared with `let` is an error.
+- Builtin output lines no longer contain emoji.
+- `requires-python` is `>=3.9`. Tested on CPython 3.9 through 3.14 on macOS.
+- `examples/network_demo.myc` prints the node and connection counts instead of
+  the whole statistics object.
+
+### Removed
+
+- `mycelium_interpreter.py`, `bio_algorithms.py`, `bio_ml_integration.py`,
+  `cultivation_monitor.py` and `network_framework.py` at the repository root.
+  Their code moved into the `mycelium_ei` package.
+- `setup.py`.
+
+## 0.1.2 (2025-09-14), 0.1.1 and 0.1.0 (2025-09-12)
+
+First uploads. Broken as described under 0.2.0: the installed command could
+not run any `.myc` file.

mycelium_ei_language-0.2.2/LICENSE

@@ -0,0 +1,57 @@
+PROPRIETARY SOFTWARE LICENSE AGREEMENT
+
+Copyright (c) 2024-2026 Michael Benjamin Crowe. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the exclusive
+property of Michael Benjamin Crowe ("Owner"). 
+
+NOTICE: This is proprietary software. Unauthorized copying, modification, distribution,
+or use of this Software is strictly prohibited and may result in severe civil and
+criminal penalties, and will be prosecuted to the maximum extent possible under law.
+
+LIMITED LICENSE GRANT:
+Subject to the terms and conditions of this Agreement, the Owner grants you a limited,
+non-exclusive, non-transferable, revocable license to:
+
+1. VIEW the source code for evaluation purposes only
+2. USE the Software for personal, non-commercial evaluation only
+3. PROVIDE feedback and suggestions to the Owner
+
+RESTRICTIONS:
+You may NOT:
+- Copy, modify, or create derivative works of the Software
+- Distribute, sublicense, lease, rent, or lend the Software
+- Use the Software for commercial purposes without explicit written permission
+- Reverse engineer, decompile, or disassemble the Software
+- Remove or alter any proprietary notices or labels
+
+COMMERCIAL LICENSING:
+For commercial use, enterprise deployment, or custom licensing arrangements,
+please contact: michael@crowelogic.com
+
+INTELLECTUAL PROPERTY:
+All intellectual property rights in and to the Software, including but not limited
+to any images, photographs, animations, video, audio, music, text, and "applets"
+incorporated into the Software, are owned by the Owner or its suppliers and are
+protected by international copyright laws and treaties.
+
+NO WARRANTIES:
+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.
+
+LIMITATION OF LIABILITY:
+IN NO EVENT SHALL THE OWNER 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.
+
+TERMINATION:
+This license is effective until terminated. Your rights under this license will
+terminate automatically without notice if you fail to comply with any of its terms.
+
+GOVERNING LAW:
+This Agreement shall be governed by and construed in accordance with the laws of
+the jurisdiction in which the Owner resides.
+
+For licensing inquiries: michael@crowelogic.com
+For technical support: https://github.com/MichaelCrowe11/mycelium-ei-lang/issues

mycelium_ei_language-0.2.2/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include examples *.myc
+recursive-include docs *.md
+global-exclude *.pyc
+global-exclude .DS_Store

mycelium_ei_language-0.2.2/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: mycelium-ei-language
+Version: 0.2.2
+Summary: A small interpreted language for cultivation models: environment parameters, adapt functions that fire when they change, and genetic, particle swarm and ant colony optimizers.
+Author-email: Michael Benjamin Crowe <michael@crowelogic.com>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/MichaelCrowe11/mycelium-ei-lang
+Project-URL: Repository, https://github.com/MichaelCrowe11/mycelium-ei-lang
+Project-URL: Issues, https://github.com/MichaelCrowe11/mycelium-ei-lang/issues
+Project-URL: Changelog, https://github.com/MichaelCrowe11/mycelium-ei-lang/blob/master/CHANGELOG.md
+Keywords: interpreter,scripting-language,cultivation,mycelium,genetic-algorithm,particle-swarm,ant-colony
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# Mycelium-EI-Lang
+
+Mycelium-EI-Lang is a small interpreted language for cultivation models: environment parameters, adapt functions that fire when they change, and genetic, particle swarm and ant colony optimizers.
+
+## Status
+
+early stage
+
+0.2.2 is the first release on PyPI that runs `.myc` programs. It is published as **mycelium-ei-language**. The older PyPI project `mycelium-ei-lang` (0.1.0 to 0.1.2) belongs to an account whose two-factor device was lost with a laptop, so it cannot be updated; its interpreter parsed Python syntax and imported a dependency it did not declare, and `myc examples/hello_world.myc` fails on every install of it. Do not install `mycelium-ei-lang`.
+
+What does not work yet:
+
+- One file per program. There is no `import`, no module system and no standard library beyond the builtins listed in `docs/reference.md`.
+- The interpreter walks the syntax tree in Python. Loops of a few hundred thousand iterations take seconds.
+- The optimizers, the neural network and the cultivation monitor are demonstration models: small populations, a Hebbian toy network, readings drawn from `random.gauss`. None of it reads a sensor or controls equipment.
+- The Rust crate under `compiler/` builds and passes its two tests, but it is a skeleton with no command-line tool. The Python package does not use it. Nothing here compiles to native code or WebAssembly.
+- Run only on macOS (arm64). Linux and Windows have not been tried.
+
+## Install and first run
+
+Run on 2026-09-11 with CPython 3.13.14 on macOS.
+
+```
+python3 -m venv .venv
+. .venv/bin/activate
+pip install mycelium-ei-language
+myc --version
+```
+
+Output:
+
+```
+mycelium-ei-language 0.2.2
+```
+
+Save this as `hello.myc`:
+
+```
+// Hello World in Mycelium-EI-Lang
+
+environment {
+    temperature: 22.5,
+    humidity: 85.0
+}
+
+function main() {
+    print("Hello from the Mycelium Network!")
+
+    let greeting: string = "Welcome to ecological intelligence programming"
+    print(greeting)
+
+    let temp: float = get_env("temperature")
+    if temp > 20.0 {
+        print("Optimal growth conditions detected")
+    } else {
+        print("Adjusting environmental parameters...")
+    }
+}
+```
+
+Then run it:
+
+```
+myc hello.myc
+```
+
+Output:
+
+```
+Hello from the Mycelium Network!
+Welcome to ecological intelligence programming
+Optimal growth conditions detected
+```
+
+`mycelium` and `python -m mycelium_ei` are the same command as `myc`. The package has no dependencies. The twelve programs in `examples/` and the tests are in the repository: `git clone https://github.com/MichaelCrowe11/mycelium-ei-lang`, then `pip install -e . pytest` and `pytest` in the checkout.
+
+## What runs today
+
+Each item is covered by a test in `tests/`; the suite (140 tests) passed on CPython 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14 on macOS on 2026-09-11.
+
+- The language in `docs/reference.md`: `environment` blocks, functions, `let` and `const`, `if`/`else if`/`else`, `while`, `for` over arrays, objects, strings and ints, arrays and objects with methods, string concatenation, `mycelium` declarations with fields, methods, `init` and `adapt` functions, `new`, and top-level `network` and `signal` declarations (`tests/test_interpreter.py`, `tests/test_parser.py`, `tests/test_lexer.py`).
+- `adapt` functions run when `set_env` or `update_global_env` changes a parameter; `examples/cultivation.myc` and `examples/neural_network.myc` show it (`tests/test_examples.py`).
+- All twelve programs in `examples/` run to completion under `myc --no-sleep --seed 1` (`tests/test_examples.py`).
+- `genetic_optimize`, `swarm_optimize`, `ant_optimize` and `bio_compare` in pure Python; a fitness function takes one array or one argument per dimension (`tests/test_bio.py`, `examples/bio_optimization_demo.myc`).
+- Network builtins: nodes, connections, broadcast signals that print as they arrive (`examples/network_demo.myc`).
+- Toy neural network and simulated cultivation builtins (`examples/bio_ml_demo.myc`, `examples/cultivation_platform_demo.myc`).
+- Command line: `--check`, `--tokens`, `--ast`, `--no-sleep`, `--seed`, `-` for standard input; errors print as `file:line:column: runtime error: ...` and exit 1; runaway recursion stops with a message instead of a crash (`tests/test_cli.py`).
+- Importing the package pulls in no third-party module (`tests/test_no_dependencies.py`).
+- `cargo build` and `cargo test` pass for `compiler/` (one unit test, one doc test).
+
+## Limits
+
+- This is an interpreter for small models, not a numerical library. The optimizers search `[-1, 1]` per dimension with populations of tens; no speed or quality claim is made against established packages.
+- `create_cultivation` and `monitor_cultivation` simulate a grow room. Do not use them to run one.
+- `quantum_bio_computing.py` and `performance_optimizations.py` at the repository root are standalone experiments from 2025 that need numpy and numba. They are not part of the package and have no tests.
+- The directories `crypto-payments/`, `npm-package/`, `vscode-extension/`, `wasm/`, `snap/`, `homebrew/`, `conda-recipe/` and the two Dockerfiles have not been run. The planning documents at the root (roadmaps, monetization, publishing) describe 2025 intentions and prices. They are not an offer.
+- Syntax errors are reported one at a time, at the first token the parser cannot place.
+
+## License and contact
+
+Proprietary. See `LICENSE`: viewing and personal non-commercial evaluation only; no copying, modification or redistribution.
+
+Contact: michael@crowelogic.com

mycelium_ei_language-0.2.2/README.md

@@ -0,0 +1,103 @@
+# Mycelium-EI-Lang
+
+Mycelium-EI-Lang is a small interpreted language for cultivation models: environment parameters, adapt functions that fire when they change, and genetic, particle swarm and ant colony optimizers.
+
+## Status
+
+early stage
+
+0.2.2 is the first release on PyPI that runs `.myc` programs. It is published as **mycelium-ei-language**. The older PyPI project `mycelium-ei-lang` (0.1.0 to 0.1.2) belongs to an account whose two-factor device was lost with a laptop, so it cannot be updated; its interpreter parsed Python syntax and imported a dependency it did not declare, and `myc examples/hello_world.myc` fails on every install of it. Do not install `mycelium-ei-lang`.
+
+What does not work yet:
+
+- One file per program. There is no `import`, no module system and no standard library beyond the builtins listed in `docs/reference.md`.
+- The interpreter walks the syntax tree in Python. Loops of a few hundred thousand iterations take seconds.
+- The optimizers, the neural network and the cultivation monitor are demonstration models: small populations, a Hebbian toy network, readings drawn from `random.gauss`. None of it reads a sensor or controls equipment.
+- The Rust crate under `compiler/` builds and passes its two tests, but it is a skeleton with no command-line tool. The Python package does not use it. Nothing here compiles to native code or WebAssembly.
+- Run only on macOS (arm64). Linux and Windows have not been tried.
+
+## Install and first run
+
+Run on 2026-09-11 with CPython 3.13.14 on macOS.
+
+```
+python3 -m venv .venv
+. .venv/bin/activate
+pip install mycelium-ei-language
+myc --version
+```
+
+Output:
+
+```
+mycelium-ei-language 0.2.2
+```
+
+Save this as `hello.myc`:
+
+```
+// Hello World in Mycelium-EI-Lang
+
+environment {
+    temperature: 22.5,
+    humidity: 85.0
+}
+
+function main() {
+    print("Hello from the Mycelium Network!")
+
+    let greeting: string = "Welcome to ecological intelligence programming"
+    print(greeting)
+
+    let temp: float = get_env("temperature")
+    if temp > 20.0 {
+        print("Optimal growth conditions detected")
+    } else {
+        print("Adjusting environmental parameters...")
+    }
+}
+```
+
+Then run it:
+
+```
+myc hello.myc
+```
+
+Output:
+
+```
+Hello from the Mycelium Network!
+Welcome to ecological intelligence programming
+Optimal growth conditions detected
+```
+
+`mycelium` and `python -m mycelium_ei` are the same command as `myc`. The package has no dependencies. The twelve programs in `examples/` and the tests are in the repository: `git clone https://github.com/MichaelCrowe11/mycelium-ei-lang`, then `pip install -e . pytest` and `pytest` in the checkout.
+
+## What runs today
+
+Each item is covered by a test in `tests/`; the suite (140 tests) passed on CPython 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14 on macOS on 2026-09-11.
+
+- The language in `docs/reference.md`: `environment` blocks, functions, `let` and `const`, `if`/`else if`/`else`, `while`, `for` over arrays, objects, strings and ints, arrays and objects with methods, string concatenation, `mycelium` declarations with fields, methods, `init` and `adapt` functions, `new`, and top-level `network` and `signal` declarations (`tests/test_interpreter.py`, `tests/test_parser.py`, `tests/test_lexer.py`).
+- `adapt` functions run when `set_env` or `update_global_env` changes a parameter; `examples/cultivation.myc` and `examples/neural_network.myc` show it (`tests/test_examples.py`).
+- All twelve programs in `examples/` run to completion under `myc --no-sleep --seed 1` (`tests/test_examples.py`).
+- `genetic_optimize`, `swarm_optimize`, `ant_optimize` and `bio_compare` in pure Python; a fitness function takes one array or one argument per dimension (`tests/test_bio.py`, `examples/bio_optimization_demo.myc`).
+- Network builtins: nodes, connections, broadcast signals that print as they arrive (`examples/network_demo.myc`).
+- Toy neural network and simulated cultivation builtins (`examples/bio_ml_demo.myc`, `examples/cultivation_platform_demo.myc`).
+- Command line: `--check`, `--tokens`, `--ast`, `--no-sleep`, `--seed`, `-` for standard input; errors print as `file:line:column: runtime error: ...` and exit 1; runaway recursion stops with a message instead of a crash (`tests/test_cli.py`).
+- Importing the package pulls in no third-party module (`tests/test_no_dependencies.py`).
+- `cargo build` and `cargo test` pass for `compiler/` (one unit test, one doc test).
+
+## Limits
+
+- This is an interpreter for small models, not a numerical library. The optimizers search `[-1, 1]` per dimension with populations of tens; no speed or quality claim is made against established packages.
+- `create_cultivation` and `monitor_cultivation` simulate a grow room. Do not use them to run one.
+- `quantum_bio_computing.py` and `performance_optimizations.py` at the repository root are standalone experiments from 2025 that need numpy and numba. They are not part of the package and have no tests.
+- The directories `crypto-payments/`, `npm-package/`, `vscode-extension/`, `wasm/`, `snap/`, `homebrew/`, `conda-recipe/` and the two Dockerfiles have not been run. The planning documents at the root (roadmaps, monetization, publishing) describe 2025 intentions and prices. They are not an offer.
+- Syntax errors are reported one at a time, at the first token the parser cannot place.
+
+## License and contact
+
+Proprietary. See `LICENSE`: viewing and personal non-commercial evaluation only; no copying, modification or redistribution.
+
+Contact: michael@crowelogic.com

mycelium_ei_language-0.2.2/docs/reference.md

@@ -0,0 +1,235 @@
+# Mycelium-EI-Lang reference
+
+This is the whole language as the interpreter in `mycelium_ei` runs it. Every
+construct here is exercised by `tests/` or by a program in `examples/`.
+
+## Running programs
+
+```
+myc program.myc            run a program (main() runs last if it is defined)
+myc --check program.myc    parse only, report syntax errors
+myc --tokens program.myc   print the token stream
+myc --ast program.myc      print the syntax tree
+myc --no-sleep ...         sleep() returns at once (also MYCELIUM_NO_SLEEP=1)
+myc --seed 1 ...           seed the random number generator for repeatable runs
+myc -                      read the program from standard input
+```
+
+`mycelium` and `python -m mycelium_ei` are the same command. Exit code 0 means
+the program ran to the end, 1 means a syntax or runtime error (printed to
+standard error as `file:line:column: kind: message`), 2 means no file was given.
+
+From Python:
+
+```python
+from mycelium_ei import run_file, run_source, Interpreter
+
+run_file("examples/hello_world.myc")
+lines = []
+interp = Interpreter("<inline>", write=lines.append, no_sleep=True, seed=1)
+interp.run('print("hi", 1 + 1)')
+assert lines == ["hi 2"]
+```
+
+## Lexical rules
+
+- Comments: `// to end of line` and `/* block */`.
+- Integers `42`, floats `1.5`, `2e-3`; strings in double quotes with the
+  escapes `\n \t \r \" \\ \0`; `true`, `false`, `null`.
+- Identifiers: letters, digits and `_`, not starting with a digit.
+- Keywords: `environment function mycelium network signal adapt if else while
+  for in return let const new true false null`. Keywords may be used as
+  object keys and after `.` (`stats.environment`).
+- Statements end at the end of the expression; `;` is allowed and ignored.
+  A call or index must start on the same line as the expression it applies
+  to, so a line that starts with `(` or `[` begins a new statement.
+
+## Types and values
+
+`int`, `float`, `string`, `bool`, `null`, `array` (`[1, 2]`), `object`
+(`{key: value, "other key": 2}`), `function`, and instances of `mycelium`
+declarations. `type_of(x)` returns the name. Type annotations (`let x: float`,
+`function f(a: int) -> float`) are accepted and ignored.
+
+Truthiness follows Python: `0`, `0.0`, `""`, `[]`, `{}` and `null` are false.
+
+`print` shows booleans as `true`/`false`, `null` as `null`, floats with full
+precision, and quotes strings inside arrays and objects.
+
+## Expressions
+
+Precedence, lowest first: assignment `=`; `||`; `&&`; `==` `!=`; `<` `>` `<=`
+`>=`; `+` `-`; `*` `/` `%`; unary `!` `-`; postfix call `f(x)`, index `a[i]`,
+property `a.b`; primary.
+
+- `+` on a string and anything concatenates (the other operand is formatted
+  as `print` would show it); on two arrays it concatenates them.
+- `/` always gives a float; `%` follows Python. Division or modulo by zero is
+  a runtime error.
+- `<` and friends compare numbers with numbers or strings with strings.
+- `&&` and `||` short-circuit and return the deciding operand.
+- Indexing an array out of range is an error; `object["missing"]` is an error;
+  `object.missing` is `null`.
+- Assignment targets: a variable declared with `let`, `array[i]`,
+  `object.key`, `object[key]`, `instance.field`.
+
+## Statements
+
+```
+let x: float = 1.0          // declare; type is optional and ignored
+const limit = 10            // assigning to a const is an error
+x = x + 1                   // assignment needs a prior let
+if a < b { ... } else if a == b { ... } else { ... }
+while cond { ... }
+for item in [1, 2, 3] { ... }     // arrays: items; objects: keys; strings: characters
+for i in 5 { ... }                // an int iterates 0..4; range(a, b) builds an array
+return expr                       // bare return at end of line returns null
+```
+
+Blocks open a new scope: a `let` inside `if`, `while`, `for` or a function is
+not visible outside it. Assignment finds the nearest enclosing declaration.
+
+## Functions
+
+```
+function name(a, b: float) -> float {
+    return a * b
+}
+```
+
+Calls must pass exactly as many arguments as there are parameters. Functions
+are values: `let f = name`. A user function with the same name as a builtin
+replaces it. If `main` is defined it runs after all top-level statements.
+
+Runaway recursion stops with `Maximum call depth (N) exceeded`. N is 2000 for
+the `myc` command, which runs the program on a thread with a 256 MB stack, and
+200 for `Interpreter` used directly from Python (`max_call_depth=` changes it;
+on CPython 3.10 and older, going higher needs `run_in_thread`).
+
+## Environment block and adapt functions
+
+```
+environment {
+    temperature: 22.5,
+    humidity: 85.0
+}
+
+adapt function respond() {
+    if get_env("temperature") > 28.0 { print("too warm") }
+}
+
+set_env("temperature", 30.0)     // prints "too warm"
+```
+
+`get_env(name)` reads a declared parameter (an undeclared name is an error);
+`set_env(name, value)` and `update_global_env(name, value)` set one and then
+run every `adapt` function once: top-level `adapt function`s with no
+parameters, then the `adapt function` methods of every live `mycelium`
+instance. An adapt function that itself calls `set_env` does not restart the
+pass. `env()` returns all parameters as an object.
+
+## mycelium, network and signal declarations
+
+```
+network Substrate { nodes: 4, density: 0.75 }      // a named record (an object)
+signal Pulse { amplitude: float, speed: float }     // a record type
+
+mycelium Colony {
+    signal growth: float = 1.0        // field with a default
+    signal label: string              // field with a typed zero value ("")
+    network links: Substrate          // field: a copy of the Substrate record
+    network local { size: 2 }         // field: an inline record
+    signal pulse: Pulse               // field: {amplitude: 0.0, speed: 0.0}
+
+    function init(name) { label = name }          // optional; receives the new arguments
+    function grow(by) { growth = growth + by; return describe() }
+    function describe() { return label + ": " + growth }
+    adapt function react() { growth = growth * 2.0 }
+}
+
+let c = new Colony("alpha")
+c.grow(0.5)            // method call
+c.growth               // field read
+c.links.nodes = 8      // fields are ordinary values
+```
+
+Inside a method, fields and the other methods are reachable by bare name and
+assignment to a field name updates the instance. Zero values by type: `float`
+0.0, `int` 0, `string` "", `bool` false, `array` [], `object` {}, anything
+else `null`. Each instance gets its own copy of record-typed fields.
+
+## Methods on arrays, strings and objects
+
+Arrays: `append(x...)` (alias `push`), `pop([i])`, `insert(i, x)`,
+`remove(x)`, `contains(x)`, `index_of(x)` (-1 if absent), `sort()`,
+`reverse()`, `join(sep)`, `slice(start[, end])`, `copy()`, `length`.
+
+Strings: `upper()`, `lower()`, `trim()`, `split([sep])`, `contains(s)`,
+`starts_with(s)`, `ends_with(s)`, `replace(old, new)`, `index_of(s)`,
+`length`. Strings are indexable: `s[0]`.
+
+Objects: `keys()`, `values()`, `has(key)`, `remove(key)`, `copy()`, `length`.
+A key that is also a method name is returned as the key's value.
+
+## Builtin functions
+
+Output and collections: `print(values...)`, `len(x)`, `range(end)` /
+`range(start, end[, step])`, `reverse(array)`, `sorted(array)`,
+`sum(array)`, `keys(obj)`, `values(obj)`, `has(obj, key)`,
+`contains(array_or_string, item)`, `join(array[, sep])`, `split(string[, sep])`.
+
+Math: `abs`, `min(a, b, ...)` or `min(array)`, `max`, `sqrt`, `pow(x, y)`,
+`exp`, `log(x[, base])`, `sin`, `cos`, `tan`, `floor`, `ceil`,
+`round(x[, digits])`, `random()` in [0, 1), `random_range(low, high)`,
+`random_int(low, high)`, `clock()` (seconds, monotonic).
+
+Conversion: `int`, `float`, `str`, `bool`, `type_of`.
+
+Environment: `get_env`, `set_env`, `env`, `sleep(milliseconds)`.
+
+Cultivation helpers: `calculate_growth_factor(temp, humidity, co2)` (a 0..1
+factor centred on 24 C, 85 percent humidity and 1000 ppm CO2),
+`create_one_hot(index, size)`, `apply_activation(x, "relu" | "sigmoid" |
+"tanh" | "linear")` or `apply_activation(array, "softmax")`,
+`apply_signal_decay(x_or_array, distance)` (multiplies by `exp(-0.1 *
+distance)`), `signal_alert(message)` and `signal_network(type, value)` (both
+print one line).
+
+Network: `create_network([name])`, `add_node([network])` (connects the new
+node to the previous one; ids are `node_01`, `node_02`, ...),
+`connect_nodes(a, b)`, `broadcast_signal(type, payload[, network])` with type
+`growth`, `nutrient`, `stress`, `alert` or `data`, `update_global_env(name,
+value[, network])`, `get_network_stats([network])` returning `{name, nodes,
+connections, environment}`. Nodes print a line when they receive a signal.
+
+Optimizers (pure Python, maximise the fitness, search space [-1, 1] per
+dimension): `genetic_optimize(fitness, dimensions=6, population_size=50,
+max_generations=100)`, `swarm_optimize(fitness, dimensions=6,
+num_particles=30, max_iterations=100)`, `ant_optimize(fitness, dimensions=6,
+num_ants=25, max_iterations=100)`, `bio_compare(fitness, dimensions=6)`. The
+fitness is a function or a function name; it takes either one array or one
+parameter per dimension and must return a number. Results are objects with
+`solution`, `fitness`, `time` and `generations` or `iterations`; `bio_compare`
+returns `{genetic: {...}, pso: {...}, aco: {...}}`. The optimizers print
+progress lines.
+
+Toy neural network (Hebbian-style adaptation, no gradient descent):
+`create_bio_network(id, input_size=4, hidden_size=8, output_size=2)`,
+`train_bio_network(id, data, epochs=50)` where data is `"growth_pattern"`
+(20 generated samples) or an array of `[inputs, targets]` pairs,
+`predict_bio_network(id, inputs)`, `compare_bio_ml([data])`.
+
+Simulated cultivation (readings come from `random.gauss`, not sensors):
+`create_cultivation(id)`, `monitor_cultivation(id)` returning `{temperature,
+humidity, growth_rate, alerts, stage}`, `get_cultivation_health(id)` returning
+`{health_score, predicted_growth, recommendations}`,
+`optimize_cultivation(id)` returning `{fitness, optimal_temperature,
+optimal_humidity, optimal_nutrients, time}`.
+
+## Errors
+
+Syntax errors stop before anything runs. Runtime errors stop the program at
+the failing line. Both print as `file:line:column: syntax error: ...` or
+`file:line:column: runtime error: ...`. From Python they are
+`mycelium_ei.MyceliumSyntaxError` and `mycelium_ei.MyceliumRuntimeError`
+(both `MyceliumError`) with `line`, `column`, `filename` and `format()`.