# karakuri-ai/wandb-fully-connected-2025-karakuri-workshop architecture

> Architecture diagram of the GitHub repository karakuri-ai/wandb-fully-connected-2025-karakuri-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop
- Repository: https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop

## Overview

##### Project type and purpose
- This is a Python-based demo/workshop tool—a “Customer Support AI” application built for a W&B (Weights & Biases) workshop.
- It ingests FAQ data, builds embeddings, serves a chat interface to answer user questions via OpenAI’s API, and logs experiments/metrics to W&B.

##### File structure
- Top-level directories/files:
- data/ (CSV sources: faq.csv, faq-embedding.csv, eval-onboarding.csv, feedback-logs.csv)
- notebooks/ (workshop.ipynb for interactive demos)
- src/ (core Python modules: chat.py, client.py, config.py, prompts.py, prompt_improvement.py, run_evaluation.py, run_improvement.py, tools.py)
- .streamlit/ (streamlit config, if a UI is used)
- pyproject.toml & uv.lock (dependency management with “uv”)
- Makefile, env.example, README.md
- Patterns: single codebase, modularized by functionality (chat, client adapters, prompt logic, data-tools, evaluation/improvement scripts).

##### README for additional insights
- Environment variables: OPENAI_API_KEY, WANDB_API_KEY, WEAVE_PROJECT_NAME
- Toolchain: Python ≥3.11, “uv sync” for dependency install
- Usage: runs scripts to evaluate prompts and improve them, uses Google Colab for live demo.

a. Data Source layer
- CSV Files in data/ → loaded by tools.py → embeddings stored (locally or in-memory)
b. Embedding & Vector Store
- prompt_improvement.py & tools.py call OpenAI Embedding API → produce faq-embedding.csv
c. Chat Interface & Prompt Assembly
- chat.py uses client.py (OpenAI client) + prompts.py (templates + retrieval) → builds completion requests
d. OpenAI API
- External service: ChatCompletion & Embedding endpoints
e. Experiment Logging
- config.py sets up W&B → run_evaluation.py & run_improvement.py log to W&B project
f. Notebook Layer
- notebooks/workshop.ipynb demonstrates end-to-end usage interactively

##### Architectural patterns & design principles
- Modular layering:
- “tools” for data ingestion & embedding
- “prompts” for template management
- “client” for external API abstraction
- “chat” for orchestrating input → retrieval → LLM call → postprocessing
- “run_*” scripts for batch experiments & improvements
- Separation of concerns: data, model, evaluation, logging
- Extensibility hooks: swap out embedding, add new prompt modules, integrate new evaluation metrics

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        CSV["CSV Files<br/>(faq.csv, eval-onboarding.csv, feedback-logs.csv)"]:::data
        Tools["tools.py"]:::internal
    end

    %% Embedding Service
    subgraph "Embedding & Vector Store"
        direction TB
        PI["prompt_improvement.py"]:::internal
        VectorStore["faq-embedding.csv"]:::data
    end

    %% Chat Engine
    subgraph "Chat Interface & Orchestration"
        direction TB
        Chat["chat.py"]:::internal
        Prompts["prompts.py"]:::internal
        Client["client.py"]:::internal
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI[(OpenAI API)]:::external
        WnB[(Weights & Biases)]:::external
    end

    %% Logging & Evaluation
    subgraph "Logging & Batch Scripts"
        direction TB
        Config["config.py"]:::internal
        EvalScript["run_evaluation.py"]:::script
        ImproveScript["run_improvement.py"]:::script
    end

    %% UI & Entry Points
    subgraph "UI & Project Config"
        direction TB
        Notebook["workshop.ipynb"]:::script
        StreamlitConfig["config.toml"]:::script
        MakefileNode["Makefile"]:::script
        Pyproject["pyproject.toml"]:::script
    end

    %% Flows
    CSV -->|"load CSV"| Tools
    Tools -->|"generate embeddings"| PI
    PI -->|"save embeddings"| VectorStore

    %% Chat flow
    UserInput["User Input"]:::external -->|enter question| Chat
    Chat -->|"assemble prompt"| Prompts
    Prompts -->|"retrieve nearest embeddings"| VectorStore
    Prompts -->|"build request"| Chat
    Chat -->|"call ChatCompletion"| Client
    Client -->|ChatCompletion request| OpenAI
    OpenAI -->|response| Client
    Client -->|return answer| Chat
    Chat -->|display answer| UserOutput["User Output"]:::external

    %% Logging & Scripts flow
    Chat -->|"log metrics"| Config
    EvalScript -->|"setup logging"| Config
    ImproveScript -->|"setup logging"| Config
    Config -->|"log to W&B"| WnB
    EvalScript -->|"batch evaluation"| WnB
    ImproveScript -->|"batch improvement"| WnB

    %% Notebook & UI
    Notebook -->|"interactive demo"| Chat
    Notebook -->|"run scripts"| EvalScript
    Notebook -->|"run scripts"| ImproveScript
    StreamlitConfig -->|"UI config"| Chat
    MakefileNode -->|"project build"| Pyproject

    %% Click Events
    click Tools "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/tools.py"
    click PI "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/prompt_improvement.py"
    click VectorStore "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/data/faq-embedding.csv"
    click Chat "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/chat.py"
    click Prompts "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/prompts.py"
    click Client "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/client.py"
    click OpenAI "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/tree/main/N/A"
    click WnB "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/tree/main/N/A"
    click Config "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/config.py"
    click EvalScript "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/run_evaluation.py"
    click ImproveScript "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/src/run_improvement.py"
    click Notebook "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/notebooks/workshop.ipynb"
    click StreamlitConfig "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/.streamlit/config.toml"
    click MakefileNode "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/tree/main/Makefile"
    click Pyproject "https://github.com/karakuri-ai/wandb-fully-connected-2025-karakuri-workshop/blob/main/pyproject.toml"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFCC80,stroke:#333,stroke-width:1px
    classDef script fill:#D3D3D3,stroke:#333,stroke-width:1px
```
