Why Gemma 3 for Arabic?

Gemma 3 stands out for three reasons when working with Arabic:

1. Multilingual training : Google trained on diverse Arabic web text, not just English unlike qwen models thay are better at coding but not arabic langauge.
2. Efficiency : 1B parameters run fast even on limited hardware (critical for accessibility) I am using it on my amd cpu :)

The 1B variant is particularly interesting: small enough to fine-tune on a single GPU, yet capable of learning structured outputs like tool calls.

Arabic Tool Calling with gemma

My goal is to fine-tune a gemma model to be good at on-device application and be able to use grep efficiently without the need for Embedding models and Rag systems.

We know that Arabic search tools struggle with:

• Morphological complexity — Arabic words have many forms (كتب، يكتب، كاتب، مكتوب)
• Dialect diversity — Modern Standard Arabic vs. regional variations
• Resource scarcity — Less training data than English

Our approach: teach the model to extract keywords and delegate to grep, a battle-tested tool that handles Arabic text well.

This shifts the burden from the LLM (which might hallucinate) to proven infrastructure.

Building Training Data

We started with MIRACL, a multilingual retrieval benchmark with Arabic passages and questions.

But we needed tool-calling examples.

Our approach was simple but effective:

1. Take the human-written queries from MIRACL
2. For each query, identify a single keyword that would find the relevant passage via grep with its variants.

3. Format as Gemma 3 chat: user query → assistant tool call This gave us 6,217 synthetic (query, keyword) pairs for training without manual annotation.

This is done with just a python code script.

Evaluation Reality

We built a 96-question test set from SILMA.

Our metric was simple: does grep(keyword="...") find the correct document? When everything returned 0%, we debugged.

The issue wasn’t the model architecture , it was format consistency.

Learned Lessons

1. Don’t fine-tune the whole model on just toolcalling after 2000 samples or more it will start losing it’s ability to answer normal question.

I will share the code and the results soon!

For more on retrieval without embeddings, see Late Interaction & ColPali and BM25 Arabic Search with Qdrant. Also check out my CV of Failures for the lessons learned along the way.

2019 corona Period

• Didn’t get Engineering degree; it was 94%, but I got 91.9% instead
• Didn’t succeed in going to ZewailCity university due to financial status, not exams

2021

No thing to mention

2022

• Solved only 2 problems alone without the team in the ACPC competition after 6 months of daily Codeforces practice
• Failed to pass technical interview with Dr. Fady, and I don’t even remember the company

2023

• Didn’t complete my networking course
• Failed to join a medical company working on 3D imaging

2024

• Multiple failures with several SEO websites that I thought would generate income, like awazly. There were around 12 different website ideas.

2025

• Didn’t get accepted in MBZUAI master Internship
  • After that, I did some research that was better than multiple researchers at MBZUAI. I thought working with them would be a huge career change, but you can achieve a lot alone!
• Didn’t get accepted in huggingface internship program

2026

• Didn’t get accepted at Bizarh competition

More failures are coming soon! wish me luck :)

Looking back, the pattern is clear: most of my rejections came from timing or circumstances, not ability. The MBZUAI rejection pushed me to do independent research that turned out better than what I’d have done there. The failed SEO websites taught me more about business than any course could. A CV of failures isn’t about dwelling on the past — it’s about seeing the thread that connects them to where you end up.

Building PC for AI research HackerRank AI Interview LiteRT and QAI Hub Vector Databases Book Review

Why Not Colab or Cloud Providers?

RunPod would cost me around $500 to $900 per month, so in less than a year I would spend more than $9,600.

Renting an A100 on Colab costs around 10,800 compute units, which is about $1,000.

With cloud solutions, the hardware is also much more limited compared to a local PC build. Here is a detailed comparison:

With a local PC, I have no session time limits, no data transfer restrictions, and full control over my hardware.

The investment pays for itself in less than a year compared to cloud costs.

Why Local Servers Are Not a Good Option in Egypt?

Building a local server in Egypt comes with some serious challenges.

First, internet bandwidth is limited in Egypt.

AI research requires downloading

large datasets and models, which can be several gigabytes or even terabytes.

This will exhaust your internet subscription very quickly and become very costly.

Second, electricity costs have increased significantly due to the current economic situation, making it expensive to run power-hungry server hardware 24 hours a day.

Third, there are frequent power outages, especially in summer, which can interrupt long training runs that may take days to complete.

A personal PC with a UPS (uninterruptible power supply) is a much more practical and controllable solution for this environment.

Components I Bought

Before You Start Buying

Stores I Bought From and My Rating

It’s Art and Engineering at the Same Time

Building this PC was a truly rewarding journey.

I learned a lot of new concepts along the way and genuinely enjoyed every step of the process.

This post was a quick overview of the experience.

Once I get the RTX 5090, I will share much more detailed content about the actual AI research and fine-tuning process.

Stay tuned! Kareem AI Blog LiteRT Review HackerRank AI Interview Vector Databses Book Review GPUVec: Cloud GPU Pricing Comparison CV of Failures: Rejections Build Career

Prompt Engineering

It’s a question about creating a prompt for an LLM to do some finance equations, to test if the model will answer the user correctly.

It’s a very simple and easy question, but the problem is:

what model are they using to follow the prompt?

There are 6 questions.

4 of them need the output to be just a number, and 2 need it to be in the following format:

• Final Price: $42, Discount Price: $23

When you try to instruct the LLM to do this, it fails.

I don’t think there is room to improve this, the model is very small and doesn’t follow instructions correctly.

This doesn’t assess how much knowledge you have about small LLMs and how to use them.

That’s a different story.

SQL Question

A SQL question about using aggregations and aliases, a medium-difficulty question.

But the hard part was that the answer shouldn’t be in table format and should be tab-separated.

As someone who has been working with SQL through ORMs for all my use cases, I had never encountered this case, so I spent around an hour figuring out how to do it.

I don’t think this assesses anything more than just syntax.

RAG Built with LangChain, LangGraph, and FAISS

Two Python files where you need to fill in the missing methods.

The problem here is that to write these methods, you must remember the exact syntax for these specific tools — which I don’t even use.

I use DSPy and Qdrant for most of my work. I’ve used FAISS before, but I’m not going to memorize how to import its modules.

Final Thoughts

Using HackerRank for this type of role, if it shows anything, it shows that the people running the interview don’t know much about AI engineering.

read more : LiteRT and Qualcomm AI Hub Vector Databases Book O’reilly CV of Failures: Rejections Build Career Abdelkareem Elkhateb HackerRank

Why On-Device Inference?

Running models on-device instead of a remote server has several practical advantages:

• Privacy: user data never leaves the device
• Latency: no network round-trip, response is immediate
• Offline: works without internet connectivity
• Cost: no cloud inference bill

These benefits come with a tradeoff: constrained compute, memory, and power budget on the device.

What is LiteRT?

LiteRT is Google’s on-device ML runtime for Android, iOS, embedded Linux, and microcontrollers.

It is the direct successor to TensorFlow Lite, with the same .tflite flatbuffer format.

The core runtime supports three execution backends:

• CPU via XNNPACK (default, broad op coverage)
• GPU via OpenGL ES / Vulkan delegates
• NPU via vendor-specific delegates (Qualcomm, MediaTek, etc.)

Models are converted to .tflite format from PyTorch, TensorFlow, or JAX using the litert-torch or ai-edge-torch Python libraries.

Converting a PyTorch Model to LiteRT

The conversion path from PyTorch to .tflite uses the litert-torch library:

import torch
import litert_torch

# Your model must be an nn.Module returning tensors (not dicts)
model.eval()
sample_inputs = (torch.randn(1, 438, 160),)

tflite_model = litert_torch.convert(model, sample_inputs)
tflite_model.export("model.tflite")

Key requirements:

• Model must use torch.export compatible ops
• Inputs and outputs must be tensors or tuples of tensors (no dicts)

Benchmarking on a Real Device Without Writing Any App Code

One underappreciated feature of LiteRT is that you can benchmark a .tflite model directly on a real Android device using ADB, with no app development required.

First, install the benchmark APK:

wget https://storage.googleapis.com/tensorflow-nightly-public/prod/tensorflow/release/lite/tools/nightly/latest/android_aarch64_benchmark_model.apk
adb install -r -d -g android_aarch64_benchmark_model.apk

Push your model and run:

adb push model.tflite /data/local/tmp/
adb shell am start -S \
  -n org.tensorflow.lite.benchmark/.BenchmarkModelActivity \
  --es args '"--graph=/data/local/tmp/model.tflite --num_threads=4"'

Read results:

adb logcat | grep "Inference timings"

This gives you real latency numbers on your target hardware in minutes.

When You Need Qualcomm AI Hub

The ADB approach runs your model on the CPU delegate by default. To unlock the Qualcomm NPU (Hexagon DSP), you need to compile the model specifically for that chip. This is where Qualcomm AI Hub comes in.

AI Hub has three products:

• Models: pre-optimized models ready to download and deploy
• Apps: sample Android app code to bundle models
• Workbench: compile and profile your custom model on 50+ hosted Qualcomm devices

The Workbench workflow in Python:

import qai_hub

model = qai_hub.upload_model("model.tflite")
job = qai_hub.submit_compile_job(
    model,
    device=qai_hub.Device("Snapdragon 8 Gen 2"),
    options="--target_runtime tflite"
)
compiled_model = job.download_target_model()

The topics

1. Intro to databases
2. Embeddings
3. FAISS
4. SQLite3
5. POstgresSQL pygvector
6. SQLite and Ollama
7. Complete RAG system app
8. Vector Query Language.

shiny and nice topics.

Vector database Book Review.

When you read the book you would feel it’s not connected with each other in a nice way. it’s like listing some information from GitHub pages without the sense of teaching.

