Help us shape the future of Go! Take the 2026 Go Developer Survey

nexssflow

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package nexssflow exposes reusable AI actions to Flow v0.65.0 and newer.

Index

Constants

View Source 
const ID = "ai"

Variables

This section is empty.

Functions

func Bundle 

func Bundle(raw map[string]string) compiler.Bundle

Bundle exposes AI actions as a Flow v0.65.0 library using canonical names.

Types

type CandidateAttemptPlan added in v0.2.0 

type CandidateAttemptPlan struct {
	CandidateID        string              `json:"candidate_id"`
	AttemptID          string              `json:"attempt_id"`
	Provider           string              `json:"provider"`
	Model              string              `json:"model"`
	BaseURL            string              `json:"base_url,omitempty"`
	RateCardID         string              `json:"rate_card_id"`
	ExpectedCurrency   cost.Currency       `json:"expected_currency"`
	PromptTokens       int                 `json:"prompt_tokens"`
	CachedPromptTokens int                 `json:"cached_prompt_tokens,omitempty"`
	CompletionTokens   int                 `json:"completion_tokens"`
	User               string              `json:"user"`
	System             string              `json:"system,omitempty"`
	MaxTokens          int                 `json:"max_tokens,omitempty"`
	Temperature        float64             `json:"temperature,omitempty"`
	JSONMode           bool                `json:"json_mode,omitempty"`
	ReasoningEffort    llm.ReasoningEffort `json:"reasoning_effort,omitempty"`
}

CandidateAttemptPlan is operator-supplied configuration for one candidate provider attempt. No provider, model, price, card, currency, or ID is inferred.

type CostEstimateRequest added in v0.2.0 

type CostEstimateRequest struct {
	CandidateID        string                 `json:"candidate_id,omitempty"`
	AttemptID          string                 `json:"attempt_id"`
	Model              string                 `json:"model"`
	RateCardID         string                 `json:"rate_card_id"`
	ExpectedCurrency   cost.Currency          `json:"expected_currency"`
	PromptTokens       int                    `json:"prompt_tokens"`
	CachedPromptTokens int                    `json:"cached_prompt_tokens,omitempty"`
	CompletionTokens   int                    `json:"completion_tokens"`
	Decision           *DecisionActionRequest `json:"decision,omitempty"`
	Prompt             *PromptRequest         `json:"prompt,omitempty"`
}

CostEstimateRequest estimates one attempt against an explicit external rate card. For a nested Decision, CompletionTokens must equal its positive MaxOutputTokens so the estimate uses the enforced worst-case output cap. The action computes no budget decision or reservation and never triggers fallback.

type CostEstimateResult added in v0.2.0 

type CostEstimateResult struct {
	CandidateID        string                 `json:"candidate_id,omitempty"`
	AttemptID          string                 `json:"attempt_id"`
	Model              string                 `json:"model"`
	RateCardID         string                 `json:"rate_card_id"`
	ExpectedCurrency   cost.Currency          `json:"expected_currency"`
	PromptTokens       int                    `json:"prompt_tokens"`
	CachedPromptTokens int                    `json:"cached_prompt_tokens"`
	CompletionTokens   int                    `json:"completion_tokens"`
	Known              bool                   `json:"known"`
	Issue              string                 `json:"issue,omitempty"`
	CostMicros         cost.Micro             `json:"cost_micros"`
	Currency           *cost.Currency         `json:"currency,omitempty"`
	Decision           *DecisionActionRequest `json:"decision,omitempty"`
	Prompt             *PromptRequest         `json:"prompt,omitempty"`
}

CostEstimateResult reports the exact card calculation, or an explicit unknown estimate when the selected card is absent or currency mismatches.

type DecisionActionRequest added in v0.2.0 

