assemble

Example shows the golden one-call path: Assemble composes a headless runtime from a validated config, and Stack.RunOnce turns a goal plus the mandatory (tenant, user, session) identity triple into a terminal answer envelope in a single blocking call.

package main

import (
	"context"
	"fmt"
	"log"

	// Production driver aggregator — the SAME sdk-facade blank import a
	// headless embedder adds (see docs/recipes/embed-harbor-headless.md)
	// so every Open the assembly performs resolves the production driver
	// set. Copyable as-is: it stays inside the sdk facade.

	// Dev-only mock LLM (D-089): explicit opt-in, never in the aggregator,
	// and deliberately has no sdk facade. It is imported here ONLY to keep
	// the example deterministic and offline; a real deployment configures a
	// real provider in harbor.yaml and drops this import.

	"github.com/hurtener/Harbor/sdk/assemble"
	"github.com/hurtener/Harbor/sdk/config"
	_ "github.com/hurtener/Harbor/sdk/drivers/prod"
	"github.com/hurtener/Harbor/sdk/identity"

	_ "github.com/hurtener/Harbor/internal/llm/mock"
)

// mockRunnableConfig builds the canonical baseline configuration and
// points the LLM seam at the deterministic, offline mock driver. It
// keeps the example bodies focused on the one-call run surface.
func mockRunnableConfig() *config.Config {
	cfg := config.Defaults()
	cfg.Telemetry.LogLevel = "error"
	cfg.LLM.Driver = "mock"
	cfg.LLM.Model = "mock/echo"
	cfg.LLM.ModelProfiles = map[string]config.LLMModelProfileConfig{
		"mock/echo": {ContextWindowTokens: 100000, TokenEstimator: "chars_div_4"},
	}
	return cfg
}

func main() {
	ctx := context.Background()

	cfg := mockRunnableConfig()
	stack, err := assemble.Assemble(ctx, cfg, assemble.Options{})
	if err != nil {
		log.Fatalf("assemble: %v", err)
	}
	defer func() { _ = stack.Close(ctx) }()

	id := identity.Identity{TenantID: "acme", UserID: "u-1", SessionID: "s-1"}
	env, err := stack.RunOnce(ctx, "Summarise the deployment status.", id)
	if err != nil {
		fmt.Println("run:", err)
		return
	}

	fmt.Println(env.FinishReason)
}

Output:
goal

Example_streaming shows RunOnce driving the same run while a WithStream sink observes its StreamEvents — token deltas, planner-step boundaries, and tool dispatches — as they occur. RunOnce still blocks and returns the same terminal envelope; the sink fires synchronously on the run goroutine, so every StreamEvent arrives before RunOnce returns. Here the sink reassembles the streamed content tokens, which reproduce the final answer exactly.

package main

import (
	"context"
	"fmt"
	"log"
	"strings"

	// Production driver aggregator — the SAME sdk-facade blank import a
	// headless embedder adds (see docs/recipes/embed-harbor-headless.md)
	// so every Open the assembly performs resolves the production driver
	// set. Copyable as-is: it stays inside the sdk facade.

	// Dev-only mock LLM (D-089): explicit opt-in, never in the aggregator,
	// and deliberately has no sdk facade. It is imported here ONLY to keep
	// the example deterministic and offline; a real deployment configures a
	// real provider in harbor.yaml and drops this import.

	"github.com/hurtener/Harbor/sdk/assemble"
	"github.com/hurtener/Harbor/sdk/config"
	_ "github.com/hurtener/Harbor/sdk/drivers/prod"
	"github.com/hurtener/Harbor/sdk/identity"

	_ "github.com/hurtener/Harbor/internal/llm/mock"
)

// mockRunnableConfig builds the canonical baseline configuration and
// points the LLM seam at the deterministic, offline mock driver. It
// keeps the example bodies focused on the one-call run surface.
func mockRunnableConfig() *config.Config {
	cfg := config.Defaults()
	cfg.Telemetry.LogLevel = "error"
	cfg.LLM.Driver = "mock"
	cfg.LLM.Model = "mock/echo"
	cfg.LLM.ModelProfiles = map[string]config.LLMModelProfileConfig{
		"mock/echo": {ContextWindowTokens: 100000, TokenEstimator: "chars_div_4"},
	}
	return cfg
}

func main() {
	ctx := context.Background()

	cfg := mockRunnableConfig()
	stack, err := assemble.Assemble(ctx, cfg, assemble.Options{})
	if err != nil {
		log.Fatalf("assemble: %v", err)
	}
	defer func() { _ = stack.Close(ctx) }()

	var streamed strings.Builder
	sink := func(e assemble.StreamEvent) {
		// Content deltas only — skip reasoning tokens and non-token events.
		if e.Kind == assemble.StreamToken && !e.Reasoning {
			streamed.WriteString(e.Text)
		}
	}

	id := identity.Identity{TenantID: "acme", UserID: "u-1", SessionID: "s-1"}
	env, err := stack.RunOnce(ctx, "Ping.", id, assemble.WithStream(sink))
	if err != nil {
		fmt.Println("run:", err)
		return
	}

	fmt.Println(streamed.String() == env.Answer)
}

Output:
true