a lot of chapters listing info that is specific to Project which if i need it i will read GitHub page.

The Charts are not that helpful they don’t add more value just an overview it’s more like AI generated one. It maybe not AI but not much helpful.

You feel there is a gab between the depth of knowledge and the titles. shiny titles.

I hoped it was more detailed more to concepts with nice explaining that works with any vector database.

• Example the FAISS chapter :
  • it gives all the indexing types in FAISS and quick overview about quantization that is bad then benefit and trade offs this is style of book!

My Recommendation.

Any Vector database Articles are far helpful and much better like :

Quarto Blogs.

Weaviate

What is HyperRun ?

HyperRun lets developers add a semantic code search chat widget to their docs.

Built on ColGrep for indexing, Lisette for LLM orchestration, and FastHTML for the UI.

Why ColGrep

Most coding agents still use grep to search codebases.

It works — but it’s pure pattern matching.

If you don’t know the exact function name, you’re stuck guessing.

Semantic search (RAG) solves this but introduces problems:

• Requires remote storage of your code (security concern)

• Needs a separate vector DB service running

• Keeping the index in sync with a fast-moving codebase is hard

ColGrep takes a completely different approach. It’s a Rust CLI tool built by LightOn that:

• Mirrors the grep interface — agents already know how to use it

• Runs entirely locally — no remote storage, no separate API service

• Uses late-interaction retrieval (ColBERT-style) via LateOn-Code models — not traditional embeddings

  • We are using their specialized coding retrieval model 17M

• Supports hybrid queries — regex filtering first, then semantic ranking on the filtered results

• Incremental index updates — only re-indexes changed files, not the whole repo

  • They are using a nice hashing trick 😎

• Tree-sitter parsing — extracts functions, classes, signatures, call graphs — not just raw text chunks

The results speak for themselves:

• Won 70% of head-to-head comparisons against vanilla grep with Claude Code

• Cut token usage by 15.7% on average

• 56% fewer search operations needed to find the right code

• Hard conceptual questions (where you describe behavior, not function names) benefit the most

Traditional embeddings compress an entire code block into a single vector — losing detail.

Late-interaction models (like ColBERT) keep per-token vectors, so they can do soft matching between query terms and code tokens.

This is why ColGrep handles “find the function that inserts articles into the database” better than a single-vector approach.

For HyperRun, ColGrep is the retrieval layer — it finds the relevant code semantically, then Lisette sends it to the LLM for a conversational answer.

How It Works

HyperRun has two sides — the Doc Author who sets it up, and the End User who asks questions.

<script src="https://your-server/embed"></script>

What’s Next

HyperRun is still early — here’s what I’m working on:

• Citations — show which code snippets the LLM used to answer, so users can verify

• GitHub Actions — auto re-index on push, auto deploy the server — zero manual steps

• Better nbdev support — ColGrep struggles with .ipynb files, so we index the exported .py package for now

• Secure BYOK — move API keys from session cookies to server-side encrypted storage

• Switching embedding models — let doc authors choose which ColGrep model to use

For a deep dive into the streaming UI architecture, see HyperRun Deep Dive: FastHTML, HTMX, and SSE.

If you want to try it or contribute: github.com/abdelkareemkobo/hyperrun

HyperRun’s semantic search is powered by ColGrep which relies on Late Interaction & ColPali for token-level retrieval. If you’re building AI tooling, also check out OpenCode — a programmable AI coding assistant and Fine-Tuning Gemma 3 for Arabic Tool Calling.

FastHTML App Setup

  User types "what does insert_article do?"
        │
        ▼
  ┌──────────┐  POST /ask   ┌──────────────┐
  │  Browser │────────────►│  FastHTML     │
  │  (HTMX)  │             │  /ask route   │
  └──────────┘              └──────┬───────┘
        ▲                          │
        │                          ▼
        │                   ┌──────────────┐
        │                   │ Returns:     │
        │                   │ • user bubble│
        │                   │ • ai bubble  │
        │                   │   (with SSE) │
        │                   │ • new input  │
        │                   │   (OOB swap) │
        │                   └──────┬───────┘
        │                          │
        │  SSE connects to         │
        │  /stream?query=...       ▼
        │                   ┌──────────────┐
        │  sse: message     │  /stream     │
        │◄──────────────────│  async gen   │
        │  sse: message     │      │       │
        │◄──────────────────│      ▼       │
        │  sse: message     │  ┌────────┐  │
        │◄──────────────────│  │ColGrep │  │
        │  sse: close       │  │search  │  │
        │◄──────────────────│  └───┬────┘  │
        │                   │      │       │
        ▼                   │      ▼       │
    marked.parse()          │  ┌────────┐  │
    renders markdown        │  │Lisette │  │
                            │  │AsyncChat│ │
                            │  │+ tools │  │
                            │  └────────┘  │
                            └──────────────┘

Setting up the app means picking your CSS framework and loading the right headers:

from fasthtml.common import *
from fhdaisy import *
from fastlucide import SvgSprites, SvgStyle

icons = SvgSprites()

