dimensions: 64,

    top_k: 12

  ],

  plugin_discovery: [

    embeddings_enabled: false,

    provider: OpenAgents.Memory.OpenAIEmbeddings,

    model_id: "text-embedding-3-small",

    model_version: "2024-01",

    dimensions: 64,

    top_k: 12

  ],

  # The shipped tool catalog. It is a zero base, deliberately small.

  #

  # A tool ships only when it meets every admission criterion in

defmodule OpenAgents.Plugins.Discovery.Doc do

  @moduledoc """

  The searchable document for one plugin manifest.

  The discovery text folds the manifest's name and description together with the

  text declared on its surfaces and capabilities. It is what gets embedded for

  semantic search; it does not synthesize a keyword routing table.

  """

  @spec text(map()) :: String.t()

  def text(%{} = manifest) do

    [manifest["name"], manifest["description"]]

    |> Enum.reject(&(&1 in [nil, ""]))

    |> Enum.concat([capability_text(manifest["capabilities"])])

    |> Enum.concat(surface_texts(manifest["surfaces"]))

    |> Enum.reject(&(&1 in [nil, ""]))

    |> Enum.join(" ")

  end

  def text(_), do: ""

  defp capability_text(nil), do: nil

  defp capability_text(caps) do

    case List.wrap(caps["hosts"]) do

      [] -> nil

      hosts -> Enum.join(hosts, " ")

    end

  end

  defp surface_texts(nil), do: []

  defp surface_texts(surfaces) when is_list(surfaces),

    do: Enum.flat_map(surfaces, &surface_texts/1)

  defp surface_texts(%{} = surface) do

    [surface["name"], surface["description"]]

    |> Enum.reject(&(&1 in [nil, ""]))

    |> Enum.concat(command_texts(surface["slash_commands"]))

    |> Enum.concat(tool_texts(surface["tools"]))

  end

  defp command_texts(nil), do: []

  defp command_texts(commands) when is_list(commands),

    do: Enum.flat_map(commands, &command_texts/1)

  defp command_texts(%{} = command),

    do: [command["command"], command["description"]] |> Enum.reject(&(&1 in [nil, ""]))

  defp tool_texts(nil), do: []

  defp tool_texts(tools) when is_list(tools), do: Enum.flat_map(tools, &tool_texts/1)

  defp tool_texts(%{} = tool),

    do: [tool["name"], tool["description"]] |> Enum.reject(&(&1 in [nil, ""]))

end

defmodule OpenAgents.Plugins.Embeddings do

  @moduledoc """

  Vector embeddings for the plugin registry, for cosine-similarity discovery.

  There are only a handful of plugins, so the vectors live in a `persistent_term`

  cache keyed by a digest over the indexed manifest set and cosine is computed in

  process. The provider is the same embedding boundary the memory and tool

  discovery systems use.

  If embeddings are disabled, unconfigured, or the provider errors, `warm/1` and

  `embed_query/1` return `:ok`/`:error` and search falls back to the unranked

  candidate list. A plugin search must never fail because the embedding provider

  is down.

  """

  alias OpenAgents.Plugins.Discovery.Doc

  alias OpenAgents.Plugins.Index

  alias OpenAgents.Provenance.Canonical

  require Logger

  @persistent_key {__MODULE__, :vectors}

  @doc "Whether embedding-backed plugin discovery is switched on and configured."

  @spec enabled?() :: boolean()

  def enabled? do

    config = Application.get_env(:openagents, :plugin_discovery, [])

    Keyword.get(config, :embeddings_enabled, false) == true and not is_nil(provider())

  end

  @doc """

  Compute and cache the plugin vectors for the provided entries.

  Safe to call repeatedly; returns `:ok` when disabled, already cached, or

  successful, and `:error` on a provider failure (leaving the cache empty so

  callers fall back to the unranked candidate list).

  """

  @spec warm([Index.Entry.t()]) :: :ok | :error

  def warm(entries) when is_list(entries) do

    cond do

      not enabled?() -> :ok

      is_map(cached(digest(entries))) -> :ok

      true -> build_and_cache(entries)

    end

  rescue

    error ->

      Logger.warning(

        "plugin_embeddings_warm_failed code=#{OpenAgents.OperationalLog.code(error)}"

      )

      :error

  end

  @doc "Cached plugin entry → vector map for a digest, or nil when unavailable."

  @spec vectors(String.t()) :: %{optional(Index.Entry.t()) => [float()]} | nil

  def vectors(digest) when is_binary(digest), do: cached(digest)

  def vectors(_digest), do: nil

  @doc "Embed a query string, or `:error` when embeddings are unavailable."

  @spec embed_query(String.t()) :: {:ok, [float()]} | :error

  def embed_query(text) when is_binary(text) and text != "" do

    if enabled?() do

      case provider().embed(text, embed_config()) do

        {:ok, vector} when is_list(vector) and vector != [] -> {:ok, vector}

        _other -> :error

      end

    else

      :error

    end

  rescue

    _error -> :error

  end

  def embed_query(_text), do: :error

  @doc false

  @spec digest([Index.Entry.t()]) :: String.t()

  def digest(entries) when is_list(entries) do

    entries

    |> Enum.sort_by(&{&1.repository, &1.release, &1.manifest["name"]})

    |> Enum.map(fn %Index.Entry{} = entry ->

      %{

        "repository" => entry.repository,

        "release" => entry.release,

        "manifest" => entry.manifest

      }

    end)

    |> then(&Canonical.digest!/1)

  end

  defdelegate cosine(a, b), to: OpenAgents.Tools.Embeddings

  # ── internal ───────────────────────────────────────────────────────────────

  defp build_and_cache(entries) do

    digest = digest(entries)

    vectors =

      entries

      |> Enum.reduce_while(%{}, fn entry, acc ->

        case provider().embed(Doc.text(entry.manifest), embed_config()) do

          {:ok, vector} when is_list(vector) and vector != [] ->

            {:cont, Map.put(acc, entry, vector)}

          _other ->

            {:halt, :error}

        end

      end)

    case vectors do

      :error ->

        :error

      map when map_size(map) > 0 ->

        :persistent_term.put(@persistent_key, {digest, map})

        Logger.info(

          "plugin_embeddings_warmed digest=#{binary_part(digest, 0, 12)} count=#{map_size(map)}"

        )

        :ok

      _empty ->

        :ok

    end

  end

  defp cached(digest) do

    case :persistent_term.get(@persistent_key, nil) do

      {^digest, map} -> map

      _absent_or_stale -> nil

    end

  end

  defp provider do

    :openagents

    |> Application.get_env(:plugin_discovery, [])

    |> Keyword.get(:provider)

  end

  defp embed_config do

    config = Application.get_env(:openagents, :plugin_discovery, [])

    %{

      model_id: Keyword.get(config, :model_id, "text-embedding-3-small"),

      model_version: Keyword.get(config, :model_version, "2024-01"),

      dimensions: Keyword.get(config, :dimensions, 64)

    }

  end

