fix: make router vector defaults generic

Author: nshkrdotcom

CHANGELOG.md

@@ -8,4 +8,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.0] - 2026-05-23
 
 ### Added
-- Initial release of `CrucibleFactorization` under the TRINITY decomposition.
+- Initial release of `CrucibleFactorization` from the monolith extraction.

MIGRATION.md

@@ -1,8 +1,7 @@
 # Migration Notes
 
-This repo was scaffolded during TRINITY decomposition Phase 1 so
-`trinity_framework` could resolve local path dependencies before the public
-GitHub repos existed.
+This repo was scaffolded during the monolith extraction so framework consumers
+could resolve local path dependencies before the public GitHub repos existed.
 
 Source material for the Phase 3 implementation:
 
@@ -16,4 +15,5 @@ Source material for the Phase 3 implementation:
 The implementation keeps provider, orchestration, tracing, and product runtime
 dependencies out of the factorization package. Compatibility functions that
 previously accepted model-state structs now operate on generic maps or structs
-with a `:data` field.
+with a `:data` field. Product-specific tensor keys belong in callers, not in
+the reusable package defaults.

README.md

@@ -13,12 +13,30 @@
   </a>
 </p>
 
-Nx SVD/SVF factorization primitives for model surgery and TRINITY artifact
-export.
+Nx SVD/SVF factorization primitives for model surgery and artifact export.
 
-This package intentionally owns the temporary Nx/EXLA git pin required for the
-thin-SVD memory behavior used by the coordinator. Contract packages should not
-inherit that pin directly.
+This package is intentionally narrow. It owns numerical factorization,
+reconstruction, tensor traversal, manifest helpers, and router-vector splitting.
+It avoids provider, tracing, orchestration, and application runtime dependencies.
+Callers that use product-specific artifact names should pass those names
+explicitly at the API boundary.
+
+## What It Provides
+
+- `CrucibleFactorization.SVD.thin/2` and `thin!/2` run reduced SVD with timing,
+  backend, rank, and sync metadata.
+- `CrucibleFactorization.SVD.reconstruct/3` rebuilds tensors from SVD
+  components and scale offsets.
+- `CrucibleFactorization.SVD.decompose_tensors/2`,
+  `reconstruct_tensors/3`, and `adapt_tensors/3` operate on selected tensor
+  entries from nested parameter trees.
+- `CrucibleFactorization.SVF` provides low-rank singular-vector-field helpers
+  for `base_tensor + low_rank_delta` workflows.
+- `CrucibleFactorization.StageCheck` and `ParityReport` provide math-only
+  tensor comparison summaries.
+- `CrucibleFactorization.SVD.load_router_vector!/2` and
+  `split_router_vector/4` load and split a flat vector into scale offsets and
+  dense head weights. The default tensor name is the generic `"router_vector"`.
 
 ## Installation
 
@@ -37,6 +55,78 @@ Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_do
 and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
 be found at <https://hexdocs.pm/crucible_factorization>.
 
