Vers3Dynamics 🐙

Autonomous Acoustic Physics and Resonance Research Platform

Bridging autonomous AI agents with acoustic physics research through a unified Rust-first execution engine.

---

Mission

Vers3Dynamics R.A.I.N. Lab is an R&D platform for non-linear wave interactions and bio-acoustic phenomena.

The system combines:

• ZeroClaw (The Body): Rust agent runtime for orchestration, tools, channels, and policy enforcement.
• James Library (The Mind): Python research workflows for resonance, recursive meetings, and synthesis.

---

Architecture

graph TB
    subgraph "Vers3Dynamics Platform"
        subgraph "ZeroClaw - The Body"
            CLI[CLI and Gateway]
            Agent[Agent Orchestrator]
            Providers[Model Providers]
            Tools[Tool Execution]
            Memory[Memory System]
        end

        subgraph "James Library - The Mind"
            RLM[Recursive Lab Meeting]
            RainLab[rain_lab.py]
            Physics[Acoustic Physics]
            Research[Research Corpus]
            Godot[Godot Visualization]
        end
    end

    User((Researcher))
    External[External APIs]

    User --> CLI
    CLI --> Agent
    Agent --> Providers
    Agent --> Tools
    Agent --> Memory
    Tools --> RLM
    RLM --> RainLab
    RainLab --> Physics
    RainLab --> Research
    RainLab --> Godot
    Providers --> External

Loading

Component	Role	Technology
ZeroClaw	Autonomous runtime, tool orchestration, provider management	Rust
James Library	Research workflows, recursive reasoning, synthesis	Python
Godot Client	Multi-agent visual interface	GDScript

---

Quick Start

Prerequisites

• Rust 1.87+
• Python 3.10+
• Optional: Miniconda for Python env management

5-Minute LM Studio Path (Recommended)

Linux/macOS:

bash scripts/quickstart_lmstudio.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\quickstart_lmstudio.ps1

This path sets up a local virtual environment, installs dependencies, sets LM Studio defaults, and runs a health check.

Full Setup

git clone https://github.com/topherchris420/james_library.git
cd james_library

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

cargo build --release

Python Research Only

python rain_lab.py --mode first-run
python rain_lab.py --mode chat --topic "your research question"
python rain_lab.py --mode rlm --topic "acoustic resonance phenomena"

Windows Installer

1) Double-click INSTALL_RAIN.cmd
2) Wait for install to finish
3) Launch R.A.I.N. Lab Chat from Desktop or Start Menu

---

Download Binaries

If you do not want to build from source, download prebuilt binaries from:

• https://github.com/topherchris420/james_library/releases

Supported release targets and extraction steps are documented in:

• docs/BINARY_RELEASES.md

---

Project Structure

james_library/
|-- src/                      # ZeroClaw Rust source
|   |-- agent/
|   |-- channels/
|   |-- gateway/
|   |-- memory/
|   |-- providers/
|   |-- runtime/
|   `-- tools/
|-- tests/                    # Rust and Python tests
|-- benches/                  # Criterion benchmarks
|-- scripts/ci/               # CI guard scripts
|-- james_library/            # Python research modules
|-- rain_lab.py               # Main Python launcher
|-- config.example.toml       # Config template
|-- Cargo.toml                # Rust workspace manifest
`-- pyproject.toml            # Python lint/type/test config

---

Reliability Guardrails

• Repo integrity guard: scripts/ci/repo_integrity_guard.py
  • Fails if duplicate src/src tree appears.
  • Fails if embedded dashboard fallback is missing (build.rs or web/dist/index.html).
• Embedded dashboard fallback: build.rs auto-creates web/dist/index.html if frontend artifacts are absent.
• Gateway request-path hardening:
  • Reduced allocation pressure in static serving path.
  • Stricter asset path validation.
  • More efficient rate limiting and idempotency cleanup behavior.

---

Development

Python

pip install -r requirements-dev.txt
ruff check .
pytest -q

Rust

cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test
cargo check

Benchmarks

cargo bench --features benchmarks --bench agent_benchmarks

---

Godot Integration

python rain_lab.py --mode chat --ui auto --topic "your topic"
python rain_lab.py --mode chat --ui on --topic "your topic"

--ui auto starts avatars when Godot is available and falls back to CLI when not.

---

Documentation

• ARCHITECTURE.md
• PRODUCT_ROADMAP.md
• CONTRIBUTING.md
• SECURITY.md
• docs/PRODUCTION_READINESS.md
• docs/FIRST_RUN_CHECKLIST.md
• docs/BINARY_RELEASES.md

---

License

MIT License. See LICENSE.