acuity-framework 1.0.0__tar.gz

acuity_framework-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ACUITY Research Team
+
+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.

acuity_framework-1.0.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: acuity-framework
+Version: 1.0.0
+Summary: ACUITY — A machine learning framework for extracting, verifying, and recommending local micro-enterprise profiles from unstructured community posts.
+Author: ACUITY Research Team
+License: MIT
+Project-URL: Repository, https://github.com/acuity-framework/acuity-framework
+Project-URL: Documentation, https://github.com/acuity-framework/acuity-framework#readme
+Keywords: nlp,ner,recommendation-engine,tfidf,cosine-similarity,business-extraction,community-posts,micro-enterprise
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: nlp
+Requires-Dist: nltk>=3.8.1; extra == "nlp"
+Provides-Extra: transformers
+Requires-Dist: transformers>=4.35.0; extra == "transformers"
+Requires-Dist: torch>=2.1.0; extra == "transformers"
+Requires-Dist: nltk>=3.8.1; extra == "transformers"
+Provides-Extra: scraper
+Requires-Dist: undetected-chromedriver>=3.5.0; extra == "scraper"
+Requires-Dist: selenium>=4.15.0; extra == "scraper"
+Requires-Dist: python-dotenv>=1.0.0; extra == "scraper"
+Provides-Extra: all
+Requires-Dist: nltk>=3.8.1; extra == "all"
+Requires-Dist: transformers>=4.35.0; extra == "all"
+Requires-Dist: torch>=2.1.0; extra == "all"
+Requires-Dist: undetected-chromedriver>=3.5.0; extra == "all"
+Requires-Dist: selenium>=4.15.0; extra == "all"
+Requires-Dist: python-dotenv>=1.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# ACUITY Framework
+
+**A**utomated **C**ommunity **U**nstructured **I**nformation to **T**argeted visibilit**Y**
+
+A Python machine learning framework for extracting, verifying, and recommending local micro-enterprise profiles from unstructured community posts (e.g., Facebook groups, forums).
+
+---
+
+## 🚀 Installation
+
+```bash
+# Core framework (no heavy dependencies)
+pip install acuity-framework
+
+# With NLP support (nltk for CRF-based NER)
+pip install acuity-framework[nlp]
+
+# With Transformer NER (requires PyTorch)
+pip install acuity-framework[transformers]
+
+# With Facebook scraper
+pip install acuity-framework[scraper]
+
+# Everything
+pip install acuity-framework[all]
+```
+
+### Local Development Install
+
+```bash
+git clone https://github.com/acuity-framework/acuity-framework.git
+cd acuity-framework
+pip install -e ".[dev]"
+```
+
+---
+
+## 📦 Modules
+
+| Module | Description |
+|--------|-------------|
+| `acuity.extraction` | NLP pipeline: preprocessing → NER → rule-based extraction → profile construction |
+| `acuity.recommendation` | TF-IDF + cosine similarity + Haversine proximity ranking |
+| `acuity.verification` | Business legitimacy verification via fuzzy matching (Levenshtein) |
+| `acuity.scraper` | Facebook community group post scraper (optional) |
+
+---
+
+## 🔧 Quick Start
+
+### 1. Extract Business Profiles from Text
+
+```python
+from acuity.extraction import ExtractionPipeline
+
+pipeline = ExtractionPipeline()
+profiles = pipeline.extract_from_texts([
+    "Mang Juan's Bakery sa Mamatid, open 8am-5pm, 0917-123-4567, pandesal ₱5",
+    "JC Auto Repair, vulcanizing, Brgy Banay-Banay, 0918-987-6543",
+])
+
+for p in profiles:
+    print(f"{p['business_name']}: {p['phones']}, {p['hours']}")
+```
+
+### 2. Verify Against a Government Registry
+
+```python
+from acuity.verification import BPLOVerifier
+
+verifier = BPLOVerifier()
+verifier.load_registry_from_list([
+    {"name": "Juan's Bakeshop", "address": "Mamatid"},
+    {"name": "JC Automotive Repair", "address": "Banay-Banay"},
+])
+
+result = verifier.verify("Mang Juan's Bakery")
+print(f"Status: {result['status']}, Score: {result['score']}")
+# Output: Status: Pending Verification, Score: 0.65
+```
+
+### 3. Recommend Businesses
+
+```python
+from acuity.recommendation import RecommendationEngine
+
+engine = RecommendationEngine()
+engine.set_profiles([
+    {"name": "Juan's Bakery", "description": "Fresh bread daily", "latitude": 14.27, "longitude": 121.12},
+    {"name": "Auto Repair", "description": "Vulcanizing and oil change", "latitude": 14.26, "longitude": 121.11},
+])
+
+results = engine.recommend("bakery bread", user_lat=14.27, user_lon=121.12)
+for r in results:
+    print(f"{r['name']}: score={r['final_score']}, dist={r['distance_km']}km")
+```
+
+---
+
+## ⚙️ Configuration
+
+All settings are controlled via the `AcuityConfig` dataclass:
+
+```python
+from acuity.config import AcuityConfig
+
+config = AcuityConfig(
+    # NER settings
+    ner_backend="crf",                    # "crf" or "transformer"
+    ner_model_path="./models/crf.pkl",    # Path to your trained model
+
+    # Recommendation weights
+    relevance_weight=0.6,
+    proximity_weight=0.4,
+    default_top_k=10,
+
+    # Verification thresholds
+    fuzzy_match_threshold_verified=0.8,
+    fuzzy_match_threshold_pending=0.6,
+)
+```
+
+---
+
+## 🌐 Integrating with Your Web Application
+
+ACUITY is framework-agnostic. Here's how to use it with Flask:
+
+```python
+from flask import Flask, request, jsonify
+from acuity.recommendation import RecommendationEngine
+
+app = Flask(__name__)
+engine = RecommendationEngine()
+
+@app.route("/api/recommend")
+def recommend():
+    query = request.args.get("q", "")
+    results = engine.recommend(query)
+    return jsonify(results)
+```
+
+See [`examples/flask_integration.py`](examples/flask_integration.py) for a complete working example.
+
+---
+
+## 🧪 Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## 📁 Project Structure
+
+```
+acuity-framework/
+├── pyproject.toml          # Package configuration
+├── README.md
+├── LICENSE
+├── acuity/
+│   ├── __init__.py         # Public API
+│   ├── config.py           # AcuityConfig dataclass
+│   ├── utils.py            # Levenshtein similarity utilities
+│   ├── extraction/         # NLP extraction pipeline
+│   │   ├── pipeline.py     # ExtractionPipeline class
+│   │   ├── preprocessing.py
+│   │   ├── ner_crf.py
+│   │   ├── ner_transformer.py
+│   │   ├── rules.py
+│   │   └── postprocessing.py
+│   ├── recommendation/     # Recommendation engine
+│   │   ├── engine.py       # RecommendationEngine class
+│   │   ├── vectorizer.py   # TF-IDF vectorizer
+│   │   ├── similarity.py   # Cosine similarity
+│   │   ├── proximity.py    # Haversine distance
+│   │   └── ranker.py       # Combined ranking
+│   ├── verification/       # Business verification
+│   │   └── bplo.py         # BPLOVerifier class
+│   └── scraper/            # Facebook scraper (optional)
+│       ├── scraper.py      # FacebookScraper class
+│       └── utils.py
+├── examples/
+│   ├── basic_extraction.py
+│   ├── basic_recommendation.py
+│   └── flask_integration.py
+└── tests/
+    ├── test_extraction.py
+    ├── test_recommendation.py
+    └── test_verification.py
+```
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+## 🎓 Academic Reference
+
+This framework was developed as part of an academic thesis at the College of Computing Studies. The core algorithms implement:
+
+- **TF-IDF Vectorization** with log-normalised term frequency and inverse document frequency
+- **Cosine Similarity** for textual relevance scoring
+- **Haversine Formula** for geographic proximity computation
+- **CRF (Conditional Random Field)** for Named Entity Recognition with BIO tagging
+- **Levenshtein Distance** for fuzzy string matching in business verification

