fix: enforce deck AI response invariants

Author: cfbender

lib/manavault/ai.ex

@@ -53,7 +53,12 @@ defmodule Manavault.AI do
          {:ok, provider} <- Provider.module(settings.provider),
          payload <- DeckAnalysis.payload(deck, Catalog.deck_cards(deck)),
          {:ok, provider_result} <- provider.analyze_deck(settings, payload),
-         {:ok, result} <- DeckAnalysis.normalize_result(provider_result, payload),
+         {:ok, result} <-
+           DeckAnalysis.normalize_result(
+             provider_result,
+             payload,
+             settings.deck_analysis_instructions
+           ),
          attrs <- analysis_attrs(result, settings),
          {:ok, deck} <- Catalog.save_deck_analysis(deck, attrs) do
       {:ok, deck}

lib/manavault/ai/deck_analysis.ex

@@ -42,6 +42,9 @@ defmodule Manavault.AI.DeckAnalysis do
     Keep the final analysis compact: use one concise paragraph for each narrative field and three to
     five concise items for each standard list when the deck supports that many. Use deeper reasoning
     to improve the analysis rather than making the final response longer.
+    Every suggested card must be legal in the deck's format. For Commander decks, its color identity
+    must also be contained within deck.commander_color_identity. Omit any card whose legality or
+    color identity you cannot verify rather than guessing.
     The facts object contains authoritative metadata calculated by ManaVault. Use its counts instead
     of recounting deck.cards.
 
