# lyihub/liars-bar-llm architecture

> Architecture diagram of the GitHub repository lyihub/liars-bar-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lyihub/liars-bar-llm
- Repository: https://github.com/lyihub/liars-bar-llm

## Overview

- Game Engine Layer:
- game.py: The main entry point handling the game loop.
- player.py: Implements the LLM-based agent logic which makes decisions (e.g., choosing cards to play or challenging).
- llm_client.py: Manages the connection/configuration for making calls to external LLM APIs (using New API or One API as noted).
- multi_game_runner.py: Allows batch execution of multiple game rounds.
- game_record.py: Handles persistence of game data (saving and extracting game records as JSON).

- Analysis Tools Layer:
- game_analyze.py: Aggregates and prints overall game statistics.
- player_matchup_analyze.py: Extracts and analyzes game records of AI vs. AI matchups.
- json_convert.py: Converts game records from JSON files into human-readable text.

- Supporting/Data Storage:
- Demo Data Directories under demo_records:
▪ game_records: Raw JSON game logs.
▪ converted_game_records: Converted text versions of game records.
▪ matchup_records: Detailed matchup logs between specific AI models.
- prompt directory: Contains template texts used for shaping the LLM’s outputs.

##### Relationships and Data Flows
- Players created in player.py depend on prompts stored under the prompt folder; indicate a relationship between player.py and prompt templates.

##### Important Architectural Patterns
- Modular Design: Each script or module handles one specific responsibility (e.g., API wrapper, game record management, analysis/visualization), which helps with scaling or modifying specific components.
- Extensibility: The design supports easy addition of new AI models (players) or modifications to prompts by isolating them in their own modules and configuration—the prompt directory helps highlight this.

##### Relevant Technologies/Frameworks
- Python is the primary language.
- The project leverages the “New API” or a similar API management tool for unified LLM calls.
- Conda (or pip) is used for dependency management (e.g., openai package is required).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Game Engine Layer
    subgraph "Game Engine"
        a1["game.py"]:::gameEngine
        a2["player.py"]:::gameEngine
        a3["llm_client.py"]:::gameEngine
        a4["multi_game_runner.py"]:::gameEngine
        a5["game_record.py"]:::gameEngine
    end

    %% Supporting/Data Storage
    subgraph "Supporting/Data Storage"
        s1["Game Records (JSON)"]:::storage
        s2["Converted Game Records (Text)"]:::storage
        s3["Matchup Records"]:::storage
        s4["Prompt Templates"]:::storage
    end

    %% Analysis Tools Layer
    subgraph "Analysis Tools"
        an1["game_analyze.py"]:::analysis
        an2["player_matchup_analyze.py"]:::analysis
        an3["json_convert.py"]:::analysis
    end

    %% Relationships within Game Engine
    a1 -->|"LLMCalls"| a3
    a4 -->|"LLMCalls"| a3
    a2 -->|"usesPrompts"| s4
    a5 -->|"recordsGameLogs"| s1

    %% Data flow from Storage to Analysis Tools
    s1 -->|"readsRecords"| an1
    s1 -->|"readsRecords"| an2
    s1 -->|"readsRecords"| an3

    %% Analysis Tools saving processed output
    an3 -->|"convertsToText"| s2
    an2 -->|"savesMatchups"| s3

    %% Styles
    classDef gameEngine fill:#ffdead,stroke:#8b4513,stroke-width:2px;
    classDef analysis fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef storage fill:#90ee90,stroke:#006400,stroke-width:2px;

    %% Click Events for Game Engine Layer
    click a1 "https://github.com/lyihub/liars-bar-llm/blob/main/./game.py"
    click a2 "https://github.com/lyihub/liars-bar-llm/blob/main/./player.py"
    click a3 "https://github.com/lyihub/liars-bar-llm/blob/main/./llm_client.py"
    click a4 "https://github.com/lyihub/liars-bar-llm/blob/main/./multi_game_runner.py"
    click a5 "https://github.com/lyihub/liars-bar-llm/blob/main/./game_record.py"

    %% Click Events for Analysis Tools Layer
    click an1 "https://github.com/lyihub/liars-bar-llm/blob/main/./game_analyze.py"
    click an2 "https://github.com/lyihub/liars-bar-llm/blob/main/./player_matchup_analyze.py"
    click an3 "https://github.com/lyihub/liars-bar-llm/blob/main/./json_convert.py"

    %% Click Events for Supporting/Data Storage
    click s1 "https://github.com/lyihub/liars-bar-llm/tree/main/./demo_records/game_records"
    click s2 "https://github.com/lyihub/liars-bar-llm/tree/main/./demo_records/converted_game_records"
    click s3 "https://github.com/lyihub/liars-bar-llm/tree/main/./demo_records/matchup_records"
    click s4 "https://github.com/lyihub/liars-bar-llm/tree/main/./prompt"
```
