Advanced Search & Discovery

Learn how to enable fast, intent-based prompt discovery using advanced search and indexing.

When your project has dozens or even hundreds of prompts, finding the exact one you need with grep or a simple file search becomes impossible. You need a search that understands intent, not just keywords.

This guide will walk you through Prompt Lockbox’s advanced search capabilities. You’ll learn how to build a search index and use powerful hybrid and SPLADE search methods to find any prompt in seconds, no matter how large your library grows.

The Goal: To move beyond simple fuzzy search and learn how to:

Build a dedicated search index for your project.

• Use Hybrid Search for a balance of keyword and semantic matching.
• Use SPLADE Search for the a balanced mix of keyword and conceptual matching.

Building Your Search Index

To enable advanced search, you first need to create an index. This is a one-time process that scans all your prompts and creates optimized files for fast lookups. The plb index command handles this for you.

Dependencies!

Advanced search methods require extra Python libraries. If you haven’t installed them, the command will guide you. You can pre-install them with: pip install prompt-lockbox[search]

How to Build the Index

You can choose which type of index to build. We recommend starting with hybrid.

CLI

# Build the index for Hybrid Search (TF-IDF + FAISS)
plb index --method=hybrid

This command will create several files inside your project’s hidden .plb/ directory. You only need to run this command again when you’ve added or significantly changed many prompts.

Choosing the Right Search Method

Now that your index is built, you can use the advanced search commands. Which one should you use?

Fuzzy Search (default)

plb search fuzzy "query"

• How it Works: Simple string matching on names, descriptions, and tags.
• Pros: Very fast, requires no index.
• Best For: Quick lookups when you already know part of the prompt’s name or a unique keyword in its description.

Hybrid (TF-IDF + Embeddings)

plb search hybrid "query"

• How it Works: Combines classic keyword search (TF-IDF) with modern semantic search (FAISS).
• Pros: The best of both worlds. It finds prompts that contain your exact keywords and prompts that are just conceptually similar.
• Best For: General-purpose, high-quality searching in any prompt library. This is the recommended “power search” for most users.

SPLADE Search

plb search splade "query"

• How it Works: Uses a state-of-the-art “sparse vector” model that is exceptionally good at understanding the context and importance of words.
• Pros: Often provides the most relevant results, especially for complex or vague queries.
• Best For: When you need the absolute highest quality results and want to find prompts based on their meaning, even if they don’t share any keywords.

Performing an Advanced Search

Note

Search index needs to be built before using search!

Now that your index is built, you can use the advanced search methods through the search() method in the SDK or the plb search command.

Let’s imagine you have this prompt in your library and you want to find it.

prompts/code-gen.v1.0.0.yml

name: python-function-writer
description: "Writes a complete Python function based on a docstring."
tags: [python, code-generation]
...

A simple fuzzy search for “python code” might work, but an advanced search for “create a python function” is much more powerful because it understands that “create,” “writer,” and “generation” are conceptually related. Examples:

Hybrid Search (CLI):

# Search using the 'hybrid' engine
plb search hybrid "create a python function"

Hybrid Search (Python SDK):

from prompt_lockbox import Project
from rich import print

project = Project()

results = project.search(
    query="create a python function",
    method="hybrid"
)

print(results)
# Expected output:
# [
#   {'score': 0.85, 'name': 'python-function-writer', ...},
#   ...
# ]

SPLADE Search (Python SDK):

from prompt_lockbox import Project
from rich import print

project = Project()

# Using the SPLADE engine is as simple as changing the method
results = project.search(
    query="create a python function",
    method="splade",
    limit=5 # You can also change the limit
)

print(results)

Tuning your Search

A unique feature of the hybrid search method is the ability to balance between keyword and semantic matching using the alpha parameter.

• alpha=0.0: Purely keyword-based (like a classic search engine).
• alpha=1.0: Purely semantic-based (finds conceptually similar prompts).
• alpha=0.5 (Default): A balanced mix of both.

This is available in both the CLI and SDK.

CLI

# Prioritize semantic meaning over keywords
plb search hybrid "email analysis" --alpha 0.9

By building an index and using the hybrid or splade search methods, you transform your prompt library from a simple collection of files into a powerful, discoverable knowledge base.