Search API Quick Start Guide

from unified_search import UnifiedSearchAPI

# Initialize (singleton pattern - safe to create multiple instances)
search_api = UnifiedSearchAPI()

# Search with default settings (semantic mode)
results = search_api.search(query="your search query")

results = search_api.search(
    query="machine learning",
    mode="semantic",
    top_k=10,
    min_similarity=0.15,
    author_filter="any"  # or "user" or "assistant"
)

results = search_api.search(
    query="machine learning",
    mode="fast",
    top_k=10,
    min_similarity=0.15
)

results = search_api.search(
    query="machine learning",
    mode="instant",
    top_k=10
)

{
    "results": [
        {
            "message_id": "...",
            "conversation_id": "...",
            "content": "...",
            "author": "user",
            "similarity": 0.85,
            "coordinates": {"x": 5, "y": 2, "z": 1, "t": 0.5},
            "ring_position": 180.0,
            "depth_category": "shallow",
            "timestamp": 1234567890,
            "content_length": 150,
            "source": "conversations_fixed"
        }
    ],
    "analysis": {
        "similarity_stats": {...},
        "depth_stats": {...},
        "ring_stats": {...},
        "author_distribution": {...},
        "depth_distribution": {...}
    },
    "query": "machine learning",
    "total_found": 25,
    "sources": {
        "conversations_fixed": 20,
        "claude_conversations": 5
    },
    "processing_time": 0.15,
    "search_mode": "semantic"
}

from core.model_manager import ModelManager

# Get singleton instance
model_mgr = ModelManager()

# Load model (cached after first load)
model_mgr.load_model()

# Encode text
embeddings = model_mgr.encode("your text")
embeddings = model_mgr.encode(["text1", "text2"])  # Batch encoding

from core.database import DatabaseSearcher, DatabaseConfig

# Initialize with custom config
config = DatabaseConfig(
    conversations_fixed_path="path/to/db.db"
)
db_searcher = DatabaseSearcher(config)

# Search conversations
rows = db_searcher.search_conversations_fixed(
    author_filter="user",
    limit=100
)

# Text search
rows = db_searcher.search_text(
    query_text="search term",
    limit=50
)

# Parse embeddings
embedding = db_searcher.parse_embedding(embedding_blob)

from core.similarity import SimilarityCalculator
import numpy as np

# Cosine similarity
vec1 = np.array([0.1, 0.2, 0.3])
vec2 = np.array([0.2, 0.3, 0.4])
similarity = SimilarityCalculator.cosine_similarity(vec1, vec2)

# Batch cosine similarity
query_vec = np.array([0.1, 0.2, 0.3])
candidate_vecs = np.array([[0.2, 0.3, 0.4], [0.3, 0.4, 0.5]])
similarities = SimilarityCalculator.cosine_similarity_batch(query_vec, candidate_vecs)

# Text similarity
similarity = SimilarityCalculator.text_similarity(
    "machine learning",
    "deep learning neural networks",
    method="combined"  # or "jaccard" or "word_frequency"
)

# Simple word match (fastest)
similarity = SimilarityCalculator.simple_word_match("python", "python programming")

from core.formatters import ResultFormatter, AnalysisGenerator

# Format single result
result = ResultFormatter.format_result(
    message_id="msg_123",
    conversation_id="conv_456",
    content="Hello world",
    author="user",
    similarity=0.85,
    coordinates={"x": 5, "y": 2, "z": 1, "t": 0.5},
    timestamp=1234567890,
    source="conversations_fixed"
)

# Format batch
results = ResultFormatter.format_results_batch(
    raw_results,
    sort_by_similarity=True,
    top_k=10
)

# Generate analysis
analysis = AnalysisGenerator.generate_analysis(results)
minimal_analysis = AnalysisGenerator.generate_minimal_analysis(results)

# Using unified_search.py
echo '{"query": "machine learning", "mode": "semantic", "top_k": 10}' | python unified_search.py

# Using legacy files (still work)
echo '{"query": "machine learning"}' | python search_api.py

from search_api import search_conversations
results = search_conversations(query="test", top_k=10)

from unified_search import UnifiedSearchAPI
search_api = UnifiedSearchAPI()
results = search_api.search(query="test", mode="semantic", top_k=10)

try:
    results = search_api.search(query="test")
    if "error" in results:
        print(f"Search error: {results['error']}")
    else:
        print(f"Found {len(results['results'])} results")
except Exception as e:
    print(f"Exception: {e}")

from core.database import DatabaseConfig
from unified_search import UnifiedSearchAPI

# Custom database paths
config = DatabaseConfig(
    conversations_fixed_path="custom/path/to/db.db",
    claude_db_path="custom/path/to/claude.db",
    claude_conversations_json="custom/path/to/conversations.json"
)

search_api = UnifiedSearchAPI(config)