config_en.md

Config Package (pkg/config)

The config package provides a flexible, powerful, and structured configuration management solution specifically designed for HypGo. It supports reading YAML configuration files, environment variable expansion, parameter validation, and default value handling.

Key Features

• YAML Support and Deserialization: Through mapstructure and yaml tags, configuration files can be easily mapped to structs.
• Flexible Configuration Sources: The LoadConfig method allows loading a configuration file from a given path into the application; an error is thrown if the path doesn't contain a configuration.
• Interface Isolation Design: Defines a series of interfaces (ConfigInterface, ServerConfigInterface, DatabaseConfigInterface, RedisConfigInterface, LoggerConfigInterface) to provide clear constraints and improve testability for configuration objects.
• Read-Write Separation Configuration Support: Provides ReplicaConfigProvider and DatabaseConfig.Replicas configuration for easily setting up multiple Read Replicas, with easy fallback to the primary database.
• Advanced Validation Support: Integrates validation tools from @maoxiaoyue/hypgo/pkg/json or other validation strategies to verify that configuration values are required or conform to specified formats.

Basic Usage

The following example demonstrates how to load a configuration file named config.yaml:

package main

import (
	"log"

	"github.com/maoxiaoyue/hypgo/pkg/config"
)

func main() {
	// Assuming config.yaml exists
	cfg, err := config.LoadConfig("config.yaml")
	if err != nil {
		log.Fatalf("Unable to load configuration: %v", err)
	}

	// Ensure all values have default fallbacks
	cfg.ApplyDefaults()

	log.Printf("Server will start on %s", cfg.GetServerConfig().GetAddr())
}

Configuration Structure

The configuration is divided into three main sections:

1. Server: Server connection settings, Protocol (HTTP2/3, etc.), TLS, and Graceful Restart configuration.
2. Database: Connection driver, DSN, connection pool settings, as well as Redis and multiple Data Replicas configuration.
3. Logger: Output log level, format, output destination, etc.

Example config.yaml:

server:
  addr: ":8080"
  protocol: "HTTP/1.1"

database:
  driver: "mysql"
  dsn: "user:pass@tcp(127.0.0.1:3306)/dbname"

logger:
  level: "info"
  format: "json"

Default Value Reference

If certain parameters are not provided, calling cfg.ApplyDefaults() defaults to:

• Server addr: :8080
• Server protocol: HTTP/1.1
• Read/Write Timeout: 10 / 10
• Logger level: info
• DB MaxIdle/Open Conns etc. also have built-in default references

LLM Configuration (llm.yaml)

v0.8.5+ LLMConfig and llm.yaml are new in v0.8.5 and are not available in v0.8.1.

HypGo provides a standalone LLM configuration file for controlling the Manifest smart enrichment feature. Place it at config/llm.yaml or .hyp/llm.yaml.

Configuration Structure

type LLMConfig struct {
    Mode   string       `yaml:"mode"`    // "none", "rag", "ollama", "api"
    RAG    RAGConfig    `yaml:"rag"`     // used when mode=rag
    Ollama OllamaConfig `yaml:"ollama"`  // used when mode=ollama
    API    APIConfig    `yaml:"api"`     // used when mode=api
}

Four Modes

Mode	Description	Cost
none	No LLM, pure Go inference only (default)	Zero
ollama	Connect to local Ollama server	Free (local compute)
api	Connect to remote API (OpenAI / Anthropic / Gemini)	Pay-per-use
rag	Vector DB + embedding + LLM generation	Pay-per-use

Ollama Configuration

mode: ollama
ollama:
  url: "http://localhost:11434"    # default
  model: "llama3"                  # required
  timeout: 30                      # seconds (default 30)
  max_tokens: 256                  # default 256

API Configuration

Supports 4 providers: openai, anthropic, gemini, custom.

mode: api
api:
  provider: "openai"               # required
  model: "gpt-4o-mini"             # required
  api_key: "${OPENAI_API_KEY}"     # required (supports ${ENV_VAR})
  base_url: ""                     # each provider has a default
  timeout: 30                      # seconds (default 30)
  max_tokens: 256                  # default 256

Provider Default BaseURLs:

Provider	Default BaseURL
openai	https://api.openai.com/v1
anthropic	https://api.anthropic.com/v1
gemini	https://generativelanguage.googleapis.com/v1beta
custom	Must be set manually

RAG Configuration

mode: rag
rag:
  embedding_model: "nomic-embed-text"       # required
  embedding_url: "http://localhost:11434"    # default Ollama
  vector_store: "chroma"                    # required: chroma/qdrant/milvus/faiss
  vector_store_url: "http://localhost:8000"  # required
  collection: "my_codebase"                 # collection name
  top_k: 5                                  # retrieval count (default 5)
  generator_model: "llama3"                 # required
  generator_url: "http://localhost:11434"    # default Ollama

Loading

// Load from path (returns mode=none defaults if file doesn't exist)
cfg, err := config.LoadLLMConfig("config/llm.yaml")

// Empty path → mode=none
cfg, err := config.LoadLLMConfig("")

// Check if enabled
if cfg.IsEnabled() {
    // mode != "none"
}

Security Design

• API Key Environment Variables: api_key supports ${ENV_VAR} syntax to avoid storing keys in plaintext
• Manifest Safety: LLM configuration never appears in Manifest output
• Response Sanitization: LLM responses are cleaned — HTML/script tags removed, length limited to 500 characters
• Local-First: Ollama defaults to localhost only

Example Configuration

See pkg/config/llm_example.yaml for a fully commented example.