@@ -117,7 +120,7 @@ defmodule Manavault.AI.DeckAnalysis do
     """
   end
 
-  def response_schema do
+  def response_schema(custom_instructions \\ nil) do
     string = %{type: "string"}
     strings = %{type: "array", items: string}
     nullable_bracket = %{type: ["integer", "null"], minimum: 1, maximum: 5}
@@ -132,6 +135,11 @@ defmodule Manavault.AI.DeckAnalysis do
       }
     }
 
+    custom_sections =
+      if custom_instructions?(custom_instructions),
+        do: custom_sections,
+        else: Map.put(custom_sections, :maxItems, 0)
+
     %{
       type: "object",
       additionalProperties: false,
@@ -156,8 +164,15 @@ defmodule Manavault.AI.DeckAnalysis do
     }
   end
 
-  def normalize_result(result, payload) when is_map(result) do
+  def normalize_result(result, payload, custom_instructions \\ nil)
+
+  def normalize_result(result, payload, custom_instructions) when is_map(result) do
     with {:ok, normalized} <- normalized_fields(result),
+         normalized <-
+           if(custom_instructions?(custom_instructions),
+             do: normalized,
+             else: Map.put(normalized, :custom_sections, [])
+           ),
          normalized <-
            Map.merge(normalized, %{
              official_bracket: value(result, :official_bracket),
@@ -168,7 +183,7 @@ defmodule Manavault.AI.DeckAnalysis do
     end
   end
 
-  def normalize_result(_result, _payload),
+  def normalize_result(_result, _payload, _custom_instructions),
     do: {:error, "The AI provider returned an invalid analysis."}
 
   def render_markdown(result) do
@@ -288,8 +303,27 @@ defmodule Manavault.AI.DeckAnalysis do
     if payload.deck.format == "commander" do
       with true <- valid_bracket?(official),
            true <- valid_bracket?(practical) do
-        official = max(official, game_changer_minimum(payload.facts.game_changer_count))
-        {:ok, Map.merge(result, %{official_bracket: official, play_bracket: practical})}
+        game_changer_count = payload.facts.game_changer_count
+        minimum = game_changer_minimum(game_changer_count)
+
+        result =
+          Map.merge(result, %{
+            official_bracket: max(official, minimum),
+            play_bracket: practical
+          })
+
+        result =
+          if official < minimum do
+            Map.put(
+              result,
+              :bracket_rationale,
+              corrected_bracket_rationale(game_changer_count, minimum, practical)
+            )
+          else
+            result
+          end
+
+        {:ok, result}
       else
         _invalid -> {:error, "The AI provider returned an invalid Commander bracket."}
       end
@@ -315,6 +349,20 @@ defmodule Manavault.AI.DeckAnalysis do
   defp game_changer_minimum(count) when count <= 3, do: 3
   defp game_changer_minimum(_count), do: 4
 
+  defp corrected_bracket_rationale(game_changer_count, minimum, practical) do
+    game_changers =
+      if game_changer_count == 1,
+        do: "1 Game Changer",
+        else: "#{game_changer_count} Game Changers"
+
+    "The official Commander Brackets guidelines require at least Bracket #{minimum} because " <>
+      "the deck contains #{game_changers}. Based on the rest of the list, it is expected to " <>
+      "play like Bracket #{practical}."
+  end
+
+  defp custom_instructions?(instructions),
+    do: is_binary(instructions) and String.trim(instructions) != ""
+
   defp section(title, content), do: "## #{title}\n\n#{content}"
 
   defp list_section(title, items) do

lib/manavault/ai/providers/open_router.ex

@@ -51,7 +51,7 @@ defmodule Manavault.AI.Providers.OpenRouter do
         json_schema: %{
           name: "manavault_deck_analysis",
           strict: true,
-          schema: DeckAnalysis.response_schema()
+          schema: DeckAnalysis.response_schema(settings.deck_analysis_instructions)
         }
       }
     }
@@ -79,7 +79,7 @@ defmodule Manavault.AI.Providers.OpenRouter do
         %{role: "system", content: DeckQuestion.system_prompt()},
         %{role: "user", content: DeckQuestion.user_prompt(question, payload)}
       ],
-      max_tokens: 8_000,
+      max_tokens: 20_000,
       temperature: 0.2,
       plugins: [%{id: "response-healing"}],
       response_format: %{

test/manavault/ai/deck_analysis_test.exs

@@ -25,6 +25,8 @@ defmodule Manavault.AI.DeckAnalysisTest do
     assert {:ok, result} = DeckAnalysis.normalize_result(@result, payload)
     assert result.official_bracket == 3
     assert result.play_bracket == 3
+    assert result.bracket_rationale =~ "require at least Bracket 3"
+    assert result.bracket_rationale =~ "1 Game Changer"
 
     weaker = Map.put(@result, "play_bracket", 2)
     assert {:ok, weaker_result} = DeckAnalysis.normalize_result(weaker, payload)
@@ -69,7 +71,8 @@ defmodule Manavault.AI.DeckAnalysisTest do
         }
       ])
 
-    assert {:ok, normalized} = DeckAnalysis.normalize_result(result, payload)
+    assert {:ok, normalized} =
+             DeckAnalysis.normalize_result(result, payload, "Add a budget upgrades section.")
 
     assert normalized.custom_sections == [
              %{title: "Budget upgrades", content: "- Start with [[Counterspell]]."}
@@ -79,6 +82,25 @@ defmodule Manavault.AI.DeckAnalysisTest do
              "## Budget upgrades\n\n- Start with [[Counterspell]]."
   end
 
+  test "requires empty custom sections when no custom instructions exist" do
+    schema = DeckAnalysis.response_schema()
+    assert schema.properties.custom_sections.maxItems == 0
+
+    custom_schema =
+      DeckAnalysis.response_schema("Add a budget section.").properties.custom_sections
+
+    refute Map.has_key?(custom_schema, :maxItems)
+
+    result =
+      Map.put(@result, "custom_sections", [
+        %{"title" => "Strengths", "content" => "Duplicated standard content."}
+      ])
+
+    payload = %{deck: %{format: "modern"}, facts: %{game_changer_count: 0}}
+    assert {:ok, normalized} = DeckAnalysis.normalize_result(result, payload)
+    assert normalized.custom_sections == []
+  end
+
   test "payload includes authoritative land metadata from counted deck zones" do
     deck = %Deck{name: "Land Count", format: "commander"}
 

test/manavault/ai_test.exs

@@ -198,7 +198,7 @@ defmodule Manavault.AITest do
 
       assert request["response_format"]["type"] == "json_schema"
       assert request["plugins"] == [%{"id" => "response-healing"}]
-      assert request["max_tokens"] == 8_000
+      assert request["max_tokens"] == 20_000
       refute Map.has_key?(request, "max_completion_tokens")
       refute Map.has_key?(request, "reasoning")
 
@@ -281,7 +281,7 @@ defmodule Manavault.AITest do
       {:ok, request_body, conn} = Plug.Conn.read_body(conn)
       request = Jason.decode!(request_body)
       refute Map.has_key?(request, "reasoning")
-      assert request["max_tokens"] == 8_000
+      assert request["max_tokens"] == 20_000
 
       json_response(conn, 200, %{
         "provider" => "Google",
@@ -294,7 +294,7 @@ defmodule Manavault.AITest do
         ],
         "usage" => %{
           "prompt_tokens" => 12_345,
-          "completion_tokens" => 8_000,
+          "completion_tokens" => 20_000,
           "completion_tokens_details" => %{"reasoning_tokens" => 7_950}
         }
       })
@@ -311,7 +311,7 @@ defmodule Manavault.AITest do
     assert log =~ "finish_reason=\"length\""
     assert log =~ "native_finish_reason=\"MAX_TOKENS\""
     assert log =~ "prompt_tokens=12345"
-    assert log =~ "completion_tokens=8000"
+    assert log =~ "completion_tokens=20000"
     assert log =~ "reasoning_tokens=7950"
     assert log =~ "result=output_token_limit"
     refute log =~ "Do not include this question in logs."
@@ -334,7 +334,7 @@ defmodule Manavault.AITest do
       {:ok, request_body, conn} = Plug.Conn.read_body(conn)
       request = Jason.decode!(request_body)
       refute Map.has_key?(request, "reasoning")
-      assert request["max_tokens"] == 8_000
+      assert request["max_tokens"] == 20_000
 
       json_response(conn, 200, %{
         "provider" => "Parasail",