api

package
v0.0.0-...-a256278 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package api provides HTTP API handlers for TARSy.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentView 

type AgentView struct {
	Type               string            `json:"type,omitempty"`
	Description        string            `json:"description,omitempty"`
	MCPServers         []string          `json:"mcp_servers,omitempty"`
	CustomInstructions string            `json:"custom_instructions"`
	LLMBackend         string            `json:"llm_backend,omitempty"`
	MaxIterations      *int              `json:"max_iterations,omitempty"`
	NativeTools        map[string]bool   `json:"native_tools,omitempty"`
	Orchestrator       *OrchestratorView `json:"orchestrator"`
	Skills             *[]string         `json:"skills"`
	RequiredSkills     []string          `json:"required_skills,omitempty"`
}

AgentView is the agent config view (no llm_provider field).

type AlertMaskingView 

type AlertMaskingView struct {
	Enabled      bool   `json:"enabled"`
	PatternGroup string `json:"pattern_group"`
}

AlertMaskingView is alert masking defaults.

type AlertResponse 

type AlertResponse struct {
	SessionID string `json:"session_id"`
	Status    string `json:"status"`
	Message   string `json:"message"`
}

AlertResponse is returned by POST /api/v1/alerts.

type AlertTypeInfo 

type AlertTypeInfo struct {
	Type        string `json:"type"`
	ChainID     string `json:"chain_id"`
	Description string `json:"description"`
}

AlertTypeInfo describes a single alert type and its associated chain.

type AlertTypesResponse 

type AlertTypesResponse struct {
	AlertTypes       []AlertTypeInfo `json:"alert_types"`
	DefaultChainID   string          `json:"default_chain_id"`
	DefaultAlertType string          `json:"default_alert_type"`
}

AlertTypesResponse is returned by GET /api/v1/alert-types.

type CancelResponse 

type CancelResponse struct {
	SessionID string `json:"session_id"`
	Message   string `json:"message"`
}

CancelResponse is returned by POST /api/v1/sessions/:id/cancel.

type ChainView 

type ChainView struct {
	AlertTypes               []string               `json:"alert_types"`
	Description              string                 `json:"description,omitempty"`
	Stages                   []StageView            `json:"stages"`
	Chat                     *ChatView              `json:"chat,omitempty"`
	Scoring                  *ScoringView           `json:"scoring,omitempty"`
	LLMProvider              string                 `json:"llm_provider,omitempty"`
	ExecutiveSummaryProvider string                 `json:"executive_summary_provider,omitempty"`
	ComposeProvider          string                 `json:"compose_provider,omitempty"`
	LLMBackend               string                 `json:"llm_backend,omitempty"`
	FallbackProviders        []FallbackProviderView `json:"fallback_providers,omitempty"`
	MaxIterations            *int                   `json:"max_iterations,omitempty"`
	MCPServers               []string               `json:"mcp_servers,omitempty"`
	SubAgents                []SubAgentView         `json:"sub_agents,omitempty"`
}

ChainView is the chain config view.

type ChatView 

type ChatView struct {
	Enabled       bool           `json:"enabled"`
	Agent         string         `json:"agent,omitempty"`
	LLMBackend    string         `json:"llm_backend,omitempty"`
	LLMProvider   string         `json:"llm_provider,omitempty"`
	MCPServers    []string       `json:"mcp_servers,omitempty"`
	MaxIterations *int           `json:"max_iterations,omitempty"`
	SubAgents     []SubAgentView `json:"sub_agents,omitempty"`
}

ChatView is chain chat config.

type CostCatalogStatusView 

type CostCatalogStatusView struct {
	Source     string  `json:"source"`
	EntryCount int     `json:"entry_count"`
	LastFetch  *string `json:"last_fetch,omitempty"` // RFC3339
	LastError  string  `json:"last_error,omitempty"`
}

CostCatalogStatusView describes the in-memory price catalog.

type CostEstimationView 

type CostEstimationView struct {
	Enabled    bool                     `json:"enabled"`
	ModelRates map[string]ModelRateView `json:"model_rates,omitempty"`
	Promotions []PromotionView          `json:"promotions,omitempty"`
	Catalog    CostCatalogStatusView    `json:"catalog"`
}

CostEstimationView is cost-estimation settings + catalog status for Config Viewer.

type DefaultToolsResponse 

type DefaultToolsResponse struct {
	AlertType   string          `json:"alert_type,omitempty"`
	MCPServers  []string        `json:"mcp_servers"`
	NativeTools map[string]bool `json:"native_tools"`
}

DefaultToolsResponse is returned by GET /api/v1/system/default-tools.

type DefaultsView 

