planner

package
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

Documentation

Overview

Package planner is the public SDK facade over Harbor's internal/planner package — the swappable Planner interface, the Decision sum, the RunContext view, the Trajectory record, and the driver registry external planner concretes register on (RFC §3.6, §6.2). Alias-based re-exports only: no behavior lives here. Event payload structs, prompt-materialisation helpers, and repair internals are deliberately private.

Example

Example shows the planner facade's primary entry surface: the driver registry that makes the Planner swappable. Blank-importing a planner concrete seats its registration; RegisteredDrivers lists the seated names a `planner.driver:` config can resolve. The example also checks a terminal reason against the canonical FinishReason vocabulary.

package main

import (
	"fmt"

	"github.com/hurtener/Harbor/sdk/planner"
	// Blank-importing the reference ReAct planner facade seats its
	// "react" driver registration, so `planner.driver: react` resolves
	// through the registry. sdk/drivers/prod seats it (and the rest of
	// the production set) too.
	_ "github.com/hurtener/Harbor/sdk/planner/react"
)

func main() {
	// The seated planner drivers a config can resolve by name.
	fmt.Println(planner.RegisteredDrivers())

	// FinishGoal is the canonical "goal achieved" terminal reason.
	fmt.Println(planner.IsValidFinishReason(planner.FinishGoal))

}
Output:
[react]
true

Index

Examples

Constants

View Source
const (
	// DispositionRef — ArtifactStub + Fetch.Tool hint (the runtime
	// default for non-image MIMEs).
	DispositionRef = internal.DispositionRef
	// DispositionInline — DataURL inline (image/* only at V1.1; the
	// runtime default for image/*).
	DispositionInline = internal.DispositionInline
	// DispositionProviderNative — provider-side understanding: the
	// materializer flags the typed part and the LLM driver uploads
	// the content inside Complete, rewriting it to a file_id
	// reference. Opt-in, never the default.
	DispositionProviderNative = internal.DispositionProviderNative
)

AttachmentDisposition values.

View Source
const (
	// DispositionLayerCallerHint — the per-attachment hint won.
	DispositionLayerCallerHint = internal.DispositionLayerCallerHint
	// DispositionLayerAgentPolicy — the per-agent policy map won.
	DispositionLayerAgentPolicy = internal.DispositionLayerAgentPolicy
	// DispositionLayerRuntimeDefault — the built-in default won.
	DispositionLayerRuntimeDefault = internal.DispositionLayerRuntimeDefault
)

DispositionLayer values.

View Source
const (
	// DegradationUnknownTool — tool:<name> named no catalog tool.
	DegradationUnknownTool = internal.DegradationUnknownTool
	// DegradationInlineUnsupportedMIME — inline on a non-image MIME.
	DegradationInlineUnsupportedMIME = internal.DegradationInlineUnsupportedMIME
	// DegradationInvalidDisposition — a non-grammar value reached
	// resolution.
	DegradationInvalidDisposition = internal.DegradationInvalidDisposition
)

DispositionDegradationReason values.

View Source
const (
	// FinishGoal — the goal was achieved.
	FinishGoal = internal.FinishGoal
	// FinishNoPath — no step/decision path remains.
	FinishNoPath = internal.FinishNoPath
	// FinishCancelled — the run was cancelled.
	FinishCancelled = internal.FinishCancelled
	// FinishDeadlineExceeded — the run ran out of time/steps.
	FinishDeadlineExceeded = internal.FinishDeadlineExceeded
	// FinishConstraintsConflict — constraints are unsatisfiable.
	FinishConstraintsConflict = internal.FinishConstraintsConflict
)

FinishReason values.

View Source
const (
	// PauseApprovalRequired — HITL approval is required.
	PauseApprovalRequired = internal.PauseApprovalRequired
	// PauseAwaitInput — the run awaits user input.
	PauseAwaitInput = internal.PauseAwaitInput
	// PauseExternalEvent — the run awaits an external event.
	PauseExternalEvent = internal.PauseExternalEvent
	// PauseConstraintsConflict — a conflict requires a human decision.
	PauseConstraintsConflict = internal.PauseConstraintsConflict
)

