Embedding (Go library)

package main

import (
    "context"
    "fmt"

    "github.com/easel/fizeau"
    _ "github.com/easel/fizeau/configinit"
)

func main() {
    svc, err := fizeau.New(fizeau.ServiceOptions{})
    if err != nil {
        panic(err)
    }
    events, err := svc.Execute(context.Background(), fizeau.ServiceExecuteRequest{
        Prompt:  "Read main.go and tell me the package name",
        Policy:  "cheap",
        WorkDir: ".",
    })
    if err != nil {
        panic(err)
    }
    for event := range events {
        fmt.Println(event.Type)
    }
}

type FizeauService interface {
    Execute(ctx context.Context, req ServiceExecuteRequest) (<-chan ServiceEvent, error)
    TailSessionLog(ctx context.Context, sessionID string) (<-chan ServiceEvent, error)
    ListHarnesses(ctx context.Context) ([]HarnessInfo, error)
    ListProviders(ctx context.Context) ([]ProviderInfo, error)
    ListModels(ctx context.Context, filter ModelFilter) ([]ModelInfo, error)
    ListPolicies(ctx context.Context) ([]PolicyInfo, error)
    HealthCheck(ctx context.Context, health HealthTarget) error
    ResolveRoute(ctx context.Context, req RouteRequest) (*RouteDecision, error)
    RecordRouteAttempt(ctx context.Context, attempt RouteAttempt) error
    RouteStatus(ctx context.Context) (*RouteStatusReport, error)

    // Historical session-log projections. CONTRACT-003 owns these so CLI
    // subcommands such as log/replay/usage do not need to read the
    // internal session-log JSONL schema.
    UsageReport(ctx context.Context, opts UsageReportOptions) (*UsageReport, error)
    ListSessionLogs(ctx context.Context) ([]SessionLogEntry, error)
    WriteSessionLog(ctx context.Context, sessionID string, w io.Writer) error
    ReplaySession(ctx context.Context, sessionID string, w io.Writer) error
}

type ServiceOptions struct {
    seamOptions

    ConfigPath string    // optional override; default $XDG_CONFIG_HOME/fizeau/config.yaml
    Logger     io.Writer // optional; agent writes structured session logs internally regardless

    // ServiceConfig, when non-nil, supplies provider and routing data for
    // ListProviders and HealthCheck. Pass a value wrapping the loaded config.
    // When nil, those methods return an error.
    ServiceConfig ServiceConfig

    // QuotaRefreshDebounce is the minimum interval between live quota probes for
    // a primary subscription harness. Zero uses the service default.
    QuotaRefreshDebounce time.Duration
    // QuotaRefreshStartupWait bounds startup waiting when the durable quota
    // cache is missing, stale, or incomplete. Zero uses the service default.
    QuotaRefreshStartupWait time.Duration
    // QuotaRefreshInterval enables periodic refresh for long-running server
    // processes. Zero disables the timer; cache refresh still happens on startup
    // and service activity.
    QuotaRefreshInterval time.Duration
    // QuotaRefreshContext optionally cancels the periodic server refresh worker.
    // When nil, the worker uses context.Background().
    QuotaRefreshContext context.Context

    // CatalogProbeTimeout bounds live /v1/models discovery during routing.
    // Zero uses the service default of 2s.
    CatalogProbeTimeout time.Duration
    // CatalogReloadTimeout bounds stale-while-revalidate catalog reloads.
    // Zero uses the service default of 30s.
    CatalogReloadTimeout time.Duration

    // LocalCostUSDPer1kTokens is the operator-supplied electricity/operations
    // estimate for local endpoint providers under the embedded agent harness.
    // Zero means local endpoint cost is unknown.
    LocalCostUSDPer1kTokens float64
    // SubscriptionCostCurve optionally overrides the default subscription
    // effective-cost curve used by routing.
    SubscriptionCostCurve *SubscriptionCostCurve

    // SessionLogDir overrides the directory used by historical session-log
    // projections (UsageReport, ListSessionLogs, WriteSessionLog,
    // ReplaySession). Empty falls back to ServiceConfig.SessionLogDir().
    // Per-Execute requests still set their own
    // ServiceExecuteRequest.SessionLogDir.
    SessionLogDir string

    // HarnessCleanupTimeout bounds stopping and reaping one wrapped harness
    // containment boundary. Zero uses the service default of 10 seconds.
    // Negative values are invalid.
    HarnessCleanupTimeout time.Duration

    // StaleHarnessReaperGrace is the minimum age before a startup reaper may
    // terminate an owned subprocess record. Zero uses the default grace window.
    StaleHarnessReaperGrace time.Duration

    // HealthProbeInterval is the interval between background aliveness probes
    // for configured non-cloud providers. Zero uses the default (60s).
    HealthProbeInterval time.Duration
    // HealthSignalTTL is the maximum age of a probe result before it expires
    // for routing purposes and when loading persisted route-health snapshots.
    // Zero uses the default (10 min).
    HealthSignalTTL time.Duration
    // PersistRouteHealth, when non-empty, is the file path where route-attempt
    // feedback and probe results are persisted across processes. The default is
    // "" so persistence stays opt-in.
    PersistRouteHealth string
    // AlivenessProber, when non-nil, overrides the default TCP-connect prober
    // used during startup and periodic aliveness probing. Nil uses the default.
    AlivenessProber ProviderAlivenessProber
}

