Metadata-Version: 2.4
Name: ikpu
Version: 0.1.0
Summary: IKPU/MXIK product classifier for Uzbekistan tax codes
Author-email: Kudrat Alimov <alimov.kolya@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kudrat-uz/ikpu
Project-URL: Repository, https://github.com/kudrat-uz/ikpu
Project-URL: Issues, https://github.com/kudrat-uz/ikpu/issues
Keywords: ikpu,mxik,uzbekistan,tax,classifier,tfidf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: scikit-learn>=1.3
Requires-Dist: numpy>=1.24
Requires-Dist: requests>=2.31
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == "server"
Requires-Dist: uvicorn>=0.23; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# ikpu

Python library for matching products with IKPU/MXIK codes (Uzbekistan tax classification) by product name or barcode.

Uses TF-IDF similarity search over the official [tasnif.soliq.uz](https://tasnif.soliq.uz) catalog.

## Installation

```bash
pip install ikpu
```

With FastAPI server support:

```bash
pip install ikpu[server]
```

## Quick Start

```python
from ikpu import IKPUMatcher

matcher = IKPUMatcher()

# Download the catalog (first time only)
matcher.update()

# Load indexes
matcher.load()

# Search by product name
results = matcher.search("Coca-Cola 0.5", language="ru", top_k=5)
for r in results:
    print(f"{r['ikpu']} — {r['name']} ({r['similarity']:.2f})")

# Search by barcode
results = matcher.search_barcode("4600494600029", language="ru")
```

## API Server

```bash
# Start the server
ikpu-server

# Or with uvicorn directly
uvicorn ikpu.api:app --host 0.0.0.0 --port 8044
```

### Endpoints

| Method | Path             | Description                  |
|--------|------------------|------------------------------|
| POST   | `/search`        | Search by name or barcode    |
| GET    | `/health`        | Service status               |
| POST   | `/rebuild-cache` | Rebuild TF-IDF indexes       |
| POST   | `/check-update`  | Check for catalog updates    |

### POST /search

```json
{
  "query": "Coca-Cola 0.5",
  "barcode": null,
  "language": "ru",
  "top_k": 5
}
```

## CLI

```bash
# Download/update the IKPU catalog
ikpu-update
```

## Configuration

Data is stored in `~/.ikpu/data/` by default. Override with the `IKPU_DATA_DIR` environment variable:

```bash
export IKPU_DATA_DIR=/path/to/custom/dir
```

## Supported Languages

- `ru` — Russian
- `uz_cyrl` — Uzbek (Cyrillic)
- `uz_latn` — Uzbek (Latin)

## License

MIT
