# yinon-gold/llms-in-wds-modeling architecture

> Architecture diagram of the GitHub repository yinon-gold/llms-in-wds-modeling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yinon-gold/llms-in-wds-modeling
- Repository: https://github.com/yinon-gold/llms-in-wds-modeling

## Overview

This repository is a research-oriented assistant for water-distribution modeling: an engineer’s question is answered by retrieving EPyT documentation, generating and reviewing code, then executing it against an EPANET network. The agent, retrieval strategies, model adapter, and execution utilities are supported by sampled source; the README documents the broader capabilities and test workflows. Some prompt/evaluation wiring and the documentation corpus are not present in the supplied excerpts or tree, so those relationships are not inferred.

Main entry points: [`llm_epanet/models/agent.py`](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/agent.py) (EPANET agent), [`llm_epanet/models/retriever.py`](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/retriever.py) (Retriever strategies), [`llm_epanet/models/llm.py`](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/llm.py) (Language model adapter), [`llm_epanet/utils/code_execution.py`](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/code_execution.py) (Code execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent workflow"]
  node_agent["EPANET agent<br/>[agent.py]"]
  node_prompts["Task prompts<br/>[prompts.py]"]
  node_resultmodel["Agent result models<br/>[data_model.py]"]
end

subgraph group_retrieval["Documentation retrieval"]
  node_retriever["Retriever strategies<br/>[retriever.py]"]
  node_bm25["BM25 scoring<br/>[bm25retriever.py]"]
  node_vector[("FAISS index<br/>[vdb.py]")]
  node_docstore["EPyT documentation<br/>[retriever.py]"]
end

subgraph group_runtime["Model and execution"]
  node_language["Language model adapter<br/>[llm.py]"]
  node_execution["Code execution<br/>[code_execution.py]"]
  node_settings["API settings<br/>[settings.py]"]
end

subgraph group_domain["Water modeling"]
  node_queries["Water queries<br/>[queries.py]"]
  node_network["EPANET network files"]
end

node_engineer(("Water engineer"))
node_openrouter["OpenRouter API"]
node_anthropic["Anthropic API"]
node_sandbox["Python sandbox"]
node_embedding["Embedding providers"]
node_epyt["EPyT / EPANET"]

node_engineer -->|"submits question"| node_agent
node_agent -->|"retrieves context"| node_retriever
node_retriever -->|"uses keyword search"| node_bm25
node_retriever -->|"loads vector index"| node_vector
node_retriever -->|"reads documents"| node_docstore
node_agent -->|"requests generation"| node_language
node_agent -->|"runs generated code"| node_execution
node_agent -->|"returns result"| node_resultmodel
node_language -->|"reads credentials"| node_settings
node_language -->|"sends completion"| node_openrouter
node_language -.->|"fallback attempt"| node_anthropic
node_retriever -->|"requests embeddings"| node_embedding
node_execution -->|"runs isolated code"| node_sandbox
node_execution -->|"executes EPyT code"| node_epyt
node_engineer -->|"selects network"| node_network
node_agent -.->|"uses task guidance"| node_prompts
node_queries -->|"names test networks"| node_network

click node_agent "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/agent.py"
click node_queries "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/data/queries.py"
click node_prompts "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/prompts.py"
click node_retriever "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/retriever.py"
click node_bm25 "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/bm25retriever.py"
click node_vector "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/vdb.py"
click node_docstore "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/retriever.py"
click node_language "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/llm.py"
click node_execution "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/code_execution.py"
click node_resultmodel "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/data_model.py"
click node_settings "https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/settings.py"
click node_network "https://github.com/yinon-gold/llms-in-wds-modeling/tree/main/networks"

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_agent,node_prompts,node_resultmodel toneBlue
class node_retriever,node_bm25,node_vector,node_docstore toneAmber
class node_language,node_execution,node_settings,node_openrouter,node_anthropic toneMint
class node_queries,node_network toneRose
class node_engineer,node_sandbox,node_embedding,node_epyt toneIndigo
```

## Components

### Agent workflow

- [EPANET agent](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/agent.py): `llm_epanet/models/agent.py`
- [Task prompts](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/prompts.py): `llm_epanet/utils/prompts.py`
- [Agent result models](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/data_model.py): `llm_epanet/utils/data_model.py`

### Documentation retrieval

- [Retriever strategies](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/retriever.py): `llm_epanet/models/retriever.py`
- [BM25 scoring](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/bm25retriever.py): `llm_epanet/models/bm25retriever.py`
- [FAISS index](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/vdb.py): `llm_epanet/models/vdb.py`
- [EPyT documentation](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/retriever.py): `llm_epanet/models/retriever.py`

### Model and execution

- [Language model adapter](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/models/llm.py): `llm_epanet/models/llm.py`
- [Code execution](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/code_execution.py): `llm_epanet/utils/code_execution.py`
- [API settings](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/utils/settings.py): `llm_epanet/utils/settings.py`

### Water modeling

- [Water queries](https://github.com/yinon-gold/llms-in-wds-modeling/blob/main/llm_epanet/data/queries.py): `llm_epanet/data/queries.py`
- [EPANET network files](https://github.com/yinon-gold/llms-in-wds-modeling/tree/main/networks): `networks`

### Other components

- **Water engineer**
- **OpenRouter API**
- **Anthropic API**
- **Python sandbox**
- **Embedding providers**
- **EPyT / EPANET**

## Connections

- Water engineer → EPANET agent: submits question (evidence: `README.md`)
- EPANET agent → Retriever strategies: retrieves context (evidence: `llm_epanet/models/agent.py`)
- Retriever strategies → BM25 scoring: uses keyword search (evidence: `llm_epanet/models/retriever.py`)
- Retriever strategies → FAISS index: loads vector index (evidence: `llm_epanet/models/retriever.py`)
- Retriever strategies → EPyT documentation: reads documents (evidence: `llm_epanet/models/retriever.py`)
- EPANET agent → Language model adapter: requests generation (evidence: `llm_epanet/models/agent.py`)
- EPANET agent → Code execution: runs generated code (evidence: `llm_epanet/models/agent.py`)
- EPANET agent → Agent result models: returns result (evidence: `llm_epanet/models/agent.py`)
- Language model adapter → API settings: reads credentials (evidence: `llm_epanet/models/llm.py`)
- Language model adapter → OpenRouter API: sends completion (evidence: `llm_epanet/models/llm.py`)
- Language model adapter → Anthropic API: fallback attempt (evidence: `llm_epanet/models/llm.py`)
- Retriever strategies → Embedding providers: requests embeddings (evidence: `llm_epanet/models/retriever.py`)
- Code execution → Python sandbox: runs isolated code (evidence: `llm_epanet/utils/code_execution.py`)
- Code execution → EPyT / EPANET: executes EPyT code (evidence: `llm_epanet/utils/code_execution.py`)
- Water engineer → EPANET network files: selects network (evidence: `README.md`)
- EPANET agent → Task prompts: uses task guidance
- Water queries → EPANET network files: names test networks (evidence: `llm_epanet/data/queries.py`)
