gurrt 0.1.0__tar.gz

gurrt-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+echo "The MIT License
+Copyright (c) `date +%Y` Arthur L Piepmeier III <http://treypiepmeier.com/>
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+\"Software\"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE." > MIT-Licence.txt

gurrt-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: gurrt
+Version: 0.1.0
+Summary: An Intelligent Open-Source Video Understanding System A different path from traditional Large Video Language Models (LVLMs). Built for modularity, openness, and real-world usability.
+Author-email: Mohammad Owais <owaismohammad2515@gmail.com>, Fareha Aslam <farehaaslam57@gmail.com>
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: torchaudio
+Requires-Dist: opencv-python>=4.13.0.92
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: transformers>=5.1.0
+Requires-Dist: accelerate>=1.12.0
+Requires-Dist: pillow>=12.1.0
+Requires-Dist: chromadb>=1.4.1
+Requires-Dist: ollama>=0.6.1
+Requires-Dist: langchain>=1.2.9
+Requires-Dist: langchain-groq>=1.1.2
+Requires-Dist: moviepy>=1.0.3
+Requires-Dist: sentence-transformers>=5.2.2
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: scenedetect>=0.6.7.1
+Requires-Dist: scikit-image>=0.26.0
+Requires-Dist: ipykernel>=7.2.0
+Requires-Dist: easyocr>=1.7.2
+Requires-Dist: yt-dlp>=2026.2.4
+Requires-Dist: openai-whisper>=20250625
+Requires-Dist: faster-whisper>=1.2.1
+Requires-Dist: langchain-text-splitters>=1.1.0
+Requires-Dist: fastapi>=0.128.7
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: supermemory>=3.24.0
+Requires-Dist: platformdirs>=4.5.1
+Requires-Dist: typer>=0.21.1
+Requires-Dist: alive-progress>=3.3.0
+Dynamic: license-file
+
+# gurrt
+An intelligent video understanding system designed as an open-source alternative to monolithic Large Video Language Models
+
+I built gurrt out of frustration.
+
+Working with Large Video Language Models locally is:
+
+- Expensive to set up  
+- GPU intensive  
+- Slow to experiment with  
+- Difficult to run on consumer hardware  
+- Often closed or partially restricted  
+
+Most state-of-the-art video models require massive compute clusters and large-scale infrastructure.  
+They are impressive — but they are not accessible.
+
+If meaningful video intelligence requires:
+
+- Multiple high-end GPUs  
+- Hours of inference time  
+- Proprietary model access  
+
+Then it stops feeling truly open.
+
+---
+
+### A Different Philosophy
+
+gurrt is not an attempt to compete with systems like YouTube’s internal models or other large-scale industrial LVLMs trained on massive GPU clusters.
+
+It is an attempt to rethink the approach.
+
+Instead of asking how to build a larger end-to-end video transformer, it explores a different path:
+
+- Smarter frame sampling techniques  
+- Stronger and more modular vision models  
+- Better structured embedding strategies  
+- More efficient and grounded RAG pipelines  
+- Persistent memory-driven reasoning  
+
+It represents a belief that meaningful video understanding can emerge from:
+
+- Thoughtful engineering  
+- Smart sampling  
+- Strong modular components  
+- Memory-augmented retrieval  
+
+Not just from massive GPU clusters and billion-parameter models.
+
+
+## Architecture Overview
+```bash
+Video
+  │
+  ├── Smart Frame Extraction
+  │     └── Captioning + Embeddings
+  │
+  ├── Audio Extraction
+  │     └── Speech-to-Text + Embeddings
+  │
+  ├── Vector Memory Store
+  │
+  ├── Supermemory (Persistent Conversation Layer)
+  │
+  └── LLM Reasoning Engine
+```
+
+## Project Setup (using uv)
+
+```bash
+# Install uv if you haven't already
+pip install uv
+
+# Sync dependencies
+uv sync
+
+# Activate environment
+.venv\Scripts\activate
+```
+
+## File Structure
+
+```bash
+gurrt/
+├── src/
+│   |
+│   │
+│   └── videorag/                      # Core Video-RAG application package
+│       │
+│       ├── api/
+│       │   └── server.py              # API server (exposes endpoints for querying, ingestion, etc.)
+│       │
+│       ├── cli/
+│       │   └── main.py                # CLI entry point (init, ingest, query commands)
+│       │
+│       ├── config/
+│       │   └── config.py              # Configuration management (API keys, paths, environment setup)
+│       │
+│       ├── core/                      # Core intelligence pipeline
+│       │   ├── __init__.py
+│       │   ├── asr.py                 # Audio extraction + speech-to-text processing
+│       │   ├── embedding.py           # Embedding generation for captions & transcripts
+│       │   ├── llm.py                 # LLM interaction and reasoning logic
+│       │   ├── models.py              # Model loading and management utilities
+│       │   ├── pipeline.py            # End-to-end ingestion + query pipeline orchestration
+│       │   ├── prompts.py             # Prompt templates and structured context injection
+│       │   ├── search.py              # Retrieval logic (semantic search over stored embeddings)
+│       │   └── vectordb.py            # Vector database interface and storage abstraction
+│       │
+│       └── utils/
+│           └── utils.py            # Shared utility functions and helpers
+│
+└── README.md                         # Project documentation
+```
+
+
+

