domain

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package domain 은 AI 어시스턴트의 대화 규칙이다 — 화면이 보낸 대화의 검증, 모델과 주고받는 메시지, 외부 LLM 으로 나가는 도구 결과의 가리기와 자르기. 외부 의존이 없다.

Index

Constants

View Source 
const (
	// MaxTurns · MaxTurnChars 는 화면이 한 번에 보낼 수 있는 대화의 크기다 — 크레딧과 컨텍스트를 묶는다.
	MaxTurns     = 20
	MaxTurnChars = 4000
	// MaxToolRounds 는 한 질문에서 도구를 부르는 라운드 상한이다. 넘기면 도구 없이 한 번 더 물어 마무리한다.
	MaxToolRounds = 6
	// MaxToolOutputChars 는 도구 결과 하나를 모델에 넘기는 길이 상한이다(GitLab 설치 로그는 수만 자다).
	MaxToolOutputChars = 12000
	// MaxToolCallsPerRound · MaxToolCallsTotal 은 한 라운드 · 한 질문에서 실행하는 도구 호출 수다. 도구는 API 를
	// 루프백으로 부르므로 IP 상한(127.0.0.1 하나)과 질문한 사용자의 레이트리밋을 함께 쓴다.
	MaxToolCallsPerRound = 8
	MaxToolCallsTotal    = 20
	// MaxPathChars 는 시스템 프롬프트에 넣는 화면 경로의 길이 상한이다.
	MaxPathChars = 200
)
View Source 
const (
	ProviderUpstage          = "upstage"
	ProviderOpenAI           = "openai"
	ProviderAnthropic        = "anthropic"
	ProviderGemini           = "gemini"
	ProviderOpenAICompatible = "openai-compatible"
)

공급자 ID.

View Source 
const MaxModelChars = 200

MaxModelChars 는 모델 이름의 길이 상한이다.

Variables

View Source 
var (
	// ErrInvalidConversation 은 화면이 보낸 대화가 규칙에 맞지 않는다는 뜻이다.
	ErrInvalidConversation = errors.New("assistant: invalid conversation")
	// ErrNotConfigured 는 LLM API 키가 없어 어시스턴트가 꺼져 있다는 뜻이다.
	ErrNotConfigured = errors.New("assistant: not configured")
	// ErrUpstream 은 LLM 호출이 실패했다는 뜻이다(키 · 크레딧 · 응답 오류).
	ErrUpstream = errors.New("assistant: llm request failed")
	// ErrTimeout 은 질문 하나에 쓸 시간을 넘겼다는 뜻이다.
	ErrTimeout = errors.New("assistant: timed out")
)
View Source 
var (
	// ErrInvalidSettings 는 관리자가 넣은 설정이 맞지 않는다는 뜻이다.
	ErrInvalidSettings = errors.New("assistant: invalid settings")
	// ErrKeyStorageUnavailable 은 API 키를 안전하게 저장할 수 없다는 뜻이다(ENCRYPTION_KEY 없음).
	ErrKeyStorageUnavailable = errors.New("assistant: key storage unavailable")
)

Functions

func LastUserQuestion 

func LastUserQuestion(turns []Turn) string

LastUserQuestion 은 대화에서 마지막 사용자 발화다. 없으면 빈 문자열.

func RedactSecrets 

func RedactSecrets(s string) string

RedactSecrets 는 문자열 안의 토큰 · 비밀번호 · 개인 키를 가린다.

func RequiresToolFirst 

func RequiresToolFirst(question string) bool

RequiresToolFirst 는 질문이 플랫폼 사실을 묻는 조회 질문인지다.

func SystemPrompt 

func SystemPrompt(page PageContext) string

SystemPrompt 는 모델에 주는 규칙이다. 화면이 대화를 들고 오므로 매 요청 맨 앞에 붙인다.

func TruncateToolOutput 

func TruncateToolOutput(s string, max int) string

TruncateToolOutput 은 도구 결과를 max 자 안팎으로 줄인다. 앞 1/3 과 뒤 2/3 를 남기고 가운데를 생략한다 — 설치 로그는 오래된 줄부터 와서 실패 원인이 끝에 있다.

func ValidateSettings 

func ValidateSettings(s Settings) error

ValidateSettings 는 설정을 검증한다. 꺼진 설정은 공급자만 맞으면 저장할 수 있다.

func ValidateTurns 

func ValidateTurns(turns []Turn) error

ValidateTurns 는 화면이 보낸 대화를 검증한다. system · tool 역할을 꾸며 넣어 지시를 바꾸지 못하게 한다.

Types

type Message 

type Message struct {
	Role         Role
	Content      string
	ToolCalls    []ToolCall
	ToolCallID   string
	ProviderData []byte
}

Message 는 모델과 주고받는 메시지다. assistant 는 ToolCalls 를, tool 은 ToolCallID 를 가질 수 있다. ProviderData 는 공급자가 응답에 담아 보낸 원본을 다음 라운드에 그대로 돌려주는 자리다(Anthropic 의 thinking 블록과 서명 — 빼거나 바꾸면 거부된다).

