Project Architecture

BrightPath is a multi-agent AI operations system designed for a training company to manage inbound communications. The architecture follows a sequential pipeline where messages are classified, processed by specialists, and summarized for management. The system leverages Large Language Models (LLMs) from Anthropic, specifically Claude Sonnet for complex reasoning and Claude Haiku for fast summarization.

The system integrates file-based memory (Markdown), structured data (JSON), and a relational database (SQLite) to provide long-term context and operational tracking. It supports both a web-based dashboard via Streamlit and a terminal-based interface for developers.

Sources: README.md:1-12, app.py:168-175, orchestrator.py:31-35

Core Agent Pipeline

The system operates on a three-agent pipeline that processes every inbound message. Each stage is isolated into a specific role with defined responsibilities and output schemas.

Pipeline Stages

1. Triage Agent: Acts as the entry point. It classifies the message category (Sales, CS, Escalation, Admin, or Complex), assesses urgency and sentiment, and identifies the customer from existing CRM data.
2. Specialist Agent (Sales or Customer Service): Receives context from the Triage Agent and reads file-based memory to draft a response or log internal actions.
3. Manager Briefing Agent: Summarizes the entire interaction into a concise, Telegram-ready format, flagging high-value opportunities or risks for human review.

The following flowchart illustrates the message flow through the architecture:

The diagram shows the sequential routing from Triage to specialized agents and finally to the briefing stage.

Sources: README.md:13-23, orchestrator.py:276-340, agents/triage_agent.md:1-35

Data and Memory Systems

BrightPath utilizes a hybrid storage strategy to maintain context across sessions and log operational history.

Memory & CRM Storage

Sources: README.md:46-65, app.py:214-236, orchestrator.py:162-185

SQLite Database Schema

The database brightpath.db consists of three primary tables used to track the system's state and history.

This ER diagram represents the structure of the relational database used for logging and task management.

Sources: orchestrator.py:44-77, app.py:183-200

Component Logic and Integration

Orchestration Logic

The orchestrator.py and app.py files manage the execution of the pipeline. The process_message function coordinates the calls to the Anthropic API, passing the output of one agent as context to the next.

# orchestrator.py:276-285
def process_message(message: str, scenario_key: str = ""):
    memory = load_memory()

    # Step 1: Triage
    triage = run_triage(message, memory)
    
    # Step 2: Specialist Agent selection
    next_agent = triage.get("next_agent", "customer_service_agent")
    category   = triage.get("category", "customer_service")

Memory Update Utilities

After a pipeline run, specifically for defined test scenarios, the system performs a "write-back" to the Markdown memory files to ensure subsequent runs have updated context.

• update_customer_history: Appends specific interaction notes to a customer's section.
• add_open_task: Inserts new tasks into open_tasks.md under priority headings.
• update_decision_log: Records why specific agent actions were taken.

Sources: memory_utils.py:43-100, app.py:349-355, orchestrator.py:330-334

System Interfaces

The architecture provides two primary entry points for interacting with the pipeline:

1. Streamlit Web Dashboard

Located in app.py, this interface provides a visual representation of the pipeline progress, a live view of memory files, and a CRM browser. It uses four tabs to segregate functionality: Run Pipeline, Tasks & History, Memory Files, and CRM Data.
Sources: app.py:11-15, README.md:81-89

2. Terminal Orchestrator

Located in orchestrator.py, this serves as a CLI for running pre-built scenarios and inspecting the database through formatted tables using the rich library. It also includes a process_message_for_telegram() function intended for headless bot integration.
Sources: orchestrator.py:350-385, orchestrator.py:406-435

Summary

The BrightPath architecture is a specialized multi-agent framework that prioritizes context and scannable output. By separating concerns between classification (Triage), action (Specialists), and reporting (Briefing), it creates a robust pipeline for managing business operations. Its use of Markdown files as "memory" allows for easy human editing and auditability, while the SQLite backend ensures all automated decisions are recorded for historical analysis.

Sources: README.md:120-125, app.py:273-305