acuity_framework-1.0.0/README.md

@@ -0,0 +1,211 @@
+# ACUITY Framework
+
+**A**utomated **C**ommunity **U**nstructured **I**nformation to **T**argeted visibilit**Y**
+
+A Python machine learning framework for extracting, verifying, and recommending local micro-enterprise profiles from unstructured community posts (e.g., Facebook groups, forums).
+
+---
+
+## 🚀 Installation
+
+```bash
+# Core framework (no heavy dependencies)
+pip install acuity-framework
+
+# With NLP support (nltk for CRF-based NER)
+pip install acuity-framework[nlp]
+
+# With Transformer NER (requires PyTorch)
+pip install acuity-framework[transformers]
+
+# With Facebook scraper
+pip install acuity-framework[scraper]
+
+# Everything
+pip install acuity-framework[all]
+```
+
+### Local Development Install
+
+```bash
+git clone https://github.com/acuity-framework/acuity-framework.git
+cd acuity-framework
+pip install -e ".[dev]"
+```
+
+---
+
+## 📦 Modules
+
+| Module | Description |
+|--------|-------------|
+| `acuity.extraction` | NLP pipeline: preprocessing → NER → rule-based extraction → profile construction |
+| `acuity.recommendation` | TF-IDF + cosine similarity + Haversine proximity ranking |
+| `acuity.verification` | Business legitimacy verification via fuzzy matching (Levenshtein) |
+| `acuity.scraper` | Facebook community group post scraper (optional) |
+
+---
+
+## 🔧 Quick Start
+
+### 1. Extract Business Profiles from Text
+
+```python
+from acuity.extraction import ExtractionPipeline
+
+pipeline = ExtractionPipeline()
+profiles = pipeline.extract_from_texts([
+    "Mang Juan's Bakery sa Mamatid, open 8am-5pm, 0917-123-4567, pandesal ₱5",
+    "JC Auto Repair, vulcanizing, Brgy Banay-Banay, 0918-987-6543",
+])
+
+for p in profiles:
+    print(f"{p['business_name']}: {p['phones']}, {p['hours']}")
+```
+
+### 2. Verify Against a Government Registry
+
+```python
+from acuity.verification import BPLOVerifier
+
+verifier = BPLOVerifier()
+verifier.load_registry_from_list([
+    {"name": "Juan's Bakeshop", "address": "Mamatid"},
+    {"name": "JC Automotive Repair", "address": "Banay-Banay"},
+])
+
+result = verifier.verify("Mang Juan's Bakery")
+print(f"Status: {result['status']}, Score: {result['score']}")
+# Output: Status: Pending Verification, Score: 0.65
+```
+
+### 3. Recommend Businesses
+
+```python
+from acuity.recommendation import RecommendationEngine
+
+engine = RecommendationEngine()
+engine.set_profiles([
+    {"name": "Juan's Bakery", "description": "Fresh bread daily", "latitude": 14.27, "longitude": 121.12},
+    {"name": "Auto Repair", "description": "Vulcanizing and oil change", "latitude": 14.26, "longitude": 121.11},
+])
+
+results = engine.recommend("bakery bread", user_lat=14.27, user_lon=121.12)
+for r in results:
+    print(f"{r['name']}: score={r['final_score']}, dist={r['distance_km']}km")
+```
+
+---
+
+## ⚙️ Configuration
+
+All settings are controlled via the `AcuityConfig` dataclass:
+
+```python
+from acuity.config import AcuityConfig
+
+config = AcuityConfig(
+    # NER settings
+    ner_backend="crf",                    # "crf" or "transformer"
+    ner_model_path="./models/crf.pkl",    # Path to your trained model
+
+    # Recommendation weights
+    relevance_weight=0.6,
+    proximity_weight=0.4,
+    default_top_k=10,
+
+    # Verification thresholds
+    fuzzy_match_threshold_verified=0.8,
+    fuzzy_match_threshold_pending=0.6,
+)
+```
+
+---
+
+## 🌐 Integrating with Your Web Application
+
+ACUITY is framework-agnostic. Here's how to use it with Flask:
+
+```python
+from flask import Flask, request, jsonify
+from acuity.recommendation import RecommendationEngine
+
+app = Flask(__name__)
+engine = RecommendationEngine()
+
+@app.route("/api/recommend")
+def recommend():
+    query = request.args.get("q", "")
+    results = engine.recommend(query)
+    return jsonify(results)
+```
+
+See [`examples/flask_integration.py`](examples/flask_integration.py) for a complete working example.
+
+---
+
+## 🧪 Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## 📁 Project Structure
+
+```
+acuity-framework/
+├── pyproject.toml          # Package configuration
+├── README.md
+├── LICENSE
+├── acuity/
+│   ├── __init__.py         # Public API
+│   ├── config.py           # AcuityConfig dataclass
+│   ├── utils.py            # Levenshtein similarity utilities
+│   ├── extraction/         # NLP extraction pipeline
+│   │   ├── pipeline.py     # ExtractionPipeline class
+│   │   ├── preprocessing.py
+│   │   ├── ner_crf.py
+│   │   ├── ner_transformer.py
+│   │   ├── rules.py
+│   │   └── postprocessing.py
+│   ├── recommendation/     # Recommendation engine
+│   │   ├── engine.py       # RecommendationEngine class
+│   │   ├── vectorizer.py   # TF-IDF vectorizer
+│   │   ├── similarity.py   # Cosine similarity
+│   │   ├── proximity.py    # Haversine distance
+│   │   └── ranker.py       # Combined ranking
+│   ├── verification/       # Business verification
+│   │   └── bplo.py         # BPLOVerifier class
+│   └── scraper/            # Facebook scraper (optional)
+│       ├── scraper.py      # FacebookScraper class
+│       └── utils.py
+├── examples/
+│   ├── basic_extraction.py
+│   ├── basic_recommendation.py
+│   └── flask_integration.py
+└── tests/
+    ├── test_extraction.py
+    ├── test_recommendation.py
+    └── test_verification.py
+```
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+## 🎓 Academic Reference
+
+This framework was developed as part of an academic thesis at the College of Computing Studies. The core algorithms implement:
+
+- **TF-IDF Vectorization** with log-normalised term frequency and inverse document frequency
+- **Cosine Similarity** for textual relevance scoring
+- **Haversine Formula** for geographic proximity computation
+- **CRF (Conditional Random Field)** for Named Entity Recognition with BIO tagging
+- **Levenshtein Distance** for fuzzy string matching in business verification

