gliner-node-wrapper/README.md

Node.js wrapper around Python-based GlinER NER library

# GlinER Node.js Wrapper

A secure and production-ready Node.js wrapper for the [GlinER](https://huggingface.co/urchade/gliner_base) Named Entity Recognition (NER) Python library.

This package allows you to call GlinER from Node.js to extract entities using labels of your choice.

---

## 📦 Installation

### Prerequisites

- Python 3.7+
- Node.js 14+

### Step 1: Install via npm

```bash
npm install gliner-node-wrapper
```

### Step 2: Python Dependencies (Auto-installed)

This package automatically installs Python dependencies (`gliner`, `torch`, `transformers`) during installation using a `postinstall` hook.

---

## 🚀 Usage

### Basic Example

```js
const { extractEntities } = require('gliner-node-wrapper');

const text = "Barack Obama served as president of the United States.";
const labels = ["person", "organization", "location"];

extractEntities(text, labels)
  .then((entities) => console.log("Entities:", entities))
  .catch((err) => console.error("Error:", err.message));
```

### Output

```json
[
  { "text": "Barack Obama", "label": "person" },
  { "text": "United States", "label": "location" }
]
```

---

## 🛠 How It Works

- A Node.js script (`index.js`) spawns a secure Python subprocess.
- Input text and labels are passed via stdin to a Python script.
- The Python script runs GlinER and returns extracted entities as JSON.

---

## 📁 Project Structure

```
gliner-node-wrapper/
├── index.js               # Main Node wrapper
├── gliner_wrapper.py      # Python subprocess handler
├── install-python.js      # Auto-installs Python deps
├── requirements.txt       # Python dependencies
├── example.js             # Demo usage
├── package.json
└── README.md
```

---

## 🔐 Security Features

- Input validation on both JS and Python sides
- Timeout to kill unresponsive subprocesses
- No shell evaluation (uses `spawn` safely)
- Full error reporting

---

## 🧪 Development

Clone the repo:

```bash
git clone https://github.com/yourname/gliner-node-wrapper.git
cd gliner-node-wrapper
npm install
```

Run the test:

```bash
npm test
```

---

## 📜 License

MIT © 2025 Your Name