acuity-framework 2.0.3__tar.gz → 3.0.0__tar.gz

{acuity_framework-2.0.3/acuity_framework.egg-info → acuity_framework-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acuity-framework
-Version: 2.0.3
+Version: 3.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
@@ -141,6 +141,75 @@ for r in results:
 
 ---
 
+## 🔌 Extensibility (v3.0)
+
+ACUITY v3.0 introduces **three pluggable extension points** via abstract base classes. You can inject custom implementations without modifying the framework's source code. All extension points are optional — existing code continues to work unchanged.
+
+### Custom NER Backend
+
+Replace the built-in CRF/Transformer NER with your own implementation:
+
+```python
+from acuity.extraction.interfaces import NERBackend
+from acuity.extraction import ExtractionPipeline
+
+class MyNERBackend(NERBackend):
+    def extract_entities(self, text: str) -> dict:
+        # Your custom entity extraction logic
+        return {
+            "business_name": ["Detected Name"],
+            "categories": ["food"],
+            "locations": ["Manila"],
+        }
+
+# Inject it — existing config-based NER is used when ner_backend=None (default)
+pipeline = ExtractionPipeline(ner_backend=MyNERBackend())
+profiles = pipeline.extract_from_texts(["Sample post text"])
+```
+
+### Custom Data Source
+
+Replace the Facebook scraper with any data source (CSV, database, API, etc.):
+
+```python
+from acuity.scraper.interfaces import DataSource
+from acuity.extraction import ExtractionPipeline
+
+class MyDataSource(DataSource):
+    def fetch_posts(self, sources: list[str], max_posts: int = 500) -> list[dict]:
+        # Your custom data fetching logic
+        return [{"text": "Post content", "poster": "Author Name"}]
+
+# Inject it and use extract_from_source() for fetch + extract in one call
+pipeline = ExtractionPipeline(data_source=MyDataSource())
+profiles = pipeline.extract_from_source(sources=["my_source_id"])
+```
+
+### Custom Ranking Strategy
+
+Replace TF-IDF + cosine similarity with your own text-relevance scoring:
+
+```python
+from acuity.recommendation.interfaces import RankingStrategy
+from acuity.recommendation import RecommendationEngine
+
+class MyRanking(RankingStrategy):
+    def compute_scores(self, profiles: list[dict], query: str) -> list[float]:
+        # Your custom relevance scoring logic
+        return [1.0 if query.lower() in str(p).lower() else 0.0 for p in profiles]
+
+# Inject it — Haversine proximity is still used alongside (it's a fixed formula)
+engine = RecommendationEngine(ranking_strategy=MyRanking())
+engine.set_profiles(profiles)
+results = engine.recommend("bakery")
+```
+
+> **Note:** Haversine distance, the pipeline stage order (preprocess → NER → rules → postprocess), and Levenshtein fuzzy matching are intentionally **not** abstracted — they are fixed, correct algorithms with no legitimate variation.
+
+See [`examples/demo_extensibility.py`](examples/demo_extensibility.py) for a complete end-to-end demo using all three extension points.
+
+---
+
 ## ⚙️ Configuration
 
 All settings are controlled via the `AcuityConfig` dataclass:
@@ -210,6 +279,7 @@ acuity-framework/
 │   ├── utils.py            # Levenshtein similarity utilities
 │   ├── extraction/         # NLP extraction pipeline
 │   │   ├── pipeline.py     # ExtractionPipeline class
+│   │   ├── interfaces.py   # NERBackend ABC (extensibility)
 │   │   ├── preprocessing.py
 │   │   ├── ner_crf.py
 │   │   ├── ner_transformer.py
@@ -217,19 +287,25 @@ acuity-framework/
 │   │   └── postprocessing.py
 │   ├── recommendation/     # Recommendation engine
 │   │   ├── engine.py       # RecommendationEngine class
+│   │   ├── interfaces.py   # RankingStrategy ABC (extensibility)
 │   │   ├── vectorizer.py   # TF-IDF vectorizer
 │   │   ├── similarity.py   # Cosine similarity
-│   │   ├── proximity.py    # Haversine distance
+│   │   ├── proximity.py    # Haversine distance (fixed, not abstracted)
 │   │   └── ranker.py       # Combined ranking
 │   ├── verification/       # Business verification
 │   │   └── bplo.py         # BPLOVerifier class
-│   └── scraper/            # Facebook scraper (optional)
+│   └── scraper/            # Data collection (optional)
 │       ├── scraper.py      # FacebookScraper class
+│       ├── interfaces.py   # DataSource ABC (extensibility)
 │       └── utils.py
 ├── examples/
 │   ├── basic_extraction.py
 │   ├── basic_recommendation.py
-│   └── flask_integration.py
+│   ├── flask_integration.py
+│   ├── custom_ner_backend.py       # Example: KeywordNERBackend
+│   ├── custom_data_source.py       # Example: CSVDataSource
+│   ├── custom_ranking_strategy.py  # Example: KeywordMatchRanking
+│   └── demo_extensibility.py       # Combined end-to-end demo
 └── tests/
     ├── test_extraction.py
     ├── test_recommendation.py

{acuity_framework-2.0.3 → acuity_framework-3.0.0}/README.md

@@ -97,6 +97,75 @@ for r in results:
 
 ---
 
+## 🔌 Extensibility (v3.0)
+
+ACUITY v3.0 introduces **three pluggable extension points** via abstract base classes. You can inject custom implementations without modifying the framework's source code. All extension points are optional — existing code continues to work unchanged.
+
+### Custom NER Backend
+
+Replace the built-in CRF/Transformer NER with your own implementation:
+
+```python
+from acuity.extraction.interfaces import NERBackend
+from acuity.extraction import ExtractionPipeline
+
+class MyNERBackend(NERBackend):
+    def extract_entities(self, text: str) -> dict:
+        # Your custom entity extraction logic
+        return {
+            "business_name": ["Detected Name"],
+            "categories": ["food"],
+            "locations": ["Manila"],
+        }
+
+# Inject it — existing config-based NER is used when ner_backend=None (default)
+pipeline = ExtractionPipeline(ner_backend=MyNERBackend())
+profiles = pipeline.extract_from_texts(["Sample post text"])
+```
+
+### Custom Data Source
+
+Replace the Facebook scraper with any data source (CSV, database, API, etc.):
+
+```python
+from acuity.scraper.interfaces import DataSource
+from acuity.extraction import ExtractionPipeline
+
+class MyDataSource(DataSource):
+    def fetch_posts(self, sources: list[str], max_posts: int = 500) -> list[dict]:
+        # Your custom data fetching logic
+        return [{"text": "Post content", "poster": "Author Name"}]
+
+# Inject it and use extract_from_source() for fetch + extract in one call
+pipeline = ExtractionPipeline(data_source=MyDataSource())
+profiles = pipeline.extract_from_source(sources=["my_source_id"])
+```
+
+### Custom Ranking Strategy
+
+Replace TF-IDF + cosine similarity with your own text-relevance scoring:
+
+```python
+from acuity.recommendation.interfaces import RankingStrategy
+from acuity.recommendation import RecommendationEngine
+
+class MyRanking(RankingStrategy):
+    def compute_scores(self, profiles: list[dict], query: str) -> list[float]:
+        # Your custom relevance scoring logic
+        return [1.0 if query.lower() in str(p).lower() else 0.0 for p in profiles]
+
+# Inject it — Haversine proximity is still used alongside (it's a fixed formula)
+engine = RecommendationEngine(ranking_strategy=MyRanking())
+engine.set_profiles(profiles)
+results = engine.recommend("bakery")
+```
+
+> **Note:** Haversine distance, the pipeline stage order (preprocess → NER → rules → postprocess), and Levenshtein fuzzy matching are intentionally **not** abstracted — they are fixed, correct algorithms with no legitimate variation.
+
+See [`examples/demo_extensibility.py`](examples/demo_extensibility.py) for a complete end-to-end demo using all three extension points.
+
+---
+
 ## ⚙️ Configuration
 
 All settings are controlled via the `AcuityConfig` dataclass:
@@ -166,6 +235,7 @@ acuity-framework/
 │   ├── utils.py            # Levenshtein similarity utilities
 │   ├── extraction/         # NLP extraction pipeline
 │   │   ├── pipeline.py     # ExtractionPipeline class
+│   │   ├── interfaces.py   # NERBackend ABC (extensibility)
 │   │   ├── preprocessing.py
 │   │   ├── ner_crf.py
 │   │   ├── ner_transformer.py
@@ -173,19 +243,25 @@ acuity-framework/
 │   │   └── postprocessing.py
 │   ├── recommendation/     # Recommendation engine
 │   │   ├── engine.py       # RecommendationEngine class
+│   │   ├── interfaces.py   # RankingStrategy ABC (extensibility)
 │   │   ├── vectorizer.py   # TF-IDF vectorizer
 │   │   ├── similarity.py   # Cosine similarity
-│   │   ├── proximity.py    # Haversine distance
+│   │   ├── proximity.py    # Haversine distance (fixed, not abstracted)
 │   │   └── ranker.py       # Combined ranking
 │   ├── verification/       # Business verification
 │   │   └── bplo.py         # BPLOVerifier class
-│   └── scraper/            # Facebook scraper (optional)
+│   └── scraper/            # Data collection (optional)
 │       ├── scraper.py      # FacebookScraper class
+│       ├── interfaces.py   # DataSource ABC (extensibility)
 │       └── utils.py
 ├── examples/
 │   ├── basic_extraction.py
 │   ├── basic_recommendation.py
-│   └── flask_integration.py
+│   ├── flask_integration.py
+│   ├── custom_ner_backend.py       # Example: KeywordNERBackend
+│   ├── custom_data_source.py       # Example: CSVDataSource
+│   ├── custom_ranking_strategy.py  # Example: KeywordMatchRanking
+│   └── demo_extensibility.py       # Combined end-to-end demo
 └── tests/
     ├── test_extraction.py
     ├── test_recommendation.py

{acuity_framework-2.0.3 → acuity_framework-3.0.0}/acuity/__init__.py

@@ -19,7 +19,7 @@ Quick Start:
     >>> from acuity.verification import BPLOVerifier
 """
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 __author__ = "ACUITY Research Team"
 
 from .config import AcuityConfig

acuity_framework-3.0.0/acuity/extraction/interfaces.py

@@ -0,0 +1,51 @@
+"""
+ACUITY Framework — Extraction Interfaces
+
+Abstract base classes defining pluggable extension points for the
+extraction pipeline. Third-party code can implement these interfaces
+to provide custom NER backends without modifying ACUITY's source.
+
+Example:
+    >>> from acuity.extraction.interfaces import NERBackend
+    >>> class MyNER(NERBackend):
+    ...     def extract_entities(self, text):
+    ...         return {"business_name": [], "categories": [], "locations": []}
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class NERBackend(ABC):
+    """Abstract interface for Named Entity Recognition backends.
+
+    Implement this class to provide a custom NER backend that can be
+    injected into :class:`~acuity.extraction.pipeline.ExtractionPipeline`
+    via its ``ner_backend`` constructor parameter.
+
+    The backend receives preprocessed text and must return a dictionary
+    of extracted entity lists.
+
+    Example:
+        >>> class KeywordNER(NERBackend):
+        ...     def extract_entities(self, text: str) -> dict:
+        ...         names = ["My Shop"] if "shop" in text.lower() else []
+        ...         return {"business_name": names, "categories": [], "locations": []}
+    """
+
+    @abstractmethod
+    def extract_entities(self, text: str) -> dict:
+        """Extract named entities from preprocessed text.
+
+        Args:
+            text: Preprocessed post text (already cleaned and normalised).
+
+        Returns:
+            A dictionary with the following keys, each mapping to a
+            list of extracted strings:
+
+            - ``"business_name"``: Extracted business name fragments.
+            - ``"categories"``: Extracted service/business categories.
+            - ``"locations"``: Extracted location/address fragments.
+        """
+        ...

{acuity_framework-2.0.3 → acuity_framework-3.0.0}/acuity/extraction/pipeline.py

@@ -22,6 +22,8 @@ from typing import Any
 from .preprocessing import preprocess
 from .rules import extract_structured_fields
 from .postprocessing import build_business_profile
+from .interfaces import NERBackend
+from ..scraper.interfaces import DataSource
 from ..config import AcuityConfig
 
 
@@ -35,13 +37,32 @@ class ExtractionPipeline:
         config: An ``AcuityConfig`` instance. If ``None``, uses defaults.
         ner_model: A pre-loaded NER model object. If provided, the pipeline
             will use this model directly instead of loading from ``config.ner_model_path``.
+        ner_backend: An optional :class:`~acuity.extraction.interfaces.NERBackend`
+            instance. When provided, the pipeline uses this backend for NER
+            instead of the built-in CRF/transformer string-branch logic.
+            When ``None`` (the default), the existing config-driven backend
+            selection is used.
+        data_source: An optional :class:`~acuity.scraper.interfaces.DataSource`
+            instance. When provided, enables :meth:`extract_from_source` to
+            fetch posts from a custom data source before extraction.
+            When ``None`` (the default), only :meth:`extract_from_texts`
+            is available (existing behavior unchanged).
     """
 
-    def __init__(self, config: AcuityConfig | None = None, ner_model: Any = None):
+    def __init__(
+        self,
+        config: AcuityConfig | None = None,
+        ner_model: Any = None,
+        ner_backend: NERBackend | None = None,
+        data_source: DataSource | None = None,
+    ):
         self.config = config or AcuityConfig()
         self._ner_model = ner_model
         self._ner_extract_fn = None
-        self._setup_ner()
+        self._custom_ner_backend = ner_backend
+        self._data_source = data_source
+        if self._custom_ner_backend is None:
+            self._setup_ner()
 
     def _setup_ner(self) -> None:
         """Initialise the NER backend based on configuration."""
@@ -86,9 +107,14 @@ class ExtractionPipeline:
         cleaned = preprocess(text)
 
         # Step 2: Named Entity Recognition
-        entities = self._ner_extract_fn(cleaned) if self._ner_extract_fn else {
-            "business_name": [], "categories": [], "locations": []
-        }
+        if self._custom_ner_backend is not None:
+            entities = self._custom_ner_backend.extract_entities(cleaned)
+        elif self._ner_extract_fn:
+            entities = self._ner_extract_fn(cleaned)
+        else:
+            entities = {
+                "business_name": [], "categories": [], "locations": []
+            }
 
         # Step 3: Rule-based extraction (contacts, hours, address patterns)
         structured = extract_structured_fields(cleaned)
@@ -169,3 +195,44 @@ class ExtractionPipeline:
             profiles = unique_profiles
 
         return profiles
+
+    def extract_from_source(
+        self,
+        sources: list[str],
+        max_posts: int = 500,
+        completeness_threshold: int | None = None,
+        deduplicate: bool = True,
+    ) -> list[dict]:
+        """Fetch posts from a :class:`~acuity.scraper.interfaces.DataSource` and extract profiles.
+
+        This is a convenience method that combines data fetching and extraction
+        into a single call. It requires a ``data_source`` to have been provided
+        to the pipeline constructor.
+
+        Args:
+            sources: List of source identifiers (meaning depends on the
+                :class:`~acuity.scraper.interfaces.DataSource` implementation).
+            max_posts: Maximum number of posts to fetch.
+            completeness_threshold: Minimum number of populated detail fields
+                to keep a profile. Defaults to ``config.completeness_threshold``.
+            deduplicate: If True, deduplicate profiles by business name.
+
+        Returns:
+            List of extracted business profile dicts.
+
+        Raises:
+            RuntimeError: If no ``data_source`` was provided to the constructor.
+        """
+        if self._data_source is None:
+            raise RuntimeError(
+                "No data_source was provided to ExtractionPipeline. "
+                "Pass a DataSource instance via the data_source parameter, "
+                "or use extract_from_texts() directly."
+            )
+
+        posts = self._data_source.fetch_posts(sources, max_posts=max_posts)
+        return self.extract_from_texts(
+            texts=posts,
+            completeness_threshold=completeness_threshold,
+            deduplicate=deduplicate,
+        )

{acuity_framework-2.0.3 → acuity_framework-3.0.0}/acuity/recommendation/engine.py

@@ -21,6 +21,7 @@ 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 .interfaces import RankingStrategy
 from ..config import AcuityConfig
 
 
@@ -34,6 +35,13 @@ class RecommendationEngine:
         config: An ``AcuityConfig`` instance. If ``None``, uses defaults.
         relevance_weight: Override the config's relevance weight.
         proximity_weight: Override the config's proximity weight.
+        ranking_strategy: An optional
+            :class:`~acuity.recommendation.interfaces.RankingStrategy` instance.
+            When provided, replaces the built-in TF-IDF + cosine similarity
+            computation for text relevance scoring. When ``None`` (the default),
+            the existing TF-IDF + cosine pipeline is used.
+            Note: Haversine proximity scoring is a fixed, correct geographic
+            formula and is not affected by this parameter.
     """
 
     def __init__(
@@ -41,6 +49,7 @@ class RecommendationEngine:
         config: AcuityConfig | None = None,
         relevance_weight: float | None = None,
         proximity_weight: float | None = None,
+        ranking_strategy: RankingStrategy | None = None,
     ):
         self.config = config or AcuityConfig()
         self.profiles: list[dict] = []
@@ -48,6 +57,7 @@ class RecommendationEngine:
         self.proximity_weight = proximity_weight if proximity_weight is not None else self.config.proximity_weight
         self._tfidf_matrix = None
         self._vectorizer = None
+        self._ranking_strategy = ranking_strategy
 
     def set_profiles(self, profiles: list[dict]) -> None:
         """Load business profiles from an in-memory list.
@@ -103,14 +113,23 @@ class RecommendationEngine:
         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:
+        if not self.profiles:
             return []
 
         # Textual relevance
-        query_vec = transform_query(self._vectorizer, query)
-        cosine_scores = compute_cosine_scores(self._tfidf_matrix, query_vec)
+        if self._ranking_strategy is not None:
+            # Use injected ranking strategy
+            cosine_scores = self._ranking_strategy.compute_scores(self.profiles, query)
+        elif self._tfidf_matrix is not None and self._vectorizer is not None:
+            # Existing TF-IDF + cosine similarity path (unchanged)
+            query_vec = transform_query(self._vectorizer, query)
+            cosine_scores = compute_cosine_scores(self._tfidf_matrix, query_vec)
+        else:
+            return []
 
-        # Proximity (if user location provided)
+        # Haversine proximity (if user location provided)
+        # NOTE: Haversine distance is a fixed, correct geographic formula
+        # with no legitimate variation — it is intentionally not abstracted.
         distances: list[float | None] = []
         if user_lat is not None and user_lon is not None:
             for profile in self.profiles:

acuity_framework-3.0.0/acuity/recommendation/interfaces.py

@@ -0,0 +1,58 @@
+"""
+ACUITY Framework — Recommendation Interfaces
+
+Abstract base classes defining pluggable extension points for the
+recommendation engine. Third-party code can implement these interfaces
+to provide custom ranking strategies without modifying ACUITY's source.
+
+Example:
+    >>> from acuity.recommendation.interfaces import RankingStrategy
+    >>> class MyRanking(RankingStrategy):
+    ...     def compute_scores(self, profiles, query):
+    ...         return [1.0] * len(profiles)  # everyone is relevant!
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class RankingStrategy(ABC):
+    """Abstract interface for text-relevance ranking strategies.
+
+    Implement this class to provide a custom ranking algorithm that can
+    be injected into :class:`~acuity.recommendation.engine.RecommendationEngine`
+    via its ``ranking_strategy`` constructor parameter.
+
+    The strategy computes a relevance score for each business profile given
+    a user query. These scores are then combined with proximity scores
+    (Haversine distance — which is a fixed formula and not abstracted)
+    to produce the final ranking.
+
+    Example:
+        >>> class BM25Ranking(RankingStrategy):
+        ...     def compute_scores(self, profiles, query):
+        ...         # Implement BM25 scoring
+        ...         return scores
+    """
+
+    @abstractmethod
+    def compute_scores(
+        self,
+        profiles: list[dict],
+        query: str,
+    ) -> list[float]:
+        """Compute relevance scores for each profile against a query.
+
+        Args:
+            profiles: List of business profile dictionaries. Each dict
+                may contain keys such as ``"name"``, ``"business_name"``,
+                ``"description"``, ``"categories"``, and ``"services"``.
+            query: The user's search query text.
+
+        Returns:
+            A list of float scores (higher = more relevant), one per
+            profile, in the same order as the input list. Scores should
+            typically be in the range [0, 1] but this is not strictly
+            required.
+        """
+        ...

acuity_framework-3.0.0/acuity/scraper/interfaces.py

@@ -0,0 +1,58 @@
+"""
+ACUITY Framework — Scraper Interfaces
+
+Abstract base classes defining pluggable extension points for data
+collection. Third-party code can implement these interfaces to provide
+custom data sources without modifying ACUITY's source.
+
+Example:
+    >>> from acuity.scraper.interfaces import DataSource
+    >>> class MySource(DataSource):
+    ...     def fetch_posts(self, sources, max_posts=500):
+    ...         return [{"text": "Sample post", "poster": "User"}]
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class DataSource(ABC):
+    """Abstract interface for data sources that provide post text.
+
+    Implement this class to provide a custom data source (e.g., CSV file,
+    database, API) that can be injected into
+    :class:`~acuity.extraction.pipeline.ExtractionPipeline` via its
+    ``data_source`` constructor parameter.
+
+    The data source receives a list of source identifiers (URLs, file paths,
+    etc.) and returns a list of post dictionaries.
+
+    Example:
+        >>> class DatabaseSource(DataSource):
+        ...     def fetch_posts(self, sources, max_posts=500):
+        ...         # Query database for posts
+        ...         return [{"text": "post text", "poster": "author"}]
+    """
+
+    @abstractmethod
+    def fetch_posts(
+        self,
+        sources: list[str],
+        max_posts: int = 500,
+    ) -> list[dict]:
+        """Fetch posts from the data source.
+
+        Args:
+            sources: List of source identifiers. The meaning depends on the
+                implementation (e.g., URLs, file paths, database table names).
+            max_posts: Maximum number of posts to return.
+
+        Returns:
+            A list of dictionaries, each with at least a ``"text"`` key
+            containing the post content. Optional keys include:
+
+            - ``"poster"``: Name of the post author.
+            - ``"scraped_at"``: Timestamp or date string of when the post
+              was collected.
+        """
+        ...

{acuity_framework-2.0.3 → acuity_framework-3.0.0/acuity_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acuity-framework
-Version: 2.0.3
+Version: 3.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
@@ -141,6 +141,75 @@ for r in results:
 
 ---
 
+## 🔌 Extensibility (v3.0)
+
+ACUITY v3.0 introduces **three pluggable extension points** via abstract base classes. You can inject custom implementations without modifying the framework's source code. All extension points are optional — existing code continues to work unchanged.
+
+### Custom NER Backend
+
+Replace the built-in CRF/Transformer NER with your own implementation:
+
+```python
+from acuity.extraction.interfaces import NERBackend
+from acuity.extraction import ExtractionPipeline
+
+class MyNERBackend(NERBackend):
+    def extract_entities(self, text: str) -> dict:
+        # Your custom entity extraction logic
+        return {
+            "business_name": ["Detected Name"],
+            "categories": ["food"],
+            "locations": ["Manila"],
+        }
+
+# Inject it — existing config-based NER is used when ner_backend=None (default)
+pipeline = ExtractionPipeline(ner_backend=MyNERBackend())
+profiles = pipeline.extract_from_texts(["Sample post text"])
+```
+
+### Custom Data Source
+
+Replace the Facebook scraper with any data source (CSV, database, API, etc.):
+
+```python
+from acuity.scraper.interfaces import DataSource
+from acuity.extraction import ExtractionPipeline
+
+class MyDataSource(DataSource):
+    def fetch_posts(self, sources: list[str], max_posts: int = 500) -> list[dict]:
+        # Your custom data fetching logic
+        return [{"text": "Post content", "poster": "Author Name"}]
+
+# Inject it and use extract_from_source() for fetch + extract in one call
+pipeline = ExtractionPipeline(data_source=MyDataSource())
+profiles = pipeline.extract_from_source(sources=["my_source_id"])
+```
+
+### Custom Ranking Strategy
+
+Replace TF-IDF + cosine similarity with your own text-relevance scoring:
+
+```python
+from acuity.recommendation.interfaces import RankingStrategy
+from acuity.recommendation import RecommendationEngine
+
+class MyRanking(RankingStrategy):
+    def compute_scores(self, profiles: list[dict], query: str) -> list[float]:
+        # Your custom relevance scoring logic
+        return [1.0 if query.lower() in str(p).lower() else 0.0 for p in profiles]
+
+# Inject it — Haversine proximity is still used alongside (it's a fixed formula)
+engine = RecommendationEngine(ranking_strategy=MyRanking())
+engine.set_profiles(profiles)
+results = engine.recommend("bakery")
+```
+
+> **Note:** Haversine distance, the pipeline stage order (preprocess → NER → rules → postprocess), and Levenshtein fuzzy matching are intentionally **not** abstracted — they are fixed, correct algorithms with no legitimate variation.
+
+See [`examples/demo_extensibility.py`](examples/demo_extensibility.py) for a complete end-to-end demo using all three extension points.
+
+---
+
 ## ⚙️ Configuration
 
 All settings are controlled via the `AcuityConfig` dataclass:
@@ -210,6 +279,7 @@ acuity-framework/
 │   ├── utils.py            # Levenshtein similarity utilities
 │   ├── extraction/         # NLP extraction pipeline
 │   │   ├── pipeline.py     # ExtractionPipeline class
+│   │   ├── interfaces.py   # NERBackend ABC (extensibility)
 │   │   ├── preprocessing.py
 │   │   ├── ner_crf.py
 │   │   ├── ner_transformer.py
@@ -217,19 +287,25 @@ acuity-framework/
 │   │   └── postprocessing.py
 │   ├── recommendation/     # Recommendation engine
 │   │   ├── engine.py       # RecommendationEngine class
+│   │   ├── interfaces.py   # RankingStrategy ABC (extensibility)
 │   │   ├── vectorizer.py   # TF-IDF vectorizer
 │   │   ├── similarity.py   # Cosine similarity
-│   │   ├── proximity.py    # Haversine distance
+│   │   ├── proximity.py    # Haversine distance (fixed, not abstracted)
 │   │   └── ranker.py       # Combined ranking
 │   ├── verification/       # Business verification
 │   │   └── bplo.py         # BPLOVerifier class
-│   └── scraper/            # Facebook scraper (optional)
+│   └── scraper/            # Data collection (optional)
 │       ├── scraper.py      # FacebookScraper class
+│       ├── interfaces.py   # DataSource ABC (extensibility)
 │       └── utils.py
 ├── examples/
 │   ├── basic_extraction.py
 │   ├── basic_recommendation.py
-│   └── flask_integration.py
+│   ├── flask_integration.py
+│   ├── custom_ner_backend.py       # Example: KeywordNERBackend
+│   ├── custom_data_source.py       # Example: CSVDataSource
+│   ├── custom_ranking_strategy.py  # Example: KeywordMatchRanking
+│   └── demo_extensibility.py       # Combined end-to-end demo
 └── tests/
     ├── test_extraction.py
     ├── test_recommendation.py

{acuity_framework-2.0.3 → acuity_framework-3.0.0}/acuity_framework.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ acuity/__init__.py
 acuity/config.py
 acuity/utils.py
 acuity/extraction/__init__.py
+acuity/extraction/interfaces.py
 acuity/extraction/ner_crf.py
 acuity/extraction/ner_transformer.py
 acuity/extraction/pipeline.py
@@ -14,11 +15,13 @@ acuity/extraction/preprocessing.py
 acuity/extraction/rules.py
 acuity/recommendation/__init__.py
 acuity/recommendation/engine.py
+acuity/recommendation/interfaces.py
 acuity/recommendation/proximity.py
 acuity/recommendation/ranker.py
 acuity/recommendation/similarity.py
 acuity/recommendation/vectorizer.py
 acuity/scraper/__init__.py
+acuity/scraper/interfaces.py
 acuity/scraper/scraper.py
 acuity/scraper/utils.py
 acuity/verification/__init__.py

{acuity_framework-2.0.3 → acuity_framework-3.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "acuity-framework"
-version = "2.0.3"
+version = "3.0.0"
 description = "ACUITY — A machine learning framework for extracting, verifying, and recommending local micro-enterprise profiles from unstructured community posts."
 readme = "README.md"
 license = {text = "MIT"}