operations

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Jun 28, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package operations provides Huma-compatible request/response types and operation registrations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterAgentOperations

func RegisterAgentOperations(api huma.API, manager AgentManager)

RegisterAgentOperations registers agent management API operations.

func RegisterCronOperations

func RegisterCronOperations(api huma.API, handler Handler)

RegisterCronOperations registers cron job API operations.

func RegisterHealthOperation

func RegisterHealthOperation(api huma.API)

RegisterHealthOperation registers the health check endpoint.

func RegisterMemoryOperations

func RegisterMemoryOperations(api huma.API, handler MemoryHandler)

RegisterMemoryOperations registers memory API operations.

func RegisterToolOperations

func RegisterToolOperations(api huma.API, handler Handler)

RegisterToolOperations registers tool-related API operations.

func RegisterUsageOperations

func RegisterUsageOperations(api huma.API, store UsageStore)

RegisterUsageOperations registers usage analytics API operations.

Types

type AgentInfo

type AgentInfo struct {
	ID           string    `json:"id" doc:"Agent unique identifier"`
	Name         string    `json:"name" doc:"Agent display name"`
	Description  string    `json:"description,omitempty" doc:"Agent description"`
	Provider     string    `json:"provider" doc:"LLM provider (anthropic, openai, etc.)"`
	Model        string    `json:"model" doc:"Model identifier"`
	Temperature  float64   `json:"temperature,omitempty" doc:"Sampling temperature (0.0-2.0)"`
	MaxTokens    int       `json:"max_tokens,omitempty" doc:"Maximum tokens to generate"`
	SystemPrompt string    `json:"system_prompt,omitempty" doc:"System prompt for the agent"`
	AllowedTools []string  `json:"allowed_tools,omitempty" doc:"List of allowed tool names"`
	DeniedTools  []string  `json:"denied_tools,omitempty" doc:"List of denied tool names"`
	Enabled      bool      `json:"enabled" doc:"Whether agent is enabled"`
	CreatedAt    time.Time `json:"created_at" doc:"Creation timestamp"`
	UpdatedAt    time.Time `json:"updated_at" doc:"Last update timestamp"`
}

AgentInfo represents information about a configured agent.

type AgentManager

type AgentManager interface {
	ListAgents(ctx context.Context) ([]AgentInfo, error)
	GetAgent(ctx context.Context, id string) (*AgentInfo, error)
	CreateAgent(ctx context.Context, req *CreateAgentRequest) (*AgentInfo, error)
	UpdateAgent(ctx context.Context, id string, req *UpdateAgentRequest) (*AgentInfo, error)
	DeleteAgent(ctx context.Context, id string) error
	CloneAgent(ctx context.Context, id string, req *CloneAgentRequest) (*AgentInfo, error)
}

AgentManager defines agent management operations.

type AgentOutput

type AgentOutput struct {
	Body AgentInfo
}

AgentOutput is the response containing a single agent.

type AgentUsage

type AgentUsage struct {
	AgentID          string  `json:"agent_id" doc:"Agent identifier"`
	Requests         int64   `json:"requests" doc:"Number of requests"`
	PromptTokens     int64   `json:"prompt_tokens" doc:"Input tokens"`
	CompletionTokens int64   `json:"completion_tokens" doc:"Output tokens"`
	TotalTokens      int64   `json:"total_tokens" doc:"Total tokens"`
	Cost             float64 `json:"cost" doc:"Estimated cost in USD"`
}

AgentUsage tracks usage per agent.

type ChartOutput

type ChartOutput struct {
	Body chartir.ChartIR
}

ChartOutput is the response for chart data.

type CloneAgentInput

type CloneAgentInput struct {
	ID   string `path:"id" doc:"Source agent ID"`
	Body CloneAgentRequest
}

CloneAgentInput is the request for cloning an agent.

type CloneAgentRequest

type CloneAgentRequest struct {
	NewID   string `json:"new_id,omitempty" doc:"New agent ID (auto-generated if empty)"`
	NewName string `json:"new_name" doc:"New agent name" required:"true"`
}

CloneAgentRequest represents a request to clone an agent.

type CreateAgentInput

type CreateAgentInput struct {
	Body CreateAgentRequest
}