type ServiceExecuteRequest struct {
    Prompt            string
    SystemPrompt      string
    Model             string
    Provider          string
    Harness           string
    Policy            string
    WorkDir           string
    Temperature       *float32
    TopP              *float64
    TopK              *int
    MinP              *float64
    RepetitionPenalty *float64
    Seed              *int64
    // SamplingSource is the comma-separated layer attribution produced by
    // internal/sampling.Resolve. Plumbed through to the llm.request
    // telemetry event for ADR-007 override-tracking; never on the wire.
    SamplingSource string
    Reasoning      Reasoning
    NoStream       bool
    Permissions    string
    // Tools overrides the built-in native agent tool set when Harness is
    // "fiz". Nil uses the native built-ins for ToolPreset and WorkDir.
    Tools []Tool
    // ToolPreset is passed through to BuiltinToolsForPreset when Tools is nil.
    // Empty uses the default tool set.
    ToolPreset string

    // PlanningMode, when true, performs one no-tool LLM "planning" call
    // before the main native agent loop and injects the response as an
    // assistant message wrapped in <plan> tags. The benchmark tool preset
    // auto-enables planning; this flag is the per-request opt-in for other
    // callers (e.g. the CLI --plan flag). Only honored when Harness=="fiz"
    // (the native loop). See internal/core.Request.PlanningMode.
    PlanningMode bool

    // EstimatedPromptTokens, when > 0, drives auto-selection's
    // context-window gate (filter out candidates whose context window is
    // too small for the prompt + safety margin).
    EstimatedPromptTokens int
    // RequiresTools, when true, drives auto-selection's tool-support gate
    // (filter out candidates that cannot invoke tools).
    RequiresTools bool
    MinPower      int
    MaxPower      int

    // CachePolicy is the public opt-out for prompt caching. Empty (the zero
    // value) and "default" both request the per-provider default caching
    // behavior; "off" disables caching for this request. Any other value is
    // rejected at the service boundary (see ValidateCachePolicy). Providers
    // that do not implement caching ignore the field; this field is read by
    // the Anthropic cache_control writer (bead C) and the cache-aware cost
    // attribution path (bead D).
    CachePolicy string

    // Three independent timeout knobs:
    //   Timeout         — wall-clock cap on the entire request.
    //   IdleTimeout     — streaming-quiet cap; per-stream gap.
    //   ProviderTimeout — per-HTTP-request cap to the provider.
    Timeout         time.Duration
    IdleTimeout     time.Duration
    ProviderTimeout time.Duration

    // Optional native-loop overrides used when Harness == "fiz". These let
    // the CLI and other callers route fully-resolved execution settings through
    // the service path instead of maintaining a divergent direct loop path.
    MaxIterations           int
    MaxTokens               int
    ReasoningByteLimit      int
    CompactionContextWindow int
    CompactionReserveTokens int

    // CostCapUSD is the per-run cost cap in USD, mirrored to
    // internal/core.Request.CostCapUSD. When > 0, the native loop halts
    // before issuing the next llm.request once running known cost plus the
    // projected next-turn cost would meet or exceed the cap; the resulting
    // final event reports Status="budget_halted". Zero means no cap. Per
    // FEAT-005 §28 / AC-FEAT-005-07, the cap requires turn cost to be known;
    // unknown-cost runs proceed past the cap with a stderr warning. Honored
    // only when Harness=="fiz" (the native loop) — subprocess harnesses
    // manage cost externally.
    CostCapUSD float64

    // Optional stall policy. When non-nil agent enforces and ends with
    // Status="stalled" if any limit hits. Default policy applies when nil.
    StallPolicy *StallPolicy

    // SessionLogDir overrides the default session-log directory for this
    // request (e.g. an execute-bead per-bundle evidence directory).
    SessionLogDir string

    // SelectedRoute is the configured model-route name the caller picked
    // (e.g. "code-pool"). Recorded into the service-owned session log so
    // post-hoc routing analytics can correlate logs to route keys without
    // reconstructing attribution from the event stream.
    SelectedRoute string

    // Metadata is bidirectional: echoed back in every Event AND stamped
    // onto every line of the session log so external consumers correlate.
    Metadata map[string]string

    // Role tags the kind of work this call performs (e.g. "implementer",
    // "reviewer", "decomposer", "summarizer"). Observational: echoed into
    // the routing_decision and final event Metadata, plus the session-log
    // header. Per CONTRACT-003 it is NOT part of the selection precedence
    // chain (Day 1) and does NOT affect routing. Empty means unset.
    //
    // Normalization: lowercased, alphanumeric + hyphen only, max 64 chars;
    // invalid values are rejected pre-dispatch with RoleNormalizationError.
    Role string
    // CorrelationID links calls that share work context (e.g.
    // "bead_123:attempt_4") so reviewer/implementer/retry attempts can be
    // joined in logs and aggregations. Observational: echoed into
    // routing_decision and final event Metadata, plus the session-log
    // header. Per CONTRACT-003 it is NOT part of the selection precedence
    // chain (Day 1) and does NOT affect routing. Empty means unset.
    //
    // Normalization: printable ASCII (no control chars, no whitespace
    // except hyphen, colon, underscore), max 256 chars; invalid values
    // are rejected pre-dispatch with CorrelationIDNormalizationError.
    CorrelationID string
}

