floorctl 0.3.0__py3-none-any.whl

floorctl/__init__.py

@@ -0,0 +1,187 @@
+"""
+floorctl — Contention-based multi-agent coordination with transactional floor control.
+
+A framework for building multi-agent systems where agents compete for a shared
+floor, self-validate their outputs, and are observed by a reactive moderator.
+
+New in v0.2: Artifacts, Consensus, and Conviction primitives for
+structured collaboration, formal decision-making, and position tracking.
+
+Usage:
+    from floorctl import FloorAgent, FloorSession, AgentProfile, InMemoryBackend
+
+    agent = FloorAgent(name="Alpha", profile=AgentProfile(...), generate_fn=..., backend=...)
+    session = FloorSession(backend=InMemoryBackend())
+    session.add_agent(agent)
+    result = session.run("session-001", topic="...")
+"""
+
+from floorctl.agent import FloorAgent
+from floorctl.moderator import (
+    ModeratorObserver,
+    InterventionDetector,
+    InterventionResult,
+    EscalationDetector,
+    DominanceDetector,
+    SilenceDetector,
+)
+from floorctl.session import FloorSession
+from floorctl.state import ConversationState, AgentMemory
+from floorctl.config import (
+    ArenaConfig,
+    AgentProfile,
+    StyleContract,
+    PhaseConfig,
+    PhaseSequence,
+    FloorConfig,
+    ModeratorConfig,
+    ConsensusConfig,
+    ConvictionConfig,
+)
+from floorctl.urgency import UrgencyScorer, UrgencyResult
+from floorctl.types import (
+    TurnRecord,
+    TurnData,
+    SessionResult,
+    SessionStatus,
+    Temperament,
+    ValidationResult,
+    FloorEvent,
+    GenerateFn,
+    ModeratorFn,
+)
+from floorctl.transcript import export_transcript
+from floorctl.validators import (
+    Validator,
+    run_validators,
+    SpeakerPrefixValidator,
+    DuplicateValidator,
+    LengthValidator,
+    BannedPhraseValidator,
+    StyleContractValidator,
+    PhaseValidator,
+)
+from floorctl.metrics import AgentMetrics, SessionMetrics
+from floorctl.backends.memory import InMemoryBackend
+
+# Optional distributed backends
+try:
+    from floorctl.backends.websocket import WebSocketBackend
+except ImportError:
+    WebSocketBackend = None  # type: ignore[assignment,misc]
+
+try:
+    from floorctl.backends.firestore import FirestoreBackend
+except ImportError:
+    FirestoreBackend = None  # type: ignore[assignment,misc]
+
+from floorctl.floor import FloorController
+from floorctl.phases import PhaseManager
+
+# New primitives (v0.2)
+from floorctl.artifacts import (
+    ArtifactStore,
+    Artifact,
+    ArtifactVersion,
+    ArtifactType,
+    ArtifactStatus,
+)
+from floorctl.consensus import (
+    ConsensusProtocol,
+    Proposal,
+    Vote,
+    ConsensusResult,
+    QuorumRule,
+    VoteChoice,
+    ProposalStatus,
+)
+from floorctl.conviction import (
+    ConvictionTracker,
+    EvidenceEvent,
+    EvidenceType,
+    DriftDirection,
+    PositionState,
+    ConvictionSnapshot,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    # Core
+    "FloorAgent",
+    "FloorSession",
+    "ModeratorObserver",
+    # Config
+    "ArenaConfig",
+    "AgentProfile",
+    "StyleContract",
+    "PhaseConfig",
+    "PhaseSequence",
+    "FloorConfig",
+    "ModeratorConfig",
+    "ConsensusConfig",
+    "ConvictionConfig",
+    # State
+    "ConversationState",
+    "AgentMemory",
+    # Urgency
+    "UrgencyScorer",
+    "UrgencyResult",
+    # Validators
+    "Validator",
+    "run_validators",
+    "SpeakerPrefixValidator",
+    "DuplicateValidator",
+    "LengthValidator",
+    "BannedPhraseValidator",
+    "StyleContractValidator",
+    "PhaseValidator",
+    # Metrics
+    "AgentMetrics",
+    "SessionMetrics",
+    # Backends
+    "InMemoryBackend",
+    "WebSocketBackend",
+    "FirestoreBackend",
+    # Types
+    "TurnRecord",
+    "TurnData",
+    "SessionResult",
+    "SessionStatus",
+    "Temperament",
+    "ValidationResult",
+    "FloorEvent",
+    "GenerateFn",
+    "ModeratorFn",
+    # Transcript Export
+    "export_transcript",
+    # Artifacts (v0.2)
+    "ArtifactStore",
+    "Artifact",
+    "ArtifactVersion",
+    "ArtifactType",
+    "ArtifactStatus",
+    # Consensus (v0.2)
+    "ConsensusProtocol",
+    "Proposal",
+    "Vote",
+    "ConsensusResult",
+    "QuorumRule",
+    "VoteChoice",
+    "ProposalStatus",
+    # Conviction (v0.2)
+    "ConvictionTracker",
+    "EvidenceEvent",
+    "EvidenceType",
+    "DriftDirection",
+    "PositionState",
+    "ConvictionSnapshot",
+    # Internals (for advanced usage)
+    "FloorController",
+    "PhaseManager",
+    "InterventionDetector",
+    "InterventionResult",
+    "EscalationDetector",
+    "DominanceDetector",
+    "SilenceDetector",
+]

