Semantic Search

Advanced rule discovery using natural language queries.

Semantic search uses AI embeddings to find relevant rules even when keywords don’t match exactly.

Overview

Traditional search matches keywords. Semantic search understands meaning.

Query	Keyword Search	Semantic Search
”button colors”	✅ Finds rules with “button” and “colors”	✅ Also finds “interactive element styling"
"how to handle errors”	❌ Might miss “exception patterns”	✅ Finds error handling, exceptions, try/catch
”make things pretty”	❌ No exact match	✅ Finds styling, design system, UI rules

How It Works


┌──────────────────┐
│ Your Rules       │
│ (Markdown text)  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Embedding Model  │ Convert text to vectors
│ (1536 dimensions)│
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Vector Database  │ Store for fast similarity search
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Query: "error"   │ → Converted to vector
│                  │ → Find similar vectors
│                  │ → Return matching rules
└──────────────────┘

Embedding Process

Indexing: When you create/update rules, they’re converted to vectors
Storing: Vectors stored in high-performance vector database
Querying: Your search query becomes a vector
Matching: Find rules with similar vectors (cosine similarity)

Using Semantic Search

Dashboard Search

In the dashboard:

Click the search bar (or press /)
Type your natural language query
Results ranked by relevance

MCP Tool

Via MCP servers:


{
  "tool": "prism_search_rules",
  "parameters": {
    "query": "How should I structure my API endpoints?",
    "limit": 5
  }
}

API


curl -X POST https://api.prismcontext.com/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "form validation patterns",
    "limit": 5,
    "threshold": 0.7
  }'

Response:


{
  "results": [
    {
      "rule_id": "rule_abc123",
      "title": "Form Validation with Zod",
      "score": 0.92,
      "snippet": "Always validate forms using Zod schemas..."
    },
    {
      "rule_id": "rule_def456",
      "title": "Input Error Handling",
      "score": 0.85,
      "snippet": "Display validation errors inline..."
    }
  ]
}

Search Parameters

Query

Your natural language question or topic:


{
  "query": "What colors should I use for buttons?"
}

Limit

Maximum results to return:


{
  "query": "...",
  "limit": 10  // Default: 5, Max: 50
}

Threshold

Minimum similarity score (0-1):


{
  "query": "...",
  "threshold": 0.7  // Only results above 70% similarity
}

Category Filter

Limit to specific categories:


{
  "query": "...",
  "categories": ["styling", "components"]
}

Project Filter

Search within specific project:


{
  "query": "...",
  "project_id": "proj_abc123"
}

Search Tips

Be Descriptive

❌ Too Vague


"colors"

Ask Questions

❌ Keywords


"error handling"

Include Context

❌ Generic


"components"

Indexing Configuration

Auto-Indexing

Rules are automatically indexed when:

Created in dashboard
Updated via API
Imported from files

Manual Re-Index

Force re-indexing of all rules:


# Via CLI
prism rules reindex --project proj_abc123
 
# Via API
curl -X POST https://api.prismcontext.com/v1/rules/reindex \
  -H "Authorization: Bearer YOUR_API_KEY"

Index Status

Check indexing status:


curl https://api.prismcontext.com/v1/rules/index-status \
  -H "Authorization: Bearer YOUR_API_KEY"


{
  "total_rules": 150,
  "indexed": 150,
  "pending": 0,
  "last_indexed": "2024-03-20T10:30:00Z"
}

Embedding Models

Default Model

Prism uses text-embedding-3-small by default:

Dimensions: 1536
Max tokens: 8191
Performance: Fast, good accuracy

Enterprise Options

For enterprise customers:

Model	Dimensions	Accuracy	Speed
text-embedding-3-small	1536	Good	Fast
text-embedding-3-large	3072	Better	Medium
Custom (BYOM)	Variable	Custom	Variable

Performance Optimization

Chunking Large Rules

Long rules are split for better matching:


Original rule: 5000 words
│
├── Chunk 1: Introduction (500 words)
├── Chunk 2: Requirements (800 words)
├── Chunk 3: Examples (1200 words)
├── Chunk 4: Anti-patterns (600 words)
└── Chunk 5: Best practices (500 words)

Search matches the most relevant chunk(s)

Caching

Search results are cached:

Default TTL: 5 minutes
Cache key: Query + filters hash
Invalidation: On rule changes

Query Optimization

The system optimizes queries automatically:


Query: "What are the colors?"
→ Expanded: "colors color palette design tokens styling"
→ Better matches across terminology

Monitoring

Search Analytics

View search patterns:

Dashboard → Analytics → Search

Most common queries
Queries with no results
Average result scores

Improving Results

If searches aren’t returning good results:

Add synonyms: Include common terms in rules
Write clear titles: Titles are weighted higher
Add summaries: Include TL;DR sections
Use examples: Examples improve matching

API Reference

Search Endpoint


POST /v1/search

Request:


{
  "query": "string (required)",
  "limit": "number (default: 5, max: 50)",
  "threshold": "number (default: 0.5, range: 0-1)",
  "categories": ["array of category strings"],
  "project_id": "string",
  "include_content": "boolean (default: false)"
}