DEV Community: Chidinma Oham

Documenting JavaScript the Easy Way

Chidinma Oham — Thu, 14 May 2026 14:15:56 +0000

Ever been in a situation where you’re under a lot of pressure or chasing a deadline, so you thought, “I probably shouldn’t bother with thoughtful variable names or documentation right now. I’ll clean it up later.”

But you never did. One compromise becomes two, then five, and before you know it, your codebase is full of little shortcuts, vague functions and variable names that make no sense.

When you come back months later, even you can’t quite remember what that function was supposed to do. Everything is a mess, and you end up spending hours figuring out what your code even does.

We’ve all been there.

Some months ago, I thought I found a solution with JSDoc and spent some time reading a bit about it. I found it really interesting, and so naturally I decided to use JSDoc comments in all of my next projects.

JSDoc is an API documentation generator for JavaScript. It is based on a series of tags (words preceded by the @ symbol) that are used before each function or module and describe the different characteristics of the code.

But then I hit a wall. Writing the comments was one thing; actually seeing them as useful documentation was another. The standard JSDoc output felt too impractical, and I found myself rarely checking the generated docs even on my own projects.

So I built JSDocViewer. It’s a small CLI tool that can be used to generate interactive documentation for your JavaScript projects using the JSDoc format.

Building JSDocViewer

JSDocViewer started as a simple Node.js CLI. The idea was to take a folder of .js files with proper JSDoc comments, parse them with the JSDoc tool and then serve the generated documentation in a local browser.

But I wanted a bit more than the standard output. I wanted something that could really be navigated through. Grouped and styled output. A clean single-page viewer. Easy integration into any project folder.

It’s open-source and available on my GitHub. The README has all the technical details.

But here’s some value I found while building that I want to share:

Consistently adding JSDoc comments helps you communicate about your code. Even the task of having to figure out the comment you will write on top of one method will prompt you to think and to clarify your method’s purpose

But Isn’t JSDoc a Bit… Old School?

Sure, there are flashier tools. But that’s kind of the point. JSDoc is low overhead. No need for new frameworks or build tools. Just write good comments and run the generator.

Want something fancier? Pair JSDoc with themes like DocStrap or use tools like TypeDoc for TypeScript.

But even plain JSDoc can transform any project’s readability especially for team projects, open-source contributions or onboarding new engineers.

Final Thoughts

Building JSDocViewer was a fun and clearly rewarding experience that showed the importance of clear communication in coding. As I developed the tool, I realized how effective JSDoc comments can be in making code more accessible and understandable.

So, if your codebase is filled with confusing functions and unclear outputs, try adding just a few JSDoc comments. Then run a tool like mine and see what your code actually looks like to someone new.

Your future self will thank you. And so will your teammates.

Want to try JSDocViewer? Check it out on GitHub. Got questions, ideas or comments on this? I’d love to hear from you.

5 Hidden DevTools Features You Wish You Knew Sooner

Chidinma Oham — Thu, 14 May 2026 14:11:30 +0000

Let me guess. You mostly use your browser DevTools to inspect elements, tweak a bit of CSS and maybe log a few things in the console. Same here. At least until I realized DevTools is hiding some ridiculously powerful tools in plain sight.

These features are not new but they’re easy to miss. And once I started using them, my debugging workflow got way smoother and faster. If you spend a lot of time in your browser while building or testing stuff, these might save you hours too.

Let’s talk about a few of my favorites.

1. Toggle Element State
The toggle element state lets you simulate CSS states like hover, focus or active directly in the DevTools panel. It’s perfect for fine-tuning interactive elements that only show styles after a user does something. Say goodbye to chasing hover styles before they disappear.

Example Use Case: You’re styling a dropdown menu that only appears on hover. Toggle hover, inspect the dropdown and apply your styles.

To use it:
Dev Tools → Inspect Element → Toggle Element State → Select Desired State

2. CSS Overview
Right click an element → Toggle Element State → Select desired state