CreateAgentInput is the request for creating an agent.

type CreateAgentRequest

type CreateAgentRequest struct {
	ID           string   `json:"id,omitempty" doc:"Agent ID (auto-generated if empty)"`
	Name         string   `json:"name" doc:"Agent display name" required:"true"`
	Description  string   `json:"description,omitempty" doc:"Agent description"`
	Provider     string   `json:"provider,omitempty" doc:"LLM provider"`
	Model        string   `json:"model,omitempty" doc:"Model identifier"`
	APIKey       string   `json:"api_key,omitempty" doc:"API key for the provider"` //nolint:gosec // G101: API key in request
	BaseURL      string   `json:"base_url,omitempty" doc:"Base URL for the provider"`
	Temperature  float64  `json:"temperature,omitempty" doc:"Sampling temperature"`
	MaxTokens    int      `json:"max_tokens,omitempty" doc:"Maximum tokens to generate"`
	SystemPrompt string   `json:"system_prompt,omitempty" doc:"System prompt"`
	AllowedTools []string `json:"allowed_tools,omitempty" doc:"Allowed tool names"`
	DeniedTools  []string `json:"denied_tools,omitempty" doc:"Denied tool names"`
}

CreateAgentRequest represents a request to create an agent.

type CreateCronJobInput

type CreateCronJobInput struct {
	Body CreateCronJobRequest
}

CreateCronJobInput is the request for creating a cron job.

type CreateCronJobRequest

type CreateCronJobRequest struct {
	Name        string           `json:"name" doc:"Job name" required:"true"`
	Description string           `json:"description,omitempty" doc:"Job description"`
	Schedule    CronScheduleInfo `json:"schedule" doc:"Job schedule configuration" required:"true"`
	Action      CronActionInfo   `json:"action" doc:"Job action configuration" required:"true"`
}

CreateCronJobRequest represents a request to create a scheduled job.

type CronActionInfo

type CronActionInfo struct {
	Type           string            `json:"type" doc:"Action type (send_message, call_webhook, call_tool)"`
	SessionID      string            `json:"session_id,omitempty" doc:"Session ID for send_message"`
	Message        string            `json:"message,omitempty" doc:"Message content for send_message"`
	WebhookURL     string            `json:"webhook_url,omitempty" doc:"Webhook URL for call_webhook"`
	WebhookMethod  string            `json:"webhook_method,omitempty" doc:"HTTP method for webhook (GET, POST, etc.)"`
	WebhookHeaders map[string]string `json:"webhook_headers,omitempty" doc:"HTTP headers for webhook"`
	WebhookBody    string            `json:"webhook_body,omitempty" doc:"Request body for webhook"`
	ToolName       string            `json:"tool_name,omitempty" doc:"Tool name for call_tool"`
	ToolParams     map[string]any    `json:"tool_params,omitempty" doc:"Tool parameters for call_tool"`
}

CronActionInfo represents job action information.

type CronJobInfo

type CronJobInfo struct {
	ID          string           `json:"id" doc:"Job unique identifier"`
	Name        string           `json:"name" doc:"Job name"`
	Description string           `json:"description,omitempty" doc:"Job description"`
	Schedule    CronScheduleInfo `json:"schedule" doc:"Job schedule configuration"`
	Action      CronActionInfo   `json:"action" doc:"Job action configuration"`
	Status      string           `json:"status" doc:"Job status (active, disabled)"`
	CreatedAt   time.Time        `json:"created_at" doc:"Creation timestamp"`
	UpdatedAt   time.Time        `json:"updated_at" doc:"Last update timestamp"`
	LastRunAt   *time.Time       `json:"last_run_at,omitempty" doc:"Last run timestamp"`
	NextRunAt   *time.Time       `json:"next_run_at,omitempty" doc:"Next scheduled run timestamp"`
	RunCount    int64            `json:"run_count" doc:"Total number of runs"`
	LastError   string           `json:"last_error,omitempty" doc:"Last error message if any"`
}

CronJobInfo represents information about a scheduled job.

type CronJobOutput

type CronJobOutput struct {
	Body CronJobInfo
}

CronJobOutput is the response containing a single cron job.

type CronJobResult