type DefaultsView struct {
	LLMProvider       string                 `json:"llm_provider,omitempty"`
	ComposeProvider   string                 `json:"compose_provider,omitempty"`
	MaxIterations     *int                   `json:"max_iterations,omitempty"`
	LLMBackend        string                 `json:"llm_backend,omitempty"`
	FallbackProviders []FallbackProviderView `json:"fallback_providers,omitempty"`
	Scoring           *ScoringView           `json:"scoring,omitempty"`
	Summarization     *SummarizationView     `json:"summarization,omitempty"`
	SuccessPolicy     string                 `json:"success_policy,omitempty"`
	AlertType         string                 `json:"alert_type,omitempty"`
	Runbook           string                 `json:"runbook,omitempty"`
	AlertMasking      *AlertMaskingView      `json:"alert_masking,omitempty"`
	Orchestrator      *OrchestratorView      `json:"orchestrator,omitempty"`
	Memory            *MemoryView            `json:"memory,omitempty"`
}

DefaultsView is system-wide defaults.

type EmbeddingView 

type EmbeddingView struct {
	Provider   string `json:"provider,omitempty"`
	Model      string `json:"model,omitempty"`
	APIKeyEnv  string `json:"api_key_env,omitempty"`
	Dimensions int    `json:"dimensions,omitempty"`
	BaseURL    string `json:"base_url,omitempty"`
}

EmbeddingView is embedding model config (api_key_env name only).

type FallbackProviderView 

type FallbackProviderView struct {
	Provider string `json:"provider"`
	Backend  string `json:"backend"`
}

FallbackProviderView is a fallback provider entry.

type FilterOptionsResponse 

type FilterOptionsResponse struct {
	AlertTypes []string `json:"alert_types"`
	ChainIDs   []string `json:"chain_ids"`
	Statuses   []string `json:"statuses"`
}

FilterOptionsResponse is returned by GET /api/v1/sessions/filter-options.

type GitHubView 

type GitHubView struct {
	TokenEnv string `json:"token_env,omitempty"`
}

GitHubView shows token env name only.

type HealthCheck 