acuity_framework-1.0.0/acuity/__init__.py

@@ -0,0 +1,27 @@
+"""
+ACUITY Framework
+================
+
+**A**utomated **C**ommunity **U**nstructured **I**nformation to **T**argeted visibilit**Y**
+
+A machine learning framework for extracting, verifying, and recommending
+local micro-enterprise profiles from unstructured community posts.
+
+Modules:
+    - acuity.extraction: NLP pipeline (preprocessing → NER → rule-based → profile building)
+    - acuity.recommendation: TF-IDF + cosine similarity + Haversine proximity ranking
+    - acuity.verification: Business legitimacy verification via fuzzy matching against registries
+    - acuity.scraper: Facebook community group post scraper (optional)
+
+Quick Start:
+    >>> from acuity.extraction import ExtractionPipeline
+    >>> from acuity.recommendation import RecommendationEngine
+    >>> from acuity.verification import BPLOVerifier
+"""
+
+__version__ = "1.0.0"
+__author__ = "ACUITY Research Team"
+
+from .config import AcuityConfig
+
+__all__ = ["AcuityConfig"]

acuity_framework-1.0.0/acuity/config.py

@@ -0,0 +1,47 @@
+"""
+ACUITY Framework Configuration
+
+Provides a centralized dataclass for all configurable parameters.
+No hardcoded paths — users supply their own paths and thresholds.
+"""
+from dataclasses import dataclass
+
+
+@dataclass
+class AcuityConfig:
+    """Configuration for the ACUITY framework.
+
+    All paths default to None, requiring the user to set them
+    based on their own project structure.
+
+    Attributes:
+        ner_model_path: Path to a trained NER model (CRF .pkl or HuggingFace directory).
+        ner_backend: Which NER backend to use: ``"crf"`` or ``"transformer"``.
+        completeness_threshold: Minimum number of populated detail fields
+            for a profile to be considered complete enough to keep.
+        relevance_weight: Weight for textual relevance in recommendation ranking [0, 1].
+        proximity_weight: Weight for geographic proximity in recommendation ranking [0, 1].
+        default_top_k: Default number of results returned by the recommendation engine.
+        fuzzy_match_threshold_verified: Levenshtein ratio threshold (0–1) to mark
+            a business as "Verified" against a BPLO registry.
+        fuzzy_match_threshold_pending: Levenshtein ratio threshold (0–1) to mark
+            a business as "Pending Verification".
+        max_flags_threshold: Number of user flags before a profile is auto-deactivated.
+    """
+
+    # NLP / Pipeline settings
+    ner_model_path: str | None = None
+    ner_backend: str = "crf"  # "crf" or "transformer"
+    completeness_threshold: int = 2
+
+    # Recommendation settings
+    relevance_weight: float = 0.6
+    proximity_weight: float = 0.4
+    default_top_k: int = 10
+
+    # BPLO Verification settings
+    fuzzy_match_threshold_verified: float = 0.8
+    fuzzy_match_threshold_pending: float = 0.6
+
+    # Business Profile limits
+    max_flags_threshold: int = 3

acuity_framework-1.0.0/acuity/extraction/__init__.py

@@ -0,0 +1,22 @@
+"""
+ACUITY Framework — Extraction Module
+
+NLP pipeline for extracting structured business information from
+unstructured community group posts (e.g., Facebook, forums).
+
+Components:
+    - preprocessing: Text cleaning and normalisation
+    - ner: Named Entity Recognition (CRF or Transformer backend)
+    - rules: Regex-based structured field extraction
+    - postprocessing: Profile construction from extraction outputs
+    - pipeline: End-to-end orchestrator
+
+Quick Start:
+    >>> from acuity.extraction import ExtractionPipeline
+    >>> pipeline = ExtractionPipeline()
+    >>> profiles = pipeline.extract_from_texts(["Mang Juan's Bakery, Mamatid, open 8am-5pm, 0917-123-4567"])
+"""
+
+from .pipeline import ExtractionPipeline
+
+__all__ = ["ExtractionPipeline"]