type CronJobResult struct {
	Success   bool   `json:"success" doc:"Whether the job succeeded"`
	Output    any    `json:"output,omitempty" doc:"Job output"`
	Error     string `json:"error,omitempty" doc:"Error message if failed"`
	Duration  string `json:"duration" doc:"Execution duration"`
	StartedAt string `json:"started_at" doc:"Start timestamp (RFC3339)"`
}

CronJobResult represents the result of triggering a job.

type CronScheduleInfo

type CronScheduleInfo struct {
	Cron     string `json:"cron,omitempty" doc:"Cron expression (e.g., '0 * * * *')"`
	Once     string `json:"once,omitempty" doc:"One-time schedule (RFC3339 timestamp)"`
	Interval string `json:"interval,omitempty" doc:"Interval duration (e.g., '1h', '30m')"`
}

CronScheduleInfo represents job schedule information.

type DeleteAgentInput

type DeleteAgentInput struct {
	ID string `path:"id" doc:"Agent ID"`
}

DeleteAgentInput is the request for deleting an agent.

type DeleteCronJobInput

type DeleteCronJobInput struct {
	ID string `path:"id" doc:"Cron job ID"`
}

DeleteCronJobInput is the request for deleting a cron job.

type DeleteMemoryInput

type DeleteMemoryInput struct {
	Key        string `path:"key" doc:"Memory key"`
	Collection string `query:"collection" default:"default" doc:"Collection name"`
}

DeleteMemoryInput is the request for deleting a memory.

type EnableDisableCronJobInput

type EnableDisableCronJobInput struct {
	ID string `path:"id" doc:"Cron job ID"`
}

EnableDisableCronJobInput is the request for enabling/disabling a cron job.

type EnableDisableCronJobOutput

type EnableDisableCronJobOutput struct {
	Body struct {
		ID     string `json:"id" doc:"Cron job ID"`
		Status string `json:"status" doc:"New status (enabled, disabled)"`
	}
}

EnableDisableCronJobOutput is the response for enabling/disabling a cron job.

type GetAgentInput

type GetAgentInput struct {
	ID string `path:"id" doc:"Agent ID"`
}

GetAgentInput is the request for getting an agent.

type GetCronJobInput

type GetCronJobInput struct {
	ID string `path:"id" doc:"Cron job ID"`
}

GetCronJobInput is the request for getting a cron job.

type Handler

type Handler interface {
	// Tools
	ListTools(ctx context.Context) ([]ToolInfo, error)

	// Cron jobs
	ListCronJobs(ctx context.Context) ([]CronJobInfo, error)
	GetCronJob(ctx context.Context, id string) (*CronJobInfo, error)
	CreateCronJob(ctx context.Context, req *CreateCronJobRequest) (*CronJobInfo, error)
	UpdateCronJob(ctx context.Context, id string, req *UpdateCronJobRequest) (*CronJobInfo, error)
	DeleteCronJob(ctx context.Context, id string) error
	TriggerCronJob(ctx context.Context, id string) (*CronJobResult, error)
	EnableCronJob(ctx context.Context, id string) error
	DisableCronJob(ctx context.Context, id string) error
}

Handler defines the interface for backend operations. This combines AgentHandler, AgentManager, and MemoryHandler from the parent package.

type HealthOutput

type HealthOutput struct {
	Body struct {
		Status string `json:"status" example:"ok" doc:"Health status"`
	}
}

HealthOutput is the response for health check.

type ListAgentsOutput

type ListAgentsOutput struct {
	Body struct {
		Object string      `json:"object" example:"list" doc:"Object type"`
		Data   []AgentInfo `json:"data" doc:"List of agents"`
	}
}

ListAgentsOutput is the response for listing agents.

type ListCollectionsOutput

type ListCollectionsOutput struct {
	Body struct {
		Object string             `json:"object" example:"list" doc:"Object type"`
		Data   []MemoryCollection `json:"data" doc:"List of collections"`
	}
}

ListCollectionsOutput is the response for listing collections.

type ListCronJobsOutput

type ListCronJobsOutput struct {
	Body struct {
		Object string        `json:"object" example:"list" doc:"Object type"`
		Data   []CronJobInfo `json:"data" doc:"List of cron jobs"`
	}
}

