Gateway#

The Gateway provides the single entry point for all message processing in the Osprey Framework. All interfaces (CLI, OpenWebUI, etc.) should call Gateway.process_message().

Note

The Gateway operates external to the compiled graph by design, enabling it to perform meta-operations such as approval response processing, state lifecycle management, and interrupt detection. This centralized approach simplifies interface implementation by removing the need for interfaces to handle complex state management, slash commands, or approval workflow logic directly.

Gateway Class#

class osprey.infrastructure.gateway.Gateway(config=None)[source]#

Bases: object

Gateway - Single Entry Point for All Message Processing

This is the only component that interfaces should call for message processing. All state management, slash commands, and approval handling is centralized here.

Usage:

gateway = Gateway()
result = await gateway.process_message(user_input, graph, config)

# Execute the result
if result.resume_command:
    await graph.ainvoke(result.resume_command, config=config)
elif result.state_updates:
    await graph.ainvoke(result.state_updates, config=config)

Initialize the gateway.

Parameters:: config (dict[str, Any] | None) – Optional configuration dictionary

Key Methods

process_message

Single entry point for all message processing.

Private Methods

`_handle_interrupt_flow`	Handle interrupt/approval flow generically.
`_handle_new_message_flow`	Handle new message flow with fresh state creation or direct chat mode.
`_has_pending_interrupts`	Check if there are pending interrupts.
`_detect_approval_response`	Detect approval or rejection in user input.
`_extract_resume_payload`	Extract interrupt payload from current LangGraph state.
`_clear_approval_state`	Clear approval state to prevent pollution in subsequent interrupts.
`_process_slash_commands`	Process slash commands using the centralized command system.

__init__(config=None)[source]#

Initialize the gateway.

Parameters:: config (dict[str, Any] | None) – Optional configuration dictionary

async process_message(user_input, compiled_graph=None, config=None)[source]#

Single entry point for all message processing.

This method handles the complete message processing flow: 1. Check for pending interrupts (approval flow) 2. Process new messages (normal flow) 3. Apply state reset and slash commands 4. Return complete result ready for execution

Parameters:

user_input (str) – The raw user message
compiled_graph (Any) – The compiled LangGraph instance
config (dict[str, Any] | None) – LangGraph execution configuration

Returns:

Complete processing result ready for execution

Return type:

GatewayResult

Gateway Result#

class osprey.infrastructure.gateway.GatewayResult(agent_state=None, resume_command=None, slash_commands_processed=None, approval_detected=False, is_interrupt_resume=False, is_state_only_update=False, exit_interface=False, error=None)[source]#

Bases: object

Result of gateway message processing.

This is the interface between Gateway and all other components.

agent_state: dict[str, Any] | None = None#

resume_command: Command | None = None#

slash_commands_processed: list[str] = None#

approval_detected: bool = False#

is_interrupt_resume: bool = False#

is_state_only_update: bool = False#

exit_interface: bool = False#

error: str | None = None#

__init__(agent_state=None, resume_command=None, slash_commands_processed=None, approval_detected=False, is_interrupt_resume=False, is_state_only_update=False, exit_interface=False, error=None)#

Registration & Configuration#

Gateway is not registered in the framework registry as it serves as the entry point that interfaces call directly. It operates independently of the node execution system and manages state transitions for the framework.

Gateway uses a two-tier approval detection system: explicit yes/no pattern matching for instant responses (yes, no, ok, etc.), with LLM-powered fallback through the configured approval model for complex natural language responses. All other operations are deterministic.

Architecture Overview#

The Gateway handles:

State reset for new conversation turns
Slash command parsing and application
Approval response detection and resume commands
Message preprocessing and state updates

Key Principles:

Gateway is the only component that creates state updates
Interfaces handle presentation only
Clean separation of concerns with single responsibility