![npm](https://img.shields.io/npm/v/query2filter-ai-sdk)
![license](https://img.shields.io/npm/l/query2filter-ai-sdk)
![typescript](https://img.shields.io/badge/typescript-supported-blue)


# Query2Filter AI

> Query2Filter AI is a lightweight TypeScript SDK that converts **natural language queries into structured filter objects** using an LLM.

It enables applications to transform human queries into structured filters that can be used to query databases, APIs, or search engines._

Example: "items under 100 with rating above 4"

```shell

becomes

```json
{
  "price": { "max": 100 },
  "rating": { "min": 4 }
}
```


# Why Query2Filter?

> Traditional filtering systems require users to manually select filters. 
Query2Filter allows users to describe what they want naturally, and the SDK extracts structured filters automatically.

Benefits:
- ✅Natural language query understanding
- ✅Schema-driven extraction
- ✅Data-agnostic architecture
- ✅Filter validation
- ✅Intelligent suggestions
- ✅Confidence scoring
- ✅Fully typed TypeScript SDK 


# Installation

```shell
"npm install query2filter-ai-sdk"
```

# Environment Setup

Set your Groq API key:

```shell
export GROQ_API_KEY="your_api_key_here"
```
You can obtain an API key from:

https://console.groq.com


# Quick Start

```shell
import { query2filter } from "query2filter-ai-sdk";

const schema = {
  attributes: {
    category: {
      type: "string"
    },
    price: {
      type: "number",
      min: 0,
      max: 100000
    },
    rating: {
      type: "number",
      min: 0,
      max: 5
    },
    size: {
      type: "number"
    }
  }
};

const result = await query2filter(
  "items under 100 with rating above 4",
  schema
);

console.log(result.filters);
console.log(result.validation);
console.log(result.suggestions);
console.log(result.confidence);
```
Example output:
```shell
{
  "filters": {
    "price": { "max": 100 },
    "rating": { "min": 4 }
  },
  "confidence": 0.91
}
```

# Use Cases

>Query2Filter can power semantic search across many domains:

- ✅E-commerce search
- ✅Marketplace platforms
- ✅SaaS dashboards
- ✅Data analytics tools
- ✅Knowledge base search
- ✅Enterprise catalogs
- ✅API query builders
- ✅Internal data tools

The SDK is **Schema-driven**, so it can adapt to any structured dataset.

# How It Works

> Query2Filter processes queries through a structured pipeline:

```shell
Natural Language Query
        │
        ▼
Schema Normalization
        │
        ▼
AI Query Parser
        │
        ▼
Filter Validation
        │
        ▼
Suggestion Engine
        │
        ▼
Structured Filters
```

The resulting filters can then be used to query a database or API.

# API


### Query2Filter(query,schema) ###
Parses a natural language query and converts it into structured filters.


### Parameters ###
<table>
  <tr>
    <th style="text-align: center;">Parameter</th>
	<th style="text-align: center;">Type</th>
    <th style="text-align: center;">Description</th>
  </tr>
  <tr>
    <td>
      query
    </td>
    <td>
      string
    </td>
	<td>
      User search query
    </td>
  </tr>
  <tr>
    <td>
      schema
    </td>
    <td>
      object
    </td>
	<td>
      Attribute schema
    </td>
  </tr>
</table>


### Returns ###
```shell
{
  filters: Record<string, any>,
  validation: {
    valid: boolean,
    errors: string[]
  },
  suggestions: string[],
  confidence: number
}
```

# Schema Definition #
> Schemas define which attributes can be extracted from queries.

Example schema:

```shell
const schema = {
  attributes: {
    attributeName: {
      type: "string" | "number",
      valid_values?: string[],
      min?: number,
      max?: number
    }
  }
};
```
This makes Query2Filter adaptable to any dataset.

# Project Structure #
```shell
src/
├── core/            # Query pipeline
├── parser/          # LLM query parsing
├── validation/      # Filter validation
├── suggestions/     # Suggestion generation
├── utils/           # Schema utilities
├── types/           # TypeScript types
└── index.ts         # SDK entry point
```

# Building from Source #

Clone the repository: 
```shell
git clone https://github.com/milindsharma21/query2filter-ai
```

Install dependencies: 
```shell
npm install
```

Build the project: 
```shell
npm run build
```

# Links # 

### NPM Package ###
https://www.npmjs.com/package/query2filter-ai-sdk

### GitHub Repository ###
https://www.npmjs.com/package/query2filter-ai-sdk

# License #

MIT license
Copyright (c) 2026 Milind Sharma