type ServiceEvent = harnesses.Event

type ServiceConfig interface {
    // ProviderNames returns provider names in stable order (default first).
    ProviderNames() []string
    // DefaultProviderName returns the name of the configured default provider.
    DefaultProviderName() string
    // Provider returns the raw config values for a named provider.
    Provider(name string) (ServiceProviderEntry, bool)
    // HealthCooldown returns the configured cooldown duration (0 = use default 30s).
    HealthCooldown() time.Duration
    // WorkDir is the base directory for file-backed health state.
    WorkDir() string
    // SessionLogDir returns the configured sessions directory.
    SessionLogDir() string
}

type ModelFilter struct {
    Harness  string
    Provider string
}

type ModelInfo struct {
    ID                            string
    Provider                      string
    ProviderType                  string
    Harness                       string
    EndpointName                  string
    EndpointBaseURL               string
    ServerInstance                string
    ContextLength                 int
    ContextSource                 string
    Utilization                   RouteUtilizationState
    Capabilities                  []string
    Cost                          CostInfo
    PerfSignal                    PerfSignal
    Power                         int
    AutoRoutable                  bool
    ExactPinOnly                  bool
    Billing                       BillingModel
    ActualCashSpend               bool
    EffectiveCost                 float64
    EffectiveCostSource           string
    SupportsTools                 bool
    DeploymentClass               string
    HealthFreshnessAt             time.Time
    HealthFreshnessSource         string
    QuotaFreshnessAt              time.Time
    QuotaFreshnessSource          string
    ModelDiscoveryFreshnessAt     time.Time
    ModelDiscoveryFreshnessSource string
    Available                     bool
    IsDefault                     bool // matches the configured default model
    RankPosition                  int  // ordinal in latest discovery rank; -1 if unranked
}

type ProviderInfo struct {
    Name             string
    Type             string // "openai" | "openrouter" | "lmstudio" | "omlx" | "ollama" | "anthropic" | "virtual"
    BaseURL          string
    Endpoints        []ServiceProviderEndpoint
    Status           string // "connected" | "unreachable" | "error: <msg>"
    ModelCount       int
    Capabilities     []string       // e.g. {"tool_use","streaming","json_mode"}
    Billing          BillingModel   // "fixed" | "per_token" | "subscription" | ""
    IncludeByDefault bool           // participates in unpinned/default routing
    IsDefault        bool           // matches the configured default_provider
    DefaultModel     string         // per-provider configured default model, if any
    CooldownState    *CooldownState // nil if not in cooldown
    Auth             AccountStatus
    EndpointStatus   []EndpointStatus
    Quota            *QuotaState
    UsageWindows     []UsageWindow
    LastError        *StatusError
}

