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

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.

• 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.
• Optional Skillware Integration: Assign skills per agent, execute tools lazily, and keep user-facing replies natural.

The framework allows extreme granularity in handling session configurations:

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

• Architecture & LiteLLM Guide - Understand local API routing, session memory, orchestration, and tool logging.
• Use Cases, Examples & Best Practices - Parameter cheat sheet, deep persona guide, scenario walkthroughs, and an edge case reference table.
• Skillware Integration Guide - Skills CLI commands, wizard assignment flow, and optional dependency behavior.
• Testing Strategy - How to write and run deterministic tests for multi-agent and skills logic.
• Contributing Guide - Learn how to contribute to the project, report bugs, and follow our design philosophy.
• Project Changelog - Track all notable updates, fixes, and pre-release changes to the framework.

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
│   └── 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            # Core Project Dependencies
└── requirements-memory.txt     # Optional Vector Memory Dependencies

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

# 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 Core Dependencies
pip install -r requirements.txt

If you plan to use vector memory features, install the heavier machine learning dependencies separately:

pip install -r requirements-memory.txt

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):

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

API keys (cloud models only)

LiteLLM reads provider credentials from the process environment (not from YAML). For local development, copy .env.example to .env and set keys such as DEEPSEEK_API_KEY or OPENAI_API_KEY. Rooms loads .env automatically at startup (shell/CI env vars take precedence).

copy .env.example .env   # Windows
# edit .env with your provider key(s)

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 Skillware skills (and per-skill overrides) to custom agents
• Optionally assigning a Global Orchestrator

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

For skills-specific commands and usage, see docs/SKILLWARE.md.

Run Tests

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

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

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