Merge pull request #8 from grey-box/sp25ccsu-api

Cumulative end-of-semester API/Middleware

Author: erikalanj

.github/workflows/main.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          cd api
+          cd fastapi/
           pip install -r requirements.txt
           python -m nltk.downloader punkt
 

extras/uvicornrun.png

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+tab_width = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

fastapi/.editorconfig

@@ -2,3 +2,4 @@ __pycache__/
 .idea/
 .venv/
 venv/
+.env

fastapi/.gitignore

@@ -0,0 +1,159 @@
+# BACKEND GUIDE
+
+## I. **RUNNING APP**
+
+Refer to [INSTALLATION.md](../INSTALLATION.md) for more in depth configuration details
+and dependency installation. This section is purely for running the backend.
+
+1) Ensure that your current working directory is `fastapi` (i.e. run `cd fastapi`)
+2) If you have not already, set up your virtual environment (`python3 -m venv venv`)
+3) Switch to the virtual environment (`source venv/bin/activate` or `venv\bin\activate.bat` depending on OS)
+4) If you have not already, install dependencies (`pip install -r requirements.txt`)
+5) Consider enabling debug logging:
+   1) Create `.env` inside the `fastapi` folder
+   2) Add properties to enable FastAPI and general debug logging:
+      ```properties
+      LOG_LEVEL=DEBUG
+      FASTAPI_DEBUG=True
+      ```
+6) Finally, run the app with Uvicorn (`uvicorn app.main:app --reload`)
+   * The app runs on port 8000 by default. To use another port, add `--port <number>` to the command.
+
+You should see logs similar to the following:
+![result](../extras/uvicornrun.png)
+
+To test the endpoints, use a tool like POSTMAN or curl in order to make GET or POST requests and receive formatted JSON responses.
+
+## II. **FILE STRUCTURE**
+
+`app` is the root package of the python project.
+
+`app/ai` contains the backend ML functionality.
+
+`app/api` contains the API endpoints exposed by the web server.
+
+`app/model` contains request and response structures for communication between the front and back end.
+
+## III. **CURRENT FUNCTIONALITY**
+
+### `/symmetry/v1/wiki/articles`
+
+**Protocol:** `GET`
+
+**Parameters:**
+ * `query`: A Wikipedia article URL or title
+ * `lang`: Optional. A language short code (i.e. "en" or "fr") defaulting to "en" for English.
+
+**Response:**
+
+```json
+{
+    "sourceArticle": "<article content>",
+    "articleLanguages": [
+        // Article language data
+    ]
+}
+```
+
+### `/symmetry/v1/articles/compare`
+
+> [!NOTE]
+> This endpoint is a work in progress and currently only returns dummy data.
+
+**Protocol:** `POST`
+
+**Parameters:**
+```json
+{
+    "article_text_blob_1": "<article 1 content>",
+    "article_text_blob_2": "<article 2 content>",
+    "article_text_blob_1_language": "<article 1 short language code>",
+    "article_text_blob_2_language": "<article 2 short language code>",
+    // Float ranging from 0-1 representing similarity percentage.
+    "comparison_threshold": 0.8,
+    "model_name": "<model name string>"
+}
+```
+
+Response:
+```json
+{
+    "comparisons": [
+        // Array of comparison objects.
+        {
+            "left_article_array": [
+                // Array of article 1 content divided into subsections.
+            ],
+            "right_article_array": [
+                // Array of article 2 content divided into subsections.
+            ],
+            "left_article_missing_info_index": [
+                // Array of indices of article 1 subsections that are not present in 2.
+            ],
+            "right_article_extra_info_index": [
+                // Array of indices of article 2 subsections that are not present in 1.
+            ]
+        }
+    ]
+}
+```
+
+## IV. **CONCEPTS & RESEARCH**
+
+### Simple UI
+The UI is supposed to be as simple as possible - the UI team is supposed to focus their
+efforts on improving the user experience, not covering all possible cases.
+That means that the API/middleware is responsible for the bulk of logic related to input
+validation.
+
+For example, the dynamic search box allowing queries by URL or article title is handled
+by the wiki articles endpoint rather than the UI.
+
+### Semantic Comparison Without Translation
+The language comparison model in use does not require that the input texts be in the same language.
+
+### JSON vs XML
+We were tasked with investigating the benefits of using XML over JSON for communications
+as it might be easier for some ML models to work with.
+
+Our findings were that the primary benefit of using XML for some ML models is that it can
+be used to more easily guard against prompt injection.
+It is otherwise largely harder to work with, and is a model-specific detail.
+
+### CORS
+Cross-origin resource sharing is useful for protecting against certain attacks.
+By restricting resources to whitelisted domains, we can prevent this.
+
+However, Symmetry currently operates as a local server. CORS will not be important until
+a future state where a standalone Symmetry server exists.
+
+### Endpoint Naming Conventions
+
+A quick read on RESTful resource naming: https://restfulapi.net/resource-naming/
+
+The current format is `/symmetry/v1/<path>/<to>/<resource>`.
+
+For a more dense and in-depth view of the RESTful philosophy, the above article
+links Roy Fielding's dissertation:
+https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1
+
+## V. **WHAT'S NEXT**
+
+### External Request Rejection
+As Symmetry does run a local web server, it would be a good idea to ensure that all
+remote requests are rejected.
+
+### CORS Configurability
+As stated above, CORS is not particularly necessary for Symmetry in its current state.
+However, in the future, it should likely be configurable to allow other origins.
+
+### Caching
+There is a cache implementation in place for articles. However, it is global and
+designed only for use in Wikipedia article fetching. With a little effort, ArticleCache
+could be repurposed into a more general and reusable content cache.
+
+### Live Comparison Data
+The [comparison endpoint](#symmetryv1articlescompare) currently returns dummy data.
+When the ML team completes their side, this endpoint will need to be connected to
+return real data.
+

fastapi/README.MD

@@ -0,0 +1,89 @@
+import hashlib
+import logging
+from time import time
+from typing import Dict, List, Optional, Tuple
+from collections import OrderedDict
+from sys import getsizeof
+
+CACHE_LIMIT = 10  # Max number of cached articles
+TTL_SECONDS = 4000  # Time to live for cached items in seconds
+
+"""
+This module implements an LRU (Least Recently Used) cache for storing articles fetched from Wikipedia.
+of the endpoint path. The above parameters are passed to the function as arguments which will determine
+the time to live as well as the amount of elements which can be stored in the cache to prevent memory leaks.
+This current implementation is exclusively insantiated and used in the wiki_article.py file, but can be 
+extraported and used in other files in future implemenetations.
+"""
+
+
+# Internal LRU cache manager
+class ArticleCache:
+    # Initializes the cache
+    def __init__(self, max_size: int = CACHE_LIMIT, ttl: int = TTL_SECONDS):
+        self.cache: "OrderedDict[str, Dict]" = OrderedDict()
+        self.max_size = max_size
+        self.ttl = ttl
+        self.current_size = 0  # Approximate memory usage in bytes
+    # Creates cache key
+    def _get_cache_key(self, key: str) -> str:
+        return hashlib.md5(key.encode()).hexdigest()
+
+    def get(self, key: str) -> Tuple[Optional[str], Optional[List[str]]]:
+        cache_key = self._get_cache_key(key)
+        cached_data = self.cache.get(cache_key)
+        # Checks cache for articles, misses if none are found
+        if not cached_data:
+            logging.info(f"[CACHE MISS] No cache entry for key: {cache_key}")
+            return None, None
+        # Cached article expires and is evicted if it exists longer than 4000 seconds (approx. 1.1 hours)
+        if time() - cached_data["timestamp"] > self.ttl:
+            self._evict(cache_key, reason="expired")
+            return None, None
+
+        self.cache.move_to_end(cache_key)
+        logging.info(f"[CACHE HIT] Returning cached data for key: {cache_key}")
+        return cached_data["content"], cached_data["languages"]
+    # Sets cached article if it has not been cached yet
+    def set(self, key: str, content: str, languages: List[str]) -> None:
+        cache_key = self._get_cache_key(key)
+        item = {
+            "content": content,
+            "languages": languages,
+            "timestamp": time(),
+        }
+        # Determines size of article
+        item_size = getsizeof(item)
+
+        # Checks cache key and moves it accordingly based on LRU to enable effective eviction if needed
+        if cache_key in self.cache:
+            self.current_size -= getsizeof(self.cache[cache_key])
+            self.cache.move_to_end(cache_key)
+        elif len(self.cache) >= self.max_size:
+            evicted_key, evicted_val = self.cache.popitem(last=False)
+            self.current_size -= getsizeof(evicted_val)
+            logging.info(f"[CACHE EVICTED] LRU item: {evicted_key}")
+
+        self.cache[cache_key] = item
+        self.current_size += item_size
+
+        logging.info(f"[CACHE SET] Key: {cache_key} | Size: {len(self.cache)}/{self.max_size} | Approx. Memory: {self.current_size} bytes")
+    # Nukes LRU article in the cache
+    def _evict(self, key: str, reason: str = "manual") -> None:
+        if key in self.cache:
+            self.current_size -= getsizeof(self.cache[key])
+            del self.cache[key]
+            logging.info(f"[CACHE {reason.upper()}] Evicted key: {key}")
+
+# Instantiate global cache object
+_article_cache = ArticleCache()
+
+# For external use
+def get_article_cache_key(key: str) -> str:
+    return _article_cache._get_cache_key(key)
+
+def get_cached_article(title: str) -> Tuple[Optional[str], Optional[List[str]]]:
+    return _article_cache.get(title)
+
+def set_cached_article(key: str, content: str, languages: List[str]) -> None:
+    _article_cache.set(key, content, languages)

fastapi/app/api/cache.py

@@ -0,0 +1,58 @@
+from app.model.response import CompareResponse, ComparisonResult
+from fastapi import APIRouter
+from app.model.request import CompareRequest
+
+router = APIRouter(prefix="/symmetry/v1", tags=["comparison"])
+
+
+@router.post("/articles/compare", response_model=CompareResponse)
+def compare_articles(payload: CompareRequest):
+    """
+    This endpoint requests a comparison of two blobs of text.
+    The request includes the articles, the languages of the articles, the comparison threshold, and model name.
+
+    The response is an array of comparison results, allowing support for a future state where
+    output may be requested from multiple ML models in a single request.
+
+    The schema for this response is defined in the model/response.py file.
+
+    ------------------------------------------------------------------------------------------------
+    THIS ENDPOINT IS NOT FINALIZED!!!
+
+    This is currently returning dummy data, and still needs to be integrated with the ML model
+    in order to return the actual comparison results from the backend.
+    ------------------------------------------------------------------------------------------------
+    """
+
+    """
+
+    """
+
+    left_article_array = [
+        "Barack Hussein Obama II is an American politician who served as the 44th president of the United States from 2009 to 2017.",
+        "Obama previously served as a U.S. senator representing Illinois from 2005 to 2008 and as an Illinois state senator from 1997 to 2004.",
+        "Obama was born in Honolulu, Hawaii.",
+        "He graduated from Columbia University in 1983 with a Bachelor of Arts degree in political science and later worked as a community organizer in Chicago.",
+        "In 1988, Obama enrolled in Harvard Law School, where he was the first black president of the Harvard Law Review.",
+        "In the 2008 presidential election, after a close primary campaign against Hillary Clinton, he was nominated by the Democratic Party for president.",
+        "Obama selected Joe Biden as his running mate and defeated Republican nominee John McCain and his running mate Sarah Palin.",
+    ]
+
+    right_article_array = [
+        "Barack Hussein Obama II is an American politician who served as the 44th president of the United States from 2009 to 2017.",
+        "A member of the Democratic Party, he was the first African-American president in American history.",
+        "He graduated from Columbia University in 1983 with a Bachelor of Arts degree in political science and later worked as a community organizer in Chicago.",
+        "In 1988, Obama enrolled in Harvard Law School, where he was the first black president of the Harvard Law Review.",
+        "He became a civil rights attorney and an academic, teaching constitutional law at the University of Chicago Law School from 1992 to 2004.",
+        "In 1996, Obama was elected to represent the 13th district in the Illinois Senate, a position he held until 2004, when he successfully ran for the U.S. Senate.",
+        "In the 2008 presidential election, after a close primary campaign against Hillary Clinton, he was nominated by the Democratic Party for president.",
+    ]
+
+    comparison = ComparisonResult(
+        left_article_array=left_article_array,
+        right_article_array=right_article_array,
+        left_article_missing_info_index=[1, 2, 6],  # Dummy indices
+        right_article_extra_info_index=[1, 4, 5],  # Dummy indices
+    )
+
+    return CompareResponse(comparisons=[comparison])