Decision Logging

Relevant source files

The following files were used as context for generating this wiki page:

• memory/decision_log.md
• memory_utils.py
• orchestrator.py
• app.py
• README.md
• agents/triage_agent.md

Decision Logging in the BrightPath AI Operations system is a dual-layered mechanism designed to capture the reasoning and outcomes of autonomous agent interactions. It provides a historical audit trail of how inbound messages were categorized, what policies were applied, and why specific actions were taken by specialist agents. This system ensures transparency in AI operations, allowing human managers to review automated responses and policy exceptions.

The system utilizes both a persistent SQLite database for structured event tracking and a human-readable Markdown-based "memory" file for high-level logic summaries. This dual approach facilitates both programmatic analysis of system performance and quick manual review by administrators.
Sources: README.md:12-19, app.py:168-185

System Architecture

The decision logging architecture follows a pipeline where each agent's output is captured and processed by an orchestrator before being persisted.

Data Flow and Persistence

When an inbound message is processed through the multi-agent pipeline (Triage -> Specialist -> Briefing), the results are distributed to two primary storage types:

1. Structured Database (SQLite): Stores raw JSON outputs from all agents in the events table.
2. Unstructured Memory (Markdown): Appends scannable summaries to decision_log.md via utility functions.

This diagram illustrates how the orchestrator acts as the central hub for dispatching agent results to different storage formats.
Sources: orchestrator.py:276-285, memory_utils.py:10-45

Database Implementation

The structural core of decision logging resides in the brightpath.db SQLite database. It maintains three primary tables to track decisions, tasks, and CRM changes.

Schema Details

The events table is the most critical for decision auditing, as it stores the full context of a pipeline run.

Field	Type	Description
timestamp	TEXT	ISO format time of the event.
message	TEXT	The original inbound user message.
category	TEXT	Classification (sales, customer_service, etc.).
urgency	TEXT	Priority level (high, medium, low).
triage_out	TEXT	Full JSON output from the Triage Agent.
agent_out	TEXT	Full JSON output from the Specialist Agent.
briefing	TEXT	Full JSON output from the Manager Briefing Agent.

Sources: app.py:168-175, orchestrator.py:44-55

Logging Functions

• log_event(message, triage, agent_result, briefing): Inserts a complete record of a pipeline execution into the events table.
• log_crm(contact, action, notes): Records specific CRM-related decisions made by sales agents.
• add_task(task_text, priority, source): Logs the "next action" decisions determined by agents.

Sources: app.py:182-205, orchestrator.py:68-100

Memory-Based Logging (Markdown)

While the database handles raw data, memory/decision_log.md provides a human-readable narrative of significant system decisions. This file is read by agents on every run to provide historical context for new decisions.

Logical Structure

The update_decision_log function in memory_utils.py standardizes the entry format:

def update_decision_log(event: str, agent: str, action: str, reason: str, status: str):
    entry = f"""
## {_timestamp()}
**Event:** {event}
**Agent:** {agent}
**Action:** {action}
**Reason:** {reason}
**Status:** {status}
"""
    append_to_file("decision_log.md", entry)

Sources: memory_utils.py:35-45

Decision Patterns

The log captures specific policy-driven logic, such as:

• Refunds: Validating requests against cancellation windows.
• VIP Exceptions: Approving last-minute changes for annual partners.
• Escalations: Flagging accounts after a threshold of complaints is reached.

This sequence shows the transformation of agent reasoning into a persistent Markdown record.
Sources: memory_utils.py:103-112, memory/decision_log.md:1-10

Visibility and Reporting

Decision logs are exposed to human operators through the Streamlit UI and specialized admin contexts.

Dashboard Integration

The app.py file includes a "Tasks & History" tab that queries the SQLite database to display recent events. It uses the get_events() function to fetch the last 20 entries, showing category, urgency, and sentiment.
Sources: app.py:214-219, app.py:539-558

Admin Context Building

The build_admin_context() function in the orchestrator aggregates the decision log and recent events into a rich text prompt for the Manager Briefing Agent. This ensures that the agent responsible for summarizing activity has full access to the recent "reasoning" of the system.
Sources: orchestrator.py:104-142, app.py:223-251

Summary

Decision Logging in BrightPath serves as the system's "conscious memory," bridging the gap between raw data storage and human-readable audit trails. By maintaining both a SQLite database of structured events and a Markdown log of agent reasoning, the system provides a robust framework for operational transparency and continuous AI context.
Sources: README.md:65-71, memory_utils.py:133-144