src/README.md

Project A: Intelligent Retail Automation Agent (Level 3)
Project A is an autonomous, on-premise AI agent designed for the Vietnamese Retail Industry. Unlike standard chatbots, it functions as a Digital Employee capable of:
Consulting: Providing business advice using context-aware memory and RAG.
Managing: Interfacing with SaaS data (Sales, Inventory, CRM).
Building: Autonomous generation of technical automation workflows (Make.com/Native JSON) based on natural language requests.
Built to run efficiently on a single L4 GPU (24GB VRAM) using a Unified 8-bit Model Architecture.
🏗️ Architecture Overview
The system utilizes a Single-Model, Multi-Persona architecture. Instead of loading multiple models, we use one high-performance model (Qwen-2.5-Coder-14B-Instruct) and dynamically swap system prompts to alter its behavior (Manager, Coder, Researcher).
System Logic Flow (Visualization)
code
Mermaid
graph TD
    User[User Input] --> Main[Main Orchestrator (main.py)]

    

    subgraph Context_Layer

        Mem[(SQLite Memory)]

        SaaS[SaaS API Mock]

        Tools[Retail Tools]

    end

    

    Main -->|Fetch History & Profile| Mem

    Main -->|Health Check| Tools

    Main -->|Send Context| Manager

    

    subgraph The_Brain_Qwen_14B

        Manager{Manager Agent}

        Coder[Coder Agent]

        Researcher[Researcher Agent]

    end

    

    Manager -->|Analyze Intent| Router{Router Decision}

    

    %% Branch 1: General Business

    Router -->|Intent: GENERAL / DATA| SaaS

    SaaS -->|Return Sales/Stock| Manager

    Manager -->|Consult & Advise| Output[Final Response]

    

    %% Branch 2: Marketing

    Router -->|Intent: MARKETING| Manager

    Manager -->|Write Copy| Output

    

    %% Branch 3: Technical Automation

    Router -->|Intent: TECHNICAL| Coder

    Coder -->|Generate JSON Blueprint| Validator[Syntax Check]

    Validator -->|Valid JSON| Integrations[Integration Manager]

    Integrations -->|Save to DB| Workflows[(Workflows Table)]

    Workflows --> Output

📂 File Structure & Components

The project is contained entirely within the src/ directory for portability.

code

Text

ProjectA/

├── main.py                  # Entry point. Handles the Event Loop, Login, and UI output.

├── requirements.txt         # Python dependencies.

├── src/

│   ├── data/                # Storage

│   │   ├── project_a.db     # SQLite DB (Chat History, Users, Stores, Sales, Workflows).

│   │   ├── docs/            # RAG Documents (PDF/TXT) for knowledge base.

│   │   └── blueprints/      # JSON Reference samples for the Coder to learn from.

│   │

│   ├── core/                # The Nervous System

│   │   ├── config.py        # Settings (Model ID, Paths, Quantization Params).

│   │   ├── engine.py        # Model Loader. Enforces Singleton pattern (loads Qwen once).

│   │   ├── memory.py        # Database Manager. Handles Context injection & History.

│   │   ├── context.py       # Login Logic. Handles Multi-store ambiguity resolution.

│   │   ├── saas_api.py      # Mock API simulating KiotViet/Sapo (Sales, Inventory).

│   │   ├── tools.py         # Deterministic Utilities (Math, Lunar Calendar, Health Check).

│   │   ├── integrations.py  # Deployment Handler (Saves JSON to DB / Mock Social Post).

│   │   └── prompts.py       # Prompt Library. Contains Persona definitions & Few-Shot examples.

│   │

│   └── agents/              # The Personas (All powered by Qwen-14B)

│       ├── base.py          # Abstract wrapper for LLM inference.

│       ├── manager.py       # THE BRAIN. Routes tasks, handles chat, intent classification.

│       ├── coder.py         # THE BUILDER. Generates strict JSON automation blueprints.

