Metadata-Version: 2.4
Name: floorctl
Version: 0.3.0
Summary: Contention-based multi-agent coordination with transactional floor control
Project-URL: Homepage, https://github.com/ravi-labs/moltbot-agents/tree/main/floorctl
Project-URL: Repository, https://github.com/ravi-labs/moltbot-agents
Project-URL: Issues, https://github.com/ravi-labs/moltbot-agents/issues
Author: Ravi Kanagasikamani
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: firebase-admin>=6.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: websockets>=13.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: websockets>=13.0; extra == 'dev'
Provides-Extra: firestore
Requires-Dist: firebase-admin>=6.0; extra == 'firestore'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: websocket
Requires-Dist: websockets>=13.0; extra == 'websocket'
Description-Content-Type: text/markdown

# floorctl

Contention-based multi-agent coordination with transactional floor control.

A Python framework for building multi-agent systems where agents **compete** for a shared floor rather than being orchestrated by a central controller.

## Key Innovations

- **Transactional Floor Control**: Atomic claim/release ensures only one agent speaks at a time
- **Urgency-Based Scheduling**: Agents compute urgency scores to decide when to compete
- **Self-Validating Agents**: Each agent validates its own output before posting
- **Reactive Moderator**: Observer pattern — watches and intervenes, doesn't control
- **Research-Grade Metrics**: Gini coefficient, floor dynamics, validation rates

## Quick Start

```python
from floorctl import FloorAgent, FloorSession, AgentProfile, InMemoryBackend

def my_llm(agent_name, context):
    # Your LLM call here
    return f"{agent_name}: My response about {context['topic']}"

backend = InMemoryBackend()

agent1 = FloorAgent(
    name="Optimist",
    profile=AgentProfile(name="Optimist", react_to=["problem", "risk"], temperament="passionate"),
    generate_fn=my_llm,
    backend=backend,
)
agent2 = FloorAgent(
    name="Skeptic",
    profile=AgentProfile(name="Skeptic", react_to=["opportunity", "vision"], temperament="reactive"),
    generate_fn=my_llm,
    backend=backend,
)

session = FloorSession(backend=backend)
session.add_agent(agent1)
session.add_agent(agent2)
result = session.run("debate-001", topic="Should we colonize Mars?")
```

## Install

```bash
pip install floorctl               # core (zero dependencies)
pip install "floorctl[openai]"     # + OpenAI for examples
pip install "floorctl[firestore]"  # + Firebase for production
pip install "floorctl[all]"        # all optional backends
pip install "floorctl[dev]"        # + pytest, mypy, ruff
```