CSS Overview scans your page and gives you a breakdown of your CSS including color usage, font stacks, unused declarations and even contrast issues. It’s a great way to audit the style without additional plugins. You get a report of how consistent your design system is.

Example Use case: You inherited a codebase and want to see which fonts and color scheme are being used.

To use it:
DevTools → Control + Shift + P → Search “Show CSS Overview”

3. Network Throttling
Network Throttling simulates slow internet speeds like “Fast 3G” or “Offline” to test how your site performs under bad network conditions. If you regularly build with users in mind, this one is a real game-changer.

Example Use case: You’re working on a landing page with lots of images and media. Switch to “Slow 3G” and see what takes too long to load.

To use it:
DevTools → Network Tab→ Throttle dropdown→ Pick connection profile.

4. Sensors Panel
The sensors panel is one of my favorites and a must-use for building anything with geolocation or device motion. The Sensors tool lets you simulate your device’s location, orientation and touch inputs.

Example Use case: You’re building a food delivery app that shows nearby restaurants. Use Sensors to change your location and check how the UI responds in different cities.

To use it:
DevTools → More Tools→ Sensors Tab

5. Live Expressions
Live Expressions display the value of any JavaScript expression in real time right there in the console. No more spamming console.log just to see if a variable is changing.

Example Use Case: You want to watch the value of user.isLoggedIn change as users navigate around. Add it as a Live Expression.

To use it:
DevTools → Console Tab→ Click Eye Icon or ‘+’ → Type any JS expression
The best developers are not just great at code. They know their tools like the back of their hand and that’s probably the gap between you and them. DevTools has so much more to offer than most of us use.

If you already use any of these or have other favorites I missed, I’d love to hear about them.

Modern Authentication: Beyond JWT

Chidinma Oham — Thu, 14 May 2026 13:17:23 +0000

At some point in your developer journey, you were told to use JWTs for authentication. For some, it was from a YouTube tutorial. For others, a blog post or perhaps a senior member of your team. Either way, you pasted the code, got a token and logged in. All was well.

But then, something broke.

The problem is with the way we talk about authentication. We often reduce it to implementation details like "use JWT" or "store the token here" without asking the important questions. Why this token format? Why this flow? Why this storage method?

The truth is JWT is just a format. A way to package data. It is not a full authentication system. It does not handle how tokens are issued. It does not protect against interception. And it definitely does not teach you how to secure your application.

Limitations of JWT as a One-Size-Fits-All Solution

JWTs are great for certain use cases. They are self-contained, compact and easy to parse. They also come with risks that many developers might overlook or not fully understand.

JWT (JSON Web Token) is a way to represent claims between two parties. It's commonly used to authenticate users by embedding their info (like ID or role) in a signed token that can be passed between the frontend and backend.

A few problems show up in the real world:

Long-lived tokens stored in localStorage become a liability. If someone gets access to the browser storage, they own the token.
Lack of token revocation means that once a JWT is issued, it is valid until it expires. If it gets stolen, the system has no built-in way to kill it.
Too much data in the token makes it vulnerable to leaks. Some developers include sensitive user information in the payload, which gets base64 encoded — not encrypted.

So yes, JWTs are useful. But they are not secure by default. And they are definitely not enough on their own.

What OAuth 2.1 Actually Solves

OAuth 2.1 removes outdated flows, enforces better defaults and makes things safer for public clients like single-page apps and mobile apps.

OAuth (Open Authorization) is a protocol that allows third-party applications to access user data without exposing their password.

Some key changes worth knowing:

The implicit flow is deprecated. This is huge. In earlier versions, SPAs would request tokens directly from the authorization server without a code exchange step. That approach exposed tokens in the browser and skipped key validation steps.
OAuth 2.1 enforces the use of authorization code flow with PKCE, even for public clients. This adds a layer of protection during the token exchange.
Refresh tokens for SPAs are now handled with more nuance, using rotating refresh tokens and secure storage patterns.

The shift is subtle but meaningful. It basically means: we know how developers actually build apps today. Let's secure it properly.