app, rt = fast_app(
    pico=False,
    hdrs=(
        *daisy_hdrs,
        SvgStyle(),
        CHAT_CSS,
        Script(src="https://unpkg.com/htmx-ext-sse@2.2.3/sse.js"),
        Script(src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"),
    ))

A few things to note:

• pico=False — FastHTML includes PicoCSS by default, we swap it for DaisyUI
• daisy_hdrs — from fhdaisy, loads Tailwind + DaisyUI via CDN
• SvgSprites() — from fastlucide, gives us Lucide icons as inline SVGs
• SSE extension and marked.js are the only external JS we load

That’s the whole frontend stack.

No bundler needed.

The Chat Widget Architecture

def chat_widget():
    return Div(
        icons,
        Label(
            Span(cls="inline-flex items-center gap-2")(
                icons("message-circle", sz=20),
                Span("Ask AI", cls="font-semibold tracking-tight")),
            fr="chat-modal",
            cls="btn btn-primary rounded-full fixed bottom-6 right-6 z-50"),
        Input(type="checkbox", id="chat-modal", cls="modal-toggle"),
        Div(cls="modal")(
            chat_content(),
            Label(cls="modal-backdrop", fr="chat-modal")))

def chat_content(standalone=False):
    box_cls = "w-full h-screen p-0 bg-base-100" if standalone else "modal-box w-11/12 max-w-4xl p-0 ..."
    return Div(
        # header, messages, input form
        cls=box_cls)

def user_bubble(msg):
    return Div(cls="chat chat-end")(
        Div("You", cls="chat-header"),
        Div(msg, cls="chat-bubble chat-bubble-primary"))

Streaming with SSE + HTMX

**Streaming Life Cycle**

  Browser (HTMX)                          Server (FastHTML)
       │                                        │
       │  ── SSE connect /stream ──────────►    │
       │                                        │
       │                              AsyncChat(query, stream=True)
       │                                        │
       │  ◄── sse: message (Span("I'll")) ──    │
       │  ◄── sse: message (Span(" search"))──  │
       │  ◄── sse: message (Span(" the")) ──    │
       │  ◄── sse: message (Span(" code"))──    │
       │           ...                          │
       │  ◄── sse: message (Span("...")) ──     │
       │  ◄── sse: close (Span("")) ────────    │
       │                                        │
       │  disconnect                            │
       │                                        │
       ▼                                        
  hx_on__sse_close fires:
  this.innerHTML = marked.parse(this.textContent)
  
  Raw text ──► Rendered markdown HTML

Why SSE over WebSockets

Chat is one-directional — the server streams tokens to the client.

WebSockets are bidirectional, which is overkill here.

SSE is:

• Built into browsers natively
• Supported by HTMX via a small extension
• Dead simple in FastHTML — just return an EventStream

def ai_bubble_stream(query):
    return Div(
        Span(cls="loading loading-dots loading-sm"),
        hx_ext="sse",
        sse_connect=stream_response.to(query=query),
        sse_swap="message",
        sse_close="close",
        hx_swap="beforeend",
        hx_on__sse_close="this.innerHTML=marked.parse(this.textContent)",
        cls="chat-bubble bg-base-200")

@rt("/stream")
async def stream_response(query: str, sess):
    chat = chats[sid]

    async def generate():
        async for chunk in await chat(query, stream=True):
            text = chunk.choices[0].delta.content
            if text:
                yield sse_message(Span(text))
        yield sse_message(Span(""), event="close")

    return EventStream(generate())

HTMX Patterns We Used

@rt("/ask")
def ask(query: str, sess):
    new_inp = Input(id="query", placeholder="Ask a follow-up question...",
                    hx_swap_oob="true")
    return Div(user_bubble(query), ai_bubble_stream(query)), new_inp

Form(cls="join w-full", hx_post=ask, hx_target="#messages", hx_swap="beforeend")(
    Input(id="query", name="query"),
    Button(icons("send", sz=18)))

@rt("/stream")
async def stream_response(query: str, sess):
    model = sess.get("model", "claude-sonnet-4-20250514")
    api_key = sess.get("api_key", None)

The Embed Trick

@rt("/embed")
def embed_js(req):
    server = f"{req.url.scheme}://{req.url.netloc}"
    js = f"""document.addEventListener('DOMContentLoaded',function(){{
      // creates floating button + iframe pointing to {server}/chat-standalone
    }});"""
    return Response(js, media_type='application/javascript; charset=utf-8')

@rt("/chat-standalone")
def chat_standalone():
    return Html(
        Head(*daisy_hdrs, SvgStyle(), CHAT_CSS,
             Script(src="<https://unpkg.com/htmx.org>"),
             Script(src="<https://unpkg.com/htmx-ext-sse@2.2.3/sse.js>"),
             Script(src="<https://cdn.jsdelivr.net/npm/marked/marked.min.js>")),
        Body(icons, chat_content(standalone=True)))

window.addEventListener('message', function(e) {
    if (e.data === 'hyperrun-close')
        document.getElementById('hr-frame').style.display = 'none'
});

Lessons Learned Using Streaming HTMX

Building HyperRun was mostly smooth — but a few things bit us.

Here’s what to watch for.

yield sse_message(Span(""), event="close")

Input(cls="modal-toggle")  # ✓ checkbox
Label(...)                  # ✗ this breaks the sibling selector
Div(cls="modal")(...)       # modal never opens

Label(...)                  # button can go anywhere before
Input(cls="modal-toggle")  # ✓ immediately before modal
Div(cls="modal")(...)       # ✓ works

Final Thoughts

The stack — FastHTML + HTMX + SSE + DaisyUI — turned out to be surprisingly productive for building a real-time chat widget. No build step, no React, no client-side state management. Just Python functions returning HTML.

You can read more about other related blogs here:

1. HyperRun

2. SeoRat

3. BM25 Search

4. BM25 Explained

5. BM25 Benchmark

Why is SEO Important?

If you do SEO correctly, you can get organic traffic for your website, which is important for making your brand or product visible without paying money.

Why Building SEO Tool?

I am an AI developer and have done SEO in my college years as a passive income source. I have some SEO websites that generate income:

1. شركة عزل اسطح بجدة
2. متجر مكملات غذائية
3. GPU Pricing Compare

Each of these websites is from a different sector and purpose. After some time working on optimizing them using Google Search Console, I found that doing good SEO is not an easy task and it’s more than just having content.

I also found that most SEO tools are cloud solutions with very high pricing compared to what a developer, blogger, or most people can afford — and the value from them is not that much! The hard and important work is still missing.

Building SEO RAT

I will be building SEO_RAT, an SEO tool that really works and helps you based on real gains and guidelines.

My main focus will be to have the following features:

1. Getting real benefits from Google Search Console, not just quick overviews
2. Smart and helpful visualizations
3. Rank Tracker
4. Competitor Analysis
5. Audit (Technical + On-Page SEO)
6. Smart indexing for pages
7. Keyword analysis (using NLP and LLMs)
   1. Semantic Search
   2. Keyword Stuffing Detection
   3. Extract user queries

…and much more features that will all be free and open source.

SEO_RAT Creator

You can find the GitHub repo here: SEO_RAT

My tech stack for this project is:

1. Python (functional style)
2. Solveit
3. fastcore, nbdev, and Jeremy’s style (I hope!)
4. FastHTML

If you find any design issues or have suggestions, I’d be happy to hear from you!

For more on how I approach SEO with NLP and automation, read How I Use NLP to Improve Website SEO and The Curse of SEO.

This is my attempt at building in public.

What is OpenCode?

OpenCode is an AI coding assistant. Different from Cursor, Claude Code, and Copilot.

Key architecture features:

Works everywhere

• Terminal
• IDE extensions
• Desktop app

LSP-enabled Automatically loads Language Server Protocol for your project. LLM gets proper code intelligence.

Multi-session Run multiple agents in parallel on the same project. No conflicts.

Share links Every session gets a shareable link. Good for debugging and code review.

Model flexibility

• GitHub Copilot account
• ChatGPT Plus/Pro account
• 75+ LLM providers via Models.dev
• Local models

The key difference: OpenCode is infrastructure you can build on, not just a chat interface.

OpenCode is Programmer Friendly

OpenCode is built in TypeScript. But you can control it with Python. No TypeScript needed.

How I use it:

1. Run OpenCode as background process on specific port
2. Create Python client that controls the server
3. Use it with DSPy for smarter workflows

Example setup:

opencode server --port 3000

# Python client
class OpenCodeClient:
    def __init__(self, port=3000):
        self.base_url = f"http://localhost:{port}"
    
    def invoke_agent(self, agent, prompt, context=None):
        response = httpx.post(
            f"{self.base_url}/api/sessions",
            json={
                "agent": agent,
                "prompt": prompt,
                "context": context
            }
        )
        return response.json()

Now you have programmatic control. Build whatever workflows you need.

Why This Hybrid Approach?

You could try to simulate OpenCode features in DSPy tool calling. But it won’t be as mature or robust.

What you’d need to rebuild:

• LSP integration
• Multi-session management
• File operations with error handling
• Bash execution with timeouts

OpenCode already has this. Battle-tested.

What DSPy adds: Structured programming and optimization for AI workflows.

Example workflow:

class FigmaToCodeWorkflow(dspy.Module):
    def forward(self, figma_url):
        # DSPy: Analyze Figma design
        analysis = self.analyzer(figma_url=figma_url)
        
        # DSPy: Pick best component
        selection = self.selector(design_analysis=analysis)
        
        # OpenCode: Build it
        result = opencode_client.invoke_agent(
            agent="build",
            prompt=f"Create component: {selection.component_name}",
            context=selection.design_specs
        )
        
        return result

DSPy analyzes and decides. OpenCode executes with proper LSP support.

OpenCode Tools

OpenCode has built-in tools:

• read - Read files
• write - Create/overwrite files
• edit - Modify existing files
• bash - Execute shell commands
• grep - Search file contents
• glob - Find files by pattern
• lsp - Code intelligence (definitions, references)
• webfetch - Fetch web content

You can create custom tools.

Example custom tool:

{
  "tools": {
    "analyze_performance": {
      "command": "python scripts/analyze.py",
      "description": "Analyze code performance"
    }
  }
}

You can also use MCP servers for database access, API integrations, and third-party services.

Specialized Agents

OpenCode has built-in agents:

Build Agent

• Full access to all tools
• Can edit files and run bash commands
• Default agent for development

Plan Agent

• Read-only by default
• All edits set to “ask” permission
• Good for analysis without changes

General Agent

• Multi-step tasks
• Full tool access
• Invoke with @general

Explore Agent

• Fast codebase exploration
• Read-only
• Find files and search code

Create custom agents:

{
  "agent": {
    "security-auditor": {
      "description": "Reviews code for vulnerabilities",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4",
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "read": "allow"
      }
    }
  }
}

Each agent can have:

• Different models
• Different tools
• Different permissions
• Custom skills
• MCP servers

OpenCode Rules (AGENTS.md)

Create AGENTS.md in your project root:

# My Project

## Architecture
- `backend/` - FastAPI server
- `frontend/` - React app
- `agents/` - DSPy workflows

## Standards
- TypeScript strict mode
- All routes in `backend/routes/`
- Tests required

## Context
This is a collaborative coding platform.

Every agent reads this on startup. They understand your project structure and conventions.

Types of rules:

Project rules: AGENTS.md in project root

• Commits to Git
• Shared with team

Global rules: ~/.config/opencode/AGENTS.md

• Personal preferences
• Not shared

Advanced: Reference external files or remote URLs:

{
  "instructions": [
    "docs/standards.md",
    "https://raw.githubusercontent.com/org/rules/main/style.md"
  ]
}

OpenCode Skills

Skills are reusable SKILL.md files. Agents can load them on demand.

Create skills in:

• Global: ~/.config/opencode/skills/
• Project: .opencode/skills/

Example skill:

<!-- .opencode/skills/react-component.md -->
# React Component Skill

Create React components following our patterns:
- Functional components with hooks
- TypeScript for props
- Tailwind for styling

Agent loads skill:

@build use react-component skill to create login form

Good for:

• Coding patterns
• Project conventions
• Reusable workflows

Smart Planning with PLAN.md

Problem: Multiple agents working in parallel duplicate work or miss dependencies.

Solution: Shared PLAN.md file.

How it works:

Create PLAN.md:

# Project Plan

## Authentication [IN PROGRESS - @build-agent-1]
- [x] JWT tokens
- [ ] Refresh logic (CURRENT)
- [ ] Password reset

## Frontend [BLOCKED - waiting on auth]
- [ ] Login form
- [ ] Dashboard

Agent workflow:

Before work:

• Read PLAN.md
• Find available tasks
• Mark [IN PROGRESS - @agent-name]

During work:

• Complete subtask
• Mark [x]
• Add new subtasks

After completion:

• Mark section complete
• Check if blocked tasks can proceed

Impact:

Before PLAN.md:

• 40% wasted work
• Constant manual coordination

After PLAN.md:

• <5% wasted work
• 90% self-coordination

Real example from my Replit clone:

I had agents building features out of order. Agent 1 builds auth while Agent 2 builds login UI (no endpoints exist yet).

Added PLAN.md with dependencies. Agents now check what’s available and what’s blocked. Problem solved.

The Impact

My project timeline: 2 months with OpenCode vs 12 months without.

Time saved:

Infrastructure (3 months)

• LSP integration
• Multi-session management
• File operations
• Bash execution

OpenCode ships all of this.

Coordination (6 months)

• PLAN.md pattern for agent sync
• Multi-session for parallel work
• Discovering this pattern would take months

Debugging (1 month)

• MLflow caught issues early
• Prompt optimization
• Performance improvements

What made the difference:

• Not rebuilding mature infrastructure
• Programmatic control with Python
• Agent coordination patterns
• Observability from day one

MLflow Integration

Attach MLflow to your Python client:

import mlflow

class OpenCodeClient:
    def invoke_agent(self, agent, prompt, context=None):
        with mlflow.start_run():
            # Log inputs
            mlflow.log_param("agent", agent)
            mlflow.log_param("prompt_length", len(prompt))
            
            # Call OpenCode
            result = self._call_opencode(agent, prompt, context)
            
            # Log outputs
            mlflow.log_metric("execution_time", result.duration)
            mlflow.log_metric("files_modified", len(result.changes))
            mlflow.log_text(result.output, "output.txt")
            
            return result

What you get:

Real-time dashboard:

• Which agents are running
• What they’re working on
• Operation duration
• Success/failure rates

