Ottava-Few-Shot-Adapter

Few-shot semantic grouping with frozen LLM embeddings.

A small, harness-agnostic semantic grouping toolkit. Bring your own schema, 10–20 labeled support examples, and unlabeled items. Ottava fits a tiny per-schema scorer over frozen Qwen/Qwen3-1.7B embeddings and assigns each item to one of your labels.

It does not generate text, fine-tune Qwen, infer the number of groups, or follow unseen instructions zero-shot. Labels and K are supplied by you.

Quick start: adapt to your schema

1. Install the Ottava code:

   pip install git+https://github.com/OscarVGit/ottava.git
   

2. Copy schema.example.json to your own schema.json and edit:

   {
     "name": "my_schema",
     "instruction": "Group the items by my criterion.",
     "labels": ["label_a", "label_b"],
     "support_cases": [
       {"items": ["example one"], "labels": ["label_a"]},
       {"items": ["example two"], "labels": ["label_b"]}
     ]
   }
   

   schema.example.md shows the same format in Markdown.

3. Fit and predict:

   python fit_and_predict.py \
     --schema schema.json \
     --tasks '["new item one", "new item two"]'
   

The first run fits and caches a per-schema scorer. Later identical requests reuse it.

Use the included example checkpoint

example/sentiment/ contains a small sentiment example fitted to negative / neutral / positive:

python fit_and_predict.py \
  --checkpoint example/sentiment \
  --tasks '["The product is excellent.", "The product is terrible."]'

The checkpoint is schema-specific. Do not reuse its label embeddings for a different schema; fit your own schema instead.

Repository contents

README.md                 this card
requirements.txt          runtime dependencies
schema.example.json       editable schema template
schema.example.md         Markdown schema example
fit_and_predict.py        fit or load, then group target items
example/sentiment/        optional fitted sentiment checkpoint
  ├── adapter.json
  ├── config.json
  ├── head.pt
  └── label_embeddings.npz

No base-model weights are included. Download Qwen/Qwen3-1.7B separately.

What the method does

1. Encode support and target items with frozen Qwen.
2. Standardize item features using support statistics.
3. Build label vectors from label prompts and support centroids.
4. Fit a small regularized linear scorer for this schema.
5. Cache the scorer and assign target items to labels.

The adapter is support-conditioned. It is not a universal pretrained grouping model; each schema gets its own fitted scorer.

Use cases

This method fits best when you already know the labels or categories you want, can provide a small set of labeled examples, and need to group a batch of short text items consistently.

• Support and feedback triage: group tickets or messages into your own routing labels, such as billing, account, technical, or general.
• Survey and open-response labeling: apply a fixed codebook to free-text survey answers so the same categories are used across respondents.
• Product review analysis: separate reviews by sentiment, theme, feature, or complaint type using your own schema.
• Document and email routing: assign incoming text to teams, queues, or priority buckets defined by representative examples.
• Qualitative research: apply an analyst-defined codebook to interview notes or open comments, with human review of low-confidence assignments.
• Content operations: group headlines, listings, posts, or reports into moderation, ownership, or topic categories.
• Taxonomy assignment: map short items to an existing label set when you want repeatable assignments rather than free-form generation.
• Near-duplicate grouping: optionally append lexical features for batches where wording overlap is a strong signal.
• Private or local grouping: run the encoder and scorer locally when sending items to an external service is undesirable.
• Human-in-the-loop labeling assistance: propose groups for review, then correct and reuse the corrected support set to refit the schema.

Where an LLM may still be better

This is not the right tool for discovering unknown categories, inferring the number of groups, following a complex criterion with no support examples, or reasoning over long documents. An LLM is often more flexible for zero-shot or open-ended cases.

Performance note

No speed benchmark is claimed here, and actual latency depends on hardware, batch size, model loading, and embedding cost. In general, for clustering or grouping cases where the labels are already defined, this path is much faster than asking an LLM to read, reason over, and cluster every item, because it does not generate text and can reuse a cached per-schema scorer.

Intended use

• Human-reviewed or shadow-mode grouping of short text items.
• Few-shot schemas with caller-supplied labels.
• Experimentation with arbitrary label sets and support examples.

Out of scope

• Zero-shot grouping of criteria absent from the support set.
• Unsupervised clustering or automatic K inference.
• Automatic merging, scheduling, or safety-critical decisions.
• Non-English or long-document inputs without validation.

Data and evaluation

The example checkpoint uses 20 hand-written sentiment support cases. No personal or user data is included. It is a loading/demo artifact and has not been validated as a production sentiment classifier.

Base model and license

• Base model: Qwen/Qwen3-1.7B
• Base-model license: Apache-2.0
• Example checkpoint and scripts: Apache-2.0

Review the base-model license before redistribution or commercial use.