# crespina/llm4cp architecture

> Architecture diagram of the GitHub repository crespina/llm4cp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crespina/llm4cp
- Repository: https://github.com/crespina/llm4cp

## Overview

##### Project type and purpose
- CP-Model-Zoo is a standalone “intelligent tutoring” / retrieval tool that lets users enter natural-language descriptions of combinatorial problems and retrieves the closest expert-written MiniZinc model.
- It comprises two main pipelines (indexing and inference) plus both GUI (Gradio) and CLI front-ends.

##### Main components
A. Data Layer (storage)
- Raw MiniZinc models (data/input/…)
- Generated text descriptions (data/output/generated_descriptions)
- Vector databases (data/vector_dbs)
- Experiment results (data/results)
B. Indexing Service (app/data_processing + run_indexing.py)
- Loads raw models and descriptions
- Generates multi-level descriptions (beginner/medium/expert)
- Calls external Embedding API (GROQ)
- Writes vector stores to disk (JSON-based vector DBs)
C. Inference Service (app/inference + run_inference.py)
- Accepts user NL query
- Embeds query via Embedding API
- Performs similarity search against vector DBs
- Retrieves matching MiniZinc code & description
D. GUI Front-end (app/gui + run_gui.py)
- Gradio interface for query input and displaying results
E. Utilities & Config (app/utils + configuration.py)
- Shared constants, helper functions, CLI/config parsing

##### Relationships and data flows
Indexing flow (one-time or on-demand):
Raw Models → Data Loaders → Description Generator → Embedding API → Vector DB + Text Stores
Inference flow (per-query):
User (GUI/CLI) → Inference Service → Embedding API → Vector DB (NN search) → Inference Service → UI

##### Architectural patterns & principles
- Layered: UI Layer → Service Layer → Data Layer → External Service
- Modular pipelines: clear separation of indexing vs. inference
- ETL-style data processing (in indexing)
- Dependency inversion: services depend on storage abstractions and external API

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Services
  Embedding_API["GROQ Embedding API"]:::external

  %% UI Layer
  subgraph "UI Layer"
    direction TB
    GUI["GUI Front-end"]:::ui
    CLI["CLI Front-end"]:::ui
  end

  %% Service Layer
  subgraph "Indexing Service" 
    direction TB
    Data_Loaders["Data Loaders"]:::service
    Indexing_Pipeline["Indexing Pipeline"]:::service
    Run_Indexing["run_indexing.py"]:::service
  end

  subgraph "Inference Service"
    direction TB
    Inference_Core["Inference Service"]:::service
    Run_Inference["run_inference.py"]:::service
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    Raw_Models["Raw MiniZinc Models"]:::storage
    Generated_Descriptions["Generated Text Descriptions"]:::storage
    Vector_DB["Vector Databases"]:::storage
    Experiment_Results["Experiment Results"]:::storage
  end

  %% Utilities & Config
  subgraph "Utilities & Config"
    direction TB
    Constants["Shared Constants"]:::utility
    Helpers["Helper Functions"]:::utility
    Config["Configuration File"]:::utility
  end

  %% Indexing Flow
  Raw_Models -->|"Load .mzn"| Data_Loaders
  Data_Loaders -->|"Generate descriptions"| Indexing_Pipeline
  Indexing_Pipeline -->|"Write descriptions"| Generated_Descriptions
  Indexing_Pipeline -->|"Call Embedding API"| Embedding_API
  Embedding_API -->|"Store vectors"| Vector_DB
  Indexing_Pipeline --> Run_Indexing

  %% Inference Flow
  GUI -->|"User query"| Inference_Core
  CLI -->|"User query"| Inference_Core
  Inference_Core -->|"Embed query"| Embedding_API
  Embedding_API -->|"Return embeddings"| Inference_Core
  Inference_Core -->|"Similarity search"| Vector_DB
  Vector_DB -->|"Return results"| Inference_Core
  Inference_Core -->|"Return model & description"| GUI
  Inference_Core -->|"Return model & description"| CLI
  Inference_Core --> Run_Inference

  %% Utilities connections
  Inference_Core --- Constants
  Inference_Core --- Helpers
  Data_Loaders --- Config
  Indexing_Pipeline --- Helpers

  %% Click Events
  click Data_Loaders "https://github.com/crespina/llm4cp/blob/main/app/data_processing/data_loaders.py"
  click Indexing_Pipeline "https://github.com/crespina/llm4cp/blob/main/app/data_processing/indexing.py"
  click Run_Indexing "https://github.com/crespina/llm4cp/blob/main/run_indexing.py"
  click Inference_Core "https://github.com/crespina/llm4cp/blob/main/app/inference/inference.py"
  click Run_Inference "https://github.com/crespina/llm4cp/blob/main/run_inference.py"
  click GUI "https://github.com/crespina/llm4cp/blob/main/app/gui/gui.py"
  click Run_GUI "https://github.com/crespina/llm4cp/blob/main/run_gui.py"
  click Constants "https://github.com/crespina/llm4cp/blob/main/app/utils/CONSTANTS.py"
  click Helpers "https://github.com/crespina/llm4cp/blob/main/app/utils/app_utils.py"
  click Config "https://github.com/crespina/llm4cp/blob/main/configuration.py"

  %% Styles
  classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
  classDef service fill:#DFFFD0,stroke:#228B22,color:#228B22;
  classDef storage fill:#FFEFD0,stroke:#FF8C00,color:#FF8C00;
  classDef external fill:#F0D0FF,stroke:#800080,color:#800080;
  classDef utility fill:#F0F0F0,stroke:#999999,color:#333333;
```
