Search Modes

-- Query: "the best way to handle errors"
-- Internally becomes: "best way handle errors"
-- ("the" and "to" are stop words)

-- This matches:
"Best practices for error handling"  -- ✅
"A way to handle errors effectively" -- ✅

# Results automatically sorted by ts_rank score
# Higher score = better match
[
  %{text: "PostgreSQL pgvector extension", score: 0.876},
  %{text: "Using pgvector with Postgres", score: 0.654},
  %{text: "Vector databases include pgvector", score: 0.432}
]

defp do_hybrid_rrf(query, params) do
  # 1. Run semantic search
  semantic_params = %{params | limit: params.limit * 2}
  {:ok, semantic_results} = do_search(:semantic, query, semantic_params)
  
  # 2. Run fulltext search
  fulltext_params = %{params | limit: params.limit * 2}
  {:ok, fulltext_results} = do_search(:fulltext, query, fulltext_params)
  
  # 3. Combine with RRF
  {:ok, rrf_combine(semantic_results, fulltext_results, params.limit)}
end

def rrf_combine(list1, list2, limit, k \\ 60) do
  # 1. Score by rank position: 1 / (k + rank)
  scores1 = list1 
    |> Enum.with_index(1) 
    |> Map.new(fn {item, rank} -> 
      {item.id, 1 / (k + rank)} 
    end)
  
  scores2 = list2
    |> Enum.with_index(1)
    |> Map.new(fn {item, rank} -> 
      {item.id, 1 / (k + rank)}
    end)
  
  # 2. Sum scores from both lists
  all_items = (list1 ++ list2) |> Enum.uniq_by(& &1.id)
  
  all_items
  |> Enum.map(fn {id, item} ->
    rrf_score = Map.get(scores1, id, 0) + Map.get(scores2, id, 0)
    Map.put(item, :score, rrf_score)
  end)
  |> Enum.sort_by(& &1.score, :desc)
  |> Enum.take(limit)
end

# API documentation search - need exact function names
defmodule MyApp.APIDocs do
  def search_function(function_name) do
    {:ok, results} = Arcana.search(
      function_name,
      repo: MyApp.Repo,
      mode: :fulltext,  # Exact matching for code symbols
      collection: "api-docs",
      limit: 3
    )
    
    results
  end
end

# Example queries:
MyApp.APIDocs.search_function("Arcana.search/2")
# Returns exact function documentation

MyApp.APIDocs.search_function("Embedder.embed")
# Returns all embed/2 implementations

# Production search - handle any query type
defmodule MyAppWeb.SearchController do
  def search(conn, %{"q" => query, "collection" => collection}) do
    {:ok, results} = Arcana.search(
      query,
      repo: MyApp.Repo,
      mode: :hybrid,         # Best overall quality
      collection: collection,
      limit: 10,
      semantic_weight: 0.6,  # Slightly favor semantics
      fulltext_weight: 0.4
    )
    
    # Add metadata for debugging
    enriched = Enum.map(results, fn result ->
      Map.merge(result, %{
        semantic_score: result[:semantic_score],
        fulltext_score: result[:fulltext_score]
      })
    end)
    
    json(conn, %{results: enriched})
  end
end

# Example queries:
# "PostgreSQL performance" - hybrid finds both semantic
#   (optimization, tuning) and keyword (PostgreSQL) matches
# "José Valim Elixir" - fulltext finds name, semantic finds context
# "how to debug" - semantic understanding with keyword boost

# Knowledge graph + vector search fusion
{:ok, results} = Arcana.search(
  "Who leads the Elixir project?",
  repo: MyApp.Repo,
  mode: :hybrid,  # Base search mode
  graph: true,    # Add graph traversal
  limit: 10
)

# Behind the scenes:
# 1. Extract entities: ["Elixir project"]
# 2. Run hybrid vector search
# 3. Traverse graph for entity relationships
# 4. Combine with RRF (lib/arcana/search.ex:139-172)

# Results include both:
# - Vector matches for "leads" and "project"
# - Graph relationships: Elixir → José Valim (creator)