ListCronJobsOutput is the response for listing cron jobs.

type ListMemoriesInput

type ListMemoriesInput struct {
	Collection string `query:"collection" default:"default" doc:"Collection name"`
	Limit      int    `query:"limit" default:"50" doc:"Maximum number of memories to return"`
}

ListMemoriesInput is the request for listing memories.

type ListMemoriesOutput

type ListMemoriesOutput struct {
	Body struct {
		Object     string         `json:"object" example:"list" doc:"Object type"`
		Collection string         `json:"collection" doc:"Collection name"`
		Data       []MemoryRecord `json:"data" doc:"List of memories"`
	}
}

ListMemoriesOutput is the response for listing memories.

type ListToolsOutput

type ListToolsOutput struct {
	Body struct {
		Object string     `json:"object" example:"list" doc:"Object type"`
		Data   []ToolInfo `json:"data" doc:"List of tools"`
	}
}

ListToolsOutput is the response for listing tools.

type MemoryCollection

type MemoryCollection struct {
	Name        string `json:"name" doc:"Collection name"`
	Description string `json:"description,omitempty" doc:"Collection description"`
	Count       int    `json:"count" doc:"Number of memories in collection"`
}

MemoryCollection represents a memory collection.

type MemoryHandler

type MemoryHandler interface {
	ListMemories(ctx context.Context, collection string, limit int) ([]MemoryRecord, error)
	SearchMemories(ctx context.Context, collection, query string, limit int) ([]MemorySearchResult, error)
	StoreMemory(ctx context.Context, req *StoreMemoryRequest) (*MemoryRecord, error)
	DeleteMemory(ctx context.Context, collection, key string) error
	ListCollections(ctx context.Context) ([]MemoryCollection, error)
}

MemoryHandler defines memory operations.

type MemoryOutput

type MemoryOutput struct {
	Body MemoryRecord
}

MemoryOutput is the response for a single memory.

type MemoryRecord

type MemoryRecord struct {
	Key        string            `json:"key" doc:"Memory unique key"`
	Content    string            `json:"content" doc:"Memory content"`
	Collection string            `json:"collection" doc:"Collection name"`
	Metadata   map[string]string `json:"metadata,omitempty" doc:"Custom metadata"`
	CreatedAt  time.Time         `json:"created_at" doc:"Creation timestamp"`
}

MemoryRecord represents a stored memory.

type MemorySearchResult

type MemorySearchResult struct {
	MemoryRecord
	Score float64 `json:"score" doc:"Relevance score (0.0-1.0)"`
}

MemorySearchResult represents a memory search result with score.

type ModelUsage

type ModelUsage struct {
	Model            string  `json:"model" doc:"Model identifier"`
	Requests         int64   `json:"requests" doc:"Number of requests"`
	PromptTokens     int64   `json:"prompt_tokens" doc:"Input tokens"`
	CompletionTokens int64   `json:"completion_tokens" doc:"Output tokens"`
	TotalTokens      int64   `json:"total_tokens" doc:"Total tokens"`
	Cost             float64 `json:"cost" doc:"Estimated cost in USD"`
}

ModelUsage tracks usage per model.

type ReloadAgentInput

type ReloadAgentInput struct {
	ID string `path:"id" doc:"Agent ID"`
}

ReloadAgentInput is the request for reloading an agent.

type ReloadAgentOutput

type ReloadAgentOutput struct {
	Body struct {
		ID     string    `json:"id" doc:"Agent ID"`
		Status string    `json:"status" example:"reloaded" doc:"Reload status"`
		Agent  AgentInfo `json:"agent" doc:"Reloaded agent info"`
	}
}

ReloadAgentOutput is the response for reloading an agent.

type SearchMemoriesInput

type SearchMemoriesInput struct {
	Query      string `query:"q" required:"true" doc:"Search query"`
	Collection string `query:"collection" default:"default" doc:"Collection name"`
	Limit      int    `query:"limit" default:"10" doc:"Maximum number of results"`
}

SearchMemoriesInput is the request for searching memories.

type SearchMemoriesOutput

