# simonbayl/agentic_optimization_tool architecture

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

- Interactive diagram: https://gitdiagram.com/simonbayl/agentic_optimization_tool
- Repository: https://github.com/simonbayl/agentic_optimization_tool

## Overview

This is a conversational operations-research agent: a user describes a decision problem, answers targeted questions, supplies data, and receives a solved linear optimization model and a business-language explanation. The turn-based LangGraph orchestrator coordinates understanding, completeness checks, clarification, model generation and execution, editing, and explanation. The README documents scenario comparisons and relaxations; unsampled implementations are represented by their existing directories where necessary. Edges rely on README statements, the shown orchestrator excerpt, or SOURCE INDEX references; unsampled connections are omitted where ownership is unclear.

Main entry points: [`orchestrator/graph_orchestrator.py`](https://github.com/simonbayl/agentic_optimization_tool/blob/main/orchestrator/graph_orchestrator.py) (Turn orchestrator), [`agentic_tools/model/builder.py`](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/builder.py) (Code generation), [`interactions/ConversationSession.py`](https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/ConversationSession.py) (Conversation session), [`agentic_tools/explain/Explain.py`](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/Explain.py) (Result explanation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_terminal["Terminal interface<br/>[terminal.py]"]
  node_session["Conversation session"]
  node_schema["Data schema reader<br/>[data_schema.py]"]
  node_orchestrator["Turn orchestrator"]
end

subgraph group_formalization["Problem formalization"]
  node_understand["Business understanding<br/>[AgentUnderstand.py]"]
  node_business["Business specification"]
  node_complete["Model completion<br/>[AgentComplete.py]"]
  node_checker["Completeness checker<br/>[checker.py]"]
  node_clarify["Clarification policy<br/>[dialogue.py]"]
end

subgraph group_solve["Model and solve"]
  node_structure["Mathematical model"]
  node_builder["Code generation<br/>[builder.py]"]
  node_context["Generation context<br/>[context.py]"]
  node_validation["Model validation<br/>[validation.py]"]
  node_executor["Generated-code execution<br/>[executor.py]"]
  node_runner["Solver runner<br/>[runner.py]"]
end

subgraph group_insight["Results and editing"]
  node_editor["Model editing<br/>[AgentEdit.py]"]
  node_patch["Model patch<br/>[patch.py]"]
  node_explainer["Result explanation<br/>[Explain.py]"]
  node_margins["Constraint margins<br/>[margins.py]"]
  node_reports["Scenario reports<br/>[report.py]"]
end

subgraph group_shared["Shared state"]
  node_questions["Clarification state"]
  node_result["Optimization result"]
  node_state["Shared agent state<br/>[AgentState.py]"]
end

node_user(("User"))
node_files[("User data files")]
node_mistral(("Mistral API"))
node_ortools(("OR-Tools HiGHS"))

node_user -->|"sends request"| node_terminal
node_terminal -->|"forwards turn"| node_session
node_session -.->|"runs turn"| node_orchestrator
node_session -.->|"loads schema"| node_schema
node_files -->|"provides columns"| node_schema
node_orchestrator -->|"updates understanding"| node_understand
node_understand -.->|"requests interpretation"| node_mistral
node_understand -->|"returns specification"| node_business
node_orchestrator -.->|"completes model"| node_complete
node_orchestrator -->|"checks completeness"| node_checker
node_checker -->|"produces questions"| node_questions
node_orchestrator -.->|"applies question policy"| node_clarify
node_clarify -->|"updates questions"| node_questions
node_complete -.->|"formalizes problem"| node_structure
node_orchestrator -->|"builds model"| node_builder
node_builder -->|"prepares generation context"| node_context
node_builder -->|"validates generated code"| node_validation
node_builder -->|"executes generated code"| node_executor
node_builder -->|"uses model specification"| node_structure
node_executor -.->|"runs model"| node_runner
node_runner -.->|"solves optimization"| node_ortools
node_builder -->|"loads model data"| node_files
node_builder -->|"returns solve result"| node_result
node_orchestrator -->|"handles model edits"| node_editor
node_editor -->|"proposes patch"| node_patch
node_editor -->|"rebuilds after edit"| node_builder
node_orchestrator -->|"explains result"| node_explainer
node_orchestrator -->|"computes margins"| node_margins
node_explainer -.->|"requests explanation"| node_mistral
node_explainer -->|"interprets solution"| node_result
node_explainer -->|"includes scenarios"| node_reports
node_orchestrator -->|"routes shared state"| node_state
node_session -->|"maintains conversation"| node_state
node_orchestrator -.->|"returns reply"| node_terminal

click node_terminal "https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/terminal.py"
click node_session "https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/ConversationSession.py"
click node_schema "https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/data_schema.py"
click node_orchestrator "https://github.com/simonbayl/agentic_optimization_tool/blob/main/orchestrator/graph_orchestrator.py"
click node_understand "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/understand/AgentUnderstand.py"
click node_business "https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/BusinessProblemSpec.py"
click node_complete "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/completeness/AgentComplete.py"
click node_checker "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/completeness/checker.py"
click node_clarify "https://github.com/simonbayl/agentic_optimization_tool/blob/main/orchestrator/dialogue.py"
click node_questions "https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/ClarificationState.py"
click node_structure "https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/MathematicalStructure.py"
click node_builder "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/builder.py"
click node_context "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/context.py"
click node_validation "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/validation.py"
click node_executor "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/executor.py"
click node_runner "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/runner.py"
click node_result "https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/OptimisationResult.py"
click node_editor "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/edit/AgentEdit.py"
click node_patch "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/edit/patch.py"
click node_explainer "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/Explain.py"
click node_margins "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/margins.py"
click node_reports "https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/report.py"
click node_state "https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/AgentState.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_terminal,node_session,node_schema,node_orchestrator,node_user toneBlue
class node_understand,node_business,node_complete,node_checker,node_clarify,node_files toneAmber
class node_structure,node_builder,node_context,node_validation,node_executor,node_runner,node_mistral toneMint
class node_editor,node_patch,node_explainer,node_margins,node_reports toneRose
class node_questions,node_result,node_state,node_ortools toneIndigo
```

## Components

### Conversation

- [Terminal interface](https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/terminal.py): `interactions/terminal.py`
- [Conversation session](https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/ConversationSession.py): `interactions/ConversationSession.py`
- [Data schema reader](https://github.com/simonbayl/agentic_optimization_tool/blob/main/interactions/data_schema.py): `interactions/data_schema.py`
- [Turn orchestrator](https://github.com/simonbayl/agentic_optimization_tool/blob/main/orchestrator/graph_orchestrator.py): `orchestrator/graph_orchestrator.py`

### Problem formalization

- [Business understanding](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/understand/AgentUnderstand.py): `agentic_tools/understand/AgentUnderstand.py`
- [Business specification](https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/BusinessProblemSpec.py): `data_model/BusinessProblemSpec.py`
- [Model completion](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/completeness/AgentComplete.py): `agentic_tools/completeness/AgentComplete.py`
- [Completeness checker](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/completeness/checker.py): `agentic_tools/completeness/checker.py`
- [Clarification policy](https://github.com/simonbayl/agentic_optimization_tool/blob/main/orchestrator/dialogue.py): `orchestrator/dialogue.py`

### Model and solve

- [Mathematical model](https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/MathematicalStructure.py): `data_model/MathematicalStructure.py`
- [Code generation](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/builder.py): `agentic_tools/model/builder.py`
- [Generation context](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/context.py): `agentic_tools/model/context.py`
- [Model validation](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/validation.py): `agentic_tools/model/validation.py`
- [Generated-code execution](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/executor.py): `agentic_tools/model/executor.py`
- [Solver runner](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/model/runner.py): `agentic_tools/model/runner.py`

### Results and editing

- [Model editing](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/edit/AgentEdit.py): `agentic_tools/edit/AgentEdit.py`
- [Model patch](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/edit/patch.py): `agentic_tools/edit/patch.py`
- [Result explanation](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/Explain.py): `agentic_tools/explain/Explain.py`
- [Constraint margins](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/margins.py): `agentic_tools/explain/margins.py`
- [Scenario reports](https://github.com/simonbayl/agentic_optimization_tool/blob/main/agentic_tools/explain/report.py): `agentic_tools/explain/report.py`

### Shared state

- [Clarification state](https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/ClarificationState.py): `data_model/ClarificationState.py`
- [Optimization result](https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/OptimisationResult.py): `data_model/OptimisationResult.py`
- [Shared agent state](https://github.com/simonbayl/agentic_optimization_tool/blob/main/data_model/AgentState.py): `data_model/AgentState.py`

### Other components

- **User**
- **User data files**
- **Mistral API**
- **OR-Tools HiGHS**

## Connections

- User → Terminal interface: sends request (evidence: `README.md`)
- Terminal interface → Conversation session: forwards turn (evidence: `interactions/terminal.py`)
- Conversation session → Turn orchestrator: runs turn
- Conversation session → Data schema reader: loads schema
- User data files → Data schema reader: provides columns (evidence: `README.md`)
- Turn orchestrator → Business understanding: updates understanding (evidence: `orchestrator/graph_orchestrator.py`)
- Business understanding → Mistral API: requests interpretation
- Business understanding → Business specification: returns specification (evidence: `agentic_tools/understand/AgentUnderstand.py`)
- Turn orchestrator → Model completion: completes model (evidence: `orchestrator/graph_orchestrator.py`)
- Turn orchestrator → Completeness checker: checks completeness (evidence: `orchestrator/graph_orchestrator.py`)
- Completeness checker → Clarification state: produces questions (evidence: `agentic_tools/completeness/checker.py`)
- Turn orchestrator → Clarification policy: applies question policy (evidence: `orchestrator/graph_orchestrator.py`)
- Clarification policy → Clarification state: updates questions (evidence: `orchestrator/dialogue.py`)
- Model completion → Mathematical model: formalizes problem
- Turn orchestrator → Code generation: builds model (evidence: `orchestrator/graph_orchestrator.py`)
- Code generation → Generation context: prepares generation context (evidence: `agentic_tools/model/builder.py`)
- Code generation → Model validation: validates generated code (evidence: `agentic_tools/model/builder.py`)
- Code generation → Generated-code execution: executes generated code (evidence: `agentic_tools/model/builder.py`)
- Code generation → Mathematical model: uses model specification (evidence: `agentic_tools/model/builder.py`)
- Generated-code execution → Solver runner: runs model
- Solver runner → OR-Tools HiGHS: solves optimization
- Code generation → User data files: loads model data (evidence: `README.md`)
- Code generation → Optimization result: returns solve result (evidence: `agentic_tools/model/builder.py`)
- Turn orchestrator → Model editing: handles model edits (evidence: `orchestrator/graph_orchestrator.py`)
- Model editing → Model patch: proposes patch (evidence: `agentic_tools/edit/AgentEdit.py`)
- Model editing → Code generation: rebuilds after edit (evidence: `agentic_tools/edit/AgentEdit.py`)
- Turn orchestrator → Result explanation: explains result (evidence: `orchestrator/graph_orchestrator.py`)
- Turn orchestrator → Constraint margins: computes margins (evidence: `orchestrator/graph_orchestrator.py`)
- Result explanation → Mistral API: requests explanation
- Result explanation → Optimization result: interprets solution (evidence: `agentic_tools/explain/Explain.py`)
- Result explanation → Scenario reports: includes scenarios (evidence: `agentic_tools/explain/Explain.py`)
- Turn orchestrator → Shared agent state: routes shared state (evidence: `orchestrator/graph_orchestrator.py`)
- Conversation session → Shared agent state: maintains conversation (evidence: `interactions/ConversationSession.py`)
- Turn orchestrator → Terminal interface: returns reply