Historical data:

• Slow agents
• Prompt optimization opportunities
• Debugging failures
• Performance trends

Cost tracking:

• Token usage per agent
• Model costs per feature
• ROI on different approaches

My setup:

Use decorators for clean code:

@mlflow.trace(name="figma_to_code", span_type=SpanType.CHAIN)
async def figma_to_code(figma_url):
    # Automatically traced
    pass

Key tags I track:

• project_name, figma_url
• model, provider
• Session ID for debugging

Getting Started

1. Install OpenCode

npm install -g opencode

1. Start server

opencode server --port 3000

1. Create Python client

import httpx

class OpenCodeClient:
    def __init__(self, port=3000):
        self.base_url = f"http://localhost:{port}"
    
    def invoke_agent(self, agent, prompt, context=None):
        response = httpx.post(
            f"{self.base_url}/api/sessions",
            json={
                "agent": agent,
                "prompt": prompt,
                "context": context
            }
        )
        return response.json()

1. Set up AGENTS.md Document your project structure and conventions.

2. Configure agents Create specialized agents for different tasks.

3. Add PLAN.md For multi-agent coordination.

4. Integrate MLflow For observability and tracking.

Summary

OpenCode provides:

• Mature code operations (LSP, file management, multi-session)
• Programmatic control (run as server, control with Python)
• Flexible configuration (agents, tools, rules, skills)
• Multi-agent coordination (PLAN.md pattern)

Why it matters:

• Don’t rebuild infrastructure
• Focus on your product
• Build custom workflows
• Production-ready from day one

The architecture is what makes it different. Not just another chat interface.

Resources:

• OpenCode docs: opencode.ai
• Follow updates: [@AbdelkareemElk1]

Related Posts:

• DSPy: Concepts and Exploration
• Building SEO RAT: A Free, Open-Source SEO Tool
• HyperRun: Self-Hosted AI Docs Chat Widget
• Super Productivity: Best Free Todo App

Why It Wins

1. Free & open source: no subscriptions, no limits
2. Cross-platform: Linux, Windows, Mac, Android, web
3. Simple to start, deep when you need it: hidden gems everywhere 💎
4. Keyboard-first: fast for power users
5. No vendor lock-in: export to JSON or CSV anytime

How I Use It Daily

I use it for development, research, and learning projects.

Here’s a snapshot of my today tasks:

• Parent tasks show total estimated time
• Subtasks track time individually
• Repeating tasks for daily habits
• Gamified “Finish Day” button celebrates your wins 🎉

Features I Love

End of Day Flow

When you hit “Finish Day”, you get 3 steps:

1. Review: summary of what you did

2. Evaluate: rate your day

3. Plan Tomorrow: set up the next day

Also includes calendar integration,linear, github..etc!

Task X #blogging 2h @work

Super Productivity vs Todoist

I switched from Todoist after using it for about a year. Here’s the honest comparison:

Bottom line: if you work solo and care about time tracking, offline access, or don’t want a subscription — Super Productivity wins. Todoist is better if you need team collaboration or a more polished mobile experience.

Is Super Productivity Completely Free?

Yes. Completely free, no ads, no premium tier, no data collection. It’s fully open source (GitHub). You can use every single feature without paying anything — ever.

What I Don’t Like

1. Dated icons: the icons are old and search for specific one hard
2. No Gantt chart: would help for longer projects
3. Sync conflicts: when using two devices simultaneously, it asks which data to keep. Apps like TickTick handle this more smoothly. I wish there was smarter merging.

FAQ: Super Productivity

Final Thoughts

There are features I still haven’t explored. The developer responds quickly and respectfully to issues.

Remember this all in a free app without ads, data leakage,…etc!

Give it a try: super-productivity.com

More Resources

If you’re interested in more tool reviews or my journey in AI, check out these posts:

1. Getting back to RSS
2. One Plus Pad 3 Review
3. Huawei Freebuds 7i Review

You can also explore my Research Papers or see my Open Source Projects.

muaalem El Quran: A New Chapter

I’m building a habit of daily TIL (Today I Learned) posts to improve my learning and share knowledge with others. This blog is part of that journey.

I’m excited to share my work on muaalem El Quran , an open-source Quranic recitation model developed by Abdalla Amal.

It’s designed as an alternative to Tarteel for the developer community, enabling anyone to build their own solutions on top of it.

We have an ambitious roadmap ahead. I joined the team as an open-source contributor focusing on:

• AI model optimization

• Inference acceleration

• Deployment infrastructure

El muaalem Before Ramadan

We have two months before Ramadan and several deliverables for both business partners and open-source projects like Quran Foundation.

Model Optimization (Wav2Vec2Bert)

model = torch.compile(model)

session = ort.InferenceSession(
    "model.onnx",
    providers=["CUDAExecutionProvider"]
)

trt_options = {
    "trt_fp16_enable": True,
    "trt_engine_cache_enable": True,
    "trt_engine_cache_path": "trt_cache",
    "trt_cuda_graph_enable": True,
}

session = ort.InferenceSession(
    "model.onnx",
    providers=[
        ("TensorrtExecutionProvider", trt_options),
        "CUDAExecutionProvider"
    ]
)

# Convert model
converter = TransformersConverter("wav2vec2bert_base")
converter.convert("ct2_model", quantization="int8")

# Load and run
encoder = ctranslate2.models.Wav2Vec2Bert(
    "ct2_model", 
    device="cuda", 
    compute_type="int8"
)

Serving the Model

With optimization complete, we needed a production-ready API. We chose LitServe a lightweight Python framework that integrates seamlessly with our TensorRT-optimized model.

class TensorRTAPI(ls.LitAPI):
    def setup(self, device):
        # Load ONNX model with TensorRT provider
        # Initialize tokenizers for all 11 output heads
        
    def decode_request(self, request):
        # Receive audio file upload
        # Load and preprocess with librosa
        # Extract features with HuggingFace processor
        
    def predict(self, input_features):
        # Run TensorRT inference
        # Return logits for all heads
        
    def encode_response(self, outputs):
        # CTC decode each head
        # Return JSON with all predictions

curl -X POST http://localhost:8000/predict \
  -F "audio=@recitation.wav"

{
  "phonemes": "ءِنَلَاهَبِكُلِشَيءِنعَلِۦمُ",
  "ghonna": "[لا غنة][مغن][لا غنة]",
  "qalqla": "[لا قلقلة]",
  ...
}

The Dependency Hell with ONNX

Okay let me be real with you.

I spent more time fighting package versions than actually optimizing the model. Not joking.

So you install librosa because you need audio stuff. It pulls in numba. Numba wants numpy<=2.0. Fine whatever.

Then you need onnxruntime-gpu. Guess what? It wants numpy>=2.1.

Everything breaks. You Google. Stack Overflow says “just downgrade”. You downgrade. Now onnxruntime breaks. Great.

And don’t get me started on ctranslate2 — the moment you install it, it downgrades like 5 packages you didn’t even know you needed.

The TensorRT disaster:

I ran uv pip install tensorrt. Waited. And waited. 12 hours later — still downloading. I gave up and went to sleep.

Next day I found out you need NVIDIA’s special index:

pip install tensorrt --extra-index-url https://pypi.nvidia.com

Took 30 mins. WHY IS THIS NOT THE DEFAULT.

Honestly? Just use different virtual environments. Don’t be like me trying to fit everything in one place. Your sanity is worth more.

Key Learnings

1. Know your hardware: GTX 1660 Ti lacks Tensor Cores, so FP16 without TensorRT hurts performance

2. TensorRT is powerful: Even on consumer GPUs, it provides significant speedups

3. Cache your engines: TensorRT engine building is slow; always enable caching

4. INT8 is viable: CTranslate2’s INT8 quantization offers good speedups with minimal accuracy loss

5. Profile first: Don’t assume — measure each optimization’s actual impact

There is more to come, and for the other part of optimization I am still exploring… Thanks!

Dataset Benchmark

I will continue exploring the bm25 and how to use with a huggingface dataset with multiple implementations and compare their speed

The methods i will use:

1. Normal Python Calculations
2. Spicy sparse matrix with python loops
3. Spicy sparse matrix with Numpy Vectorization
4. Rank_bm25
5. bm25-sparse
6. Polars optimization

If there is any mistake please tell me!

it’s first time for me to create a benchmark for anything

from datasets import load_dataset
import time
import random

# Load dataset
dataset = load_dataset("rotten_tomatoes", split="train")
corpus = [item["text"] for item in dataset]
print(f"Corpus size: {len(corpus)} reviews")


def generate_random_queries(corpus, num_queries=1000):
    queries = []
    for _ in range(num_queries):
        doc = random.choice(corpus)
        words = tokenize(doc)
        num_words = random.randint(2, 4)
        if len(words) >= num_words:
            query_words = random.sample(words, num_words)
        else:
            query_words = words
        queries.append(" ".join(query_words))
    return queries


test_queries = generate_random_queries(corpus, 1000)
print(f"Generated {len(test_queries)} test queries")

Corpus size: 8530 reviews
Generated 1000 test queries