type SearchMemoriesOutput struct {
	Body struct {
		Object     string               `json:"object" example:"list" doc:"Object type"`
		Collection string               `json:"collection" doc:"Collection name"`
		Query      string               `json:"query" doc:"Search query"`
		Data       []MemorySearchResult `json:"data" doc:"Search results"`
	}
}

SearchMemoriesOutput is the response for searching memories.

type StoreMemoryInput

type StoreMemoryInput struct {
	Body StoreMemoryRequest
}

StoreMemoryInput is the request for storing a memory.

type StoreMemoryRequest

type StoreMemoryRequest struct {
	Content    string            `json:"content" doc:"Memory content" required:"true"`
	Key        string            `json:"key,omitempty" doc:"Memory key (auto-generated if empty)"`
	Collection string            `json:"collection,omitempty" doc:"Collection name (defaults to 'default')"`
	Metadata   map[string]string `json:"metadata,omitempty" doc:"Custom metadata"`
}

StoreMemoryRequest represents a request to store a memory.

type ToolInfo

type ToolInfo struct {
	Name        string         `json:"name" doc:"Tool name"`
	Description string         `json:"description" doc:"Tool description"`
	Parameters  map[string]any `json:"parameters,omitempty" doc:"JSON Schema for tool parameters"`
	Category    string         `json:"category,omitempty" doc:"Tool category"`
}

ToolInfo represents information about an available tool.

type TriggerCronJobInput

type TriggerCronJobInput struct {
	ID string `path:"id" doc:"Cron job ID"`
}

TriggerCronJobInput is the request for triggering a cron job.

type TriggerCronJobOutput

type TriggerCronJobOutput struct {
	Body CronJobResult
}

TriggerCronJobOutput is the response for triggering a cron job.

type UpdateAgentInput

type UpdateAgentInput struct {
	ID   string `path:"id" doc:"Agent ID"`
	Body UpdateAgentRequest
}

UpdateAgentInput is the request for updating an agent.

type UpdateAgentRequest

type UpdateAgentRequest struct {
	Name         *string  `json:"name,omitempty" doc:"Agent display name"`
	Description  *string  `json:"description,omitempty" doc:"Agent description"`
	Provider     *string  `json:"provider,omitempty" doc:"LLM provider"`
	Model        *string  `json:"model,omitempty" doc:"Model identifier"`
	APIKey       *string  `json:"api_key,omitempty" doc:"API key for the provider"` //nolint:gosec // G101: API key in request
	BaseURL      *string  `json:"base_url,omitempty" doc:"Base URL for the provider"`
	Temperature  *float64 `json:"temperature,omitempty" doc:"Sampling temperature"`
	MaxTokens    *int     `json:"max_tokens,omitempty" doc:"Maximum tokens to generate"`
	SystemPrompt *string  `json:"system_prompt,omitempty" doc:"System prompt"`
	AllowedTools []string `json:"allowed_tools,omitempty" doc:"Allowed tool names"`
	DeniedTools  []string `json:"denied_tools,omitempty" doc:"Denied tool names"`
	Enabled      *bool    `json:"enabled,omitempty" doc:"Whether agent is enabled"`
}

UpdateAgentRequest represents a request to update an agent.

type UpdateCronJobInput

type UpdateCronJobInput struct {
	ID   string `path:"id" doc:"Cron job ID"`
	Body UpdateCronJobRequest
}

UpdateCronJobInput is the request for updating a cron job.

type UpdateCronJobRequest

type UpdateCronJobRequest struct {
	Name        *string           `json:"name,omitempty" doc:"Job name"`
	Description *string           `json:"description,omitempty" doc:"Job description"`
	Schedule    *CronScheduleInfo `json:"schedule,omitempty" doc:"Job schedule configuration"`
	Action      *CronActionInfo   `json:"action,omitempty" doc:"Job action configuration"`
}

UpdateCronJobRequest represents a request to update a scheduled job.

type UsageBucket

type UsageBucket struct {
	Timestamp        time.Time `json:"timestamp" doc:"Bucket start timestamp"`
	Requests         int64     `json:"requests" doc:"Number of requests"`
	PromptTokens     int64     `json:"prompt_tokens" doc:"Input tokens"`
	CompletionTokens int64     `json:"completion_tokens" doc:"Output tokens"`
	TotalTokens      int64     `json:"total_tokens" doc:"Total tokens"`
	Cost             float64   `json:"cost" doc:"Estimated cost in USD"`
}