floorctl/agent.py

@@ -0,0 +1,423 @@
+"""
+FloorAgent — the active agent SDK for contention-based coordination.
+
+Extracted from Sangam's CouncilSDK. Agents independently:
+1. Watch the transcript for new turns
+2. Compute urgency to decide whether to speak
+3. Compete for the floor via atomic claims
+4. Generate responses via user-provided LLM function
+5. Self-validate before posting
+6. Release the floor
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import threading
+from datetime import datetime, timezone
+from typing import Any
+
+from floorctl.backends.base import Backend
+from floorctl.config import AgentProfile, ArenaConfig, PhaseConfig, StyleContract
+from floorctl.floor import FloorController
+from floorctl.metrics import AgentMetrics
+from floorctl.state import ConversationState
+from floorctl.types import GenerateFn, TurnData, TurnRecord, UrgencyResult
+from floorctl.urgency import UrgencyScorer
+from floorctl.validators import Validator, run_validators, strip_speaker_prefix
+
+logger = logging.getLogger("floorctl.agent")
+
+
+class FloorAgent:
+    """
+    Active agent that independently watches, decides, generates, and posts.
+
+    Usage:
+        agent = FloorAgent(name="Alpha", profile=..., generate_fn=..., backend=...)
+        agent.listen_and_react(session_id)  # blocks until session ends
+    """
+
+    def __init__(
+        self,
+        name: str,
+        profile: AgentProfile,
+        generate_fn: GenerateFn,
+        backend: Backend,
+        validators: list[Validator] | None = None,
+        config: ArenaConfig | None = None,
+    ) -> None:
+        self.name = name
+        self.profile = profile
+        self.generate_fn = generate_fn
+        self.backend = backend
+        self.validators = validators or []
+        self.config = config or ArenaConfig()
+
+        # Internal state
+        self.state = ConversationState()
+        self._session_id: str = ""
+        self._speaking = False
+        self._is_running = False
+        self._gave_opening = False
+        self._my_turns_this_phase: dict[str, int] = {}
+        self._last_posted_turn_index = -10
+        self._stop_event = threading.Event()
+
+        # Core engines
+        self.urgency_scorer = UrgencyScorer()
+        self.floor_ctrl = FloorController(
+            agent_name=name,
+            backend=backend,
+            config=self.config.floor,
+        )
+
+        # Metrics
+        self.metrics: AgentMetrics | None = None
+
+        # Agent names in session (for validators)
+        self._agent_names: list[str] = []
+
+    def join_session(self, session_id: str) -> None:
+        """Register this agent in the session."""
+        self._session_id = session_id
+        session_state = self.backend.get_session_state(session_id)
+        self.state.topic = session_state.get("topic", "")
+        self.state.phase = session_state.get("phase", "")
+        self._agent_names = session_state.get("participants", [])
+        self.metrics = AgentMetrics(self.name, session_id)
+
+    def listen_and_react(self, session_id: str) -> None:
+        """
+        Block: watch transcript, compute urgency, compete for floor, speak.
+        Returns when session ends or stop() is called.
+        """
+        self._session_id = session_id
+        self._is_running = True
+        self._stop_event.clear()
+
+        if not self.metrics:
+            self.metrics = AgentMetrics(self.name, session_id)
+
+        # Load existing turns
+        existing_turns = self.backend.get_turns(session_id)
+        for turn in existing_turns:
+            self.state.add_turn(turn.speaker, turn.text, turn.is_moderator)
+
+        # Subscribe to new turns
+        unsub_turns = self.backend.subscribe_turns(session_id, self._on_new_turn)
+
+        # Subscribe to session changes (phase updates, floor signals)
+        unsub_session = self.backend.subscribe_session(session_id, self._on_session_update)
+
+        logger.info(f"[{self.name}] Listening on session {session_id}")
+
+        # Block until stopped
+        self._stop_event.wait()
+
+        unsub_turns()
+        unsub_session()
+        self._is_running = False
+        logger.info(f"[{self.name}] Stopped listening")
+
+    def stop(self) -> None:
+        """Signal the agent to stop listening."""
+        self._stop_event.set()
+        self.floor_ctrl.cancel_retry()
+
+    # ── Callbacks ────────────────────────────────────────────────────
+
+    def _on_new_turn(self, turn: TurnRecord) -> None:
+        """Called when a new turn appears in the transcript."""
+        # Record in local state
+        self.state.add_turn(turn.speaker, turn.text, turn.is_moderator)
+
+        # Don't react to our own turns
+        if turn.speaker == self.name:
+            return
+
+        # Don't react if we're currently speaking
+        if self._speaking:
+            return
+
+        # Check session status
+        session_state = self.backend.get_session_state(self._session_id)
+        if session_state.get("status") == "COMPLETED":
+            self.stop()
+            return
+
+        # Update phase from session
+        new_phase = session_state.get("phase", self.state.phase)
+        if new_phase != self.state.phase:
+            self.state.phase = new_phase
+            self.state.reset_phase_count()
+
+        # Check if we should speak
+        self._try_speak(turn)
+
+    def _on_session_update(self, state: dict[str, Any]) -> None:
+        """Called when session-level state changes."""
+        new_phase = state.get("phase", "")
+        if new_phase and new_phase != self.state.phase:
+            logger.info(f"[{self.name}] Phase changed: {self.state.phase} → {new_phase}")
+            self.state.phase = new_phase
+            self.state.reset_phase_count()
+
+        if state.get("status") == "COMPLETED":
+            self.stop()
+
+        # Floor recovery signal
+        if (state.get("floor_released_without_post")
+                and state.get("floor_released_by") != self.name):
+            if self.metrics:
+                self.metrics.record_floor_retry(executed=True)
+
+    # ── Core Turn Logic ──────────────────────────────────────────────
+
+    def _try_speak(self, last_turn: TurnRecord) -> None:
+        """Decide whether to compete for floor and speak."""
+        # Skip terminal phases
+        phase_config = self.config.phases.get(self.state.phase)
+        if phase_config and phase_config.is_terminal:
+            return
+
+        # Check per-phase turn cap
+        my_phase_turns = self.state.agent_turns_in_phase(self.name)
+        if my_phase_turns >= self.config.floor.max_turns_per_phase_per_agent:
+            return
+
+        # Check min turns between speaking
+        turns_since = self.state.turns_since_agent_spoke(self.name)
+        if turns_since < self.config.floor.min_turns_between_speaking:
+            return
+
+        # Compute urgency
+        threshold_adj = self.floor_ctrl.starvation_threshold_reduction()
+        urgency_result = self.urgency_scorer.compute(
+            agent_name=self.name,
+            last_text=last_turn.text,
+            last_speaker=last_turn.speaker,
+            is_moderator=last_turn.is_moderator,
+            state=self.state,
+            profile=self.profile,
+            threshold_adjustment=threshold_adj,
+        )
+
+        # Record metrics
+        if self.metrics:
+            self.metrics.record_urgency(
+                urgency=urgency_result.score,
+                threshold=urgency_result.threshold,
+                triggered_by=urgency_result.triggered_by,
+                phase=self.state.phase,
+                above_threshold=urgency_result.above_threshold,
+                components=urgency_result.components,
+            )
+
+        if not urgency_result.above_threshold:
+            return
+
+        logger.debug(
+            f"[{self.name}] Urgency {urgency_result.score:.3f} > "
+            f"{urgency_result.threshold:.3f} — claiming floor"
+        )
+
+        # Try to claim the floor
+        claimed = self.floor_ctrl.try_claim(self._session_id)
+        if self.metrics:
+            self.metrics.record_floor_claim(success=claimed)
+            self.metrics.record_floor_event(
+                success=claimed, is_retry=False,
+                urgency=urgency_result.score,
+                threshold=urgency_result.threshold,
+                phase=self.state.phase,
+            )
+
+        if not claimed:
+            # Schedule retry
+            if self.metrics:
+                self.metrics.record_floor_retry(scheduled=True)
+            self.floor_ctrl.schedule_retry(
+                self._session_id,
+                lambda: self._retry_claim(),
+                phase_turns=my_phase_turns,
+            )
+            return
+
+        # We have the floor — generate and post
+        self._speaking = True
+        claim_time = time.time()
+
+        try:
+            response = self._generate_response()
+            if response:
+                self._post_turn(response)
+                if self.metrics:
+                    hold_time = time.time() - claim_time
+                    self.metrics.record_floor_hold_time(hold_time)
+                    self.metrics.record_floor_release(posted_successfully=True)
+                    self.metrics.record_silence_duration(turns_since)
+                self.floor_ctrl.release(self._session_id, posted_successfully=True)
+            else:
+                # Validation failed after retries
+                if self.metrics:
+                    self.metrics.record_floor_release(posted_successfully=False)
+                self.floor_ctrl.release(self._session_id, posted_successfully=False)
+        except Exception as e:
+            logger.error(f"[{self.name}] Error during generation: {e}")
+            self.floor_ctrl.release(self._session_id, posted_successfully=False)
+        finally:
+            self._speaking = False
+
+    def _retry_claim(self) -> None:
+        """Retry floor claim after delay."""
+        if not self._is_running or self._speaking:
+            return
+
+        claimed = self.floor_ctrl.try_claim(self._session_id)
+        if self.metrics:
+            self.metrics.record_floor_retry(executed=True)
+            self.metrics.record_floor_claim(success=claimed)
+            self.metrics.record_floor_event(
+                success=claimed, is_retry=True,
+                phase=self.state.phase,
+            )
+
+        if claimed:
+            if self.metrics:
+                self.metrics.record_floor_retry(succeeded=True)
+            self._speaking = True
+            claim_time = time.time()
+            try:
+                response = self._generate_response()
+                if response:
+                    self._post_turn(response)
+                    if self.metrics:
+                        self.metrics.record_floor_hold_time(time.time() - claim_time)
+                        self.metrics.record_floor_release(posted_successfully=True)
+                    self.floor_ctrl.release(self._session_id, posted_successfully=True)
+                else:
+                    self.floor_ctrl.release(self._session_id, posted_successfully=False)
+            except Exception as e:
+                logger.error(f"[{self.name}] Retry error: {e}")
+                self.floor_ctrl.release(self._session_id, posted_successfully=False)
+            finally:
+                self._speaking = False
+
+    # ── Generation + Validation ──────────────────────────────────────
+
+    def _generate_response(self) -> str | None:
+        """Generate a response with self-validation and retry loop."""
+        phase_config = self.config.phases.get(self.state.phase)
+        style_contract = self.profile.style_contract
+
+        context = self._build_context()
+        retries = 0
+        last_failures: list[str] = []
+
+        for attempt in range(1 + self.config.max_self_retries):
+            if attempt > 0:
+                context["retry_failures"] = last_failures
+                context["retry_attempt"] = attempt
+
+            gen_start = time.time()
+            try:
+                draft = self.generate_fn(self.name, context)
+            except Exception as e:
+                logger.error(f"[{self.name}] Generate failed: {e}")
+                if self.metrics:
+                    self.metrics.record_generation_time(time.time() - gen_start)
+                continue
+            gen_time = time.time() - gen_start
+
+            if self.metrics:
+                self.metrics.record_generation_time(gen_time)
+
+            # Run validators
+            if self.validators:
+                passed, failures = run_validators(
+                    draft, self.name, self.state,
+                    validators=self.validators,
+                    style_contract=style_contract,
+                    phase_config=phase_config,
+                    agent_names=self._agent_names,
+                )
+                if self.metrics:
+                    failure_names = [f.split("]")[0].strip("[") for f in failures]
+                    self.metrics.record_validation(passed, failure_names)
+
+                if not passed:
+                    logger.debug(
+                        f"[{self.name}] Validation failed (attempt {attempt + 1}): "
+                        + "; ".join(failures)
+                    )
+                    last_failures = failures
+                    retries += 1
+                    continue
+
+            # Passed validation (or no validators)
+            if self.metrics:
+                self.metrics.record_retries_for_turn(retries)
+            return draft
+
+        logger.warning(
+            f"[{self.name}] All {self.config.max_self_retries + 1} attempts failed"
+        )
+        return None
+
+    def _build_context(self) -> dict[str, Any]:
+        """Build the context dict passed to the user's generate_fn."""
+        phase_config = self.config.phases.get(self.state.phase)
+        mem = self.state.ensure_agent_memory(self.name)
+
+        context: dict[str, Any] = {
+            "topic": self.state.topic,
+            "phase": self.state.phase,
+            "agent_name": self.name,
+            "personality": self.profile.personality,
+            "rolling_summary": self.state.rolling_summary,
+            "recent_turns": self.state.get_last_n_turns_text(self.config.context_window_turns),
+            "open_threads": self.state.open_threads,
+            "agent_memory": {
+                "last_points": mem.last_points[-5:],
+                "turns_spoken": mem.turns_spoken,
+            },
+            "all_agents": self._agent_names,
+            "turn_index": self.state.turn_index,
+        }
+
+        if self.profile.style_contract:
+            context["style_contract"] = self.profile.style_contract.description
+
+        if phase_config:
+            context["phase_constraints"] = phase_config.constraints
+            context["phase_max_words"] = phase_config.max_words
+            context["phase_min_words"] = phase_config.min_words
+
+        return context
+
+    def _post_turn(self, response: str) -> None:
+        """Post a validated response to the backend."""
+        turn = TurnData(
+            agent_name=self.name,
+            transcript=response,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            is_moderator=False,
+            turn_type=self.state.phase.lower(),
+        )
+        self.backend.post_turn(self._session_id, turn)
+
+        if self.metrics:
+            self.metrics.record_turn_posted(self.state.phase)
+
+        # Update local tracking
+        self._my_turns_this_phase[self.state.phase] = (
+            self._my_turns_this_phase.get(self.state.phase, 0) + 1
+        )
+        self._last_posted_turn_index = self.state.turn_index
+
+        logger.info(
+            f"[{self.name}] Posted turn in {self.state.phase} "
+            f"(turn #{self.state.turn_index})"
+        )