Metadata-Version: 2.4
Name: fewshotkit
Version: 0.0.1
Summary: Embedding-based few-shot learning library for keyword spotting and related tasks
Author: fewshotkit contributors
License: MIT
Project-URL: Homepage, https://github.com/example/fewshotkit
Project-URL: Repository, https://github.com/example/fewshotkit
Keywords: few-shot,keyword-spotting,embedding,protonet,matching-network
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: scikit-learn>=1.4; extra == "dev"

# fewshotkit

`fewshotkit` là thư viện Python cho bài toán **few-shot learning dựa trên embedding** (đặc biệt phù hợp với Keyword Spotting).

Mục tiêu của thư viện:
- Nhẹ, dễ dùng, API gần giống sklearn.
- Không chứa encoder (bạn tự tạo embedding từ pipeline khác).
- Chạy offline, deterministic, tập trung vào suy luận few-shot.

---

## 1. fewshotkit giải quyết bài toán gì?

Bạn đã có embedding vector (NumPy) và muốn:
- Huấn luyện nhanh từ ít mẫu support (`fit`).
- Dự đoán class cho query (`predict`).
- Lấy xác suất cho từng class (`predict_proba`).
- Đánh giá bằng episodic few-shot (`evaluate_n_way_k_shot`).

fewshotkit **không** trích xuất đặc trưng từ audio thô, chỉ làm việc trên embedding đầu vào.

---

## 2. Cài đặt

### Cài đặt cơ bản
```bash
cd /home/ngocan/Projects/KWS_Project/Fewshot
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### Cài đặt cho phát triển (test/lint/benchmark)
```bash
pip install -e .[dev]
```

---

## 3. Kiểm tra nhanh môi trường

Đảm bảo `python` và `pip` cùng một virtualenv:

```bash
which python
python -c "import sys; print(sys.executable)"
```

Cả 2 lệnh nên trỏ về:
`/home/ngocan/Projects/KWS_Project/Fewshot/.venv/bin/python`

---

## 4. Định dạng dữ liệu đầu vào

### Input chuẩn cho model
- `X_support`: `np.ndarray`, shape `(N, D)`
- `y_support`: `np.ndarray`, shape `(N,)`
- `X_query`: `np.ndarray`, shape `(M, D)`

### Output
- `predict(X_query)`: shape `(M,)`
- `predict_proba(X_query)`: shape `(M, num_classes)`

### Lưu ý
- `D` (embedding dimension) phải nhất quán giữa support/query.
- `y_support` có thể là số hoặc chuỗi.
- Nếu shape sai, thư viện sẽ raise `ValueError` rõ ràng.

---

## 5. API chính

Import public API:

```python
from fewshotkit import (
    ProtoNet,
    SiameseKNN,
    MatchingNet,
    evaluate_n_way_k_shot,
)
```

Tất cả model đều hỗ trợ:
- `fit(X, y)`
- `predict(X)`
- `predict_proba(X)`
- `score(X, y)`
- `add_class(label, embeddings)`
- `remove_class(label)`

---

## 6. Dùng từng model

### 6.1 ProtoNet (khuyên dùng để bắt đầu)

```python
import numpy as np
from fewshotkit import ProtoNet

x_support = np.array([[0.0, 0.0], [0.1, 0.0], [1.0, 1.0], [1.1, 1.0]])
y_support = np.array(["off", "off", "on", "on"], dtype=object)
x_query = np.array([[0.05, 0.0], [1.05, 1.0]])

model = ProtoNet(metric="cosine")  # hoặc metric="euclidean"
model.fit(x_support, y_support)

pred = model.predict(x_query)
proba = model.predict_proba(x_query)
```

Cơ chế: tính centroid cho từng class rồi so sánh query với centroid.

### 6.2 SiameseKNN

```python
from fewshotkit import SiameseKNN

model = SiameseKNN(metric="euclidean", k=3)
model.fit(x_support, y_support)
pred = model.predict(x_query)
```

Cơ chế: so similarity tới toàn bộ support, voting theo top-k.

### 6.3 MatchingNet

```python
from fewshotkit import MatchingNet

model = MatchingNet(metric="cosine")
model.fit(x_support, y_support)
pred = model.predict(x_query)
```

Cơ chế: attention softmax giữa query và support để tính xác suất lớp.

---

## 7. Unknown detection (phát hiện ngoài tập lớp)

Bạn có thể set ngưỡng để trả về nhãn unknown khi độ tương đồng thấp:

```python
from fewshotkit import ProtoNet

model = ProtoNet(metric="cosine", threshold=0.8, unknown_label="unknown")
model.fit(x_support, y_support)
pred = model.predict(x_query)
```

Nếu score tốt nhất < `threshold` thì output là `unknown_label`.

---

## 8. Thêm/Xóa class động

```python
model.add_class("maybe", np.array([[0.5, 0.5], [0.6, 0.5]]))
model.remove_class("maybe")
```

Hữu ích khi cần enroll class mới mà không train lại pipeline encoder.

---

## 9. Đánh giá episodic few-shot

```python
import numpy as np
from fewshotkit import ProtoNet, evaluate_n_way_k_shot

x = np.random.randn(300, 64)
y = np.repeat(np.arange(10), 30)

model = ProtoNet(metric="euclidean")
result = evaluate_n_way_k_shot(
    model,
    x,
    y,
    n_way=5,
    k_shot=5,
    n_query=10,
    n_episodes=100,
    random_state=42,
)

print(result["accuracy_mean"], result["accuracy_std"])
```

Kết quả trả về gồm:
- `accuracy_mean`
- `accuracy_std`
- `episode_accuracies`
- metadata episode (`n_way`, `k_shot`, `n_query`, `n_episodes`, `random_state`)

---
