acuity-framework 1.0.0__py3-none-any.whl

acuity/recommendation/__init__.py

@@ -0,0 +1,16 @@
+"""
+ACUITY Framework — Recommender Module
+
+Recommendation engine using TF-IDF, cosine similarity, and Haversine
+proximity ranking to match user queries with local business profiles.
+
+Quick Start:
+    >>> from acuity.recommendation import RecommendationEngine
+    >>> engine = RecommendationEngine()
+    >>> engine.set_profiles([{"name": "Juan's Bakery", "description": "Fresh bread daily"}])
+    >>> results = engine.recommend("bakery")
+"""
+
+from .engine import RecommendationEngine
+
+__all__ = ["RecommendationEngine"]

acuity/recommendation/engine.py

@@ -0,0 +1,138 @@
+"""
+ACUITY Framework — Recommendation Engine
+
+Main orchestrator that combines textual relevance (TF-IDF + cosine)
+with geographic proximity (Haversine) to produce ranked results.
+
+Usage:
+    >>> from acuity.recommendation import RecommendationEngine
+    >>> engine = RecommendationEngine()
+    >>> engine.set_profiles([
+    ...     {"name": "Juan's Bakery", "description": "Fresh bread and pastries daily"},
+    ...     {"name": "JC Auto Repair", "description": "Vulcanizing and oil change"},
+    ... ])
+    >>> results = engine.recommend(query="bakery", user_lat=14.25, user_lon=121.10)
+"""
+from __future__ import annotations
+
+import json
+
+from .vectorizer import build_tfidf_matrix, transform_query
+from .similarity import compute_cosine_scores
+from .proximity import haversine_distance
+from .ranker import rank_results
+from ..config import AcuityConfig
+
+
+class RecommendationEngine:
+    """End-to-end recommendation engine for ACUITY.
+
+    Combines TF-IDF text similarity with Haversine geographic proximity
+    to rank business profiles against user queries.
+
+    Args:
+        config: An ``AcuityConfig`` instance. If ``None``, uses defaults.
+        relevance_weight: Override the config's relevance weight.
+        proximity_weight: Override the config's proximity weight.
+    """
+
+    def __init__(
+        self,
+        config: AcuityConfig | None = None,
+        relevance_weight: float | None = None,
+        proximity_weight: float | None = None,
+    ):
+        self.config = config or AcuityConfig()
+        self.profiles: list[dict] = []
+        self.relevance_weight = relevance_weight if relevance_weight is not None else self.config.relevance_weight
+        self.proximity_weight = proximity_weight if proximity_weight is not None else self.config.proximity_weight
+        self._tfidf_matrix = None
+        self._vectorizer = None
+
+    def set_profiles(self, profiles: list[dict]) -> None:
+        """Load business profiles from an in-memory list.
+
+        Accepts profiles with any combination of the following keys:
+        ``name``, ``business_name``, ``description``, ``categories``, ``services``.
+
+        Args:
+            profiles: List of business profile dictionaries.
+        """
+        self.profiles = profiles
+        # Build TF-IDF matrix from profile text fields
+        texts = []
+        for p in self.profiles:
+            name = p.get("name") or p.get("business_name") or ""
+            desc = p.get("description") or ""
+            cats = " ".join(p.get("categories") or [])
+            srvs = " ".join(p.get("services") or [])
+
+            texts.append(f"{name} {desc} {cats} {srvs}")
+        self._vectorizer, self._tfidf_matrix = build_tfidf_matrix(texts)
+        print(f"Loaded {len(self.profiles)} profiles. TF-IDF matrix built.")
+
+    def load_profiles(self, path: str) -> None:
+        """Load business profiles from a JSON file.
+
+        Args:
+            path: Path to a JSON file containing a list of profile dicts.
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        self.set_profiles(data)
+
+    def recommend(
+        self,
+        query: str,
+        user_lat: float | None = None,
+        user_lon: float | None = None,
+        top_k: int | None = None,
+    ) -> list[dict]:
+        """Return top-k ranked business profiles for *query*.
+
+        Args:
+            query: User's search query text.
+            user_lat: User's latitude (optional, for proximity scoring).
+            user_lon: User's longitude (optional, for proximity scoring).
+            top_k: Number of results to return. Defaults to ``config.default_top_k``.
+
+        Returns:
+            List of profile dicts augmented with ``relevance_score``,
+            ``distance_km``, ``proximity_score``, and ``final_score``.
+        """
+        if top_k is None:
+            top_k = self.config.default_top_k
+
+        if not self.profiles or self._tfidf_matrix is None or self._vectorizer is None:
+            return []
+
+        # Textual relevance
+        query_vec = transform_query(self._vectorizer, query)
+        cosine_scores = compute_cosine_scores(self._tfidf_matrix, query_vec)
+
+        # Proximity (if user location provided)
+        distances: list[float | None] = []
+        if user_lat is not None and user_lon is not None:
+            for profile in self.profiles:
+                biz_lat = profile.get("latitude")
+                biz_lon = profile.get("longitude")
+                if biz_lat is not None and biz_lon is not None:
+                    distances.append(
+                        haversine_distance(user_lat, user_lon, biz_lat, biz_lon)
+                    )
+                else:
+                    distances.append(None)
+        else:
+            distances = [None] * len(self.profiles)
+
+        # Combine & rank
+        results = rank_results(
+            profiles=self.profiles,
+            cosine_scores=cosine_scores,
+            distances=distances,
+            relevance_weight=self.relevance_weight,
+            proximity_weight=self.proximity_weight,
+            top_k=top_k,
+        )
+
+        return results

acuity/recommendation/proximity.py

@@ -0,0 +1,35 @@
+"""
+ACUITY Framework — Haversine Proximity
+
+Calculates geographic distance between two coordinate pairs using the
+Haversine formula for great-circle distance on a sphere.
+Used for proximity-based ranking of businesses relative to the user.
+"""
+import math
+
+# Earth's mean radius in kilometres
+EARTH_RADIUS_KM = 6371.0
+
+
+def haversine_distance(
+    lat1: float, lon1: float,
+    lat2: float, lon2: float,
+) -> float:
+    """Return the great-circle distance (km) between two lat/lon points.
+
+    Args:
+        lat1, lon1: User's coordinates (decimal degrees).
+        lat2, lon2: Business's coordinates (decimal degrees).
+
+    Returns:
+        Distance in kilometres.
+    """
+    lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])
+
+    dlat = lat2 - lat1
+    dlon = lon2 - lon1
+
+    a = math.sin(dlat / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
+    c = 2 * math.asin(math.sqrt(a))
+
+    return EARTH_RADIUS_KM * c

acuity/recommendation/ranker.py

@@ -0,0 +1,61 @@
+"""
+ACUITY Framework — Combined Ranker
+
+Merges textual relevance scores and proximity distances into a single
+ranking, using a configurable weighting scheme.
+"""
+from __future__ import annotations
+
+
+def rank_results(
+    profiles: list[dict],
+    cosine_scores: list[float],
+    distances: list[float | None],
+    relevance_weight: float = 0.6,
+    proximity_weight: float = 0.4,
+    top_k: int = 10,
+) -> list[dict]:
+    """Produce a ranked list of business profiles.
+
+    The final score is a weighted combination of:
+        - Textual relevance  (cosine similarity, higher = better)
+        - Proximity score    (inverse distance, closer = better)
+
+    Args:
+        profiles: List of business profile dicts.
+        cosine_scores: List of cosine similarity values per profile.
+        distances: List of distances in km (``None`` if unavailable).
+        relevance_weight: Weight for textual relevance [0, 1].
+        proximity_weight: Weight for proximity [0, 1].
+        top_k: How many results to return.
+
+    Returns:
+        Sorted list of profile dicts with added scoring fields:
+        ``relevance_score``, ``distance_km``, ``proximity_score``, ``final_score``.
+    """
+    scored: list[dict] = []
+
+    for i, profile in enumerate(profiles):
+        relevance = float(cosine_scores[i])
+
+        dist = distances[i]
+        if dist is not None:
+            # Inverse distance proximity score (1.0 = 0 km away)
+            proximity_score = 1.0 / (1.0 + dist)
+        else:
+            proximity_score = 0.0
+
+        final_score = (relevance_weight * relevance) + (proximity_weight * proximity_score)
+
+        scored.append({
+            **profile,
+            "relevance_score": round(float(relevance), 4),
+            "distance_km": round(float(dist), 2) if dist is not None else None,
+            "proximity_score": round(float(proximity_score), 4),
+            "final_score": round(float(final_score), 4),
+        })
+
+    # Sort descending by final score
+    scored.sort(key=lambda x: x["final_score"], reverse=True)
+
+    return list(scored[:top_k])

acuity/recommendation/similarity.py

@@ -0,0 +1,48 @@
+"""
+ACUITY Framework — Cosine Similarity
+
+Computes relevance scores between a user query vector and the
+TF-IDF business profile vectors using pure Python.
+"""
+from __future__ import annotations
+
+import math
+
+
+def compute_cosine_scores(
+    tfidf_matrix: list[dict[str, float]],
+    query_vec: list[dict[str, float]],
+) -> list[float]:
+    """Return a list of cosine similarity scores for every profile.
+
+    Args:
+        tfidf_matrix: List of sparse dictionary vectors representing profiles.
+        query_vec: List containing one sparse dictionary vector for the user query.
+
+    Returns:
+        List of similarity scores in [0, 1].
+    """
+    if not query_vec:
+        return [0.0] * len(tfidf_matrix)
+
+    query = query_vec[0]
+    query_mag = math.sqrt(sum(val ** 2 for val in query.values()))
+
+    if query_mag == 0:
+        return [0.0] * len(tfidf_matrix)
+
+    scores = []
+    for vector in tfidf_matrix:
+        dot_product = 0.0
+        for term, weight in query.items():
+            if term in vector:
+                dot_product += weight * vector[term]
+
+        doc_mag = math.sqrt(sum(val ** 2 for val in vector.values()))
+
+        if doc_mag == 0:
+            scores.append(0.0)
+        else:
+            scores.append(dot_product / (query_mag * doc_mag))
+
+    return scores

acuity/recommendation/vectorizer.py

@@ -0,0 +1,174 @@
+"""
+ACUITY Framework — TF-IDF Vectorizer
+
+Converts business profile descriptions (and user queries) into
+TF-IDF feature vectors for similarity computation using pure Python.
+No external dependencies (no scikit-learn, no numpy).
+"""
+from __future__ import annotations
+
+import math
+import re
+from collections import defaultdict
+
+# Standard English stop words
+STOP_WORDS = set([
+    "i", "me", "my", "myself", "we", "our", "ours", "ourselves", "you", "your",
+    "yours", "yourself", "yourselves", "he", "him", "his", "himself", "she",
+    "her", "hers", "herself", "it", "its", "itself", "they", "them", "their",
+    "theirs", "themselves", "what", "which", "who", "whom", "this", "that",
+    "these", "those", "am", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "having", "do", "does", "did", "doing", "a", "an",
+    "the", "and", "but", "if", "or", "because", "as", "until", "while", "of",
+    "at", "by", "for", "with", "about", "against", "between", "into", "through",
+    "during", "before", "after", "above", "below", "to", "from", "up", "down",
+    "in", "out", "on", "off", "over", "under", "again", "further", "then",
+    "once", "here", "there", "when", "where", "why", "how", "all", "any",
+    "both", "each", "few", "more", "most", "other", "some", "such", "no",
+    "nor", "not", "only", "own", "same", "so", "than", "too", "very", "s",
+    "t", "can", "will", "just", "don", "should", "now"
+])
+
+
+class CustomTfidfVectorizer:
+    """Pure-Python TF-IDF vectorizer with n-gram support.
+
+    This implementation requires no external dependencies and produces
+    sparse dictionary-based vectors for memory efficiency.
+
+    Args:
+        ngram_range: Tuple of (min_n, max_n) for n-gram extraction.
+    """
+
+    def __init__(self, ngram_range: tuple[int, int] = (1, 2)):
+        self.ngram_range = ngram_range
+        self.idf_weights: dict[str, float] = {}
+        self.vocabulary: set[str] = set()
+        self.n_documents: int = 0
+
+    def _tokenize_and_ngrams(self, text: str) -> list[str]:
+        """Tokenize text and generate n-grams."""
+        text = text.lower()
+        tokens = re.findall(r'\b[a-z0-9]+\b', text)
+
+        # Remove stop words
+        tokens = [t for t in tokens if t not in STOP_WORDS]
+
+        ngrams = []
+        min_n, max_n = self.ngram_range
+
+        # Unigrams
+        if min_n <= 1:
+            ngrams.extend(tokens)
+
+        # Bigrams, Trigrams, etc.
+        for n in range(max(2, min_n), max_n + 1):
+            for i in range(len(tokens) - n + 1):
+                ngram = " ".join(tokens[i:i + n])
+                ngrams.append(ngram)
+
+        return ngrams
+
+    def fit_transform(self, documents: list[str]) -> list[dict[str, float]]:
+        """Fit the vectorizer on *documents* and return their TF-IDF vectors.
+
+        Args:
+            documents: List of text strings.
+
+        Returns:
+            List of sparse TF-IDF vectors (dicts mapping terms to weights).
+        """
+        self.n_documents = len(documents)
+        document_term_counts = []
+        doc_frequency: dict[str, int] = defaultdict(int)
+
+        # Stage 1: Tokenize and compute term frequencies per document
+        for doc in documents:
+            tokens = self._tokenize_and_ngrams(doc)
+            term_counts: dict[str, int] = defaultdict(int)
+            for token in tokens:
+                term_counts[token] += 1
+
+            document_term_counts.append(term_counts)
+
+            # Count document frequency
+            for unique_term in set(tokens):
+                doc_frequency[unique_term] += 1
+                self.vocabulary.add(unique_term)
+
+        # Stage 2: Compute IDF weights
+        for term, df in doc_frequency.items():
+            self.idf_weights[term] = math.log(self.n_documents / df)
+
+        # Stage 3: Compute TF-IDF vectors
+        tfidf_vectors = []
+        for term_counts in document_term_counts:
+            vector = {}
+            for term, count in term_counts.items():
+                if count > 0:
+                    tf = 1.0 + math.log(count)
+                    vector[term] = tf * self.idf_weights[term]
+            tfidf_vectors.append(vector)
+
+        return tfidf_vectors
+
+    def transform(self, documents: list[str], partial_match: bool = False) -> list[dict[str, float]]:
+        """Transform new documents into the fitted TF-IDF space.
+
+        Args:
+            documents: List of text strings to transform.
+            partial_match: If True, enable bi-directional prefix matching
+                (e.g., "print" matches "printing" and vice versa).
+
+        Returns:
+            List of sparse TF-IDF vectors.
+        """
+        tfidf_vectors = []
+        for doc in documents:
+            tokens = self._tokenize_and_ngrams(doc)
+            term_counts: dict[str, int] = defaultdict(int)
+            for token in tokens:
+                if token in self.vocabulary:
+                    term_counts[token] += 1
+
+                # Bi-directional prefix matching
+                if partial_match and len(token) >= 3:
+                    for vocab_term in self.vocabulary:
+                        if vocab_term != token and (vocab_term.startswith(token) or token.startswith(vocab_term)):
+                            term_counts[vocab_term] += 1
+
+            vector = {}
+            for term, count in term_counts.items():
+                if count > 0:
+                    tf = 1.0 + math.log(count)
+                    vector[term] = tf * self.idf_weights[term]
+            tfidf_vectors.append(vector)
+
+        return tfidf_vectors
+
+
+def build_tfidf_matrix(documents: list[str]) -> tuple[CustomTfidfVectorizer, list[dict[str, float]]]:
+    """Fit a custom TF-IDF vectorizer on *documents* and return the vectors.
+
+    Args:
+        documents: List of text strings.
+
+    Returns:
+        Tuple of (vectorizer, tfidf_vectors).
+    """
+    vectorizer = CustomTfidfVectorizer(ngram_range=(1, 2))
+    tfidf_matrix = vectorizer.fit_transform(documents)
+    return vectorizer, tfidf_matrix
+
+
+def transform_query(vectorizer: CustomTfidfVectorizer, query: str) -> list[dict[str, float]]:
+    """Transform a user query string into the fitted TF-IDF vector space.
+
+    Args:
+        vectorizer: A fitted ``CustomTfidfVectorizer``.
+        query: The user's search query text.
+
+    Returns:
+        List containing one sparse TF-IDF vector for the query.
+    """
+    return vectorizer.transform([query], partial_match=True)

acuity/scraper/__init__.py

@@ -0,0 +1,16 @@
+"""
+ACUITY Framework — Scraper Module
+
+Data collection from Facebook community groups using undetected_chromedriver.
+
+Requires the ``scraper`` extra: ``pip install acuity-framework[scraper]``
+
+Quick Start:
+    >>> from acuity.scraper import FacebookScraper
+    >>> scraper = FacebookScraper()
+    >>> posts = scraper.run(["https://facebook.com/groups/example"])
+"""
+
+from .scraper import FacebookScraper
+
+__all__ = ["FacebookScraper"]