Metadata-Version: 2.4
Name: reflexmesh
Version: 0.1.0
Summary: Typed event-driven software control and learned metacontrol
Author: Felipe Santibanez-Leal
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/fsantibanezleal/reflexmesh
Project-URL: Issues, https://github.com/fsantibanezleal/reflexmesh/issues
Project-URL: Documentation, https://github.com/fsantibanezleal/reflexmesh/tree/main/docs
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: train
Requires-Dist: torch>=2.6; extra == "train"
Requires-Dist: scikit-learn>=1.6; extra == "train"
Requires-Dist: xgboost>=3.0; extra == "train"
Requires-Dist: gymnasium>=1.0; extra == "train"
Requires-Dist: sb3-contrib>=2.6; extra == "train"
Requires-Dist: onnx>=1.17; extra == "train"
Requires-Dist: onnxruntime>=1.20; extra == "train"
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.135; extra == "server"
Requires-Dist: uvicorn>=0.34; extra == "server"
Requires-Dist: httpx>=0.28; extra == "server"
Provides-Extra: mcp
Requires-Dist: jsonschema<5,>=4.23; extra == "mcp"
Requires-Dist: regex>=2024.11; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# reflexmesh

For actual user files, run `reflexmesh workflow recipe.json --workspace /absolute/directory`, or start the local workbench with `--workspace`. The [workspace workflow contract](docs/workspace-workflows.md) covers registered processes, dependency verification, previews, cancellation and native receipts.

Released trained checkpoints are separate downloadable assets: `reflexmesh fetch-models --destination models/checkpoints --version v0.01.000` verifies the archive and every model digest before replacing files. Use only project release artifacts: some trained framework formats require trusted model files. The scientific pipeline remains available to rebuild the checkpoints from owned data.

An event-driven software controller with a Rust authority core, Python tool adapters, learned policies and asynchronous language-model coordination. The library is the engine behind Neuraxis.

The controller maintains exact capabilities and resource versions separately from learned recurrent state. A policy proposes a bounded action or requests deliberation. The executor revalidates authority and state before dispatch, records effects durably, and preserves unknown outcomes for reconciliation. Model confidence never grants permission.

## Install and execute

Python 3.11+ is required. Source builds require Rust and platform C/C++ build tools. Training and the local workbench server are optional dependencies.

```sh
python -m pip install '.[train,server,dev]'
reflexmesh doctor
mkdir workspace
reflexmesh workflow examples/verified-workflow.json --workspace workspace
```

The example performs a real file write and checks its SHA-256 postcondition through the native broker. It does not call an LLM. Use the Runtime SDK to register files, fixed process templates, explicit HTTP endpoints and application-specific tools. Use Controller to submit dependent goals, subscribe to events and coordinate a slow planner.

```python
from pathlib import Path
from reflexmesh.effectors import WorkspaceFiles
from reflexmesh.runtime import Runtime

root = Path('workspace')
root.mkdir(exist_ok=True)
with Runtime(root, ('file.read', 'file.write')) as runtime:
    WorkspaceFiles(root).register(runtime)
    candidate = runtime.candidate('file.write', {'path': 'answer.txt', 'content': '42'})
    receipt = runtime.execute_candidate(candidate)
    print(receipt['status'])
```

## Scientific pipeline

The owned workload suite contains 20 independent software-effect families, six fault variants and disjoint train/validation/calibration/test environments. It executes disposable real files, local HTTP services and child processes with independent postcondition checks. Twelve policy methods cover FSM, behavior tree, calibrated logistic/XGBoost scoring, GRU behavior cloning, LinUCB, masked PPO, learned-transition lookahead, direct LLM, asynchronous FSM+LLM, learned deferral and recurrent metacontrol.

```sh
python -m reflexmesh.pipeline collect --artifacts artifacts
python -m reflexmesh.pipeline train --artifacts artifacts
python -m reflexmesh.pipeline ppo --artifacts artifacts
python -m reflexmesh.pipeline gates --artifacts artifacts --model qwen3.5:4b
python -m reflexmesh.pipeline evaluate --artifacts artifacts --seeds 10
```

Model-dependent methods require a real configured local Ollama model. No unavailable planner is silently replaced with a rule policy. Raw traces, fitted checkpoints, lineage digests and aggregate statistics remain separate. External benchmarks have independent code/model/data license and environment provenance. Scores on designed workloads do not establish production or AGI performance.

## Workbench service

```sh
reflexmesh serve --checkpoints artifacts/checkpoints --artifacts artifacts/evaluation --model qwen3.5:4b
```

The service binds loopback and prints a session token. Every executable endpoint requires that token and the same origin. The service executes registered disposable workloads; public static replays have no host-tool authority.

## Evidence and limits

Fast/slow routing, recurrent policies, predictive control and learned deferral are prior art. The research hypothesis concerns outcome-grounded deliberation allocation under asynchronous state change, resource-versioned proposals and persistent effect residuals. It requires matched held-out comparisons and component ablations. Implementation alone does not establish novelty or superiority.

This is a process-level coordination library, not an operating-system sandbox or a hard real-time system. A cancelled request does not imply rollback or cancellation of a remote provider. Hostile native executables require independent isolation. See [runtime contracts](docs/runtime.md), [native architecture](docs/architecture/native-broker.md), [contributing](CONTRIBUTING.md) and [security](SECURITY.md).

Authored source is Apache-2.0. External models, data and benchmarks retain their own licenses.