type PageContext 

type PageContext struct {
	Path string
}

PageContext 는 사용자가 보고 있는 화면이다. NewPageContext 로 만든다.

func NewPageContext 

func NewPageContext(path string) PageContext

NewPageContext 는 화면 경로를 시스템 프롬프트에 넣을 수 있게 다듬는다 — 줄바꿈 · 제어 문자를 지우고 길이를 묶어, 경로에 지시문을 끼워 넣거나 비용 상한을 우회하지 못하게 한다.

type Protocol 

type Protocol string

Protocol 은 모델 API 의 모양이다. 벤더는 여럿이어도 모양은 둘이다. 

const (
	// ProtocolOpenAI 는 OpenAI 호환 Chat Completions 다(Upstage · OpenAI · Gemini 의 OpenAI 호환 엔드포인트 · vLLM 등).
	ProtocolOpenAI Protocol = "openai"
	// ProtocolAnthropic 은 Anthropic Messages API 다.
	ProtocolAnthropic Protocol = "anthropic"
)

type Provider 

type Provider struct {
	ID             string   `json:"id"`
	Protocol       Protocol `json:"protocol"`
	DefaultBaseURL string   `json:"default_base_url,omitempty"`
	DefaultModel   string   `json:"default_model,omitempty"`
	// KeyRequired 가 거짓이면 키 없이도 켤 수 있다(사내 서버).
	KeyRequired bool `json:"key_required"`
}

Provider 는 고를 수 있는 모델 공급자다. 기본 주소 · 모델이 비어 있으면 관리자가 넣어야 한다.

func ProviderByID 

func ProviderByID(id string) (Provider, bool)

ProviderByID 는 공급자를 찾는다.

func Providers 

func Providers() []Provider

Providers 는 고를 수 있는 공급자다.

type Role 

type Role string

Role 은 메시지를 누가 말했는지다(OpenAI 호환 Chat Completions 의 역할 이름). 

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type Settings 

type Settings struct {
	OrgID    string
	Enabled  bool
	Provider string
	BaseURL  string
	Model    string
	APIKey   string
	// KeyUnreadable 은 키가 저장돼 있지만 복호화하지 못했다는 뜻이다(ENCRYPTION_KEY 가 바뀜). 관리자가 다시 넣는다.
	KeyUnreadable bool
	UpdatedAt     time.Time
	UpdatedBy     string
}

Settings 는 조직의 어시스턴트 설정이다. APIKey 는 저장소에서 복호화한 원문이다 — 응답에는 KeyHint 만 싣는다.

func (Settings) EffectiveBaseURL 

func (s Settings) EffectiveBaseURL() string

EffectiveBaseURL · EffectiveModel 은 비어 있으면 공급자 기본값이다.

func (Settings) EffectiveModel 

func (s Settings) EffectiveModel() string

func (Settings) HasKey 

func (s Settings) HasKey() bool

HasKey 는 키가 저장돼 있는지다.

func (Settings) KeyHint 

func (s Settings) KeyHint() string

KeyHint 는 화면에 보일 키 표시다 — 끝 네 자리만. 8자보다 짧으면 끝자리도 보이지 않는다.

func (Settings) Ready 

func (s Settings) Ready() bool

Ready 는 대화에 쓸 수 있는 설정인지다.

func (Settings) SameEndpoint 

func (s Settings) SameEndpoint(o Settings) bool

SameEndpoint 는 키를 보낼 곳이 같은지다 — 공급자와 실제 주소가 둘 다 같아야 한다. 저장된 키는 같은 곳으로만 이어 쓴다(주소만 바꿔 저장된 키를 다른 서버로 보내 빼내지 못하게).

type ToolCall 

type ToolCall struct {
	ID           string
	Name         string
	Arguments    string
	ProviderData []byte
}

ToolCall 은 모델이 고른 도구 호출이다. Arguments 는 모델이 만든 JSON 문자열 그대로다. ProviderData 는 공급자가 호출에 붙여 보낸 것을 다음 요청에 그대로 되돌려 주는 자리다(Gemini 의 사고 서명 — 빠지면 400).

type ToolSpec 

type ToolSpec struct {
	Name        string
	Description string
	Parameters  map[string]any
}

ToolSpec 은 모델에 알려 주는 도구 하나다. Parameters 는 JSON Schema 다.

type ToolTrace 

type ToolTrace struct {
	Name string `json:"name"`
	OK   bool   `json:"ok"`
}

ToolTrace 는 답에 함께 싣는 "사용한 도구" 한 줄이다 — 인자 · 결과는 싣지 않는다.

type Turn 

type Turn struct {
	Role    Role
	Content string
}

Turn 은 화면이 보낸 대화 한 줄이다. 화면은 user · assistant 만 보낼 수 있다.

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.