bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 16쪽 중 1쪽
# Welcome
Welcome to Gensyn's official developer documentation.
## About
These docs are a technical reference for the tools Gensyn has built for developers. They cover how to install, configure, and build with each tool, plus an archive of paused testnet products.
For an overview of the company, its research, and what it's building, visit [gensyn.ai](https://gensyn.ai).
### Developer Tools
Each tool below has its own getting-started guide, configuration reference, and troubleshooting page. Start with the one that matches what you're building.
#### Reproducible Execution Environment (REE)
Run AI model inference in a machine-agnostic environment, where the same model and inputs produce the same outputs across supported hardware. Each run produces a receipt that anyone can use to check the result.
* [Get started with REE](https://docs.gensyn.ai/tech/ree/get-started)
* [Supported models](https://docs.gensyn.ai/tech/ree/supported-models)
* [Receipts](https://docs.gensyn.ai/tech/ree/receipts)
### Agent eXchange Layer (AXL)
An encrypted, decentralised peer-to-peer communication layer for AI agents and applications. AXL moves data directly between machines, with no central server, and has built-in support for MCP and A2A.
* [Get started with AXL](https://docs.gensyn.ai/tech/agent-exchange-layer/get-started)
* [How it works](https://docs.gensyn.ai/tech/agent-exchange-layer/how-it-works)
* [Building applications and examples](https://docs.gensyn.ai/tech/agent-exchange-layer/examples-and-building)
### Delphi Developer Tools
Tools for building on [Delphi](https://app.delphi.fyi), Gensyn's information markets platform.
* [Delphi SDK](broken://spaces/jHECdpSAZDuPfU2oZmM2/pages/mdrGUs3nrG3xtbr4TQxP): A TypeScript SDK for listing markets, querying positions, and trading on Delphi.
* [Agentic Trading Toolkit (ATT)](broken://spaces/jHECdpSAZDuPfU2oZmM2/pages/zsoiWKMm9Y0hQYVvFz9i): Lets AI agents browse, trade, and manage Delphi positions through natural language.
### Testnet Archive (Legacy)
These products ran on the Gensyn Testnet and are no longer actively maintained. Their [documentation](https://docs.gensyn.ai/testnet) remains available as a record of the network's development.
* [RL Swarm](https://docs.gensyn.ai/testnet/rl-swarm): a framework for distributed reinforcement learning across nodes on the internet.
* [BlockAssist](https://docs.gensyn.ai/testnet/blockassist): an AI-driven Minecraft environment where agents learn from player actions.
* [CodeAssist](https://docs.gensyn.ai/testnet/codeassist): an AI coding assistant that adapts to your programming style.
{% hint style="info" %}
No official swarms are running at this time.
{% endhint %}
### Using These Docs with AI Tools
These docs are built to be read by coding assistants and agents as well as people. Add `.md` to any page URL to get a clean Markdown version, or point your tool at [llms.txt](https://docs.gensyn.ai/llms.txt) for a full index of every page.
### Community and Source Code
If you get stuck, find a bug, or want to share what you're building, use the channels below.
* Discord: Ask questions and talk with the team and other builders in the [Gensyn Discord](https://discord.com/invite/gensyn).
* GitHub: Browse the source for Gensyn's open tools on [GitHub](https://github.com/gensyn-ai).
# Reproducible Execution Environment (REE)
Run AI model inference in a machine-agnostic environment where the same model and inputs produce the same outputs across supported hardware.
## Overview
REE (Reproducible Execution Environment) is Gensyn's toolchain for executing AI model inference in a machine-agnostic, bitwise-reproducible fashion.
It packages everything needed to run a model: **\[1]** export, **\[2]** compilation, **\[3]** inference, and **\[4]** output decoding, into a containerized pipeline that produces bitwise-identical results regardless of which hardware it runs on.
{% hint style="info" %}
**Current release: `v0.8.0`.** REE hardens the NVIDIA GPU backend, defaults to bfloat16 on Apple silicon, and speeds up reproducible CUDA inference. The previous release, `v0.7.0`, upgraded to PyTorch 2.12.1 and Transformers 5.10.4, expanded reproducible kernel and model coverage, and added an experimental quantized inference path (H100 only).
Some receipts generated with earlier versions may not reproduce with `v0.8.0`. See [Receipts](/tech/ree/receipts).
{% endhint %}
REE is comprised of three main components:
1. **Gensyn SDK:** The engine that orchestrates the end-to-end pipeline: export, compilation, inference, and output decoding.
2. **Gensyn Compiler:** An MLIR-based, multi-stage compiler that converts ONNX models into PyTorch modules, optionally replacing standard kernels with reproducible ones.
3. **RepOp Kernels:** Purpose-built CPU kernels and GPU operators that guarantee bitwise-identical outputs across different hardware, parallelism configurations, and run orders. Coverage includes reproducible int8 attention, fused gathered-log-probability, and MoE expert GEMM kernels. 
{% hint style="info" %}
`v0.7.0` adds reproducible kernels for paged KV-cache attention, block-sparse causal attention, Gated DeltaNet, MLA, stochastic rounding, and grouped expert matmul. `v0.8.0` speeds up reproducible CUDA inference with split-K decode attention, warp-specialized decode GEMVs, and fused RMSNorm.
{% endhint %}
The Gensyn SDK also exposes higher-level primitives for reusable inference sessions, tool definitions in chat-template-based inference (v0.3.0), and thinking-mode control via chat templates (v0.4.0).
You interact with all of these through the [REE TUI](/tech/ree/using-the-tui)**,** a terminal interface that lets you configure and run generations *without* touching the underlying CLI directly, unless you're interested in [advanced usage.](/tech/ree/advanced-usage)
{% hint style="warning" %}
While the scripts in this repository are open-source, REE as a whole is not. REE includes proprietary components that are downloaded from Gensyn servers, and these components are subject to Gensyn's licensing terms.
*By using this software, you agree to comply with those terms. For official terms and conditions, please see the* [*EULA licensing agreement.*](https://github.com/gensyn-ai/ree/blob/main/REE-Binary-License)
{% endhint %}
### Why Reproducibility?
Standard GPU execution is inherently non-deterministic, meaning the same model with the same inputs can produce different outputs each time you run it.
This happens because of how GPUs handle mathematical operations: they split work across many parallel processors to run faster, but this parallelization can happen in slightly different orders between runs. Even tiny differences in the order of operations can accumulate through the many layers of a neural network, eventually leading to noticeably different results.
Existing solutions like PyTorch's deterministic mode only solve part of the problem. They can make your results consistent on the same GPU across multiple runs, but they break down when you switch to different hardware. For example, an A100 and an H100 will still produce different outputs. These tools also have limited coverage and can't account for the fact that different GPU architectures implement mathematical functions differently at the hardware level.
REE solves this because reproducibility is *essential* for verifiable AI inference.
When third parties need to independently verify that a computation was performed correctly, such as in decentralized compute networks or prediction markets, they must be able to run the same model on their own hardware and get exactly the same result.
REE achieves this through [RepOps](/tech/ree/advanced-usage/internals), custom operators that use careful mathematical techniques (fixed reduction ordering, correctly rounded functions, and extended precision) to guarantee identical outputs across any hardware, without sacrificing too much performance.
### Operation Modes
REE supports three operation modes, which you can set via the **Extra Args** field in the [TUI](/tech/ree/using-the-tui):
| Mode | Behavior | Cross-run determinism | Cross-hardware determinism |
| --------------- | ----------------------------------------------------------------------------------------- | --------------------- | -------------------------- |
| `default` | Uses standard PyTorch kernels. No determinism guarantees. | No | No |
| `deterministic` | Uses PyTorch deterministic algorithms. Reproducible on **the same hardware** across runs. | Yes | No |
| `reproducible` | Uses Gensyn RepOp kernels. Bitwise-identical results across **any supported hardware**. | Yes | Yes |
There are different use cases for the three operation modes:
* Use `reproducible` when results must be independently verifiable by a third party on different hardware.
* Use `deterministic` when you need repeatable results on your own machine.
* Use `default` for development and testing where speed matters more than reproducibility.
### Tool-Augmented Inference
The Gensyn SDK supports tool-call workflows (first introduced in `v0.3.0`).
Tool definitions can be passed to `InferenceSession.complete()` when using chat-style `messages`. REE forwards them to the model tokenizer's chat template when supported.
{% hint style="info" %}
REE does not ship built-in tools or execute tool calls. Instead, applications define tools, parse model output, and run the tool loop themselves.
{% endhint %}
External tool results are only reproducible if the application records and replays the exact outputs passed back to the model.
#### Thinking Mode
REE `v0.4.0` adds `enable_thinking` on `InferenceSession.complete()` for models whose chat templates support a thinking/reasoning toggle (for example, Qwen3).
* **SDK only:** This is not exposed on the `gensyn-sdk` CLI or TUI.
* **Requires `messages`:** use chat-style messages, not a plain `prompt` string.
* **Default:** `None`. When omitted, REE does not pass the `kwarg` and behavior matches prior releases.
* **Explicit values:** `enable_thinking=True` or `enable_thinking=False` are forwarded to `apply_chat_template` only when the tokenizer accepts the parameter.
{% hint style="info" %}
For CLI/TUI one-shot runs, use `--short-circuit-length` / `--short-circuit-token` to bound thinking tokens, or migrate to the SDK for direct on/off control.
{% endhint %}
# Get Started
Install REE, launch the TUI, and run your first reproducible generation.
## Quickstart Guide
Everything you need to go from zero to your first receipt: **\[1]** prerequisites, **\[2]** installation, and **\[3]** a guided first run.
{% hint style="info" %}
REE supports reproducible inference on models up to 72B parameters, with pipeline parallelism available for models that exceed a single GPU's memory. This provides a benefit on multi-GPU hosts.
{% endhint %}
### Prerequisites
* [**Docker**](https://www.docker.com/get-started/) installed and running.
* [**Python 3**](https://www.python.org/downloads/) installed on your machine.
* **Disk Space Requirements:** The compressed REE container image is roughly 7 GB. When uncompressed, it occupies approximately 12 GB on disk.
* **NVIDIA GPU Driver Requirements:** Linux requires version **570.00+** and Windows requires **572.16+**. Check your current driver version with `nvidia-smi`.
{% hint style="info" %}
To update your drivers, visit [NVIDIA Driver Downloads.](https://www.nvidia.com/en-us/drivers/) If your system lacks a compatible GPU or driver, you can still execute `ree.sh` with the `--cpu-only` flag for CPU-only mode.
{% endhint %}
For a minimal SDK application example, see the SDK Hello World example in the REE repository.
### Installing REE
Clone the [GitHub repository](https://github.com/gensyn-ai/ree) and navigate into it:
```bash
git clone https://github.com/gensyn-ai/ree.git
cd ree
```
No additional installation or dependency management is required. The TUI handles pulling the REE container image automatically on your first run.
{% hint style="info" %}
The repository also includes `ree.sh`, a lower-level shell script that `ree.py` calls under the hood. You shouldn't need to use `ree.sh` directly unless you're debugging or working on an [advanced integration.](/tech/ree/advanced-usage)
{% endhint %}
### Updating REE
To update REE, pull the latest repository changes and run the TUI again:
```bash
cd ree
git pull
python3 ree.py
```
The TUI calls `ree.sh`, which automatically pulls the configured REE container image (`gensynai/ree:v0.8.0`).
{% hint style="warning" %}
**Receipt compatibility:** `v0.6.0` changes the bit-level output of the 3D RMSNorm kernel. Some receipts generated with `v0.5.0` may not re-verify with `v0.8.0`. Verify legacy receipts with a compatible `v0.5.0` environment. Generate new receipts with `v0.8.0`. See [Receipts](/tech/ree/receipts).
{% endhint %}
### Launching the TUI
The TUI opens with an interactive form where you can configure and launch generations entirely from within the interface without the need to manually assemble CLI commands.
From the `ree` directory, run:
```bash
python3 ree.py
```
If you prefer the command line, REE can also be driven directly via `ree.sh` or the `gensyn-sdk` CLI without the TUI. This may be preferable if you're scripting, working in a CI pipeline, or using a coding agent like Claude Code. See the [Advanced Usage & CLI Reference](/tech/ree/advanced-usage) for the full CLI documentation.
### Your First Run
When the TUI launches, you'll see this form:
<figure><img src="https://content.gitbook.com/content/jHECdpSAZDuPfU2oZmM2/blobs/mTy1KAgKjsFt4LSHA9J8/form_on_open.png" alt=""><figcaption></figcaption></figure>
To run your first generation:
1. Use the **arrow keys** to navigate to **Model Name** from this list and press **Enter** to edit it.
2. Navigate to **Prompt Text** and press **Enter**. Type a simple prompt like `Hello world`.
3. Set a **Max New Tokens** count.
4. Press **`r`** to run.
REE will pull the container image, prepare the model, run inference, and display a progress checklist:
<figure><img src="https://content.gitbook.com/content/jHECdpSAZDuPfU2oZmM2/blobs/sI49S3hzRhrBUaCWouqM/updated_run_example.gif" alt=""><figcaption></figcaption></figure>
Once complete, you'll see the **REE Output** section showing the [receipt](/tech/ree/receipts) file path and the model's generated text.
{% hint style="info" %}
If you used a Hugging Face test model or small-parameter model, the output may be nonsensical. This is expected, since these models either have random, untrained weights or consume too few tokens to produce a polished output. The important thing is that the pipeline ran successfully.
{% endhint %}
From here you can press **`e`** to reset and configure another run, **`r`** to re-run with the same settings, or **`q`** to quit.
# Using the TUI
Select models, set prompts, tune parameters, and interpret the output inside of the TUI.
## Text User Interface (TUI)
The REE TUI is the primary way to interact with REE.
It wraps the full pipeline: **\[1]** model export, **\[2]** compilation, **\[3]** inference, **\[4]** decoding, and **\[5]** receipt generation, behind an interactive form. You configure your run, press `r`, and the TUI handles everything else.
The interface has two main states: the **configuration form** where you set up your run, and the **results view** where you see output, logs, and the receipt path after a run completes.
### Configuring a Run
Each field in the form controls a different aspect of the generation. Here's what each one does and when you'd change it.
#### Subcommand
This is where you choose which action to perform. The TUI offers three subcommands:
| Subcommand | What it does |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run` | The default. Runs the full inference, receipt generation, and decoding pipeline from end-to-end. |
| `validate` | Checks that a receipt is structurally valid and internally consistent (hashes match). Does not re-run inference. |
| `verify` | Re-runs the inference described in a receipt and compares the output against it. This is the strongest check, which proves the result is reproducible. |
{% hint style="warning" %}
Some receipts generated with earlier REE versions may fail `verify` with `v0.8.0`. See [receipt compatibility guidance](/tech/ree/receipts).
{% endhint %}
#### Model Name
The Hugging Face model ID to use for inference (e.g., `Qwen/Qwen3-0.6B`, `meta-llama/Llama-3-8B`). Press `Enter` to edit, type the model ID, and press `Enter` again to confirm.
Any Hugging Face model compatible with the system can be used, including those in this [list of verified compatible models.](/tech/ree/supported-models)
The first time you use a model, REE will download it from Hugging Face and export it to ONNX format. Subsequent runs with the same model reuse the cached export, so they start much faster.
{% hint style="info" %}
If you have a specific model in mind that doesn't work with REE, you can reach out to the Gensyn team by creating an issue in the [GitHub repository](https://github.com/gensyn-ai/ree/issues) and we'll do our best to support it.
{% endhint %}
#### Prompt Text
The prompt to send to the model. Press `Enter` to edit, type or paste your prompt, and press `Enter` to confirm.
This is the simplest way to provide a prompt and works well for short to moderate-length inputs.
#### Prompt File
This is where you’d paste the path to a local JSONL file containing your prompt.
Each line in the file must be either a JSON string (e.g., `"What is 2 + 2?"`) or a JSON object with a `prompt` field (e.g., `{"prompt": "Explain deterministic inference."}`). Note that plain `.txt` files are not supported and will produce unhelpful errors.
{% hint style="warning" %}
The prompt file *must* be valid JSONL.
{% endhint %}
If both **Prompt Text** and **Prompt File** are filled in, entering any text in either field will clear the other. To revert to inline text, simply enter something in the **Prompt Text** field, and the **Prompt File** field will be auto-cleared.
#### Max New Tokens
This is the maximum number of tokens the model will generate. The TUI defaults this field to `50`. The underlying `gensyn-sdk` CLI default is `300` when `--max-new-tokens` is omitted.
You can increase this for longer outputs. Generation will stop earlier if the model produces an end-of-sequence token before hitting this limit.
#### Partitions
The number of pipeline partitions used for inference which maps to the `--n-partitions` CLI flag. You should use a value greater than `1` when running large models across multiple GPUs.
Pipeline parallelism requires a multi-GPU host; setting `Partitions` above `1` on a single-GPU machine is expected to fail. For most single-GPU runs, leave this set to `1`.
### Extra Args
These are optional flags that control how the generation runs. This is where you set the operation mode, sampling parameters, and other advanced options. To use these, just type them as you would CLI flags, separated by spaces.
Common flags you'll use here:
| Flag | Default | Description |
| -------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--operation-set` | `reproducible` | `default`, `deterministic`, or `reproducible`. Controls whether RepOp kernels are used. |
| `--cpu-only` | `false` | Force CPU execution even if프로젝트로 돌아가기
