A secure, local-first multi-agent orchestration framework.

Overview

Rooms is a robust, highly-configurable framework designed for testing, simulating, and orchestrating multiple AI agents in structured conversation spaces. Built with a local-first philosophy, it leverages LiteLLM to securely route requests to local models (like Ollama) or commercial APIs without data leakage.

Tip

Extensibility: Rooms natively supports dropping in your own custom Python inference functions. You aren't limited to standard LLM endpoints.

Key Features

• Local Priority Integration: Zero-leakage API routing via litellm. Seamlessly integrates with local offline instances.
• Dynamic Turn Orchestration: Agents interact via round_robin, argumentative, or dynamic relevance-based conversational flows.
• Expertise-Weighted Selection: In dynamic mode, agents are scored against the live topic context — the most relevant expert speaks next.
• User-Directed Addressing: Type @AgentName in any input to force a specific agent to respond next, bypassing automatic scoring.
• PASS Mechanic: Agents may respond with PASS if they have nothing meaningful to add, silently skipping their turn and keeping the flow clean.
• Deep Personas: Configure intricate agent backgrounds and behavioral instructions dynamically per session.
• Custom Architectures: Bypass standard LLMs entirely and plug in custom Python functions for specific agent inference.
• Human-In-The-Loop: Inject user instructions at defined intervals — or instantly when an agent directly addresses the user by name.
• User Profile & Identity: Name and background provided at session start; agents treat the user as an equal room participant.
• Global Orchestrator: A designated room moderator that fires every N turns to summarize or redirect agents, with no runaway loop risk.
• Timestamped Session Memory: All turns, messages, and system events are tagged with precise timestamps for full auditability.

Framework Capabilities

The framework allows extreme granularity in handling session configurations:

Capability	Scope	Notes
Generative Control	Per-Agent	Set temperature, max_tokens, timeout, and system prompts individually.
Logic Hooks	Runtime	Dynamically load native .py files to act as agents.
Data Preservation	Ephemeral	RAM-only by default. Prompted to export as Markdown or CSV on exit.
Session Memory	Full History	Timestamped history shared across all participants throughout the session.
User Identity	Per-Session	User name and background injected into room intro for agent awareness.
Expert Routing	Dynamic	Agents scored by expertise against live context — best fit speaks next.
Forced Addressing	On-Demand	@AgentName in any message forces that agent's next response.

Documentation Library

For deeper insights into how to leverage and modify the framework, please refer to our dedicated documentation guides:

• Architecture & LiteLLM Guide - Understand how local API routing, session memory, and agent selection work.
• Use Cases, Examples & Best Practices - Parameter cheat sheet, deep persona guide, scenario walkthroughs, and an edge case reference table.
• Testing Strategy - How to write and run deterministic tests for multi-agent logic.
• Contributing Guide - Learn how to contribute to the project, report bugs, and follow our design philosophy.

Project Structure

Rooms/
├── rooms/              # Core Package
│   ├── __init__.py
│   ├── config.py       # Pydantic Configuration Models
│   ├── agent.py        # Agent & LiteLLM/Custom Logic
│   ├── session.py      # Turn Orchestration & Memory
│   ├── settings.py     # YAML settings loader (#26, #27)
│   └── storage.py      # Secure Log Serialization
├── tests/              # Unit Tests
│   └── test_session.py # Logic Verification
├── outputs/            # Session Transcripts
├── cli.py                      # Interactive Wizard Entry Point
├── rooms.settings.example.yaml # Settings template (commit this)
├── requirements.txt            # Project Dependencies

rooms.settings.yaml is gitignored — create it locally with python cli.py config init or by copying the example file.

Quick Start

1. Installation

# Clone the repository
git clone https://github.com/arpahls/Rooms.git
cd Rooms

# Setup Environment
python -m venv venv
venv\Scripts\activate  # Windows: venv\Scripts\activate | Unix: source venv/bin/activate

# Install Dependencies
pip install -r requirements.txt

2. Configure defaults (optional)

You do not need a settings file to run the CLI — built-in defaults apply (see rooms.settings.example.yaml for the shape). To customize per machine, create a local file (gitignored):

File	In git?	Purpose
rooms.settings.example.yaml	Yes (template)	Committed reference; copy or use config init
rooms.settings.yaml	No (gitignored)	Your local overrides (model tag, user name, personas)

python cli.py config init    # copies example → rooms.settings.yaml in cwd
# Or manually: copy rooms.settings.example.yaml to rooms.settings.yaml
# Edit rooms.settings.yaml — e.g. defaults.litellm_model from `ollama list`
python cli.py config reset   # remove user file; revert to shipped defaults
python cli.py --config path/to/settings.yaml

3. Usage

Start the Interactive Wizard

python cli.py

The wizard will step you through:

• Setting your user profile (name and background)
• Defining the session topic and turn limits
• Inviting default or custom agents with individual temperatures and system prompts
• Optionally assigning a Global Orchestrator

During a session, type @AgentName in any user input to force a specific agent to respond next.

Run Tests

# Always run via pytest with PYTHONPATH set:
$env:PYTHONPATH="."; python -m pytest tests/ -v

License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap & Progress

Track our active progress on the GitHub Issues board.

_{Developed and Maintained by ARPA HELLENIC LOGICAL SYSTEMS
Support: systems@arpacorp.net}