def benchmark_python_loops():
    print("=== 1. NORMAL PYTHON (LOOPS) ===")
    start = time.time()

    # Tokenize all documents
    all_docs_terms_py = []
    for doc in corpus:
        tokens = tokenize(doc)
        all_docs_terms_py.append(Counter(tokens))

    # Compute DF
    df_py = {}
    for doc_tf in all_docs_terms_py:
        for term in doc_tf.keys():
            df_py[term] = df_py.get(term, 0) + 1

    # Average doc length
    total_len = sum(sum(doc_tf.values()) for doc_tf in all_docs_terms_py)
    avg_doc_len_py = total_len / len(corpus)

    # IDF function
    def compute_idf_py(term, df_dict, N):
        if term not in df_dict:
            return 0
        return np.log((N - df_dict[term] + 0.5) / (df_dict[term] + 0.5))

    # BM25 function
    def bm25_score_py(term, doc_tf, idf_val, doc_len, avg_len, k1=1.5, b=0.75):
        tf = doc_tf.get(term, 0)
        if tf == 0:
            return 0
        return idf_val * tf * (k1 + 1) / (tf + k1 * (1 - b + b * (doc_len / avg_len)))

    index_time = time.time() - start

    # Query
    start_query = time.time()
    for query in test_queries:
        query_tokens = tokenize(query)
        doc_scores = [0] * len(corpus)
        for token in query_tokens:
            if token in df_py:
                idf_val = compute_idf_py(token, df_py, len(corpus))
                for doc_idx, doc_tf in enumerate(all_docs_terms_py):
                    doc_len = sum(doc_tf.values())
                    doc_scores[doc_idx] += bm25_score_py(
                        token, doc_tf, idf_val, doc_len, avg_doc_len_py
                    )
        top_k = sorted(
            range(len(doc_scores)), key=lambda i: doc_scores[i], reverse=True
        )[:10]

    query_time = time.time() - start_query
    qps = len(test_queries) / query_time

    print(f"Indexing: {index_time:.4f}s")
    print(f"Query time: {query_time:.4f}s")
    print(f"QPS: {qps:.2f}\n")

    return index_time, query_time, qps


benchmark_python_loops()

=== 1. NORMAL PYTHON (LOOPS) ===
Indexing: 0.0801s
Query time: 23.6460s
QPS: 42.29

(0.08005261421203613, 23.645965099334717, 42.29051323551751)

Why Sparse Matrices?

Right now, to search for “python programming”, you’d need to: 1. Loop through each document 2. Calculate BM25 score for “python” 3. Calculate BM25 score for “programming” 4. Add them up

That’s slow for large datasets!

The key insight: We can pre-compute ALL BM25 scores for ALL words in ALL documents and store them in a matrix. Then searching becomes just looking up rows and adding them.

Here’s what the matrix looks like conceptually:

               Doc0   Doc1   Doc2
python         -0.51  -0.56   0.00
programming    -1.95  -2.14  -1.79
java            0.00   0.00   2.20

def benchmark_sparse_python_loops():
    print("=== 2. SPARSE MATRIX WITH PYTHON LOOPS ===")
    start = time.time()

    # Tokenize
    all_docs_terms_sp = []
    for doc in corpus:
        tokens = tokenize(doc)
        all_docs_terms_sp.append(Counter(tokens))

    # Get all words and create word_to_idx
    all_words_sp = list(set(word for doc in all_docs_terms_sp for word in doc))
    word_to_idx_sp = {word: idx for idx, word in enumerate(all_words_sp)}

    # Compute DF
    df_sp = {}
    for doc_tf in all_docs_terms_sp:
        for term in doc_tf.keys():
            df_sp[term] = df_sp.get(term, 0) + 1

    # Average doc length
    avg_doc_len_sp = sum(sum(doc_tf.values()) for doc_tf in all_docs_terms_sp) / len(
        corpus
    )

    # Build sparse matrix
    rows_idx = []
    cols_idx = []
    data = []

    for word_idx, word in enumerate(all_words_sp):
        idf_val = np.log((len(corpus) - df_sp[word] + 0.5) / (df_sp[word] + 0.5))
        for doc_idx, doc_tf in enumerate(all_docs_terms_sp):
            doc_len = sum(doc_tf.values())
            tf = doc_tf.get(word, 0)
            if tf != 0:
                score = (
                    idf_val
                    * tf
                    * 2.5
                    / (tf + 1.5 * (1 - 0.75 + 0.75 * (doc_len / avg_doc_len_sp)))
                )
                rows_idx.append(word_idx)
                cols_idx.append(doc_idx)
                data.append(score)

    sparse_matrix_sp = csr_matrix(
        (data, (rows_idx, cols_idx)), shape=(len(all_words_sp), len(corpus))
    )

    index_time = time.time() - start

    # Query
    start_query = time.time()
    for query in test_queries:
        query_indices = [
            word_to_idx_sp[word] for word in tokenize(query) if word in word_to_idx_sp
        ]
        if query_indices:
            doc_scores = np.array(
                sparse_matrix_sp[query_indices, :].sum(axis=0)
            ).flatten()
            top_k = np.argsort(doc_scores)[-10:][::-1]

    query_time = time.time() - start_query
    qps = len(test_queries) / query_time

    print(f"Indexing: {index_time:.4f}s")
    print(f"Query time: {query_time:.4f}s")
    print(f"QPS: {qps:.2f}\n")

    return index_time, query_time, qps


benchmark_sparse_python_loops()

=== 2. SPARSE MATRIX WITH PYTHON LOOPS ===
Indexing: 77.9146s
Query time: 0.4709s
QPS: 2123.64

(77.91458225250244, 0.4708900451660156, 2123.6380133019015)

Performance Optimization with Numpy

My code has python loops everywhere. Python loops are very slow. The goal here it to use Numpy Vectorization: doing operations on entiry arrays at once instead of looping :

for word_1 in all_words:
for doc_idx, doc_1 in enumerate(all_docs_terms):
    idf_python_1 = compute_idf(word_1, 3, df)
    doc_len_1 = sum(all_docs_terms[doc_idx].values())
    score_1 = bm25_score(word_1, doc_1, idf_python_1, doc_len_1, avg_doc_len)

This has nested loops => very slow for large datasets. Key Insight: Instead of computing one BM25 score at a time, we can compute all scores at once using matrix opertions.

def benchmark_sparse_numpy():
    print("=== 3. SPARSE MATRIX WITH NUMPY VECTORIZATION ===")
    start = time.time()

    # Tokenize
    all_docs_terms_np = []
    for doc in corpus:
        tokens = tokenize(doc)
        all_docs_terms_np.append(Counter(tokens))

    all_words_np = list(set(word for doc in all_docs_terms_np for word in doc))
    word_to_idx_np = {word: idx for idx, word in enumerate(all_words_np)}

    # Build TF matrix
    rows = []
    cols = []
    tf_data = []

    for doc_idx, doc_tf in enumerate(all_docs_terms_np):
        for word, tf in doc_tf.items():
            rows.append(word_to_idx_np[word])
            cols.append(doc_idx)
            tf_data.append(tf)

    tf_matrix_np = csr_matrix(
        (tf_data, (rows, cols)), shape=(len(all_words_np), len(corpus))
    )

    # Compute DF array
    df_array_np = np.array((tf_matrix_np > 0).sum(axis=1)).flatten()

    # Document lengths
    doc_lengths_np = np.array(tf_matrix_np.sum(axis=0)).flatten()
    avg_doc_len_np = doc_lengths_np.mean()

    # Compute IDF array
    N = len(corpus)
    idf_array_np = np.log((N - df_array_np + 0.5) / (df_array_np + 0.5))

    # Vectorized BM25
    k1 = 1.5
    b = 0.75
    tf_dense = tf_matrix_np.toarray()

    numerator = tf_dense * (k1 + 1)
    length_norm = 1 - b + b * (doc_lengths_np / avg_doc_len_np)
    denominator = tf_dense + k1 * length_norm

    idf_column = idf_array_np.reshape(-1, 1)
    bm25_scores = idf_column * (numerator / (denominator + 1e-10))

    bm25_matrix_np = csr_matrix(bm25_scores)

    index_time = time.time() - start

    # Query
    start_query = time.time()
    for query in test_queries:
        query_indices = [
            word_to_idx_np[word] for word in tokenize(query) if word in word_to_idx_np
        ]
        if query_indices:
            doc_scores = np.array(
                bm25_matrix_np[query_indices, :].sum(axis=0)
            ).flatten()
            top_k = np.argsort(doc_scores)[-10:][::-1]

    query_time = time.time() - start_query
    qps = len(test_queries) / query_time

    print(f"Indexing: {index_time:.4f}s")
    print(f"Query time: {query_time:.4f}s")
    print(f"QPS: {qps:.2f}\n")

    return index_time, query_time, qps


benchmark_sparse_numpy()

=== 3. SPARSE MATRIX WITH NUMPY VECTORIZATION ===
Indexing: 6.9885s
Query time: 0.5250s
QPS: 1904.79

(6.988537311553955, 0.5249927043914795, 1904.7883744577036)

def benchmark_rank_bm25():
    from rank_bm25 import BM25Okapi

    print("=== 4. RANK-BM25 ===")

    tokenized_corpus_rank = [tokenize(doc) for doc in corpus]

    start = time.time()
    bm25_rank = BM25Okapi(tokenized_corpus_rank)
    index_time = time.time() - start

    start_query = time.time()
    for query in test_queries:
        query_tokens = tokenize(query)
        scores = bm25_rank.get_scores(query_tokens)
        top_k = np.argsort(scores)[-10:][::-1]

    query_time = time.time() - start_query
    qps = len(test_queries) / query_time

    print(f"Indexing: {index_time:.4f}s")
    print(f"Query time: {query_time:.4f}s")
    print(f"QPS: {qps:.2f}\n")

    return index_time, query_time, qps


benchmark_rank_bm25()

=== 4. RANK-BM25 ===
Indexing: 0.0813s
Query time: 5.0695s
QPS: 197.26

(0.08132147789001465, 5.069519281387329, 197.2573619892297)

