Terminal Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal Interface in the BrightPath AI Operations system is a text-based Command Line Interface (CLI) used to interact with the multi-agent orchestration pipeline. It serves as a lightweight alternative to the Streamlit web dashboard, allowing developers and administrators to run pre-defined test scenarios, input custom messages, and inspect the operational state of the system directly from a console environment.
The interface is primarily implemented in orchestrator.py and utilizes the rich library to provide formatted console output, including tables, panels, and colored status indicators. It facilitates the execution of the three-agent pipeline—Triage, Specialist (Sales or Customer Service), and Manager Briefing—while providing real-time feedback on lead qualification, urgency detection, and automated task generation.
Sources: orchestrator.py:1-12, README.md:14-22, README.md:65-71
CLI Architecture and User Flow
The terminal interface operates through a persistent while loop that displays a menu of options and waits for user input. Users can select from a numbered list of pre-defined scenarios, view system logs, or manually type an inbound message to be processed by the AI pipeline.
Main Menu Logic
The print_menu() function generates a table of available actions, while the main() loop handles the user's choice.
The menu includes 18 pre-built scenarios categorized into "Original" and "Memory-Dependent" groups, allowing for consistent testing of edge cases like repeat complaints or VIP booking changes.
Sources: orchestrator.py:350-388, scenarios.py:12-113
AI Pipeline Orchestration
When a message is selected or typed, the interface triggers the process_message function. This function coordinates the sequential execution of AI agents and visually reports the progress of each step to the terminal.
Orchestration Sequence
The following sequence diagram illustrates the data flow through the terminal interface during a pipeline run:
Specialist Routing Logic
The terminal interface uses the classification output from the Triage Agent to determine which specialist agent to invoke.
| Classification | Condition | Agent Invoked | Output Displayed |
|---|---|---|---|
sales | next_agent == "sales_agent" | run_sales_agent | Lead tier, Estimated value, CRM update |
customer_service | Default case | run_customer_service_agent | Issue type, Policy used, Draft response |
admin | category == "admin" | Internal Logic | Rich context briefing from DB and Memory |
Sources: orchestrator.py:255-300, orchestrator.py:314-342
Data Inspection Tools
The Terminal Interface provides dedicated commands to inspect the underlying system state without requiring external database tools.
Task and History Views
The show_tasks() and show_history() functions query the SQLite database and render the results in scannable rich tables.
- Open Tasks (
t): Displays the creation timestamp, task description, priority (color-coded: red for high, yellow for medium, green for low), and current status. - Recent Events (
h): Displays a log of the last 10 pipeline events, including category, urgency, sentiment, and a truncated version of the original message.
Sources: orchestrator.py:114-148
Console Formatting
The interface utilizes specific rich components to improve readability:
Panel: Used for the inbound message and the final Telegram summary.Console.rule: Provides horizontal delimiters between pipeline steps.dim/boldstyles: Distinguish between technical logs and actionable AI outputs.
Sources: orchestrator.py:256-259, orchestrator.py:328-332
Integration and Silent Processing
The terminal interface also includes a "silent" version of the orchestration logic designed for external integrations, such as a Telegram bot.
def process_message_for_telegram(message: str) -> dict:
"""Silent version of process_message() — returns result dict for Telegram."""
# Logic repeats pipeline steps without printing to console
# Returns a structured dictionary containing summary, action, value, and risk
This function allows the same terminal-based logic to power a telegram_bot.py (noted as an optional expansion) by returning a dictionary with keys: summary, action, value, and risk.
Sources: orchestrator.py:390-424, README.md:115-123
The Terminal Interface provides a robust, developer-centric gateway to the BrightPath AI pipeline. By combining interactive scenario testing with direct database inspection and multi-agent orchestration, it ensures that operational processes can be managed and audited entirely through a console environment.