# tonyxianyuan/hk-llm-investor-lab architecture

> Architecture diagram of the GitHub repository tonyxianyuan/hk-llm-investor-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonyxianyuan/hk-llm-investor-lab
- Repository: https://github.com/tonyxianyuan/hk-llm-investor-lab

## Overview

LLM Trading Lab preserves a live micro-cap experiment and its audit trail while also containing an IPO-focused, multi-model experiment workflow. In the IPO workflow, scheduled runs assemble research or daily prompts, gather and format candidate/company data, collect model orders, filter them against constraints, and save reports, orders, and sentiment through LIBB. The micro-cap side records portfolio and trade history and provides accounting and performance analysis. README documents live execution, stop-loss enforcement, benchmarks, and risk metrics; their detailed implementation is not fully shown in the sampled source.

Main entry points: [`Experiments/multi_model_ipo/workflow.py`](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/workflow.py) (Run Workflow), [`Experiments/multi_model_ipo/prompts/prompt_assembly.py`](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/prompt_assembly.py) (Prompt Assembly), [`Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/fetching.py`](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/fetching.py) (Market Data Fetching), [`Experiments/chatgpt_micro-cap/scripts/processing/trading_script.py`](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/processing/trading_script.py) (Trading Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ipo["IPO Experiment"]
  node_workflow["Run Workflow<br/>[workflow.py]"]
  node_libb["LIBB Model"]
  node_order_check["Order Verification"]
  node_csv_conversion["CSV Conversion<br/>[csv_conversion.py]"]
end

subgraph group_prompts["Prompt Construction"]
  node_prompt_models["Prompt Models<br/>[prompt_models.py]"]
  node_assembly["Prompt Assembly<br/>[prompt_assembly.py]"]
  node_daily_prompt["Daily Prompt<br/>[daily_prompt.py]"]
  node_deep_prompt["Research Prompt"]
  node_starting_prompt["Starting Prompt<br/>[starting_prompt.py]"]
end

subgraph group_research["Market Research"]
  node_candidate_data["Candidate Research<br/>[main_functions.py]"]
  node_fetching["Market Data Fetching<br/>[fetching.py]"]
  node_data_utilities["Data Formatting<br/>[utilities.py]"]
  node_data_config["Research Config<br/>[config.py]"]
  node_market_services["Market Data Services"]
end

subgraph group_micro["Micro-Cap Experiment"]
  node_micro_engine["Trading Engine<br/>[trading_script.py]"]
  node_portfolio_process["Portfolio Processing"]
  node_trade_log[("Trade Log<br/>[Trade Log.csv]")]
  node_daily_accounting[("Daily Accounting<br/>[Daily Updates.csv]")]
  node_artifacts["Research Archive"]
end

subgraph group_analysis["Portfolio Analytics"]
  node_analytics_data["Analytics Data<br/>[data_helper.py]"]
  node_benchmark_chart["Benchmark Analysis"]
  node_performance_metrics["Performance Metrics<br/>[load_dataV3.py]"]
  node_episode_metric["Episode PCR<br/>[episode_pcr.py]"]
  node_charts["Portfolio Charts"]
  node_evaluation["Experiment Evaluation"]
end

node_operator(("Experiment Operator"))
node_model_service["LLM Providers"]
node_market_data_service["Financial Data APIs"]

node_operator -->|"starts runs"| node_workflow
node_workflow -->|"selects flow"| node_prompt_models
node_workflow -->|"filters orders"| node_order_check
node_workflow -->|"converts records"| node_csv_conversion
node_workflow -->|"runs models"| node_libb
node_workflow -.->|"requests model output"| node_model_service
node_workflow -->|"builds prompts"| node_assembly
node_prompt_models -->|"uses assembly"| node_assembly
node_assembly -->|"uses daily template"| node_daily_prompt
node_assembly -->|"uses research template"| node_deep_prompt
node_assembly -->|"uses research data"| node_candidate_data
node_prompt_models -->|"uses starting template"| node_starting_prompt
node_candidate_data -->|"enriches candidates"| node_fetching
node_candidate_data -->|"formats eligibility"| node_data_utilities
node_fetching -->|"uses helpers"| node_data_utilities
node_data_config -->|"configures fetching"| node_fetching
node_fetching -.->|"fetches company data"| node_market_services
node_order_check -->|"checks IPO data"| node_fetching
node_workflow -.->|"runs trading"| node_micro_engine
node_micro_engine -.->|"records trades"| node_trade_log
node_micro_engine -.->|"updates portfolio"| node_daily_accounting
node_portfolio_process -->|"delegates to"| node_micro_engine
node_analytics_data -->|"reads trades"| node_trade_log
node_analytics_data -->|"reads balances"| node_daily_accounting
node_benchmark_chart -->|"loads portfolio totals"| node_analytics_data
node_benchmark_chart -->|"downloads benchmarks"| node_market_data_service
node_charts -->|"loads datasets"| node_analytics_data
node_operator -->|"reviews decisions"| node_artifacts
node_operator -->|"reviews results"| node_evaluation
node_operator -.->|"analyzes returns"| node_performance_metrics
node_operator -.->|"analyzes episodes"| node_episode_metric

click node_workflow "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/workflow.py"
click node_prompt_models "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/prompt_models.py"
click node_assembly "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/prompt_assembly.py"
click node_daily_prompt "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/daily_prompt.py"
click node_deep_prompt "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/deep_research_prompt.py"
click node_starting_prompt "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/starting_prompt.py"
click node_candidate_data "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/main_functions.py"
click node_fetching "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/fetching.py"
click node_data_utilities "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/utilities.py"
click node_data_config "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/config.py"
click node_order_check "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/miscellaneous/order_verification.py"
click node_csv_conversion "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/miscellaneous/csv_conversion.py"
click node_micro_engine "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/processing/trading_script.py"
click node_portfolio_process "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/processing/ProcessPortfolio.py"
click node_trade_log "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/csv_files/Trade%20Log.csv"
click node_daily_accounting "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/csv_files/Daily%20Updates.csv"
click node_analytics_data "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/graphing/data_helper.py"
click node_benchmark_chart "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/graphing/equity_vs_baseline.py"
click node_performance_metrics "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/metrics/load_dataV3.py"
click node_episode_metric "https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/metrics/episode_pcr.py"
click node_charts "https://github.com/tonyxianyuan/hk-llm-investor-lab/tree/main/Experiments/chatgpt_micro-cap/graphing"
click node_artifacts "https://github.com/tonyxianyuan/hk-llm-investor-lab/tree/main/Experiments/chatgpt_micro-cap/collected_artifacts"
click node_evaluation "https://github.com/tonyxianyuan/hk-llm-investor-lab/tree/main/Experiments/chatgpt_micro-cap/evaluation"

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_workflow,node_libb,node_order_check,node_csv_conversion toneBlue
class node_prompt_models,node_assembly,node_daily_prompt,node_deep_prompt,node_starting_prompt toneAmber
class node_candidate_data,node_fetching,node_data_utilities,node_data_config,node_market_services,node_market_data_service toneMint
class node_micro_engine,node_portfolio_process,node_trade_log,node_daily_accounting,node_artifacts toneRose
class node_analytics_data,node_benchmark_chart,node_performance_metrics,node_episode_metric,node_charts,node_evaluation,node_operator,node_model_service toneIndigo
```

## Components

### IPO Experiment

- [Run Workflow](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/workflow.py): `Experiments/multi_model_ipo/workflow.py`
- **LIBB Model**
- [Order Verification](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/miscellaneous/order_verification.py): `Experiments/multi_model_ipo/miscellaneous/order_verification.py`
- [CSV Conversion](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/miscellaneous/csv_conversion.py): `Experiments/multi_model_ipo/miscellaneous/csv_conversion.py`

### Prompt Construction

- [Prompt Models](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/prompt_models.py): `Experiments/multi_model_ipo/prompt_orchestration/prompt_models.py`
- [Prompt Assembly](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/prompt_assembly.py): `Experiments/multi_model_ipo/prompts/prompt_assembly.py`
- [Daily Prompt](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/daily_prompt.py): `Experiments/multi_model_ipo/prompts/daily_prompt.py`
- [Research Prompt](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/deep_research_prompt.py): `Experiments/multi_model_ipo/prompts/deep_research_prompt.py`
- [Starting Prompt](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompts/starting_prompt.py): `Experiments/multi_model_ipo/prompts/starting_prompt.py`

### Market Research

- [Candidate Research](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/main_functions.py): `Experiments/multi_model_ipo/prompt_orchestration/main_functions.py`
- [Market Data Fetching](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/fetching.py): `Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/fetching.py`
- [Data Formatting](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/utilities.py): `Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/utilities.py`
- [Research Config](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/config.py): `Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/config.py`
- **Market Data Services**

### Micro-Cap Experiment

- [Trading Engine](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/processing/trading_script.py): `Experiments/chatgpt_micro-cap/scripts/processing/trading_script.py`
- [Portfolio Processing](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/processing/ProcessPortfolio.py): `Experiments/chatgpt_micro-cap/scripts/processing/ProcessPortfolio.py`
- [Trade Log](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/csv_files/Trade%20Log.csv): `Experiments/chatgpt_micro-cap/csv_files/Trade Log.csv`
- [Daily Accounting](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/csv_files/Daily%20Updates.csv): `Experiments/chatgpt_micro-cap/csv_files/Daily Updates.csv`
- [Research Archive](https://github.com/tonyxianyuan/hk-llm-investor-lab/tree/main/Experiments/chatgpt_micro-cap/collected_artifacts): `Experiments/chatgpt_micro-cap/collected_artifacts`

### Portfolio Analytics

- [Analytics Data](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/graphing/data_helper.py): `Experiments/chatgpt_micro-cap/graphing/data_helper.py`
- [Benchmark Analysis](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/graphing/equity_vs_baseline.py): `Experiments/chatgpt_micro-cap/graphing/equity_vs_baseline.py`
- [Performance Metrics](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/metrics/load_dataV3.py): `Experiments/chatgpt_micro-cap/scripts/metrics/load_dataV3.py`
- [Episode PCR](https://github.com/tonyxianyuan/hk-llm-investor-lab/blob/main/Experiments/chatgpt_micro-cap/scripts/metrics/episode_pcr.py): `Experiments/chatgpt_micro-cap/scripts/metrics/episode_pcr.py`
- [Portfolio Charts](https://github.com/tonyxianyuan/hk-llm-investor-lab/tree/main/Experiments/chatgpt_micro-cap/graphing): `Experiments/chatgpt_micro-cap/graphing`
- [Experiment Evaluation](https://github.com/tonyxianyuan/hk-llm-investor-lab/tree/main/Experiments/chatgpt_micro-cap/evaluation): `Experiments/chatgpt_micro-cap/evaluation`

### Other components

- **Experiment Operator**
- **LLM Providers**
- **Financial Data APIs**

## Connections

- Experiment Operator → Run Workflow: starts runs (evidence: `Experiments/multi_model_ipo/workflow.py`)
- Run Workflow → Prompt Models: selects flow (evidence: `Experiments/multi_model_ipo/workflow.py`)
- Run Workflow → Order Verification: filters orders (evidence: `Experiments/multi_model_ipo/workflow.py`)
- Run Workflow → CSV Conversion: converts records (evidence: `Experiments/multi_model_ipo/workflow.py`)
- Run Workflow → LIBB Model: runs models (evidence: `Experiments/multi_model_ipo/workflow.py`)
- Run Workflow → LLM Providers: requests model output
- Run Workflow → Prompt Assembly: builds prompts (evidence: `Experiments/multi_model_ipo/workflow.py`)
- Prompt Models → Prompt Assembly: uses assembly (evidence: `Experiments/multi_model_ipo/prompt_orchestration/prompt_models.py`)
- Prompt Assembly → Daily Prompt: uses daily template (evidence: `Experiments/multi_model_ipo/prompts/prompt_assembly.py`)
- Prompt Assembly → Research Prompt: uses research template (evidence: `Experiments/multi_model_ipo/prompts/prompt_assembly.py`)
- Prompt Assembly → Candidate Research: uses research data (evidence: `Experiments/multi_model_ipo/prompts/prompt_assembly.py`)
- Prompt Models → Starting Prompt: uses starting template (evidence: `Experiments/multi_model_ipo/prompt_orchestration/prompt_models.py`)
- Candidate Research → Market Data Fetching: enriches candidates (evidence: `Experiments/multi_model_ipo/prompt_orchestration/main_functions.py`)
- Candidate Research → Data Formatting: formats eligibility (evidence: `Experiments/multi_model_ipo/prompt_orchestration/main_functions.py`)
- Market Data Fetching → Data Formatting: uses helpers (evidence: `Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/fetching.py`)
- Research Config → Market Data Fetching: configures fetching (evidence: `Experiments/multi_model_ipo/prompt_orchestration/get_prompt_data/config.py`)
- Market Data Fetching → Market Data Services: fetches company data
- Order Verification → Market Data Fetching: checks IPO data (evidence: `Experiments/multi_model_ipo/miscellaneous/order_verification.py`)
- Run Workflow → Trading Engine: runs trading
- Trading Engine → Trade Log: records trades
- Trading Engine → Daily Accounting: updates portfolio
- Portfolio Processing → Trading Engine: delegates to (evidence: `Experiments/chatgpt_micro-cap/scripts/processing/ProcessPortfolio.py`)
- Analytics Data → Trade Log: reads trades (evidence: `Experiments/chatgpt_micro-cap/graphing/data_helper.py`)
- Analytics Data → Daily Accounting: reads balances (evidence: `Experiments/chatgpt_micro-cap/graphing/data_helper.py`)
- Benchmark Analysis → Analytics Data: loads portfolio totals (evidence: `Experiments/chatgpt_micro-cap/graphing/equity_vs_baseline.py`)
- Benchmark Analysis → Financial Data APIs: downloads benchmarks (evidence: `Experiments/chatgpt_micro-cap/graphing/equity_vs_baseline.py`)
- Portfolio Charts → Analytics Data: loads datasets (evidence: `Experiments/chatgpt_micro-cap/graphing/daily_returns.py`)
- Experiment Operator → Research Archive: reviews decisions (evidence: `README.md`)
- Experiment Operator → Experiment Evaluation: reviews results (evidence: `README.md`)
- Experiment Operator → Performance Metrics: analyzes returns
- Experiment Operator → Episode PCR: analyzes episodes
