Update README.md

README.md

@@ -1,13 +1,369 @@
 ---
 license: apache-2.0
-base_model: Qwen/Qwen3-Embedding-0.6B
+base_model:
+- Qwen/Qwen3-Embedding-0.6B
 pipeline_tag: sentence-similarity
+library_name: sentence-transformers
+language:
+- multilingual
 tags:
+- transformers
 - sentence-transformers
+- text-embeddings
+- feature-extraction
+- retrieval
+- rag
+- multilingual
+- semantic-search
+- qwen3
+- alfotech
+model-index:
+- name: alfo-embedding-0.6b
+  results:
+  - task:
+      type: sentence-similarity
+      name: Retrieval (Easy Benchmark)
+    metrics:
+    - type: recall_at_1
+      value: 0.967
+      name: Recall@1
+    - type: recall_at_5
+      value: 0.999
+      name: Recall@5
+    - type: recall_at_10
+      value: 1.000
+      name: Recall@10
+    - type: mrr_at_10
+      value: 0.9815
+      name: MRR@10
+  - task:
+      type: sentence-similarity
+      name: Retrieval (Hard Benchmark, 72,635-doc corpus / 1,000 queries)
+    metrics:
+    - type: recall_at_1
+      value: 0.614
+      name: Recall@1
+    - type: recall_at_5
+      value: 0.883
+      name: Recall@5
+    - type: recall_at_10
+      value: 0.929
+      name: Recall@10
+    - type: mrr_at_10
+      value: 0.7268
+      name: MRR@10
 ---
 
 <p align="center">
   <img src="image.png" width="200"/>
 </p>
 