+## Thin SVD
+
+```elixir
+alias CrucibleFactorization.SVD
+
+matrix = Nx.tensor([[2.0, 4.0], [1.0, 2.0]], type: :f32)
+
+{:ok, result} = SVD.thin(matrix, rank: 1, compute_type: :f32, force_sync?: true)
+reconstructed = SVD.reconstruct(result, Nx.broadcast(0.0, {result.rank}))
+```
+
+`result` includes `:u`, `:s`, `:v`, `:rank`, source type, backend label,
+decompose timing, and optional force-sync timing.
+
+## SVF Delta Reconstruction
+
+```elixir
+alias CrucibleFactorization.SVF
+
+base = Nx.tensor([[1.0, 1.0], [1.0, 1.0]], type: :f32)
+delta = Nx.tensor([[2.0, 4.0], [1.0, 2.0]], type: :f32)
+
+{:ok, svf} = SVF.decompose(delta, rank: 1)
+{:ok, adapted} = SVF.reconstruct(base, svf)
+```
+
+## Tensor Traversal
+
+```elixir
+entries =
+  params
+  |> SVD.decomposable_tensor_entries(path_filter: SVD.layer_index_filter([26]))
+
+manifest = SVD.tensor_manifest(entries)
+count = SVD.singular_value_count(entries)
+```
+
+The helpers accept generic nested maps, lists, tuples, and structs with a
+`:data` field. They do not require a framework runtime struct.
+
+## Router Vector Helpers
+
+```elixir
+vector = SVD.load_router_vector!("router_vector.safetensors")
+
+split =
+  SVD.split_router_vector(
+    vector,
+    scale_count,
+    hidden_size,
+    output_count
+  )
+
+split.scale_offsets
+split.head_weights
+```
+
+For product-specific safetensors keys, pass the key explicitly:
+
+```elixir
+vector = SVD.load_router_vector!("artifact.safetensors", "product_router_vector")
+```
+
+## Backend And Sync Options
+
+`thin/2` accepts:
+
+- `:rank` for reduced rank selection.
+- `:compute_type`, either `:source` or `:f32`.
+- `:backend` for `Nx.backend_transfer/2`.
+- `:force_sync?` and `:sync_fun` for timing asynchronous backends.
+
 ## CI
 
 ```sh
@@ -48,3 +138,6 @@ CUDA is opt-in:
 ```sh
 XLA_TARGET=cuda12 mix test --only cuda
 ```
+
+`mix ci` runs dependency fetch, format check, warning-as-error compile, tests,
+Credo strict, Dialyzer, and docs generation.

lib/crucible/factorization/svd.ex

@@ -5,7 +5,7 @@ defmodule Crucible.Factorization.SVD do
 
   alias CrucibleFactorization.{Backend, Errors, StageTiming}
 
-  @router_vector_key "trinity_router_es_vector"
+  @router_vector_key "router_vector"
 
   @type decomposition :: %{
           required(:u) => Nx.Tensor.t(),

lib/crucible_factorization.ex

@@ -1,18 +1,5 @@
 defmodule CrucibleFactorization do
   @moduledoc """
-  Documentation for `CrucibleFactorization`.
+  Nx SVD/SVF factorization primitives for model surgery and artifact export.
   """
-
-  @doc """
-  Hello world.
-
-  ## Examples
-
-      iex> CrucibleFactorization.hello()
-      :world
-
-  """
-  def hello do
-    :world
-  end
 end

lib/crucible_factorization/svd.ex

@@ -24,7 +24,7 @@ defmodule CrucibleFactorization.SVD do
   defdelegate adapt_tensors(tensors, scale_offsets, opts \\ []), to: Crucible.Factorization.SVD
   defdelegate put_tensor_entries(container, tensor_entries), to: Crucible.Factorization.SVD
 
-  defdelegate load_router_vector!(path, tensor_name \\ "trinity_router_es_vector"),
+  defdelegate load_router_vector!(path, tensor_name \\ "router_vector"),
     to: Crucible.Factorization.SVD
 
   defdelegate split_router_vector(vector, scale_count, hidden_size, output_count),

test/crucible_factorization/svd_test.exs

@@ -62,6 +62,21 @@ defmodule CrucibleFactorization.SVDTest do
     assert result.backend_label == "Nx.BinaryBackend"
   end
 
+  test "load_router_vector!/2 defaults to a generic tensor name" do
+    path = tmp_path("router_vector.safetensors")
+    Safetensors.write!(path, %{"router_vector" => Nx.tensor([1.0, 2.0], type: :f32)})
+
+    assert SVD.load_router_vector!(path) |> Nx.to_flat_list() == [1.0, 2.0]
+  end
+
+  test "load_router_vector!/2 accepts explicit product tensor names" do
+    path = tmp_path("custom_router_vector.safetensors")
+    tensor_name = "product_router_vector"
+    Safetensors.write!(path, %{tensor_name => Nx.tensor([3.0, 4.0], type: :f32)})
+
+    assert SVD.load_router_vector!(path, tensor_name) |> Nx.to_flat_list() == [3.0, 4.0]
+  end
+
   defp reconstruction_error(result, matrix) do
     result
     |> SVD.reconstruct(Nx.broadcast(0.0, {result.rank}))
@@ -81,4 +96,10 @@ defmodule CrucibleFactorization.SVDTest do
 
     assert max_abs <= tolerance
   end
+
+  defp tmp_path(name) do
+    dir = Path.join(System.tmp_dir!(), "crucible_factorization_tests")
+    File.mkdir_p!(dir)
+    Path.join(dir, "#{System.unique_integer([:positive])}_#{name}")
+  end
 end