# s-nitya/perishable-goods-paper architecture

> Architecture diagram of the GitHub repository s-nitya/perishable-goods-paper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s-nitya/perishable-goods-paper
- Repository: https://github.com/s-nitya/perishable-goods-paper

## Overview

This repository contains several generations of an LLM-based perishable-goods pricing simulator. The documented benchmark workflow is a runner pairing catalog items and private buyer states, executing each item encounter through a market environment under either hierarchical seller reasoning or LinearDecay, then summarizing outcomes and token use. The graph emphasizes the revised benchmark and preserves the earlier simulator implementations. Internal orchestration details for the revised MAS are based on the README; unsampled source limits finer call-flow claims.

Main entry points: [`kanishka_revised_mas/runner.py`](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/runner.py) (Benchmark runner), [`kanishka_revised_mas/environment.py`](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/environment.py) (Negotiation and expiry), [`kanishka_revised_mas/mas_agents.py`](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py) (Hierarchical seller MAS), [`final_architecture/environment.py`](https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/environment.py) (Final environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_benchmark["Revised benchmark"]
  node_benchmark_runner["Benchmark runner<br/>[runner.py]"]
  node_catalog["Product catalog<br/>[catalog.py]"]
  node_buyer["Private-state buyer<br/>[buyer.py]"]
  node_market["Negotiation and expiry<br/>[environment.py]"]
  node_results["Trial metrics<br/>[runner.py]"]
end

subgraph group_seller["Seller policies"]
  node_mas["Hierarchical seller MAS<br/>[mas_agents.py]"]
  node_strategic["Strategic pricing debate<br/>[mas_agents.py]"]
  node_tactical["Tactical negotiation<br/>[mas_agents.py]"]
  node_linear["LinearDecay policy<br/>[linear_decay.py]"]
end

subgraph group_earlier["Earlier simulators"]
  node_final_env["Final environment<br/>[environment.py]"]
  node_final_agents["Final agent set<br/>[agents.py]"]
  node_final_baseline["Final baselines<br/>[baselines.py]"]
  node_final_llm["Final LLM client<br/>[llm_client.py]"]
  node_hive_main["Hive benchmark entry<br/>[main.py]"]
  node_hive_env["Hive environment<br/>[environment.py]"]
  node_hive_agents["Hive agents<br/>[agents.py]"]
  node_hive_visualizer["Hive results visualizer<br/>[visualizer.py]"]
  node_hive_llm["Hive LLM client<br/>[llm_client.py]"]
  node_src_main["Alternate benchmark entry<br/>[main.py]"]
  node_src_env["Alternate environment<br/>[environment.py]"]
  node_src_agents["Alternate agents<br/>[agents.py]"]
  node_src_visualizer["Alternate visualizer<br/>[visualizer.py]"]
  node_src_llm["Alternate LLM client<br/>[llm_client.py]"]
end

subgraph group_services["Model services"]
  node_revised_llm["Tracked LLM client<br/>[llm_client.py]"]
  node_llm_provider["LLM API providers"]
end

node_researcher(("Benchmark operator"))

node_researcher -.->|"starts"| node_benchmark_runner
node_benchmark_runner -->|"loads"| node_catalog
node_benchmark_runner -->|"runs encounters"| node_market
node_benchmark_runner -->|"uses buyer states"| node_buyer
node_market -->|"requests decisions"| node_buyer
node_market -->|"invokes seller"| node_mas
node_market -->|"evaluates offers"| node_linear
node_benchmark_runner -->|"summarizes trials"| node_results
node_mas -.->|"formulates policy"| node_strategic
node_mas -.->|"coordinates negotiation"| node_tactical
node_benchmark_runner -->|"creates client"| node_revised_llm
node_revised_llm -->|"sends API requests"| node_llm_provider
node_final_env -->|"uses agents"| node_final_agents
node_final_env -->|"uses baseline"| node_final_baseline
node_final_agents -->|"calls client"| node_final_llm
node_hive_main -->|"runs simulation"| node_hive_env
node_hive_env -->|"uses agents"| node_hive_agents
node_hive_agents -->|"calls client"| node_hive_llm
node_hive_main -->|"displays results"| node_hive_visualizer
node_src_main -->|"runs simulation"| node_src_env
node_src_env -->|"uses agents"| node_src_agents
node_src_agents -->|"calls client"| node_src_llm
node_src_main -->|"displays results"| node_src_visualizer

click node_benchmark_runner "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/runner.py"
click node_catalog "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/catalog.py"
click node_buyer "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/buyer.py"
click node_market "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/environment.py"
click node_results "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/runner.py"
click node_mas "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py"
click node_strategic "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py"
click node_tactical "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py"
click node_linear "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/linear_decay.py"
click node_revised_llm "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/llm_client.py"
click node_final_env "https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/environment.py"
click node_final_agents "https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/agents.py"
click node_final_baseline "https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/baselines.py"
click node_final_llm "https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/llm_client.py"
click node_hive_main "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/main.py"
click node_hive_env "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/environment.py"
click node_hive_agents "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/agents.py"
click node_hive_visualizer "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/visualizer.py"
click node_hive_llm "https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/llm_client.py"
click node_src_main "https://github.com/s-nitya/perishable-goods-paper/blob/main/src/main.py"
click node_src_env "https://github.com/s-nitya/perishable-goods-paper/blob/main/src/environment.py"
click node_src_agents "https://github.com/s-nitya/perishable-goods-paper/blob/main/src/agents.py"
click node_src_visualizer "https://github.com/s-nitya/perishable-goods-paper/blob/main/src/visualizer.py"
click node_src_llm "https://github.com/s-nitya/perishable-goods-paper/blob/main/src/llm_client.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_benchmark_runner,node_catalog,node_buyer,node_market,node_results toneBlue
class node_mas,node_strategic,node_tactical,node_linear toneAmber
class node_final_env,node_final_agents,node_final_baseline,node_final_llm,node_hive_main,node_hive_env,node_hive_agents,node_hive_visualizer,node_hive_llm,node_src_main,node_src_env,node_src_agents,node_src_visualizer,node_src_llm toneMint
class node_revised_llm,node_llm_provider toneRose
class node_researcher toneIndigo
```

## Components

### Revised benchmark

- [Benchmark runner](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/runner.py): `kanishka_revised_mas/runner.py`
- [Product catalog](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/catalog.py): `kanishka_revised_mas/catalog.py`
- [Private-state buyer](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/buyer.py): `kanishka_revised_mas/buyer.py`
- [Negotiation and expiry](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/environment.py): `kanishka_revised_mas/environment.py`
- [Trial metrics](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/runner.py): `kanishka_revised_mas/runner.py`

### Seller policies

- [Hierarchical seller MAS](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py): `kanishka_revised_mas/mas_agents.py`
- [Strategic pricing debate](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py): `kanishka_revised_mas/mas_agents.py`
- [Tactical negotiation](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/mas_agents.py): `kanishka_revised_mas/mas_agents.py`
- [LinearDecay policy](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/linear_decay.py): `kanishka_revised_mas/linear_decay.py`

### Earlier simulators

- [Final environment](https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/environment.py): `final_architecture/environment.py`
- [Final agent set](https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/agents.py): `final_architecture/agents.py`
- [Final baselines](https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/baselines.py): `final_architecture/baselines.py`
- [Final LLM client](https://github.com/s-nitya/perishable-goods-paper/blob/main/final_architecture/llm_client.py): `final_architecture/llm_client.py`
- [Hive benchmark entry](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/main.py): `kanishka_src/main.py`
- [Hive environment](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/environment.py): `kanishka_src/environment.py`
- [Hive agents](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/agents.py): `kanishka_src/agents.py`
- [Hive results visualizer](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/visualizer.py): `kanishka_src/visualizer.py`
- [Hive LLM client](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_src/llm_client.py): `kanishka_src/llm_client.py`
- [Alternate benchmark entry](https://github.com/s-nitya/perishable-goods-paper/blob/main/src/main.py): `src/main.py`
- [Alternate environment](https://github.com/s-nitya/perishable-goods-paper/blob/main/src/environment.py): `src/environment.py`
- [Alternate agents](https://github.com/s-nitya/perishable-goods-paper/blob/main/src/agents.py): `src/agents.py`
- [Alternate visualizer](https://github.com/s-nitya/perishable-goods-paper/blob/main/src/visualizer.py): `src/visualizer.py`
- [Alternate LLM client](https://github.com/s-nitya/perishable-goods-paper/blob/main/src/llm_client.py): `src/llm_client.py`

### Model services

- [Tracked LLM client](https://github.com/s-nitya/perishable-goods-paper/blob/main/kanishka_revised_mas/llm_client.py): `kanishka_revised_mas/llm_client.py`
- **LLM API providers**

### Other components

- **Benchmark operator**

## Connections

- Benchmark operator → Benchmark runner: starts
- Benchmark runner → Product catalog: loads (evidence: `kanishka_revised_mas/runner.py`)
- Benchmark runner → Negotiation and expiry: runs encounters (evidence: `kanishka_revised_mas/runner.py`)
- Benchmark runner → Private-state buyer: uses buyer states (evidence: `kanishka_revised_mas/runner.py`)
- Negotiation and expiry → Private-state buyer: requests decisions (evidence: `kanishka_revised_mas/environment.py`)
- Negotiation and expiry → Hierarchical seller MAS: invokes seller (evidence: `kanishka_revised_mas/environment.py`)
- Negotiation and expiry → LinearDecay policy: evaluates offers (evidence: `kanishka_revised_mas/environment.py`)
- Benchmark runner → Trial metrics: summarizes trials (evidence: `kanishka_revised_mas/runner.py`)
- Hierarchical seller MAS → Strategic pricing debate: formulates policy (evidence: `kanishka_revised_mas/mas_agents.py`)
- Hierarchical seller MAS → Tactical negotiation: coordinates negotiation (evidence: `kanishka_revised_mas/mas_agents.py`)
- Benchmark runner → Tracked LLM client: creates client (evidence: `kanishka_revised_mas/runner.py`)
- Tracked LLM client → LLM API providers: sends API requests (evidence: `kanishka_revised_mas/llm_client.py`)
- Final environment → Final agent set: uses agents (evidence: `final_architecture/environment.py`)
- Final environment → Final baselines: uses baseline (evidence: `final_architecture/environment.py`)
- Final agent set → Final LLM client: calls client (evidence: `final_architecture/agents.py`)
- Hive benchmark entry → Hive environment: runs simulation (evidence: `kanishka_src/main.py`)
- Hive environment → Hive agents: uses agents (evidence: `kanishka_src/environment.py`)
- Hive agents → Hive LLM client: calls client (evidence: `kanishka_src/agents.py`)
- Hive benchmark entry → Hive results visualizer: displays results (evidence: `kanishka_src/main.py`)
- Alternate benchmark entry → Alternate environment: runs simulation (evidence: `src/main.py`)
- Alternate environment → Alternate agents: uses agents (evidence: `src/environment.py`)
- Alternate agents → Alternate LLM client: calls client (evidence: `src/agents.py`)
- Alternate benchmark entry → Alternate visualizer: displays results (evidence: `src/main.py`)