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_runTyped shows the generic typed embed binding: RunTyped derives a JSON Schema from a Go type (the same reflection-based derivation sdk/tools/inproc.RegisterFunc uses for tool registration), drives a schema-constrained run, and returns the validated answer already unmarshaled into that type — replacing the WithOutputSchema + json.Unmarshal two-liner with one generic 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/sdk/planner"

	_ "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
}

// sentimentReport is the RunTyped target type for Example_runTyped — a
// plain Go struct, no hand-authored JSON Schema required.
type sentimentReport struct {
	Sentiment  string  `json:"sentiment"`
	Confidence float64 `json:"confidence,omitempty"`
}

// fixedFinishPlanner is a deterministic planner.Planner concrete used
// ONLY to keep this example offline and reproducible: it returns a
// fixed terminal Finish payload with no LLM call at all, so
// Example_runTyped needs no network and no scripted-provider ceremony.
// A production RunTyped call rides the SAME schema-derivation +
// validation path against a real generation-steering planner — see
// docs/recipes/embed-harbor-headless.md and examples/embed-runonce/.
type fixedFinishPlanner struct{ payload any }

func (p fixedFinishPlanner) Next(_ context.Context, _ planner.RunContext) (planner.Decision, error) {
	return planner.Finish{Reason: planner.FinishGoal, Payload: p.payload}, nil
}

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

	cfg := mockRunnableConfig()
	stack, err := assemble.Assemble(ctx, cfg, assemble.Options{
		PlannerOverride: fixedFinishPlanner{
			payload: map[string]any{"sentiment": "positive", "confidence": 0.9},
		},
	})
	if err != nil {
		log.Fatalf("assemble: %v", err)
	}
	defer func() { _ = stack.Close(ctx) }()

	id := identity.Identity{TenantID: "acme", UserID: "u-1", SessionID: "s-1"}
	report, env, err := assemble.RunTyped[sentimentReport](ctx, stack, "Classify the sentiment.", id)
	if err != nil {
		fmt.Println("run:", err)
		return
	}

	fmt.Println(report.Sentiment, env.FinishReason)
}

Output:
positive 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