executor

Documentation

Overview

Package executor runs prompts against Hydra Heads. Two strategies: CLI (subprocess) and HTTP (OpenAI-compatible REST).

Index

• func EstimateTokens(s string) int
• func Supports(h provider.Head) bool
• func SupportsHTTP(h provider.Head) bool
• func Unroutable(h provider.Head) string
• type AgyExecutor
  • func (e *AgyExecutor) Execute(ctx context.Context, req Request) (*Response, error)
• type AuthRequiredError
  • func (e *AuthRequiredError) Error() string
• type CLIExecutor
  • func (e *CLIExecutor) Execute(ctx context.Context, req Request) (*Response, error)
• type Executor
  • func For(h provider.Head) Executor
• type HTTPExecutor
  • func (e *HTTPExecutor) Execute(ctx context.Context, req Request) (*Response, error)
• type OllamaExecutor
  • func (e *OllamaExecutor) Execute(ctx context.Context, req Request) (*Response, error)
• type Request
• type Response

Functions

func EstimateTokens

func EstimateTokens(s string) int

EstimateTokens approximates a token count from text length, for the CLI heads that report no usage of their own.

Never returns 0 for text that exists. len(s)/4 truncated a reply of "OK" to zero tokens, so a call that answered was reported as producing nothing and its cost rounded to $0.000 (#696).

func Supports

func Supports(h provider.Head) bool

Supports reports whether Hydra can execute a discovered head today.

func SupportsHTTP

func SupportsHTTP(h provider.Head) bool

SupportsHTTP reports whether Hydra can execute the head over HTTP today.

func Unroutable

func Unroutable(h provider.Head) string

Unroutable explains why a discovered head cannot be dispatched to, or returns "" when it can.

This is the primary check and Supports delegates to it, so a surface that lists heads and a surface that routes to them cannot disagree. They did: `hyctl probe` advertised the PATH-discovered Ollama binary while `hyctl dispatch --local` refused and told the user to go look at `hyctl probe` (#248). Discovery finding a head and Hydra being able to drive it are different questions, and only one function should answer the second.

Types

type AgyExecutor

type AgyExecutor struct{}

AgyExecutor invokes `agy --print` with model selection via the --model flag. Ports all logic from dispatch/agy.sh natively in Go.

func (*AgyExecutor) Execute

func (e *AgyExecutor) Execute(ctx context.Context, req Request) (*Response, error)

type AuthRequiredError

type AuthRequiredError struct {
	ModelFlag string
	Pool      string
	AuthURL   string
}

AuthRequiredError is returned when agy signals that authentication is needed.

func (*AuthRequiredError) Error

func (e *AuthRequiredError) Error() string

type CLIExecutor

type CLIExecutor struct{}

CLIExecutor runs a prompt via a subprocess CLI tool.

func (*CLIExecutor) Execute

func (e *CLIExecutor) Execute(ctx context.Context, req Request) (*Response, error)

type Executor

type Executor interface {
	Execute(ctx context.Context, req Request) (*Response, error)
}

Executor runs a prompt and returns a response.

func For

func For(h provider.Head) Executor

For selects the correct Executor for a given Head.

• registry source (agy tiers): AgyExecutor → native (execs the `agy` binary)
• ollama source: OllamaExecutor → native /api/generate
• env source / port source / explicit endpoint: HTTPExecutor → per-provider REST
• everything else: CLIExecutor → subprocess

env-key heads (Source=="env") carry no Executable, they are API providers (anthropic, openai, groq, …). HTTPExecutor.Execute dispatches on Head.Provider and already has an adapter for each, so env heads route to HTTP, not CLI.

type HTTPExecutor

type HTTPExecutor struct {
	// contains filtered or unexported fields
}

HTTPExecutor runs prompts against HTTP-based providers.

func (*HTTPExecutor) Execute

func (e *HTTPExecutor) Execute(ctx context.Context, req Request) (*Response, error)

type OllamaExecutor

type OllamaExecutor struct {
	// contains filtered or unexported fields
}

OllamaExecutor calls the Ollama native /api/generate endpoint. Before dispatching it health-checks the server and attempts auto-start. Ports dispatch/ollama.sh natively in Go.

func (*OllamaExecutor) Execute

func (e *OllamaExecutor) Execute(ctx context.Context, req Request) (*Response, error)

type Request

type Request struct {
	Prompt    string
	Head      provider.Head
	MaxTokens int    // 0 = provider default
	System    string // optional system prompt
}

Request is everything needed to execute a prompt against a Head.

type Response

type Response struct {
	Output       string
	InputTokens  int
	OutputTokens int
	Duration     time.Duration
	Model        string
	Truncated    bool // true when output exceeded the accumulator cap

	// TokensEstimated is true when InputTokens/OutputTokens were derived by
	// Hydra (e.g. agy's char/4 heuristic) rather than reported by the provider.
	// HTTP and Ollama executors parse real usage and leave this false; the agy
	// executor sets it true. Consumers must not present estimated tokens as
	// measured spend.
	TokensEstimated bool
}

Response is the result of a successful execution.