# dumindi18/tripsupervisor architecture

> Architecture diagram of the GitHub repository dumindi18/tripsupervisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dumindi18/tripsupervisor
- Repository: https://github.com/dumindi18/tripsupervisor

## Overview

TripSupervisor is a runnable multi-agent trip-booking scenario designed to exercise workflow, verification, concurrency and hallucination failures. A customer request is initialized by the supervisor, then flight, hotel and activity agents search and book in parallel; a verifier and checkout produce a ground-truth record, and Trip Digest summarizes it for a final hallucination check. The sampled source shows these stages and shared-state interactions; other documented failure toggles are retained as configuration capability, without inferring their internal wiring.

Main entry points: [`blackboard.py`](https://github.com/dumindi18/tripsupervisor/blob/main/blackboard.py) (Shared blackboard), [`run_trip_supervisor.py`](https://github.com/dumindi18/tripsupervisor/blob/main/run_trip_supervisor.py) (Scenario runner), [`trip_workflow.py`](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py) (Flight agent), [`trip_mock_apis.py`](https://github.com/dumindi18/tripsupervisor/blob/main/trip_mock_apis.py) (Booking APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_runner["Scenario runner"]
  node_engine["DAG engine<br/>[workflow.py]"]
  node_agent["LLM agent<br/>[agent.py]"]
end

subgraph group_trip["Trip booking stages"]
  node_supervisor["Trip supervisor<br/>[trip_workflow.py]"]
  node_flight["Flight agent<br/>[trip_workflow.py]"]
  node_hotel["Hotel agent<br/>[trip_workflow.py]"]
  node_activity["Activity agent<br/>[trip_workflow.py]"]
  node_mock_apis["Booking APIs<br/>[trip_mock_apis.py]"]
  node_verifier["Budget verifier<br/>[trip_workflow.py]"]
  node_checkout["Checkout<br/>[trip_workflow.py]"]
  node_digest["Trip Digest<br/>[trip_workflow.py]"]
end

subgraph group_state["Shared state and failure controls"]
  node_blackboard[("Shared blackboard<br/>[blackboard.py]")]
  node_failure_config["Failure controls"]
  node_json_parser["JSON response parser<br/>[trip_json.py]"]
end

subgraph group_checks["Result checking"]
  node_hallucination_check["Hallucination checker"]
end

node_customer(("Trip requester"))
node_ollama["Ollama service"]
node_trip_result["Trip result"]

node_customer -->|"submits request"| node_runner
node_runner -->|"configures failures"| node_failure_config
node_runner -->|"runs workflow"| node_engine
node_runner -->|"builds stages"| node_supervisor
node_engine -->|"runs agents"| node_agent
node_agent -->|"sends prompts"| node_ollama
node_supervisor -->|"writes brief"| node_blackboard
node_flight -->|"reads and writes"| node_blackboard
node_hotel -->|"reads and writes"| node_blackboard
node_activity -->|"reads and writes"| node_blackboard
node_flight -->|"searches and books"| node_mock_apis
node_hotel -->|"searches and books"| node_mock_apis
node_activity -->|"searches and books"| node_mock_apis
node_flight -->|"parses response"| node_json_parser
node_hotel -->|"parses response"| node_json_parser
node_activity -->|"parses response"| node_json_parser
node_verifier -->|"reads and writes"| node_blackboard
node_checkout -->|"reads and writes"| node_blackboard
node_digest -->|"reads and writes"| node_blackboard
node_runner -->|"checks digest"| node_hallucination_check
node_runner -->|"reads result"| node_blackboard
node_blackboard -->|"provides record"| node_trip_result
node_digest -->|"produces summary"| node_trip_result
node_runner -->|"prints results"| node_trip_result

click node_runner "https://github.com/dumindi18/tripsupervisor/blob/main/run_trip_supervisor.py"
click node_engine "https://github.com/dumindi18/tripsupervisor/blob/main/workflow.py"
click node_agent "https://github.com/dumindi18/tripsupervisor/blob/main/agent.py"
click node_supervisor "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_flight "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_hotel "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_activity "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_mock_apis "https://github.com/dumindi18/tripsupervisor/blob/main/trip_mock_apis.py"
click node_verifier "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_checkout "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_digest "https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py"
click node_blackboard "https://github.com/dumindi18/tripsupervisor/blob/main/blackboard.py"
click node_failure_config "https://github.com/dumindi18/tripsupervisor/blob/main/trip_failure_config.py"
click node_json_parser "https://github.com/dumindi18/tripsupervisor/blob/main/trip_json.py"
click node_hallucination_check "https://github.com/dumindi18/tripsupervisor/blob/main/trip_hallucination.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_engine,node_agent toneBlue
class node_supervisor,node_flight,node_hotel,node_activity,node_mock_apis,node_verifier,node_checkout,node_digest toneAmber
class node_blackboard,node_failure_config,node_json_parser,node_customer toneMint
class node_hallucination_check toneRose
class node_ollama,node_trip_result toneIndigo
```

## Components

### Workflow orchestration

- [Scenario runner](https://github.com/dumindi18/tripsupervisor/blob/main/run_trip_supervisor.py): `run_trip_supervisor.py`
- [DAG engine](https://github.com/dumindi18/tripsupervisor/blob/main/workflow.py): `workflow.py`
- [LLM agent](https://github.com/dumindi18/tripsupervisor/blob/main/agent.py): `agent.py`

### Trip booking stages

- [Trip supervisor](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`
- [Flight agent](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`
- [Hotel agent](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`
- [Activity agent](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`
- [Booking APIs](https://github.com/dumindi18/tripsupervisor/blob/main/trip_mock_apis.py): `trip_mock_apis.py`
- [Budget verifier](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`
- [Checkout](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`
- [Trip Digest](https://github.com/dumindi18/tripsupervisor/blob/main/trip_workflow.py): `trip_workflow.py`

### Shared state and failure controls

- [Shared blackboard](https://github.com/dumindi18/tripsupervisor/blob/main/blackboard.py): `blackboard.py`
- [Failure controls](https://github.com/dumindi18/tripsupervisor/blob/main/trip_failure_config.py): `trip_failure_config.py`
- [JSON response parser](https://github.com/dumindi18/tripsupervisor/blob/main/trip_json.py): `trip_json.py`

### Result checking

- [Hallucination checker](https://github.com/dumindi18/tripsupervisor/blob/main/trip_hallucination.py): `trip_hallucination.py`

### Other components

- **Trip requester**
- **Ollama service**
- **Trip result**

## Connections

- Trip requester → Scenario runner: submits request (evidence: `run_trip_supervisor.py`)
- Scenario runner → Failure controls: configures failures (evidence: `run_trip_supervisor.py`)
- Scenario runner → DAG engine: runs workflow (evidence: `run_trip_supervisor.py`)
- Scenario runner → Trip supervisor: builds stages (evidence: `run_trip_supervisor.py`)
- DAG engine → LLM agent: runs agents (evidence: `workflow.py`)
- LLM agent → Ollama service: sends prompts (evidence: `agent.py`)
- Trip supervisor → Shared blackboard: writes brief (evidence: `trip_workflow.py`)
- Flight agent → Shared blackboard: reads and writes (evidence: `trip_workflow.py`)
- Hotel agent → Shared blackboard: reads and writes (evidence: `trip_workflow.py`)
- Activity agent → Shared blackboard: reads and writes (evidence: `trip_workflow.py`)
- Flight agent → Booking APIs: searches and books (evidence: `trip_workflow.py`)
- Hotel agent → Booking APIs: searches and books (evidence: `trip_workflow.py`)
- Activity agent → Booking APIs: searches and books (evidence: `trip_workflow.py`)
- Flight agent → JSON response parser: parses response (evidence: `trip_workflow.py`)
- Hotel agent → JSON response parser: parses response (evidence: `trip_workflow.py`)
- Activity agent → JSON response parser: parses response (evidence: `trip_workflow.py`)
- Budget verifier → Shared blackboard: reads and writes (evidence: `trip_workflow.py`)
- Checkout → Shared blackboard: reads and writes (evidence: `trip_workflow.py`)
- Trip Digest → Shared blackboard: reads and writes (evidence: `trip_workflow.py`)
- Scenario runner → Hallucination checker: checks digest (evidence: `run_trip_supervisor.py`)
- Scenario runner → Shared blackboard: reads result (evidence: `run_trip_supervisor.py`)
- Shared blackboard → Trip result: provides record
- Trip Digest → Trip result: produces summary (evidence: `trip_workflow.py`)
- Scenario runner → Trip result: prints results (evidence: `run_trip_supervisor.py`)