type DecisionActionRequest struct {
	AttemptID          string                 `json:"attempt_id"`
	Provider           string                 `json:"provider,omitempty"`
	Model              string                 `json:"model,omitempty"`
	BaseURL            string                 `json:"base_url,omitempty"`
	RateCardID         string                 `json:"rate_card_id,omitempty"`
	ExpectedCurrency   *cost.Currency         `json:"expected_currency,omitempty"`
	PromptTokens       int                    `json:"prompt_tokens,omitempty"`
	CachedPromptTokens int                    `json:"cached_prompt_tokens,omitempty"`
	CompletionTokens   int                    `json:"completion_tokens,omitempty"`
	MaxOutputTokens    int                    `json:"max_output_tokens"`
	State              json.RawMessage        `json:"state"`
	Questions          []llm.DecisionQuestion `json:"questions"`
	AllowedIDs         []string               `json:"allowed_ids,omitempty"`
	Candidates         []DecisionCandidate    `json:"candidates,omitempty"`
}

DecisionActionRequest is the strongly typed input to ai.decide. The decision call has its own AttemptID and requires a positive MaxOutputTokens cap; candidate attempts remain separately identified.

type DecisionActionResult added in v0.2.0 

type DecisionActionResult struct {
	AttemptID          string               `json:"attempt_id"`
	Model              string               `json:"model"`
	RateCardID         string               `json:"rate_card_id,omitempty"`
	ExpectedCurrency   *cost.Currency       `json:"expected_currency,omitempty"`
	PromptTokens       int                  `json:"prompt_tokens,omitempty"`
	CachedPromptTokens int                  `json:"cached_prompt_tokens,omitempty"`
	CompletionTokens   int                  `json:"completion_tokens,omitempty"`
	MaxOutputTokens    int                  `json:"max_output_tokens"`
	Answers            []llm.DecisionAnswer `json:"answers"`
	Usage              llm.Usage            `json:"usage"`
	Candidates         []DecisionCandidate  `json:"candidates,omitempty"`
}

DecisionActionResult keeps provider answers typed and echoes the decision AttemptID and operator-supplied candidate attempt plans for NFlow routing.

type DecisionCandidate added in v0.2.0 

type DecisionCandidate struct {
	ID          string               `json:"id"`
	Description string               `json:"description"`
	Attempt     CandidateAttemptPlan `json:"attempt"`
}

DecisionCandidate is one allowlisted choice and its corresponding provider attempt plan. ID is the choice ID; CandidateID is reserved for the actual prompt/cost-estimate attempt held in Attempt.

type DecisionDecl added in v0.2.0 

type DecisionDecl struct {
	Provider string
	Model    string
	BaseURL  string
}

DecisionDecl selects the separately configured decision-capable provider.

type GlobalOptions 

type GlobalOptions struct {
	APIKeyEnv         string
	Timeout           time.Duration
	DefaultModel      string
	Provider          string
	BaseURL           string
	DecisionAPIKeyEnv string
	DecisionModel     string
	DecisionProvider  string
	DecisionBaseURL   string
}

GlobalOptions are supplied by Flow's @require options block.

type LLMDecl 

type LLMDecl struct {
	Provider string
	Model    string
	BaseURL  string
}

LLMDecl contains the per-call values accepted by ai.prompt.

type PromptRequest added in v0.2.0 

type PromptRequest struct {
	CandidateID      string         `json:"candidate_id,omitempty"`
	AttemptID        string         `json:"attempt_id,omitempty"`
	RateCardID       string         `json:"rate_card_id,omitempty"`
	ExpectedCurrency *cost.Currency `json:"expected_currency,omitempty"`
	// PromptTokens, CachedPromptTokens, and CompletionTokens are the caller's
	// preflight basis, not provider-reported usage. The result Usage carries actuals.
	PromptTokens       int                   `json:"prompt_tokens,omitempty"`
	CachedPromptTokens int                   `json:"cached_prompt_tokens,omitempty"`
	CompletionTokens   int                   `json:"completion_tokens,omitempty"`
	Context            json.RawMessage       `json:"context,omitempty"`
	User               string                `json:"user"`
	System             string                `json:"system,omitempty"`
	Provider           string                `json:"provider,omitempty"`
	Model              string                `json:"model,omitempty"`
	BaseURL            string                `json:"base_url,omitempty"`
	MaxTokens          int                   `json:"max_tokens,omitempty"`
	Temperature        float64               `json:"temperature,omitempty"`
	JSONMode           bool                  `json:"json_mode,omitempty"`
	ReasoningEffort    llm.ReasoningEffort   `json:"reasoning_effort,omitempty"`
	Fallback           *CandidateAttemptPlan `json:"fallback,omitempty"`
}