What Exactly is PKCE

PKCE is not hard to understand. It is essentially a way to prove that the app requesting the token is the same app that started the process.

PKCE (Proof Key for Code Exchange) is a security extension to OAuth. It protects the authorization code flow, especially in public clients that can't securely store secrets.

Here's how it works:

The app generates a random string called a code verifier.
It hashes this value and sends the code challenge to the authorization server.
Later, when the app tries to exchange the authorization code for a token, it must provide the original code verifier.
The server checks if the hashed verifier matches the challenge sent earlier.
This prevents attackers from intercepting the authorization code and using it. Without the original code verifier, the exchange fails.

PKCE protects against a real and common threat. And it works without needing a client secret.

Real-World Authentication

Authentication is not just about passing the test case. It is about withstanding the real-world messiness of browsers, devices, networks and users.

Some things to keep in mind:

Use short-lived access tokens and long-lived refresh tokens. Always rotate refresh tokens on use.
Store tokens securely. In web apps, avoid localStorage. Use HTTP-only cookies with SameSite and Secure flags when possible.
Adopt token revocation strategies. Blacklists, rotation and introspection endpoints can help.
Rely on trusted auth providers unless you have a good reason to build your own. Auth0, Clerk, Okta and others have done the hard work.
Log and monitor. Treat authentication failures and token activity as security events. Alert when something unusual happens.

The goal is not just to authenticate users. The goal is to protect the system, the data and the people using it.

Why Does Any Of This Matter?

The rise of AI tools and frameworks has made authentication feel like a solved problem. Paste this, configure that and it works.

Until it doesn't.

Good authentication is not just about getting users in. It's about building trust, preventing abuse and laying the foundation for a system that can grow without security breaches.

You don't need to become an OAuth expert. But you do need to care about the decisions being made on your behalf.

JWTs, OAuth and PKCE. They all have the same goal with different approaches. But when used together — and correctly — they form the backbone of modern authentication systems that actually scale.

The key is to approach auth like you approach any other part of software engineering. With clarity. With care. With context.

If you're building an app that handles user data, it is your responsibility. Proper authentication should never be an afterthought. It is a core part of the user experience and system security.

Step-by-Step Guide to Java REST APIs with OpenAPI Integration

Chidinma Oham — Thu, 14 May 2026 13:12:08 +0000

A great API is one which people use. Not necessarily the one with the best design or technology behind it.

If a developer from half a world away can successfully use your API without losing their minds, you've done a great job. Good documentation makes that possible and that's where OpenAPI and Swagger come in. Their auto-generated, interactive and standardized documentation takes your API from meh to something everyone wants to build around all with a few lines of setup.

In this guide, I'll show you how to build a Java REST API using Spring Boot and integrate OpenAPI for simple and clear documentation. In five steps, you'll learn some key concepts, pro tips and how to make your API developer-friendly.

1. Setting up the Project

Let's start by creating a new project using Spring Boot and Gradle (Groovy) in IntelliJ IDEA. If you're starting from scratch, generate a Spring Boot project with these dependencies:

Spring Web: To build the REST API
Spring Data JPA: For database interaction
SQL Server Driver: To connect with SQL Server
Springdoc OpenAPI: For API documentation (more on this later)

Once your project is set up, Gradle will handle dependencies automatically.

2. Structuring the API

A clean architecture helps keep things maintainable. We're going to use this three-layered structure for the API:

Repository Layer — Manages database interactions
Service Layer — Contains business logic
Controller Layer — Handles HTTP requests

Each part has a clear responsibility and makes the API easy to extend and debug.

3. Connecting to SQL Server

A lot of people stumble here especially when starting out, so let's make sure SQL Server is properly configured. To do this:

Enable TCP/IP connections in SQL Server Configuration Manager.
Verify the SQL Server Browser service is running.
Configure your firewall to allow connections on port 1433.

