Construct universal modules with decoded options

2026-07-17 06:30:56 +00:00
parent ce3a07512f
commit b949e9bbc0
22 changed files with 290 additions and 158 deletions
--- a/internal/modules/dnd/chunk/scenes/chunker.go
+++ b/internal/modules/dnd/chunk/scenes/chunker.go
@@ -33,10 +33,17 @@ var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
 var _ contracts.Chunker = (*Chunker)(nil)
 var _ contracts.ManifestMetadataProvider = (*Chunker)(nil)

-type Chunker struct{}
+type Options struct{}

-func New() *Chunker {
-	return &Chunker{}
+type Chunker struct {
+	llm contracts.StructuredLLMClient
+}
+
+func New(llmClient contracts.StructuredLLMClient, _ Options) (*Chunker, error) {
+	if llmClient == nil {
+		return nil, chunkerErrorf("LLM client must not be nil")
+	}
+	return &Chunker{llm: llmClient}, nil
 }

 func (c *Chunker) Key() string {
@@ -71,6 +78,9 @@ func (c *Chunker) Chunk(ctx context.Context, req contracts.ChunkRequest) (contra
 	if c == nil {
 		return contracts.ChunkResult{}, chunkerErrorf("chunker must not be nil")
 	}
+	if c.llm == nil {
+		return contracts.ChunkResult{}, chunkerErrorf("LLM client must not be nil")
+	}
 	if ctx == nil {
 		return contracts.ChunkResult{}, chunkerErrorf("context must not be nil")
 	}
@@ -86,15 +96,8 @@ func (c *Chunker) Chunk(ctx context.Context, req contracts.ChunkRequest) (contra
 	if err := source.ValidateDocument(req.Source); err != nil {
 		return contracts.ChunkResult{}, chunkerErrorf("validate source document: %w", err)
 	}
-	if req.LLMClient == nil {
-		return contracts.ChunkResult{}, chunkerErrorf("LLM client must not be nil")
-	}
-	if len(req.Options) > 0 {
-		return contracts.ChunkResult{}, chunkerErrorf("options are not supported")
-	}
-
 	var response chunkResponse
-	if _, err := req.LLMClient.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
+	if _, err := c.llm.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
 		StageName:     Key,
 		PromptID:      PromptID,
 		PromptVersion: ResponseSchemaVersion,
@@ -130,11 +133,27 @@ func ModuleSpec() pipeline.ModuleSpec {
 }

 func Register(registry *pipeline.ChunkerRegistry) error {
-	return registry.RegisterWithSpec(ModuleSpec(), func() (contracts.Chunker, error) {
-		return New(), nil
+	return registry.RegisterBuilderWithSpec(ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Chunker, error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(request.Dependencies.LLM, options)
 	})
 }

+func validateOptions(options map[string]any) error {
+	_, err := DecodeOptions(options)
+	return err
+}
+
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, chunkerErrorf("%w", err)
+	}
+	return Options{}, nil
+}
+
 func chunksFromResponse(doc *source.SourceDocument, response chunkResponse) ([]source.Chunk, error) {
 	if response.Scenes == nil {
 		return nil, fmt.Errorf("scenes must be present")
--- a/internal/modules/dnd/chunk/scenes/chunker_test.go
+++ b/internal/modules/dnd/chunk/scenes/chunker_test.go
@@ -15,10 +15,8 @@ import (
 )

 func TestNewModuleSpecAndRegister(t *testing.T) {
-	chunker := New()
-	if chunker == nil {
-		t.Fatal("New() = nil, want chunker")
-	}
+	client := &fakeScenesLLMClient{}
+	chunker := newChunker(t, client)
 	if chunker.Key() != Key {
 		t.Fatalf("Key() = %q, want %q", chunker.Key(), Key)
 	}
@@ -52,7 +50,7 @@ func TestNewModuleSpecAndRegister(t *testing.T) {
 	if !reflect.DeepEqual(registered, want) {
 		t.Fatalf("registered spec = %#v, want %#v", registered, want)
 	}
-	built, err := registry.Build(Key)
+	built, err := registry.BuildWithRequest(Key, pipeline.BuildRequest{Dependencies: pipeline.ModuleDependencies{LLM: client}})
 	if err != nil {
 		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
 	}
@@ -62,6 +60,18 @@ func TestNewModuleSpecAndRegister(t *testing.T) {
 	if slots := built.ReferenceSlots(); !reflect.DeepEqual(slots, want.ReferenceSlots) {
 		t.Fatalf("ReferenceSlots() = %#v, want %#v", slots, want.ReferenceSlots)
 	}
+	if err := registry.ValidateOptions(Key, map[string]any{"unexpected": true}); err == nil || !strings.Contains(err.Error(), "unknown option") {
+		t.Fatalf("ValidateOptions() error = %v, want unknown option error", err)
+	}
+}
+
+func TestConstructionRejectsMissingDependencyAndUnknownOptions(t *testing.T) {
+	if _, err := New(nil, Options{}); err == nil || !strings.Contains(err.Error(), "LLM client") {
+		t.Fatalf("New(nil) error = %v, want LLM client error", err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil || !strings.Contains(err.Error(), "unknown option") {
+		t.Fatalf("DecodeOptions() error = %v, want unknown option error", err)
+	}
 }

 func TestRegisterNilRegistryReturnsError(t *testing.T) {
@@ -129,7 +139,7 @@ func TestChunkReturnsSceneChunksFromStructuredOutput(t *testing.T) {
 		},
 	}

-	result, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+	result, err := newChunker(t, client).Chunk(context.Background(), chunkRequest())
 	if err != nil {
 		t.Fatalf("Chunk() error = %v, want nil", err)
 	}
@@ -221,7 +231,7 @@ func TestChunkPassesReferencesAsPromptInputs(t *testing.T) {
 			},
 		},
 	}}
-	req := chunkRequestWithClient(client)
+	req := chunkRequest()
 	req.References = contracts.ReferenceSet{
 		Slots: map[string]contracts.ResolvedReferenceSlot{
 			"players": {
@@ -245,7 +255,7 @@ func TestChunkPassesReferencesAsPromptInputs(t *testing.T) {
 		},
 	}

-	if _, err := New().Chunk(context.Background(), req); err != nil {
+	if _, err := newChunker(t, client).Chunk(context.Background(), req); err != nil {
 		t.Fatalf("Chunk() error = %v, want nil", err)
 	}
 	request := client.requests[0]
@@ -293,7 +303,7 @@ func TestChunkRejectsWhitespaceOnlyBoundaryCaveats(t *testing.T) {
 		},
 	}

-	_, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+	_, err := newChunker(t, client).Chunk(context.Background(), chunkRequest())
 	if err == nil {
 		t.Fatal("Chunk() error = nil, want malformed structured output error")
 	}
@@ -306,12 +316,11 @@ func TestChunkDefensivelyCopiesSourceUnitsAndMetadata(t *testing.T) {
 	doc := sceneSourceDocument()
 	client := &fakeScenesLLMClient{response: validSceneResponse()}

-	result, err := New().Chunk(context.Background(), contracts.ChunkRequest{
+	result, err := newChunker(t, client).Chunk(context.Background(), contracts.ChunkRequest{
 		Source:      doc,
 		SourceInput: sceneSourceInput(),
 		SessionID:   "session-123",
 		LLMProfile:  "profile-scenes",
-		LLMClient:   client,
 	})
 	if err != nil {
 		t.Fatalf("Chunk() error = %v, want nil", err)
@@ -338,7 +347,7 @@ func TestChunkDefensivelyCopiesSourceUnitsAndMetadata(t *testing.T) {
 }

 func TestChunkerManifestMetadataIncludesPromptAndSchemaProvenance(t *testing.T) {
-	metadata := New().ManifestMetadata()
+	metadata := newChunker(t, &fakeScenesLLMClient{}).ManifestMetadata()

 	tests := map[string]string{
 		"prompt_id":               PromptID,
@@ -368,7 +377,7 @@ func TestChunkerManifestMetadataIncludesPromptAndSchemaProvenance(t *testing.T)

 func TestChunkRejectsInvalidRequests(t *testing.T) {
 	validClient := &fakeScenesLLMClient{response: validSceneResponse()}
-	validReq := chunkRequestWithClient(validClient)
+	validReq := chunkRequest()
 	canceledCtx, cancel := context.WithCancel(context.Background())
 	cancel()
 	invalidDoc := sceneSourceDocument()
@@ -384,13 +393,11 @@ func TestChunkRejectsInvalidRequests(t *testing.T) {
 		want    string
 	}{
 		{name: "nil chunker", chunker: nil, ctx: context.Background(), req: validReq, want: "chunker"},
-		{name: "nil context", chunker: New(), ctx: nil, req: validReq, want: "context"},
-		{name: "canceled context", chunker: New(), ctx: canceledCtx, req: validReq, want: "context"},
-		{name: "nil source", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{LLMClient: validClient}, want: "source"},
-		{name: "empty source units", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{Source: emptyDoc, LLMClient: validClient}, want: "units"},
-		{name: "invalid source", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{Source: invalidDoc, LLMClient: validClient}, want: "validate source document"},
-		{name: "nil LLM client", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{Source: sceneSourceDocument()}, want: "LLM client"},
-		{name: "unsupported options", chunker: New(), ctx: context.Background(), req: requestWithOptions(validReq), want: "options"},
+		{name: "nil context", chunker: newChunker(t, validClient), ctx: nil, req: validReq, want: "context"},
+		{name: "canceled context", chunker: newChunker(t, validClient), ctx: canceledCtx, req: validReq, want: "context"},
+		{name: "nil source", chunker: newChunker(t, validClient), ctx: context.Background(), req: contracts.ChunkRequest{}, want: "source"},
+		{name: "empty source units", chunker: newChunker(t, validClient), ctx: context.Background(), req: contracts.ChunkRequest{Source: emptyDoc}, want: "units"},
+		{name: "invalid source", chunker: newChunker(t, validClient), ctx: context.Background(), req: contracts.ChunkRequest{Source: invalidDoc}, want: "validate source document"},
 	}

 	for _, tt := range tests {
@@ -488,7 +495,7 @@ func TestChunkRejectsMalformedStructuredOutput(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			client := &fakeScenesLLMClient{response: tt.response}
-			_, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+			_, err := newChunker(t, client).Chunk(context.Background(), chunkRequest())
 			if err == nil {
 				t.Fatal("Chunk() error = nil, want error")
 			}
@@ -502,7 +509,7 @@ func TestChunkRejectsMalformedStructuredOutput(t *testing.T) {
 func TestChunkWrapsLLMClientError(t *testing.T) {
 	client := &fakeScenesLLMClient{err: errors.New("provider unavailable")}

-	_, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+	_, err := newChunker(t, client).Chunk(context.Background(), chunkRequest())
 	if err == nil {
 		t.Fatal("Chunk() error = nil, want LLM error")
 	}
@@ -511,13 +518,12 @@ func TestChunkWrapsLLMClientError(t *testing.T) {
 	}
 }

-func chunkRequestWithClient(client contracts.StructuredLLMClient) contracts.ChunkRequest {
+func chunkRequest() contracts.ChunkRequest {
 	return contracts.ChunkRequest{
 		Source:      sceneSourceDocument(),
 		SourceInput: sceneSourceInput(),
 		SessionID:   "session-123",
 		LLMProfile:  "profile-scenes",
-		LLMClient:   client,
 	}
 }

@@ -527,9 +533,13 @@ func sceneSourceInput() contracts.LLMInputMaterial {
 	return contracts.NewLLMInputMaterial("source", "application/json", []byte(sceneTranscriptJSON), "sha256:transcript", "file:///session-alpha.json")
 }

-func requestWithOptions(req contracts.ChunkRequest) contracts.ChunkRequest {
-	req.Options = map[string]any{"max_units": 2}
-	return req
+func newChunker(t *testing.T, client contracts.StructuredLLMClient) *Chunker {
+	t.Helper()
+	chunker, err := New(client, Options{})
+	if err != nil {
+		t.Fatalf("New() error = %v, want nil", err)
+	}
+	return chunker
 }

 func sceneSourceDocument() *source.SourceDocument {
--- a/internal/modules/dnd/chunk/scenes/scriptorium_assets_test.go
+++ b/internal/modules/dnd/chunk/scenes/scriptorium_assets_test.go
@@ -47,7 +47,7 @@ func TestScriptoriumPromptPreparesTranscriptAndTaskMessages(t *testing.T) {
 func TestScriptoriumPromptDiagnosticsOmitRawMaterials(t *testing.T) {
 	transcript := []byte(`{"secret":"source text"}`)
 	prepared := prepareScenesPrompt(t, transcript, "private player note", "private party note", "private glossary note")
-	metadata := New().ManifestMetadata()
+	metadata := newChunker(t, &fakeScenesLLMClient{}).ManifestMetadata()

 	payload, err := json.Marshal(map[string]any{
 		"prepared": map[string]any{