georag 0.1.0__tar.gz

georag-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: georag
+Version: 0.1.0
+Summary: Spatial-Semantic Retrieval Augmented Generation framework
+Author-email: Developer <makindeadedeji500@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: django>=4.2
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: numpy>=1.24
+
+# georag

georag-0.1.0/README.md

@@ -0,0 +1 @@
+# georag

georag-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "georag"
+version = "0.1.0"
+description = "Spatial-Semantic Retrieval Augmented Generation framework"
+readme = "README.md"
+authors = [
+    { name = "Developer", email = "makindeadedeji500@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "django>=4.2",
+    "scikit-learn>=1.3.0",
+    "psycopg2-binary>=2.9",
+    "numpy>=1.24"
+]

georag-0.1.0/setup.cfg

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

georag-0.1.0/src/georag/__init__.py

@@ -0,0 +1,54 @@
+from typing import Dict, Any
+from .parsers import GeoParser
+from .retrievers import SpatialVectorRetriever
+from .cluster import SpatialRouter
+
+class GeoRAGPipeline:
+    """
+    The main orchestration engine for the GeoRAG framework.
+    """
+    def __init__(self, chunk_model, max_clusters: int = 3):
+        self.chunk_model = chunk_model
+        self.retriever = SpatialVectorRetriever(chunk_model)
+        self.router = SpatialRouter(max_clusters=max_clusters)
+
+    def generate_context(
+        self, 
+        query_embedding: list[float], 
+        target_longitude: float, 
+        target_latitude: float, 
+        radius_km: float, 
+        top_k: int = 10
+    ) -> str:
+        """
+        Executes the full pipeline and formats the results into an LLM-ready context string.
+        """
+        # 1. Parse coordinates into PostGIS format
+        target_point = GeoParser.point_from_coords(target_longitude, target_latitude)
+        
+        # 2. Run the two-pass spatial-semantic search
+        results = self.retriever.hybrid_search(
+            query_embedding=query_embedding,
+            target_point=target_point,
+            radius_km=radius_km,
+            top_k=top_k
+        )
+        
+        # 3. Route and cluster the data geographically
+        clustered_data = self.router.cluster_results(results)
+        
+        # 4. Synthesize the context string
+        if not clustered_data:
+            return "No relevant geospatial data found for this query."
+            
+        context_string = "Geospatial Data Context:\n"
+        for region_id, data in clustered_data.items():
+            lon, lat = data['centroid_lon_lat']
+            context_string += f"\n--- {region_id} (Approx. Center: {lon:.4f} Lon, {lat:.4f} Lat) ---\n"
+            for excerpt in data['excerpts']:
+                context_string += f"- {excerpt}\n"
+                
+        return context_string
+
+# Expose key components at the package level
+__all__ = ['GeoRAGPipeline', 'GeoParser']

georag-0.1.0/src/georag/cluster.py

@@ -0,0 +1,47 @@
+import numpy as np
+from sklearn.cluster import KMeans
+
+class SpatialRouter:
+    """
+    Groups retrieved geographic chunks into logical spatial clusters 
+    to provide structured context for the LLM.
+    """
+    def __init__(self, max_clusters: int = 3):
+        self.max_clusters = max_clusters
+
+    def cluster_results(self, chunks) -> dict:
+        """
+        Takes a QuerySet of retrieved chunk objects and groups them geographically.
+        Returns a dictionary mapping cluster IDs to their centroid coordinates and text.
+        """
+        # Convert QuerySet to a list to avoid multiple database hits
+        chunk_list = list(chunks)
+        
+        if not chunk_list:
+            return {}
+            
+        # Extract coordinates [longitude, latitude] for the clustering algorithm
+        coords = np.array([[chunk.geometry.x, chunk.geometry.y] for chunk in chunk_list])
+        
+        # We can't have more clusters than we have data points
+        n_clusters = min(self.max_clusters, len(chunk_list))
+        
+        # Initialize and run Scikit-Learn K-Means
+        kmeans = KMeans(n_clusters=n_clusters, random_state=42, n_init=10)
+        labels = kmeans.fit_predict(coords)
+        
+        grouped_data = {}
+        for idx, label in enumerate(labels):
+            cluster_id = f"Region_{label + 1}"
+            
+            if cluster_id not in grouped_data:
+                # Store the geometric center of this cluster
+                centroid = kmeans.cluster_centers_[label].tolist()
+                grouped_data[cluster_id] = {
+                    "centroid_lon_lat": centroid,
+                    "excerpts": []
+                }
+                
+            grouped_data[cluster_id]["excerpts"].append(chunk_list[idx].text)
+            
+        return grouped_data

georag-0.1.0/src/georag/models.py

@@ -0,0 +1,38 @@
+from django.contrib.gis.db import models as gis_models
+from django.db import models
+from pgvector.django import VectorField, HnswIndex
+from django.contrib.postgres.indexes import GistIndex
+
+class GeoRAGDocumentBase(models.Model):
+    """
+    Abstract base model representing a parent document.
+    """
+    title = models.CharField(max_length=255)
+    metadata = models.JSONField(default=dict, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        abstract = True
+
+class GeoRAGChunkBase(models.Model):
+    """
+    Abstract base model representing a text chunk with spatial and semantic data.
+    """
+    text = models.TextField()
+    embedding = VectorField(dimensions=768, null=True, blank=True)
+    geometry = gis_models.GeometryField(srid=4326, null=True, blank=True)
+    
+    class Meta:
+        abstract = True
+        indexes = [
+            # Optimize spatial queries (radius, intersection)
+            GistIndex(fields=['geometry'], name='%(class)s_geom_idx'),
+            # Optimize semantic vector search (cosine distance)
+            HnswIndex(
+                name='%(class)s_vector_idx',
+                fields=['embedding'],
+                m=16,
+                ef_construction=64,
+                opclasses=['vector_cosine_ops']
+            )
+        ]

georag-0.1.0/src/georag/parsers.py

@@ -0,0 +1,42 @@
+import json
+from django.contrib.gis.geos import GEOSGeometry, Point
+
+class GeoParser:
+    """
+    Handles the conversion of raw coordinates or GeoJSON into PostGIS-compatible geometries.
+    """
+    @staticmethod
+    def point_from_coords(longitude: float, latitude: float) -> Point:
+        """
+        Creates a standard PostGIS Point geometry.
+        CRITICAL: In spatial databases, Longitude (X) always comes before Latitude (Y).
+        """
+        # SRID 4326 is the standard GPS coordinate system (WGS 84)
+        return Point(longitude, latitude, srid=4326)
+
+    @staticmethod
+    def parse_geojson(geojson_dict: dict) -> GEOSGeometry:
+        """
+        Converts a standard GeoJSON boundary (like a polygon of an oil spill) into PostGIS geometry.
+        """
+        return GEOSGeometry(json.dumps(geojson_dict))
+
+
+class DocumentChunker:
+    """
+    Splits large documents into smaller chunks for vector embedding, 
+    preparing them to be tagged with spatial metadata.
+    """
+    def __init__(self, chunk_size: int = 250):
+        self.chunk_size = chunk_size
+
+    def chunk_text(self, text: str) -> list[str]:
+        """
+        A robust word-based chunker. 
+        """
+        words = text.split()
+        chunks = []
+        for i in range(0, len(words), self.chunk_size):
+            chunk = " ".join(words[i:i + self.chunk_size])
+            chunks.append(chunk)
+        return chunks

georag-0.1.0/src/georag/retrievers.py

@@ -0,0 +1,36 @@
+from django.contrib.gis.geos import Point
+from django.contrib.gis.measure import Distance
+from pgvector.django import CosineDistance
+from django.db.models import QuerySet
+
+class SpatialVectorRetriever:
+    """
+    Executes the two-pass GeoRAG algorithm combining PostGIS spatial boundaries 
+    with pgvector semantic cosine similarity.
+    """
+    def __init__(self, chunk_model):
+        """
+        Initializes the retriever with the specific Django model to query.
+        """
+        self.chunk_model = chunk_model
+
+    def hybrid_search(
+        self, 
+        query_embedding: list[float], 
+        target_point: Point, 
+        radius_km: float, 
+        top_k: int = 5
+    ) -> QuerySet:
+        """
+        Pass 1: Filter database by geographic radius using GiST indexes.
+        Pass 2: Calculate cosine distance using HNSW indexes on the filtered subset.
+        """
+        return (
+            self.chunk_model.objects
+            # Spatial Pre-Filter: Only keep chunks within the target radius
+            .filter(geometry__distance_lte=(target_point, Distance(km=radius_km)))
+            # Semantic Search: Calculate cosine distance between chunk and query
+            .annotate(semantic_distance=CosineDistance('embedding', query_embedding))
+            # Sort by the most semantically relevant
+            .order_by('semantic_distance')[:top_k]
+        )

georag-0.1.0/src/georag.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: georag
+Version: 0.1.0
+Summary: Spatial-Semantic Retrieval Augmented Generation framework
+Author-email: Developer <makindeadedeji500@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: django>=4.2
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: numpy>=1.24
+
+# georag

georag-0.1.0/src/georag.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/georag/__init__.py
+src/georag/cluster.py
+src/georag/models.py
+src/georag/parsers.py
+src/georag/retrievers.py
+src/georag.egg-info/PKG-INFO
+src/georag.egg-info/SOURCES.txt
+src/georag.egg-info/dependency_links.txt
+src/georag.egg-info/requires.txt
+src/georag.egg-info/top_level.txt

georag-0.1.0/src/georag.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

georag-0.1.0/src/georag.egg-info/requires.txt

@@ -0,0 +1,4 @@
+django>=4.2
+scikit-learn>=1.3.0
+psycopg2-binary>=2.9
+numpy>=1.24

georag-0.1.0/src/georag.egg-info/top_level.txt

@@ -0,0 +1 @@
+georag