PromptRequest is the strongly typed input to ai.prompt. CandidateID and AttemptID identify one provider attempt. Fallback is inert metadata for the enclosing NFlow error handler; ai.prompt never retries it itself.

type PromptResult added in v0.2.0 

type PromptResult struct {
	CandidateID        string          `json:"candidate_id,omitempty"`
	AttemptID          string          `json:"attempt_id,omitempty"`
	RateCardID         string          `json:"rate_card_id,omitempty"`
	ExpectedCurrency   *cost.Currency  `json:"expected_currency,omitempty"`
	Context            json.RawMessage `json:"context,omitempty"`
	Provider           string          `json:"provider"`
	Content            string          `json:"content"`
	Model              string          `json:"model"`
	PromptTokens       int             `json:"prompt_tokens"`
	CachedPromptTokens int             `json:"cached_prompt_tokens,omitempty"`
	CompTokens         int             `json:"comp_tokens"`
	TotalTokens        int             `json:"total_tokens"`
	Usage              llm.Usage       `json:"usage"`
}

PromptResult is one provider attempt. It intentionally does not merge the entire incoming Flow state into the output; callers retain only declared, inspectable fields and can use IDs to account attempts independently.

type RoleAgent 

type RoleAgent struct {
	Name            string              `json:"name"`
	Role            string              `json:"role"`
	Instructions    string              `json:"instructions"`
	CandidateID     string              `json:"candidate_id,omitempty"`
	AttemptID       string              `json:"attempt_id,omitempty"`
	Provider        string              `json:"provider,omitempty"`
	Model           string              `json:"model,omitempty"`
	BaseURL         string              `json:"base_url,omitempty"`
	ReasoningEffort llm.ReasoningEffort `json:"reasoning_effort,omitempty"`
}

RoleAgent is one role declared for a single ai.team invocation. It is not a durable actor: its only turn is run in order, then its output is added to the in-run conversation for later roles.

type RoleTurn 

type RoleTurn struct {
	Name         string    `json:"name"`
	Role         string    `json:"role"`
	CandidateID  string    `json:"candidate_id,omitempty"`
	AttemptID    string    `json:"attempt_id,omitempty"`
	Provider     string    `json:"provider"`
	Content      string    `json:"content"`
	Model        string    `json:"model"`
	PromptTokens int       `json:"prompt_tokens"`
	CompTokens   int       `json:"completion_tokens"`
	Usage        llm.Usage `json:"usage"`
}

RoleTurn is one independent completion produced by a role agent.

type TeamRequest added in v0.2.0 

type TeamRequest struct {
	Goal            string              `json:"goal"`
	Agents          []RoleAgent         `json:"agents"`
	CandidateID     string              `json:"candidate_id,omitempty"`
	AttemptID       string              `json:"attempt_id,omitempty"`
	Provider        string              `json:"provider,omitempty"`
	Model           string              `json:"model,omitempty"`
	BaseURL         string              `json:"base_url,omitempty"`
	MaxTokens       int                 `json:"max_tokens,omitempty"`
	Temperature     float64             `json:"temperature,omitempty"`
	ReasoningEffort llm.ReasoningEffort `json:"reasoning_effort,omitempty"`
}

TeamRequest is the typed input to ai.team.

type TeamResult added in v0.2.0 

type TeamResult struct {
	Goal         string        `json:"goal"`
	Agents       []RoleTurn    `json:"agents"`
	Conversation []llm.Message `json:"conversation"`
	Content      string        `json:"content"`
	Provider     string        `json:"provider"`
	Model        string        `json:"model"`
	PromptTokens int           `json:"prompt_tokens"`
	CompTokens   int           `json:"comp_tokens"`
	TotalTokens  int           `json:"total_tokens"`
}

TeamResult contains each independently accounted role turn and the final in-run transcript. Cost is not summed across currencies/models; inspect each turn's Usage for its configured rate-card currency.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.