To connect to the database (we're using SQL Server here), add your database credentials in the application.properties file:

spring.datasource.url=jdbc:sqlserver://localhost:1433;databaseName=mydb
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update

Spring Boot handles the connection and Hibernate takes care of ORM (Object-Relational Mapping).

💡 PRO TIP: Use environment variables for sensitive information.

4. Creating the REST API

Now that our connection is set up, we'll build a simple API to manage a user entity. This example will show the flow from request to database using the structure we defined earlier.

Entity Class

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String email;

    // Getters and setters 
}

Repository Interface

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

Service Class

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    public User createUser(User user) {
        return userRepository.save(user);
    }
}

Controller Class

@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;

    @GetMapping
    public List<User> getUsers() {
        return userService.getAllUsers();
    }

    @PostMapping
    public User addUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}

At this point, you can test the endpoints we created using Postman. The basic GET and POST operations for User should be functional now.

5. Integrating OpenAPI with Spring Boot

Now let's document our API in a way that's clean, interactive and self-updating. This is where Springdoc OpenAPI comes in.

If you haven't already, include this in your build.gradle file:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

💡 PRO TIP: Run ./gradlew build or refresh Gradle so the dependencies are installed before you proceed.

Finally, to access the Swagger UI, run your application and go to: http://localhost:8080/swagger-ui/index.html

You'll see the auto-generated UI that shows our endpoints, models and request/response formats.

💡 PRO TIP: Add basic annotations and enhance your endpoints with simple descriptions.

We've just built a functional and well-structured Java REST API and made it developer-friendly with OpenAPI integration. The beauty of using Springdoc is that it doesn't require heavy setup and your documentation always stays in sync with your code.

Clean code is good. Clean, documented code? Even better.

If you're new to this or just needed a refresher, hope this helped. I'd love to hear from you — comment or reach out with questions. I reply!

JDBC vs JPA: Which Should You Use?

Chidinma Oham — Thu, 14 May 2026 12:53:33 +0000

When it comes to database interaction in Java, a choice is usually made between Java Database Connectivity (JDBC) and Java Persistence API (JPA). Some people say JDBC is outdated and avoid it entirely while others never tried JPA and prefer to stick to what works for them.

Both of these technologies have their individual strengths and weaknesses so let's talk about the differences between them, their performances, best practices and a real-world use case to help you decide which to use in your next project.

JDBC is Java's direct way of communicating with a database. It's basically writing SQL manually but in your Java code. It's been around since forever and gives you a lot more control. JPA is an API specification that lets you interact with a database using objects. It's a more modern approach that works just as great and handles boring database stuff for you.

JDBC vs JPA: Key Differences

JDBC

Direct SQL Execution: Writing and executing SQL queries directly in the code gives you a much higher level of control over database operations. This comes in real handy in performance-critical applications where literally every millisecond matters.

Connection Management: Because JDBC allows us full control over database connections such as opening, closing and managing connection pools; resource usage and performance are optimized.

JPA

Object-Relational Mapping (ORM): JPA offers a higher-level abstraction by mapping Java objects to database tables. This reduces boilerplate code and allows us to pay more attention to business logic rather than database interactions.

Automatic SQL Generation: SQL queries are automatically generated which typically makes development a lot quicker. However, this abstraction can sometimes result in less optimized SQL queries compared to manually written SQL.

JDBC vs JPA: Performance

JDBC

Pros: JDBC offers highly optimized performance due to the direct control over SQL execution and connection management.
Cons: Increased development time and error rates due to manual management of database interactions.

JPA

Pros: Increased speed of development as a result of the automatic SQL generation.
Cons: The abstraction layer could lead to less optimized SQL queries. It also requires careful configuration to avoid performance issues.

JDBC vs JPA: Best Practices

JDBC

Connection Pooling: Implement connection pooling to manage database
connections efficiently and reduce the cost of opening and closing connections.
Batch Updates: Use batch updates to execute multiple SQL statements in a single call to reduce the number of round trips to the database.
Indexing: Ensure that database tables are properly indexed to speed up query performance.

JPA