def benchmark_bm25s():
    import bm25s

    print("=== 5. BM25S ===")

    start = time.time()
    retriever_bm25s = bm25s.BM25()
    corpus_tokens_bm25s = bm25s.tokenize(corpus, show_progress=False)
    retriever_bm25s.index(corpus_tokens_bm25s, show_progress=False)
    index_time = time.time() - start

    start_query = time.time()
    for query in test_queries:
        query_tokens_bm25s = bm25s.tokenize(query, show_progress=False)
        results, scores = retriever_bm25s.retrieve(
            query_tokens_bm25s, k=10, show_progress=False
        )

    query_time = time.time() - start_query
    qps = len(test_queries) / query_time

    print(f"Indexing: {index_time:.4f}s")
    print(f"Query time: {query_time:.4f}s")
    print(f"QPS: {qps:.2f}\n")

    return index_time, query_time, qps


benchmark_bm25s()

=== 5. BM25S ===
Indexing: 0.5329s
Query time: 0.7049s
QPS: 1418.74

(0.5328564643859863, 0.7048521041870117, 1418.7373408687158)

def benchmark_polars():
    import polars as pl

    print("=== 6. POLARS OPTIMIZATION ===")
    start = time.time()

    k1 = 1.5
    b = 0.75
    N = len(corpus)

    # Create LazyFrame
    lf = pl.LazyFrame({"doc_id": range(N), "text": corpus})

    # Tokenize and explode
    lf_tokens = (
        lf.with_columns(
            pl.col("text").str.to_lowercase().str.split(" ").alias("tokens")
        )
        .explode("tokens")
        .filter(pl.col("tokens").str.len_chars() > 0)
    )

    # Build vocab
    vocab_df = (
        lf_tokens.select(pl.col("tokens").unique()).collect().with_row_index("word_idx")
    )
    vocab_size = len(vocab_df)

    # Join to map tokens to indices
    lf_tokens = lf_tokens.join(vocab_df.lazy(), on="tokens", how="left")

    # Compute TF
    lf_tf = lf_tokens.group_by(["doc_id", "word_idx"]).agg(pl.len().alias("tf"))

    # Compute document lengths
    lf_doc_lens = lf_tf.group_by("doc_id").agg(pl.col("tf").sum().alias("doc_len"))
    avg_doc_len_pl = lf_doc_lens.select(pl.col("doc_len").mean()).collect().item()

    # Compute DF and IDF
    lf_idf = (
        lf_tf.group_by("word_idx")
        .agg(pl.col("doc_id").n_unique().alias("df"))
        .with_columns(
            ((pl.lit(N) - pl.col("df") + 0.5) / (pl.col("df") + 0.5)).log().alias("idf")
        )
    )

    # Calculate BM25
    df_bm25_pl = (
        lf_tf.join(lf_doc_lens, on="doc_id", how="left")
        .join(lf_idf, on="word_idx", how="left")
        .with_columns(
            (
                pl.col("idf")
                * pl.col("tf")
                * (k1 + 1)
                / (
                    pl.col("tf")
                    + k1 * (1 - b + b * (pl.col("doc_len") / avg_doc_len_pl))
                )
            ).alias("bm25_score")
        )
        .select(["doc_id", "word_idx", "bm25_score"])
        .collect()
    )

    # Build sparse matrix
    rows_pl = df_bm25_pl["word_idx"].to_numpy()
    cols_pl = df_bm25_pl["doc_id"].to_numpy()
    data_pl = df_bm25_pl["bm25_score"].to_numpy()
    word_to_idx_pl = dict(zip(vocab_df["tokens"], vocab_df["word_idx"]))
    bm25_matrix_pl = csr_matrix((data_pl, (rows_pl, cols_pl)), shape=(vocab_size, N))

    index_time = time.time() - start

    # Query
    start_query = time.time()
    for query in test_queries:
        query_indices = [
            word_to_idx_pl[word] for word in tokenize(query) if word in word_to_idx_pl
        ]
        if query_indices:
            doc_scores = np.array(
                bm25_matrix_pl[query_indices, :].sum(axis=0)
            ).flatten()
            top_k = np.argsort(doc_scores)[-10:][::-1]

    query_time = time.time() - start_query
    qps = len(test_queries) / query_time

    print(f"Indexing: {index_time:.4f}s")
    print(f"Query time: {query_time:.4f}s")
    print(f"QPS: {qps:.2f}\n")

    return index_time, query_time, qps


benchmark_polars()

=== 6. POLARS OPTIMIZATION ===
Indexing: 0.1580s
Query time: 0.6143s
QPS: 1627.94

(0.1579906940460205, 0.6142714023590088, 1627.9449053946898)

🏆 BM25 Benchmark Results (8,530 documents, 1000 queries)

Key Findings:

1. Sample Documents

Let’s start with a small collection of documents to search through.

documents = [
    "Python is a programming language",
    "I love Python programming",
    "Java is also a programming language",
]

2. Tokenization

First, we need to break text into individual words (tokens). We’ll convert to lowercase for case-insensitive matching.

def tokenize(text):
    """Convert text to lowercase and split into words."""
    return text.lower().split()


# Test tokenization
print("Example:", tokenize(documents[0]))

Example: ['python', 'is', 'a', 'programming', 'language']

3. Term Frequency (TF)

For each document, we count how many times each word appears.

We’ll use Python’s Counter for this.

from collections import Counter


def compute_term_frequencies(documents):
    """Compute term frequency for each document."""
    doc_term_freqs = []
    for doc in documents:
        tokens = tokenize(doc)
        term_freq = Counter(tokens)
        doc_term_freqs.append(term_freq)
    return doc_term_freqs


all_docs_terms = compute_term_frequencies(documents)

# Display term frequencies for each document
for i, tf in enumerate(all_docs_terms):
    print(f"Document {i}: {dict(tf)}")

Document 0: {'python': 1, 'is': 1, 'a': 1, 'programming': 1, 'language': 1}
Document 1: {'i': 1, 'love': 1, 'python': 1, 'programming': 1}
Document 2: {'java': 1, 'is': 1, 'also': 1, 'a': 1, 'programming': 1, 'language': 1}

4. Document Frequency (DF)

Document frequency counts in how many documents each term appears. This helps identify common vs. rare words.

def compute_document_frequency(doc_term_freqs):
    """Count how many documents each term appears in."""
    df = {}
    for doc_tf in doc_term_freqs:
        for term in doc_tf.keys():
            df[term] = df.get(term, 0) + 1
    return df


df = compute_document_frequency(all_docs_terms)
print("Document Frequencies:", df)

Document Frequencies: {'python': 2, 'is': 2, 'a': 2, 'programming': 3, 'language': 2, 'i': 1, 'love': 1, 'java': 1, 'also': 1}

5. Inverse Document Frequency (IDF)

IDF measures how rare or common a word is across all documents. Rare words get higher scores.

The formula is:

where:

• = total number of documents

• = document frequency of word

import math


def compute_idf(term, df, num_docs):
    """Calculate IDF score for a term."""
    if term not in df:
        return 0
    df_term = df[term]
    return math.log((num_docs - df_term + 0.5) / (df_term + 0.5))


# Test IDF scores
print(f"IDF('python'): {compute_idf('python', df, len(documents)):.4f}")
print(f"IDF('java'): {compute_idf('java', df, len(documents)):.4f}")
print(f"IDF('programming'): {compute_idf('programming', df, len(documents)):.4f}")

IDF('python'): -0.5108
IDF('java'): 0.5108
IDF('programming'): -1.9459

6. Average Document Length

BM25 normalizes scores by document length to avoid bias toward longer documents.

def compute_avg_doc_length(doc_term_freqs):
    """Calculate average document length (in terms)."""
    total_length = sum(len(doc_tf) for doc_tf in doc_term_freqs)
    return total_length / len(doc_term_freqs)


avg_doc_len = compute_avg_doc_length(all_docs_terms)
print(f"Average document length: {avg_doc_len:.2f} unique terms")

Average document length: 5.00 unique terms

7. BM25 Score for a Single Term

The BM25 score for a single term in a document is:

where:

• = term frequency of word in document

• = length of document

• = average document length

• = term frequency saturation parameter (typically 1.2-2.0)

• = length normalization parameter (typically 0.75)

The Role of Parameters and

Parameter	Controls	Low Value	High Value
(1.2-2.0)	Term frequency saturation	TF matters less	TF matters more
(0-1)	Length normalization	Ignore length	Penalize long docs

• : Only IDF matters, TF is ignored

• : Document length is ignored

• : Full length normalization

def bm25_term_score(term, doc_tf, idf_score, doc_length, avg_doc_len, k1=1.5, b=0.75):
    """Calculate BM25 score for a single term in a document."""
    tf = doc_tf.get(term, 0)
    if tf == 0:
        return 0

    numerator = idf_score * tf * (k1 + 1)
    denominator = tf + k1 * (1 - b + b * (doc_length / avg_doc_len))
    return numerator / denominator

8. Full BM25 Search

To score a query against all documents:

1. Tokenize the query

2. For each document, sum the BM25 scores of all query terms

3. Return scores for all documents

def bm25_search(query, documents, doc_term_freqs, df, avg_doc_len, k1=1.5, b=0.75):
    """
    Score all documents for a given query using BM25.

    Returns a list of (document_index, score) tuples sorted by relevance.
    """
    query_tokens = tokenize(query)
    num_docs = len(documents)
    scores = []

    for doc_idx, doc_tf in enumerate(doc_term_freqs):
        doc_length = sum(doc_tf.values())  # Total terms in document
        doc_score = 0

        for term in query_tokens:
            idf_score = compute_idf(term, df, num_docs)
            doc_score += bm25_term_score(
                term, doc_tf, idf_score, doc_length, avg_doc_len, k1, b
            )

        scores.append((doc_idx, doc_score))

    # Sort by score (descending)
    scores.sort(key=lambda x: x[1], reverse=True)
    return scores

9. Test the Search Engine

def display_results(query, results, documents):
    """Pretty print search results."""
    print(f"\nQuery: '{query}'")
    print("-" * 60)
    for rank, (doc_idx, score) in enumerate(results, 1):
        print(f"{rank}. [Score: {score:6.3f}] {documents[doc_idx]}")