gurrt-0.1.0/README.md

@@ -0,0 +1,117 @@
+# gurrt
+An intelligent video understanding system designed as an open-source alternative to monolithic Large Video Language Models
+
+I built gurrt out of frustration.
+
+Working with Large Video Language Models locally is:
+
+- Expensive to set up  
+- GPU intensive  
+- Slow to experiment with  
+- Difficult to run on consumer hardware  
+- Often closed or partially restricted  
+
+Most state-of-the-art video models require massive compute clusters and large-scale infrastructure.  
+They are impressive — but they are not accessible.
+
+If meaningful video intelligence requires:
+
+- Multiple high-end GPUs  
+- Hours of inference time  
+- Proprietary model access  
+
+Then it stops feeling truly open.
+
+---
+
+### A Different Philosophy
+
+gurrt is not an attempt to compete with systems like YouTube’s internal models or other large-scale industrial LVLMs trained on massive GPU clusters.
+
+It is an attempt to rethink the approach.
+
+Instead of asking how to build a larger end-to-end video transformer, it explores a different path:
+
+- Smarter frame sampling techniques  
+- Stronger and more modular vision models  
+- Better structured embedding strategies  
+- More efficient and grounded RAG pipelines  
+- Persistent memory-driven reasoning  
+
+It represents a belief that meaningful video understanding can emerge from:
+
+- Thoughtful engineering  
+- Smart sampling  
+- Strong modular components  
+- Memory-augmented retrieval  
+
+Not just from massive GPU clusters and billion-parameter models.
+
+
+## Architecture Overview
+```bash
+Video
+  │
+  ├── Smart Frame Extraction
+  │     └── Captioning + Embeddings
+  │
+  ├── Audio Extraction
+  │     └── Speech-to-Text + Embeddings
+  │
+  ├── Vector Memory Store
+  │
+  ├── Supermemory (Persistent Conversation Layer)
+  │
+  └── LLM Reasoning Engine
+```
+
+## Project Setup (using uv)
+
+```bash
+# Install uv if you haven't already
+pip install uv
+
+# Sync dependencies
+uv sync
+
+# Activate environment
+.venv\Scripts\activate
+```
+
+## File Structure
+
+```bash
+gurrt/
+├── src/
+│   |
+│   │
+│   └── videorag/                      # Core Video-RAG application package
+│       │
+│       ├── api/
+│       │   └── server.py              # API server (exposes endpoints for querying, ingestion, etc.)
+│       │
+│       ├── cli/
+│       │   └── main.py                # CLI entry point (init, ingest, query commands)
+│       │
+│       ├── config/
+│       │   └── config.py              # Configuration management (API keys, paths, environment setup)
+│       │
+│       ├── core/                      # Core intelligence pipeline
+│       │   ├── __init__.py
+│       │   ├── asr.py                 # Audio extraction + speech-to-text processing
+│       │   ├── embedding.py           # Embedding generation for captions & transcripts
+│       │   ├── llm.py                 # LLM interaction and reasoning logic
+│       │   ├── models.py              # Model loading and management utilities
+│       │   ├── pipeline.py            # End-to-end ingestion + query pipeline orchestration
+│       │   ├── prompts.py             # Prompt templates and structured context injection
+│       │   ├── search.py              # Retrieval logic (semantic search over stored embeddings)
+│       │   └── vectordb.py            # Vector database interface and storage abstraction
+│       │
+│       └── utils/
+│           └── utils.py            # Shared utility functions and helpers
+│
+└── README.md                         # Project documentation
+```
+
+
+