Eager vs. Lazy Loading: Use eager loading for data that is frequently accessed together and lazy loading for less frequently accessed data as a way to optimize performance.
Caching: Configure caching mechanisms provided by JPA implementations to reduce queries to the database and improve performance.
Avoid N+1 Select Problem: Use fetch joins or batch fetching to avoid the N+1 select problem which can significantly reduce performance.

JDBC vs JPA: How It Works

Let's compare the two using a simple fictional application where we need to retrieve a user's details from the database. Using JDBC, we can directly write the SQL query to fetch the data. With JPA, we can simplify the process by reducing boilerplate code.

JDBC:

Connection conn = DriverManager.getConnection(url, user, pass);
PreparedStatement stmt = 
      conn.prepareStatement("SELECT * FROM users WHERE id = ?");
stmt.setInt(1, id);
ResultSet rs = stmt.executeQuery();

JPA:

@Entity
public class User {
    @Id
    private Long id;
}

User user = entityManager.find(User.class, id);

Quick Decision Guide

If you prioritize control and high-performance (every millisecond counts), **JDBC* is for you.
If you're all about scalability with minimal database complexity, **JPA* is the way to go.
*If you want the best of both worlds, you can mix both — JPA for most
operations and JDBC as a fallback for more critical queries.

JDBC vs JPA: Hybrid Setup

If we were building an e-commerce platform that could grow to handle thousands of transactions per second, JPA would be a good starting choice for its simplicity and maintainability. Managing operations would be straightforward using entity mappings and we would avoid writing repetitive SQL.

As our platform grows, we may start having performance issues during sales maybe, when thousands of users place orders simultaneously. JPA's automatic query generation might not be optimized for handling large-scale bulk inserts.

This is where our hybrid setup comes in. JPA would remain our primary choice for managing entities and day-to-day database operations but for the more demanding tasks we would use plain old JDBC.

JDBC vs JPA: Which Do You Use?

The choice depends on the specific requirements of your project and personal preference of course. You could decide to go old school with JDBC and enjoy the control and performance benefits it offers. You could decide to stay on top of trends and enjoy the high-level abstraction JPA offers. As long as you're building stuff — stuff that matters, they're both just means to an end.

Build Your First Semantic Search with Sentence Transformers and ChromaDB

Chidinma Oham — Thu, 14 May 2026 12:27:50 +0000

I recently finished watching Game of Thrones (no comment on the final season) and as the final credits rolled, I wasn’t quite ready to leave that atmosphere behind. I loved the political scheming, the shifting loyalties and even the moral ambiguity of certain characters so I found myself wanting to read a book that captured that exact same vibe or maybe even listen to a playlist that matched the emotional texture of it all.

Most search engines couldn't help me because they were built to recommend based on genre, popularity or what other people had clicked. It wouldn't understand feelings or moods or the subtle nuances of human emotion. I didn't want “another fantasy show”. I wanted something that felt emotionally adjacent to what I had just experienced.

That idea stayed in my head for a while and eventually I decided to play around with transformers to see what I could do about it.

The result was a semantic media recommendation engine using ChromaDB and Sentence Transformers that takes in a natural language input describing an emotion, vibe, concept or narrative situation, converts that input into embeddings then retrieves semantically similar media recommendations across books, films, poems and songs.

In this tutorial, we will build that cross-media recommender using semantic search, understand the core concepts that power it and compare different architectures along with their benefits and trade offs.

What We Are Building

At a high level, the system works like this:

A dataset of media items is prepared.
Each media item is converted into an embedding vector.
Those embeddings are stored inside ChromaDB.
A user enters a natural language query.
The query is embedded using the same model.
ChromaDB retrieves semantically similar media items.
The system returns recommendations across multiple media types.

An important thing to note here is that we are not matching keywords.

The user does not need to type: “sad movie”, “grief song” or “political fantasy book”

Instead, they can describe an emotion or situation naturally and the system retrieves results based on semantic similarity. For instance; "last day in a city before I relocate"

The Tech Stack

For this project, we'll be using:

