pithsdk

type AfterToolContext struct {
	// RunID is the unique identifier for the current run.
	RunID string
	// SessionID is the unique identifier for the current session.
	SessionID string
	// AgentName is the name of the agent running this tool.
	AgentName string
	// ToolName is the name of the tool that was called.
	ToolName string
	// CallID is the provider-assigned tool call identifier.
	CallID string
	// Args is the parsed tool arguments.
	Args map[string]any
	// Result is the text output from the tool.
	Result string
	// Error is non-nil when the tool returned an error.
	Error error
}

type AfterToolResult struct {
	// OverrideResult replaces the tool's output text when non-empty.
	OverrideResult string
}

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

type AgentConfig struct {
	// Name is an optional display name for the agent.
	Name string
	// Instructions is the system prompt sent to the model.
	Instructions string
	// Model is a bare ID (e.g. "gpt-4o-mini") or provider/model (e.g. "anthropic/claude-...").
	Model string
	// Tools are custom tools available during runs.
	Tools []Tool
	// Settings overrides client-level generation defaults for this agent.
	Settings *ModelSettings
}

type BeforeToolContext struct {
	// RunID is the unique identifier for the current run.
	RunID string
	// SessionID is the unique identifier for the current session.
	SessionID string
	// AgentName is the name of the agent running this tool.
	AgentName string
	// ToolName is the name of the tool being called.
	ToolName string
	// CallID is the provider-assigned tool call identifier.
	CallID string
	// Args is the parsed tool arguments.
	Args map[string]any
}

type BeforeToolResult struct {
	// Block prevents the tool from executing when true.
	Block bool
	// Reason is the message returned when blocking a tool call.
	Reason string
}

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

type ClientConfig struct {
	// APIKey is the OpenAI-compatible API key. When empty, OPENAI_API_KEY is used at run time.
	APIKey string
	// DefaultProvider is the provider ID for bare model strings (default "openai").
	DefaultProvider string
	// DefaultModel is used when an Agent has no Model set (default "gpt-4o-mini").
	DefaultModel string
	// DefaultSettings applies generation defaults to all agents unless overridden.
	DefaultSettings *ModelSettings
}

type Hooks struct {
	// BeforeToolCall is called before each tool execution.
	// Return a result with Block=true to prevent execution.
	BeforeToolCall func(ctx BeforeToolContext) (*BeforeToolResult, error)

	// AfterToolCall is called after each tool execution.
	// Use OverrideResult to replace the tool's output.
	AfterToolCall func(ctx AfterToolContext) (*AfterToolResult, error)

	// ShouldStopAfterTurn is called after each agent turn.
	// Return true to stop the run after this turn.
	ShouldStopAfterTurn func(ctx TurnContext) bool
}

type MessageSummary struct {
	// Role is the message role (e.g. "user", "assistant", "toolResult").
	Role string
	// Text is the message text content.
	Text string
}

type ModelPreset struct {
	// ID is the model identifier used in provider/model strings.
	ID string
	// Name is an optional display name; defaults to ID.
	Name string
	// BaseURL is an optional API base URL; the provider may use its own default.
	BaseURL string
	// ContextWindow is the model context size; zero uses the SDK default.
	ContextWindow int
	// MaxTokens is the default max output tokens; zero uses the SDK default.
	MaxTokens int
}

type ModelSettings struct {
	// Temperature controls randomness. Nil leaves the provider default.
	Temperature *float64
	// MaxTokens caps output tokens. Nil leaves the provider default.
	MaxTokens *int
}

type ProviderRegistration struct {
	// Provider implements gateway.ProviderPort for the custom API.
	Provider gateway.ProviderPort

	// Credentials — set exactly one of the following:
	// APIKey is a static API key string.
	APIKey string
	// APIKeyEnv names an environment variable holding the API key (e.g. "ANTHROPIC_API_KEY").
	APIKeyEnv string
	// Credential is a custom resolver returning the API key for the provider ID.
	Credential func(providerID string) (string, error)

	// Models lists model presets to register in the gateway catalog.
	Models []ModelPreset
}

type RunOption func(*RunOptions)

type RunOptions struct {
	// RunID overrides the auto-generated run identifier. Empty triggers auto-generation.
	RunID string
	// Context holds run-scoped local dependencies exposed as ToolContext.Local.
	Context any
	// Instructions overrides the agent system prompt for this run only.
	Instructions string
	// Stream receives assistant text deltas during the run; nil blocks until complete.
	Stream func(chunk TextChunk)
	// MaxTurns limits tool-calling loop iterations for this run. Zero uses defaultMaxTurns (10).
	MaxTurns int
	// Hooks are lifecycle callbacks for this run.
	Hooks *Hooks
}

type RunResult struct {
	// RunID is the unique identifier for this run, auto-generated unless overridden via WithRunID.
	RunID string
	// Text is the final assistant response text.
	Text string
	// Messages is the session transcript after this run, as simplified summaries.
	Messages []MessageSummary
	// Usage reports token usage from the last assistant response, if available.
	Usage *UsageSummary
}

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

type SessionOption func(*sessionOpts)

type TextChunk struct {
	// Delta is the incremental text from the latest EventTextDelta.
	Delta string
	// Text is the accumulated assistant text so far.
	Text string
}

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

type ToolContext struct {
	// Run is the context for the current Session.Run call.
	Run context.Context
	// RunID is the unique identifier for the current run.
	RunID string
	// SessionID is the unique identifier for the current session.
	SessionID string
	// Local holds run-scoped dependencies from WithContext; not sent to the model.
	Local any
	// ToolName is the name of the tool being invoked.
	ToolName string
	// CallID is the provider-assigned tool call identifier.
	CallID string
}

type TurnContext struct {
	// RunID is the unique identifier for the current run.
	RunID string
	// SessionID is the unique identifier for the current session.
	SessionID string
	// AgentName is the name of the running agent.
	AgentName string
	// TurnNumber is the 1-based turn count within the current run.
	TurnNumber int
}

type UsageSummary struct {
	// Input is the number of input/prompt tokens.
	Input int
	// Output is the number of output/completion tokens.
	Output int
	// Total is the combined token count when reported by the provider.
	Total int
}