gurrt-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "gurrt"
+version = "0.1.0"
+description = "An Intelligent Open-Source Video Understanding System A different path from traditional Large Video Language Models (LVLMs). Built for modularity, openness, and real-world usability."
+authors = [
+    {name="Mohammad Owais", email = "owaismohammad2515@gmail.com"},
+    {name= "Fareha Aslam", email = "farehaaslam57@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+dependencies = [
+    "torch",
+    "torchvision",
+    "torchaudio",
+    "opencv-python>=4.13.0.92",
+    "python-dotenv>=1.2.1",
+    "transformers>=5.1.0",
+    "accelerate>=1.12.0",
+    "pillow>=12.1.0",
+    "chromadb>=1.4.1",
+    "ollama>=0.6.1",
+    "langchain>=1.2.9",
+    "langchain-groq>=1.1.2",
+    "moviepy>=1.0.3",
+    "sentence-transformers>=5.2.2",
+    "tqdm>=4.67.3",
+    "scenedetect>=0.6.7.1",
+    "scikit-image>=0.26.0",
+    "ipykernel>=7.2.0",
+    "easyocr>=1.7.2",
+    "yt-dlp>=2026.2.4",
+    "openai-whisper>=20250625",
+    "faster-whisper>=1.2.1",
+    "langchain-text-splitters>=1.1.0",
+    "fastapi>=0.128.7",
+    "pydantic>=2.12.5",
+    "supermemory>=3.24.0",
+    "platformdirs>=4.5.1",
+    "typer>=0.21.1",
+    "alive-progress>=3.3.0",
+]   
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+
+[[tool.uv.index]]
+name = "pytorch-cu121"
+url = "https://download.pytorch.org/whl/cu121"
+explicit = true
+
+[tool.uv.sources]
+torch = { index = "pytorch-cu121" }
+torchvision = { index = "pytorch-cu121" }
+torchaudio = { index = "pytorch-cu121" }
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "build>=1.4.0",
+    "twine>=6.2.0",
+]
+
+[project.scripts]
+gurrt = "gurrt.cli.main:app"
+

gurrt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gurrt-0.1.0/src/gurrt/api/server.py

