Qurrah commited on
Commit
ff71005
Β·
1 Parent(s): c437b70

UPDATED: detailed readme

Browse files
Files changed (1) hide show
  1. README.md +186 -10
README.md CHANGED
@@ -1,10 +1,186 @@
1
- ---
2
- title: Replyflow Rag
3
- emoji: πŸ’»
4
- colorFrom: red
5
- colorTo: blue
6
- sdk: docker
7
- pinned: false
8
- ---
9
-
10
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ReplyFlow RAG
2
+
3
+ ReplyFlow RAG is a Shopify-connected retrieval-augmented generation (RAG) API for multi-brand customer support. The project combines policy and FAQ embeddings, live Shopify inventory data, and a query router to produce accurate responses for product, shipping, returns, and support questions.
4
+
5
+ ## Key Features
6
+
7
+ - FastAPI-based API for query handling, brand onboarding, and ingestion
8
+ - Shopify onboarding with webhookless brand registration
9
+ - Shopify policy ingestion into Supabase embeddings
10
+ - Semantic retrieval over brand documents and FAQs
11
+ - Live inventory lookup for product and stock questions
12
+ - Route classification into `INVENTORY`, `RAG`, or `BOTH`
13
+ - Comment logging for analytics and traceability
14
+
15
+ ## Architecture
16
+
17
+ - `app.py` β€” FastAPI server exposing `/health`, `/query`, `/onboard`, and `/ingest`
18
+ - `pipeline_v2.py` β€” current request pipeline that resolves brand context, routes queries, retrieves documents, and generates replies
19
+ - `router.py` β€” LLM-based router that decides query routing
20
+ - `retriever.py` β€” semantic retrieval using embeddings stored in Supabase
21
+ - `generator.py` β€” LLM prompt generation for RAG or combined responses
22
+ - `shopify_onboard.py` β€” Shopify brand registration and Supabase channel linking
23
+ - `shopify_ingest.py` β€” ingestion flow for Shopify policies and brand indexing
24
+ - `shopify_client.py` β€” Shopify API helpers for policies, products, and live inventory
25
+ - `chunker.py` β€” text chunking for policy documents
26
+ - `embedder.py` β€” embedding creation and storage with SentenceTransformer
27
+ - `supabase_client.py` β€” Supabase client initialization
28
+ - `llm_client.py` β€” Groq API client initialization
29
+
30
+ ## Requirements
31
+
32
+ - Python 3.11+ (or compatible)
33
+ - `venv` or other virtual environment
34
+ - Supabase project with the required tables and RPC function
35
+ - Shopify store credentials for onboarding and ingestion
36
+ - Groq API key for LLM access
37
+
38
+ Install dependencies:
39
+
40
+ ```bash
41
+ python3 -m venv venv
42
+ source venv/bin/activate
43
+ pip install -r requirements.txt
44
+ ```
45
+
46
+ ## Environment Variables
47
+
48
+ Create a `.env` file with at least the following values:
49
+
50
+ ```env
51
+ GROQ_API_KEY=your_groq_api_key
52
+ GROQ_MODEL=llama-3.1-8b-instant
53
+ SUPABASE_URL=https://your.supabase.url
54
+ SUPABASE_SERVICE_KEY=your_supabase_service_key
55
+ ```
56
+
57
+ For local Shopify testing, the following variables may also be useful:
58
+
59
+ ```env
60
+ SHOPIFY_SHOP_DOMAIN=your-store.myshopify.com
61
+ SHOPIFY_ACCESS_TOKEN=shpat_xxx
62
+ ```
63
+
64
+ ## Running the API
65
+
66
+ Start the FastAPI server:
67
+
68
+ ```bash
69
+ python app.py
70
+ ```
71
+
72
+ The app listens on `http://0.0.0.0:7860` by default.
73
+
74
+ ## API Endpoints
75
+
76
+ ### Health check
77
+
78
+ ```http
79
+ GET /health
80
+ ```
81
+
82
+ ### Query
83
+
84
+ ```http
85
+ POST /query
86
+ Content-Type: application/json
87
+ ```
88
+
89
+ Body example:
90
+
91
+ ```json
92
+ {
93
+ "query": "Do you have the leather sneakers in stock?",
94
+ "channel": "instagram",
95
+ "channel_identifier": "1234567890",
96
+ "external_id": "comment_123",
97
+ "commenter_handle": "@customer",
98
+ "post_caption": "New drop: premium leather sneakers"
99
+ }
100
+ ```
101
+
102
+ Response:
103
+
104
+ ```json
105
+ {
106
+ "answer": "...",
107
+ "query": "Do you have the leather sneakers in stock?"
108
+ }
109
+ ```
110
+
111
+ ### Onboard
112
+
113
+ Register a new Shopify brand and ingest its policies:
114
+
115
+ ```http
116
+ POST /onboard
117
+ Content-Type: application/json
118
+ ```
119
+
120
+ Body example:
121
+
122
+ ```json
123
+ {
124
+ "shop_domain": "replyflow-test.myshopify.com",
125
+ "access_token": "shpat_xxx"
126
+ }
127
+ ```
128
+
129
+ ### Ingest
130
+
131
+ Re-index an existing brand by slug:
132
+
133
+ ```http
134
+ POST /ingest
135
+ Content-Type: application/json
136
+ ```
137
+
138
+ Body example:
139
+
140
+ ```json
141
+ {
142
+ "brand_slug": "replyflow-test"
143
+ }
144
+ ```
145
+
146
+ ## Data Flow
147
+
148
+ 1. `query` request arrives via `app.py`
149
+ 2. `pipeline_v2.answer()` resolves the brand from Supabase
150
+ 3. `router.py` classifies the query as `INVENTORY`, `RAG`, or `BOTH`
151
+ 4. `retriever.py` fetches relevant embeddings when needed
152
+ 5. `shopify_client.py` fetches live product/inventory data for inventory queries
153
+ 6. `generator.py` composes the final answer with the LLM
154
+ 7. `shopify_ingest.py` and `shopify_onboard.py` handle brand onboarding and policy ingestion
155
+
156
+ ## Supabase Schema Notes
157
+
158
+ The project expects a Supabase schema with the following logical tables:
159
+
160
+ - `workspace` / `brands` β€” brand/workspace metadata
161
+ - `social_account` / `brand_channels` β€” linked Shopify and social channel credentials
162
+ - `embeddings` β€” stored semantic chunks and embeddings
163
+ - `comments` β€” logged questions, replies, and route decisions
164
+
165
+ Also note the use of a Supabase RPC function called `match_embeddings` for similarity search.
166
+
167
+ ## Development Notes
168
+
169
+ - `pipeline_v2.py` is the active pipeline version
170
+ - `pipeline.py` is an earlier version with a slightly different schema and routing flow
171
+ - `generator.py` uses a stricter context-only answer prompt to prevent hallucination
172
+ - `chunker.py` splits Shopify policy text into smaller retrievable chunks
173
+ - `embedder.py` stores embeddings for later semantic retrieval
174
+
175
+ ## Contribution
176
+
177
+ This repository is intended for rapid Shopify RAG prototyping. To extend it:
178
+
179
+ - add FAQ ingestion in `shopify_ingest.py`
180
+ - add product embedding ingestion and retrieval
181
+ - improve prompt templates in `generator.py`
182
+ - add caching and rate limiting for Shopify API calls
183
+
184
+ ## License
185
+
186
+ Use and adapt this code as needed for prototyping. No explicit license is included in this repository.