type HealthCheck struct {
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

HealthCheck represents the status of a single health check component.

type HealthResponse 

type HealthResponse struct {
	Status  string                 `json:"status"`
	Version string                 `json:"version"`
	Checks  map[string]HealthCheck `json:"checks"`
}

HealthResponse is returned by GET /health.

type LLMProviderView 

type LLMProviderView struct {
	Type           string          `json:"type"`
	Model          string          `json:"model"`
	APIKeyEnv      string          `json:"api_key_env,omitempty"`
	CredentialsEnv string          `json:"credentials_env,omitempty"`
	ProjectEnv     string          `json:"project_env,omitempty"`
	LocationEnv    string          `json:"location_env,omitempty"`
	BaseURL        string          `json:"base_url,omitempty"`
	NativeTools    map[string]bool `json:"native_tools,omitempty"`
}

LLMProviderView is an LLM provider config entry.

type MCPServerStatus 

type MCPServerStatus struct {
	ID        string        `json:"id"`
	Healthy   bool          `json:"healthy"`
	LastCheck string        `json:"last_check"`
	ToolCount int           `json:"tool_count"`
	Tools     []MCPToolInfo `json:"tools"`
	Error     *string       `json:"error"`
}

MCPServerStatus describes the health and tools of a single MCP server.

type MCPServerView 

type MCPServerView struct {
	Transport     SanitizedTransport    `json:"transport"`
	Instructions  string                `json:"instructions,omitempty"`
	DataMasking   *config.MaskingConfig `json:"data_masking,omitempty"`
	Summarization *MCPSummarizationView `json:"summarization,omitempty"`
}

MCPServerView is a sanitized MCP server config entry.

type MCPServersResponse 

type MCPServersResponse struct {
	Servers []MCPServerStatus `json:"servers"`
}

MCPServersResponse is returned by GET /api/v1/system/mcp-servers.

type MCPSummarizationView 

type MCPSummarizationView struct {
	Enabled              *bool  `json:"enabled,omitempty"`
	SizeThresholdTokens  int    `json:"size_threshold_tokens,omitempty"`
	SummaryMaxTokenLimit int    `json:"summary_max_token_limit,omitempty"`
	LLMProvider          string `json:"llm_provider,omitempty"`
	LLMBackend           string `json:"llm_backend,omitempty"`
}

MCPSummarizationView is an MCP server summarization block, including server-only enablement and size fields.

type MCPToolInfo 

type MCPToolInfo struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

MCPToolInfo describes a single tool from an MCP server.

type MemoryView 

type MemoryView struct {
	Enabled              bool          `json:"enabled"`
	MaxInject            int           `json:"max_inject,omitempty"`
	ReflectorMemoryLimit int           `json:"reflector_memory_limit,omitempty"`
	Embedding            EmbeddingView `json:"embedding,omitempty"`
}

MemoryView is investigation memory config.

type ModelRateView 

type ModelRateView struct {
	InputPerMillion  float64 `json:"input_per_million"`
	OutputPerMillion float64 `json:"output_per_million"`
}

ModelRateView is a flat per-million USD override.

type OrchestratorView 

type OrchestratorView struct {
	MaxConcurrentAgents *int    `json:"max_concurrent_agents,omitempty"`
	AgentTimeout        *string `json:"agent_timeout,omitempty"`
	MaxBudget           *string `json:"max_budget,omitempty"`
}

OrchestratorView emits duration fields as strings.

type PromotionView 

type PromotionView struct {
	ID               string  `json:"id,omitempty"`
	Model            string  `json:"model"`
	InputPerMillion  float64 `json:"input_per_million"`
	OutputPerMillion float64 `json:"output_per_million"`
	Start            *string `json:"start,omitempty"`  // RFC3339 UTC; omitted when already-active
	End              string  `json:"end"`              // RFC3339 UTC
	Status           string  `json:"status,omitempty"` // active | upcoming | expired
}

PromotionView is a time-bounded rate with lifecycle for Config Viewer.

type QueueView 

type QueueView struct {
	WorkerCount             int    `json:"worker_count"`
	MaxConcurrentSessions   int    `json:"max_concurrent_sessions"`
	PollInterval            string `json:"poll_interval"`
	PollIntervalJitter      string `json:"poll_interval_jitter"`
	SessionTimeout          string `json:"session_timeout"`
	GracefulShutdownTimeout string `json:"graceful_shutdown_timeout"`
	ScoringShutdownTimeout  string `json:"scoring_shutdown_timeout"`
	OrphanDetectionInterval string `json:"orphan_detection_interval"`
	OrphanThreshold         string `json:"orphan_threshold"`
	HeartbeatInterval       string `json:"heartbeat_interval"`
}

QueueView emits all queue durations as strings.

type RetentionView 

type RetentionView struct {
	SessionRetentionDays int    `json:"session_retention_days"`
	EventTTL             string `json:"event_ttl"`
	CleanupInterval      string `json:"cleanup_interval"`
}

RetentionView emits durations as strings.

type RunbooksView 

type RunbooksView struct {
	RepoURL        string   `json:"repo_url,omitempty"`
	CacheTTL       string   `json:"cache_ttl,omitempty"`
	AllowedDomains []string `json:"allowed_domains,omitempty"`
}

RunbooksView is runbook system config.

type SanitizedTransport 

type SanitizedTransport struct {
	Type              string   `json:"type"`
	Command           string   `json:"command,omitempty"`
	Args              []string `json:"args,omitempty"`
	URL               string   `json:"url,omitempty"`
	VerifySSL         *bool    `json:"verify_ssl,omitempty"`
	Timeout           int      `json:"timeout,omitempty"`
	EnvKeys           []string `json:"env_keys,omitempty"`
	CustomHeaderKeys  []string `json:"custom_header_keys,omitempty"`
	SessionCleanupURL string   `json:"session_cleanup_url,omitempty"`
	BearerTokenSet    bool     `json:"bearer_token_set"`
}

SanitizedTransport is the fail-closed MCP transport allowlist.

type ScoreSessionResponse 

type ScoreSessionResponse struct {
	ScoreID string `json:"score_id"`
}

ScoreSessionResponse is the HTTP response for POST /sessions/:id/score.

type ScoringView 

type ScoringView struct {
	Enabled       bool     `json:"enabled"`
	Agent         string   `json:"agent,omitempty"`
	LLMBackend    string   `json:"llm_backend,omitempty"`
	LLMProvider   string   `json:"llm_provider,omitempty"`
	MCPServers    []string `json:"mcp_servers,omitempty"`
	MaxIterations *int     `json:"max_iterations,omitempty"`
}

ScoringView is scoring config.

type SendChatMessageRequest 

type SendChatMessageRequest struct {
	Content string `json:"content"`
}

SendChatMessageRequest is the HTTP request body for POST /sessions/:id/chat/messages.

type SendChatMessageResponse 

type SendChatMessageResponse struct {
	ChatID    string `json:"chat_id"`
	MessageID string `json:"message_id"`
	StageID   string `json:"stage_id"`
}

SendChatMessageResponse is the HTTP response for POST /sessions/:id/chat/messages.

type Server 

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

Server is the HTTP API server.

func NewServer 

func NewServer(
	cfg *config.Config,
	dbClient *database.Client,
	alertService *services.AlertService,
	sessionService *services.SessionService,
	workerPool *queue.WorkerPool,
	connManager *events.ConnectionManager,
) *Server

NewServer creates a new API server with Echo v5.

func (*Server) SetCancelNotifier 

func (s *Server) SetCancelNotifier(cn events.SessionCancelNotifier)

SetCancelNotifier sets the cross-pod cancel notifier for session cancellation.

func (*Server) SetChatExecutor 

func (s *Server) SetChatExecutor(executor *queue.ChatMessageExecutor)

SetChatExecutor sets the chat message executor for follow-up chat processing.

func (*Server) SetChatService 

func (s *Server) SetChatService(svc *services.ChatService)

SetChatService sets the chat service for follow-up chat endpoints.

func (*Server) SetCostBook 

func (s *Server) SetCostBook(book *cost.Book)

SetCostBook sets the price book for Config Viewer catalog status.

func (*Server) SetDashboardDir 

func (s *Server) SetDashboardDir(dir string)

SetDashboardDir sets the path to the dashboard build directory and registers static file serving routes. When set and the directory contains an index.html, assets are served from /assets/* and a SPA fallback is registered for all non-API routes.

Must be called after NewServer (which registers API routes first) so that API routes take priority over the wildcard SPA fallback.

func (*Server) SetEventPublisher 

func (s *Server) SetEventPublisher(pub agent.EventPublisher)

SetEventPublisher sets the event publisher for real-time event delivery.

func (*Server) SetHealthMonitor 

func (s *Server) SetHealthMonitor(monitor *mcp.HealthMonitor)

SetHealthMonitor sets the MCP health monitor for the health endpoint.

func (*Server) SetInteractionService 

func (s *Server) SetInteractionService(svc *services.InteractionService)

SetInteractionService sets the interaction service for trace endpoints.

func (*Server) SetMemoryService 

func (s *Server) SetMemoryService(svc *memory.Service)

SetMemoryService sets the memory service for memory CRUD endpoints and review-triggered refinement.

func (*Server) SetRunbookService 

func (s *Server) SetRunbookService(rs *runbook.Service)

SetRunbookService sets the runbook service for the runbook listing endpoint.

func (*Server) SetScoringExecutor 

func (s *Server) SetScoringExecutor(executor *queue.ScoringExecutor)

SetScoringExecutor sets the scoring executor for the re-score endpoint.

func (*Server) SetScoringService 

func (s *Server) SetScoringService(svc *services.ScoringService)

SetScoringService sets the scoring service for score read endpoints.

func (*Server) SetStageService 

func (s *Server) SetStageService(svc *services.StageService)

SetStageService sets the stage service for trace endpoints.

func (*Server) SetTimelineService 

func (s *Server) SetTimelineService(svc *services.TimelineService)

SetTimelineService sets the timeline service for the timeline endpoint.

func (*Server) SetWarningsService 

func (s *Server) SetWarningsService(svc *services.SystemWarningsService)

SetWarningsService sets the system warnings service for the health endpoint.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the HTTP server.

func (*Server) Start 

func (s *Server) Start(addr string) error

Start starts the HTTP server on the given address (non-blocking).

func (*Server) StartWithListener 

func (s *Server) StartWithListener(ln net.Listener) error

StartWithListener starts the HTTP server on a pre-created listener. Used by test infrastructure to serve on a random OS-assigned port.

func (*Server) ValidateWiring 

func (s *Server) ValidateWiring() error

ValidateWiring checks that all required services have been wired via their Set* methods. Call this after all Set* calls and before Start/StartWithListener. Returns an error listing every missing service so that wiring gaps are caught at startup rather than surfacing as 503s at request time.

Services that are legitimately optional (e.g. healthMonitor / warningService when MCP is disabled) are NOT checked here.

type SkillMetaView 

type SkillMetaView struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

SkillMetaView is skill metadata (no body).

type SlackView 

type SlackView struct {
	Enabled  bool   `json:"enabled"`
	TokenEnv string `json:"token_env,omitempty"`
	Channel  string `json:"channel,omitempty"`
}

SlackView shows token env name only.

type StageAgentView 

type StageAgentView struct {
	Name              string                 `json:"name"`
	Type              string                 `json:"type,omitempty"`
	LLMProvider       string                 `json:"llm_provider,omitempty"`
	LLMBackend        string                 `json:"llm_backend,omitempty"`
	MaxIterations     *int                   `json:"max_iterations,omitempty"`
	MCPServers        []string               `json:"mcp_servers,omitempty"`
	SubAgents         []SubAgentView         `json:"sub_agents,omitempty"`
	FallbackProviders []FallbackProviderView `json:"fallback_providers,omitempty"`
	RequiredSkills    []string               `json:"required_skills,omitempty"`
	Skills            []string               `json:"skills,omitempty"`
}

StageAgentView is a stage agent reference with overrides.

type StageView 

type StageView struct {
	Name              string                 `json:"name"`
	Agents            []StageAgentView       `json:"agents"`
	Replicas          int                    `json:"replicas,omitempty"`
	SuccessPolicy     string                 `json:"success_policy,omitempty"`
	MaxIterations     *int                   `json:"max_iterations,omitempty"`
	MCPServers        []string               `json:"mcp_servers,omitempty"`
	FallbackProviders []FallbackProviderView `json:"fallback_providers,omitempty"`
	SubAgents         []SubAgentView         `json:"sub_agents,omitempty"`
	Synthesis         *SynthesisView         `json:"synthesis,omitempty"`
}

StageView is a chain stage.

type SubAgentView 

type SubAgentView struct {
	Name           string   `json:"name"`
	LLMProvider    string   `json:"llm_provider,omitempty"`
	LLMBackend     string   `json:"llm_backend,omitempty"`
	MaxIterations  *int     `json:"max_iterations,omitempty"`
	MCPServers     []string `json:"mcp_servers,omitempty"`
	RequiredSkills []string `json:"required_skills,omitempty"`
	Skills         []string `json:"skills,omitempty"`
}

SubAgentView is a sub-agent reference.

type SubmitAlertRequest 

type SubmitAlertRequest struct {
	AlertType               string                     `json:"alert_type"`
	Runbook                 string                     `json:"runbook,omitempty"`
	Data                    string                     `json:"data"`
	MCP                     *models.MCPSelectionConfig `json:"mcp,omitempty"`
	SlackMessageFingerprint string                     `json:"slack_message_fingerprint,omitempty"`
}

SubmitAlertRequest is the HTTP request body for POST /api/v1/alerts.

type SummarizationView 

type SummarizationView struct {
	LLMProvider string `json:"llm_provider,omitempty"`
	LLMBackend  string `json:"llm_backend,omitempty"`
}

SummarizationView is defaults.summarization (named provider/backend only).

type SynthesisView 

type SynthesisView struct {
	Agent       string `json:"agent,omitempty"`
	LLMBackend  string `json:"llm_backend,omitempty"`
	LLMProvider string `json:"llm_provider,omitempty"`
}

SynthesisView is stage synthesis config.

type SystemConfigResponse 

type SystemConfigResponse struct {
	Defaults     *DefaultsView              `json:"defaults"`
	Queue        *QueueView                 `json:"queue"`
	System       SystemView                 `json:"system"`
	Agents       map[string]AgentView       `json:"agents"`
	Chains       map[string]ChainView       `json:"chains"`
	MCPServers   map[string]MCPServerView   `json:"mcp_servers"`
	LLMProviders map[string]LLMProviderView `json:"llm_providers"`
	Skills       map[string]SkillMetaView   `json:"skills"`
}

SystemConfigResponse is returned by GET /api/v1/system/config.

type SystemConfigSkillResponse 

type SystemConfigSkillResponse struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Body        string `json:"body"`
}

SystemConfigSkillResponse is returned by GET /api/v1/system/config/skills/:name.

type SystemView 

type SystemView struct {
	GitHub           *GitHubView         `json:"github,omitempty"`
	Slack            *SlackView          `json:"slack,omitempty"`
	Runbooks         *RunbooksView       `json:"runbooks,omitempty"`
	Retention        *RetentionView      `json:"retention,omitempty"`
	CostEstimation   *CostEstimationView `json:"cost_estimation,omitempty"`
	DashboardURL     string              `json:"dashboard_url,omitempty"`
	AllowedWSOrigins []string            `json:"allowed_ws_origins"`
}

SystemView is GitHub/Slack/runbooks/retention/dashboard settings.

type SystemWarningItem 

type SystemWarningItem struct {
	ID        string `json:"id"`
	Category  string `json:"category"`
	Message   string `json:"message"`
	Details   string `json:"details"`
	ServerID  string `json:"server_id,omitempty"`
	CreatedAt string `json:"created_at"`
}

SystemWarningItem is a single system warning.

type SystemWarningsResponse 

type SystemWarningsResponse struct {
	Warnings []SystemWarningItem `json:"warnings"`
}

SystemWarningsResponse is returned by GET /api/v1/system/warnings.

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.