@@ -0,0 +1,105 @@
+from typing import Annotated
+from fastapi import FastAPI, status
+from fastapi.responses import JSONResponse
+from gurrt.core.llm import query_llm, delete
+from pydantic import Field
+import subprocess
+
+app = FastAPI(title= "Video-Amigo")
+
+   
+@app.get('/save_models')
+async def save_models() -> JSONResponse:
+    try:
+        result = subprocess.run(["python", r"core\models.py"],
+                                capture_output= True,
+                                check= True,
+                                text= True)
+        return JSONResponse(status_code=status.HTTP_200_OK, 
+                            content={"message": "Resource Saved Successfully!",
+                                     "output": result.stdout} )
+    except subprocess.CalledProcessError as e:
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "message": "Script execution failed",
+                "error": e.stderr
+            }
+        )
+
+@app.get('/create_vectordb')
+async def vectordb_creation() -> JSONResponse:
+    try:
+        vector_db_creation = subprocess.run(["python", r"core\vectordb.py"],
+                                capture_output= True,
+                                check= True,
+                                text= True)
+        
+    except subprocess.CalledProcessError as e:
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "message": "Script execution failed",
+                "error": e.stderr
+            }
+        )
+    return JSONResponse(status_code=status.HTTP_200_OK, 
+                            content={"message": "Resource Saved Successfully!",
+                                     "frame_output": vector_db_creation.stdout})
+
+@app.get('/upload_video')
+async def video_save_caption_emb(video: Annotated[str, Field(description= "Recieve Video Path")]) -> JSONResponse:
+    try:
+        result_frame = subprocess.run(["python", r"core\embedding.py"],
+                                capture_output= True,
+                                check= True,
+                                text= True)
+        
+    except subprocess.CalledProcessError as e:
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "message": "Script execution failed",
+                "error": e.stderr
+            }
+        )
+    
+    try:
+        result_audio = subprocess.run(["python", r"core\asr.py"],
+                                capture_output= True,
+                                check= True,
+                                text= True)
+        
+    except subprocess.CalledProcessError as e:
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "message": "Script execution failed",
+                "error": e.stderr
+            }
+        )
+    
+    return JSONResponse(status_code=status.HTTP_200_OK, 
+                            content={"message": "Resource Saved Successfully!",
+                                     "frame_output": result_frame.stdout,
+                                     "audio_output": result_audio.stdout} )
+
+@app.get("/llm_chat")
+async def chat(query: str) -> str:
+    answer = await query_llm(query= query)
+    return answer
+
+@app.get("/delete_chat")
+async def delete_chat() -> JSONResponse:
+    try: 
+        delete()
+        return JSONResponse(status_code=status.HTTP_200_OK, 
+                            content={"message": "Memory Deleted Successfully!"} )
+    except Exception as e:
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "message": "Script execution failed",
+                "error": e
+            }
+        )

gurrt-0.1.0/src/gurrt/cli/main.py

