floorctl 0.3.1

Contention-based multi-agent coordination with transactional floor control

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

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

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