Hugging Face's logo

Spaces:
FrnklnWrld
/
Me
Running

App Files Community
FrnklnWrld commited on
Commit
8f5face
Β·
verified Β·
1 Parent(s): c23a5ac

Create docs.html

Browse files
Files changed (1) hide show
  1. docs.html +1627 -0
docs.html ADDED
@@ -0,0 +1,1627 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Abdullah Bot API β€” Developer Documentation</title>
7
+ <link href="https://fonts.googleapis.com/css2?family=DM+Mono:ital,wght@0,300;0,400;0,500;1,400&family=Fraunces:ital,opsz,wght@0,9..144,300;0,9..144,600;0,9..144,700;1,9..144,400&family=Cabinet+Grotesk:wght@400;500;700;800&display=swap" rel="stylesheet">
8
+ <style>
9
+ :root {
10
+ --ink: #0a0c10;
11
+ --ink2: #1a1d26;
12
+ --ink3: #252836;
13
+ --border: #2a2e40;
14
+ --border2: #1e2130;
15
+ --gold: #c9a84c;
16
+ --gold2: #e8c97a;
17
+ --gold-dim: rgba(201,168,76,0.15);
18
+ --gold-glow: rgba(201,168,76,0.08);
19
+ --teal: #3ecfb2;
20
+ --teal-dim: rgba(62,207,178,0.12);
21
+ --red: #e05c5c;
22
+ --muted: #6b7090;
23
+ --muted2: #4a4f6a;
24
+ --text: #dde0ee;
25
+ --text2: #a8adc8;
26
+ --code: #0d1018;
27
+ --sidebar-w: 280px;
28
+ }
29
+
30
+ * { margin:0; padding:0; box-sizing:border-box; }
31
+
32
+ html { scroll-behavior: smooth; }
33
+
34
+ body {
35
+ background: var(--ink);
36
+ color: var(--text);
37
+ font-family: 'Cabinet Grotesk', sans-serif;
38
+ min-height: 100vh;
39
+ display: flex;
40
+ overflow-x: hidden;
41
+ }
42
+
43
+ /* ── NOISE TEXTURE ── */
44
+ body::after {
45
+ content:'';
46
+ position:fixed;
47
+ inset:0;
48
+ background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)' opacity='0.03'/%3E%3C/svg%3E");
49
+ pointer-events:none;
50
+ z-index:9999;
51
+ opacity:0.4;
52
+ }
53
+
54
+ /* ══════════════════════════════
55
+ SIDEBAR
56
+ ══════════════════════════════ */
57
+ .sidebar {
58
+ width: var(--sidebar-w);
59
+ min-height: 100vh;
60
+ background: var(--ink2);
61
+ border-right: 1px solid var(--border2);
62
+ position: fixed;
63
+ top: 0; left: 0;
64
+ overflow-y: auto;
65
+ z-index: 100;
66
+ display: flex;
67
+ flex-direction: column;
68
+ }
69
+
70
+ .sidebar::-webkit-scrollbar { width: 4px; }
71
+ .sidebar::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }
72
+
73
+ .sidebar-logo {
74
+ padding: 28px 24px 20px;
75
+ border-bottom: 1px solid var(--border2);
76
+ }
77
+ .logo-moon { font-size: 1.4rem; display: block; margin-bottom: 10px; }
78
+ .logo-name {
79
+ font-family: 'Fraunces', serif;
80
+ font-size: 1.15rem;
81
+ font-weight: 700;
82
+ color: var(--gold2);
83
+ letter-spacing: -0.01em;
84
+ line-height: 1.2;
85
+ }
86
+ .logo-sub {
87
+ font-family: 'DM Mono', monospace;
88
+ font-size: 0.62rem;
89
+ color: var(--muted);
90
+ letter-spacing: 0.12em;
91
+ text-transform: uppercase;
92
+ margin-top: 4px;
93
+ }
94
+
95
+ .sidebar-search {
96
+ padding: 16px 16px 12px;
97
+ border-bottom: 1px solid var(--border2);
98
+ }
99
+ .search-input {
100
+ width: 100%;
101
+ background: var(--ink);
102
+ border: 1px solid var(--border);
103
+ border-radius: 8px;
104
+ padding: 9px 12px 9px 34px;
105
+ color: var(--text);
106
+ font-family: 'DM Mono', monospace;
107
+ font-size: 0.75rem;
108
+ outline: none;
109
+ transition: border-color 0.2s;
110
+ position: relative;
111
+ }
112
+ .search-wrap { position: relative; }
113
+ .search-wrap::before {
114
+ content: 'βŒ•';
115
+ position: absolute;
116
+ left: 10px; top: 50%;
117
+ transform: translateY(-50%);
118
+ color: var(--muted2);
119
+ font-size: 1rem;
120
+ pointer-events: none;
121
+ z-index:1;
122
+ }
123
+ .search-input:focus { border-color: var(--gold); }
124
+ .search-input::placeholder { color: var(--muted2); }
125
+
126
+ .nav-section {
127
+ padding: 20px 16px 4px;
128
+ }
129
+ .nav-section-label {
130
+ font-family: 'DM Mono', monospace;
131
+ font-size: 0.6rem;
132
+ text-transform: uppercase;
133
+ letter-spacing: 0.18em;
134
+ color: var(--muted2);
135
+ padding: 0 8px;
136
+ margin-bottom: 6px;
137
+ }
138
+ .nav-item {
139
+ display: flex;
140
+ align-items: center;
141
+ gap: 9px;
142
+ padding: 8px 10px;
143
+ border-radius: 8px;
144
+ cursor: pointer;
145
+ font-size: 0.86rem;
146
+ color: var(--text2);
147
+ transition: all 0.15s;
148
+ text-decoration: none;
149
+ border: 1px solid transparent;
150
+ margin-bottom: 2px;
151
+ position: relative;
152
+ }
153
+ .nav-item:hover { background: var(--ink3); color: var(--text); }
154
+ .nav-item.active {
155
+ background: var(--gold-dim);
156
+ border-color: rgba(201,168,76,0.25);
157
+ color: var(--gold2);
158
+ }
159
+ .nav-item.active::before {
160
+ content: '';
161
+ position: absolute;
162
+ left: -1px; top: 20%; bottom: 20%;
163
+ width: 3px;
164
+ background: var(--gold);
165
+ border-radius: 0 2px 2px 0;
166
+ }
167
+ .nav-icon { font-size: 0.9rem; opacity: 0.7; }
168
+ .nav-badge {
169
+ margin-left: auto;
170
+ font-family: 'DM Mono', monospace;
171
+ font-size: 0.58rem;
172
+ padding: 2px 7px;
173
+ border-radius: 10px;
174
+ background: var(--teal-dim);
175
+ color: var(--teal);
176
+ border: 1px solid rgba(62,207,178,0.2);
177
+ }
178
+ .nav-badge.post { background: var(--gold-dim); color: var(--gold); border-color: rgba(201,168,76,0.2); }
179
+
180
+ .sidebar-footer {
181
+ margin-top: auto;
182
+ padding: 20px 16px;
183
+ border-top: 1px solid var(--border2);
184
+ }
185
+ .version-chip {
186
+ font-family: 'DM Mono', monospace;
187
+ font-size: 0.65rem;
188
+ color: var(--muted);
189
+ display: flex;
190
+ align-items: center;
191
+ gap: 6px;
192
+ }
193
+ .version-dot { width:6px; height:6px; background: var(--teal); border-radius:50%; box-shadow: 0 0 6px var(--teal); animation: pulse 2s infinite; }
194
+ @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
195
+
196
+ /* ══════════════════════════════
197
+ MAIN CONTENT
198
+ ══════════════════════════════ */
199
+ .main {
200
+ margin-left: var(--sidebar-w);
201
+ flex: 1;
202
+ min-height: 100vh;
203
+ }
204
+
205
+ .topbar {
206
+ position: sticky;
207
+ top: 0;
208
+ background: rgba(10,12,16,0.88);
209
+ backdrop-filter: blur(16px);
210
+ border-bottom: 1px solid var(--border2);
211
+ padding: 14px 48px;
212
+ display: flex;
213
+ align-items: center;
214
+ gap: 16px;
215
+ z-index: 50;
216
+ }
217
+ .breadcrumb {
218
+ font-family: 'DM Mono', monospace;
219
+ font-size: 0.72rem;
220
+ color: var(--muted);
221
+ display: flex;
222
+ align-items: center;
223
+ gap: 8px;
224
+ }
225
+ .breadcrumb span { color: var(--text2); }
226
+ .topbar-actions { margin-left: auto; display: flex; gap: 10px; align-items: center; }
227
+ .topbar-btn {
228
+ font-family: 'DM Mono', monospace;
229
+ font-size: 0.68rem;
230
+ padding: 6px 14px;
231
+ border-radius: 7px;
232
+ border: 1px solid var(--border);
233
+ background: transparent;
234
+ color: var(--text2);
235
+ cursor: pointer;
236
+ transition: all 0.15s;
237
+ text-decoration: none;
238
+ display: flex; align-items: center; gap: 6px;
239
+ }
240
+ .topbar-btn:hover { border-color: var(--gold); color: var(--gold); }
241
+ .topbar-btn.primary { background: var(--gold); color: var(--ink); border-color: var(--gold); font-weight: 700; }
242
+ .topbar-btn.primary:hover { background: var(--gold2); }
243
+
244
+ .content {
245
+ max-width: 860px;
246
+ margin: 0 auto;
247
+ padding: 56px 48px 100px;
248
+ }
249
+
250
+ /* ══════════════════════════════
251
+ SECTIONS
252
+ ══════════════════════════════ */
253
+ .section { display: none; animation: fadeIn 0.3s ease; }
254
+ .section.active { display: block; }
255
+ @keyframes fadeIn { from{opacity:0;transform:translateY(12px)} to{opacity:1;transform:none} }
256
+
257
+ /* ── HERO SECTION ── */
258
+ .hero-eyebrow {
259
+ font-family: 'DM Mono', monospace;
260
+ font-size: 0.68rem;
261
+ text-transform: uppercase;
262
+ letter-spacing: 0.2em;
263
+ color: var(--gold);
264
+ margin-bottom: 20px;
265
+ display: flex; align-items: center; gap: 10px;
266
+ }
267
+ .hero-eyebrow::before { content:''; width:32px; height:1px; background:var(--gold); display:inline-block; }
268
+
269
+ .page-title {
270
+ font-family: 'Fraunces', serif;
271
+ font-size: clamp(2.4rem, 4vw, 3.4rem);
272
+ font-weight: 700;
273
+ line-height: 1.1;
274
+ letter-spacing: -0.03em;
275
+ margin-bottom: 20px;
276
+ color: var(--text);
277
+ }
278
+ .page-title em { font-style: italic; color: var(--gold2); }
279
+
280
+ .page-desc {
281
+ font-size: 1.05rem;
282
+ color: var(--text2);
283
+ line-height: 1.75;
284
+ max-width: 640px;
285
+ margin-bottom: 36px;
286
+ }
287
+
288
+ .stats-row {
289
+ display: grid;
290
+ grid-template-columns: repeat(4, 1fr);
291
+ gap: 14px;
292
+ margin-bottom: 48px;
293
+ }
294
+ .stat-card {
295
+ background: var(--ink2);
296
+ border: 1px solid var(--border2);
297
+ border-radius: 12px;
298
+ padding: 18px 20px;
299
+ transition: border-color 0.2s;
300
+ }
301
+ .stat-card:hover { border-color: var(--gold); }
302
+ .stat-num {
303
+ font-family: 'Fraunces', serif;
304
+ font-size: 1.9rem;
305
+ font-weight: 700;
306
+ color: var(--gold2);
307
+ line-height: 1;
308
+ margin-bottom: 4px;
309
+ }
310
+ .stat-label { font-size: 0.78rem; color: var(--muted); }
311
+
312
+ /* ── HEADINGS ── */
313
+ h2 {
314
+ font-family: 'Fraunces', serif;
315
+ font-size: 1.75rem;
316
+ font-weight: 600;
317
+ letter-spacing: -0.02em;
318
+ color: var(--text);
319
+ margin: 52px 0 16px;
320
+ padding-bottom: 14px;
321
+ border-bottom: 1px solid var(--border2);
322
+ display: flex; align-items: center; gap: 12px;
323
+ }
324
+ h2 .h2-icon { font-size: 1.2rem; }
325
+ h3 {
326
+ font-family: 'Cabinet Grotesk', sans-serif;
327
+ font-size: 1.1rem;
328
+ font-weight: 700;
329
+ color: var(--text);
330
+ margin: 28px 0 12px;
331
+ }
332
+
333
+ p {
334
+ font-size: 0.95rem;
335
+ color: var(--text2);
336
+ line-height: 1.8;
337
+ margin-bottom: 16px;
338
+ }
339
+
340
+ /* ── CALLOUT BOXES ── */
341
+ .callout {
342
+ border-radius: 12px;
343
+ padding: 18px 22px;
344
+ margin: 24px 0;
345
+ display: flex;
346
+ gap: 14px;
347
+ font-size: 0.9rem;
348
+ line-height: 1.7;
349
+ }
350
+ .callout-icon { font-size: 1.2rem; flex-shrink:0; margin-top:1px; }
351
+ .callout.info { background: rgba(62,207,178,0.07); border: 1px solid rgba(62,207,178,0.2); color: var(--text2); }
352
+ .callout.warning { background: rgba(201,168,76,0.08); border: 1px solid rgba(201,168,76,0.25); color: var(--text2); }
353
+ .callout.danger { background: rgba(224,92,92,0.08); border: 1px solid rgba(224,92,92,0.25); color: var(--text2); }
354
+ .callout strong { color: var(--text); }
355
+
356
+ /* ── CODE BLOCKS ── */
357
+ .code-wrap {
358
+ position: relative;
359
+ margin: 20px 0;
360
+ }
361
+ .code-lang {
362
+ font-family: 'DM Mono', monospace;
363
+ font-size: 0.62rem;
364
+ text-transform: uppercase;
365
+ letter-spacing: 0.12em;
366
+ color: var(--muted);
367
+ background: var(--ink3);
368
+ border: 1px solid var(--border2);
369
+ border-bottom: none;
370
+ padding: 6px 14px;
371
+ border-radius: 8px 8px 0 0;
372
+ display: inline-block;
373
+ }
374
+ pre {
375
+ background: var(--code);
376
+ border: 1px solid var(--border2);
377
+ border-radius: 0 8px 8px 8px;
378
+ padding: 20px 24px;
379
+ overflow-x: auto;
380
+ font-family: 'DM Mono', monospace;
381
+ font-size: 0.82rem;
382
+ line-height: 1.75;
383
+ color: #98c9a3;
384
+ }
385
+ pre::-webkit-scrollbar { height:4px; }
386
+ pre::-webkit-scrollbar-thumb { background:var(--border); border-radius:2px; }
387
+
388
+ .copy-btn {
389
+ position: absolute;
390
+ top: 36px; right: 10px;
391
+ font-family: 'DM Mono', monospace;
392
+ font-size: 0.62rem;
393
+ padding: 4px 10px;
394
+ border: 1px solid var(--border);
395
+ border-radius: 6px;
396
+ background: var(--ink3);
397
+ color: var(--muted);
398
+ cursor: pointer;
399
+ transition: all 0.15s;
400
+ }
401
+ .copy-btn:hover { border-color: var(--gold); color: var(--gold); }
402
+
403
+ code {
404
+ font-family: 'DM Mono', monospace;
405
+ font-size: 0.83em;
406
+ background: var(--ink3);
407
+ border: 1px solid var(--border2);
408
+ border-radius: 5px;
409
+ padding: 2px 7px;
410
+ color: var(--gold2);
411
+ }
412
+
413
+ /* ── ENDPOINT CARDS ── */
414
+ .endpoint {
415
+ background: var(--ink2);
416
+ border: 1px solid var(--border2);
417
+ border-radius: 14px;
418
+ margin: 20px 0;
419
+ overflow: hidden;
420
+ transition: border-color 0.2s;
421
+ }
422
+ .endpoint:hover { border-color: var(--border); }
423
+ .endpoint-head {
424
+ padding: 18px 24px;
425
+ display: flex;
426
+ align-items: center;
427
+ gap: 14px;
428
+ cursor: pointer;
429
+ }
430
+ .method {
431
+ font-family: 'DM Mono', monospace;
432
+ font-size: 0.68rem;
433
+ font-weight: 500;
434
+ padding: 4px 11px;
435
+ border-radius: 6px;
436
+ letter-spacing: 0.05em;
437
+ flex-shrink: 0;
438
+ }
439
+ .method.GET { background: rgba(62,207,178,0.1); color: var(--teal); border: 1px solid rgba(62,207,178,0.25); }
440
+ .method.POST { background: var(--gold-dim); color: var(--gold); border: 1px solid rgba(201,168,76,0.25); }
441
+ .endpoint-path {
442
+ font-family: 'DM Mono', monospace;
443
+ font-size: 0.92rem;
444
+ color: var(--text);
445
+ }
446
+ .endpoint-summary { font-size: 0.82rem; color: var(--muted); margin-left: auto; }
447
+ .chevron { color: var(--muted2); transition: transform 0.2s; font-size:0.8rem; }
448
+ .endpoint.open .chevron { transform: rotate(180deg); }
449
+ .endpoint-body { display:none; padding: 0 24px 24px; border-top: 1px solid var(--border2); }
450
+ .endpoint.open .endpoint-body { display: block; }
451
+
452
+ /* ── PARAMS TABLE ── */
453
+ .param-table { width:100%; border-collapse:collapse; margin:18px 0; font-size:.85rem; }
454
+ .param-table th {
455
+ font-family:'DM Mono',monospace; font-size:.62rem;
456
+ text-transform:uppercase; letter-spacing:.14em;
457
+ color:var(--muted2); text-align:left;
458
+ padding:8px 12px; border-bottom:1px solid var(--border2);
459
+ }
460
+ .param-table td { padding:11px 12px; border-bottom:1px solid rgba(42,46,64,0.5); vertical-align:top; }
461
+ .param-table tr:last-child td { border-bottom:none; }
462
+ .pname { font-family:'DM Mono',monospace; color:var(--teal); font-size:.82rem; }
463
+ .ptype { font-family:'DM Mono',monospace; color:var(--gold); font-size:.78rem; }
464
+ .req { font-size:.6rem; padding:2px 6px; border-radius:4px; background:rgba(224,92,92,.12); color:var(--red); border:1px solid rgba(224,92,92,.25); margin-left:5px; }
465
+ .opt { font-size:.6rem; padding:2px 6px; border-radius:4px; background:rgba(107,112,144,.12); color:var(--muted); border:1px solid var(--border2); margin-left:5px; }
466
+ .pdesc { color: var(--text2); font-size:.84rem; }
467
+
468
+ /* ── RESPONSE OBJECT ── */
469
+ .resp-field { display:flex; gap:12px; padding:10px 0; border-bottom:1px solid var(--border2); font-size:.85rem; }
470
+ .resp-field:last-child { border-bottom:none; }
471
+ .rname { font-family:'DM Mono',monospace; color:var(--teal); min-width:160px; flex-shrink:0; }
472
+ .rtype { font-family:'DM Mono',monospace; color:var(--gold); min-width:80px; flex-shrink:0; font-size:.78rem; }
473
+ .rdesc { color:var(--text2); }
474
+
475
+ /* ── TONE TABLE ── */
476
+ .tone-grid { display:grid; grid-template-columns:1fr 1fr; gap:10px; margin:20px 0; }
477
+ .tone-card {
478
+ background:var(--ink2); border:1px solid var(--border2);
479
+ border-radius:10px; padding:14px 16px;
480
+ transition: border-color .15s;
481
+ }
482
+ .tone-card:hover { border-color:var(--gold); }
483
+ .tone-name { font-family:'DM Mono',monospace; font-size:.78rem; color:var(--gold2); margin-bottom:4px; }
484
+ .tone-desc { font-size:.78rem; color:var(--muted); line-height:1.5; }
485
+
486
+ /* ── ERROR TABLE ── */
487
+ .error-row { display:flex; align-items:flex-start; gap:16px; padding:14px 0; border-bottom:1px solid var(--border2); font-size:.85rem; }
488
+ .error-row:last-child { border-bottom:none; }
489
+ .ecode { font-family:'DM Mono',monospace; font-size:.82rem; padding:3px 10px; border-radius:6px; flex-shrink:0; min-width:52px; text-align:center; }
490
+ .ecode.e400 { background:rgba(201,168,76,.12); color:var(--gold); border:1px solid rgba(201,168,76,.25); }
491
+ .ecode.e500 { background:rgba(224,92,92,.12); color:var(--red); border:1px solid rgba(224,92,92,.25); }
492
+ .ecode.e503 { background:rgba(62,207,178,.12); color:var(--teal); border:1px solid rgba(62,207,178,.25); }
493
+
494
+ /* ── STEP LIST ── */
495
+ .steps { counter-reset: step; margin: 20px 0; }
496
+ .step {
497
+ display: flex; gap: 16px;
498
+ padding: 18px 0; border-bottom: 1px solid var(--border2);
499
+ counter-increment: step;
500
+ }
501
+ .step:last-child { border-bottom: none; }
502
+ .step-num {
503
+ font-family: 'Fraunces', serif;
504
+ font-size: 1.4rem; font-weight: 700;
505
+ color: var(--gold2); opacity:.4;
506
+ line-height:1; flex-shrink:0;
507
+ min-width:28px;
508
+ }
509
+ .step-content h4 { font-size:.92rem; font-weight:700; color:var(--text); margin-bottom:6px; }
510
+ .step-content p { font-size:.85rem; margin-bottom:0; }
511
+
512
+ /* ── FEATURE LIST ── */
513
+ .feature-list { list-style:none; margin:16px 0; }
514
+ .feature-list li {
515
+ display: flex; align-items: flex-start; gap: 10px;
516
+ padding: 9px 0; border-bottom: 1px solid rgba(42,46,64,0.4);
517
+ font-size:.9rem; color:var(--text2); line-height:1.6;
518
+ }
519
+ .feature-list li:last-child { border-bottom:none; }
520
+ .feature-list li::before { content:'β—†'; color:var(--gold); font-size:.5rem; margin-top:6px; flex-shrink:0; }
521
+
522
+ /* ── PROPOSAL HIGHLIGHT ── */
523
+ .proposal-box {
524
+ background: linear-gradient(135deg, rgba(201,168,76,0.06) 0%, rgba(62,207,178,0.04) 100%);
525
+ border: 1px solid rgba(201,168,76,0.3);
526
+ border-radius: 16px;
527
+ padding: 32px 36px;
528
+ margin: 32px 0;
529
+ position: relative;
530
+ overflow: hidden;
531
+ }
532
+ .proposal-box::before {
533
+ content: '✦';
534
+ position: absolute;
535
+ top: 20px; right: 24px;
536
+ font-size: 2rem;
537
+ color: var(--gold);
538
+ opacity: 0.2;
539
+ }
540
+ .proposal-box h3 { margin-top:0; color:var(--gold2); }
541
+
542
+ /* ── DIVIDER ── */
543
+ .divider { height:1px; background:var(--border2); margin:40px 0; }
544
+
545
+ /* ── TAG ROW ── */
546
+ .tag-row { display:flex; flex-wrap:wrap; gap:8px; margin:16px 0; }
547
+ .tag {
548
+ font-family:'DM Mono',monospace; font-size:.7rem;
549
+ padding:5px 12px; border-radius:20px;
550
+ border:1px solid var(--border); color:var(--text2);
551
+ background:var(--ink2);
552
+ }
553
+
554
+ /* ── MOBILE TOGGLE ── */
555
+ .mobile-toggle {
556
+ display:none;
557
+ position:fixed; top:14px; left:14px;
558
+ z-index:200;
559
+ background:var(--ink2); border:1px solid var(--border);
560
+ border-radius:8px; padding:8px 12px;
561
+ cursor:pointer; font-size:1rem;
562
+ }
563
+
564
+ @media(max-width:820px){
565
+ .sidebar { transform: translateX(-100%); transition:transform .3s; }
566
+ .sidebar.open { transform: translateX(0); }
567
+ .main { margin-left:0; }
568
+ .content { padding:40px 24px 80px; }
569
+ .topbar { padding:14px 24px; }
570
+ .stats-row { grid-template-columns:1fr 1fr; }
571
+ .tone-grid { grid-template-columns:1fr; }
572
+ .mobile-toggle { display:block; }
573
+ }
574
+ </style>
575
+ </head>
576
+ <body>
577
+
578
+ <button class="mobile-toggle" onclick="document.querySelector('.sidebar').classList.toggle('open')">☰</button>
579
+
580
+ <!-- ══ SIDEBAR ══ -->
581
+ <aside class="sidebar">
582
+ <div class="sidebar-logo">
583
+ <span class="logo-moon">πŸŒ™</span>
584
+ <div class="logo-name">Abdullah Bot API</div>
585
+ <div class="logo-sub">Developer Documentation</div>
586
+ </div>
587
+
588
+ <div class="sidebar-search">
589
+ <div class="search-wrap">
590
+ <input class="search-input" type="text" placeholder="Search docs…" oninput="searchDocs(this.value)">
591
+ </div>
592
+ </div>
593
+
594
+ <nav>
595
+ <div class="nav-section">
596
+ <div class="nav-section-label">Getting Started</div>
597
+ <a class="nav-item active" onclick="show('overview')">
598
+ <span class="nav-icon">β—ˆ</span> Overview
599
+ </a>
600
+ <a class="nav-item" onclick="show('quickstart')">
601
+ <span class="nav-icon">⚑</span> Quick Start
602
+ </a>
603
+ <a class="nav-item" onclick="show('auth')">
604
+ <span class="nav-icon">πŸ”‘</span> Authentication
605
+ </a>
606
+ </div>
607
+
608
+ <div class="nav-section">
609
+ <div class="nav-section-label">API Reference</div>
610
+ <a class="nav-item" onclick="show('chat')">
611
+ <span class="nav-icon">πŸ’¬</span> /chat
612
+ <span class="nav-badge post">POST</span>
613
+ </a>
614
+ <a class="nav-item" onclick="show('journey')">
615
+ <span class="nav-icon">πŸ“Š</span> /journey
616
+ <span class="nav-badge">GET</span>
617
+ </a>
618
+ <a class="nav-item" onclick="show('categories')">
619
+ <span class="nav-icon">πŸ“š</span> /categories
620
+ <span class="nav-badge">GET</span>
621
+ </a>
622
+ <a class="nav-item" onclick="show('reset')">
623
+ <span class="nav-icon">πŸ”„</span> /reset-journey
624
+ <span class="nav-badge post">POST</span>
625
+ </a>
626
+ <a class="nav-item" onclick="show('health')">
627
+ <span class="nav-icon">πŸ’š</span> /health
628
+ <span class="nav-badge">GET</span>
629
+ </a>
630
+ </div>
631
+
632
+ <div class="nav-section">
633
+ <div class="nav-section-label">Concepts</div>
634
+ <a class="nav-item" onclick="show('tones')">
635
+ <span class="nav-icon">🎭</span> Tone Detection
636
+ </a>
637
+ <a class="nav-item" onclick="show('journey-flow')">
638
+ <span class="nav-icon">πŸ›€οΈ</span> Journey Flow
639
+ </a>
640
+ <a class="nav-item" onclick="show('multilingual')">
641
+ <span class="nav-icon">🌍</span> Multilingual
642
+ </a>
643
+ <a class="nav-item" onclick="show('fallback')">
644
+ <span class="nav-icon">πŸ”„</span> Model Fallback
645
+ </a>
646
+ </div>
647
+
648
+ <div class="nav-section">
649
+ <div class="nav-section-label">Integration</div>
650
+ <a class="nav-item" onclick="show('flutter')">
651
+ <span class="nav-icon">πŸ“±</span> Flutter Guide
652
+ </a>
653
+ <a class="nav-item" onclick="show('errors')">
654
+ <span class="nav-icon">⚠️</span> Error Handling
655
+ </a>
656
+ <a class="nav-item" onclick="show('upwork')">
657
+ <span class="nav-icon">πŸ’Ό</span> Upwork Proposal
658
+ </a>
659
+ </div>
660
+ </nav>
661
+
662
+ <div class="sidebar-footer">
663
+ <div class="version-chip">
664
+ <span class="version-dot"></span>
665
+ v2.1 Β· Llama-3 Β· Live
666
+ </div>
667
+ </div>
668
+ </aside>
669
+
670
+ <!-- ══ MAIN ══ -->
671
+ <main class="main">
672
+ <div class="topbar">
673
+ <div class="breadcrumb">
674
+ Docs <span>β€Ί</span> <span id="breadcrumb-current">Overview</span>
675
+ </div>
676
+ <div class="topbar-actions">
677
+ <a class="topbar-btn" href="https://frnklnwrld-me.hf.space/docs" target="_blank">βŽ‹ Swagger</a>
678
+ <a class="topbar-btn" href="https://frnklnwrld-me.hf.space/health" target="_blank">πŸ’š Health</a>
679
+ <a class="topbar-btn primary" href="https://frnklnwrld-me.hf.space/" target="_blank">β†— Live API</a>
680
+ </div>
681
+ </div>
682
+
683
+ <div class="content">
684
+
685
+ <!-- ══ OVERVIEW ══ -->
686
+ <section id="sec-overview" class="section active">
687
+ <div class="hero-eyebrow">Islamic AI Companion</div>
688
+ <h1 class="page-title">Abdullah Bot <em>API</em></h1>
689
+ <p class="page-desc">
690
+ A spiritually-grounded conversational API built on Meta's Llama-3 models.
691
+ Designed for Muslim lifestyle apps β€” combines tone detection, journey tracking,
692
+ Quranic references and multilingual support in a single, deployable FastAPI backend.
693
+ </p>
694
+
695
+ <div class="stats-row">
696
+ <div class="stat-card">
697
+ <div class="stat-num">3</div>
698
+ <div class="stat-label">Llama-3 Fallback Models</div>
699
+ </div>
700
+ <div class="stat-card">
701
+ <div class="stat-num">13</div>
702
+ <div class="stat-label">Tone Detection Modes</div>
703
+ </div>
704
+ <div class="stat-card">
705
+ <div class="stat-num">11</div>
706
+ <div class="stat-label">MCQ Categories</div>
707
+ </div>
708
+ <div class="stat-card">
709
+ <div class="stat-num">3</div>
710
+ <div class="stat-label">Languages Supported</div>
711
+ </div>
712
+ </div>
713
+
714
+ <h2><span class="h2-icon">β—ˆ</span> What is this API?</h2>
715
+ <p>
716
+ The Abdullah Bot API is a production-ready backend that powers Islamic AI companions.
717
+ It wraps Hugging Face's Router API with a 3-tier model fallback system, integrates
718
+ Supabase for persistent journey tracking, and delivers structured, tone-aware responses
719
+ grounded in Quranic wisdom.
720
+ </p>
721
+ <p>
722
+ The API is designed to be consumed by Flutter mobile apps, web frontends, or any
723
+ HTTP client. Every response includes a <code>voice_answer</code>, optional
724
+ <code>middle_section</code> detail, <code>follow_up</code> prompt, and
725
+ <code>next_action_guidance</code> β€” making it trivial to build rich, structured UIs.
726
+ </p>
727
+
728
+ <h2><span class="h2-icon">β—ˆ</span> Architecture</h2>
729
+ <ul class="feature-list">
730
+ <li><strong>FastAPI</strong> backend hosted on Hugging Face Spaces (free tier)</li>
731
+ <li><strong>Llama-3-8B β†’ Llama-3.1-8B β†’ Llama-3.2-1B</strong> automatic fallback chain</li>
732
+ <li><strong>Supabase</strong> Postgres for users, journeys, MCQ answers, chat history</li>
733
+ <li><strong>Al-Quran Cloud API</strong> for real-time Quranic verse fetching</li>
734
+ <li><strong>Tone & language detection</strong> β€” 13 tones, Arabic / Urdu / Roman-Urdu / English</li>
735
+ <li><strong>Retry logic</strong> with exponential backoff on DB cold starts</li>
736
+ <li>Structured response format optimised for voice + text hybrid UIs</li>
737
+ </ul>
738
+
739
+ <div class="callout info">
740
+ <span class="callout-icon">ℹ️</span>
741
+ <div><strong>Base URL:</strong> <code>https://frnklnwrld-me.hf.space</code><br>
742
+ All endpoints return JSON. No API key required from clients β€” the HF token is server-side only.</div>
743
+ </div>
744
+ </section>
745
+
746
+ <!-- ══ QUICK START ══ -->
747
+ <section id="sec-quickstart" class="section">
748
+ <div class="hero-eyebrow">Getting Started</div>
749
+ <h1 class="page-title">Quick <em>Start</em></h1>
750
+ <p class="page-desc">Send your first message in under 2 minutes.</p>
751
+
752
+ <div class="steps">
753
+ <div class="step">
754
+ <div class="step-num">01</div>
755
+ <div class="step-content">
756
+ <h4>Send a POST to /chat</h4>
757
+ <p>The only required fields are <code>message</code> and <code>user_id</code>. The API handles everything else automatically.</p>
758
+ </div>
759
+ </div>
760
+ <div class="step">
761
+ <div class="step-num">02</div>
762
+ <div class="step-content">
763
+ <h4>Receive a structured response</h4>
764
+ <p>Every response contains <code>voice_answer</code> (short, speakable), <code>middle_section</code> (detail), and <code>follow_up</code> (next prompt).</p>
765
+ </div>
766
+ </div>
767
+ <div class="step">
768
+ <div class="step-num">03</div>
769
+ <div class="step-content">
770
+ <h4>Start a journey (optional)</h4>
771
+ <p>Send <code>"start journey"</code> to begin MCQ-based self-assessment. The API tracks progress per user per category in Supabase.</p>
772
+ </div>
773
+ </div>
774
+ </div>
775
+
776
+ <h3>cURL Example</h3>
777
+ <div class="code-wrap">
778
+ <div class="code-lang">bash</div>
779
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
780
+ <pre>curl -X POST https://frnklnwrld-me.hf.space/chat \
781
+ -H "Content-Type: application/json" \
782
+ -d '{
783
+ "message": "What is the meaning of patience in Islam?",
784
+ "user_id": "Abdullah123",
785
+ "category": "Religious Self"
786
+ }'</pre>
787
+ </div>
788
+
789
+ <h3>JavaScript (fetch)</h3>
790
+ <div class="code-wrap">
791
+ <div class="code-lang">javascript</div>
792
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
793
+ <pre>const response = await fetch('https://frnklnwrld-me.hf.space/chat', {
794
+ method: 'POST',
795
+ headers: { 'Content-Type': 'application/json' },
796
+ body: JSON.stringify({
797
+ message: 'What is sabr?',
798
+ user_id: 'user_abc123',
799
+ category: 'Religious Self'
800
+ })
801
+ });
802
+
803
+ const data = await response.json();
804
+ console.log(data.voice_answer); // Short spoken response
805
+ console.log(data.middle_section); // Detailed notes
806
+ console.log(data.follow_up); // Next conversation prompt</pre>
807
+ </div>
808
+
809
+ <h3>Python (requests)</h3>
810
+ <div class="code-wrap">
811
+ <div class="code-lang">python</div>
812
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
813
+ <pre>import requests
814
+
815
+ res = requests.post(
816
+ "https://frnklnwrld-me.hf.space/chat",
817
+ json={
818
+ "message": "I feel sad today",
819
+ "user_id": "testuser",
820
+ "category": "Emotional Self"
821
+ }
822
+ )
823
+ data = res.json()
824
+ print(data["voice_answer"])
825
+ print(data["model_used"]) # Which Llama model responded</pre>
826
+ </div>
827
+
828
+ <h3>Sample Response</h3>
829
+ <div class="code-wrap">
830
+ <div class="code-lang">json</div>
831
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
832
+ <pre>{
833
+ "status": "insight_only",
834
+ "voice_answer": "SubhanAllah, I hear the weight in your words. Remember, after hardship comes ease (Quran 94:5). You are not alone β€” Allah is closer to you than your jugular vein.",
835
+ "middle_section": "Sadness is a human experience acknowledged in the Quran. The Prophet ο·Ί himself experienced grief deeply. Allowing yourself to feel is not weakness β€” it is honesty before Allah.",
836
+ "middle_label": "Detailed Notes",
837
+ "follow_up": "Would you like to explore what specifically is weighing on your heart today?",
838
+ "references": "Quran 94:5 β€” Indeed, with hardship comes ease.",
839
+ "model_used": "Llama-3-8B-Instruct",
840
+ "next_action_guidance": {
841
+ "type": "general_chat",
842
+ "message": "Assalamu alaikum. How fares your heart today?",
843
+ "suggested_delay_hours": 6,
844
+ "islamic_reminder": "Quranic Principle: Do not despair of Allah's mercy (39:53)."
845
+ }
846
+ }</pre>
847
+ </div>
848
+ </section>
849
+
850
+ <!-- ══ AUTH ══ -->
851
+ <section id="sec-auth" class="section">
852
+ <div class="hero-eyebrow">Security</div>
853
+ <h1 class="page-title">Authenti<em>cation</em></h1>
854
+
855
+ <div class="callout info">
856
+ <span class="callout-icon">βœ…</span>
857
+ <div><strong>No client-side API key needed.</strong> The API is publicly accessible. All sensitive credentials (HF token, Supabase keys) are stored as server-side secrets on Hugging Face Spaces.</div>
858
+ </div>
859
+
860
+ <h2><span class="h2-icon">β—ˆ</span> Server-Side Secrets</h2>
861
+ <p>The following environment variables must be set in your HF Space <strong>Settings β†’ Secrets</strong>:</p>
862
+
863
+ <div class="code-wrap">
864
+ <div class="code-lang">env</div>
865
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
866
+ <pre>HF_TOKEN=hf_xxxxxxxxxxxxxxxxxx # Hugging Face token with Inference API access
867
+ SUPABASE_URL=https://xxxx.supabase.co # Your Supabase project URL
868
+ SUPABASE_SERVICE_KEY=sbp_xxxxxxxxxxxx # Service role key (NOT anon key)</pre>
869
+ </div>
870
+
871
+ <div class="callout warning">
872
+ <span class="callout-icon">⚠️</span>
873
+ <div><strong>Never commit credentials to code.</strong> Use the HF Spaces Secrets UI. If a key was ever hardcoded, regenerate it immediately in Supabase Dashboard β†’ Settings β†’ API β†’ Regenerate.</div>
874
+ </div>
875
+
876
+ <h2><span class="h2-icon">β—ˆ</span> User Identity</h2>
877
+ <p>
878
+ Users are identified by <code>user_id</code> (display name string) in every request.
879
+ There is no JWT/session auth β€” the API trusts the client-provided <code>user_id</code>.
880
+ For production apps, validate identity in your own middleware before hitting this API.
881
+ </p>
882
+ </section>
883
+
884
+ <!-- ══ /chat ══ -->
885
+ <section id="sec-chat" class="section">
886
+ <div class="hero-eyebrow">API Reference</div>
887
+ <h1 class="page-title"><em>/chat</em></h1>
888
+ <p class="page-desc">The core endpoint. Handles all conversation, journey flow, and MCQ submission.</p>
889
+
890
+ <div class="endpoint open">
891
+ <div class="endpoint-head" onclick="toggleEndpoint(this.parentElement)">
892
+ <span class="method POST">POST</span>
893
+ <span class="endpoint-path">/chat</span>
894
+ <span class="endpoint-summary">Main conversation endpoint</span>
895
+ <span class="chevron">β–Ύ</span>
896
+ </div>
897
+ <div class="endpoint-body">
898
+
899
+ <h3>Request Body</h3>
900
+ <table class="param-table">
901
+ <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
902
+ <tbody>
903
+ <tr><td><span class="pname">message</span><span class="req">required</span></td><td><span class="ptype">string</span></td><td class="pdesc">User's message. Max 1000 characters. Supports English, Urdu (script + Roman), Arabic.</td></tr>
904
+ <tr><td><span class="pname">user_id</span><span class="req">required</span></td><td><span class="ptype">string</span></td><td class="pdesc">Unique user identifier / display name. Used to look up journey and chat history in Supabase.</td></tr>
905
+ <tr><td><span class="pname">category</span><span class="opt">optional</span></td><td><span class="ptype">string</span></td><td class="pdesc">Journey category context. Default: <code>"General"</code>. Use values from <code>/categories</code>.</td></tr>
906
+ <tr><td><span class="pname">previous_summary</span><span class="opt">optional</span></td><td><span class="ptype">object</span></td><td class="pdesc">Previously returned <code>cumulative_summary</code> object to carry session context forward.</td></tr>
907
+ <tr><td><span class="pname">answers</span><span class="opt">optional</span></td><td><span class="ptype">array</span></td><td class="pdesc">MCQ answer submission array. Each item: <code>{question_num, answer, score}</code>.</td></tr>
908
+ </tbody>
909
+ </table>
910
+
911
+ <h3>Response Fields</h3>
912
+ <div style="margin:16px 0">
913
+ <div class="resp-field"><span class="rname">status</span><span class="rtype">string</span><span class="rdesc">One of: <code>insight_only</code>, <code>asking_questions</code>, <code>need_more_answers</code>, <code>session_complete</code>, <code>meta_response</code></span></div>
914
+ <div class="resp-field"><span class="rname">voice_answer</span><span class="rtype">string</span><span class="rdesc">Short, conversational response β€” designed for TTS / display as primary message.</span></div>
915
+ <div class="resp-field"><span class="rname">middle_section</span><span class="rtype">string?</span><span class="rdesc">Extended detail, practical takeaway, or reflective content. May be null for simple exchanges.</span></div>
916
+ <div class="resp-field"><span class="rname">middle_label</span><span class="rtype">string?</span><span class="rdesc">Label for middle_section, e.g. "Detailed Notes", "Practical Takeaway", "Progress Summary".</span></div>
917
+ <div class="resp-field"><span class="rname">current_mcqs</span><span class="rtype">array?</span><span class="rdesc">Array of MCQ objects to display. Each: <code>{question: string, options: string[]}</code>.</span></div>
918
+ <div class="resp-field"><span class="rname">answers_summary</span><span class="rtype">object?</span><span class="rdesc">Summary of just-submitted answers: <code>{batch_avg: number}</code>.</span></div>
919
+ <div class="resp-field"><span class="rname">cumulative_summary</span><span class="rtype">object?</span><span class="rdesc">Full journey progress object. Persist and send back as <code>previous_summary</code>.</span></div>
920
+ <div class="resp-field"><span class="rname">follow_up</span><span class="rtype">string?</span><span class="rdesc">Suggested next question or action to continue the conversation.</span></div>
921
+ <div class="resp-field"><span class="rname">references</span><span class="rtype">string?</span><span class="rdesc">Quranic/Hadith reference when the message is Islamic in nature.</span></div>
922
+ <div class="resp-field"><span class="rname">next_action_guidance</span><span class="rtype">object</span><span class="rdesc">Always present. Contains <code>{type, message, suggested_delay_hours, islamic_reminder}</code>.</span></div>
923
+ <div class="resp-field"><span class="rname">model_used</span><span class="rtype">string?</span><span class="rdesc">Which model responded: <code>Llama-3-8B-Instruct</code>, <code>Llama-3.1-8B-Instruct</code>, <code>Llama-3.2-1B-Instruct</code>, or <code>fallback</code>.</span></div>
924
+ </div>
925
+
926
+ <h3>Status Values Explained</h3>
927
+ <table class="param-table">
928
+ <thead><tr><th>Status</th><th>Meaning</th><th>UI Action</th></tr></thead>
929
+ <tbody>
930
+ <tr><td><code>insight_only</code></td><td class="pdesc">General AI response</td><td class="pdesc">Display voice_answer + optional middle_section</td></tr>
931
+ <tr><td><code>asking_questions</code></td><td class="pdesc">MCQ journey started</td><td class="pdesc">Render <code>current_mcqs</code> as a form</td></tr>
932
+ <tr><td><code>need_more_answers</code></td><td class="pdesc">More answers needed</td><td class="pdesc">Show remaining MCQs</td></tr>
933
+ <tr><td><code>session_complete</code></td><td class="pdesc">All MCQs answered</td><td class="pdesc">Show progress summary + celebrate</td></tr>
934
+ <tr><td><code>meta_response</code></td><td class="pdesc">User asked about bot behavior</td><td class="pdesc">Display explanation</td></tr>
935
+ </tbody>
936
+ </table>
937
+
938
+ </div>
939
+ </div>
940
+ </section>
941
+
942
+ <!-- ══ /journey ══ -->
943
+ <section id="sec-journey" class="section">
944
+ <div class="hero-eyebrow">API Reference</div>
945
+ <h1 class="page-title"><em>/journey</em></h1>
946
+
947
+ <div class="endpoint open">
948
+ <div class="endpoint-head" onclick="toggleEndpoint(this.parentElement)">
949
+ <span class="method GET">GET</span>
950
+ <span class="endpoint-path">/journey/{user_id}</span>
951
+ <span class="endpoint-summary">Fetch user progress</span>
952
+ <span class="chevron">β–Ύ</span>
953
+ </div>
954
+ <div class="endpoint-body">
955
+ <h3>Path & Query Parameters</h3>
956
+ <table class="param-table">
957
+ <thead><tr><th>Param</th><th>Type</th><th>Description</th></tr></thead>
958
+ <tbody>
959
+ <tr><td><span class="pname">user_id</span><span class="req">path</span></td><td><span class="ptype">string</span></td><td class="pdesc">The user's display name / identifier.</td></tr>
960
+ <tr><td><span class="pname">category</span><span class="opt">query</span></td><td><span class="ptype">string</span></td><td class="pdesc">Filter to a specific journey category. Default: <code>"General"</code>.</td></tr>
961
+ </tbody>
962
+ </table>
963
+
964
+ <h3>Example</h3>
965
+ <div class="code-wrap">
966
+ <div class="code-lang">bash</div>
967
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
968
+ <pre>GET /journey/Abdullah123?category=Religious+Self</pre>
969
+ </div>
970
+
971
+ <h3>Response</h3>
972
+ <div class="code-wrap">
973
+ <div class="code-lang">json</div>
974
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
975
+ <pre>{
976
+ "user_id": "Abdullah123",
977
+ "category": "Religious Self",
978
+ "total_sessions": 12,
979
+ "spiritual_stage": "developing",
980
+ "member_since": "2025-01-15",
981
+ "cumulative_summary": {
982
+ "overall_avg": 3.8,
983
+ "progress_note": "Recent avg: 4.2/5 | Improving MashaAllah"
984
+ },
985
+ "main_loopholes": ["Low in Q3", "Low in Q7"],
986
+ "pending_questions": 3,
987
+ "recent_activity": [...]
988
+ }</pre>
989
+ </div>
990
+ </div>
991
+ </div>
992
+ </section>
993
+
994
+ <!-- ══ /categories ══ -->
995
+ <section id="sec-categories" class="section">
996
+ <div class="hero-eyebrow">API Reference</div>
997
+ <h1 class="page-title"><em>/categories</em></h1>
998
+
999
+ <div class="endpoint open">
1000
+ <div class="endpoint-head" onclick="toggleEndpoint(this.parentElement)">
1001
+ <span class="method GET">GET</span>
1002
+ <span class="endpoint-path">/categories</span>
1003
+ <span class="endpoint-summary">List all MCQ journey categories</span>
1004
+ <span class="chevron">β–Ύ</span>
1005
+ </div>
1006
+ <div class="endpoint-body">
1007
+ <p>Returns all available self-assessment journey categories with question counts. Use these values in the <code>category</code> field of other requests.</p>
1008
+ <div class="code-wrap">
1009
+ <div class="code-lang">json</div>
1010
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1011
+ <pre>{
1012
+ "categories": [
1013
+ "Religious Self",
1014
+ "Emotional Self",
1015
+ "Intellectual Self",
1016
+ "Social Self",
1017
+ "Physical Self",
1018
+ "Financial Self",
1019
+ "Family Self",
1020
+ "Professional Self",
1021
+ "Creative Self",
1022
+ "Community Self",
1023
+ "General"
1024
+ ],
1025
+ "total_questions": {
1026
+ "Religious Self": 12,
1027
+ "Emotional Self": 10,
1028
+ "General": 8
1029
+ },
1030
+ "description": "Categories for spiritual and personal development journeys"
1031
+ }</pre>
1032
+ </div>
1033
+ </div>
1034
+ </div>
1035
+ </section>
1036
+
1037
+ <!-- ══ /reset ══ -->
1038
+ <section id="sec-reset" class="section">
1039
+ <div class="hero-eyebrow">API Reference</div>
1040
+ <h1 class="page-title"><em>/reset-journey</em></h1>
1041
+
1042
+ <div class="endpoint open">
1043
+ <div class="endpoint-head" onclick="toggleEndpoint(this.parentElement)">
1044
+ <span class="method POST">POST</span>
1045
+ <span class="endpoint-path">/reset-journey/{user_id}</span>
1046
+ <span class="endpoint-summary">Reset journey in a category</span>
1047
+ <span class="chevron">β–Ύ</span>
1048
+ </div>
1049
+ <div class="endpoint-body">
1050
+ <p>Clears all journey progress (MCQ answers, summary, loopholes, pending questions) for a user in a specific category. The user record and chat history are preserved.</p>
1051
+ <table class="param-table">
1052
+ <thead><tr><th>Param</th><th>Type</th><th>Description</th></tr></thead>
1053
+ <tbody>
1054
+ <tr><td><span class="pname">user_id</span><span class="req">path</span></td><td><span class="ptype">string</span></td><td class="pdesc">User to reset.</td></tr>
1055
+ <tr><td><span class="pname">category</span><span class="opt">query</span></td><td><span class="ptype">string</span></td><td class="pdesc">Category to reset. Default: <code>"General"</code>.</td></tr>
1056
+ </tbody>
1057
+ </table>
1058
+ <div class="code-wrap">
1059
+ <div class="code-lang">json β€” Response</div>
1060
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1061
+ <pre>{
1062
+ "status": "success",
1063
+ "message": "Journey reset for Abdullah123 in Religious Self. Ready to start fresh, insha'Allah!",
1064
+ "islamic_reminder": "Quranic Principle: Indeed, with hardship comes ease (94:5)."
1065
+ }</pre>
1066
+ </div>
1067
+ </div>
1068
+ </div>
1069
+ </section>
1070
+
1071
+ <!-- ══ /health ══ -->
1072
+ <section id="sec-health" class="section">
1073
+ <div class="hero-eyebrow">API Reference</div>
1074
+ <h1 class="page-title"><em>/health</em></h1>
1075
+
1076
+ <div class="endpoint open">
1077
+ <div class="endpoint-head" onclick="toggleEndpoint(this.parentElement)">
1078
+ <span class="method GET">GET</span>
1079
+ <span class="endpoint-path">/health</span>
1080
+ <span class="endpoint-summary">API status & model config</span>
1081
+ <span class="chevron">β–Ύ</span>
1082
+ </div>
1083
+ <div class="endpoint-body">
1084
+ <p>Use this to verify the API is running and which models are configured. Recommended for Flutter app startup checks.</p>
1085
+ <div class="code-wrap">
1086
+ <div class="code-lang">json</div>
1087
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1088
+ <pre>{
1089
+ "status": "OK",
1090
+ "mode": "HF Router API (Free Tier)",
1091
+ "models": [
1092
+ "Llama-3-8B-Instruct",
1093
+ "Llama-3.1-8B-Instruct",
1094
+ "Llama-3.2-1B-Instruct"
1095
+ ],
1096
+ "api_url": "https://router.huggingface.co/v1/chat/completions",
1097
+ "token_configured": true
1098
+ }</pre>
1099
+ </div>
1100
+ </div>
1101
+ </div>
1102
+ </section>
1103
+
1104
+ <!-- ══ TONES ══ -->
1105
+ <section id="sec-tones" class="section">
1106
+ <div class="hero-eyebrow">Concepts</div>
1107
+ <h1 class="page-title">Tone <em>Detection</em></h1>
1108
+ <p class="page-desc">The API automatically detects the emotional tone of every message and adjusts response style, persona, and language accordingly.</p>
1109
+
1110
+ <p>Tone is detected via multilingual keyword matching across 13 emotional states. The detected tone shapes the system prompt, persona, and Islamic framing of the response β€” no configuration required from the client.</p>
1111
+
1112
+ <div class="tone-grid">
1113
+ <div class="tone-card"><div class="tone-name">sad</div><div class="tone-desc">Gentle, Quranic comfort. Validates feelings, offers 1-2 grounded steps.</div></div>
1114
+ <div class="tone-card"><div class="tone-name">anxious</div><div class="tone-desc">Soothing, tawakkul-based grounding. 3 practical steps.</div></div>
1115
+ <div class="tone-card"><div class="tone-name">angry</div><div class="tone-desc">Calm, de-escalating. Short sentences, prophetic patience.</div></div>
1116
+ <div class="tone-card"><div class="tone-name">energetic</div><div class="tone-desc">High-energy, motivating. Islamic encouragement + action prompts.</div></div>
1117
+ <div class="tone-card"><div class="tone-name">curious</div><div class="tone-desc">Engaging, instructive. Concise explanation + follow-up question.</div></div>
1118
+ <div class="tone-card"><div class="tone-name">confused</div><div class="tone-desc">Supportive, numbered steps. Asks one clarifying question.</div></div>
1119
+ <div class="tone-card"><div class="tone-name">grateful</div><div class="tone-desc">Warm, reflective. Acknowledges with Alhamdulillah.</div></div>
1120
+ <div class="tone-card"><div class="tone-name">reflective</div><div class="tone-desc">Introspective. Quranic metaphor + one practical takeaway.</div></div>
1121
+ <div class="tone-card"><div class="tone-name">urgent</div><div class="tone-desc">Direct, numbered steps (1-3). Safety check when relevant.</div></div>
1122
+ <div class="tone-card"><div class="tone-name">dive_deep</div><div class="tone-desc">Structured sections: Summary / Details / Example.</div></div>
1123
+ <div class="tone-card"><div class="tone-name">humorous</div><div class="tone-desc">Playful, kind. Maintains adab (respect).</div></div>
1124
+ <div class="tone-card"><div class="tone-name">skeptical</div><div class="tone-desc">Evidence-focused. Islamic sources + counterexample.</div></div>
1125
+ <div class="tone-card"><div class="tone-name">neutral</div><div class="tone-desc">Balanced, friendly. Default for all unmatched messages.</div></div>
1126
+ </div>
1127
+
1128
+ <div class="callout info">
1129
+ <span class="callout-icon">πŸ’‘</span>
1130
+ <div>Tone keywords work in <strong>English</strong>, <strong>Roman Urdu</strong> (e.g. <code>dukhi</code>, <code>ghussa</code>), and <strong>Urdu script</strong> (e.g. <code>افسردہ</code>, <code>غءہ</code>). The <code>model_used</code> field in the response won't tell you the tone β€” but <code>next_action_guidance.message</code> will reflect the tone persona used.</div>
1131
+ </div>
1132
+ </section>
1133
+
1134
+ <!-- ══ JOURNEY FLOW ══ -->
1135
+ <section id="sec-journey-flow" class="section">
1136
+ <div class="hero-eyebrow">Concepts</div>
1137
+ <h1 class="page-title">Journey <em>Flow</em></h1>
1138
+ <p class="page-desc">The journey system enables longitudinal self-assessment across 11 spiritual and personal development categories.</p>
1139
+
1140
+ <div class="steps">
1141
+ <div class="step">
1142
+ <div class="step-num">1</div>
1143
+ <div class="step-content">
1144
+ <h4>User sends "start journey"</h4>
1145
+ <p>API generates 6 MCQs from the selected category (or resumes pending questions). Returns <code>status: "asking_questions"</code> with <code>current_mcqs</code> array.</p>
1146
+ </div>
1147
+ </div>
1148
+ <div class="step">
1149
+ <div class="step-num">2</div>
1150
+ <div class="step-content">
1151
+ <h4>User submits answers</h4>
1152
+ <p>Send answers in <code>answers</code> array: <code>[{question_num: 1, answer: "Often", score: 4}]</code>. Or inline in message text: <code>"1. Often 2. Rarely 3. Always"</code>.</p>
1153
+ </div>
1154
+ </div>
1155
+ <div class="step">
1156
+ <div class="step-num">3</div>
1157
+ <div class="step-content">
1158
+ <h4>Progress computed & saved</h4>
1159
+ <p>Scores averaged with exponential smoothing (30% new / 70% historical). Low-scoring answers recorded as "loopholes" for targeted follow-up.</p>
1160
+ </div>
1161
+ </div>
1162
+ <div class="step">
1163
+ <div class="step-num">4</div>
1164
+ <div class="step-content">
1165
+ <h4>Session complete</h4>
1166
+ <p>Returns <code>status: "session_complete"</code> with <code>cumulative_summary</code>. Store this and pass back as <code>previous_summary</code> in future requests.</p>
1167
+ </div>
1168
+ </div>
1169
+ </div>
1170
+
1171
+ <h3>MCQ Options & Score Map</h3>
1172
+ <div class="code-wrap">
1173
+ <div class="code-lang">json</div>
1174
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1175
+ <pre>{
1176
+ "options": ["Always", "Often", "Sometimes", "Rarely", "Never"],
1177
+ "scores": [ 5, 4, 3, 2, 1 ]
1178
+ }</pre>
1179
+ </div>
1180
+ </section>
1181
+
1182
+ <!-- ══ MULTILINGUAL ══ -->
1183
+ <section id="sec-multilingual" class="section">
1184
+ <div class="hero-eyebrow">Concepts</div>
1185
+ <h1 class="page-title"><em>Multi</em>lingual</h1>
1186
+ <p class="page-desc">The API detects and mirrors the user's language automatically β€” no configuration needed.</p>
1187
+
1188
+ <h2><span class="h2-icon">β—ˆ</span> Supported Languages</h2>
1189
+ <ul class="feature-list">
1190
+ <li><strong>English</strong> β€” default, full feature support</li>
1191
+ <li><strong>Urdu script</strong> (Ω†Ψ³ΨͺΨΉΩ„ΫŒΩ‚) β€” detected via Unicode range <code>U+0600–U+06FF</code> + Urdu-specific characters</li>
1192
+ <li><strong>Roman Urdu</strong> β€” detected via keyword matching (ap, kya, kyun, bhai, alaikum, hain…)</li>
1193
+ <li><strong>Arabic</strong> β€” detected via Unicode; uses Arabic Islamic terminology</li>
1194
+ </ul>
1195
+
1196
+ <h3>Example β€” Urdu Input</h3>
1197
+ <div class="code-wrap">
1198
+ <div class="code-lang">json β€” Request</div>
1199
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1200
+ <pre>{
1201
+ "message": "Ψ’Ψ¬ Ω…ΫŒΪΊ بہΨͺ Ψ§Ψ―Ψ§Ψ³ ہوں",
1202
+ "user_id": "user123"
1203
+ }</pre>
1204
+ </div>
1205
+ <p>The API detects Urdu script, sets <code>detected_lang: "ur"</code>, and responds in Urdu with culturally relevant Islamic phrasing and dua.</p>
1206
+ </section>
1207
+
1208
+ <!-- ══ FALLBACK ══ -->
1209
+ <section id="sec-fallback" class="section">
1210
+ <div class="hero-eyebrow">Concepts</div>
1211
+ <h1 class="page-title">Model <em>Fallback</em></h1>
1212
+ <p class="page-desc">A 3-tier automatic fallback ensures the API stays responsive even when primary models are rate-limited or unavailable.</p>
1213
+
1214
+ <h2><span class="h2-icon">β—ˆ</span> Fallback Chain</h2>
1215
+ <div class="code-wrap">
1216
+ <div class="code-lang">priority order</div>
1217
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1218
+ <pre>1. meta-llama/Meta-Llama-3-8B-Instruct β†’ Best quality
1219
+ 2. meta-llama/Llama-3.1-8B-Instruct β†’ Latest stable
1220
+ 3. meta-llama/Llama-3.2-1B-Instruct β†’ Fastest / lightest</pre>
1221
+ </div>
1222
+
1223
+ <p>Each model is tried with up to 2 retries and exponential backoff on rate limits (429). If all 3 models fail, a graceful Islamic fallback message is returned rather than a 500 error.</p>
1224
+
1225
+ <h3>Retry Logic</h3>
1226
+ <div class="code-wrap">
1227
+ <div class="code-lang">python</div>
1228
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1229
+ <pre>for model in MODELS: # Try each model in priority order
1230
+ for attempt in range(2): # Up to 2 retries per model
1231
+ if status == 429:
1232
+ time.sleep(2 ** attempt) # 1s, then 2s backoff
1233
+ continue
1234
+ if status == 200:
1235
+ return answer, model_name # Success β€” stop here
1236
+ break # Other error β€” try next model</pre>
1237
+ </div>
1238
+
1239
+ <div class="callout info">
1240
+ <span class="callout-icon">ℹ️</span>
1241
+ <div>The <code>model_used</code> field in every response tells you which model actually answered. Values: <code>Llama-3-8B-Instruct</code>, <code>Llama-3.1-8B-Instruct</code>, <code>Llama-3.2-1B-Instruct</code>, <code>fallback</code>, or <code>emergency_fallback</code>.</div>
1242
+ </div>
1243
+ </section>
1244
+
1245
+ <!-- ══ FLUTTER ══ -->
1246
+ <section id="sec-flutter" class="section">
1247
+ <div class="hero-eyebrow">Integration</div>
1248
+ <h1 class="page-title">Flutter <em>Guide</em></h1>
1249
+ <p class="page-desc">A complete example for integrating Abdullah Bot into a Flutter/Dart app.</p>
1250
+
1251
+ <h3>Service Class</h3>
1252
+ <div class="code-wrap">
1253
+ <div class="code-lang">dart</div>
1254
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1255
+ <pre>import 'dart:convert';
1256
+ import 'package:http/http.dart' as http;
1257
+
1258
+ class AbdullahBotService {
1259
+ static const String baseUrl = 'https://frnklnwrld-me.hf.space';
1260
+
1261
+ Future sendMessage({
1262
+ required String message,
1263
+ required String userId,
1264
+ String category = 'General',
1265
+ Map? previousSummary,
1266
+ List? answers,
1267
+ }) async {
1268
+ final response = await http.post(
1269
+ Uri.parse('$baseUrl/chat'),
1270
+ headers: {'Content-Type': 'application/json'},
1271
+ body: jsonEncode({
1272
+ 'message': message,
1273
+ 'user_id': userId,
1274
+ 'category': category,
1275
+ if (previousSummary != null) 'previous_summary': previousSummary,
1276
+ if (answers != null) 'answers': answers,
1277
+ }),
1278
+ );
1279
+
1280
+ if (response.statusCode == 200) {
1281
+ return jsonDecode(response.body);
1282
+ } else if (response.statusCode == 503) {
1283
+ throw Exception('Service waking up β€” please retry in a moment');
1284
+ } else {
1285
+ throw Exception('API error: ${response.statusCode}');
1286
+ }
1287
+ }
1288
+
1289
+ Future getJourney(String userId, {String category = 'General'}) async {
1290
+ final response = await http.get(
1291
+ Uri.parse('$baseUrl/journey/$userId?category=$category'),
1292
+ );
1293
+ return jsonDecode(response.body);
1294
+ }
1295
+ }</pre>
1296
+ </div>
1297
+
1298
+ <h3>Widget Usage</h3>
1299
+ <div class="code-wrap">
1300
+ <div class="code-lang">dart</div>
1301
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1302
+ <pre>// In your chat widget:
1303
+ final bot = AbdullahBotService();
1304
+ final data = await bot.sendMessage(
1305
+ message: userInput,
1306
+ userId: currentUser.id,
1307
+ category: selectedCategory,
1308
+ );
1309
+
1310
+ // Render the structured response:
1311
+ Text(data['voice_answer']) // Primary message bubble
1312
+ Text(data['middle_section'] ?? '') // Expandable detail card
1313
+ Text(data['follow_up'] ?? '') // Suggested reply chip
1314
+ Text(data['references'] ?? '') // Quranic reference footer</pre>
1315
+ </div>
1316
+
1317
+ <div class="callout warning">
1318
+ <span class="callout-icon">⚠️</span>
1319
+ <div><strong>Cold start handling:</strong> On first request after inactivity, Supabase may take 3-7s to wake. Show a loading indicator and handle <code>503</code> responses with a "Waking up…" message and auto-retry after 5s.</div>
1320
+ </div>
1321
+ </section>
1322
+
1323
+ <!-- ══ ERRORS ══ -->
1324
+ <section id="sec-errors" class="section">
1325
+ <div class="hero-eyebrow">Integration</div>
1326
+ <h1 class="page-title">Error <em>Handling</em></h1>
1327
+
1328
+ <div class="divider"></div>
1329
+ <div class="error-row">
1330
+ <span class="ecode e400">400</span>
1331
+ <div><strong style="color:var(--text)">Bad Request</strong><br><span style="color:var(--text2);font-size:.85rem">Missing required fields. Check that <code>message</code> and <code>user_id</code> are present and non-empty.</span></div>
1332
+ </div>
1333
+ <div class="error-row">
1334
+ <span class="ecode e503">503</span>
1335
+ <div><strong style="color:var(--text)">Service Unavailable</strong><br><span style="color:var(--text2);font-size:.85rem">Supabase cold start. Retry after 5 seconds. The API returns a human-readable <code>detail</code> message: <code>"Database is waking up β€” please retry in a few seconds."</code></span></div>
1336
+ </div>
1337
+ <div class="error-row">
1338
+ <span class="ecode e500">500</span>
1339
+ <div><strong style="color:var(--text)">Internal Server Error</strong><br><span style="color:var(--text2);font-size:.85rem">Unexpected error. Check HF Space logs. Common causes: missing secrets, Supabase schema mismatch, all 3 Llama models failed simultaneously.</span></div>
1340
+ </div>
1341
+ <div class="divider"></div>
1342
+
1343
+ <h3>Recommended Client Pattern</h3>
1344
+ <div class="code-wrap">
1345
+ <div class="code-lang">javascript</div>
1346
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1347
+ <pre>async function chatWithRetry(message, userId, retries = 3) {
1348
+ for (let i = 0; i < retries; i++) {
1349
+ try {
1350
+ const res = await fetch('/chat', {
1351
+ method: 'POST',
1352
+ headers: { 'Content-Type': 'application/json' },
1353
+ body: JSON.stringify({ message, user_id: userId })
1354
+ });
1355
+
1356
+ const text = await res.text();
1357
+ let data;
1358
+ try { data = JSON.parse(text); }
1359
+ catch { throw new Error('Server error: ' + text.slice(0, 100)); }
1360
+
1361
+ if (res.status === 503) {
1362
+ // Supabase cold start β€” wait and retry
1363
+ await new Promise(r => setTimeout(r, 5000));
1364
+ continue;
1365
+ }
1366
+ if (!res.ok) throw new Error(data.detail || 'Request failed');
1367
+ return data;
1368
+
1369
+ } catch (err) {
1370
+ if (i === retries - 1) throw err;
1371
+ await new Promise(r => setTimeout(r, 2000 * (i + 1)));
1372
+ }
1373
+ }
1374
+ }</pre>
1375
+ </div>
1376
+ </section>
1377
+
1378
+ <!-- ══ UPWORK ══ -->
1379
+ <section id="sec-upwork" class="section">
1380
+ <div class="hero-eyebrow">Upwork Proposal Materials</div>
1381
+ <h1 class="page-title">Proposal <em>Kit</em></h1>
1382
+ <p class="page-desc">Ready-to-use materials for hiring Flutter developers, backend engineers, or AI integration specialists on Upwork.</p>
1383
+
1384
+ <div class="proposal-box">
1385
+ <h3>🎯 Proposal Template β€” Flutter Developer</h3>
1386
+ <p style="color:var(--text2);font-size:.9rem;margin-top:12px">Copy, personalise, and post as a job or use as an opening message.</p>
1387
+ </div>
1388
+
1389
+ <div class="code-wrap">
1390
+ <div class="code-lang">Upwork Job Post β€” Flutter Developer</div>
1391
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1392
+ <pre>Title: Flutter Developer β€” Islamic AI Companion App (Abdullah Bot)
1393
+
1394
+ We're building a Flutter mobile app powered by a live FastAPI backend
1395
+ (hosted on Hugging Face Spaces). The backend is complete and production-ready.
1396
+ We need an experienced Flutter developer to build the mobile UI.
1397
+
1398
+ === BACKEND OVERVIEW ===
1399
+ β€’ Live API: https://frnklnwrld-me.hf.space
1400
+ β€’ Swagger docs: https://frnklnwrld-me.hf.space/docs
1401
+ β€’ AI Model: Meta Llama-3 (3-tier fallback)
1402
+ β€’ Database: Supabase (Postgres)
1403
+ β€’ Features: Tone detection (13 modes), Journey tracking, MCQ system,
1404
+ Multilingual (English/Urdu/Arabic), Quranic references
1405
+
1406
+ === YOUR RESPONSIBILITIES ===
1407
+ 1. Build Flutter chat UI consuming POST /chat endpoint
1408
+ 2. Render structured responses: voice_answer + middle_section + follow_up
1409
+ 3. Implement MCQ journey screen (render current_mcqs array as interactive form)
1410
+ 4. Journey progress screen using GET /journey/{user_id}
1411
+ 5. Category picker using GET /categories
1412
+ 6. Handle cold-start 503 errors with graceful retry UX
1413
+ 7. State management (Provider or Riverpod preferred)
1414
+ 8. Local caching of cumulative_summary
1415
+
1416
+ === API RESPONSE STRUCTURE ===
1417
+ Every /chat response returns:
1418
+ - voice_answer (string): Primary message β€” display as main chat bubble
1419
+ - middle_section (string?): Detail card β€” collapsible
1420
+ - follow_up (string?): Suggested next message chip
1421
+ - current_mcqs (array?): MCQ questions to render as form
1422
+ - model_used (string): Which AI model responded
1423
+ - next_action_guidance (object): UI hints
1424
+
1425
+ === REQUIREMENTS ===
1426
+ β€’ 3+ years Flutter experience
1427
+ β€’ REST API integration (http or dio package)
1428
+ β€’ Clean architecture preferred
1429
+ β€’ Portfolio of chat/messaging UIs required
1430
+ β€’ Islamic/Arabic UI experience is a strong plus
1431
+
1432
+ === DELIVERABLES ===
1433
+ β€’ Complete Flutter project (clean code, well-commented)
1434
+ β€’ APK for testing
1435
+ β€’ README with setup instructions
1436
+
1437
+ Please share 2-3 examples of chat apps you've built.
1438
+ Budget: [your budget] | Timeline: 2-3 weeks</pre>
1439
+ </div>
1440
+
1441
+ <div class="callout info">
1442
+ <span class="callout-icon">πŸ’‘</span>
1443
+ <div><strong>Pro tip:</strong> Attach the live API URL (<code>https://frnklnwrld-me.hf.space</code>) and Swagger docs link to your Upwork job post. Developers can test the API before applying, which filters for engineers who actually read the brief.</div>
1444
+ </div>
1445
+
1446
+ <div class="proposal-box">
1447
+ <h3>🎯 Proposal Template β€” Backend / DevOps</h3>
1448
+ </div>
1449
+
1450
+ <div class="code-wrap">
1451
+ <div class="code-lang">Upwork Job Post β€” Backend Engineer</div>
1452
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1453
+ <pre>Title: FastAPI / Python Developer β€” Enhance Islamic AI Bot Backend
1454
+
1455
+ We have a production FastAPI backend for an Islamic AI companion app.
1456
+ The core is working. We need help with improvements and scaling.
1457
+
1458
+ === CURRENT STACK ===
1459
+ β€’ FastAPI + Python 3.10
1460
+ β€’ Hugging Face Spaces (hosting)
1461
+ β€’ Supabase (Postgres + REST)
1462
+ β€’ Meta Llama-3 via HF Router API (3-model fallback)
1463
+ β€’ Live at: https://frnklnwrld-me.hf.space
1464
+
1465
+ === TASKS ===
1466
+ 1. Add async support β€” convert sync DB calls to async (supabase-py async client)
1467
+ 2. Add proper rate limiting middleware (slowapi)
1468
+ 3. Implement background tasks for non-critical operations (chat logging)
1469
+ 4. Add Redis caching layer for frequently fetched data (categories, user journeys)
1470
+ 5. Improve error responses β€” standardise error schema across all endpoints
1471
+ 6. Add /admin endpoints for analytics (total users, avg scores by category)
1472
+ 7. Write pytest suite β€” target 80% coverage on business logic
1473
+ 8. Add Pydantic v2 migration (currently v1 syntax)
1474
+
1475
+ === CODEBASE HIGHLIGHTS ===
1476
+ β€’ Tone detection: 13 emotional tones, multilingual (EN/UR/AR)
1477
+ β€’ Model fallback: 3-tier Llama-3 chain with exponential backoff
1478
+ β€’ Journey tracking: MCQ system with score smoothing
1479
+ β€’ Structured responses: voice_answer + middle_section + follow_up format
1480
+
1481
+ === REQUIREMENTS ===
1482
+ β€’ Strong FastAPI & SQLAlchemy/PostgREST experience
1483
+ β€’ Supabase or PostgreSQL background
1484
+ β€’ Experience with async Python (asyncio, httpx)
1485
+ β€’ Understanding of LLM API integration patterns
1486
+
1487
+ Please share your GitHub or sample FastAPI project.
1488
+ Budget: [your budget] | Timeline: 1-2 weeks</pre>
1489
+ </div>
1490
+
1491
+ <div class="proposal-box">
1492
+ <h3>πŸ“‹ Technical Spec Sheet</h3>
1493
+ <p style="color:var(--text2);font-size:.9rem;margin-top:12px">Share this with any developer you're interviewing.</p>
1494
+ </div>
1495
+
1496
+ <div class="code-wrap">
1497
+ <div class="code-lang">Technical Spec β€” For Developer Interview</div>
1498
+ <button class="copy-btn" onclick="copyCode(this)">copy</button>
1499
+ <pre>=== ABDULLAH BOT API β€” TECHNICAL SPEC ===
1500
+
1501
+ LIVE ENDPOINTS
1502
+ Base: https://frnklnwrld-me.hf.space
1503
+ Docs: https://frnklnwrld-me.hf.space/docs
1504
+ Health: https://frnklnwrld-me.hf.space/health
1505
+
1506
+ KEY ENDPOINTS
1507
+ POST /chat β€” Main AI conversation (requires: message, user_id)
1508
+ GET /journey/:id β€” User progress stats
1509
+ GET /categories β€” Available MCQ categories (11 total)
1510
+ POST /reset-journey β€” Reset user journey in a category
1511
+
1512
+ RESPONSE FORMAT (all /chat responses)
1513
+ status: "insight_only" | "asking_questions" | "session_complete"
1514
+ voice_answer: string β€” short, speakable primary response
1515
+ middle_section: string? β€” extended detail or notes
1516
+ follow_up: string? β€” suggested next message
1517
+ current_mcqs: [{question, options[5]}]? β€” MCQ form data
1518
+ model_used: "Llama-3-8B-Instruct" | "fallback" | ...
1519
+ next_action_guidance: {type, message, suggested_delay_hours, islamic_reminder}
1520
+
1521
+ MCQ ANSWER SUBMISSION
1522
+ Send in: answers: [{question_num: 1, answer: "Often", score: 4}]
1523
+ Scores: Always=5, Often=4, Sometimes=3, Rarely=2, Never=1
1524
+
1525
+ ERROR CODES
1526
+ 400 β€” Missing required fields
1527
+ 503 β€” Supabase cold start (retry after 5s)
1528
+ 500 β€” Server error (check HF Space logs)
1529
+
1530
+ TECH STACK
1531
+ Python 3.10, FastAPI, Uvicorn
1532
+ supabase-py, httpx, requests
1533
+ pydantic v1, python-dotenv
1534
+
1535
+ SECRETS REQUIRED (HF Space Settings β†’ Secrets)
1536
+ HF_TOKEN, SUPABASE_URL, SUPABASE_SERVICE_KEY</pre>
1537
+ </div>
1538
+
1539
+ <div class="tag-row">
1540
+ <span class="tag">FastAPI</span>
1541
+ <span class="tag">Python</span>
1542
+ <span class="tag">Flutter</span>
1543
+ <span class="tag">Supabase</span>
1544
+ <span class="tag">Llama-3</span>
1545
+ <span class="tag">HuggingFace</span>
1546
+ <span class="tag">Islamic App</span>
1547
+ <span class="tag">Urdu/Arabic</span>
1548
+ <span class="tag">REST API</span>
1549
+ </div>
1550
+ </section>
1551
+
1552
+ </div><!-- /content -->
1553
+ </main>
1554
+
1555
+ <script>
1556
+ const SECTIONS = {
1557
+ 'overview': { el: 'sec-overview', label: 'Overview' },
1558
+ 'quickstart': { el: 'sec-quickstart', label: 'Quick Start' },
1559
+ 'auth': { el: 'sec-auth', label: 'Authentication' },
1560
+ 'chat': { el: 'sec-chat', label: '/chat' },
1561
+ 'journey': { el: 'sec-journey', label: '/journey' },
1562
+ 'categories': { el: 'sec-categories', label: '/categories' },
1563
+ 'reset': { el: 'sec-reset', label: '/reset-journey' },
1564
+ 'health': { el: 'sec-health', label: '/health' },
1565
+ 'tones': { el: 'sec-tones', label: 'Tone Detection' },
1566
+ 'journey-flow': { el: 'sec-journey-flow', label: 'Journey Flow' },
1567
+ 'multilingual': { el: 'sec-multilingual', label: 'Multilingual' },
1568
+ 'fallback': { el: 'sec-fallback', label: 'Model Fallback' },
1569
+ 'flutter': { el: 'sec-flutter', label: 'Flutter Guide' },
1570
+ 'errors': { el: 'sec-errors', label: 'Error Handling' },
1571
+ 'upwork': { el: 'sec-upwork', label: 'Upwork Proposal Kit' },
1572
+ };
1573
+
1574
+ function show(key) {
1575
+ const def = SECTIONS[key];
1576
+ if (!def) return;
1577
+
1578
+ // Hide all sections
1579
+ Object.values(SECTIONS).forEach(s => {
1580
+ const el = document.getElementById(s.el);
1581
+ if (el) el.classList.remove('active');
1582
+ });
1583
+
1584
+ // Show target
1585
+ const target = document.getElementById(def.el);
1586
+ if (target) target.classList.add('active');
1587
+
1588
+ // Update nav
1589
+ document.querySelectorAll('.nav-item').forEach(n => n.classList.remove('active'));
1590
+ event?.currentTarget?.classList.add('active');
1591
+
1592
+ // Update breadcrumb
1593
+ document.getElementById('breadcrumb-current').textContent = def.label;
1594
+
1595
+ // Scroll to top
1596
+ document.querySelector('.main').scrollTo({ top: 0, behavior: 'smooth' });
1597
+
1598
+ // Close mobile sidebar
1599
+ document.querySelector('.sidebar').classList.remove('open');
1600
+ }
1601
+
1602
+ function toggleEndpoint(card) {
1603
+ card.classList.toggle('open');
1604
+ }
1605
+
1606
+ function copyCode(btn) {
1607
+ const pre = btn.nextElementSibling;
1608
+ navigator.clipboard.writeText(pre.innerText.trim()).then(() => {
1609
+ btn.textContent = 'βœ“ copied';
1610
+ setTimeout(() => btn.textContent = 'copy', 2000);
1611
+ });
1612
+ }
1613
+
1614
+ function searchDocs(query) {
1615
+ if (!query.trim()) {
1616
+ document.querySelectorAll('.nav-item').forEach(n => n.style.display = '');
1617
+ return;
1618
+ }
1619
+ const q = query.toLowerCase();
1620
+ document.querySelectorAll('.nav-item').forEach(n => {
1621
+ const text = n.textContent.toLowerCase();
1622
+ n.style.display = text.includes(q) ? '' : 'none';
1623
+ });
1624
+ }
1625
+ </script>
1626
+ </body>
1627
+ </html>