{"id":50508946,"url":"https://github.com/denisecase/pro-analytics-ai","last_synced_at":"2026-06-02T18:31:22.970Z","repository":{"id":289703424,"uuid":"972142474","full_name":"denisecase/pro-analytics-ai","owner":"denisecase","description":"This project demonstrates an OpenAI ChatGPT like project illustrating the structure and implementation of a Retrieval-Augmented Generation (RAG) system built with Python, vector embeddings, and Large Language Models (LLM).","archived":false,"fork":false,"pushed_at":"2025-05-18T18:30:34.000Z","size":141,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T19:33:41.784Z","etag":null,"topics":["analytics","educational","git","llm","professional","python"],"latest_commit_sha":null,"homepage":"http://34.222.116.69:8000","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denisecase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-24T15:46:16.000Z","updated_at":"2025-05-18T18:30:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"ee6f9f73-bf58-4ef5-822a-072eab431caa","html_url":"https://github.com/denisecase/pro-analytics-ai","commit_stats":null,"previous_names":["denisecase/pro-analytics-ai"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/denisecase/pro-analytics-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denisecase%2Fpro-analytics-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denisecase%2Fpro-analytics-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denisecase%2Fpro-analytics-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denisecase%2Fpro-analytics-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denisecase","download_url":"https://codeload.github.com/denisecase/pro-analytics-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denisecase%2Fpro-analytics-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33833277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","educational","git","llm","professional","python"],"created_at":"2026-06-02T18:31:21.575Z","updated_at":"2026-06-02T18:31:22.958Z","avatar_url":"https://github.com/denisecase.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pro-analytics-ai\r\n\r\nThis project demonstrates an OpenAI ChatGPT like project illustrating the structure and implementation of a Retrieval-Augmented Generation (RAG) system built with Python, vector embeddings, and Large Language Models (LLM).\r\n\r\nIMPORTANT: Growing a working LLM system requires **serious hardware** and **significant storage**.\r\nRead the requirements BEFORE attempting (or just read the repo to get an idea.)\r\nThis initial, local-only implementation takes a whooping **300 GB** of space. \r\n\r\n## Limited Focus / Small Raw Data Set (~100 KB)\r\n\r\nThis assistant is trained on the [pro-analytics-01](https://github.com/denisecase/pro-analytics-01) guide and is designed to help with setting up and working on professional analytics projects using Git, Python, and VS Code.\r\n\r\nThe corpus includes the relevant `.md`, `.py`, `.ipynb`, `.txt`, and configuration files from the project.\r\n\r\n| File Type | Example Files | Approx Size | Notes |\r\n|:----------|:--------------|:------------|:------|\r\n| Markdown files (.md) | README.md, setup_os.md, etc. | ~50 KB | Instructions and guides |\r\n| Python scripts (.py) | demo_script.py, install_python.py, etc. | ~25 KB | Basic educational scripts |\r\n| Jupyter notebooks (.ipynb) | demo_notebook.ipynb | ~25 KB | Demo workflows |\r\n| Configuration files (.txt, .gitignore, requirements.txt) | requirements.txt, .gitignore | ~2–5 KB | Important setup information |\r\n\r\n**Total estimated training set size: ~100 KB (before tokenization).**\r\n---\r\n\r\n## Assistant Behavior Customization (GUIDELINES.md)\r\n\r\nIn addition to the raw project content, this assistant uses a small [`GUIDELINES.md`](backend/D_storage_layer/raw_docs/GUIDELINES.md) file to define behavior standards.\r\n\r\nThe guidelines influence how the assistant:\r\n\r\n- Confirms the user's operating system and terminal as needed.\r\n- Formats answers professionally and concisely.\r\n- Provides technically accurate and context-aware support.\r\n- Asks only one clarifying question at a time.\r\n\r\nThis customization improves the consistency, professionalism, and usefulness of the responses, especially when helping new analysts.\r\n\r\n---\r\n\r\n## Requirements (⭐32+ GB RAM, ⭐0.5 TB+ SSD)\r\n\r\nThe information size is trivial, but building a brain from it takes a great deal of effort, memory, and space. \r\nThe biggest example took **300 GB** easily, and with additional quanitization support, we may get that below **100 GB**.\r\nFor an illustration of how the space is used, see [SPACE.md](SPACE.md).\r\n\r\nMachine requirements even for this small corpus are:\r\n\r\n- 32 GB RAM minimum (64 GB preferred for smoother training and inference)\r\n- 1 TB SSD storage minimum (model, environment, temporary files)\r\n- 4–8 CPU cores (modern i7, Ryzen 5, or equivalent recommended)\r\n- GPU: Strongly recommended (NVIDIA T4, A10, 3060 or better)\r\n  - Optional for API-based usage only (requires more space ~300 GB).\r\n  - Required for running 8-bit or 4-bit quantized local models.\r\n- Ubuntu 20.04/22.04 recommended (or WSL2 on Windows 11)\r\n\r\nTested on a machine with a 12-core (24-thread) CPU, 64 GB RAM, no discrete GPU (integrated graphics only), and a 2 TB NVMe SSD.\r\n\r\nAdditional:\r\n\r\n- Use **Python 3.11** for better compatibility and performance with modern ML libraries.\r\n- Machine Learning libraries like PyTorch and HuggingFace can require **0.5 GB or more** of installation space.\r\n- On **Windows**, perform all operations inside **WSL2** (Ubuntu) to avoid compatibility problems and streamline Python, Git, and ML tool use.\r\n   - Open PowerShell, type `wsl` and hit return.\r\n   - If setting up WSL for the first time, store your WSL username and password - you will need the password during later installations. \r\n\r\n## Large Tools (and their Space Requirements)\r\n\r\n| Tool/Library | Purpose | Approx Size |\r\n|:-------------|:--------|:------------|\r\n| sentence-transformers | Generating vector embeddings | **~0.5–1 GB** |\r\n| chromadb | Local vector database storage | ~100–200 MB |\r\n| fonttools | Dependency for tokenizer backends | ~50–100 MB |\r\n| openai | Querying GPT models (API client) | ~50 MB |\r\n| fastapi | Local API interaction (backend server) | ~50 MB |\r\n| uvicorn | ASGI server for running FastAPI | ~50 MB |\r\n| bitsandbytes | For 8-bit quantization (optional) | ~80 MB |\r\n| auto-gptq | 4-bit model loader (optional) | ~150–250 MB |\r\n| | pretrained 4-bit models  | **~0.3–1 GB** per model |\r\n\r\nSummary\r\n\r\n- Total base environment without quantization: **~1–2 GB**\r\n- With 8-bit quantization support: **~2–2.5 GB**\r\n- With 4-bit quantization support: **~2.5–3.5 GB**\r\n\r\n\r\nFor more information about space requirements when building a neural net brain, see [SPACE.md](SPACE.md).\r\n\r\n## Pretrained Language Models\r\n\r\nPretrained large language models (LLMs) have already been trained to understand and generate human language.\r\nThey are available for free from sources like [Hugging Face](https://huggingface.co/models).\r\nWhen loading a model using libraries like `transformers` or `auto-gptq`, the model files are automatically downloaded into a local Hugging Face cache, typically located at `~/.cache/huggingface/` (in Linux and WSL systems) so the large files can be shared across projects.\r\n\r\nThese models include the trained neural network weights needed to generate text, answer questions, or perform other natural language tasks.  \r\nPretrained models can be very large — often **1 GB or more per model**, even when quantized (compressed) into 8-bit or 4-bit formats.\r\n\r\nIMPORTANT: Make sure you have sufficient **disk space** and **memory** before attempting to download and run larger models.\r\n\r\n---\r\n\r\n## Architecture\r\n\r\nFront End\r\n\r\n- Simple HTML/CSS/JS web app\r\n\r\nL\r\n| Layer  | Responsibility | Depends On | Expanded Description |\r\n|:-------|:---------------|:------------|:---------------------|\r\n| utils  | Logging and Configuration | none | Core utility functions for logging important events and managing settings. Foundation for all other layers. |\r\n| C      | Retrieval (Context Finder) | utils | Takes a user question and searches for related information from the stored vector database (in chromadb). Needs utils for configuration and logging. |\r\n| B      | Prompt Building and Querying | C | Builds a full prompt using both the user's question and retrieved context, then sends it to an LLM model (via openai library or local API). Needs the retrieval layer to gather context first. |\r\n| A      | API Interface (Public Endpoint) | B | Exposes a public API (e.g., using fastapi and uvicorn) that receives user questions, calls the prompt/query layer, and returns answers. Only depends on layer B. |\r\n\r\nFor more information about the magic that happens in layer B, see the [backend/B_prompt_model/README.md](backend/B_prompt_model/README.md).\r\n\r\n---\r\n\r\n## LLM Source Options (Choose One if Using Full-Precision or API Models)\r\n\r\n- OpenRouter\tOpen-source LLMs + OpenAI compatibility (free w/key)\r\n- OpenAI API\tClean, reliable, simple for students (paid w/key)\r\n\r\nPrices for GPT-3.5 are pretty affordable\r\n\r\n- $0.0015 per 1,000 tokens (input)\r\n- $0.002 per 1,000 tokens (output)\r\n\r\n---\r\n\r\n## Current Status\r\n\r\nRuns locally, not yet hosted.\r\n\r\n\r\n| Feature                     | Description                                         |\r\n|-----------------------------|-----------------------------------------------------|\r\n| Frontend Input + Button     | Captures and sends question to the backend  |\r\n| FastAPI Backend             | Handles POST requests, logs content        |\r\n| Embedded Markdown Knowledge | Chunks \u0026 indexes repository content        |\r\n| RAG + OpenRouter API   | Builds a prompt from relevant context and queries LLM |\r\n| UI Response      | Displays answer in the interface      |\r\n\r\n\r\n---\r\n\r\n## Responses Will Change (Set Temp to 0 to be Consistent)\r\n\r\nAnswers will change. To get consistent responses, we can set the 'temperature' to zero. \r\n\r\n```python\r\nresponse = client.chat.completions.create(\r\n    model=model_name,\r\n    messages=[{\"role\": \"user\", \"content\": prompt}],\r\n    temperature=0.0\r\n)\r\n```\r\n\r\nSince we haven't done that, responses will vary. For example:\r\n\r\n- Git is a version control system.\r\n- Git is a version control system that allows you to track changes in your code, collaborate with others, and manage your project's history effectively.\r\n \r\n![Example](images/pro-analytics-ai.png)\r\n\r\n---\r\n\r\n## If Windows, Work in WSL\r\n\r\nOpen PowerShell terminal and type `wsl` and hit Enter to run. \r\nAll work is done in WSL. Tested with Ubuntu.\r\n\r\n## Create Repos folder and Clone (One-Time to Get Started)\r\n\r\n- Create ~/Repos folder: `mkdir -p ~/Repos`\r\n- Clone your repo with `git clone your-repo-url`\r\n- Change directory into your project repo with `cd pro-analytics-ai`\r\n- Open your project repo folder in VS Code: `code .`\r\n\r\n## Prepare the Environment (One-Time Task)\r\n\r\nIn VS Code, open a Terminal / New Terminal and run the following commands one at a time. \r\n\r\n```shell\r\nsudo apt update\r\nsudo apt install software-properties-common -y\r\nsudo add-apt-repository ppa:deadsnakes/ppa -y\r\nsudo apt update\r\nsudo apt install python3.11 python3.11-venv -y\r\nsudo apt install uvicorn -y\r\n```\r\n\r\n## Get LLM API Key (One-Time Task)\r\n\r\n1. Go to: https://openrouter.ai/\r\n2. Click \"Sign In\" (top right). You can use Google, GitHub, or email\r\n3. After logging in, go to: \u003chttps://openrouter.ai/account\u003e\r\n4. Scroll to the API Keys section\r\n5. Click \"Create Key\". Name it `Pro-Analytics-AI` or something. Set amount to 1. \r\n6. Copy your new API key (it will start with or-)\r\n7. Paste it into your `.env` file like this:\r\n\r\nOPENROUTER_API_KEY=or-xxxxxxxxxxxxxxxxxxxx\r\n\r\n## Create a .venv and Install Dependencies\r\n\r\nOpen the project repository folder in VS Code. \r\nOpen a new terminal (bash or zsh) (e.g. using the VS Code menu / Terminal / New Terminal) and run the following commands one at a time. \r\n\r\n1. Create a new virtual environment named .venv (one-time task).\r\n2. Activate the virtual environment (every time you open a terminal).\r\n3. Install and upgrade key packages.\r\n4. Install and upgrade packages from requirements.txt.\r\n\r\nFor more info, see requirements.txt. \r\nAdd `--timeout 100` to let each file take 100 seconds instead of default 15 seconds. \r\nRun update again after installing deadsnakes.\r\n\r\n```shell\r\npython3.11 -m venv .venv\r\nsource .venv/bin/activate\r\npython3 -m pip install --upgrade pip setuptools wheel\r\npython3 -m pip install --upgrade -r requirements.txt --timeout 100\r\n```\r\n\r\nNote 1. You may need to rerun the last install command several times to get all packages downloaded and installed correctly into your local project virtual environment (.venv). \r\n\r\nNote 2. When returning to the project, remember to activate your .venv before installing requirements or running code. \r\n\r\n\r\n## To Run Locally - Terminal 1 of 2 (Server/API):\r\n\r\nTo launch the backend:\r\n\r\n```shell\r\nsource .venv/bin/activate\r\nuvicorn backend.A_api_interface.query_api:app --host 0.0.0.0 --port 8000 --reload\r\n```\r\nKeep the terminal open and don't use it for anything else while running the backend. \r\n\r\n## To Run Locally - Terminal 2 of 2 (Client):\r\n\r\nTo test it, open another terminal and run:\r\n\r\n```shell\r\ncurl -X POST http://127.0.0.1:8000/query \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"question\": \"What is git?\"}'\r\n```\r\n\r\nUse CTRL+C - hold down the CTRL and c key together - (multiple times if needed) to kill the process. \r\n\r\n## To Open a Front End Web Page Preview\r\n\r\nInstall VS Code Extension Live Preview. \r\nIn VS Code, right-click `docs/index.html` and select \"Show Preview\". \r\n\r\n\r\n## Optional / As Needed: Update Content As the Source Repository Changes\r\n\r\n```shell\r\ngit clone https://github.com/denisecase/pro-analytics-01 backend/D_storage_layer/raw_docs/pro-analytics-01\r\nrm -rf backend/D_storage_layer/raw_docs/pro-analytics-01/.git\r\nrm -rf backend/D_storage_layer/raw_docs/pro-analytics-01/.vscode\r\nrm -rf backend/D_storage_layer/raw_docs/pro-analytics-01/logs\r\npython3 refresh_chroma.py\r\n```\r\n\r\nThis updates the content and deletes the .git folder and other unneeded parts from backend/D_storage_layer/raw_docs/pro-analytics-01.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenisecase%2Fpro-analytics-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenisecase%2Fpro-analytics-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenisecase%2Fpro-analytics-ai/lists"}