PauseReason values.

View Source
const (
	// JoinAll — wait for every branch.
	JoinAll = internal.JoinAll
	// JoinFirstSuccess — first successful branch wins.
	JoinFirstSuccess = internal.JoinFirstSuccess
	// JoinKeyed — join on a keyed subset.
	JoinKeyed = internal.JoinKeyed
	// JoinN — join when N branches resolved.
	JoinN = internal.JoinN
)

JoinKind values.

View Source
const (
	// WakePush — the runtime wakes the planner on resolution.
	WakePush = internal.WakePush
	// WakePoll — the planner polls at deterministic boundaries.
	WakePoll = internal.WakePoll
	// WakeHybrid — push with a poll fallback.
	WakeHybrid = internal.WakeHybrid
)

WakeMode values.

View Source
const (
	// TaskErrorCodeRunLoopError — the run loop failed.
	TaskErrorCodeRunLoopError = internal.TaskErrorCodeRunLoopError
	// TaskErrorCodeCancelled — the run was cancelled.
	TaskErrorCodeCancelled = internal.TaskErrorCodeCancelled
)

Task-error codes the runtime maps non-goal finishes to.

Variables

View Source
var (
	// ErrPlannerClosed — the planner has been closed.
	ErrPlannerClosed = internal.ErrPlannerClosed
	// ErrInvalidDecision — the decision failed runtime validation.
	ErrInvalidDecision = internal.ErrInvalidDecision
	// ErrRepairExhausted — the schema-repair budget ran out.
	ErrRepairExhausted = internal.ErrRepairExhausted
	// ErrIdentityRequired — the run's identity quadruple is incomplete.
	ErrIdentityRequired = internal.ErrIdentityRequired
	// ErrInvalidConfig — the planner configuration is invalid.
	ErrInvalidConfig = internal.ErrInvalidConfig
	// ErrDeterministicStep — a deterministic step returned an error.
	ErrDeterministicStep = internal.ErrDeterministicStep
	// ErrParallelCapExceeded — CallParallel exceeded the absolute cap.
	ErrParallelCapExceeded = internal.ErrParallelCapExceeded
	// ErrParallelInvalidJoin — the CallParallel join spec is invalid.
	ErrParallelInvalidJoin = internal.ErrParallelInvalidJoin
	// ErrMemoryBlockUnserializable — a memory block is not JSON-serialisable.
	ErrMemoryBlockUnserializable = internal.ErrMemoryBlockUnserializable
	// ErrDriverUnknown — the named planner driver is not registered.
	ErrDriverUnknown = internal.ErrDriverUnknown
	// ErrNilTrajectory — compression refuses a nil trajectory.
	ErrNilTrajectory = internal.ErrNilTrajectory
	// ErrEmptySummary — the summariser violated its contract.
	ErrEmptySummary = internal.ErrEmptySummary
	// ErrOutputInvalid — a run-level structured-output run's terminal
	// answer failed schema validation after the correction budget
	// (assemble.WithOutputSchema). Never a silent fallback to
	// unvalidated text; the runner returns this typed error instead.
	ErrOutputInvalid = internal.ErrOutputInvalid
)

Re-exported sentinel errors callers compare via errors.Is.

View Source
var ConfigFromOperator = internal.ConfigFromOperator

ConfigFromOperator projects the operator config block into the resolved PlannerConfig.

View Source
var CountToolInvocations = internal.CountToolInvocations

CountToolInvocations counts the actual tool invocations recorded across a Trajectory's steps — the shared semantics behind AnswerEnvelope.ToolCallsSeen. See internal.CountToolInvocations for the counting rule.

View Source
var DecisionInvocationCount = internal.DecisionInvocationCount