Python
ChromaDB
Sentence Transformers (The all-MiniLM-L6-v2 embedding model)

The architecture is intentionally simple so we can appreciate the mechanics of semantic retrieval before adding APIs, interfaces or LLM integrations.

Understanding Embeddings

Before writing any code, we need to understand embeddings properly.

An embedding is a numerical representation of text. When we pass text into a transformer model, the model converts that text into a high-dimensional vector.

Something like:

[0.231, -0.884, 0.442, ...]

The actual numbers are not important. What matters is spatial similarity. Text with similar meaning ends up mathematically close together in vector space.

For example:

“grief after death”
“mourning someone”
“coping with loss”

may all exist near each other inside that space. Meanwhile:

“summer beach party”
“high energy dance music”

would likely exist far away.

Step 1: Setting Up the Project

Create a new folder for the project and navigate into it:

mkdir semantic-media-search
cd semantic-media-search

Next, create a virtual environment.

python -m venv venv

Activate the environment:

venv\Scripts\activate

Once activated, install the required dependencies:

pip install chromadb sentence-transformers

Here is what each package is responsible for:

sentence-transformers handles text embeddings using transformer models.
chromadb stores and retrieves embeddings using vector similarity search.

Step 2: Project Structure

Create the following project structure:

semantic-media-search/
│
├── data/
│   └── media.json
│
├── chroma_db/
│
├── embed.py
├── search.py
└── venv/

Step 3: Structuring The Dataset

Since semantic search depends heavily on contextual meaning, the quality of the dataset matters a lot.

For this prototype, we'd be using a manually curated json dataset containing books, films, songs and poems. Each item contains a title, creator, themes, mood, description and media type.

In the media.json file inside the data folder:

[
  {
    "id": "1",
    "title": "Purple Hibiscus",
    "type": "book",
    "creator": "Chimamanda Ngozi Adichie",
    "themes": ["family", "religion", "silence"],
    "mood": ["melancholic", "tense"],
    "description": "A coming-of-age story exploring control, silence and political unrest."
  },
  {
    "id": "2",
    "title": "Moonlight",
    "type": "film",
    "creator": "Barry Jenkins",
    "themes": ["identity", "loneliness", "masculinity"],
    "mood": ["introspective", "emotional"],
    "description": "A deeply emotional film about identity, vulnerability and human connection."
  }
]

One thing you'll quickly realize while building this project is that embeddings become much better when the descriptions are emotionally descriptive instead of mechanically factual. For example:

"description": "A fantasy film released in 2012" does not carry much semantic value. Meanwhile:

"description": "A haunting story about grief, memory and emotional isolation" contains significantly richer contextual meaning for the embedding model to work with.

Step 4: Creating Embeddings

Now we can begin generating embeddings from our media dataset.

In our embed.py file

import json
import chromadb
from sentence_transformers import SentenceTransformer

We first load the embedding model:

print("Downloading and loading model...")
model = SentenceTransformer('all-MiniLM-L6-v2')

The first time you run this, the model will be downloaded locally. Next, initialize ChromaDB:

chroma_client = chromadb.PersistentClient(path="./chroma_db")

collection = chroma_client.get_or_create_collection(
    name="media_recommendations"
)

We are using PersistentClient instead of an in-memory database because we want the embeddings stored permanently between runs.

Now load the dataset:

with open('data/media.json', 'r') as file:
    media_items = json.load(file)

At this stage, we need to convert each media item into embedding-friendly text.

This is an important step.

We are not embedding only the description field. Instead, we combine the title, themes, mood, creator and description into a single contextual string. That gives the transformer more semantic information to work with.

Inside a loop:

for item in media_items:

    embedding_text = f"""
    Title: {item['title']}
    Type: {item['type']}
    Creator: {item['creator']}
    Themes: {", ".join(item['themes'])}
    Mood: {", ".join(item['mood'])}
    Description: {item['description']}
    """

Now generate the embedding:

embedding = model.encode(embedding_text).tolist()

