Collaboration Engine¶

The collaboration module implements human-in-the-loop sessions with scoring, approval gates, and handoff protocols. CollaborationEngine (src/fcc/collaboration/engine.py:67) is the façade: it owns a session dictionary, an optional EventBus, and a ScoringEngine. Each CollaborationSession (src/fcc/collaboration/models.py:265) is a frozen aggregate over a sequence of SessionTurn records, a list of ApprovalGate definitions, a single HandoffProtocol, and a mutable SharedContext. The diagram below shows those aggregates plus the supporting enums (SessionStatus, TurnType, ApprovalDecision) and the QualityScore/AgentCapabilityRating records that the scoring engine produces.

The diagram below details the collaboration session aggregate and its scoring and gating peers.

classDiagram
    class SessionStatus {
        <<enumeration>>
        CREATED
        ACTIVE
        PAUSED
        COMPLETED
        ABORTED
    }

    class TurnType {
        <<enumeration>>
        HUMAN
        AGENT
        SYSTEM
    }

    class ApprovalDecision {
        <<enumeration>>
        APPROVED
        REJECTED
        NEEDS_REVISION
        DEFERRED
    }

    class CollaborationEngine {
        -_sessions : dict
        -_event_bus : EventBus
        -_scoring : ScoringEngine
        +create_session(workflow_id, participants, gates, handoff_protocol) CollaborationSession
        +snapshot(session_id)
    }

    class CollaborationSession {
        <<frozen dataclass>>
        +session_id : str
        +workflow_id : str
        +status : SessionStatus
        +participants : list[str]
        +shared_context : dict
        +created_at : datetime
        +updated_at : datetime
    }

    class SessionTurn {
        <<frozen dataclass>>
        +turn_id : str
        +turn_type : TurnType
        +actor : str
        +content : str
        +timestamp : datetime
    }

    class ApprovalGate {
        <<frozen dataclass>>
        +gate_id : str
        +workflow_node_id : str
        +required_score : float
        +requires_human : bool
        +rubric : dict
    }

    class QualityScore {
        <<frozen dataclass>>
        +score_id : str
        +deliverable_id : str
        +scorer : str
        +score : float
        +rubric_scores : dict
        +justification : str
        +timestamp : datetime
    }

    class HandoffProtocol {
        <<frozen dataclass>>
        +max_consecutive_agent_turns : int
        +auto_approve_threshold : float
        +escalation_threshold : float
    }

    class ScoringEngine {
        +score(deliverable, rubric) QualityScore
    }

    class SharedContext {
        +get(key)
        +set(key, value)
    }

    class AgentCapabilityRating {
        <<frozen dataclass>>
        +persona_id : str
        +total_approvals : int
        +total_rejections : int
        +avg_quality_score : float
        +total_evaluations : int
    }

    CollaborationEngine "1" *-- "0..*" CollaborationSession : _sessions
    CollaborationEngine "1" --> "1" ScoringEngine : _scoring
    CollaborationSession "1" --> "1" SessionStatus : status
    CollaborationSession "1" *-- "1..*" SessionTurn : turns
    CollaborationSession "1" *-- "1..*" ApprovalGate : gates
    CollaborationSession "1" *-- "1" HandoffProtocol : handoff_protocol
    CollaborationSession "1" o-- "1" SharedContext : shared_context
    SessionTurn "1" --> "1" TurnType : turn_type
    SessionTurn "1" o-- "0..1" ApprovalDecision : approval
    SessionTurn "1" o-- "0..1" QualityScore : score
    ScoringEngine "1" ..> "0..*" QualityScore : produces
    ScoringEngine "1" ..> "0..*" AgentCapabilityRating : aggregates

Reach for the collaboration engine whenever a workflow needs explicit human checkpoints, rubric-based scoring, or capped agent autonomy. The HandoffProtocol is deliberately narrow — three numbers — because richer policies belong in the rubric on each ApprovalGate. The SessionRecorder companion (in recording.py) consumes the event bus to persist session state, so enabling the optional _event_bus on the engine is what turns a live session into a replayable one.

Common extension points are custom ScoringEngine strategies (new rubric schemas), additional ApprovalDecision outcomes via scorer plugins, and richer SharedContext adapters that back the context with durable storage instead of an in-memory dict.

Key contracts¶

CollaborationEngine — façade owning sessions, optional event bus, and a scoring engine; creates sessions and snapshots them.
CollaborationSession — frozen aggregate root holding the workflow id, status, participants, turns, gates, handoff protocol, and shared context.
SessionTurn — frozen record of one contribution, tagged by TurnType, optionally carrying an ApprovalDecision and a QualityScore.
ApprovalGate — frozen gate definition binding a workflow node to a required score threshold, a human-required flag, and a rubric.
QualityScore — frozen rubric-based score produced by the scoring engine, with per-dimension scores and a justification.
HandoffProtocol — frozen three-value policy governing agent-autonomy caps and auto-approve / escalation thresholds.
SessionStatus / TurnType / ApprovalDecision — enumerations closing the state space of the session lifecycle, turn provenance, and gate outcomes.
ScoringEngine — produces QualityScore records and aggregates them into AgentCapabilityRating summaries per persona.
SharedContext — mutable auditable key-value workspace shared across turns.
AgentCapabilityRating — frozen per-persona roll-up of approvals, rejections, and average quality score over all evaluations.

Collaboration Engine¶

Key contracts¶

See also¶