-# Alfo Embedding 0.6B
+<h1 align="center">Alfo Embedding 0.6B</h1>
+
+<p align="center">
+  <b>Production-oriented multilingual text embedding model by Alfo Tech Industries</b><br/>
+  Built on Qwen3-Embedding-0.6B · Evaluation-first retrieval pipeline
+</p>
+
+<p align="center">
+  <a href="https://huggingface.co/alfotech/alfo-embedding-0.6b"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model-yellow"></a>
+  <a href="#license"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
+  <img alt="Params" src="https://img.shields.io/badge/params-0.6B-lightgrey">
+  <img alt="Context" src="https://img.shields.io/badge/context-32K-lightgrey">
+  <img alt="Languages" src="https://img.shields.io/badge/languages-100%2B-lightgrey">
+</p>
+
+---
+
+## Table of Contents
+
+- [Highlights](#highlights)
+- [Model Overview](#model-overview)
+- [Quickstart](#quickstart)
+- [Development Philosophy](#development-philosophy)
+- [Training Pipeline](#training-pipeline)
+- [Evaluation](#evaluation)
+- [Failure Analysis](#failure-analysis)
+- [Intended Use](#intended-use)
+- [Limitations & Bias](#limitations--bias)
+- [Production Recommendations](#production-recommendations)
+- [Roadmap](#roadmap)
+- [Transparency](#transparency)
+- [Citation](#citation)
+- [License](#license)
+
+---
+
+## Highlights
+
+Alfo Embedding 0.6B is a production-focused embedding model built on **Qwen3-Embedding-0.6B**, optimized through an evaluation-first retrieval pipeline.
+
+Rather than training from scratch, this project focuses on improving real-world retrieval quality through:
+
+- Hard retrieval evaluation
+- Semantic hard-negative analysis
+- Contrastive embedding fine-tuning
+- Retrieval-oriented optimization
+- Production deployment validation
+
+> **Goal:** build practical AI infrastructure for semantic search and Retrieval-Augmented Generation.
+
+---
+
+## Model Overview
+
+| Property | Value |
+|---|---|
+| Model Type | Text Embedding |
+| Base Model | [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B) |
+| Parameters | 0.6B |
+| Context Length | 32K tokens |
+| Default Embedding Dimension | 1024 |
+| Supported Dimensions | 32 – 1024 (Matryoshka-style truncation) |
+| Languages | 100+ |
+| Instruction Aware | Yes |
+| License | Apache-2.0 |
+
+The upstream Qwen3 embedding architecture provides multilingual understanding, long-context retrieval, configurable embedding dimensions, and instruction-aware query encoding. This project extends that foundation with a retrieval-focused fine-tuning and evaluation workflow.
+
+---
+
+## Quickstart
+
+### Install
+
+```bash
+pip install -U sentence-transformers
+```
+
+### Basic encoding
+
+```python
+from sentence_transformers import SentenceTransformer
+
+model = SentenceTransformer("alfotech/alfo-embedding-0.6b")
+
+embeddings = model.encode(
+    [
+        "Artificial intelligence improves search.",
+        "Vector embeddings represent semantic meaning.",
+    ],
+    normalize_embeddings=True,
+)
+```
+
+### Instruction-aware retrieval (recommended for queries)
+
+Qwen3-derived embedding models perform best when queries are prefixed with a retrieval instruction; documents are encoded without one.
+
+```python
+from sentence_transformers import SentenceTransformer
+
+model = SentenceTransformer("alfotech/alfo-embedding-0.6b")
+
+queries = ["How can I optimize transformer inference?"]
+documents = [
+    "Techniques such as quantization, KV-cache reuse, and batching reduce inference latency.",
+    "The stock market closed higher today on strong earnings reports.",
+]
+
+query_embeddings = model.encode(queries, prompt_name="query", normalize_embeddings=True)
+doc_embeddings = model.encode(documents, normalize_embeddings=True)
+
+scores = model.similarity(query_embeddings, doc_embeddings)
+print(scores)
+```
+
+### Reducing embedding dimension
+
+```python
+embeddings = model.encode(
+    ["Shorter vectors for cheaper storage."],
+    normalize_embeddings=True,
+    truncate_dim=256,  # any value from 32–1024
+)
+```
+
+---
+
+## Development Philosophy
+
+Rather than optimizing only for easy benchmarks, the training pipeline intentionally targets difficult retrieval scenarios where semantically similar distractors are present.
+
+```text
+Baseline → Hard Benchmark → Failure Analysis → Hard Negative Mining
+        → Fine-Tuning → Validation → Production Testing
+```
+
+Every optimization decision is driven by measured evaluation rather than intuition.
+
+---
+
+## Training Pipeline
+
+Development was performed in **Google Colab** using dual Tesla T4 GPUs.
+
+**Pipeline components:**
+
+- Retrieval dataset preparation
+- Duplicate removal
+- Quality filtering
+- Validation leakage checks
+- Hard-negative mining
+- Multiple Negatives Ranking Loss with in-batch negatives
+- Continuous retrieval evaluation
+- Production validation
+
+---
+
+## Evaluation
+
+The model is evaluated under both easy and hard retrieval conditions.
+
+### Easy Benchmark
+
+| Metric | Score |
+|---|---|
+| Recall@1 | **0.967** |
+| Recall@5 | **0.999** |
+| Recall@10 | **1.000** |
+| MRR@10 | **0.9815** |
+
+Validates the retrieval pipeline under standard, low-ambiguity conditions.
+
+### Hard Retrieval Benchmark
+
+Corpus: **72,635 documents** · Queries: **1,000**
+
+| Metric | Score |
+|---|---|
+| Recall@1 | **0.614** |
+| Recall@5 | **0.883** |
+| Recall@10 | **0.929** |
+| MRR@10 | **0.7268** |
+
+Introduces semantically similar distractors, making it more representative of production retrieval systems than the easy benchmark alone.
+
+---
+
+## Failure Analysis
+
+| Metric | Value |
+|---|---|
+| Semantic hard negatives identified | **386** |
+| Avg. positive similarity | **0.689** |
+| Avg. top-negative similarity | **0.653** |
+| Avg. margin (positive − negative) | **0.036** |
+| Duplicate contamination detected | **0** |
+| Noisy positives detected | **0** |
+
+The narrow average margin (0.036) between true positives and top hard negatives is the primary remaining bottleneck and is the main target of the next fine-tuning iteration (see [Roadmap](#roadmap)).
+
+---
+
+## Intended Use
+
+**Recommended use cases:**
+
+- Semantic search
+- Retrieval-Augmented Generation (RAG)
+- Enterprise / knowledge-base search
+- FAQ matching
+- Code search
+- Similarity search
+- Vector database indexing
+- Multilingual retrieval
+
+**Out of scope:**
+
+- Text generation, classification, or summarization — this is an embedding-only model, not a generative LLM.
+- High-stakes decisions (legal, medical, financial, safety) made solely from similarity scores without human review.
+- Any use case requiring guarantees on protected or demographic attributes; no such evaluation has been performed (see below).
+
+---
+
+## Limitations & Bias
+
+- Evaluation to date is retrieval-accuracy focused (Recall@k, MRR@10). No dedicated fairness, bias, or demographic-parity audit has been conducted.
+- Hard-benchmark performance (Recall@1 of 0.614) is meaningfully lower than easy-benchmark performance (0.967), so retrieval quality should be validated on your own domain data before production rollout.
+- Long-context (32K) behavior is inherited from the base model and has not been independently re-validated by this project.
+- As with any embedding model, outputs reflect patterns in the underlying pretraining and fine-tuning data and may not generalize evenly across all 100+ supported languages.
+
+---
+
+## Production Recommendations
+
+| Setting | Value |
+|---|---|
+| Sequence Length | 512 |
+| Batch Size | 32 |
+| Normalize Embeddings | Enabled |
+| Similarity Metric | Cosine |
+
+These provide a practical starting balance between retrieval quality and inference throughput — tune per workload.
+
+---
+
+## Roadmap
+
+- Larger, curated retrieval datasets
+- Better hard-negative refinement (targeting the 0.036 avg. margin)
+- Domain-specific adaptation
+- Full blind evaluation
+- Extended benchmark coverage
+- Additional deployment optimizations
+
+---
+
+## Transparency
+
+This repository prioritizes reproducibility. Current documentation includes training methodology, retrieval evaluation, hard-benchmark results, production inference examples, and deployment recommendations.
+
+External benchmark leaderboard claims are intentionally omitted unless independently measured.
+
+---
+
+## Citation
+
+If this project helps your work, please cite both the upstream Qwen3 Embedding paper and this repository.
+
+**Qwen3 Embedding**
+
+```bibtex
+@article{qwen3embedding,
+  title={Qwen3 Embedding: Advancing Text Embedding and Reranking Through Foundation Models},
+  author={Zhang, Yanzhao and Li, Mingxin and Long, Dingkun and others},
+  journal={arXiv preprint arXiv:2506.05176},
+  year={2025}
+}
+```
+
+**Alfo Embedding**
+
+```bibtex
+@misc{alfotech_alfo_embedding_2026,
+  title={Alfo Embedding 0.6B},
+  author={Alfo Tech Industries},
+  year={2026},
+  publisher={Hugging Face},
+  url={https://huggingface.co/alfotech/alfo-embedding-0.6b}
+}
+```
+
+---
+
+## Acknowledgements
+
+This project builds upon the open-source **Qwen3-Embedding-0.6B** foundation model, whose multilingual and long-context embedding architecture made this work possible.
+
+## License
+
+Apache-2.0, inherited from the upstream Qwen3-Embedding-0.6B model.
+
+---
+
+<p align="center">
+<b>Built by Alfo Tech Industries</b><br/>
+<i>Building practical AI infrastructure for developers, startups, and enterprises.</i><br/>
+<a href="https://github.com/Alfo-Tech-Lab">GitHub</a>
+</p>