│       └── researcher.py    # THE EYES. Performs web searches (DuckDuckGo).

🧩 Detailed Component Roles

1. The Core Engines

engine.py: Loads Qwen-2.5-Coder-14B-Instruct in 8-bit quantization. This fits the model into ~16GB VRAM, leaving ~8GB buffer for long context windows (Chat History + RAG).

memory.py: Not just a logger. It actively seeds "Mock Data" (Sales, Users) so the system feels alive immediately. It formats the last 

N

N

 turns of conversation for the Manager to ensure continuity.

saas_api.py: Acts as the bridge to your business data. Currently returns mock data, but designed to be replaced with requests.get() to your real Backend API.

2. The Agents

Manager (manager.py):

Smart Routing: Distinguishes between "I want to automate" (Vague -> Ask Question) vs "Automate email on new order" (Specific -> Call Coder).

Contextual Glue: Injects Store Name, Industry, and Time into the system prompt so answers are always relevant.

Coder (coder.py):

Registry Aware: Uses a library of "Golden Templates" (in prompts.py or JSON) to ensure generated Make.com blueprints use the correct internal IDs and parameter names.

Researcher (researcher.py):

Summarizes web search results into Vietnamese business insights.

3. The Deployment Layer

integrations.py:

Instead of just printing code, it saves the generated Workflow JSON into the workflows table in SQLite.

Simulates the "Save & Activate" flow of a real SaaS platform.

🚀 Deployment Instructions

1. Hardware Requirements

GPU: NVIDIA GPU with 24GB VRAM minimum (Recommended: L4, A10g, RTX 3090/4090).

RAM: 16GB System RAM.

Disk: 50GB free space (Model weights are large).

2. Environment Setup

It is recommended to use conda or a virtual environment.

code

Bash

# 1. Create Environment

conda create -n project_a python=3.10

conda activate project_a


# 2. Install Dependencies
pip install -r requirements.txt
requirements.txt content:
code
Text
torch
transformers
accelerate
bitsandbytes
duckduckgo-search
sentence-transformers
sqlite3
lunardate
protobuf
3. Running the Agent
The project is self-contained. The first run will automatically:
Download the Qwen-14B model (approx. 9-10GB).
Initialize the SQLite Database.
Seed mock data (User: Nguyen Van A).
code
Bash
python src/main.py
🧪 Testing the Capabilities
Once the system shows ✅ Ready, try these scenarios:
Scenario A: Business Intelligence (Data + Context)
Input: "Hôm nay doanh thu thế nào?" (How is revenue today?)
Logic: Manager detects DATA_INTERNAL -> Calls saas_api.get_sales_report -> Formats response.
Output: "Doanh thu hôm nay của BabyWorld là 3.700.000 VND..."
Scenario B: Contextual Advice (Lunar Tool + Profile)
Input: "Hôm nay là ngày bao nhiêu âm? Có nên khuyến mãi không?"
Logic: Manager calls RetailTools.get_lunar_date -> Checks Profile (Baby Store) -> Suggests advice.
Output: "Hôm nay là 15 Âm lịch... Nên chạy chương trình nhẹ nhàng..."
Scenario C: Automation Building (The "Meta-Agent")
Input: "Tự động gửi email cảm ơn khi có đơn hàng mới."
Logic: Manager detects TECHNICAL (Specific) -> Coder generates JSON -> Integrations saves to DB.
Output: "Đã thiết kế xong. Workflow ID: 5. ✅ ĐÃ LƯU THÀNH CÔNG."
🔮 Future Roadmap (Beyond Phase 22)
Real API Hookup: Replace saas_api.py methods with real SQL queries to your Postgres/MySQL production DB.

Frontend Integration: Connect this Python backend to your Website via FastAPI.

User types in Web Chat -> FastAPI sends to main.py -> Agent Returns Text/JSON.

Vision Support: Upgrade to Qwen-VL to allow users to upload photos of invoices or products for auto-entry.