Yashodeep2006 commited on
Commit
b748d21
·
verified ·
1 Parent(s): 6395928

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +7 -1543
README.md CHANGED
@@ -1,1543 +1,7 @@
1
- <div align="center">
2
-
3
- # 🚀 RAGForge
4
-
5
- ### Production-Ready AI Backend Framework built with FastAPI, LiteLLM and LangChain
6
-
7
- RAGForge is a modular AI backend framework that helps developers build production-ready AI applications with built-in Retrieval-Augmented Generation (RAG), intelligent caching, rate limiting, automatic LLM fallbacks, and administrative APIs.
8
-
9
- ---
10
-
11
- ![Python](https://img.shields.io/badge/Python-3.11-blue)
12
- ![FastAPI](https://img.shields.io/badge/FastAPI-Framework-green)
13
- ![LiteLLM](https://img.shields.io/badge/LiteLLM-Multi--LLM-orange)
14
- ![LangChain](https://img.shields.io/badge/LangChain-RAG-blueviolet)
15
- ![FAISS](https://img.shields.io/badge/FAISS-VectorDB-red)
16
- ![License](https://img.shields.io/badge/License-MIT-success)
17
-
18
- </div>
19
-
20
- ---
21
-
22
- # 📖 Overview
23
-
24
- RAGForge is an extensible AI backend framework designed for developers who want to build scalable AI applications without repeatedly implementing common backend infrastructure.
25
-
26
- Instead of writing the same boilerplate code for every chatbot, RAGForge provides a reusable architecture with built-in support for:
27
-
28
- - Retrieval-Augmented Generation (RAG)
29
- - Multiple LLM providers
30
- - Automatic provider fallbacks
31
- - Persistent response caching
32
- - User rate limiting
33
- - Modular AI engine architecture
34
- - Administrative APIs
35
- - Production-ready FastAPI backend
36
-
37
- The framework separates AI inference, retrieval, caching, user management, and administration into independent modules, making it easy to extend and maintain.
38
-
39
- ---
40
-
41
- # ✨ Features
42
-
43
- ## 🤖 AI
44
-
45
- - Retrieval-Augmented Generation (RAG)
46
- - LangChain integration
47
- - FAISS Vector Store
48
- - HuggingFace Embeddings
49
- - Configurable prompts
50
- - Modular RAG Engine
51
-
52
- ---
53
-
54
- ## 🌐 LLM Gateway
55
-
56
- - LiteLLM integration
57
- - Multi-provider support
58
- - Groq
59
- - OpenAI
60
- - Gemini
61
- - Ollama
62
- - Automatic provider fallbacks
63
-
64
- ---
65
-
66
- ## ⚡ Performance
67
-
68
- - Persistent DiskCache response caching
69
- - Cache hit detection
70
- - Cache miss detection
71
- - Fast repeated responses
72
- - Reduced API costs
73
-
74
- ---
75
-
76
- ## 🔒 Security
77
-
78
- - Per-user rate limiting
79
- - IP-based user identification
80
- - Daily request limits
81
- - Protected admin endpoints
82
- - Configurable admin key
83
-
84
- ---
85
-
86
- ## 📊 Administration
87
-
88
- - Active users
89
- - User statistics
90
- - Reset individual users
91
- - Reset all users
92
- - Cache management
93
- - Usage analytics
94
-
95
- ---
96
-
97
- ## ⚙️ Production Ready
98
-
99
- - Docker support
100
- - Hugging Face Spaces deployment
101
- - Configurable settings
102
- - Modular architecture
103
- - Easy extension
104
- - Clean project structure
105
-
106
- ---
107
-
108
- # 🎯 Why RAGForge?
109
-
110
- Many AI projects start with a simple chatbot.
111
-
112
- As the project grows, developers often add caching, rate limiting, retrieval, multiple LLM providers, logging, and administrative features directly into the application.
113
-
114
- Over time, the codebase becomes difficult to maintain because responsibilities become tightly coupled.
115
-
116
- RAGForge was designed to solve this problem.
117
-
118
- Instead of treating these features as part of the chatbot, RAGForge treats them as independent modules.
119
-
120
- ```
121
- Client
122
-
123
- ↓
124
-
125
- FastAPI
126
-
127
- ↓
128
-
129
- Rate Limiter
130
-
131
- ↓
132
-
133
- Response Cache
134
-
135
- ↓
136
-
137
- AI Engine
138
-
139
- ↓
140
-
141
- LLM Service
142
-
143
- ↓
144
-
145
- LiteLLM
146
-
147
- ↓
148
-
149
- LLM Provider
150
- ```
151
-
152
- Each component has exactly one responsibility.
153
-
154
- This makes the framework easier to understand, extend, and maintain.
155
-
156
- ---
157
-
158
- # 🏗 Architecture
159
-
160
- ```
161
- Client
162
-
163
- │
164
-
165
- ▼
166
-
167
- FastAPI API
168
-
169
- │
170
-
171
- ┌─────────────────┴─────────────────┐
172
-
173
- │ │
174
-
175
- User Manager Admin APIs
176
-
177
- │
178
-
179
- ▼
180
-
181
- Rate Limiter
182
-
183
- │
184
-
185
- ▼
186
-
187
- Response Cache
188
-
189
- │
190
-
191
- ▼
192
-
193
- RAG Engine
194
-
195
- │
196
-
197
- ▼
198
-
199
- Retrieval Chain
200
-
201
- │
202
-
203
- ▼
204
-
205
- Retriever
206
-
207
- │
208
-
209
- ▼
210
-
211
- FAISS Index
212
-
213
- │
214
-
215
- ▼
216
-
217
- Retrieved Docs
218
-
219
- │
220
-
221
- ▼
222
-
223
- Prompt Template
224
-
225
- │
226
-
227
- ▼
228
-
229
- LLM Service
230
-
231
- │
232
-
233
- ▼
234
-
235
- LiteLLM
236
-
237
- │
238
-
239
- ┌───────────┼─────────────┬────────────┐
240
-
241
- ▼ ▼ ▼ ▼
242
-
243
- Groq Gemini OpenAI Ollama
244
- ```
245
-
246
- ---
247
-
248
- # 🚀 Key Components
249
-
250
- RAGForge consists of several independent modules.
251
-
252
- | Module | Responsibility |
253
- | -------------- | ----------------------------- |
254
- | FastAPI | REST API |
255
- | User Manager | User tracking & rate limiting |
256
- | Response Cache | Persistent response caching |
257
- | RAG Engine | AI inference pipeline |
258
- | Retriever | Semantic document retrieval |
259
- | Prompt | System prompt construction |
260
- | LLM Service | LLM abstraction layer |
261
- | LiteLLM | Multi-provider gateway |
262
- | Admin APIs | User and cache management |
263
-
264
- Each component has a single responsibility, following clean architecture principles.
265
-
266
- ---
267
-
268
- # 📂 Project Structure
269
-
270
- ```text
271
- RAGForge/
272
-
273
- │
274
-
275
- ├── admin/
276
- │ ├── routes.py
277
- │
278
- ├── cache/
279
- │ ├── response_cache.py
280
- │ ├── repository.py
281
- │ ├── user_manager.py
282
- │
283
- ├── llm/
284
- │ ├── gateway.py
285
- │ ├── service.py
286
- │
287
- ├── models/
288
- │ ├── schemas.py
289
- │
290
- ├── rag/
291
- │ ├── data/
292
- │ │ └── data.txt
293
- │ │
294
- │ ├── faiss_index/
295
- │ │
296
- │ ├── embeddings.py
297
- │ ├── vectorstore.py
298
- │ ├── retriever.py
299
- │ ├── prompt.py
300
- │ ├── chain.py
301
- │ ├── engine.py
302
- │ ├── ingest.py
303
- │
304
- ├── app.py
305
- ├── config.py
306
- ├── Dockerfile
307
- ├── requirements.txt
308
- └── README.md
309
- ```
310
-
311
- ---
312
-
313
- # 🧩 Module Responsibilities
314
-
315
- ## app.py
316
-
317
- Entry point of the application.
318
-
319
- Responsible for:
320
-
321
- - FastAPI initialization
322
- - Request routing
323
- - Cache lookup
324
- - Rate limiting
325
- - AI engine execution
326
-
327
- ---
328
-
329
- ## admin/
330
-
331
- Contains all administrative endpoints.
332
-
333
- Examples:
334
-
335
- - View users
336
- - View statistics
337
- - Reset users
338
- - Clear cache
339
-
340
- ---
341
-
342
- ## cache/
343
-
344
- Responsible for all caching operations.
345
-
346
- Includes:
347
-
348
- - Response cache
349
- - User management
350
- - Repository abstraction
351
-
352
- ---
353
-
354
- ## llm/
355
-
356
- Responsible for communication with LLM providers.
357
-
358
- Includes:
359
-
360
- - LiteLLM integration
361
- - Provider configuration
362
- - LangChain model generation
363
-
364
- ---
365
-
366
- ## rag/
367
-
368
- Contains the complete Retrieval-Augmented Generation pipeline.
369
-
370
- Includes:
371
-
372
- - Document ingestion
373
- - Embeddings
374
- - FAISS
375
- - Retriever
376
- - Prompt
377
- - Chain
378
- - Engine
379
-
380
- # ⚙️ Request Lifecycle
381
-
382
- The following diagram illustrates the complete lifecycle of a user request.
383
-
384
- ```
385
- User
386
-
387
- │
388
-
389
- ▼
390
-
391
- POST /chat Request
392
-
393
- │
394
-
395
- ▼
396
-
397
- Extract Client IP
398
-
399
- │
400
-
401
- ▼
402
-
403
- Register User Request
404
-
405
- │
406
-
407
- ▼
408
-
409
- Response Cache Lookup
410
-
411
- ┌──────────┴──────────┐
412
-
413
- │ │
414
-
415
- Cache Hit Cache Miss
416
-
417
- │ │
418
-
419
- ▼ ▼
420
-
421
- Return Cached Rate Limiter
422
-
423
- Response │
424
-
425
- ▼
426
-
427
- Request Allowed?
428
-
429
- ┌────────┴────────┐
430
-
431
- │ │
432
-
433
- No Yes
434
-
435
- │ │
436
-
437
- ▼ ▼
438
-
439
- HTTP 429 Error RAG Engine
440
-
441
- │
442
-
443
- ▼
444
-
445
- Retriever
446
-
447
- │
448
-
449
- ▼
450
-
451
- FAISS Index
452
-
453
- │
454
-
455
- ▼
456
-
457
- Retrieved Context
458
-
459
- │
460
-
461
- ▼
462
-
463
- Prompt Template
464
-
465
- │
466
-
467
- ▼
468
-
469
- LLM Service
470
-
471
- │
472
-
473
- ▼
474
-
475
- LiteLLM
476
-
477
- │
478
-
479
- ┌───────────────┬───────────────┬───────────────┐
480
-
481
- ▼ ▼ �� ▼
482
-
483
- Groq Gemini OpenAI Ollama
484
-
485
- │
486
-
487
- ▼
488
-
489
- Generated Response
490
-
491
- │
492
-
493
- ▼
494
-
495
- Save Response Cache
496
-
497
- │
498
-
499
- ▼
500
-
501
- Return Final Answer
502
- ```
503
-
504
- Every request follows the same lifecycle, ensuring that caching, rate limiting, retrieval, and AI inference are consistently applied.
505
-
506
- ---
507
-
508
- # 🧠 Retrieval-Augmented Generation (RAG)
509
-
510
- RAGForge uses a Retrieval-Augmented Generation (RAG) pipeline.
511
-
512
- Unlike a traditional chatbot, the model does not rely solely on its pre-trained knowledge.
513
-
514
- Instead, it retrieves relevant information from a vector database before generating an answer.
515
-
516
- ```
517
- User Question
518
-
519
- ↓
520
-
521
- Retriever
522
-
523
- ↓
524
-
525
- Semantic Search
526
-
527
- ↓
528
-
529
- FAISS
530
-
531
- ↓
532
-
533
- Relevant Chunks
534
-
535
- ↓
536
-
537
- Prompt
538
-
539
- ↓
540
-
541
- LLM
542
-
543
- ↓
544
-
545
- Final Answer
546
- ```
547
-
548
- This ensures that answers remain grounded in the supplied knowledge base.
549
-
550
- ---
551
-
552
- # 📚 Document Ingestion Pipeline
553
-
554
- RAGForge separates **offline indexing** from **online inference**.
555
-
556
- Instead of building embeddings during application startup, RAGForge provides an independent ingestion pipeline.
557
-
558
- ```
559
- python rag/ingest.py
560
-
561
- ↓
562
-
563
- Load Documents
564
-
565
- ↓
566
-
567
- Split Documents
568
-
569
- ↓
570
-
571
- Generate Embeddings
572
-
573
- ↓
574
-
575
- Create FAISS Index
576
-
577
- ↓
578
-
579
- Save Index
580
-
581
- ↓
582
-
583
- Done
584
- ```
585
-
586
- After the index is created, the application only loads the existing FAISS database.
587
-
588
- This significantly reduces startup time and follows production RAG architecture.
589
-
590
- ---
591
-
592
- # ✂️ Text Splitting
593
-
594
- Large documents are divided into smaller chunks before embedding.
595
-
596
- ```
597
- Document
598
-
599
- ↓
600
-
601
- Chunk 1
602
-
603
- Chunk 2
604
-
605
- Chunk 3
606
-
607
- Chunk 4
608
- ```
609
-
610
- Configuration
611
-
612
- ```python
613
- CHUNK_SIZE = 500
614
-
615
- CHUNK_OVERLAP = 100
616
- ```
617
-
618
- Overlapping chunks preserve context across document boundaries and improve retrieval quality.
619
-
620
- ---
621
-
622
- # 🔎 Semantic Retrieval
623
-
624
- RAGForge performs semantic retrieval using FAISS.
625
-
626
- The retriever uses **Maximum Marginal Relevance (MMR)** to balance relevance and diversity.
627
-
628
- Configuration
629
-
630
- ```python
631
- SEARCH_TYPE = "mmr"
632
-
633
- TOP_K = 3
634
-
635
- FETCH_K = 5
636
-
637
- LAMBDA_MULT = 0.5
638
- ```
639
-
640
- Workflow
641
-
642
- ```
643
- Question
644
-
645
- ↓
646
-
647
- FAISS
648
-
649
- ↓
650
-
651
- 5 Candidate Chunks
652
-
653
- ↓
654
-
655
- MMR
656
-
657
- ↓
658
-
659
- Best 3 Chunks
660
-
661
- ↓
662
-
663
- LLM
664
- ```
665
-
666
- This reduces redundant context while improving answer quality.
667
-
668
- ---
669
-
670
- # 🧠 Embedding Model
671
-
672
- AIForge converts text into dense vector representations using HuggingFace embeddings.
673
-
674
- Current embedding model
675
-
676
- ```
677
- sentence-transformers/all-MiniLM-L6-v2
678
- ```
679
-
680
- The embedding model is centralized inside
681
-
682
- ```
683
- rag/embeddings.py
684
- ```
685
-
686
- making it easy to replace with stronger models in the future.
687
-
688
- ---
689
-
690
- # 🗄 Vector Store
691
-
692
- FAISS is used as the vector database.
693
-
694
- Responsibilities include:
695
-
696
- - Storing document embeddings
697
- - Performing similarity search
698
- - Returning relevant document chunks
699
-
700
- Unlike many RAG implementations, AIForge never rebuilds the vector store during runtime.
701
-
702
- The vector store is created once using
703
-
704
- ```
705
- python rag/ingest.py
706
- ```
707
-
708
- and loaded by the application when it starts.
709
-
710
- ---
711
-
712
- # 📝 Prompt Construction
713
-
714
- The retrieved document chunks are injected into a system prompt before being sent to the LLM.
715
-
716
- ```
717
- Question
718
-
719
- ↓
720
-
721
- Retrieved Context
722
-
723
- ↓
724
-
725
- Prompt Template
726
-
727
- ↓
728
-
729
- LLM
730
- ```
731
-
732
- Prompt construction is isolated in
733
-
734
- ```
735
- rag/prompt.py
736
- ```
737
-
738
- allowing prompts to evolve independently of the retrieval logic.
739
-
740
- ---
741
-
742
- # 🔗 Retrieval Chain
743
-
744
- AIForge uses LangChain's Retrieval Chain.
745
-
746
- The chain combines:
747
-
748
- - Retriever
749
- - Prompt
750
- - LLM
751
-
752
- into a single inference pipeline.
753
-
754
- ```
755
- Retriever
756
-
757
- ↓
758
-
759
- Relevant Documents
760
-
761
- ↓
762
-
763
- Stuff Documents Chain
764
-
765
- ↓
766
-
767
- Prompt
768
-
769
- ↓
770
-
771
- LLM
772
-
773
- ↓
774
-
775
- Answer
776
- ```
777
-
778
- The chain itself is defined inside
779
-
780
- ```
781
- rag/chain.py
782
- ```
783
-
784
- which acts as the composition layer for the RAG pipeline.
785
-
786
- ---
787
-
788
- # 🤖 RAG Engine
789
-
790
- The RAG Engine provides a simple interface to the rest of the framework.
791
-
792
- ```
793
- app.py
794
-
795
- ↓
796
-
797
- RAGEngine.chat(prompt)
798
-
799
- ↓
800
-
801
- Answer
802
- ```
803
-
804
- The FastAPI application does not interact with LangChain directly.
805
-
806
- Instead, it communicates exclusively with the RAG Engine.
807
-
808
- This abstraction makes it possible to replace the underlying AI implementation without changing the REST API.
809
-
810
- ---
811
-
812
- # 🌉 LLM Service
813
-
814
- The LLM Service is the central abstraction layer for AI providers.
815
-
816
- Responsibilities include:
817
-
818
- - Loading model configuration
819
- - Managing temperature
820
- - Managing timeout
821
- - Managing retries
822
- - Creating LangChain-compatible chat models
823
- - Providing a unified interface to LiteLLM
824
-
825
- Instead of allowing different parts of the framework to instantiate providers independently, every AI component communicates through the LLM Service.
826
-
827
- This eliminates duplicated configuration and keeps provider management centralized.
828
-
829
- ---
830
-
831
- # 🔀 LiteLLM Integration
832
-
833
- LiteLLM acts as a universal gateway to multiple providers.
834
-
835
- ```
836
- LLM Service
837
-
838
- ↓
839
-
840
- LiteLLM
841
-
842
- ↓
843
-
844
- Groq
845
-
846
- Gemini
847
-
848
- OpenAI
849
-
850
- Ollama
851
- ```
852
-
853
- Changing the provider requires only a configuration update.
854
-
855
- The rest of the application remains unchanged.
856
-
857
- ---
858
-
859
- # 🔄 Automatic Fallbacks
860
-
861
- If the primary provider becomes unavailable, LiteLLM automatically routes requests to fallback providers.
862
-
863
- ```
864
- Request
865
-
866
- ↓
867
-
868
- Groq
869
-
870
- ↓
871
-
872
- Success?
873
-
874
- ├── Yes → Return Response
875
-
876
- └── No
877
-
878
- ↓
879
-
880
- Gemini
881
-
882
- ↓
883
-
884
- Success?
885
-
886
- ├── Yes → Return Response
887
-
888
- └── No
889
-
890
- ↓
891
-
892
- OpenAI
893
-
894
- ↓
895
-
896
- Return Response
897
- ```
898
-
899
- This significantly improves application availability without requiring changes to application code.
900
-
901
- ---
902
-
903
- # 🧩 AI Engine Abstraction
904
-
905
- The FastAPI application interacts only with the AI Engine.
906
-
907
- ```
908
- FastAPI
909
-
910
- ↓
911
-
912
- AI Engine
913
-
914
- ↓
915
-
916
- RAG Engine
917
-
918
- ↓
919
-
920
- LLM Service
921
-
922
- ↓
923
-
924
- LiteLLM
925
- ```
926
-
927
- Because the engine is abstracted, future implementations such as AI Agents or alternative retrieval systems can be introduced without changing the REST API.
928
-
929
- ---
930
-
931
- # 🚀 Why This Architecture?
932
-
933
- AIForge follows the **Single Responsibility Principle (SRP)**.
934
-
935
- Each module performs one task only.
936
-
937
- | Module | Responsibility |
938
- | ---------------- | --------------------------- |
939
- | `embeddings.py` | Load embedding model |
940
- | `vectorstore.py` | Manage FAISS index |
941
- | `retriever.py` | Retrieve relevant documents |
942
- | `prompt.py` | Build prompt template |
943
- | `chain.py` | Compose retrieval chain |
944
- | `engine.py` | Execute RAG pipeline |
945
- | `service.py` | Manage LLM configuration |
946
- | `app.py` | Handle HTTP requests |
947
-
948
- This separation improves maintainability, readability, testing, and scalability.
949
-
950
- ---
951
-
952
- # 🏭 Production Design Principles
953
-
954
- AIForge follows several software engineering best practices.
955
-
956
- - Separation of concerns
957
- - Modular architecture
958
- - Configuration-driven design
959
- - Offline document ingestion
960
- - Centralized LLM management
961
- - Reusable AI engine
962
- - Independent caching layer
963
- - Independent user management
964
- - Provider abstraction
965
-
966
- These principles allow the framework to evolve while minimizing changes to existing components.
967
-
968
- # 🚀 Installation
969
-
970
- ## Prerequisites
971
-
972
- Before running AIForge, ensure you have the following installed:
973
-
974
- - Python 3.11+
975
- - Git
976
- - pip
977
- - Virtual Environment (recommended)
978
-
979
- ---
980
-
981
- # Clone Repository
982
-
983
- ```bash
984
- git clone https://github.com/codewithyasho/AIForge.git
985
-
986
- cd AIForge
987
- ```
988
-
989
- ---
990
-
991
- # Create Virtual Environment
992
-
993
- ### Windows
994
-
995
- ```bash
996
- python -m venv .venv
997
-
998
- .venv\Scripts\activate
999
- ```
1000
-
1001
- ### Linux / macOS
1002
-
1003
- ```bash
1004
- python3 -m venv .venv
1005
-
1006
- source .venv/bin/activate
1007
- ```
1008
-
1009
- ---
1010
-
1011
- # Install Dependencies
1012
-
1013
- ```bash
1014
- pip install -r requirements.txt
1015
- ```
1016
-
1017
- ---
1018
-
1019
- # Environment Variables
1020
-
1021
- Create a `.env` file in the project root.
1022
-
1023
- Example
1024
-
1025
- ```env
1026
- ###########################################################
1027
- # API Keys
1028
- ###########################################################
1029
-
1030
- GROQ_API_KEY=your_groq_key
1031
-
1032
- GOOGLE_API_KEY=your_google_key
1033
-
1034
- OPENAI_API_KEY=your_openai_key
1035
-
1036
- ###########################################################
1037
- # Admin
1038
- ###########################################################
1039
-
1040
- ADMIN_KEY=yashodeep
1041
- ```
1042
-
1043
- Only include providers that you intend to use.
1044
-
1045
- ---
1046
-
1047
- # Configuration
1048
-
1049
- All project settings are centralized in
1050
-
1051
- ```
1052
- config.py
1053
- ```
1054
-
1055
- Example
1056
-
1057
- ```python
1058
- # -------------------------
1059
- # RAG
1060
- # -------------------------
1061
-
1062
- DATA_PATH = "rag/data/data.txt"
1063
-
1064
- FAISS_PATH = "rag/faiss_index"
1065
-
1066
- EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
1067
-
1068
- CHUNK_SIZE = 500
1069
-
1070
- CHUNK_OVERLAP = 100
1071
-
1072
- TOP_K = 3
1073
-
1074
- FETCH_K = 5
1075
-
1076
- LAMBDA_MULT = 0.5
1077
-
1078
-
1079
- # -------------------------
1080
- # LiteLLM
1081
- # -------------------------
1082
-
1083
- PRIMARY_MODEL = "groq/openai/gpt-oss-120b"
1084
-
1085
- FALLBACK_MODELS = [
1086
-
1087
- "gemini/gemini-2.5-flash",
1088
-
1089
- "openai/gpt-4.1-mini"
1090
-
1091
- ]
1092
-
1093
- TEMPERATURE = 0.2
1094
-
1095
- TIMEOUT = 30
1096
- ```
1097
-
1098
- Every major setting can be modified without changing application code.
1099
-
1100
- ---
1101
-
1102
- # Building the Knowledge Base
1103
-
1104
- AIForge separates indexing from serving.
1105
-
1106
- Whenever the knowledge base changes:
1107
-
1108
- ```bash
1109
- python rag/ingest.py
1110
- ```
1111
-
1112
- Expected Output
1113
-
1114
- ```
1115
- Loading documents...
1116
-
1117
- Splitting documents...
1118
-
1119
- Loading embedding model...
1120
-
1121
- Creating FAISS...
1122
-
1123
- Saving FAISS...
1124
-
1125
- AIForge ingestion completed successfully.
1126
- ```
1127
-
1128
- The FAISS index only needs to be regenerated when the source documents change.
1129
-
1130
- ---
1131
-
1132
- # Running AIForge
1133
-
1134
- Development
1135
-
1136
- ```bash
1137
- uvicorn app:app --reload
1138
- ```
1139
-
1140
- Production
1141
-
1142
- ```bash
1143
- uvicorn app:app --host 0.0.0.0 --port 8000
1144
- ```
1145
-
1146
- The API will be available at
1147
-
1148
- ```
1149
- http://127.0.0.1:8000
1150
- ```
1151
-
1152
- Swagger Documentation
1153
-
1154
- ```
1155
- http://127.0.0.1:8000/docs
1156
- ```
1157
-
1158
- ReDoc
1159
-
1160
- ```
1161
- http://127.0.0.1:8000/redoc
1162
- ```
1163
-
1164
- ---
1165
-
1166
- # API Reference
1167
-
1168
- ---
1169
-
1170
- ## GET /
1171
-
1172
- Returns API status.
1173
-
1174
- Response
1175
-
1176
- ```json
1177
- {
1178
- "message": "🚀 AIForge Running Successfully"
1179
- }
1180
- ```
1181
-
1182
- ---
1183
-
1184
- ## POST /chat
1185
-
1186
- Generate an AI response.
1187
-
1188
- Request
1189
-
1190
- ```json
1191
- {
1192
- "prompt": "Who is Yashodeep?"
1193
- }
1194
- ```
1195
-
1196
- Example Response
1197
-
1198
- ```json
1199
- {
1200
- "success": true,
1201
- "cached": false,
1202
- "provider": "groq",
1203
- "remaining_questions": 9,
1204
- "answer": "Yashodeep Hundiwale is..."
1205
- }
1206
- ```
1207
-
1208
- ---
1209
-
1210
- ## Admin Endpoints
1211
-
1212
- All administrative endpoints require the following header.
1213
-
1214
- ```
1215
- X-Admin-Key: yashodeep
1216
- ```
1217
-
1218
- ---
1219
-
1220
- ### GET /admin/
1221
-
1222
- API status
1223
-
1224
- ---
1225
-
1226
- ### GET /admin/users
1227
-
1228
- Returns all active users.
1229
-
1230
- ---
1231
-
1232
- ### GET /admin/user/{user_id}
1233
-
1234
- Returns information about a specific user.
1235
-
1236
- ---
1237
-
1238
- ### GET /admin/stats
1239
-
1240
- Returns overall application statistics.
1241
-
1242
- ---
1243
-
1244
- ### GET /admin/cache
1245
-
1246
- Returns cache information.
1247
-
1248
- ---
1249
-
1250
- ### GET /admin/top-users
1251
-
1252
- Returns users ordered by request count.
1253
-
1254
- ---
1255
-
1256
- ### GET /admin/active-users
1257
-
1258
- Returns recently active users.
1259
-
1260
- ---
1261
-
1262
- ### DELETE /admin/user/{user_id}
1263
-
1264
- Reset one user.
1265
-
1266
- ---
1267
-
1268
- ### DELETE /admin/users
1269
-
1270
- Reset every user.
1271
-
1272
- ---
1273
-
1274
- ### DELETE /admin/cache
1275
-
1276
- Clear response cache.
1277
-
1278
- ---
1279
-
1280
- ### DELETE /admin/reset
1281
-
1282
- Reset both users and cache.
1283
-
1284
- ---
1285
-
1286
- # Docker
1287
-
1288
- Build Image
1289
-
1290
- ```bash
1291
- docker build -t aiforge .
1292
- ```
1293
-
1294
- Run Container
1295
-
1296
- ```bash
1297
- docker run -p 7860:7860 aiforge
1298
- ```
1299
-
1300
- AIForge automatically starts using
1301
-
1302
- ```
1303
- uvicorn
1304
- ```
1305
-
1306
- inside the container.
1307
-
1308
- ---
1309
-
1310
- # Deploying to Hugging Face Spaces
1311
-
1312
- AIForge includes a Dockerfile compatible with Hugging Face Docker Spaces.
1313
-
1314
- Deployment steps:
1315
-
1316
- 1. Create a Docker Space.
1317
- 2. Push the repository.
1318
- 3. Add repository secrets:
1319
-
1320
- ```
1321
- ADMIN_KEY
1322
-
1323
- GROQ_API_KEY
1324
-
1325
- GOOGLE_API_KEY
1326
-
1327
- OPENAI_API_KEY
1328
- ```
1329
-
1330
- 4. Hugging Face automatically builds the image.
1331
- 5. AIForge becomes publicly accessible.
1332
-
1333
- No code changes are required.
1334
-
1335
- ---
1336
-
1337
- # Performance
1338
-
1339
- AIForge improves response latency through persistent caching.
1340
-
1341
- Example
1342
-
1343
- First Request
1344
-
1345
- ```
1346
- User
1347
-
1348
- ↓
1349
-
1350
- LLM
1351
-
1352
- ↓
1353
-
1354
- ~2 seconds
1355
- ```
1356
-
1357
- Repeated Request
1358
-
1359
- ```
1360
- User
1361
-
1362
- ↓
1363
-
1364
- DiskCache
1365
-
1366
- ↓
1367
-
1368
- <50 ms
1369
- ```
1370
-
1371
- Benefits
1372
-
1373
- - Lower latency
1374
- - Reduced API cost
1375
- - Reduced provider usage
1376
- - Improved user experience
1377
-
1378
- ---
1379
-
1380
- # Tech Stack
1381
-
1382
- | Category | Technology |
1383
- | ------------ | ------------------- |
1384
- | Backend | FastAPI |
1385
- | AI Gateway | LiteLLM |
1386
- | RAG | LangChain |
1387
- | Vector Store | FAISS |
1388
- | Embeddings | HuggingFace |
1389
- | Cache | DiskCache |
1390
- | Validation | Pydantic |
1391
- | API | REST |
1392
- | Language | Python |
1393
- | Deployment | Docker |
1394
- | Hosting | Hugging Face Spaces |
1395
-
1396
- ---
1397
-
1398
- # Current Features
1399
-
1400
- - FastAPI Backend
1401
- - LiteLLM Gateway
1402
- - Retrieval-Augmented Generation
1403
- - HuggingFace Embeddings
1404
- - FAISS Vector Database
1405
- - MMR Retrieval
1406
- - Prompt Templates
1407
- - Automatic Fallbacks
1408
- - Persistent Response Cache
1409
- - User Manager
1410
- - Rate Limiting
1411
- - Admin APIs
1412
- - Docker Deployment
1413
- - Hugging Face Spaces Support
1414
- - Modular Architecture
1415
-
1416
- ---
1417
-
1418
- # Roadmap
1419
-
1420
- ## Version 1.0
1421
-
1422
- - FastAPI
1423
- - LiteLLM
1424
- - RAG
1425
- - FAISS
1426
- - DiskCache
1427
- - Rate Limiting
1428
- - Admin APIs
1429
-
1430
- ---
1431
-
1432
- ## Version 1.1
1433
-
1434
- - Structured Logging
1435
- - Health Endpoint
1436
- - Better Exception Handling
1437
- - Configuration Validation
1438
-
1439
- ---
1440
-
1441
- ## Version 1.2
1442
-
1443
- - Streaming Responses
1444
- - Conversation Memory
1445
- - Multiple Knowledge Bases
1446
- - Configurable AI Engines
1447
-
1448
- ---
1449
-
1450
- ## Version 2.0
1451
-
1452
- - AI Agents
1453
- - LangGraph Integration
1454
- - MCP Support
1455
- - Authentication
1456
- - Dashboard
1457
- - Monitoring
1458
- - PostgreSQL Support
1459
- - Redis Support
1460
- - Kubernetes Deployment
1461
-
1462
- ---
1463
-
1464
- # Contributing
1465
-
1466
- Contributions are welcome.
1467
-
1468
- If you would like to contribute:
1469
-
1470
- 1. Fork the repository.
1471
-
1472
- 2. Create a new feature branch.
1473
-
1474
- 3. Commit your changes.
1475
-
1476
- 4. Push the branch.
1477
-
1478
- 5. Open a Pull Request.
1479
-
1480
- Please ensure new code follows the existing project architecture.
1481
-
1482
- ---
1483
-
1484
- # License
1485
-
1486
- This project is licensed under the MIT License.
1487
-
1488
- You are free to use, modify, and distribute AIForge.
1489
-
1490
- ---
1491
-
1492
- # Author
1493
-
1494
- ## Yashodeep Hundiwale
1495
-
1496
- AI Engineer • Data Scientist • Backend Developer
1497
-
1498
- Portfolio
1499
-
1500
- https://yashodeep.me
1501
-
1502
- GitHub
1503
-
1504
- https://github.com/codewithyasho
1505
-
1506
- ---
1507
-
1508
- # Acknowledgements
1509
-
1510
- AIForge is built on top of several outstanding open-source projects.
1511
-
1512
- Special thanks to:
1513
-
1514
- - FastAPI
1515
- - LiteLLM
1516
- - LangChain
1517
- - HuggingFace
1518
- - FAISS
1519
- - DiskCache
1520
- - Uvicorn
1521
- - Pydantic
1522
-
1523
- Without these projects, AIForge would not have been possible.
1524
-
1525
- ---
1526
-
1527
- # ⭐ Support
1528
-
1529
- If RAGForge helped you, please consider giving the repository a ⭐.
1530
-
1531
- It helps others discover the project and encourages future development.
1532
-
1533
- ---
1534
-
1535
- # Final Thoughts
1536
-
1537
- RAGForge was created to provide a clean, reusable, and production-oriented backend architecture for AI applications.
1538
-
1539
- Instead of tightly coupling retrieval, caching, user management, and model providers into a single application, RAGForge separates every responsibility into independent modules.
1540
-
1541
- This architecture allows developers to build scalable AI systems while keeping the codebase modular, maintainable, and easy to extend.
1542
-
1543
- Whether you are building a portfolio chatbot, a document assistant, a customer support bot, or a domain-specific RAG application, RAGForge provides a strong foundation that can evolve with your project.
 
1
+ ---
2
+ title: RAGFORGE
3
+ sdk: docker
4
+ emoji: 🚀
5
+ colorFrom: pink
6
+ colorTo: green
7
+ ---