UsageBucket represents usage for a single time bucket.

type UsageRecord

type UsageRecord struct {
	ID               string    `json:"id" doc:"Record ID"`
	Timestamp        time.Time `json:"timestamp" doc:"Request timestamp"`
	Model            string    `json:"model" doc:"Model used"`
	AgentID          string    `json:"agent_id,omitempty" doc:"Agent ID if applicable"`
	SessionID        string    `json:"session_id,omitempty" doc:"Session ID"`
	PromptTokens     int       `json:"prompt_tokens" doc:"Input tokens"`
	CompletionTokens int       `json:"completion_tokens" doc:"Output tokens"`
	TotalTokens      int       `json:"total_tokens" doc:"Total tokens"`
	Cost             float64   `json:"cost" doc:"Estimated cost in USD"`
	Latency          int64     `json:"latency_ms" doc:"Response latency in milliseconds"`
}

UsageRecord represents a single usage event.

type UsageRecordsInput

type UsageRecordsInput struct {
	Limit int `query:"limit" default:"100" doc:"Maximum number of records to return"`
}

UsageRecordsInput is the request for getting usage records.

type UsageRecordsOutput

type UsageRecordsOutput struct {
	Body struct {
		Object string        `json:"object" example:"list" doc:"Object type"`
		Data   []UsageRecord `json:"data" doc:"Usage records"`
	}
}

UsageRecordsOutput is the response for usage records.

type UsageStore

type UsageStore interface {
	GetSummary(since, until time.Time) *UsageSummary
	GetTimeseries(since, until time.Time, interval string) *UsageTimeseries
	GetRecords(limit int) []UsageRecord
}

UsageStore defines usage tracking operations.

type UsageSummary

type UsageSummary struct {
	TotalRequests     int64                  `json:"total_requests" doc:"Total number of requests"`
	TotalPromptTokens int64                  `json:"total_prompt_tokens" doc:"Total input tokens"`
	TotalCompTokens   int64                  `json:"total_completion_tokens" doc:"Total output tokens"`
	TotalTokens       int64                  `json:"total_tokens" doc:"Total tokens"`
	TotalCost         float64                `json:"total_cost" doc:"Total estimated cost in USD"`
	AvgLatency        float64                `json:"avg_latency_ms" doc:"Average response latency"`
	ByModel           map[string]*ModelUsage `json:"by_model" doc:"Usage breakdown by model"`
	ByAgent           map[string]*AgentUsage `json:"by_agent" doc:"Usage breakdown by agent"`
	PeriodStart       time.Time              `json:"period_start" doc:"Period start timestamp"`
	PeriodEnd         time.Time              `json:"period_end" doc:"Period end timestamp"`
}

UsageSummary provides aggregated usage statistics.

type UsageSummaryInput

type UsageSummaryInput struct {
	Since string `query:"since" doc:"Start time (RFC3339 or relative: 1h, 24h, 7d, 30d)"`
	Until string `query:"until" doc:"End time (RFC3339, defaults to now)"`
}

UsageSummaryInput is the request for getting usage summary.

type UsageSummaryOutput

type UsageSummaryOutput struct {
	Body UsageSummary
}

UsageSummaryOutput is the response for usage summary.

type UsageTimeseries

type UsageTimeseries struct {
	Interval string        `json:"interval" doc:"Bucket interval (hour, day)"`
	Buckets  []UsageBucket `json:"buckets" doc:"Time-bucketed data"`
}

UsageTimeseries represents time-bucketed usage data.

type UsageTimeseriesInput

type UsageTimeseriesInput struct {
	Since    string `query:"since" doc:"Start time (RFC3339 or relative)"`
	Until    string `query:"until" doc:"End time (RFC3339)"`
	Interval string `query:"interval" default:"hour" doc:"Bucket interval (minute, hour, day)"`
}

UsageTimeseriesInput is the request for getting usage timeseries.

type UsageTimeseriesOutput

type UsageTimeseriesOutput struct {
	Body UsageTimeseries
}

UsageTimeseriesOutput is the response for usage timeseries.

Jump to

Keyboard shortcuts

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