# Test different queries
queries = ["python programming", "java programming", "love python"]

for query in queries:
    results = bm25_search(query, documents, all_docs_terms, df, avg_doc_len)
    display_results(query, results, documents)

Query: 'python programming'
------------------------------------------------------------
1. [Score: -1.785] Java is also a programming language
2. [Score: -2.457] Python is a programming language
3. [Score: -2.700] I love Python programming

Query: 'java programming'
------------------------------------------------------------
1. [Score: -1.317] Java is also a programming language
2. [Score: -1.946] Python is a programming language
3. [Score: -2.138] I love Python programming

Query: 'love python'
------------------------------------------------------------
1. [Score:  0.000] I love Python programming
2. [Score:  0.000] Java is also a programming language
3. [Score: -0.511] Python is a programming language

10. Understanding the Results

• Negative scores can occur when query terms appear in most documents (high DF)
• Higher scores indicate better relevance
• With small document collections, common words dominate; BM25 works best with larger collections
• The parameters and can be tuned for different applications

The Three Ideas Behind BM25

1. Term Frequency: Words appearing more often in a doc → more relevant
   • BUT with diminishing returns (5 mentions isn’t 5x better than 1)
2. Inverse Document Frequency: Rare words matter more
   • “quantum” is more useful than “the”
3. Document Length Normalization: Shorter docs are often more focused
   • A 100-word doc mentioning “python” once may be more relevant than a 10,000-word doc mentioning it once

Here is Part 2: BM25 with Qdrant: A real use case for using BM25 with Gemini embeddings to improve search results for real estate.

Also the Marimo BM25 Explained

A benchmark: BM25 Benchmark

The Problem

When building a real estate search system, I ran into a frustrating issue: dense vector search kept returning the wrong locations. A query for “6th Settlement Apartment” would return properties in “5th Settlement” or “New Cairo” instead.

I was using Gemini’s embedding model, which performs well for both English and Arabic. But even strong embeddings struggle with domain-specific data where names are nearly identical:

• El Patio Vera
• El Patio Solo
• El Patio Casa

These project names fall outside the embedding model’s training distribution.

The semantic similarity between them is too high for dense search to distinguish.

My property chunks contain full descriptions like “Villa in El Patio Vera, 3 bedrooms, 1,000,000 EGP”. Semantic search handles most queries well, but some searches are fundamentally lexical. I needed both approaches working together.

When Dense Search Fails

My dataset contained 12,877 real estate properties across Egypt with location names like:

• 6th Settlement, 5th Settlement
• 6th of October, 5th of October
• Sheikh Zayed, New Zayed
• El Alamein, North Coast

When a user searched for “6th Settlement Apartment less than 10 million”, the dense vector results looked like this:

5th Settlement, New Cairo - 9.5M
5th Settlement, New Cairo - 9.3M
El Alamein, North Coast - 5.6M
5th Settlement, New Cairo - 9.4M
El Alamein, North Coast - 5.7M

Zero results from 6th Settlement. The embedding model treated “6th” and “5th” as semantically similar because they are both ordinal numbers. The word “Settlement” matched in both cases, pushing the semantic similarity even higher. This is exactly where lexical matching would help.

Why Hybrid Search Works

Dense vectors and BM25 have complementary strengths.

Dense vectors understand meaning. They know that “apartment”, “flat”, and “unit” refer to similar things. They handle typos and variations gracefully. But they struggle with exact matches where surface-level differences matter, like distinguishing “6th” from “5th”.

BM25 sparse vectors match tokens exactly. The token “6th” will never match “5th”. This works across languages without additional configuration. The downside is that BM25 has no semantic understanding. It cannot recognize that “apartment” and “flat” mean the same thing.

By combining both approaches, you get semantic understanding when you need it and exact matching when that matters more.

The architecture looks like this:

User Query: "6th Settlement Apartment"
                    |
         +----------+----------+
         |                     |
   Dense Search          BM25 Search
   (100 candidates)      (30 candidates)
         |                     |
         +----------+----------+
                    |
              RRF Fusion
                    |
             Final Results

Reciprocal Rank Fusion combines the rankings from both approaches, giving weight to results that appear highly ranked in either or both lists.

Challenge 1: Reducing Token Noise

The first problem I encountered was tokenization noise. Raw property chunks contained everything: URLs, metadata IDs, field names, and numeric values.

A typical chunk looked like:

"Palm Hills, Palm Hills New Cairo, Apartment, 15.3M EGP,
154 sqm, metadata_id_123, https://example.com/file.pdf, ..."

Tokenizing this produced over 13,000 unique tokens across the corpus. Most of these were useless for search: URL fragments, random IDs, and field names that would never appear in user queries.

The solution was to extract only the fields that users would actually search for:

• Developer name
• Project name
• Unit type
• Location and sublocation

After filtering, a chunk became:

"Palm Hills Palm Hills New Cairo Apartment 5th Settlement New Cairo"

This reduced the vocabulary from 13,000 tokens to 1,941, an 86% reduction. The BM25 index became faster and more accurate because every remaining token was meaningful.

Challenge 2: Handling Stopwords

Common words like “of”, “in”, and “the” added noise to the BM25 scores. Since this was a bilingual system supporting Arabic and English, I needed stopwords for both languages:

STOPWORDS = {
    # English
    'the', 'a', 'an', 'of', 'in', 'on', 'at', 'to', 'for', 'and', 'or',
    # Arabic
    'في', 'من', 'إلى', 'على', 'عن', 'مع', 'هذا', 'هذه', 'ذلك', 'التي', 'الذي'
}

Removing these ensured that queries like “apartment in 6th Settlement” focused on the meaningful tokens rather than matching every document containing “in”.

Challenge 3: N-gram Tokenization

With basic tokenization, similar location names still overlapped too much:

"6th Settlement" → ['6th', 'settlement']
"5th Settlement" → ['5th', 'settlement']

Both share the token “settlement”, so BM25 would give partial credit to 5th Settlement results even when the user explicitly asked for 6th Settlement.

The solution was to add bigrams, two-word phrases joined with an underscore:

def tokenize_ngram(text: str) -> List[str]:
    words = [w for w in text.split() if w not in STOPWORDS]
    tokens = words.copy()
    
    for i in range(len(words) - 1):
        tokens.append(f"{words[i]}_{words[i+1]}")
    
    return tokens

Now the tokenization produces:

"6th Settlement" → ['6th', 'settlement', '6th_settlement']
"5th Settlement" → ['5th', 'settlement', '5th_settlement']

The bigram “6th_settlement” is unique and will only match documents containing that exact phrase. This dramatically improved precision for location-specific queries.

Challenge 4: Data Imbalance

Even with proper tokenization, some brands dominated the results unfairly. My dataset had:

• Palm Hills: 718 properties
• El Patio: 49 properties

When searching for “El Patio apartment”, BM25 would often return Palm Hills results first because the sheer frequency of Palm Hills in the corpus gave it higher term frequency scores.

The solution was to adjust the balance between dense and sparse search in the hybrid approach. By retrieving more candidates from dense search (100) and fewer from BM25 (30), I gave semantic understanding more influence in the final ranking. This allowed the dense embeddings, which correctly understood “El Patio” as a distinct entity, to override BM25’s frequency bias.

RRF (Reciprocal Rank Fusion) Explained

RRF is a method for combining rankings from multiple search systems.

c How It Works

Instead of averaging scores (which can be misleading when different systems use different scales), RRF uses rank positions.

Formula:

RRF_score = Σ (1 / (k + rank))

Where: - k = constant (usually 60) - rank = position in that ranking (1st, 2nd, 3rd…)

Results

After implementing hybrid search with these optimizations, the same query that previously failed now worked correctly.

Query: “6th Settlement Apartment less than 10 million”

Before (Dense Only):

5th Settlement - 9.5M
5th Settlement - 9.3M
El Alamein - 5.6M

After (Hybrid with BM25):

6th Settlement - 8.0M
6th Settlement - 9.5M
6th Settlement - 7.2M

Key Takeaways

1. Filter your tokens aggressively. Remove everything that users would never search for.

2. Use n-grams for multi-word entities. Bigrams turn “6th Settlement” into a unique, matchable token.

3. Handle stopwords in all supported languages. A bilingual system needs bilingual stopword lists.

4. Balance dense and sparse weights based on your data. If one brand dominates your corpus, give more weight to semantic search.

5. Hybrid search is not always necessary. If pure semantic search works for your use case, the added complexity of BM25 may not be worth it. Use hybrid when exact matches matter and when you have domain-specific vocabulary that embeddings handle poorly.

# Step 1: Install dependencies
# pip install qdrant-client rank-bm25

import re
from typing import List
import pickle
from rank_bm25 import BM25Okapi
from qdrant_client import QdrantClient, models

# Step 2: Define tokenizer with stopwords and bigrams
STOPWORDS = {
    "the",
    "a",
    "an",
    "of",
    "in",
    "on",
    "at",
    "to",
    "for",
    "and",
    "or",
    "في",
    "من",
    "إلى",
    "على",
    "عن",
    "مع",
}


def tokenize_ngram(text: str) -> List[str]:
    text = text.lower()
    text = re.sub(r"[^\w\s]", " ", text)
    words = [w for w in text.split() if w not in STOPWORDS]
    tokens = words.copy()
    for i in range(len(words) - 1):
        tokens.append(f"{words[i]}_{words[i + 1]}")
    return tokens

# Step 3: Build BM25 index from your filtered chunks
filtered_chunks = ["palm hills apartment 5th settlement new cairo", ...]  # Your data
tokenized_corpus = [tokenize_ngram(chunk) for chunk in filtered_chunks]
bm25 = BM25Okapi(tokenized_corpus)