The .tolist() conversion is necessary because ChromaDB expects standard Python lists instead of NumPy arrays.

Next, store everything inside ChromaDB:

collection.add(
    ids=[item["id"]],
    embeddings=[embedding],
    documents=[embedding_text],
    metadatas=[{
        "title": item["title"],
        "type": item["type"],
        "creator": item["creator"]
    }]
)

Finally, print a success message:

print("Success! Embeddings stored in ChromaDB.")

Run the script:

python embed.py

If everything works correctly, your embeddings will now be stored inside the chroma_db directory.

At this point, the system understands your media semantically. We now need a way to retrieve similar results from natural language input.

Step 5: Building The Search Layer

Inside the search.py file:

import chromadb
from sentence_transformers import SentenceTransformer

Load the same embedding model again:

model = SentenceTransformer('all-MiniLM-L6-v2')

This part is extremely important. The same embedding model used during ingestion must also be used during retrieval. Otherwise, the vectors would exist in different semantic spaces and similarity search would break.

Now reconnect to ChromaDB:

chroma_client = chromadb.PersistentClient(path="./chroma_db")

collection = chroma_client.get_collection(
    name="media_recommendations"
)

Take user input:

query = input(
    "What kind of vibe or story are you looking for?\n> "
)

Convert the query into an embedding:

query_embedding = model.encode(query).tolist()

Now comes the retrieval step.

Instead of retrieving random recommendations across all media, we will intentionally retrieve one recommendation for each media type: a book, a film, a song and a poem.

Define the media types:

media_types = ["book", "film", "song", "poem"]

Now loop through them:

for media in media_types:

    results = collection.query(
        query_embeddings=[query_embedding],
        n_results=1,
        where={"type": media}
    )

The where filter ensures we retrieve recommendations within each category separately. Without this filter, the system might return four books or four songs depending on vector similarity.

Now handle the results safely:

if len(results["metadatas"][0]) > 0:

    metadata = results["metadatas"][0][0]

    print("-------------------------")
    print(f"Type: {metadata['type'].upper()}")
    print(f"Title: {metadata['title']}")
    print(f"Creator: {metadata['creator']}")

else:

    print("-------------------------")
    print(f"Type: {media.upper()}")
    print("Result: Nothing found.")

Run the script:

python search.py

Then try prompts like:

*grief after losing someone
*feeling like a million bucks
*last day in a city before relocating
*the feeling of growing apart from your childhood

Architecture Comparisons and Trade-Offs

The stack for this prototype is entirely local. We used a local instance of ChromaDB and a lightweight open-source embedding model. When you are building a semantic search engine, you generally have a few architectural routes each with its own headaches and perks.

Route 1: The Fully Local Stack (Our approach)

We ran the database on our machine and generated embeddings using our own CPU. It was completely free. No API key or internet connection needed (after initial download) and nobody else has access to our data. However, this approach could be heavy on your local resources. The all-MiniLM-L6-v2 model is tiny but if you scale up to millions of rows or use a larger, more nuanced model your machine might struggle.

Route 2: The Managed API Stack

You use OpenAI or Cohere for embeddings and a managed vector database like Pinecone or Weaviate Cloud. These services handle the heavy math, meaning your app runs fast on any device and scales effortlessly. But you pay per token and per database hour. Plus, you are completely dependent on external services staying online.

Route 3: The Hybrid Stack

You might keep the database local or self-hosted but use an external API for the embeddings. This would allow you control your data storage while outsourcing the intense compute required for generating embeddings. You still have API dependency and moving large chunks of vector data back and forth over a network can create latency.

Next Steps

This same architecture powers a wide range of real-world applications, from enterprise recommendation systems to customer support AI, semantic document search and any other contextual retrieval systems.

When I was satisfied with the results in the terminal, I wrapped it in FastAPI and deployed to a web application with the help of Codex. I tested it out using a prompt of political scheming, shifting loyalties and characters making highly questionable moral choices. It handed me The Traitor Baru Cormorant by Seth Dickinson. 10/10 no notes.