@@ -0,0 +1,171 @@
+import os
+import logging
+
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+
+logging.disable(logging.WARNING)
+
+import typer
+from pathlib import Path
+from platformdirs import user_config_dir
+import json
+import asyncio
+from gurrt.core.pipeline import VideoRag
+
+from rich.theme import Theme
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.text import Text
+from rich.rule import Rule
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn
+
+custom_theme = Theme({
+    "primary": "bold green",
+    "success": "bold bright_green",
+    "error": "bold red",
+    "info": "green",
+    "warning": "yellow"
+})
+
+console = Console(theme= custom_theme)
+
+
+app = typer.Typer(help= "🌿 gurrt: A Video Understanding Tool")
+
+config_dir = Path(user_config_dir("gurrt"))
+config_dir.mkdir(exist_ok= True, parents= True)
+
+
+@app.callback()
+def main():
+    title = Text("🌿 Gurrt: A Video Understanding Tool", style="bold bright_green")
+    console.print(Rule(title, style="green"))
+@app.command()
+def init():
+    """
+    Initialize VideoRag by saving required API keys.
+    """
+    groq_link = "https://console.groq.com/docs/models"
+    ollama_link = "https://docs.ollama.com/api/introduction"
+    supermemory_link = "https://supermemory.ai/docs/integrations/supermemory-sdk"
+    config_file = config_dir / "config.json"
+    console.print(
+        Panel(
+            "[info]Get your Groq API Key here:\n[/info]"
+            f"[bold green]{groq_link}[/bold green]",
+            title="Groq",
+            border_style="green"
+        )
+    )
+    groq = Prompt.ask("[info]Enter Groq API Key[/info]", password=True)
+    
+    console.print(
+        Panel(
+            "[info]Get your Supermemory API Key here:\n[/info]"
+            f"[bold green]{supermemory_link}[/bold green]",
+            title="Supermemory",
+            border_style="green"
+        )
+    )
+    supermemory = Prompt.ask("[primary]Enter Supermemory API Key[/primary]", password=True)
+
+    
+    console.print(
+        Panel(
+            "[info]Ollama Setup Guide:\n[/info]"
+            f"[bold green]{ollama_link}[/bold green]",
+            title="Ollama",
+            border_style="green"
+        )
+    )
+    ollama = Prompt.ask("[info]Enter Ollama API Key[/info]", password=True)
+    
+    with open(config_file, "w") as f:
+        json.dump({
+            "GROQ_API_KEY": groq,
+            "SUPERMEMORY_API_KEY": supermemory,
+            "OLLAMA_API_KEY": ollama
+        }, f, indent= 2)
+        
+    console.print(
+        Panel(
+        "[success]✔ Configuration saved successfully![/success]"
+        f"[success]saved at {config_file} [/success]",
+        border_style= "green"
+        ))
+        
+    
+@app.command()
+def models_download():
+    """
+    Download and cache all required AI models locally.
+    """
+    cache_dir = config_dir /"models"
+    cache_dir.mkdir(exist_ok= True, parents= True)
+
+    console.print(
+        Panel(
+            "[primary]Downloading Models[/primary]",
+            border_style="green"
+        )
+    )
+    from gurrt.core.models import download_models
+    with Progress(
+        SpinnerColumn(style="green"),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(bar_width=None, style="green"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("[info]Downloading models...", total=100)
+        download_models(cache_dir)
+        progress.update(task, completed=100)
+
+    console.print("[success]✔ Models cached successfully![/success]")
+
+
+
+@app.command()
+def index(video_path):
+    """
+    Index a video by extracting frames and audio for retrieval.
+    """
+    console.print(
+        Panel(
+            f"[primary]Indexing Video[/primary]\n[info]{video_path}[/info]",
+            border_style="green"
+        )
+    )
+    rag = VideoRag()
+    rag.index_video(video_path=video_path)
+    
+    with console.status("[info]Processing audio transcription...[/info]", spinner="dots"):
+        rag.index_audio(video_path=video_path)
+    
+    console.print(Panel(
+            "[success]✔ Video indexed successfully![/success]"
+            "[success]You may start asking your queries![/success]",
+            border_style="green"
+        ))
+    
+@app.command(help = "Ask a question about an indexed video.")
+def ask(query:str):
+    """
+    Ask a question about an indexed video.
+    """
+    rag = VideoRag()
+    
+    
+    with console.status("[info]Thinking...[/info]", spinner="dots"):
+        response = asyncio.run(rag.ask(query= query))
+    console.print(
+        Panel(
+            response,
+            title="[success]Answer[/success]",
+            border_style="green"
+        )
+    )
+        
+if __name__ == "__main__":
+    app()

gurrt-0.1.0/src/gurrt/config/config.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+from platformdirs import user_config_dir
+import json
+
+class Settings:
+    def __init__(self):
+        home = Path(user_config_dir("gurrt"))
+        home.mkdir(exist_ok=True, parents= True)
+        
+        config_file = home / "config.json"
+        cfg = {}
+        
+        if config_file.exists():
+            with open(config_file) as f:
+                cfg = json.load(f)
+            self.GROQ_API_KEY = cfg.get('GROQ_API_KEY')
+            self.SUPERMEMORY_API_KEY = cfg.get("SUPERMEMORY_API_KEY")
+        else:
+            raise RuntimeError("API Keys not found")
+        self.CLIP_MODEL = "openai/clip-vit-base-patch32"
+        self.LLM_MODEL="llama-3.1-8b-instant"
+        self.RERANKER_MODEL = 'cross-encoder/ms-marco-MiniLM-L-6-v2'
+        self.BLIP_MODEL = "Salesforce/blip-image-captioning-large"
+        self.WHISPER_MODEL = "large-v2"
+
+        self.MODEL_CACHE_DIR = home / "models"
+        self.CHROMA_DB_PATH= home / "chroma_db"
+        self.AUDIO_PATH = home / "output.mp3"