# Save for later use
with open("bm25_index.pkl", "wb") as f:
    pickle.dump(bm25, f)

# Step 4: Create hybrid collection in Qdrant
client = QdrantClient(url="your-url", api_key="your-key")

client.create_collection(
    collection_name="hybrid_collection",
    vectors_config={
        "dense": models.VectorParams(size=3072, distance=models.Distance.COSINE)
    },
    sparse_vectors_config={"text-sparse": models.SparseVectorParams()},
)

# Step 5: Convert text to sparse vector using BM25 scores
def text_to_sparse_vector(text: str, bm25_index) -> models.SparseVector:
    tokens = tokenize_ngram(text)
    scores = bm25_index.get_scores(tokens)

    indices = []
    values = []
    for idx, score in enumerate(scores):
        if score > 0:
            indices.append(idx)
            values.append(float(score))

    return models.SparseVector(indices=indices, values=values)


# Step 6: Upload documents with both vectors
for i, (chunk, dense_embedding, metadata) in enumerate(
    zip(filtered_chunks, embeddings, metadata_list)
):
    client.upsert(
        collection_name="hybrid_collection",
        points=[
            models.PointStruct(
                id=i,
                payload=metadata,
                vector={
                    "dense": dense_embedding,
                    "text-sparse": text_to_sparse_vector(chunk, bm25),
                },
            )
        ],
    )

# Step 7: Hybrid search with RRF fusion
def hybrid_search(query_text: str, query_dense_vector: list, limit: int = 10):
    query_sparse = text_to_sparse_vector(query_text, bm25)

    results = client.query_points(
        collection_name="hybrid_collection",
        prefetch=[
            models.Prefetch(query=query_dense_vector, using="dense", limit=100),
            models.Prefetch(query=query_sparse, using="text-sparse", limit=30),
        ],
        query=models.FusionQuery(fusion=models.Fusion.RRF),
        limit=limit,
    )
    return results.points


# Usage
results = hybrid_search("6th Settlement Apartment", your_query_embedding)

Meet Pyversity: Your Diversification Toolkit

Pyversity is a lightweight library that solves a common problem: search results that all look the same. It re-ranks your results to surface items that are relevant and different from each other.

What makes it special? - Multiple strategies: MMR, MSD, DPP, COVER, and SSD - each with different strengths - Minimal dependencies: Just NumPy - Simple API: One function to rule them all

Let’s see it in action with a quick example.

import numpy as np
from pyversity import diversify, Strategy

# Define embeddings and scores (e.g. cosine similarities of a query result)
embeddings = np.random.randn(100, 256)
scores = np.random.rand(100)

# Diversify the result
diversified_result = diversify(
    embeddings=embeddings,
    scores=scores,
    k=10, 
    strategy=Strategy.MMR,
    diversity=0.5 # Diversity parameter (higher values prioritize diversity)
)


print("Diversified Indices:\n", diversified_result.indices)
print("\nSelection Scores:\n", diversified_result.selection_scores)
print("\nStrategy Used:", diversified_result.strategy)

Diversified Indices:
 [66 16 20 34 54 89 53 81 24 42]

Selection Scores:
 [0.4990284  0.49552712 0.49322212 0.4734265  0.44911325 0.44692624
 0.4468549  0.43787128 0.4272018  0.4173287 ]

Strategy Used: Strategy.MMR

Diversification Strategies

Qdrant MMR in Action

Qdrant has built-in MMR support that helps diversify visual search results.

Let’s test it with a fashion dataset - we’ll search for “black jacket” and compare standard search (which might return very similar items) against MMR search (which balances relevance with variety).

We’ll use the DeepFashion dataset with CLIP embeddings for visual similarity.

In the end, we will use pyversity with Qdrant

Creating Fashion Embedding

def fashion_search_standard(query_text, limit=5):
    text_model = TextEmbedding(model_name="Qdrant/clip-ViT-B-32-text")
    query_embedding = list(text_model.embed([query_text]))[0]
    
    results = client.query_points(
        collection_name=collection_name,
        query=query_embedding.tolist(),
        limit=limit,
        with_payload=True
    )
    return results
    

STANDARD FASHION SEARCH: 'black jacket'

Standard Search Results for "black jacket"

#1 • Score: 0.288

a young man wearing a black jacket and tie

Jackets & Vests

#2 • Score: 0.287

a black leather jacket on a white background

Jackets & Vests

#3 • Score: 0.287

a black leather jacket on a white background

Jackets & Vests

#4 • Score: 0.283

a man wearing a black jacket with a hood

Jackets & Vests

#5 • Score: 0.278

a man wearing a black jacket and jeans

Jackets & Vests

Standard Qdrant Search Results

Notice something? Most of these black jackets look very similar

Same style, similar cuts, nearly identical designs.

While they’re all highly relevant to our query, they don’t give users much variety to choose from. This is exactly the problem diversification solves. All scores ar around 0.288 to 0.278 very similar results

def fashion_search_mmr(query_text, limit=5, diversity=0.5):
    text_model = TextEmbedding(model_name="Qdrant/clip-ViT-B-32-text")
    query_embedding = list(text_model.embed([query_text]))[0]
    
    results = client.query_points(
        collection_name=collection_name,
        query=models.NearestQuery(
            nearest=query_embedding.tolist(),
            mmr=models.Mmr(
                diversity=diversity,  # 0.0 - relevance; 1.0 - diversity
                candidates_limit=100  # num of candidates to preselect
            )
        ),
        limit=limit,
        with_payload=True
    )
    return results

MMR Search – Diverse Black Jackets: "black jacket"

#1 • Score: 0.288

a young man wearing a black jacket and tie

Jackets & Vests

#2 • Score: 0.240

a man in a black shirt is looking at the camera

Tees & Tanks

#3 • Score: 0.275

a man wearing a black jacket and plaid shirt

Jackets & Vests

#4 • Score: 0.275

a man in a blue jacket is posing for a picture

Jackets & Vests

#5 • Score: 0.242

a man wearing a hat and plaid pants

Jackets & Vests

#6 • Score: 0.254

a man in a black shirt and black pants

Jackets & Vests

Pyversity with Qdrant

Let’s try to use the Pyversity algorhtims with Qdrant engine

def apply_pyversity(qdrant_results, strategy=Strategy.MMR, k=10, **strategy_kwargs):
    """Apply Pyversity diversification to Qdrant search results"""
    embeddings = np.array([point.vector for point in qdrant_results.points])
    scores = np.array([point.score for point in qdrant_results.points])
    
    diversified = diversify(
        embeddings=embeddings,
        scores=scores,
        k=k,
        strategy=strategy,
        **strategy_kwargs
    )
    
    # Return reordered results based on diversified indices
    return [qdrant_results.points[i] for i in diversified.indices], diversified

def diversified_search(client, collection_name, query_embedding, 
                       strategy=Strategy.MMR, k=10, 
                       candidates_limit=100, **strategy_kwargs):
    """Search Qdrant and apply Pyversity diversification"""
    results = client.query_points(
        collection_name=collection_name,
        query=query_embedding.tolist(),
        limit=candidates_limit,
        with_payload=True,
        with_vectors=True
    )
    
    # This should return the tuple from apply_pyversity
    return apply_pyversity(results, strategy=strategy, k=k, **strategy_kwargs)

============================================================
Testing MMR Strategy
============================================================

MMR Strategy: "black jacket"

#1 • Score: 0.288

a young man wearing a black jacket and tie

Jackets & Vests

#2 • Score: 0.240

a man in a black shirt is looking at the camera

Tees & Tanks

#3 • Score: 0.275

a man wearing a black jacket and plaid shirt

Jackets & Vests

#4 • Score: 0.275

a man in a blue jacket is posing for a picture

Jackets & Vests

#5 • Score: 0.242

a man wearing a hat and plaid pants

Jackets & Vests

#6 • Score: 0.254

a man in a black shirt and black pants

Jackets & Vests

Diversity Stats:
Strategy: Strategy.MMR
Selection Scores: [ 0.1440569  -0.21647353 -0.23149979 -0.23982394 -0.2528901  -0.2622754 ]

============================================================
Testing MSD Strategy
============================================================

MSD Strategy: "black jacket"

#1 • Score: 0.288

a young man wearing a black jacket and tie

Jackets & Vests

#2 • Score: 0.240

a man in a black shirt is looking at the camera

Tees & Tanks

#3 • Score: 0.278

a man wearing a black jacket and jeans

Jackets & Vests

#4 • Score: 0.246

a man sitting on top of a white cube

Jackets & Vests

#5 • Score: 0.242

a man wearing a baseball cap and a plaid shirt

Sweaters

#6 • Score: 0.287

a black leather jacket on a white background

Jackets & Vests

Diversity Stats:
Strategy: Strategy.MSD
Selection Scores: [0.1440569  0.28352648 0.45831633 0.5803725  0.7433619  0.9287865 ]

============================================================
Testing DPP Strategy
============================================================

DPP Strategy: "black jacket"

#1 • Score: 0.288

a young man wearing a black jacket and tie

Jackets & Vests

#2 • Score: 0.287

a black leather jacket on a white background

Jackets & Vests

#3 • Score: 0.275

a man in a blue jacket is posing for a picture

Jackets & Vests

#4 • Score: 0.278

a man wearing a black jacket and jeans

Jackets & Vests

#5 • Score: 0.283

a man wearing a black jacket with a hood

Jackets & Vests

#6 • Score: 0.272

a man in a black jacket and black pants

Jackets & Vests

Diversity Stats:
Strategy: Strategy.DPP
Selection Scores: [11.763905   4.50202    1.778986   1.6289598  1.1995786  1.063326 ]

============================================================
Testing COVER Strategy
============================================================

COVER Strategy: "black jacket"

#1 • Score: 0.254

a man in a black jacket and red pants

Jackets & Vests