DecisionInvocationCount returns the number of tool invocations a single decision represents.

View Source
var DefaultDisposition = internal.DefaultDisposition

DefaultDisposition is the runtime-default layer (image/* → inline, everything else → ref — byte-for-byte the pre-84b dispatch).

View Source
var DefaultTokenEstimator = internal.DefaultTokenEstimator

DefaultTokenEstimator is the chars/4 trajectory token estimate.

View Source
var DispositionPolicyFromConfig = internal.DispositionPolicyFromConfig

DispositionPolicyFromConfig decodes the harbor.yaml `multimodal.disposition` block into a DispositionPolicy.

View Source
var DispositionTool = internal.DispositionTool

DispositionTool builds the parametrised tool:<name> disposition.

View Source
var EffectiveDisposition = internal.EffectiveDisposition

EffectiveDisposition applies runtime capability constraints to a resolved disposition, returning the honoured disposition plus a typed degradation fact when they differ.

View Source
var ErrInvalidDisposition = internal.ErrInvalidDisposition

ErrInvalidDisposition is the loud ParseDisposition failure.

View Source
var HintsFromConfig = internal.HintsFromConfig

HintsFromConfig projects the operator hints block into PlanningHints (nil when the block is empty).

View Source
var IsValidFinishReason = internal.IsValidFinishReason

IsValidFinishReason reports whether r is canonical.

View Source
var IsValidPauseReason = internal.IsValidPauseReason

IsValidPauseReason reports whether r is canonical.

View Source
var MustRegister = internal.MustRegister

MustRegister registers a planner concrete, panicking on conflict (init()-time registration).

View Source
var NewCompressionRunner = internal.NewCompressionRunner

NewCompressionRunner constructs the trajectory-compression runner over a Summariser.

View Source
var NewProcessLocalRegistry = internal.NewProcessLocalRegistry

NewProcessLocalRegistry constructs the process-local handle registry for non-serialisable tool handles.

View Source
var ParseDisposition = internal.ParseDisposition

ParseDisposition validates a carrier string against the disposition grammar.

View Source
var Register = internal.Register

Register registers a planner concrete by name (the seam external planner authors plug into).

View Source
var RegisteredDrivers = internal.RegisteredDrivers

RegisteredDrivers lists the seated planner driver names (blank-import sdk/planner/react or sdk/drivers/prod to seat the production set).

View Source
var Resolve = internal.Resolve

Resolve resolves the configured planner concrete via the driver registry.

View Source
var ResolveDisposition = internal.ResolveDisposition

ResolveDisposition is the pure precedence resolver: per-attachment caller hint > per-agent policy map > runtime default. Returns the resolved disposition and the layer that won.

View Source
var ResolveWakeMode = internal.ResolveWakeMode

ResolveWakeMode resolves a planner's effective WakeMode (WakePush unless the concrete declares otherwise via WakeAware).

View Source
var TaskErrorCodeForFinish = internal.TaskErrorCodeForFinish

TaskErrorCodeForFinish maps a non-goal FinishReason to its task-error code.

View Source
var WithTokenEstimator = internal.WithTokenEstimator

WithTokenEstimator overrides the runner's token estimator.

Functions

This section is empty.

Types

type AnswerEnvelope

type AnswerEnvelope = internal.AnswerEnvelope

AnswerEnvelope is the canonical terminal answer shape.

type AttachmentDisposition added in v1.4.0

type AttachmentDisposition = internal.AttachmentDisposition

AttachmentDisposition declares how an uploaded input artifact is handed to the model (ref / inline / provider_native / tool:<name>).

type AwaitTask

type AwaitTask = internal.AwaitTask

AwaitTask joins a previously spawned task.

type BackgroundMemberOutcome

type BackgroundMemberOutcome = internal.BackgroundMemberOutcome

BackgroundMemberOutcome is one member of a joined group.

type BackgroundResult

type BackgroundResult = internal.BackgroundResult

BackgroundResult is a joined background task's outcome.

type Budget

type Budget = internal.Budget

Budget carries the run's enforced budget caps.

type BudgetHints

type BudgetHints = internal.BudgetHints

BudgetHints carries advisory budget guidance.

type CallParallel

type CallParallel = internal.CallParallel

CallParallel dispatches N tool branches with a join spec.

type CallTool

type CallTool = internal.CallTool

CallTool dispatches one tool.

type ChunkKind

type ChunkKind = internal.ChunkKind

ChunkKind discriminates StreamChunk kinds.

type CompressionOption

type CompressionOption = internal.CompressionOption

CompressionOption customises NewCompressionRunner.

type CompressionRunner

type CompressionRunner = internal.CompressionRunner

CompressionRunner runs trajectory compression at step boundaries.

type ControlSignals

type ControlSignals = internal.ControlSignals

ControlSignals is the steering snapshot the runtime projects.

type Decision

type Decision = internal.Decision

Decision is the sealed decision sum a Planner returns.

type DispositionDegradation added in v1.4.0

type DispositionDegradation = internal.DispositionDegradation

DispositionDegradation is the typed fact returned when a resolved disposition cannot be honoured (the caller logs/emits it).

type DispositionDegradationReason added in v1.4.0

type DispositionDegradationReason = internal.DispositionDegradationReason

DispositionDegradationReason is the typed degradation vocabulary.

type DispositionLayer added in v1.4.0

type DispositionLayer = internal.DispositionLayer

DispositionLayer names the precedence layer that won a resolution.

type DispositionPolicy added in v1.4.0

type DispositionPolicy = internal.DispositionPolicy

DispositionPolicy is the per-agent per-MIME map + default.

type ErrToolContextLost

type ErrToolContextLost = internal.ErrToolContextLost

ErrToolContextLost is the loud lost-handle failure on resume.

type ErrUnserializable

type ErrUnserializable = internal.ErrUnserializable

ErrUnserializable is the loud pause/resume serialization failure (CLAUDE.md §5 fail-loudly; never a silent context drop).

type Factory

type Factory = internal.Factory

Factory constructs a planner concrete from config + deps.

type FactoryDeps

type FactoryDeps = internal.FactoryDeps

FactoryDeps carries the dependencies a Factory may consume.

type FailureRecord

type FailureRecord = internal.FailureRecord

FailureRecord records one repaired/observed failure.

type Finish

type Finish = internal.Finish

Finish is the terminal decision.

type FinishReason

type FinishReason = internal.FinishReason

FinishReason is the canonical terminal reason.

type HandleID

type HandleID = internal.HandleID

HandleID identifies one registered non-serialisable handle.

type HandleRegistry

type HandleRegistry = internal.HandleRegistry

HandleRegistry stores non-serialisable handles across steps.

type InputArtifactView

type InputArtifactView = internal.InputArtifactView

InputArtifactView is one planner-visible input artifact.

type JoinKind

type JoinKind = internal.JoinKind

JoinKind discriminates JoinSpec strategies.

type JoinSpec

type JoinSpec = internal.JoinSpec

JoinSpec describes how CallParallel branches join.

type MemoryBlocks

type MemoryBlocks = internal.MemoryBlocks

MemoryBlocks is the projected memory block set.

type MemoryView

type MemoryView = internal.MemoryView

MemoryView is the read-only memory view a planner sees.

type ParallelBranchObservation

type ParallelBranchObservation = internal.ParallelBranchObservation

ParallelBranchObservation is one branch's observation.

type ParallelObservation

type ParallelObservation = internal.ParallelObservation

ParallelObservation is the joined CallParallel observation.

type PauseReason

type PauseReason = internal.PauseReason

PauseReason is the canonical pause vocabulary.

type Planner

type Planner = internal.Planner

Planner is the swappable reasoning-policy interface (CLAUDE.md §1 property 3). Concretes implement Next(ctx, rc) (Decision, error).

type PlannerConfig

type PlannerConfig = internal.PlannerConfig

PlannerConfig is the resolved planner configuration.

type PlanningHints

type PlanningHints = internal.PlanningHints

PlanningHints are runtime-supplied planning constraints.

type PlanningNudges

type PlanningNudges = internal.PlanningNudges

PlanningNudges are caller-provided ordering/parallel/budget nudges.

type ReasoningReplayMode

type ReasoningReplayMode = internal.ReasoningReplayMode

ReasoningReplayMode controls reasoning-trace replay in prompts.

type RepairCounters

type RepairCounters = internal.RepairCounters

RepairCounters carries the per-run schema-repair counters.

type RequestPause

type RequestPause = internal.RequestPause

RequestPause parks the run on the unified pause/resume primitive.

type ResumeHint

type ResumeHint = internal.ResumeHint

ResumeHint carries the pause's resume guidance.

type RunContext

type RunContext = internal.RunContext

RunContext is the per-step view the runtime projects for the planner (identity, goal, trajectory, catalog, memory, skills).

type Skill

type Skill = internal.Skill

Skill is the planner-visible skill projection.

type SkillLookup

type SkillLookup = internal.SkillLookup

SkillLookup is the read-only skill lookup a planner sees.

type SkillResult

type SkillResult = internal.SkillResult

SkillResult is one planner-visible skill search hit.

type Source

type Source = internal.Source

Source records a step's provenance.

type SpawnSpec

type SpawnSpec = internal.SpawnSpec

SpawnSpec describes the task a SpawnTask decision spawns.

type SpawnTask

type SpawnTask = internal.SpawnTask

SpawnTask spawns a background task (twinned with AwaitTask).

type SteeringInjection

type SteeringInjection = internal.SteeringInjection

SteeringInjection is an INJECT_CONTEXT record on the trajectory.

type Step

type Step = internal.Step

Step is one trajectory step.

type StreamChunk

type StreamChunk = internal.StreamChunk

StreamChunk is one chunked-output fragment on the trajectory.

type Summariser

type Summariser = internal.Summariser

Summariser produces the five-field trajectory Summary.

type Summary

type Summary = internal.Summary

Summary is the compaction artefact of a compressed trajectory.

type TokenEstimator

type TokenEstimator = internal.TokenEstimator

TokenEstimator estimates a trajectory's token footprint.

type ToolCallDeferred

type ToolCallDeferred = internal.ToolCallDeferred

ToolCallDeferred records a deferred (approval-gated) tool call.

type ToolCatalogView

type ToolCatalogView = internal.ToolCatalogView

ToolCatalogView is the identity-filtered catalog view.

type ToolContext

type ToolContext = internal.ToolContext

ToolContext is the tool-only handle bundle (serialisable half + handle registry).

type Trajectory

type Trajectory = internal.Trajectory

Trajectory is the append-only execution log of a run.

type WakeAware

type WakeAware = internal.WakeAware

WakeAware is the optional wake-mode declaration interface.

type WakeMode

type WakeMode = internal.WakeMode

WakeMode declares a planner's wake-on-resolution strategy.

Directories

Path Synopsis
Package deterministic is the public SDK facade over Harbor's internal/planner/deterministic package — the decision-tree planner concrete that drives the same Runtime as the LLM-driven ReAct planner through the identical Planner seam (RFC §3.6, §6.2).
Package deterministic is the public SDK facade over Harbor's internal/planner/deterministic package — the decision-tree planner concrete that drives the same Runtime as the LLM-driven ReAct planner through the identical Planner seam (RFC §3.6, §6.2).
Package react is the public SDK facade over Harbor's internal/planner/react package — the reference LLM-driven ReAct planner concrete (RFC §3.6, §6.2).
Package react is the public SDK facade over Harbor's internal/planner/react package — the reference LLM-driven ReAct planner concrete (RFC §3.6, §6.2).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL