item-extractor 1.0.0__tar.gz

item_extractor-1.0.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: item-extractor
+Version: 1.0.0
+Summary: Extract todos, tasks, reminders, and events from natural language
+Author: UnknwnDev
+Author-email: UnknwnDev <0unknwn.dev@gmail.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: dateparser>=1.4.3
+Requires-Dist: spacy>=3.8.16
+Requires-Dist: ipykernel>=7.3.0 ; extra == 'notebook'
+Requires-Dist: pandas>=3.0.6 ; extra == 'notebook'
+Requires-Dist: scikit-learn>=1.9.1 ; extra == 'notebook'
+Requires-Dist: pytest>=9.1.1 ; extra == 'notebook'
+Requires-Python: >=3.12
+Provides-Extra: notebook
+Description-Content-Type: text/markdown
+
+# Item Extractor
+
+[![PyPI version](https://shields.io)](https://pypi.org)
+[![Python versions](https://shields.io)](https://pypi.org)
+
+lightweight feature extraction that turns natural-language into structured JSON of type tasks, events, todos, etc...
+
+## Installation
+
+Choose the installation method that fits your use case:
+
+### 1. Standard Installation (Production / Inference)
+If you only need to run existing agents, install the core package. This keeps the installation lightweight and bundles the standard **spaCy `en_core_web_md` model** automatically:
+```bash
+uv add item_extractor
+# or via pip
+pip install item_extractor
+```
+
+### 2. Notebook Installation (Development / Intent Classification Custom Agent Training)
+If you want to use our interactive Jupyter Notebooks to design, benchmark, and train your own custom agent models, install the package with the `notebook` extra dependencies:
+```bash
+uv add "item_extractor[notebook]"
+# or via pip
+pip install "item_extractor[notebook]"
+```
+
+---
+
+## 🚀 Quick Start (Core Library)
+
+Use the built-in components to run an agent directly in your Python application:
+
+```python
+from item_extractor import extract
+
+items = extract("Organize the garage")
+print(response) # Returns Todo(title='Organize the garage', description='', type=<ItemType.TODO: 'todo'>, completed=False)
+```
+
+---
+
+## 🧠 Creating Custom Intent Classification Agent Model
+
+If you installed the package with the `[notebook]` extras, you can create and fine-tune your own agent architectures. 
+
+1. Clone this repository to access the starter templates:
+   ```bash
+   git clone https://github.com/UnknwnDev/item-extractor.git
+   cd item_extractor
+   ```
+2. Open `notebooks/create_custom_agent.ipynb` and follow the step-by-step guide to train your agent using spaCy embeddings, customize decision thresholds, and evaluate agent trajectories.
+
+
+
+## 🛠️ Contribution & Local Setup
+
+For developers looking to contribute to the codebase:
+
+```bash
+# Clone and sync all environment dependencies including notebook extras
+git clone https://github.com/UnknwnDev/item-extractor.git
+cd item_extractor
+uv sync --extra notebook
+
+# Run the test suite
+uv run pytest
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

item_extractor-1.0.0/README.md

@@ -0,0 +1,72 @@
+# Item Extractor
+
+[![PyPI version](https://shields.io)](https://pypi.org)
+[![Python versions](https://shields.io)](https://pypi.org)
+
+lightweight feature extraction that turns natural-language into structured JSON of type tasks, events, todos, etc...
+
+## Installation
+
+Choose the installation method that fits your use case:
+
+### 1. Standard Installation (Production / Inference)
+If you only need to run existing agents, install the core package. This keeps the installation lightweight and bundles the standard **spaCy `en_core_web_md` model** automatically:
+```bash
+uv add item_extractor
+# or via pip
+pip install item_extractor
+```
+
+### 2. Notebook Installation (Development / Intent Classification Custom Agent Training)
+If you want to use our interactive Jupyter Notebooks to design, benchmark, and train your own custom agent models, install the package with the `notebook` extra dependencies:
+```bash
+uv add "item_extractor[notebook]"
+# or via pip
+pip install "item_extractor[notebook]"
+```
+
+---
+
+## 🚀 Quick Start (Core Library)
+
+Use the built-in components to run an agent directly in your Python application:
+
+```python
+from item_extractor import extract
+
+items = extract("Organize the garage")
+print(response) # Returns Todo(title='Organize the garage', description='', type=<ItemType.TODO: 'todo'>, completed=False)
+```
+
+---
+
+## 🧠 Creating Custom Intent Classification Agent Model
+
+If you installed the package with the `[notebook]` extras, you can create and fine-tune your own agent architectures. 
+
+1. Clone this repository to access the starter templates:
+   ```bash
+   git clone https://github.com/UnknwnDev/item-extractor.git
+   cd item_extractor
+   ```
+2. Open `notebooks/create_custom_agent.ipynb` and follow the step-by-step guide to train your agent using spaCy embeddings, customize decision thresholds, and evaluate agent trajectories.
+
+
+
+## 🛠️ Contribution & Local Setup
+
+For developers looking to contribute to the codebase:
+
+```bash
+# Clone and sync all environment dependencies including notebook extras
+git clone https://github.com/UnknwnDev/item-extractor.git
+cd item_extractor
+uv sync --extra notebook
+
+# Run the test suite
+uv run pytest
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

item_extractor-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "item-extractor"
+version = "1.0.0"
+description = "Extract todos, tasks, reminders, and events from natural language"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "dateparser>=1.4.3",
+    "spacy>=3.8.16",
+]
+
+[[project.authors]]
+name = "UnknwnDev"
+email = "0unknwn.dev@gmail.com"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+notebook = [
+    "ipykernel>=7.3.0",
+    "pandas>=3.0.6",
+    "scikit-learn>=1.9.1",
+    "pytest>=9.1.1",
+]
+
+[tool.uv.sources.en_core_web_md]
+url = "https://github.com"
+
+[tool.hatch.build.targets.wheel]
+exclude = [
+    "*.ipynb",
+    "notebooks/",
+    "tests/",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "*.ipynb",
+    "notebooks/",
+    "tests/",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"

item_extractor-1.0.0/pyproject.toml.orig

@@ -0,0 +1,51 @@
+[project]
+name = "item-extractor"
+version = "1.0.0"
+description = "Extract todos, tasks, reminders, and events from natural language"
+readme = "README.md"
+authors = [
+    { name = "UnknwnDev", email = "0unknwn.dev@gmail.com" }
+]
+requires-python = ">=3.12"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "dateparser>=1.4.3",
+    "spacy>=3.8.16",
+]
+
+[tool.uv.sources]
+en_core_web_md = { url = "https://github.com" }
+
+[project.optional-dependencies]
+notebook = [
+    "ipykernel>=7.3.0",
+    "pandas>=3.0.6",
+    "scikit-learn>=1.9.1",
+    "pytest>=9.1.1",
+]
+
+[tool.hatch.build.targets.wheel]
+# Exclude notebooks from the final .whl package
+exclude = [
+    "*.ipynb",
+    "notebooks/",
+    "tests/",
+]
+
+[tool.hatch.build.targets.sdist]
+# Exclude notebooks from the source distribution archive (.tar.gz)
+exclude = [
+    "*.ipynb",
+    "notebooks/",
+    "tests/",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"

item_extractor-1.0.0/src/item_extractor/__init__.py

@@ -0,0 +1,28 @@
+from .extractor import Extractor
+from .models import (
+    Event,
+    ExtractedItem,
+    ItemType,
+    Reminder,
+    Task,
+    Todo,
+)
+
+# Create a default instance on module load
+_default_extractor = Extractor()
+
+
+def extract(text: str) -> list[ExtractedItem]:
+    return _default_extractor.extract(text)
+
+
+__all__ = [
+    "extract",
+    "Extractor",
+    "ExtractedItem",
+    "ItemType",
+    "Todo",
+    "Task",
+    "Reminder",
+    "Event",
+]

item_extractor-1.0.0/src/item_extractor/extractor.py

@@ -0,0 +1,143 @@
+import dateparser
+import joblib
+import spacy
+
+from datetime import datetime, timedelta
+from spacy.matcher import Matcher
+
+from .models import *
+
+
+class Extractor:
+    def __init__(self, model="en_core_web_md", timezone="PST") -> None:
+        self.classifier = joblib.load("model/intent_classifier.joblib")
+        self.nlp = spacy.load(model)
+        self.matcher = Matcher(self.nlp.vocab)
+        self.timezone = timezone
+
+        todo_pattern = [
+            {"POS": "VERB"},
+            {"POS": "DET", "OP": "?"},
+            {"POS": "ADJ", "OP": "*"},
+            {"POS": "NOUN", "OP": "*"},
+            {"POS": "NOUN"},
+        ]
+
+        task_pattern = [
+            {"POS": "VERB"},
+            {"POS": {"IN": ["DET", "ADJ", "NOUN", "PROPN", "NUM"]}, "OP": "*"},
+            {"POS": "NOUN"},
+        ]
+
+        reminder_pattern = [
+            {"LOWER": "remind"},
+            {"POS": {"IN": ["PRON", "PROPN"]}},
+            {"LOWER": "to"},
+            {"POS": "VERB"},
+            {"OP": "{1,4}"},  # Captures the next 1-4 words
+        ]
+
+        event_pattern = [
+            {"POS": {"IN": ["NOUN", "ADJ", "PROPN"]}, "OP": "*"},
+            {"LEMMA": {"IN": ["appointment", "meeting", "lunch", "event", "session"]}},
+        ]
+
+        self.matcher.add("TODO", [todo_pattern])
+        self.matcher.add("TASK", [task_pattern])
+        self.matcher.add("REMINDER", [reminder_pattern])
+        self.matcher.add("EVENT", [event_pattern])
+
+    def parse_command(self, text: str):
+        """Extracts item title, datetime, and location from given text for item creation.
+
+        Args:
+            text (str): user input
+
+        Returns:
+            dict: dictionary of title, datetime, and location
+        """
+        doc = self.nlp(text)
+        matches = self.matcher(doc)
+
+        if not matches:
+            return {"title": "Could not extract a pattern."}
+
+        longest_match = None
+        max_length = 0
+
+        for match_id, start, end in matches:
+            match_length = end - start
+            if match_length > max_length:
+                max_length = match_length
+                longest_match = (match_id, start, end)
+
+        match_id, start, end = longest_match  # type: ignore
+        intent_label = self.nlp.vocab.strings[match_id]
+
+        if intent_label == "REMINDER":
+            match_span = doc[start:end]
+            to_index = start + 2
+
+            for token in match_span:
+                if token.lower_ == "to":
+                    to_index = token.i
+                    break
+
+            extracted_phrase = doc[to_index + 1 : end].text
+        else:
+            extracted_phrase = doc[start:end].text
+
+        date: str = ""
+        time: str = ""
+        location: str | None = None
+
+        for ent in doc.ents:
+            if ent.label_ == "DATE":
+                date = ent.text
+            if ent.label_ == "TIME":
+                time = ent.text
+            if ent.label_ in ["GPE", "LOC"]:
+                location = ent.text
+
+        date_time: datetime | None = dateparser.parse(
+            date + time, settings={"TIMEZONE": self.timezone}
+        )
+
+        data = {"title": extracted_phrase, "datetime": date_time, "location": location}
+        return data
+
+    def extract(self, text: str) -> ExtractedItem:
+        """Extract todo, task, reminder, and event from natural language.
+
+        Args:
+            text (str): user input
+
+        Returns:
+            ExtractedItem: Object of Todo | Task | Reminder | Event | None
+        """
+        # Predict the category without any hardcoded rules
+        prediction = self.classifier.predict([text])[0]
+
+        item = None
+
+        data = self.parse_command(text)
+
+        print(data)
+        if prediction == "todo":
+            item = Todo(title=data["title"])
+        elif prediction == "reminder":
+            item = Reminder(title=data["title"])
+        elif prediction == "event":
+            item = Event(
+                    title=data["title"],
+                    start_at=data["datetime"], # type: ignore
+                    end_at=data["datetime"] + timedelta(hours=1), # type: ignore
+                    location=data["location"]
+                )
+
+        elif prediction == "task":
+            item = Task(title=data["title"], due_at=data["datetime"]) # type: ignore
+
+        print(item, prediction)
+
+        return item

item_extractor-1.0.0/src/item_extractor/models.py

@@ -0,0 +1,52 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ItemType(StrEnum):
+    TODO = "todo"
+    TASK = "task"
+    REMINDER = "reminder"
+    EVENT = "event"
+
+
+class BaseItem(BaseModel):
+    title: str
+    description: str = ""
+
+
+class Todo(BaseItem):
+    type: Literal[ItemType.TODO] = ItemType.TODO
+
+    completed: bool = False
+
+
+class Task(BaseItem):
+    type: Literal[ItemType.TASK] = ItemType.TASK
+
+    due_at: datetime | None = None
+    priority: int | None = Field(default=None, ge=1, le=5)
+
+
+class Reminder(BaseItem):
+    type: Literal[ItemType.REMINDER] = ItemType.REMINDER
+
+    remind_at: datetime | None = None
+    recurrence: str | None = None
+
+
+class Event(BaseItem):
+    type: Literal[ItemType.EVENT] = ItemType.EVENT
+
+    start_at: datetime
+    end_at: datetime | None = None
+    location: str | None = None
+    attendees: list[str] = Field(default_factory=list)
+
+
+ExtractedItem = Annotated[
+    Todo|Task|Reminder|Event|None,
+    Field(discriminator="type"),
+]