{ "name": "forge.collab", "language": "python", "version": "0.1.0", "description": "Python collab package; imports are explicit from this package.", "manifest": "forge-py/pyproject.toml", "manifestSha256": "7f96957378b21995bf2e583af2afd1b9e6fb3b0089ff3559d62c7e012a034696", "status": "source-reference", "registryPublicationVerified": false, "route": "/libraries/python/collab", "features": {}, "files": [ { "path": "forge-py/src/forge/collab/__init__.py", "sha256": "d376d88c49ee97ef6531a69641820aeb63dda9b599648d4c12875ce9296cbfb9", "artifactSha256": "9a1a4e8ae42c487f461f0aa3e5c9e57dd55e059ab4f5d67cb877c2ce57368bc2", "url": "/reference/source/forge-py/src/forge/collab/__init__.py.txt", "declarations": [] }, { "path": "forge-py/src/forge/collab/capability.py", "sha256": "ef6044de509764a625f0ef70211dbc5d88c9f226493789361473fa795bff656c", "artifactSha256": "c2cfb2f9ba1fdc966af72e9ed0d646a1d1b750613e92cbf9093d29355dbefa2e", "url": "/reference/source/forge-py/src/forge/collab/capability.py.txt", "declarations": [ { "name": "CapabilityAdvertiser", "line": 19, "signature": "class CapabilityAdvertiser(Protocol)", "documentation": "Capability advertiser contract.\n\nAgents implement this protocol to advertise their capabilities to the\ncollaboration framework. The coordinator uses these advertisements to\nmatch tasks to suitable agents.\n\nANVIL Spec section 11.6 -- Agent Capability Profile." }, { "name": "CapabilityAdvertiser.advertise_capabilities", "line": 29, "signature": "def advertise_capabilities(self) -> AgentCapabilityProfile", "documentation": "Return the agent's full capability profile.\n\nReturns:\n An AgentCapabilityProfile describing the agent's capabilities." }, { "name": "CapabilityAdvertiser.can_handle", "line": 37, "signature": "def can_handle(self, task_type: str) -> bool", "documentation": "Return True if this agent can handle the given task type.\n\nArgs:\n task_type: The task type to check (e.g., \"code-review\").\n\nReturns:\n True if the agent supports this task type." }, { "name": "CapabilityAdvertiser.current_availability", "line": 48, "signature": "def current_availability(self) -> float", "documentation": "Return the agent's current availability (0.0 to 1.0).\n\nThis is the inverse of current_load: availability = 1.0 - load.\n\nReturns:\n A value between 0.0 and 1.0 representing available capacity." }, { "name": "match_task_to_agents", "line": 60, "signature": "def match_task_to_agents(task: DelegatedTask, agents: list[AgentCapabilityProfile]) -> list[str]", "documentation": "Match a task to available agents based on capability profiles.\n\nThe matching algorithm:\n 1. Filters agents that support the task's task_type.\n 2. Filters agents that have all required tools (from\n constraints.allowed_tools, if non-empty).\n 3. Filters agents with availability > 0.0 (not fully loaded).\n 4. Sorts by availability descending (most available first).\n\nANVIL Spec section 11.6 -- Task-to-Agent Matching.\n\nArgs:\n task: The task to match.\n agents: The available agent capability profiles.\n\nReturns:\n A list of agent DIDs sorted by suitability (most suitable first).\n Returns an empty list if no agents match.\n\nExample:\n >>> from forge.collab.types import (\n ... AgentCapabilityProfile, CollaborationRole,\n ... TaskConstraints, TaskPriority,\n ... )\n >>> task = DelegatedTask(\n ... task_id=\"task-001\",\n ... task_type=\"summarize\",\n ... description=\"Summarize document\",\n ... input={},\n ... constraints=TaskConstraints(),\n ... delegator=\"did:oas:agent:coord\",\n ... priority=TaskPriority.NORMAL,\n ... )\n >>> agents = [\n ... AgentCapabilityProfile(\n ... agent_did=\"did:oas:agent:w1\",\n ... supported_roles=[CollaborationRole.WORKER],\n ... supported_task_types=[\"summarize\"],\n ... available_tools=[],\n ... current_load=0.3,\n ... max_concurrent_tasks=5,\n ... ),\n ... ]\n >>> match_task_to_agents(task, agents)\n ['did:oas:agent:w1']" } ] }, { "path": "forge-py/src/forge/collab/context.py", "sha256": "647005f337ebc632f667479eac6ecc92a81780331283377596ce68aadff19b55", "artifactSha256": "57f36d68e7bf70612a6d2352140420462feced8a46d0ef7fa80aea192b4cc207", "url": "/reference/source/forge-py/src/forge/collab/context.py.txt", "declarations": [ { "name": "SharedContextContract", "line": 19, "signature": "class SharedContextContract(Protocol)", "documentation": "Shared context contract for collaboration sessions.\n\nImplementations provide read/write access to a session-scoped key-value\nstore. Each entry carries versioning, authorship, and visibility metadata.\n\nANVIL Spec section 11.4 -- Shared Context." }, { "name": "SharedContextContract.context_read", "line": 29, "signature": "async def context_read(self, session_id: str, key: str) -> ContextEntry", "documentation": "Read a context entry by key from the specified session.\n\nArgs:\n session_id: The session whose context to read from.\n key: The key of the entry to read.\n\nReturns:\n The ContextEntry for the given key.\n\nRaises:\n ContextKeyNotFoundError: If the key does not exist.\n SessionNotFoundError: If the session does not exist." }, { "name": "SharedContextContract.context_write", "line": 50, "signature": "async def context_write(self, session_id: str, entry: ContextEntry) -> None", "documentation": "Write a context entry to the specified session.\n\nIf the key already exists, the entry is updated with the new value\nand its version is incremented.\n\nArgs:\n session_id: The session whose context to write to.\n entry: The context entry to write.\n\nRaises:\n SessionNotFoundError: If the session does not exist." }, { "name": "SharedContextContract.context_keys", "line": 70, "signature": "async def context_keys(self, session_id: str) -> list[str]", "documentation": "List all keys in the specified session's context.\n\nArgs:\n session_id: The session whose context keys to list.\n\nReturns:\n A list of key strings.\n\nRaises:\n SessionNotFoundError: If the session does not exist." }, { "name": "InMemorySharedContext", "line": 88, "signature": "class InMemorySharedContext()", "documentation": "In-memory implementation of the shared context store.\n\nStores context entries in a nested dict keyed by session ID and\nthen by entry key. Suitable for testing and single-process deployments.\n\nExample:\n >>> ctx = InMemorySharedContext()\n >>> ctx.create_session(\"sess-001\")\n >>> from forge.collab.types import ContextEntry, ContextVisibility\n >>> entry = ContextEntry(\n ... key=\"result\",\n ... value=42,\n ... value_type=\"number\",\n ... author=\"did:oas:agent:writer\",\n ... version=1,\n ... timestamp=\"2026-02-19T10:00:00Z\",\n ... visibility=ContextVisibility.SESSION,\n ... )\n >>> ctx.write_entry(\"sess-001\", entry)\n >>> ctx.read_entry(\"sess-001\", \"result\").key\n 'result'" }, { "name": "InMemorySharedContext.__init__", "line": 112, "signature": "def __init__(self) -> None", "documentation": "" }, { "name": "InMemorySharedContext.create_session", "line": 115, "signature": "def create_session(self, session_id: str) -> None", "documentation": "Register a session in the context store.\n\nThis must be called before reading or writing context for a session.\nCalling it for an already-registered session is a no-op.\n\nArgs:\n session_id: The ID of the session to register." }, { "name": "InMemorySharedContext.session_count", "line": 128, "signature": "def session_count(self) -> int", "documentation": "Return the number of sessions in the context store." }, { "name": "InMemorySharedContext.write_entry", "line": 132, "signature": "def write_entry(self, session_id: str, entry: ContextEntry) -> None", "documentation": "Write a context entry directly.\n\nArgs:\n session_id: The session to write to.\n entry: The context entry to write.\n\nRaises:\n SessionNotFoundError: If the session does not exist." }, { "name": "InMemorySharedContext.read_entry", "line": 150, "signature": "def read_entry(self, session_id: str, key: str) -> ContextEntry", "documentation": "Read a context entry directly.\n\nArgs:\n session_id: The session to read from.\n key: The key to read.\n\nReturns:\n The ContextEntry for the given key.\n\nRaises:\n SessionNotFoundError: If the session does not exist.\n ContextKeyNotFoundError: If the key does not exist." }, { "name": "InMemorySharedContext.list_keys", "line": 175, "signature": "def list_keys(self, session_id: str) -> list[str]", "documentation": "List all keys for a session.\n\nArgs:\n session_id: The session to list keys for.\n\nReturns:\n A sorted list of key strings.\n\nRaises:\n SessionNotFoundError: If the session does not exist." }, { "name": "InMemorySharedContext.context_read", "line": 196, "signature": "async def context_read(self, session_id: str, key: str) -> ContextEntry", "documentation": "Read a context entry (async interface).\n\nArgs:\n session_id: The session to read from.\n key: The key to read.\n\nReturns:\n The ContextEntry for the given key.\n\nRaises:\n SessionNotFoundError: If the session does not exist.\n ContextKeyNotFoundError: If the key does not exist." }, { "name": "InMemorySharedContext.context_write", "line": 216, "signature": "async def context_write(self, session_id: str, entry: ContextEntry) -> None", "documentation": "Write a context entry (async interface).\n\nArgs:\n session_id: The session to write to.\n entry: The context entry to write.\n\nRaises:\n SessionNotFoundError: If the session does not exist." }, { "name": "InMemorySharedContext.context_keys", "line": 232, "signature": "async def context_keys(self, session_id: str) -> list[str]", "documentation": "List all keys (async interface).\n\nArgs:\n session_id: The session to list keys for.\n\nReturns:\n A sorted list of key strings.\n\nRaises:\n SessionNotFoundError: If the session does not exist." } ] }, { "path": "forge-py/src/forge/collab/delegation.py", "sha256": "6ebeef1e3cf7ab265e5cac12eb0031b82affa0e9b208cbbb0ec6209103df4de4", "artifactSha256": "1ffdaff9a74036333d857d49ddbfe73a6606ffc104d3a1382b07ce2d83e6852e", "url": "/reference/source/forge-py/src/forge/collab/delegation.py.txt", "declarations": [ { "name": "create_delegated_task", "line": 24, "signature": "def create_delegated_task(delegator_did: str, task_type: str, description: str, input_data: Any, priority: TaskPriority=TaskPriority.NORMAL, constraints: TaskConstraints | None=None) -> DelegatedTask", "documentation": "Create a delegated task with a unique ID and timestamp.\n\nThe task ID is generated as a UUID v4 prefixed with ``\"task-\"``.\n\nANVIL Spec section 11.3 -- Delegated Task.\n\nArgs:\n delegator_did: The OAS DID of the agent delegating the task.\n task_type: The type of task (e.g., \"code-review\", \"summarize\").\n description: A human-readable description of the task.\n input_data: The input data for the task.\n priority: The task priority level. Defaults to NORMAL.\n constraints: Execution constraints. Defaults to no limits.\n\nReturns:\n A new DelegatedTask with a unique ID and current timestamp.\n\nExample:\n >>> task = create_delegated_task(\n ... \"did:oas:agent:coordinator-1\",\n ... \"summarize\",\n ... \"Summarize the quarterly report\",\n ... {\"document_id\": \"doc-123\"},\n ... )\n >>> task.task_id.startswith(\"task-\")\n True\n >>> task.task_type\n 'summarize'" }, { "name": "validate_task_constraints", "line": 79, "signature": "def validate_task_constraints(constraints: TaskConstraints) -> None", "documentation": "Validate that a task's constraints are within acceptable bounds.\n\nChecks:\n - max_steps, if set, must be greater than 0.\n - max_tokens, if set, must be greater than 0.\n - max_duration_seconds, if set, must be greater than 0.\n - required_confidence, if set, must be between 0.0 and 1.0 inclusive.\n\nANVIL Spec section 11.3 -- Task Constraints.\n\nArgs:\n constraints: The task constraints to validate.\n\nRaises:\n DelegationFailedError: If any constraint is invalid.\n\nExample:\n >>> validate_task_constraints(TaskConstraints()) # OK, defaults\n >>> validate_task_constraints(TaskConstraints(max_steps=0))\n Traceback (most recent call last):\n ...\n forge.collab.errors.DelegationFailedError: ..." } ] }, { "path": "forge-py/src/forge/collab/errors.py", "sha256": "2057cc964f97ad10c7ccaefe126ed07ed0c62d9bff650e4081aaea2534c94df8", "artifactSha256": "0248dd09c32504f7a085ea666cc9e7208dae1f7b0f187cfc69d2b8ce7b44144d", "url": "/reference/source/forge-py/src/forge/collab/errors.py.txt", "declarations": [ { "name": "CollabError", "line": 14, "signature": "class CollabError(ForgeError)", "documentation": "Base error for collaboration operations." }, { "name": "SessionNotFoundError", "line": 18, "signature": "class SessionNotFoundError(CollabError)", "documentation": "The specified collaboration session does not exist.\n\nANVIL Spec section 11.2 -- Collaboration Session.\n\nArgs:\n session_id: The session ID that was not found." }, { "name": "SessionNotFoundError.__init__", "line": 27, "signature": "def __init__(self, session_id: str) -> None", "documentation": "" }, { "name": "SessionAlreadyActiveError", "line": 35, "signature": "class SessionAlreadyActiveError(CollabError)", "documentation": "A session with the given ID is already active.\n\nANVIL Spec section 11.2 -- Collaboration Session.\n\nArgs:\n session_id: The session ID that is already active." }, { "name": "SessionAlreadyActiveError.__init__", "line": 44, "signature": "def __init__(self, session_id: str) -> None", "documentation": "" }, { "name": "InvalidSessionTransitionError", "line": 52, "signature": "class InvalidSessionTransitionError(CollabError)", "documentation": "An invalid session state transition was attempted.\n\nANVIL Spec section 11.2 -- Session State Machine.\n\nArgs:\n from_state: The current session state.\n to_state: The target state that was attempted." }, { "name": "InvalidSessionTransitionError.__init__", "line": 62, "signature": "def __init__(self, from_state: str, to_state: str) -> None", "documentation": "" }, { "name": "NotAParticipantError", "line": 71, "signature": "class NotAParticipantError(CollabError)", "documentation": "The agent is not a participant in the specified session.\n\nANVIL Spec section 11.2 -- Session Participation.\n\nArgs:\n agent_did: The agent DID that is not a participant.\n session_id: The session ID." }, { "name": "NotAParticipantError.__init__", "line": 81, "signature": "def __init__(self, agent_did: str, session_id: str) -> None", "documentation": "" }, { "name": "TaskNotFoundError", "line": 90, "signature": "class TaskNotFoundError(CollabError)", "documentation": "The specified delegated task does not exist.\n\nANVIL Spec section 11.3 -- Delegated Task.\n\nArgs:\n task_id: The task ID that was not found." }, { "name": "TaskNotFoundError.__init__", "line": 99, "signature": "def __init__(self, task_id: str) -> None", "documentation": "" }, { "name": "TaskAlreadyAssignedError", "line": 107, "signature": "class TaskAlreadyAssignedError(CollabError)", "documentation": "The task is already assigned to another agent.\n\nANVIL Spec section 11.3 -- Delegated Task.\n\nArgs:\n task_id: The task ID.\n assignee: The DID of the agent currently assigned." }, { "name": "TaskAlreadyAssignedError.__init__", "line": 117, "signature": "def __init__(self, task_id: str, assignee: str) -> None", "documentation": "" }, { "name": "CapabilityMismatchError", "line": 126, "signature": "class CapabilityMismatchError(CollabError)", "documentation": "Agent capabilities do not match the task requirements.\n\nANVIL Spec section 11.6 -- Agent Capability Profile.\n\nArgs:\n task_type: The task type.\n agent_did: The agent DID.\n reason: A human-readable explanation." }, { "name": "CapabilityMismatchError.__init__", "line": 137, "signature": "def __init__(self, task_type: str, agent_did: str, reason: str) -> None", "documentation": "" }, { "name": "ContextKeyNotFoundError", "line": 147, "signature": "class ContextKeyNotFoundError(CollabError)", "documentation": "The specified key was not found in the shared context.\n\nANVIL Spec section 11.4 -- Shared Context.\n\nArgs:\n key: The key that was not found." }, { "name": "ContextKeyNotFoundError.__init__", "line": 156, "signature": "def __init__(self, key: str) -> None", "documentation": "" }, { "name": "ContextPermissionDeniedError", "line": 163, "signature": "class ContextPermissionDeniedError(CollabError)", "documentation": "The agent does not have permission to access the context key.\n\nANVIL Spec section 11.4 -- Shared Context.\n\nArgs:\n key: The context key.\n agent_did: The agent DID." }, { "name": "ContextPermissionDeniedError.__init__", "line": 173, "signature": "def __init__(self, key: str, agent_did: str) -> None", "documentation": "" }, { "name": "InterruptRejectedError", "line": 182, "signature": "class InterruptRejectedError(CollabError)", "documentation": "The interrupt was rejected by the target agent.\n\nANVIL Spec section 11.5 -- Interrupts.\n\nArgs:\n interrupt_id: The interrupt ID.\n reason: A human-readable explanation." }, { "name": "InterruptRejectedError.__init__", "line": 192, "signature": "def __init__(self, interrupt_id: str, reason: str) -> None", "documentation": "" }, { "name": "DelegationFailedError", "line": 201, "signature": "class DelegationFailedError(CollabError)", "documentation": "A task delegation operation failed.\n\nANVIL Spec section 11.3 -- Delegated Task.\n\nArgs:\n reason: A human-readable explanation." }, { "name": "DelegationFailedError.__init__", "line": 210, "signature": "def __init__(self, reason: str) -> None", "documentation": "" }, { "name": "RoleViolationError", "line": 217, "signature": "class RoleViolationError(CollabError)", "documentation": "The agent attempted an action that violates its assigned role.\n\nANVIL Spec section 11.1 -- Collaboration Roles.\n\nArgs:\n agent_did: The agent DID.\n role: The role the agent holds.\n action: The action the agent attempted." }, { "name": "RoleViolationError.__init__", "line": 228, "signature": "def __init__(self, agent_did: str, role: str, action: str) -> None", "documentation": "" } ] }, { "path": "forge-py/src/forge/collab/interrupt.py", "sha256": "d4d11524202a2ef9e53e056e1e0a0e074f7b99f3d9433662a16efc7cb8764e6f", "artifactSha256": "7684cf917abeaba1836a8c57b1db3a06ac1218fc499fe2ae44646ea6aa67c25f", "url": "/reference/source/forge-py/src/forge/collab/interrupt.py.txt", "declarations": [ { "name": "InterruptHandler", "line": 26, "signature": "class InterruptHandler(Protocol)", "documentation": "Interrupt handler contract.\n\nAgents implement this protocol to handle incoming interrupts. The handler\ndecides whether to acknowledge the interrupt and optionally reports\nits interrupted state for potential resumption.\n\nANVIL Spec section 11.5 -- Interrupts." }, { "name": "InterruptHandler.on_interrupt", "line": 37, "signature": "async def on_interrupt(self, interrupt: Interrupt) -> InterruptResponse", "documentation": "Handle an incoming interrupt.\n\nThe handler inspects the interrupt type and priority, then decides\nwhether to acknowledge it.\n\nArgs:\n interrupt: The interrupt to handle.\n\nReturns:\n An InterruptResponse indicating acknowledgment and optional state.\n\nRaises:\n InterruptRejectedError: If the interrupt cannot be handled." }, { "name": "InterruptHandler.on_preempt", "line": 58, "signature": "async def on_preempt(self, interrupt: Interrupt) -> InterruptedState", "documentation": "Called when the agent must be preempted by a higher-priority task.\n\nThe agent should save its current state and prepare for the current\ntask to be suspended or aborted.\n\nArgs:\n interrupt: The preemption interrupt.\n\nReturns:\n An InterruptedState snapshot of the agent's state.\n\nRaises:\n InterruptRejectedError: If preemption is not possible." }, { "name": "create_interrupt", "line": 80, "signature": "def create_interrupt(interrupt_type: InterruptType, source_did: str, priority: TaskPriority, payload: Any) -> Interrupt", "documentation": "Create an interrupt with a unique ID and current timestamp.\n\nThe interrupt ID is generated as a UUID v4 prefixed with ``\"int-\"``.\n\nANVIL Spec section 11.5 -- Interrupts.\n\nArgs:\n interrupt_type: The type of interrupt.\n source_did: The OAS DID of the agent sending the interrupt.\n priority: The priority of the interrupt.\n payload: Arbitrary payload data for the interrupt.\n\nReturns:\n A new Interrupt with a unique ID and current timestamp.\n\nExample:\n >>> interrupt = create_interrupt(\n ... InterruptType.SUSPEND,\n ... \"did:oas:agent:coordinator-1\",\n ... TaskPriority.HIGH,\n ... {\"reason\": \"higher priority work\"},\n ... )\n >>> interrupt.interrupt_id.startswith(\"int-\")\n True\n >>> interrupt.interrupt_type\n " } ] }, { "path": "forge-py/src/forge/collab/roles.py", "sha256": "8e1b99b76cd16b2768a5db2ba1a611a8fea8ec10003caee5453af3e16f42426b", "artifactSha256": "e9d6d77aa7c5bea94b6dc5af404d59d624674e7c47ec410027200d75d52ddac9", "url": "/reference/source/forge-py/src/forge/collab/roles.py.txt", "declarations": [ { "name": "CoordinatorContract", "line": 24, "signature": "class CoordinatorContract(Protocol)", "documentation": "Coordinator role contract -- decomposes and assigns tasks.\n\nThe coordinator is responsible for breaking down high-level objectives\ninto individual tasks, assigning them to suitable workers, collecting\nresults, and handling worker failures. There is at most one coordinator\nper collaboration session.\n\nANVIL Spec section 11.1 -- Coordinator Role." }, { "name": "CoordinatorContract.decompose_task", "line": 36, "signature": "async def decompose_task(self, task: DelegatedTask) -> list[DelegatedTask]", "documentation": "Decompose a high-level task into smaller sub-tasks.\n\nArgs:\n task: The task to decompose.\n\nReturns:\n A list of sub-tasks derived from the original task.\n\nRaises:\n DelegationFailedError: If the task cannot be decomposed." }, { "name": "CoordinatorContract.assign_task", "line": 54, "signature": "async def assign_task(self, task: DelegatedTask, worker_did: str) -> TaskAcknowledgment", "documentation": "Assign a task to a specific worker agent.\n\nArgs:\n task: The task to assign.\n worker_did: The OAS DID of the target worker.\n\nReturns:\n A TaskAcknowledgment from the worker.\n\nRaises:\n CapabilityMismatchError: If the worker cannot handle the task.\n DelegationFailedError: If the assignment fails." }, { "name": "CoordinatorContract.aggregate_results", "line": 75, "signature": "async def aggregate_results(self, results: list[TaskResult]) -> TaskResult", "documentation": "Aggregate results from multiple worker tasks into a single result.\n\nArgs:\n results: The results from all completed sub-tasks.\n\nReturns:\n A single aggregated TaskResult.\n\nRaises:\n DelegationFailedError: If the results cannot be aggregated." }, { "name": "CoordinatorContract.handle_worker_failure", "line": 93, "signature": "async def handle_worker_failure(self, task_id: str, worker_did: str, error: str) -> None", "documentation": "Handle a failure reported by a worker.\n\nArgs:\n task_id: The ID of the failed task.\n worker_did: The DID of the worker that failed.\n error: A description of the failure.\n\nRaises:\n DelegationFailedError: If recovery is not possible." }, { "name": "WorkerContract", "line": 112, "signature": "class WorkerContract(Protocol)", "documentation": "Worker role contract -- executes delegated tasks, reports progress.\n\nWorkers receive tasks from coordinators, execute them within the given\nconstraints, report progress periodically, and submit results upon\ncompletion.\n\nANVIL Spec section 11.1 -- Worker Role." }, { "name": "WorkerContract.on_task_delegated", "line": 123, "signature": "async def on_task_delegated(self, task: DelegatedTask) -> TaskAcknowledgment", "documentation": "Called when a task is delegated to this worker.\n\nArgs:\n task: The delegated task to evaluate.\n\nReturns:\n A TaskAcknowledgment indicating acceptance or rejection.\n\nRaises:\n CollabError: If the acknowledgment cannot be produced." }, { "name": "WorkerContract.report_progress", "line": 141, "signature": "async def report_progress(self, progress: TaskProgress) -> None", "documentation": "Report progress on an in-flight task.\n\nArgs:\n progress: The progress report.\n\nRaises:\n TaskNotFoundError: If the task ID does not match an active task." }, { "name": "WorkerContract.submit_result", "line": 156, "signature": "async def submit_result(self, result: TaskResult) -> None", "documentation": "Submit the result of a completed task.\n\nArgs:\n result: The task result to submit.\n\nRaises:\n TaskNotFoundError: If the task ID does not match an active task." }, { "name": "WorkerContract.on_task_cancelled", "line": 171, "signature": "async def on_task_cancelled(self, task_id: str, reason: str) -> None", "documentation": "Called when a task is cancelled by the coordinator.\n\nArgs:\n task_id: The ID of the cancelled task.\n reason: A human-readable cancellation reason.\n\nRaises:\n TaskNotFoundError: If the task is not known." }, { "name": "PeerContract", "line": 188, "signature": "class PeerContract(Protocol)", "documentation": "Peer role contract -- participates in consensus-based collaboration.\n\nIn peer-mode collaboration, all agents have equal standing. Peers propose\nactions, vote on proposals, and act on consensus decisions.\n\nANVIL Spec section 11.1 -- Peer Role." }, { "name": "PeerContract.propose", "line": 198, "signature": "async def propose(self, proposal: Any) -> str", "documentation": "Submit a proposal for peer consensus.\n\nArgs:\n proposal: The proposal data to submit for voting.\n\nReturns:\n A unique proposal ID string.\n\nRaises:\n DelegationFailedError: If the proposal cannot be submitted." }, { "name": "PeerContract.vote", "line": 216, "signature": "async def vote(self, proposal_id: str, approve: bool) -> None", "documentation": "Vote on an existing proposal.\n\nArgs:\n proposal_id: The ID of the proposal to vote on.\n approve: True to approve, False to reject.\n\nRaises:\n DelegationFailedError: If voting has closed or proposal not found." }, { "name": "PeerContract.on_consensus", "line": 233, "signature": "async def on_consensus(self, proposal_id: str, result: Any) -> None", "documentation": "Called when consensus is reached on a proposal.\n\nArgs:\n proposal_id: The ID of the proposal that reached consensus.\n result: The consensus result data.\n\nRaises:\n CollabError: If the agent cannot act on the consensus." } ] }, { "path": "forge-py/src/forge/collab/session.py", "sha256": "a078e69a8acb49b7b729f5bccca63916aa8f34875804672616d21736b226d1d9", "artifactSha256": "586ea77ab05978cd65a13343f3e39fe09344a6c4fd0de2cdb2f2ba199650c495", "url": "/reference/source/forge-py/src/forge/collab/session.py.txt", "declarations": [ { "name": "SessionContract", "line": 34, "signature": "class SessionContract(Protocol)", "documentation": "Session lifecycle contract.\n\nAgents implement this protocol to receive notifications about session\nlifecycle events: joining, state transitions, and leaving.\n\nANVIL Spec section 11.2 -- Session Lifecycle." }, { "name": "SessionContract.on_session_join", "line": 43, "signature": "async def on_session_join(self, session: CollaborationSession, role: CollaborationRole) -> None", "documentation": "Called when the agent joins a collaboration session.\n\nArgs:\n session: The session being joined.\n role: The role assigned to this agent in the session.\n\nRaises:\n CollabError: If the agent cannot join the session." }, { "name": "SessionContract.on_session_transition", "line": 59, "signature": "async def on_session_transition(self, session_id: str, from_state: SessionState, to_state: SessionState) -> None", "documentation": "Called when the session transitions between states.\n\nArgs:\n session_id: The ID of the session.\n from_state: The previous state.\n to_state: The new state.\n\nRaises:\n CollabError: If the agent cannot handle the transition." }, { "name": "SessionContract.on_session_leave", "line": 77, "signature": "async def on_session_leave(self, session_id: str, reason: str) -> None", "documentation": "Called when the agent leaves a collaboration session.\n\nArgs:\n session_id: The ID of the session being left.\n reason: A human-readable reason for leaving.\n\nRaises:\n CollabError: If cleanup fails." }, { "name": "SessionManager", "line": 94, "signature": "class SessionManager()", "documentation": "Manages the session state machine per ANVIL Spec section 11.2.\n\nThe SessionManager enforces the immutable transition table for\ncollaboration sessions. It tracks the current state, validates all\ntransitions, and maintains a complete transition history.\n\nSessions start in the PROPOSED state and progress through ACTIVE\nand COMPLETING to terminal states (COMPLETED, TIMED_OUT, DISSOLVED).\n\nExample:\n >>> mgr = SessionManager()\n >>> mgr.state\n \n >>> t = mgr.transition(SessionState.ACTIVE)\n >>> t.from_state\n \n >>> mgr.state\n " }, { "name": "SessionManager.__init__", "line": 115, "signature": "def __init__(self) -> None", "documentation": "" }, { "name": "SessionManager.state", "line": 120, "signature": "def state(self) -> SessionState", "documentation": "Return the current session state." }, { "name": "SessionManager.transition", "line": 125, "signature": "def transition(self, target: SessionState) -> SessionTransition", "documentation": "Attempt to transition to the given target state.\n\nValidates the transition against the ANVIL Spec section 11.2\ntransition table. If valid, the state is updated and a\nSessionTransition is recorded. If invalid, an error is raised\nand the state is unchanged.\n\nArgs:\n target: The desired target SessionState.\n\nReturns:\n A SessionTransition record on success.\n\nRaises:\n InvalidSessionTransitionError: If the transition is invalid\n or is a self-transition.\n\nExample:\n >>> mgr = SessionManager()\n >>> t = mgr.transition(SessionState.ACTIVE)\n >>> t.to_state\n " }, { "name": "SessionManager.can_transition_to", "line": 172, "signature": "def can_transition_to(self, target: SessionState) -> bool", "documentation": "Return True if the transition to target is valid.\n\nArgs:\n target: The candidate target SessionState.\n\nReturns:\n True if the transition is permitted by the ANVIL table.\n\nExample:\n >>> mgr = SessionManager()\n >>> mgr.can_transition_to(SessionState.ACTIVE)\n True\n >>> mgr.can_transition_to(SessionState.COMPLETING)\n False" }, { "name": "SessionManager.valid_transitions", "line": 190, "signature": "def valid_transitions(self) -> list[SessionState]", "documentation": "Return the set of valid target states from the current state.\n\nReturns:\n A list of valid target states. Empty for terminal states." }, { "name": "SessionManager.history", "line": 199, "signature": "def history(self) -> list[SessionTransition]", "documentation": "Return the complete transition history.\n\nThe history is ordered chronologically -- the first entry is the\nfirst transition that occurred.\n\nReturns:\n A list of all SessionTransition records." } ] }, { "path": "forge-py/src/forge/collab/types.py", "sha256": "31d97df4d4baecc0d4975a899e27934961b5e8d3a343055279307cf69dfdb5ba", "artifactSha256": "4c4fb74788f03a91f0d492e771bf8a75d35b85456b7573e02e8ac6639cf903ce", "url": "/reference/source/forge-py/src/forge/collab/types.py.txt", "declarations": [ { "name": "CollaborationRole", "line": 27, "signature": "class CollaborationRole(Enum)", "documentation": "Role an agent plays in a collaboration session.\n\nRoles define the set of actions available to an agent within a session.\nA Coordinator decomposes and assigns tasks; a Worker executes delegated\ntasks; a Peer participates in consensus-based decision-making.\n\nANVIL Spec section 11.1 -- Collaboration Roles.\n\nExample:\n >>> role = CollaborationRole.COORDINATOR\n >>> role.value\n 'coordinator'" }, { "name": "SessionState", "line": 51, "signature": "class SessionState(Enum)", "documentation": "State of a collaboration session.\n\nThe session state machine controls which operations are valid. Sessions\nstart in the PROPOSED state and progress through ACTIVE and COMPLETING\nstates to terminal states.\n\nANVIL Spec section 11.2 -- Session State Machine.\n\nTransition Table (IMMUTABLE -- ANVIL Spec section 11.2):\n\n| Current State | Valid Next States |\n|---------------|--------------------------------------|\n| PROPOSED | ACTIVE, DISSOLVED |\n| ACTIVE | COMPLETING, DISSOLVED, TIMED_OUT |\n| COMPLETING | COMPLETED, DISSOLVED |\n| COMPLETED | *(terminal)* |\n| TIMED_OUT | *(terminal)* |\n| DISSOLVED | *(terminal)* |\n\nExample:\n >>> state = SessionState.ACTIVE\n >>> state.is_terminal()\n False\n >>> SessionState.COMPLETED.is_terminal()\n True" }, { "name": "SessionState.valid_transitions", "line": 87, "signature": "def valid_transitions(self) -> list[SessionState]", "documentation": "Return the valid target states from this state.\n\nReturns:\n A list of SessionState values that are valid targets.\n Returns an empty list for terminal states.\n\nExample:\n >>> targets = SessionState.ACTIVE.valid_transitions()\n >>> SessionState.COMPLETING in targets\n True" }, { "name": "SessionState.is_terminal", "line": 113, "signature": "def is_terminal(self) -> bool", "documentation": "Return True if this is a terminal state (no outgoing transitions).\n\nTerminal states are COMPLETED, TIMED_OUT, and DISSOLVED.\n\nExample:\n >>> SessionState.PROPOSED.is_terminal()\n False\n >>> SessionState.COMPLETED.is_terminal()\n True" }, { "name": "TaskStatus", "line": 135, "signature": "class TaskStatus(Enum)", "documentation": "Status of a completed delegated task.\n\nANVIL Spec section 11.3 -- Task Status.\n\nExample:\n >>> TaskStatus.COMPLETED.value\n 'completed'" }, { "name": "TaskPriority", "line": 150, "signature": "class TaskPriority(Enum)", "documentation": "Priority level for task scheduling.\n\nHigher priority tasks are scheduled before lower priority tasks.\nThe default priority is NORMAL.\n\nANVIL Spec section 11.3 -- Task Priority.\n\nExample:\n >>> TaskPriority.NORMAL.value\n 'normal'" }, { "name": "InterruptType", "line": 173, "signature": "class InterruptType(Enum)", "documentation": "Type of interrupt that can be sent to an agent.\n\nANVIL Spec section 11.5 -- Interrupt Types.\n\nExample:\n >>> InterruptType.SUSPEND.value\n 'suspend'" }, { "name": "ContextVisibility", "line": 195, "signature": "class ContextVisibility(Enum)", "documentation": "Visibility scope for a shared context entry.\n\nControls which agents can read a context entry. Entries may be visible\nto the entire session, to agents with a specific role, or to a single\nnamed agent.\n\nANVIL Spec section 11.4 -- Context Visibility.\n\nNote:\n For role-based and agent-based visibility, use the factory methods\n ``for_role`` and ``for_agent`` on ContextEntry, or set the\n visibility_target field alongside the enum value.\n\nExample:\n >>> ContextVisibility.SESSION.value\n 'session'" }, { "name": "SessionParticipant", "line": 224, "signature": "class SessionParticipant()", "documentation": "A participant in a collaboration session.\n\nEach participant has an assigned role and a status indicating whether\nthey are actively participating.\n\nANVIL Spec section 11.2 -- Collaboration Session.\n\nArgs:\n agent_did: The OAS DID of the participating agent.\n role: The role this agent plays in the session.\n joined_at: ISO 8601 timestamp when the agent joined.\n status: Current participation status (e.g., \"active\", \"left\").\n\nExample:\n >>> p = SessionParticipant(\n ... agent_did=\"did:oas:agent:worker-1\",\n ... role=CollaborationRole.WORKER,\n ... joined_at=\"2026-02-19T10:00:00Z\",\n ... status=\"active\",\n ... )\n >>> p.role\n " }, { "name": "TaskConstraints", "line": 256, "signature": "class TaskConstraints()", "documentation": "Constraints bounding a delegated task's execution.\n\nConstraints prevent runaway tasks by limiting steps, tokens, duration,\nand tool access. The worker must respect these bounds during execution.\n\nANVIL Spec section 11.3 -- Task Constraints.\n\nExample:\n >>> c = TaskConstraints()\n >>> c.max_steps is None\n True" }, { "name": "DelegatedTask", "line": 278, "signature": "class DelegatedTask()", "documentation": "A task delegated from a coordinator to a worker agent.\n\nDelegated tasks carry input data, constraint bounds, output expectations,\nand context key references that the worker may read from the shared\ncontext store.\n\nANVIL Spec section 11.3 -- Delegated Task.\n\nArgs:\n task_id: Unique identifier for this task.\n task_type: The type of task (e.g., \"code-review\", \"summarize\").\n description: Human-readable description of the task.\n input: Input data for the task.\n constraints: Constraints bounding the task execution.\n delegator: The OAS DID of the agent that delegated this task.\n priority: Priority level for task scheduling.\n output_schema: Optional JSON Schema for the expected output.\n deadline: Optional ISO 8601 deadline for task completion.\n context_keys: Keys in the shared context that this task may read.\n\nExample:\n >>> task = DelegatedTask(\n ... task_id=\"task-001\",\n ... task_type=\"summarize\",\n ... description=\"Summarize the document\",\n ... input={\"doc_id\": \"doc-1\"},\n ... constraints=TaskConstraints(),\n ... delegator=\"did:oas:agent:coord\",\n ... priority=TaskPriority.NORMAL,\n ... )\n >>> task.task_type\n 'summarize'" }, { "name": "TaskResult", "line": 326, "signature": "class TaskResult()", "documentation": "The result of a completed delegated task.\n\nWorkers submit results with a status, output data, optional confidence\nscore, metadata, and an optional cryptographic signature.\n\nANVIL Spec section 11.3 -- Task Result.\n\nArgs:\n task_id: The ID of the task this result corresponds to.\n status: The completion status of the task.\n output: The output data produced by the worker.\n confidence: Optional confidence score (0.0 to 1.0).\n metadata: Arbitrary metadata about the task execution.\n signature: Optional Ed25519 signature over the result.\n\nExample:\n >>> result = TaskResult(\n ... task_id=\"task-001\",\n ... status=TaskStatus.COMPLETED,\n ... output={\"summary\": \"LGTM\"},\n ... )\n >>> result.status\n " }, { "name": "TaskAcknowledgment", "line": 361, "signature": "class TaskAcknowledgment()", "documentation": "A worker's acknowledgment of a delegated task.\n\nWhen a task is delegated, the worker responds with an acknowledgment\nindicating whether it accepts or rejects the task.\n\nANVIL Spec section 11.3 -- Task Acknowledgment.\n\nArgs:\n task_id: The ID of the task being acknowledged.\n accepted: Whether the worker accepts the task.\n rejection_reason: Reason for rejection, if not accepted.\n estimated_completion_seconds: Estimated time to completion.\n\nExample:\n >>> ack = TaskAcknowledgment(\n ... task_id=\"task-001\",\n ... accepted=True,\n ... )\n >>> ack.accepted\n True" }, { "name": "TaskProgress", "line": 391, "signature": "class TaskProgress()", "documentation": "Progress report for an in-flight delegated task.\n\nWorkers periodically report progress to the coordinator.\n\nANVIL Spec section 11.3 -- Task Progress.\n\nArgs:\n task_id: The ID of the task this progress report corresponds to.\n percentage: Completion percentage (0.0 to 100.0).\n message: Human-readable status message.\n\nExample:\n >>> progress = TaskProgress(\n ... task_id=\"task-001\",\n ... percentage=50.0,\n ... message=\"Halfway through\",\n ... )\n >>> progress.percentage\n 50.0" }, { "name": "Interrupt", "line": 419, "signature": "class Interrupt()", "documentation": "An interrupt sent to an agent during task execution.\n\nInterrupts allow coordinators (or the platform) to preempt, suspend,\nresume, abort, or redirect an agent's current work.\n\nANVIL Spec section 11.5 -- Interrupts.\n\nArgs:\n interrupt_id: Unique identifier for this interrupt.\n interrupt_type: The type of interrupt.\n source: The OAS DID of the agent that sent the interrupt.\n priority: Priority of the interrupt.\n payload: Arbitrary payload data for the interrupt.\n timestamp: ISO 8601 timestamp when the interrupt was created.\n\nExample:\n >>> interrupt = Interrupt(\n ... interrupt_id=\"int-001\",\n ... interrupt_type=InterruptType.SUSPEND,\n ... source=\"did:oas:agent:coord\",\n ... priority=TaskPriority.HIGH,\n ... payload={\"reason\": \"higher priority\"},\n ... timestamp=\"2026-02-19T10:30:00Z\",\n ... )\n >>> interrupt.interrupt_type\n " }, { "name": "InterruptResponse", "line": 457, "signature": "class InterruptResponse()", "documentation": "An agent's response to an interrupt.\n\nAfter receiving an interrupt, the agent acknowledges it and optionally\nreports its interrupted state for potential resumption.\n\nANVIL Spec section 11.5 -- Interrupt Response.\n\nArgs:\n interrupt_id: The ID of the interrupt being responded to.\n acknowledged: Whether the agent acknowledged the interrupt.\n current_state: The agent's state at the time of interruption.\n\nExample:\n >>> response = InterruptResponse(\n ... interrupt_id=\"int-001\",\n ... acknowledged=True,\n ... )\n >>> response.acknowledged\n True" }, { "name": "InterruptedState", "line": 485, "signature": "class InterruptedState()", "documentation": "Snapshot of an agent's state at the moment of interruption.\n\nCaptures enough information to resume the task later if the\ninterrupt type supports resumption.\n\nANVIL Spec section 11.5 -- Interrupted State.\n\nArgs:\n task_id: The ID of the task that was interrupted, if any.\n step_count: The number of steps completed before interruption.\n progress_percentage: Progress percentage at interruption (0-100).\n can_resume: Whether the task can be resumed from this state.\n\nExample:\n >>> state = InterruptedState(\n ... step_count=5,\n ... progress_percentage=42.0,\n ... can_resume=True,\n ... )\n >>> state.can_resume\n True" }, { "name": "ContextEntry", "line": 516, "signature": "class ContextEntry()", "documentation": "An entry in a session's shared context store.\n\nContext entries are key-value pairs with versioning, authorship tracking,\nand visibility controls.\n\nANVIL Spec section 11.4 -- Shared Context.\n\nArgs:\n key: The key identifying this context entry.\n value: The value stored in this entry.\n value_type: The type of the value (e.g., \"json\", \"text\").\n author: The OAS DID of the agent that wrote this entry.\n version: Monotonically increasing version number for this key.\n timestamp: ISO 8601 timestamp when this version was written.\n visibility: Visibility control for this entry.\n visibility_target: Role or DID for ROLE/AGENT visibility.\n\nExample:\n >>> entry = ContextEntry(\n ... key=\"analysis.result\",\n ... value={\"score\": 0.95},\n ... value_type=\"json\",\n ... author=\"did:oas:agent:worker-1\",\n ... version=1,\n ... timestamp=\"2026-02-19T10:15:00Z\",\n ... visibility=ContextVisibility.SESSION,\n ... )\n >>> entry.version\n 1" }, { "name": "AgentCapabilityProfile", "line": 559, "signature": "class AgentCapabilityProfile()", "documentation": "An agent's advertised capability profile for task matching.\n\nCapability profiles describe what an agent can do (supported roles,\ntask types, available tools), its current load, and its maximum\nconcurrency.\n\nANVIL Spec section 11.6 -- Agent Capability Profile.\n\nArgs:\n agent_did: The OAS DID of the agent.\n supported_roles: Collaboration roles this agent supports.\n supported_task_types: Task types this agent can handle.\n available_tools: Tool names available to this agent.\n current_load: Current load factor (0.0=idle, 1.0=full).\n max_concurrent_tasks: Maximum concurrent tasks.\n\nExample:\n >>> profile = AgentCapabilityProfile(\n ... agent_did=\"did:oas:agent:analyzer\",\n ... supported_roles=[CollaborationRole.WORKER],\n ... supported_task_types=[\"summarize\"],\n ... available_tools=[\"read_file\"],\n ... current_load=0.3,\n ... max_concurrent_tasks=5,\n ... )\n >>> profile.max_concurrent_tasks\n 5" }, { "name": "SessionTransition", "line": 598, "signature": "class SessionTransition()", "documentation": "A record of a single session state transition.\n\nEvery session transition is timestamped and stored in the session's\ntransition history for audit trail purposes.\n\nANVIL Spec section 11.2 -- Session State Machine.\n\nArgs:\n from_state: The state before the transition.\n to_state: The state after the transition.\n timestamp: ISO 8601 timestamp when the transition occurred.\n\nExample:\n >>> t = SessionTransition(\n ... from_state=SessionState.PROPOSED,\n ... to_state=SessionState.ACTIVE,\n ... timestamp=\"2026-02-19T10:00:00Z\",\n ... )\n >>> t.from_state\n " }, { "name": "CollaborationSession", "line": 627, "signature": "class CollaborationSession()", "documentation": "A collaboration session grouping agents for coordinated work.\n\nSessions have a typed purpose, a set of participants with assigned roles,\nan optional coordinator, and an optional shared context store.\n\nANVIL Spec section 11.2 -- Collaboration Session.\n\nArgs:\n session_id: Unique identifier for this session.\n session_type: The type of collaboration (e.g., \"code-review\").\n participants: The agents participating in this session.\n created_at: ISO 8601 timestamp when the session was created.\n coordinator: The DID of the coordinator agent, if any.\n shared_context_id: The ID of the shared context store.\n timeout_seconds: Optional session timeout in seconds.\n metadata: Arbitrary metadata for application-specific properties.\n\nExample:\n >>> session = CollaborationSession(\n ... session_id=\"sess-001\",\n ... session_type=\"code-review\",\n ... participants=[],\n ... created_at=\"2026-02-19T10:00:00Z\",\n ... )\n >>> session.session_id\n 'sess-001'" } ] } ] }