Metadata-Version: 2.4
Name: rsoslang
Version: 0.3.0
Summary: RSOS State Runtime and Language: multi-agent workflows in 2 model calls instead of 42, with hash-checked shared state (MCP server included)
Author: r-a-elu-architecture
License-Expression: Apache-2.0
Project-URL: Homepage, https://r-a-elu-architecture.github.io/RSOS-Language/
Project-URL: Repository, https://github.com/r-a-elu-architecture/RSOS-Language
Project-URL: Results, https://r-a-elu-architecture.github.io/RSOS-Language/results.html
Keywords: mcp,multi-agent,agents,llm,state,langgraph,protocol
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: mcp>=1.10
Provides-Extra: experiments
Requires-Dist: tiktoken; extra == "experiments"
Requires-Dist: numpy; extra == "experiments"
Requires-Dist: networkx; extra == "experiments"
Dynamic: license-file

# RSOS Language

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24304403.svg)](https://doi.org/10.5281/zenodo.24304403) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![tests](https://github.com/r-a-elu-architecture/RSOS-Language/actions/workflows/tests.yml/badge.svg)](https://github.com/r-a-elu-architecture/RSOS-Language/actions/workflows/tests.yml)

*RSOS: an executable spatial-symbolic language for human–AI and AI–AI communication.* Whitepaper: R. A. Elu (2026),
[doi:10.5281/zenodo.24304403](https://doi.org/10.5281/zenodo.24304403) (all versions). Code: Apache 2.0. Software release 0.2.0:
[doi:10.5281/zenodo.24317658](https://doi.org/10.5281/zenodo.24317658).

## RSOS State Runtime: 2 model calls instead of 42

**For multi-agent workflows that edit shared state.** The model decides; the language executes. On real LLM agents
(pre-registered, every failure reported): a 14-step task in **2 model calls instead of 42**, **2.8–3.7× cheaper** than
the best setup built for the same agents at API prices, **8× faster**, **32/32 correct**, every injected drift healed
with **zero model calls**. When agents compute from their own copies, a Slipstream-style anchor protocol got **0 of
16** tasks right; RSOS stayed right.

```bash
pip install rsoslang                             # or, from a clone: pip install -e .
claude mcp add rsos -- rsoslang mcp              # or with no install: claude mcp add rsos -- uvx rsoslang mcp
python experiments/a5_runtime_equivalence.py     # from a clone: this runtime replays every measured plan, 32/32 match
```

**[Drop it in (Python or MCP) →](STATE.md)** · **[Replicate it, under $1 →](REPLICATE.md)** ·
**[All results, failures included →](https://r-a-elu-architecture.github.io/RSOS-Language/results.html)**

**A spatial-symbolic programming language for humans and AI.** You write a program the way you think it: objects in
a scene, placed, touched, pierced, entered, coloured, connected by lines, kept in the rooms of a house. The same
program runs in two places:
- in a **machine**: an AI agent workflow, a simulation;
- in a **person**: a practised mental model, delivered as a timed session of images, words, sounds, scents and
  vibration codes.

**[Open the editor →](docs/editor.html)** A real 12-module support agent, painted. Put a guest at the head, heart,
brain or beside a module, and see the measured effect.

**Results (17 Nov 2026, pre-registered, real LLM agents; whitepaper v2: [doi:10.5281/zenodo.24320392](https://doi.org/10.5281/zenodo.24320392)):**
a protocol designed by the RSOS White Dragon engine (A3b) used 0.55× the BPE channel tokens of a Slipstream-style
anchor protocol while keeping every copy of the shared state true in 16/16 tasks (anchor protocol 0/16) and healing
every injected drift without a model call. The White Dragon also redesigned a weak agent system, cutting errors by
63% (A2). Of 27 predictions on real hosts, 18 passed and 9 failed; all are reported.

**First real-host test (A1, 17 Nov 2026, pre-registered):** three LLM agents (planner, worker, checker) on 8 tasks. The RSOS palace protocol used about 7× fewer channel tokens than JSON with full state (2,563 vs 17,311), finished 7/8 tasks exactly correct (JSON 5/8), and caught and healed 24/24 injected drifts with 0 model calls (38 tokens per repair). Summaries + retrieval: 0/8 correct, 24/24 drifts kept. One model family, 8 tasks. Report: [`experiments/A1_REPORT.md`](experiments/A1_REPORT.md).

## Purpose

RSOS grew from one seed: healing, transforming, signalling and evolving. It integrates the whole of human
experience, including its shadow, so that what is integrated can be transformed rather than denied. Because its seed
is healing, RSOS is used with consent and for the good of the person or system it works with, never to harm or
coerce. See [`RESPONSIBLE_USE.md`](RESPONSIBLE_USE.md),
[`GOVERNANCE.md`](GOVERNANCE.md), [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`TRADEMARKS.md`](TRADEMARKS.md).

## What makes it different

- **Where you place an operator decides what it does.** The same spell corrector placed at a module's head, heart,
  brain or beside it gives four different results, measured on held-out data.
- **Meanings in three tiers.**
  - a fixed core, shared by everyone;
  - declared variations, scoped to a person, host, world or state;
  - meanings left open on purpose, found by search.

  Nothing changes silently.
- **The host decides.** Every operation runs on a declared host with its own channels and states. A cue on a channel
  the host does not have is an error.
- **Safety is in the compiler.** Person-facing operations need consent and pass a constitution of seven checks;
  return to baseline is always available.
- **Every result is reproducible.** Pre-registered experiments, seeds, result hashes; negatives published with
  positives.

## Quick start

```bash
pip install -e .
python -m rsoslang check examples/robot_head.rsl
python -m rsoslang ir examples/sol_remote.rsl
RSOS_CUE_FRAMEWORK=/path/to/RSOS-Multimodal-Cue-Framework python -m rsoslang session examples/healing.rsl
./reproduce.sh
```

## Use it from Claude or any MCP assistant

```json
{"mcpServers": {"rsos-language": {"command": "python", "args": ["-m", "rsoslang.mcp_server"],
  "env": {"RSOS_CUE_FRAMEWORK": "/path/to/RSOS-Multimodal-Cue-Framework"}}}}
```

The tools are `rsos_statements`, `rsos_check`, `rsos_compile`, `rsos_session`, `rsos_paint_workflow`,
`rsos_apply_gestures` and `rsos_paint_graph`.

## Results

See `results/BUILD_REPORT.md`. It covers every pre-registered test, the ones that failed included.

## Licence

Apache 2.0. Research and development software; not a medical device.

<!-- mcp-name: io.github.r-a-elu-architecture/rsos -->
