floorctl 0.3.0__tar.gz

floorctl-0.3.0/.gitignore

@@ -0,0 +1,136 @@
+# =====================================================
+# Environment and secrets
+# =====================================================
+.env
+.env.*
+.env.local
+*.env
+secrets/
+*.pem
+*.key
+
+# =====================================================
+# Logs
+# =====================================================
+*.log
+audit.jsonl
+logs/
+
+# =====================================================
+# Python
+# =====================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+.venv/
+.virtualenv/
+*.egg-info/
+dist/
+build/
+eggs/
+*.egg
+*.whl
+pip-log.txt
+pip-delete-this-directory.txt
+
+# =====================================================
+# Testing and coverage
+# =====================================================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# =====================================================
+# Type checking
+# =====================================================
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# =====================================================
+# Jupyter
+# =====================================================
+.ipynb_checkpoints/
+
+# =====================================================
+# IDE and editors
+# =====================================================
+.idea/
+.vscode/
+.cursor/
+*.swp
+*.swo
+*~
+*.sublime-project
+*.sublime-workspace
+
+# =====================================================
+# OS generated
+# =====================================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# =====================================================
+# Node.js
+# =====================================================
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# =====================================================
+# Firebase
+# =====================================================
+serviceAccount*.json
+firebase-admin*.json
+firebase-credentials*.json
+.firebaserc
+firebase-debug.log
+firebase-debug.*.log
+firestore-debug.log
+ui-debug.log
+.firebase/
+
+# Firebase config with secrets (use .example instead)
+firebase_config.py
+!firebase_config.example.py
+
+# =====================================================
+# Project-specific runtime files
+# =====================================================
+*.jsonl
+agent_memory.json
+knowledge_bank.json
+discovery_cache.json
+social_network.json
+feelings_journal.json
+
+# Generated audio files
+90s-kid/web/public/audio/*.mp3
+90s-kid/web/public/audio/previews/*.mp3
+
+# Web app build output
+90s-kid/web/dist/
+
+# Admin config (contains admin emails)
+admin_config.json
+!admin_config.example.json

floorctl-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ravi Kanagasikamani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

floorctl-0.3.0/PKG-INFO

@@ -0,0 +1,89 @@
+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
+```

floorctl-0.3.0/README.md

@@ -0,0 +1,53 @@
+# 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
+```