Perk-a-Cola Classification 🥤

Automated, privacy-first text classification pipeline powered by local LLMs via LM Studio.

Overview

Perk-a-Cola is a modular, high-performance classification system designed to process large Excel datasets using local Large Language Models. Built with a focus on privacy, modularity, and software engineering best practices, it allows you to classify text descriptions (e.g., identifying AI-related content) without sending data to external cloud providers.

Key Features

• 🔒 Privacy First: Runs entirely local using LM Studio (tested with Ministral3-3B).
• ⚡ High Performance: Asynchronous concurrency handles 10,000+ rows efficiently.
• 🧩 Modular Architecture:
  • Strategy Pattern for interchangeable classifiers.
  • Config-driven design (YAML) for easy customization of labels, prompts, and models.
• 🧠 Smart Parsing: Robust regex-based output parsing with support for "thinking" models.
• 📊 Excel Integration: Native read/write support for .xlsx files.

Architecture

The system follows a clean separation of concerns:

src/
├── config.py        # Typed configuration loader
├── data_reader.py   # Specialized Excel reader
├── classifier.py    # Async LLM classifier (Strategy implementation)
├── output_writer.py # Result writer
└── main.py          # Pipeline orchestrator

Prerequisites

• Python 3.10+
• LM Studio (or any OpenAI-compatible local server) running on localhost:1234
• A model loaded in LM Studio (recommended: qwen3-4b-instruct)

Installation

1. Clone the repository:

   git clone https://github.com/Vinello28/Perk-a-Cola.git
   cd Perk-a-Cola

2. Install dependencies:

   pip install -r requirements.txt

Configuration

Customize the classification behavior in app/src/config.yaml:

llm:
  model_name: "qwen3-4b"
  enable_thinking: true  # Utilize model's reasoning capabilities

classification:
  labels: ["ai", "non_ai"]
  description_column: "Descrizione"

concurrency:
  max_workers: 10  # Adjust based on your VRAM/System specs

Running with Docker (Recommended)

The easiest way to run the application (both GUI and CLI) without dealing with Python environments is using Docker Compose.

1. Start LM Studio: Load your model and start the server on port 1234.
2. Run the GUI:

   docker-compose up --build

   Then open http://localhost:8501 in your browser.

For CLI usage with Docker, or Linux specific configurations, please see the User Guide.

Usage (Local Python)

If you prefer not to use Docker:

1. Start LM Studio: Load your model and start the server on port 1234.

2. Prepare Data: Place your .xlsx files in app/data/. Ensure they have the configured target column (default: "Descrizione").

3. Run the Pipeline:

   python app/src/main.py

   You can also specify a custom config file:

   python app/src/main.py --config path/to/custom_config.yaml

4. View Results: Classified files will be generated in app/out/ with the suffix _classified.xlsx.

License

Distribued under the MIT License. See LICENSE for more information.

---

Built with ❤️ by Vinello28