end

  require Logger

  alias OpenAgents.Plugins.Embeddings

  alias OpenAgents.Plugins.Manifest

  defmodule Entry do

    @moduledoc "One indexed, validated plugin release."

    defstruct [:repository, :release, :manifest]

    defstruct [:repository, :release, :manifest, :score]

    @type t :: %__MODULE__{

            repository: String.t(),

            release: String.t(),

            manifest: map()

            manifest: map(),

            score: float() | nil

          }

  end

  @doc "Render an index entry as a JSON-friendly map."

  @spec to_map(Entry.t()) :: map()

  def to_map(%Entry{repository: repository, release: release, manifest: manifest}) do

    %{

  def to_map(%Entry{repository: repository, release: release, manifest: manifest, score: score}) do

    base = %{

      "repository" => repository,

      "release" => release,

      "manifest" => manifest

    }

    if is_number(score), do: Map.put(base, "score", score), else: base

  end

  @doc """

  Search plugin manifests for `query` and return `{:ok, [Entry.t()]}`. When

  embeddings are enabled and available, results are sorted by cosine similarity

  and each entry has its `score` set; otherwise the unranked candidate list is

  returned for the caller to choose from. The call never raises because of a

  provider failure.

  """

  @spec search(String.t(), keyword()) :: {:ok, [Entry.t()]}

  def search(query, opts \\ []) when is_binary(query) do

    candidates = list(opts)

    top_k = Keyword.get(opts, :top_k, default_top_k())

    with true <- query != "" and Embeddings.enabled?(),

         {:ok, query_vector} <- Embeddings.embed_query(query),

         digest <- Embeddings.digest(candidates),

         vectors <- Embeddings.vectors(digest) || warm_and_vectors(candidates),

         true <- is_map(vectors) do

      ranked =

        candidates

        |> Enum.map(fn entry ->

          vector = Map.get(vectors, entry, [])

          score = Embeddings.cosine(query_vector, vector)

          %{entry | score: score}

        end)

        |> Enum.sort_by(fn entry -> {-entry.score, entry.manifest["name"]} end)

        |> Enum.take(top_k)

      {:ok, ranked}

    else

      _ -> {:ok, candidates}

    end

  end

  defp warm_and_vectors(candidates) do

    case Embeddings.warm(candidates) do

      :ok -> Embeddings.vectors(Embeddings.digest(candidates))

      :error -> nil

    end

  end

  defp default_top_k do

    :openagents

    |> Application.get_env(:plugin_discovery, [])

    |> Keyword.get(:top_k, 12)

  end

  defp fetch(module) when is_atom(module), do: module.entries()

defmodule OpenAgents.Plugins.SearchTest do

  use ExUnit.Case, async: false

  alias OpenAgents.Plugins.Index

  @fixture_path "test/fixtures/plugin_manifest.json"

  @weather_manifest %{

    "manifest_version" => 1,

    "name" => "weather_check",

    "version" => "0.1.0",

    "author" => "OpenAgents",

    "description" => "Check the local weather forecast and report current conditions.",

    "artifact" => %{

      "path" => "weather_check.wasm",

      "digest" => "sha256:0000000000000000000000000000000000000000000000000000000000000000"

    },

    "abi" => %{

      "kind" => "packet-v0",

      "entry" => "handle_packet",

      "alloc" => "packet_alloc"

    },

    "interface" => %{

      "input" => %{"type" => "object"},

      "output" => %{"type" => "object"}

    },

    "capabilities" => %{

      "mounts" => [],

      "hosts" => [],

      "timeout_ms" => 1000,

      "memory_max_mib" => 64

    },

    "price_msats" => nil,

    "license" => "MIT"

  }

  setup do

    original = Application.get_env(:openagents, :plugin_discovery)

    :persistent_term.put({OpenAgents.Plugins.Embeddings, :vectors}, nil)

    on_exit(fn ->

      :persistent_term.put({OpenAgents.Plugins.Embeddings, :vectors}, nil)

      Application.put_env(:openagents, :plugin_discovery, original)

    end)

    :ok

  end

  defp git_manifest do

    @fixture_path

    |> File.read!()

    |> Jason.decode!()

  end

  defp git_entry,

    do: %{

      repository: "OpenAgentsInc/git-lost-work",

      release: "main",

      raw_manifest: git_manifest()

    }

  defp weather_entry,

    do: %{

      repository: "OpenAgentsInc/weather-check",

      release: "main",

      raw_manifest: @weather_manifest

    }

  describe "search/2" do

    test "ranks manifests by cosine when embeddings are enabled" do

      Application.put_env(:openagents, :plugin_discovery,

        embeddings_enabled: true,

        provider: OpenAgents.Plugins.EmbeddingsTestProvider,

        model_id: "test",

        model_version: "test",

        dimensions: 4,

        top_k: 2

      )

      {:ok, [first, second]} = Index.search("git history", source: [git_entry(), weather_entry()])

      assert first.manifest["name"] == "git_lost_work"

      assert first.score > 0.0

      assert second.manifest["name"] == "weather_check"

      assert second.score == 0.0

      assert first.score > second.score

    end

    test "returns the unranked candidate list when embeddings are disabled" do

      Application.put_env(:openagents, :plugin_discovery,

        embeddings_enabled: false,

        provider: OpenAgents.Plugins.EmbeddingsTestProvider,

        model_id: "test",

        model_version: "test",

        dimensions: 4,

        top_k: 1

      )

      {:ok, [first, second]} = Index.search("git history", source: [git_entry(), weather_entry()])

      assert first.manifest["name"] == "git_lost_work"

      assert is_nil(first.score)

      assert second.manifest["name"] == "weather_check"

      assert is_nil(second.score)

    end

    test "returns the unranked candidate list instead of raising when the provider errors" do

      Application.put_env(:openagents, :plugin_discovery,

        embeddings_enabled: true,

        provider: OpenAgents.Plugins.EmbeddingsErrorProvider,

        model_id: "test",

        model_version: "test",

        dimensions: 4,

        top_k: 1

      )

      {:ok, [first, second]} = Index.search("git history", source: [git_entry(), weather_entry()])

      assert first.manifest["name"] == "git_lost_work"

      assert is_nil(first.score)

      assert second.manifest["name"] == "weather_check"

      assert is_nil(second.score)

    end

  end

end

defmodule OpenAgents.Plugins.EmbeddingsErrorProvider do

  @moduledoc false

  @behaviour OpenAgents.Memory.EmbeddingProvider

  @impl true

  def embed(_text, _config), do: {:error, :test_provider_error}

end

defmodule OpenAgents.Plugins.EmbeddingsTestProvider do

  @moduledoc false

  @behaviour OpenAgents.Memory.EmbeddingProvider

  @words ["git", "history", "weather", "forecast"]

  @impl true

  def embed(text, %{dimensions: dimensions}) do

    vector = for _ <- 1..dimensions, do: 0.0

    tokens = text |> String.downcase() |> String.split(~r/[^a-z0-9]+/u, trim: true)

    vector =

      Enum.reduce(tokens, vector, fn token, acc ->

        case Enum.find_index(@words, &(&1 == token)) do

          nil ->

            acc

          idx when idx < dimensions ->

            List.update_at(acc, idx, &(&1 + 1.0))

          _other ->

            acc

        end

      end)

    {:ok, vector}

  end

end