How to Build Vector Search from Scratch in Python: Complete Beginner-Friendly Guide

Code Magnet published a beginner-friendly guide on building a vector search engine from scratch in pure Python, using only the standard library (re, math, collections) and implementing TF-IDF and cosine similarity. The guide walks through tokenization, vocabulary building, TF-IDF vectorization, and a VectorSearchEngine class, aiming to teach the underlying mechanics before using external libraries.

If you’ve used ChatGPT, Google, or any modern recommendation system, you’ve used vector search — even if you didn’t know it. It’s the technology that lets machines find “similar” pieces of text, images, or data, not just exact keyword matches. In this guide, we’ll build a working vector search engine from scratch using pure Python — no sklearn, no faiss, no external embedding APIs. Just re, math, and collections from the standard library. By the end, you'll understand exactly what's happening under the hood before you ever plug in a library. This post originally appeared on Code Magnet — head there for the full formatted version with the downloadable code. Vector search works by converting text into a list of numbers a “vector” that captures something about its meaning or content. Similar pieces of text end up with similar vectors. To search, you convert your query into a vector too, then find which documents have the closest vectors using a similarity measure. We’ll use two classic building blocks: First, we need some text to search through, and a way to break sentences into words tokens . python python import reimport mathfrom collections import Counter documents = "Python is a popular programming language for data science", "Machine learning models require large amounts of training data", "Vector search helps find similar documents using embeddings", "Data science uses Python and statistics to analyze data", "Search engines use vectors to rank relevant documents", "Deep learning is a subset of machine learning using neural networks", python def tokenize text : text = text.lower return re.findall r" a-z +", text Every unique word across all documents becomes part of our vocabulary. Each document will eventually be represented as a vector of numbers — one number per vocabulary word. python python def build vocabulary docs : vocab = set for doc in docs: vocab.update tokenize doc return sorted vocab This is the core of our engine. TF-IDF gives more weight to words that are frequent in a specific document but rare across the whole collection — these words are usually the most meaningful ones. python python class TFIDFVectorizer: def init self : self.vocab = self.idf = {} python def fit self, docs : self.vocab = build vocabulary docs n docs = len docs df = Counter for doc in docs: for word in set tokenize doc : df word += 1 for word in self.vocab: self.idf word = math.log n docs / 1 + df word + 1 return self python def transform self, docs : vectors = for doc in docs: tokens = tokenize doc tf = Counter tokens total = len tokens vector = tf w / total if total else 0 self.idf.get w, 0 for w in self.vocab vectors.append vector return vectors python def fit transform self, docs : self.fit docs return self.transform docs What’s happening here: Once documents are vectors, we need a way to measure how similar two vectors are. Cosine similarity measures the angle between two vectors — it returns 1 for identical direction, 0 for no similarity. python python def cosine similarity vec a, vec b : dot = sum a b for a, b in zip vec a, vec b mag a = math.sqrt sum a a for a in vec a mag b = math.sqrt sum b b for b in vec b if mag a == 0 or mag b == 0: return 0.0 return dot / mag a mag b Now we wrap everything into a VectorSearchEngine class that can index documents and search them. python python class VectorSearchEngine: def init self : self.vectorizer = TFIDFVectorizer self.doc vectors = self.documents = python def index self, docs : self.documents = docs self.doc vectors = self.vectorizer.fit transform docs print f"Indexed {len docs } documents." print f"Vocabulary size: {len self.vectorizer.vocab } unique words\n" python def search self, query, top k=3 : query vector = self.vectorizer.transform query 0 scores = i, cosine similarity query vector, dv for i, dv in enumerate self.doc vectors scores.sort key=lambda x: x 1 , reverse=True results = scores :top k print f"Query: '{query}'" print "-" 60 for rank, idx, score in enumerate results, 1 : print f"Rank {rank} | Score: {score:.4f}" print f" Document: {self.documents idx }" print return results Let’s index our sample documents and run a few searches: python engine = VectorSearchEngine engine.index documents engine.search "machine learning and neural networks" engine.search "python for data analysis" engine.search "finding similar documents with vectors" Indexed 6 documents.Vocabulary size: 39 unique words Query: 'machine learning and neural networks'------------------------------------------------------------Rank 1 | Score: 0.6070 Document: Deep learning is a subset of machine learning using neural networksRank 2 | Score: 0.2307 Document: Machine learning models require large amounts of training dataRank 3 | Score: 0.1732 Document: Data science uses Python and statistics to analyze data Query: 'python for data analysis'------------------------------------------------------------Rank 1 | Score: 0.5456 Document: Python is a popular programming language for data scienceRank 2 | Score: 0.3838 Document: Data science uses Python and statistics to analyze dataRank 3 | Score: 0.1138 Document: Machine learning models require large amounts of training data Query: 'finding similar documents with vectors'------------------------------------------------------------Rank 1 | Score: 0.3845 Document: Vector search helps find similar documents using embeddingsRank 2 | Score: 0.3845 Document: Search engines use vectors to rank relevant documentsRank 3 | Score: 0.0000 Document: Python is a popular programming language for data science Notice something interesting in the last result: the third-ranked document scores 0.0000 . That’s because our third document shares zero vocabulary words with the query — TF-IDF cosine similarity is purely lexical word-based , not semantic. It has no idea that “vectors” and “programming language” could ever be related in meaning; it only counts shared words. This from-scratch engine is great for learning, but it has real limits worth knowing before you use it in production: Originally published at codemagnet.in , where I write about Python, data science, and practical coding tutorials. How to Build Vector Search from Scratch in Python: Complete Beginner-Friendly Guide https://blog.devgenius.io/how-to-build-vector-search-from-scratch-in-python-complete-beginner-friendly-guide-cd8a4fc73955 was originally published in Dev Genius https://blog.devgenius.io on Medium, where people are continuing the conversation by highlighting and responding to this story.