Plant UML docs

README.md

@@ -46,6 +46,6 @@ Check out the configuration reference at https://huggingface.co/docs/hub/spaces-
 ├── .env                             # Environment variables for configuration settings**
 ├── ipynb/                           # Jupyter notebooks used for fine-tuning / transfer learning model
 │   ├── facenet/                     # Jupyter Notebooks for Facenet / MTCNN test
-│   ├── llm/                         # Jupyter Notebooks for LLM training / validation
+│   └── llm/                         # Jupyter Notebooks for LLM training / validation
 └── docs/                            # Project Documents (ONLY MARKDOWNs and UML diagrams)
 ```

docs/EduConnect_class.puml

@@ -0,0 +1,38 @@
+@startuml EduConnect
+class FastAPIApp {
+}
+
+class User {
+}
+
+class Authentication {
+}
+
+class JWTToken {
+}
+
+class TinyDB {
+}
+
+class FileHandler {
+}
+
+class ChatHandler {
+}
+
+class DocumentIngestor {
+}
+
+class FaceVerifier {
+}
+
+FastAPIApp --> User : manages
+FastAPIApp --> Authentication : uses
+Authentication --> JWTToken : generates/validates
+User --> TinyDB : stores/retrieves data
+FastAPIApp --> FileHandler : uploads/downloads files
+FastAPIApp --> ChatHandler : sends/receives messages
+FastAPIApp --> DocumentIngestor : processes documents
+FastAPIApp --> FaceVerifier : verifies user face
+
+@enduml

docs/EduConnect_seq.puml

@@ -0,0 +1,30 @@
+@startuml EduConnect
+actor User
+participant "FastAPIApp" as app
+participant "Authentication" as auth
+database "TinyDB" as db
+participant "FileHandler" as fileHandler
+participant "ChatHandler" as chat
+participant "DocumentIngestor" as docIngestor
+
+== User Login ==
+User -> app : login()
+app -> auth : authenticate()
+auth -> db : verifyUser()
+db --> auth : userValidated
+auth --> app : token
+app --> User : token
+
+== Chat Message ==
+User -> app : sendMessage()
+app -> chat : processMessage()
+chat --> User : response
+
+== Upload Document ==
+User -> app : uploadDocument()
+app -> fileHandler : saveFile()
+fileHandler -> docIngestor : processDocument()
+docIngestor --> fileHandler : docProcessed
+fileHandler --> User : uploadSuccess
+
+@enduml

docs/api/userchat_class.puml

@@ -0,0 +1,20 @@
+@startuml userchat
+class APIRouter {
+}
+
+class LLMInfer {
+    +llm_infer(user_collection_name: str, prompt: str): str
+}
+
+class SanitizeCollectionName {
+    +sanitize_collection_name(name: str): str
+}
+
+class Dependencies {
+    +get_current_user(): dict
+}
+
+APIRouter ..> LLMInfer : uses
+APIRouter ..> SanitizeCollectionName : uses
+APIRouter ..> Dependencies : uses
+@enduml

docs/api/userchat_seq.puml

@@ -0,0 +1,28 @@
+@startuml userchat
+actor User
+participant "APIRouter" as router
+participant "Dependencies" as dependencies
+participant "SanitizeCollectionName" as sanitizer
+participant "LLMInfer" as llm
+
+User -> router : chat_with_llama(user_input)
+activate router
+
+router -> dependencies : get_current_user()
+activate dependencies
+dependencies --> router : current_user
+deactivate dependencies
+
+router -> sanitizer : sanitize_collection_name(current_user["user_id"])
+activate sanitizer
+sanitizer --> router : sanitized_name
+deactivate sanitizer
+
+router -> llm : llm_infer(sanitized_name, user_input)
+activate llm
+llm --> router : model_response
+deactivate llm
+
+router --> User : {"ai_response": model_response, "user_id", "name", "role"}
+deactivate router
+@enduml

docs/api/userlogin_class.puml

@@ -0,0 +1,21 @@
+@startuml userlogin
+class UserLogin {
+    +user_login(file: UploadFile): dict
+}
+
+class FaceVerification {
+    +verify_user_face(file_path: str): Optional[dict]
+}
+
+class JWTToken {
+    +create_access_token(data: dict, expires_delta: Optional[timedelta]): string
+}
+
+class TinyDBHelper {
+    +insert_token(user_id: string, token: string, expires_at: string): void
+}
+
+UserLogin ..> FaceVerification : uses
+FaceVerification ..> JWTToken : uses
+JWTToken ..> TinyDBHelper : uses
+@enduml

docs/api/userlogin_seq.puml

@@ -0,0 +1,28 @@
+@startuml userlogin
+actor Client
+participant "UserLogin" as login
+participant "FaceVerification" as verification
+participant "JWTToken" as jwt
+database "TinyDB" as db
+
+Client -> login : user_login(file)
+activate login
+
+login -> verification : verify_user_face(file_path)
+activate verification
+verification --> login : verification_result
+deactivate verification
+
+login -> jwt : create_access_token(user_id, metadata)
+activate jwt
+jwt --> login : access_token
+deactivate jwt
+
+login -> db : insert_token(user_id, access_token, expires_at)
+activate db
+db --> login
+deactivate db
+
+login --> Client : {access_token, user_id, name, role}
+deactivate login
+@enduml

docs/api/userlogout_class.puml

@@ -0,0 +1,15 @@
+@startuml userlogout
+class APIRouter {
+}
+
+class TinyDBHelper {
+    +query_token(user_id: string, token: string): bool
+    +remove_token_by_value(token: string): void
+}
+
+class OAuth2Scheme {
+}
+
+APIRouter ..> TinyDBHelper : uses
+APIRouter ..> OAuth2Scheme : depends on
+@enduml

docs/api/userlogout_seq.puml

@@ -0,0 +1,29 @@
+@startuml userlogout
+actor Client
+participant "APIRouter" as router
+participant "OAuth2Scheme" as oauth2
+participant "TinyDBHelper" as db
+
+Client -> router : user_logout(token)
+activate router
+
+router -> oauth2 : get token from request
+activate oauth2
+oauth2 --> router : token
+deactivate oauth2
+
+router -> db : query_token(user_id, token)
+activate db
+alt if token exists
+    db --> router : true
+    router -> db : remove_token_by_value(token)
+    db -> router : token removed
+else
+    db --> router : false
+    router --> Client : {"detail": "Token not found."}
+end
+deactivate db
+
+router --> Client : {"message": "User logged out successfully"}
+deactivate router
+@enduml

docs/api/userupload_class.puml

@@ -0,0 +1,23 @@
+@startuml userupload
+class APIRouter {
+}
+
+class UploadFile {
+}
+
+class FileDependencies {
+}
+
+class DocumentIngestor {
+    +ingest_document(file_location: str, collection_name: str): void
+}
+
+class Sanitizer {
+    +sanitize_collection_name(name: str): str
+}
+
+APIRouter ..> UploadFile : receives
+APIRouter ..> FileDependencies : uses
+UploadFile ..> DocumentIngestor : processed by
+APIRouter ..> Sanitizer : uses
+@enduml

docs/api/userupload_seq.puml

@@ -0,0 +1,33 @@
+@startuml userupload
+actor Client
+participant "APIRouter" as router
+participant "UploadFile" as file
+participant "Sanitizer" as sanitizer
+participant "DocumentIngestor" as ingestor
+
+Client -> router : upload_file(file)
+activate router
+
+router -> file : check_content_type()
+activate file
+file --> router : valid/invalid
+deactivate file
+
+alt if file is valid
+    router -> sanitizer : sanitize_collection_name(current_user["user_id"])
+    activate sanitizer
+    sanitizer --> router : sanitized_name
+    deactivate sanitizer
+    
+    router -> ingestor : ingest_document(file_location, sanitized_name)
+    activate ingestor
+    ingestor --> router : success/failure
+    deactivate ingestor
+    
+    router --> Client : {"status": "File uploaded and processed successfully."}
+else if file is invalid
+    router --> Client : {"status": "Unsupported file type."}
+end
+
+deactivate router
+@enduml

docs/dependencies_class.puml

@@ -0,0 +1,23 @@
+@startuml dependencies
+class OAuth2PasswordBearer {
+}
+
+class JWTError {
+}
+
+class HTTPException {
+}
+
+class TinyDBHelper {
+    +query_token(user_id: string, token: string): bool
+}
+
+class Dependencies {
+    +get_current_user(token: str): dict
+}
+
+OAuth2PasswordBearer ..> Dependencies : token
+Dependencies ..> JWTError : catch errors
+Dependencies ..> HTTPException : throw on failure
+Dependencies ..> TinyDBHelper : validate token
+@enduml

docs/dependencies_seq.puml

@@ -0,0 +1,37 @@
+@startuml dependencies
+actor Client
+participant "OAuth2PasswordBearer" as oauth2
+participant "Dependencies" as dependencies
+participant "JWTError" as jwtError
+participant "HTTPException" as httpException
+database "TinyDBHelper" as db
+
+Client -> dependencies : get_current_user(token)
+activate dependencies
+
+dependencies -> oauth2 : token
+oauth2 --> dependencies : token
+dependencies -> dependencies : decode_jwt(token)
+activate dependencies
+alt success
+    dependencies --> dependencies : payload
+else JWTError
+    dependencies -> jwtError : raise credentials_exception
+    jwtError --> dependencies : HTTP_401_UNAUTHORIZED
+end
+deactivate dependencies
+
+dependencies -> db : query_token(user_id, token)
+activate db
+alt token valid
+    db --> dependencies : true
+else token invalid
+    db --> dependencies : false
+    dependencies -> httpException : raise expiry_exception
+    httpException --> dependencies : HTTP_401_UNAUTHORIZED
+end
+deactivate db
+
+dependencies --> Client : user_details
+deactivate dependencies
+@enduml

docs/design_principles.md

@@ -1,101 +0,0 @@
-# DESIGN PRINCIPLES
-
-## VectorDB collections
-
-Given that our EduConnect project is an academic project with a scale limited to not more than 10 users, the approach of creating separate vector stores (ChromaDB collections) for each user becomes highly feasible and manageable. This small scale alleviates concerns about scalability and management overhead that would be significant in a larger, production-level system. Here's how we can effectively implement and manage user-specific vector stores under these conditions:
-
-### Implementation Strategy for Small Scale
-
-1. **Simplified Database Management**: With a maximum of 10 users, managing separate ChromaDB collections becomes straightforward. we can manually monitor and maintain these collections without the need for automated scalability solutions.
-
-2. **Personalized Data Handling**: This setup allows for a high degree of personalization in data handling and retrieval. Each user's interactions and uploads can be contained within their dedicated collection, ensuring data isolation and relevance.
-
-3. **Performance Considerations**: Performance issues related to managing multiple collections are negligible at this scale. Each user's collection will be relatively small, ensuring quick access and query times.
-
-4. **Security and Privacy**: Maintaining separate collections for each user naturally enhances data privacy, as there is a clear separation of data at the database level.
-
-### Example Adjustments
-
-Given the small scale of our project, we might not need to implement complex dynamic collection management. Instead, we can hard-code the logic to create or select a collection based on the user ID. Here is a simplified example adjustment to our document ingestion logic:
-
-```python
-# utils/doc_ingest.py
-def ingest_document(file_location: str, user_id: str):
-    """
-    Process and ingest a document into a user-specific vector database.
-    
-    :param file_location: The location of the uploaded file on the server.
-    :param user_id: The ID of the user uploading the document.
-    """
-    # Construct a unique collection name based on user_id
-    collection_name = f"user_{user_id}_collection"
-    
-    try:
-        vectordb = pdf_to_vec(file_location, collection_name)
-        print("Document processed and ingested successfully into user-specific collection.")
-    except Exception as e:
-        print(f"Error processing document for user {user_id}: {e}")
-        raise
-```
-
-For `pdf_to_vec`, ensure it uses the `collection_name` to store the embeddings in the correct user-specific collection:
-
-```python
-def pdf_to_vec(filename, collection_name):
-    # Logic to process the PDF and store its embeddings in vectordb
-    # Use collection_name for ChromaDB collection
-    # This function will now be more aware of user-specific storage requirements
-```
-
-### Final Notes
-
-Given the academic nature and small scale of our project, focusing on implementing clean, maintainable code that clearly demonstrates the functionality and benefits of user-specific data handling is more valuable than worrying about scalability. This approach also serves as a good model for how similar systems could be architected to scale with more users, by introducing more automated and dynamic management of resources and collections.
-
-## DEFAULT CHAIN
-
-Configuring `default_chain` for each chat interaction, especially when it involves setting up multiple components like template parsing, vector database retrieval, and language model routing for every single request, could indeed introduce overhead and potentially impact performance. This overhead is particularly concerning if the configuration process is resource-intensive, involving complex computations or significant memory allocation.
-
-### Strategies to Optimize Performance
-
-1. **Caching Common Components**: Components that don't change frequently, such as prompt templates and certain chain configurations, can be cached. This way, we avoid re-initializing these components for every chat interaction. we can initialize these components once and reuse them across chat sessions.
-
-2. **Lazy Initialization**: Only initialize certain parts of the chain when they are actually needed. If certain prompts or chains are used more frequently than others, we could prioritize their initialization and delay others until they're required.
-
-3. **Preconfigured Chain Templates**: If the customization per user is limited to a few parameters (such as the vector database they're interacting with), consider creating a preconfigured template for the chains that can be quickly cloned or adapted per user session with minimal overhead.
-
-4. **Efficient Retrieval Mechanism**: For the vector database retriever used in `ConversationalRetrievalChain`, ensure that the mechanism to switch between user-specific databases is optimized. This might mean having a lightweight way of switching context without needing to reload or reinitialize the entire database connection or retrieval logic.
-
-### Implementation Example
-
-Here's an example of how we might implement a caching mechanism for `default_chain` components that are common across users:
-
-```python
-# Assuming a simplified caching mechanism for demonstration
-chain_cache = {}
-
-def get_or_create_chain(user_id, llm):
-    if 'default_chain' in chain_cache and 'router_chain' in chain_cache:
-        default_chain = chain_cache['default_chain']
-        router_chain = chain_cache['router_chain']
-        destination_chains = chain_cache['destination_chains']
-    else:
-        vectordb = get_vectordb_for_user(user_id)  # User-specific vector database
-        # Configuration for default_chain, router_chain, and destination_chains as before
-        # [...]
-        chain_cache['default_chain'] = default_chain
-        chain_cache['router_chain'] = router_chain
-        chain_cache['destination_chains'] = destination_chains
-    
-    # Here we can adapt the chains if needed based on the user_id, for example, by adjusting the vectordb retriever
-    # This is where user-specific adaptations occur
-
-    return default_chain, router_chain, destination_chains
-```
-
-### Key Points
-
-- **Reuse and Cache**: Reuse components wherever possible, caching configurations that are static or common across interactions.
-- **Minimize Dynamic Configuration**: Minimize the amount of dynamic configuration needed per interaction by using templates and parameters that can be easily switched out.
-- **Optimize Data Layer**: Ensure the data layer (e.g., user-specific vector databases) is optimized for quick switching or context updates to prevent it from becoming a bottleneck.
-
-Adopting these strategies will help maintain responsiveness and efficiency in our chat application, ensuring that overhead from setting up `default_chain` for each interaction is minimized.

docs/main_class.puml

@@ -0,0 +1,45 @@
+@startuml main
+class FastAPI {
+}
+
+class CORSMiddleware {
+}
+
+class StaticFiles {
+}
+
+class Jinja2Templates {
+}
+
+class AdminFunctions {
+}
+
+class UserFaceEmbeddingFunction {
+}
+
+class ChromaDBFaceHelper {
+}
+
+class UserLoginRouter {
+}
+
+class UserLogoutRouter {
+}
+
+class UserChatRouter {
+}
+
+class UserUploadRouter {
+}
+
+FastAPI --> CORSMiddleware : uses
+FastAPI --> StaticFiles : serves
+FastAPI --> Jinja2Templates : renders
+FastAPI --> AdminFunctions : utilizes
+FastAPI --> UserFaceEmbeddingFunction : utilizes
+FastAPI --> ChromaDBFaceHelper : utilizes
+FastAPI --> UserLoginRouter : includes
+FastAPI --> UserLogoutRouter : includes
+FastAPI --> UserChatRouter : includes
+FastAPI --> UserUploadRouter : includes
+@enduml

docs/main_seq.puml

@@ -0,0 +1,24 @@
+@startuml main
+actor Admin
+participant "FastAPI" as app
+participant "AdminFunctions" as admin
+participant "Jinja2Templates" as templates
+
+Admin -> app : POST /admin/login
+activate app
+
+app -> admin : verify_admin_password(username, password)
+activate admin
+admin --> app : verification_result
+deactivate admin
+
+alt verification success
+    app -> templates : TemplateResponse("admin_register_user.html")
+    templates --> Admin
+else verification failure
+    app -> templates : TemplateResponse("admin_login.html", {"error": "Invalid password"})
+    templates --> Admin
+end
+
+deactivate app
+@enduml

docs/utils/chat_rag_class.puml

@@ -0,0 +1,26 @@
+@startuml chat_rag
+class PyPDFLoader {
+}
+
+class HuggingFaceEmbeddings {
+}
+
+class CharacterTextSplitter {
+}
+
+class Chroma {
+}
+
+class LlamaCpp {
+}
+
+class LlamaModelSingleton {
+    {static} get_instance()
+    _load_llm()
+}
+
+PyPDFLoader --> HuggingFaceEmbeddings : uses
+HuggingFaceEmbeddings --> CharacterTextSplitter : uses
+CharacterTextSplitter --> Chroma : creates vectors
+LlamaCpp ..> LlamaModelSingleton : instance
+@enduml

docs/utils/chat_rag_seq.puml

@@ -0,0 +1,27 @@
+@startuml chat_rag
+actor User
+participant "PyPDFLoader" as loader
+participant "HuggingFaceEmbeddings" as embeddings
+participant "CharacterTextSplitter" as splitter
+participant "Chroma" as vectordb
+
+User -> loader : load(filename)
+activate loader
+loader --> User : document
+deactivate loader
+
+User -> embeddings : init(model_name)
+activate embeddings
+embeddings --> User : embeddings
+deactivate embeddings
+
+User -> splitter : split_documents(document)
+activate splitter
+splitter --> User : document_chunks
+deactivate splitter
+
+User -> vectordb : from_documents(document_chunks, embeddings)
+activate vectordb
+vectordb --> User : vectordb
+deactivate vectordb
+@enduml

docs/utils/db_class.puml

@@ -0,0 +1,22 @@
+@startuml db
+class TinyDBHelper {
+  -db : TinyDB
+  -tokens_table
+  +insert_token(user_id : string, token : string, expires_at : string) : void
+  +query_token(user_id : string, token : string) : bool
+  +remove_token_by_value(token : string) : void
+}
+
+class UserFaceEmbeddingFunction {
+  -facenet : FaceNet
+  +__call__(input : Images) : Embeddings
+}
+
+class ChromaDBFaceHelper {
+  -client
+  -user_faces_db
+  +query_user_face(presented_face : Any, n_results : int) : dict
+  +print_query_results(query_results : dict) : void
+}
+
+@enduml

docs/utils/db_seq.puml

@@ -0,0 +1,22 @@
+@startuml db
+actor User
+participant "ChromaDBFaceHelper" as helper
+participant "UserFaceEmbeddingFunction" as embedder
+database "Chroma DB" as db
+
+User -> helper: query_user_face(presented_face, n_results)
+activate helper
+
+helper -> embedder: __call__(presented_face)
+activate embedder
+embedder -> db: query(embeddings)
+activate db
+db --> embedder: query_results
+deactivate db
+
+embedder --> helper: embeddings
+deactivate embedder
+
+helper --> User: query_results
+deactivate helper
+@enduml

docs/utils/doc_ingest_class.puml

@@ -0,0 +1,10 @@
+@startuml doc_ingest
+class DocumentIngestor {
+    +ingest_document(file_location: str, collection_name: str): void
+}
+
+class VectorDB {
+    +pdf_to_vec(file_location: str, collection_name: str): VectorDB
+}
+DocumentIngestor --> VectorDB : uses
+@enduml

docs/utils/doc_ingest_seq.puml

@@ -0,0 +1,16 @@
+@startuml doc_ingest
+actor User
+participant "DocumentIngestor" as ingestor
+participant "VectorDB" as vectordb
+
+User -> ingestor : ingest_document(file_location, collection_name)
+activate ingestor
+
+ingestor -> vectordb : pdf_to_vec(file_location, collection_name)
+activate vectordb
+vectordb --> ingestor : vectordb
+deactivate vectordb
+
+ingestor --> User : "Document processed and ingested successfully"
+deactivate ingestor
+@enduml

docs/utils/download_model_class.puml

@@ -0,0 +1,12 @@
+@startuml download_model
+class ModelDownloader {
+  -model_file_path : string
+  -model_name : string
+  -model_dir : string
+  +model_file_exists_and_valid(model_file_path : string) : boolean
+  +write_model_path_to_txt_file(model_file_path : string) : void
+  +download_hf_model() : void
+  +download_gguf_model() : void
+  +download_model() : void
+}
+@enduml

docs/utils/download_model_seq.puml

@@ -0,0 +1,31 @@
+@startuml download_model
+actor User
+participant "Environment" as env
+participant "ModelDownloader" as downloader
+
+User -> downloader: download_model()
+activate downloader
+
+downloader -> env: Get MODEL_CLASS
+activate env
+env --> downloader: 'hf' or 'gguf'
+deactivate env
+
+alt MODEL_CLASS is 'hf'
+    downloader -> downloader: download_hf_model()
+    activate downloader
+    downloader -> downloader: model_file_exists_and_valid()
+    downloader -> downloader: write_model_path_to_txt_file()
+    deactivate downloader
+else MODEL_CLASS is 'gguf'
+    downloader -> downloader: download_gguf_model()
+    activate downloader
+    downloader -> downloader: model_file_exists_and_valid()
+    downloader -> downloader: write_model_path_to_txt_file()
+    deactivate downloader
+else Unsupported model class
+    downloader -> User: Print "Unsupported model class"
+end
+
+deactivate downloader
+@enduml

docs/utils/ec_image_utils_class.puml

@@ -0,0 +1,9 @@
+@startuml ec_image_utiils
+class ImageUtils {
+  {static} load_image(filename : string) : image
+  {static} normalize(img : image) : image
+  {static} detect_faces_with_mtcnn(img : image) : List[boundingBox]
+  {static} crop_faces_to_160x160(img : image, bounding_boxes : List[boundingBox]) : imageArray
+  {static} get_user_cropped_image_from_photo(filename : string) : image
+}
+@enduml

docs/utils/ec_image_utils_seq.puml

@@ -0,0 +1,26 @@
+@startuml ec_image_utils
+actor User
+participant "ImageUtils" as utils
+
+User -> utils : get_user_cropped_image_from_photo(filename)
+activate utils
+
+utils -> utils : load_image(filename)
+activate utils
+utils --> utils : img
+deactivate utils
+
+utils -> utils : detect_faces_with_mtcnn(img)
+activate utils
+utils --> utils : bounding_boxes
+deactivate utils
+
+utils -> utils : crop_faces_to_160x160(img, bounding_boxes)
+activate utils
+utils --> utils : cropped_faces
+deactivate utils
+
+utils --> User : cropped_face[0]
+deactivate utils
+
+@enduml

docs/utils/jwt_utils_class.puml

@@ -0,0 +1,7 @@
+@startuml jwt_utils
+class JWTUtils {
+  +encode_jwt(data: dict): string
+  +decode_jwt(token: string): dict
+  +create_access_token(data: dict, expires_delta: Union[timedelta, None]): string
+}
+@enduml

docs/utils/jwt_utils_seq.puml

@@ -0,0 +1,16 @@
+@startuml jwt_utils
+actor Client
+participant "JWTUtils" as utils
+
+Client -> utils : create_access_token(data, expires_delta)
+activate utils
+
+utils -> utils : encode_jwt(data)
+activate utils
+utils -> utils : Setting expiration
+utils --> utils : encoded_jwt
+deactivate utils
+
+utils --> Client : encoded_jwt
+deactivate utils
+@enduml