Metadata-Version: 2.3
Name: item-extractor
Version: 1.0.1
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: joblib>=1.6.0
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://img.shields.io/pypi/v/item-extractor.svg)](https://pypi.org/project/item-extractor)
[![Python versions](https://img.shields.io/pypi/pyversions/item-extractor.svg)](https://pypi.org/project/item-extractor)

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]"
```

---

## How to use

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.