type HarnessInfo struct {
    Name                 string
    Type                 string // "native" | "subprocess"
    Available            bool
    Path                 string
    Error                string
    Billing              BillingModel
    AutoRoutingEligible  bool
    TestOnly             bool
    ExactPinSupport      bool
    DefaultModel         string   // built-in default model when no override is supplied
    SupportedPermissions []string // subset of {"safe","supervised","unrestricted"}
    SupportedReasoning   []string // values such as {"low","medium","high","xhigh","max"}
    CostClass            string   // "local" | "cheap" | "medium" | "expensive"
    Quota                *QuotaState
    Account              *AccountStatus
    UsageWindows         []UsageWindow
    LastError            *StatusError
    CapabilityMatrix     HarnessCapabilityMatrix
}

type RouteRequest struct {
    Policy      string // optional named policy bundle: cheap|default|smart|air-gapped
    Model       string
    Provider    string
    Harness     string
    Reasoning   Reasoning
    Permissions string
    AllowLocal  bool
    Require     []string
    MinPower    int
    MaxPower    int

    // EstimatedPromptTokens, when > 0, filters out candidates whose context
    // window cannot accommodate the prompt (with a safety margin).
    EstimatedPromptTokens int

    // RequiresTools, when true, filters out candidates that do not support
    // tool calling.
    RequiresTools bool

    // CachePolicy mirrors ServiceExecuteRequest.CachePolicy. Routing decisions
    // today do not act on it; it is carried through so callers using
    // ResolveRoute as a public surface can plumb the same opt-out the
    // Execute path honors.
    CachePolicy string

    // Role tags the kind of work this call performs (e.g. "implementer",
    // "reviewer", "decomposer"). Observational only — it does NOT enter the
    // routing precedence chain. Mirrors ServiceExecuteRequest.Role so
    // ResolveRoute previews don't diverge from Execute.
    Role string

    // CorrelationID joins calls that share work context (e.g.
    // "bead_123:attempt_4"). Observational only — it does NOT enter the
    // routing precedence chain. Mirrors ServiceExecuteRequest.CorrelationID.
    CorrelationID string

    // ExcludedRoutes lists (Provider, Model, Endpoint) combinations the caller
    // has determined are currently unavailable. The router skips any candidate
    // matching an entry. Provider is required; Model and Endpoint are optional
    // (empty matches any value for that field).
    //
    // Use this to communicate caller-side health signals across calls without
    // redesigning provider config. The routing engine records excluded
    // candidates with FilterReasonCallerExcluded for observability.
    ExcludedRoutes []ExcludedRoute
}

type RouteDecision struct {
    // RequestedPolicy is the caller-supplied policy, when any.
    RequestedPolicy string
    // SnapshotCapturedAt records when the model snapshot used for scoring
    // was assembled.
    SnapshotCapturedAt time.Time
    // PowerPolicy records the effective policy inputs used for this
    // resolution. It stays separate from the chosen model so operator
    // surfaces can explain policy without re-deriving it.
    PowerPolicy RoutePowerPolicy
    // Harness is the selected harness name.
    Harness string
    // Provider is the selected provider for native agent routes.
    Provider string
    // Endpoint is the selected named endpoint when the provider exposes more
    // than one endpoint.
    Endpoint string
    // ServerInstance is the normalized server identity used for sticky
    // affinity and route evidence.
    ServerInstance string
    // Model is the selected concrete model.
    Model string
    // Reason summarizes why the selected candidate won.
    Reason string
    // Sticky captures whether this decision reused an existing sticky lease
    // or created a new one.
    Sticky RouteStickyState
    // Utilization captures the endpoint sample that informed the selected
    // candidate, when known.
    Utilization RouteUtilizationState
    // Power is the catalog-projected power of the selected Model
    // (per CONTRACT-003 § Catalog Power Projection). 0 means
    // unknown/exact-pin-only/no catalog entry. DDx callers read this
    // to compute next-attempt MinPower without importing catalog code.
    Power int
    // Candidates is the full ranked decision trace, including rejected
    // candidates and their rejection reasons.
    Candidates []RouteCandidate
}

func New(opts ServiceOptions) (FizeauService, error)

func RegisterConfigLoader(fn func(dir string) (ServiceConfig, error))

make docs-embedding