### Download and Run AxonHub Locally

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Quickly start AxonHub on your local machine using a downloaded release. Follow the setup wizard on first run.

```bash
# Download and extract (macOS ARM64 example)
curl -sSL https://github.com/looplj/axonhub/releases/latest/download/axonhub_darwin_arm64.tar.gz | tar xz
cd axonhub_*

# Run with SQLite (default)
./axonhub

# Open http://localhost:8090
# First run: Follow the setup wizard to initialize the system (create admin account, password must be at least 6 characters)
```

--------------------------------

### Copy Example Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Copy the example configuration file to create your own configuration file for customization.

```bash
cp config.example.yml config.yml
```

--------------------------------

### Install prek with uv

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Install the prek tool using the 'uv' Python package and tool manager.

```bash
uv tool install prek
```

--------------------------------

### Install prek with Standalone Installer

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Download and run the standalone installer script for prek on Linux or macOS.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh
```

--------------------------------

### Install prek with Homebrew

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Install the prek tool on macOS or Linux using Homebrew.

```bash
brew install prek
```

--------------------------------

### Virtual Machine Deployment - Install Script

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Command to execute the installation script for AxonHub on a Virtual Machine.

```bash
sudo ./install.sh
```

--------------------------------

### Virtual Machine Deployment - Start Service

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Command to start the AxonHub service on a Virtual Machine using the provided helper script.

```bash
# Start service
#  For simplicity, we recommend managing AxonHub with the helper scripts:

# Start
./start.sh
```

--------------------------------

### AxonHub Configuration Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Example configuration for AxonHub, specifying server port, name, database dialect, DSN, and logging settings.

```yaml
# config.yml
server:
  port: 8090
  name: "AxonHub"

db:
  dialect: "sqlite3"
  dsn: "file:axonhub.db?cache=shared&_fk=1&_pragma=journal_mode(WAL)"

log:
  level: "info"
  encoding: "json"
```

--------------------------------

### Install prek with pipx

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Install the prek tool using the 'pipx' Python application installer.

```bash
pipx install prek
```

--------------------------------

### Setting and Getting Principals

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/authz-coding-guidelines.md

Shows how to set a principal with conflict detection and retrieve the principal from a context.

```go
// Set principal (with conflict detection)
ctx, err := authz.WithPrincipal(ctx, principal)

// Get principal
p, ok := authz.GetPrincipal(ctx)
p := authz.MustGetPrincipal(ctx)  // panics if not exists
```

--------------------------------

### Install prek Git Hooks

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Install the git hooks managed by prek.

```bash
prek install
```

--------------------------------

### OIDC Provider Configuration Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/guides/oidc.md

Configure OIDC providers in `conf/config.yml`. This example shows settings for Google SSO, including JIT provisioning and PKCE.

```yaml
server:
  public_url: "https://axonhub.example.com"

oidc:
  providers:
    - id: "google"
      name: "google"
      display_name: "Google SSO"
      issuer_url: "https://accounts.google.com"
      client_id: "YOUR_GOOGLE_CLIENT_ID"
      client_secret: "YOUR_GOOGLE_CLIENT_SECRET"
      extra_scopes: ["openid", "profile", "email"]
      jit_enabled: true              # Automatically create user on first login (Just-In-Time)
      auto_link_by_email: true       # Link to existing user by verified email
      require_email_verified: true   # Only link if email is verified by IdP
      enable_pkce: true              # Recommended for enhanced security (RFC 7636)
      sync_user_info: true           # Sync name and avatar on every login
      button_color: "#DB4437"        # UI Customization: Button color
      icon_url: "https://www.google.com/favicon.ico" # UI Customization: Icon URL
```

--------------------------------

### Helm Kubernetes Quick Installation

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Command to perform a quick installation of AxonHub on Kubernetes using the official Helm chart.

```bash
# Quick installation
git clone https://github.com/looplj/axonhub.git
cd axonhub
helm install axonhub ./deploy/helm
```

--------------------------------

### Install AxonHub Helm Chart

Source: https://github.com/looplj/axonhub/blob/unstable/deploy/helm/README.md

Installs the AxonHub chart with a specified release name. Ensure you are in the project root directory.

```bash
helm install axonhub ./deploy/helm
```

--------------------------------

### Start AxonHub Services

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Start the AxonHub services using Docker Compose in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### MySQL Database Connection String

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Example connection string for a MySQL database.

```text
username:password@tcp(host:3306)/database?parseTime=True&multiStatements=true&charset=utf8mb4
```

--------------------------------

### Start AxonHub Backend

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/development.md

Build and run the AxonHub backend directly, or use 'air' for a development workflow with hot reloading. 'air' is recommended for active development.

```bash
# Option 1: Build and run directly
make build-backend
./axonhub

# Option 2: Use air for hot reload (recommended for development)
go install github.com/air-verse/air@latest
air
```

--------------------------------

### PostgreSQL Database Connection String

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Example connection string for a PostgreSQL database.

```text
postgres://username:password@host:5432/database?sslmode=disable
```

--------------------------------

### Model Mapping Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/getting-started/quick-start.md

Demonstrates how a client request for 'gpt-4o-mini' is mapped to 'gpt-4o'. This is useful for managing model availability and cost.

```python
response = client.chat.completions.create(
    model="gpt-4o-mini",  # Will be mapped to "gpt-4o"
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)
```

--------------------------------

### SQLite Database Connection String

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Example connection string for an SQLite database.

```text
file:axonhub.db?cache=shared&_fk=1&_pragma=journal_mode(WAL)
```

--------------------------------

### Load Balancer Setup with Nginx

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Docker Compose setup including AxonHub replicas and an Nginx service acting as a load balancer.

```yaml
services:
  axonhub:
    image: looplj/axonhub:latest
    deploy:
      replicas: 3
    networks:
      - axonhub_network

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - axonhub
    networks:
      - axonhub_network
```

--------------------------------

### Production Server, Database, and Cache Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Example configuration for a production environment, using PostgreSQL, Redis for caching, and JSON logging.

```yaml
server:
  port: 8090
  name: "AxonHub Production"
  debug: false
  request_timeout: "30s"
  llm_request_timeout: "600s"

db:
  dialect: "postgres"
  dsn: "postgres://axonhub:password@localhost:5432/axonhub?sslmode=disable"
  debug: false

cache:
  mode: "redis"
  redis:
    addr: "redis:6379"
    password: "redis-password"
    expiration: "30m"

log:
  level: "warn"
  encoding: "json"
  output: "file"
  file:
    path: "/var/log/axonhub/axonhub.log"
    max_size: 200
    max_age: 14
    max_backups: 7
```

--------------------------------

### Test Principal Setup with System or User Context

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/authz-coding-guidelines.md

Set up test contexts using `authz.NewSystemContext` or `authz.NewUserContext` for testing authorization logic. These functions create a background context with the specified principal type.

```go
func TestSomething(t *testing.T) {
    ctx := authz.NewSystemContext(context.Background())
    // or
    ctx := authz.NewUserContext(context.Background(), 123)

    // Test code...
}
```

--------------------------------

### Basic Request Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Make a basic API request to list models using cURL.

```bash
curl -s http://localhost:8090/v1/models \
  -H "Authorization: Bearer your-api-key" | jq
```

--------------------------------

### Example Load Balancing Decision Log

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/openai/chat/load_balance/README.md

An example log entry showing the details of a load balancing decision, including the number of channels considered, retry status, and the selected top channel with its score. This is useful for troubleshooting.

```plaintext
INFO Load balancing decision completed
  total_channels=4
  selected_channels=3
  retry_enabled=true
  max_channel_retries=2
  top_channel_id=1
  top_channel_name="High Priority Channel"
  top_channel_score=1250.5
```

--------------------------------

### Install prek with pnpm

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Add prek as a development dependency in a Node.js project using pnpm.

```bash
pnpm add -D @j178/prek
```

--------------------------------

### Development Server and Database Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Example configuration for a development environment, using SQLite for the database and enabling debug logging.

```yaml
server:
  port: 8090
  name: "AxonHub Dev"
  debug: true

db:
  dialect: "sqlite3"
  dsn: "file:axonhub.db?cache=shared&_fk=1"
  debug: true

log:
  level: "debug"
  encoding: "console"
  output: "stdio"
```

--------------------------------

### AxonHub Configuration for PostgreSQL

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Example environment variables for configuring AxonHub to use PostgreSQL as its database.

```yaml
axonhub:
  environment:
    - AXONHUB_DB_DIALECT=postgres
    - AXONHUB_DB_DSN=postgres://user:pass@host:5432/axonhub
```

--------------------------------

### OpenAI SDK Python Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Use the OpenAI Python SDK to list models and access extended metadata.

```python
import openai

client = openai.OpenAI(
    api_key="your-axonhub-api-key",
    base_url="http://localhost:8090/v1"
)

# Get models with extended metadata
models = client.models.list()
for model in models.data:
    print(f"Model: {model.id}")
    # Access extended fields if available
    if hasattr(model, 'name'):
        print(f"  Name: {model.name}")
    if hasattr(model, 'pricing'):
        print(f"  Input price: ${model.pricing.input}/1M tokens")
```

--------------------------------

### Example Load Balancing Log Entries

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/openai/chat/load_balance/TESTING_GUIDE.md

These log entries indicate a load balancing decision has been made and provide details about the selected channel.

```text
Load balancing decision completed
  total_channels=4
  selected_channels=3
  top_channel_id=1
  top_channel_score=1250.5
  
Channel load balancing details
  channel_id=1
  channel_name="High Priority"
  total_score=1250.5
  final_rank=1
  strategy_breakdown={...}
```

--------------------------------

### AxonHub Configuration for MySQL

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Example environment variables for configuring AxonHub to use MySQL as its database.

```yaml
axonhub:
  environment:
    - AXONHUB_DB_DIALECT=mysql
    - AXONHUB_DB_DSN=user:pass@tcp(host:3306)/axonhub?charset=utf8mb4&parseTime=True
```

--------------------------------

### Run prek version with uvx

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Check the prek version without installing it by using 'uvx'.

```bash
uvx prek --version
```

--------------------------------

### Virtual Machine Deployment - Configuration Check

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Command to check the AxonHub configuration after installation on a Virtual Machine.

```bash
# Configuration file check
axonhub config check
```

--------------------------------

### Client Request Headers for Context Entities

Source: https://github.com/looplj/axonhub/blob/unstable/internal/contexts/README.md

Example of how a client can send project, thread, and trace IDs using HTTP headers.

```bash
curl -H "X-Project-ID: proj_123" \
     -H "X-Thread-ID: thread-abc-123" \
     -H "X-Trace-ID: trace-xyz-456" \
     https://api.example.com/endpoint
```

--------------------------------

### Complete Channel Configuration with Model Mapping and Overrides

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/getting-started/quick-start.md

A complete channel configuration example for OpenAI production, including model mappings and override parameters for temperature, max tokens, and response format.

```yaml
# Complete channel configuration
name: "openai-production"
type: "openai"
base_url: "https://api.openai.com/v1"
credentials:
  api_key: "your-openai-key"
supported_models: ["gpt-4o", "gpt-4", "gpt-3.5-turbo"]
settings:
  modelMappings:
    - from: "chat-model"
      to: "gpt-4o"
    - from: "fast-model"
      to: "gpt-3.5-turbo"
  overrideParameters: |
    {
      "temperature": 0.3,
      "max_tokens": 1024,
      "response_format": {
        "type": "json_object"
      }
    }
```

--------------------------------

### Set Custom Database Passwords for Production

Source: https://github.com/looplj/axonhub/blob/unstable/deploy/helm/README.md

Example of setting secure, custom passwords for AxonHub and PostgreSQL in a production environment.

```yaml
axonhub:
  dbPassword: "your-secure-password"

postgresql:
  auth:
    postgresPassword: "your-secure-postgres-password"
    password: "your-secure-password"
```

--------------------------------

### Read-Write Separation Example (PostgreSQL)

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Demonstrates configuring read-write separation for PostgreSQL, specifying separate DSNs for the master and read replica. Queries are routed based on operation type.

```yaml
db:
  dialect: "postgres"
  dsn: "postgres://axonhub:password@master.db:5432/axonhub?sslmode=disable"
  read_replica:
    read_dsn: "postgres://axonhub:password@replica.db:5432/axonhub?sslmode=disable"
```

--------------------------------

### Selective Fields Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Request specific fields like 'name' and 'pricing' using the `include` parameter.

```bash
curl -s "http://localhost:8090/v1/models?include=name,pricing" \
  -H "Authorization: Bearer your-api-key" | jq
```

--------------------------------

### Run Migration Test with MySQL

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/migration/MIGRATION_TEST.md

Execute the migration test script using MySQL. Requires Docker to be installed and running.

```bash
./scripts/migration/migration-test.sh v0.1.0 --db-type mysql
```

--------------------------------

### Model Routing Examples Table

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/guides/antigravity.md

This table illustrates how different model names map to specific quota pools, initial endpoints, and fallback sequences.

```text
| Model Name | Quota Pool | Initial Endpoint | Fallback Sequence |
|------------|-----------|------------------|-------------------|
| `claude-sonnet-4-5` | Antigravity | Daily | Daily → Autopush → Prod |
| `gemini-2.5-pro` | Gemini CLI | Prod | Prod → Daily → Autopush |
| `gemini-2.5-pro:antigravity` | Antigravity | Daily | Daily → Autopush → Prod |
| `antigravity-gemini-2.5-pro` | Antigravity | Daily | Daily → Autopush → Prod |
| `gemini-3-flash` | Antigravity | Daily | Daily → Autopush → Prod |
| `gpt-oss-120b-medium` | Antigravity | Daily | Daily → Autopush → Prod |
```

--------------------------------

### Docker Compose Deployment for AxonHub

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Steps to deploy AxonHub using Docker Compose. This includes cloning the repository, setting environment variables for database connection, and starting the services.

```bash
# Clone project
git clone https://github.com/looplj/axonhub.git
cd axonhub

# Set environment variables
export AXONHUB_DB_DIALECT="tidb"
export AXONHUB_DB_DSN="<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4"

# Start services
docker-compose up -d

# Check status
docker-compose ps
```

--------------------------------

### Run Migration Test with SQLite

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/migration/MIGRATION_TEST.md

Execute the migration test script using SQLite as the default database. No Docker is required for this setup.

```bash
./scripts/migration/migration-test.sh v0.1.0
```

--------------------------------

### Setting up Context Middleware

Source: https://github.com/looplj/axonhub/blob/unstable/internal/contexts/README.md

Initialize thread and trace services and add middleware to the router. The WithProjectID middleware must be added first.

```go
threadService := biz.NewThreadService()
traceService := biz.NewTraceService()

// Add middleware to router (order matters)
router.Use(middleware.WithProjectID())      // Must come first
router.Use(middleware.WithThreadID(threadService))
router.Use(middleware.WithTraceID(traceService))
```

--------------------------------

### Update prek

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Update prek to the latest version if installed via the standalone installer.

```bash
prek self update
```

--------------------------------

### Go Gemini SDK Client and Model Usage

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/gemini/README.md

Demonstrates how to create a client, select a model, and generate content using the go-genai library. Ensure the context and any necessary options are provided.

```go
import "google.golang.org/genai"

// Create client
client, err := genai.NewClient(ctx, opts...)

// Create model
model := client.GenerativeModel("gemini-1.5-flash")

// Generate content
response, err := model.GenerateContent(ctx, genai.Text("Hello"))

// Chat session
session := model.StartChat()
response, err := session.SendMessage(ctx, genai.Text("Follow-up question"))
```

--------------------------------

### GitHub Actions E2E Test Example

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/e2e/E2E_QUICK_START.md

Example of how to run E2E tests within a GitHub Actions workflow.

```yaml
# GitHub Actions example
- name: Run E2E tests
  run: |
    cd frontend
    pnpm test:e2e
```

--------------------------------

### Virtual Machine Deployment - Extract and Run

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Steps to extract the AxonHub release archive and navigate into the extracted directory for VM deployment.

```bash
# Extract and run
unzip axonhub_*.zip
cd axonhub_*
```

--------------------------------

### Background Tasks with System Principal and Bypass

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/authz-coding-guidelines.md

Illustrates the correct approach for background tasks, requiring explicit System principal declaration and controlled bypass.

```go
// Before (direct bypass, no principal declaration)
ctx = ent.NewContext(ctx, svc.db)
ctx = privacy.DecisionContext(ctx, privacy.Allow)

// After (explicit System principal + controlled bypass)
ctx = ent.NewContext(ctx, svc.db)
ctx = authz.NewSystemContext(ctx)
ctx = authz.WithBypassPrivacy(ctx, "provider-quota-check")
```

--------------------------------

### Running AxonHub Load Balance Tests

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/openai/chat/load_balance/README.md

Commands to execute all load balance integration tests using 'make' or 'go test'. Includes options for verbose output and setting a timeout.

```bash
# Run all load balance tests
make test

# Or use go test directly
go test -v ./...

# Run with timeout
go test -v -timeout 5m ./...
```

--------------------------------

### Python Example for Jina Endpoint Rerank API

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/rerank-api.md

This Python script shows how to use the Jina-specific rerank endpoint. It's similar to the general rerank API but targets the /jina/v1/rerank path. The example includes setting `return_documents` to True and prints the reranked results.

```python
import requests

# Jina-specific rerank request
response = requests.post(
    "http://localhost:8090/jina/v1/rerank",
    headers={
        "Authorization": "Bearer your-axonhub-api-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "jina-reranker-v1-base-en",
        "query": "What are the benefits of renewable energy?",
        "documents": [
            "Solar power generates electricity from sunlight.",
            "Coal mining provides jobs but harms the environment.",
            "Wind turbines convert wind energy into electricity.",
            "Fossil fuels are non-renewable and contribute to climate change."
        ],
        "top_n": 3,
        "return_documents": True
    }
)

result = response.json()
print("Reranked documents:")
for i, item in enumerate(result["results"]):
    print(f"{i+1}. Score: {item['relevance_score']:.3f}")
    print(f"   Text: {item['document']['text']}")
```

--------------------------------

### Initialize Adaptive Load Balancer

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/openai/chat/load_balance/README.md

Create a new load balancer using the default adaptive strategy, which considers trace awareness, error rates, round-robin, and latency. This strategy is dynamic and aims for optimal distribution.

```go
adaptiveLoadBalancer := NewLoadBalancer(systemService,
    NewTraceAwareStrategy(requestService),
    NewErrorAwareStrategy(channelService),
    NewWeightRoundRobinStrategy(channelService),
    NewLatencyAwareStrategy(channelService),
    NewRateLimitAwareStrategy(rateLimitTracker, connectionTracker),
)
```

--------------------------------

### 500 Internal Server Error Response

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Example of an error response for a server-side issue.

```json
{
  "error": {
    "message": "Internal server error",
    "type": "internal_error",
    "code": "internal_error"
  }
}
```

--------------------------------

### Running Go Tests for Context Management

Source: https://github.com/looplj/axonhub/blob/unstable/internal/contexts/README.md

Commands to execute tests for context, business logic, and middleware components.

```bash
go test ./internal/contexts/
go test ./internal/server/biz/thread_test.go ./internal/server/biz/thread.go
go test ./internal/server/biz/trace_test.go ./internal/server/biz/trace.go
go test ./internal/server/middleware/thread_test.go ./internal/server/middleware/thread.go
go test ./internal/server/middleware/trace_test.go ./internal/server/middleware/trace.go
```

--------------------------------

### Create Dumper Instance in Go

Source: https://github.com/looplj/axonhub/blob/unstable/internal/dumper/README.md

Instantiate a dumper by first creating a logger, then defining the dumper configuration, and finally calling `dumper.New`.

```go
// Create a logger
logger := log.New(log.Config{
    Level: 0, // Debug level
})

// Create dumper config
config := dumper.Config{
    Enabled:    true,
    DumpPath:   "./dumps",
    MaxSize:    100,
    MaxAge:     24 * time.Hour,
    MaxBackups: 10,
}

// Create a dumper
dumper := dumper.New(config, logger)
```

--------------------------------

### 401 Unauthorized Error Response

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Example of an error response when an invalid API key is provided.

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

--------------------------------

### Include All Extended Fields Example

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Request all extended metadata for models using the `include=all` parameter.

```bash
curl -s "http://localhost:8090/v1/models?include=all" \
  -H "Authorization: Bearer your-api-key" | jq
```

--------------------------------

### Extract and Run AxonHub from Archive

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Instructions for extracting the AxonHub application from a zip archive and running it. Includes steps for adding execution permissions and managing the service.

```bash
# Extract the downloaded file
unzip axonhub_*.zip
cd axonhub_*

# Add execution permissions (only for Linux/macOS)
chmod +x axonhub

# Run directly - default SQLite database

# Install AxonHub to system
sudo ./install.sh

# Start AxonHub service
./start.sh

# Stop AxonHub service
./stop.sh
```

--------------------------------

### Build AxonHub Frontend Only

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/development.md

Builds the frontend application for AxonHub. This command should be run from the 'frontend' directory.

```bash
cd frontend
pnpm build
```

--------------------------------

### List Available Models (GET /anthropic/v1/models)

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/anthropic-api.md

Retrieves a list of all models available through the Anthropic API via AxonHub.

```APIDOC
## GET /anthropic/v1/models

### Description
Lists all the AI models that are currently available to be used through the Anthropic API via AxonHub. This includes models from various providers that AxonHub supports.

### Method
GET

### Endpoint
`/anthropic/v1/models`

### Parameters
None

### Response
#### Success Response (200)
- **data** (array) - A list of available model objects.
  - **id** (string) - The unique identifier for the model.
  - **type** (string) - The type of the model (e.g., "model").

#### Response Example
```json
{
  "data": [
    {
      "id": "claude-3-opus-20240229",
      "type": "model"
    },
    {
      "id": "gpt-4o",
      "type": "model"
    },
    {
      "id": "gemini-2.5",
      "type": "model"
    }
  ]
}
```
```

--------------------------------

### Run Migration Test with PostgreSQL

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/migration/MIGRATION_TEST.md

Execute the migration test script using PostgreSQL. Requires Docker to be installed and running.

```bash
./scripts/migration/migration-test.sh v0.1.0 --db-type postgres
```

--------------------------------

### Principal Types and Context Creation

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/authz-coding-guidelines.md

Defines principal types and demonstrates how to create contexts for System, User, and API Key principals.

```go
// Principal types
PrincipalTypeSystem  // System principal (background tasks)
PrincipalTypeUser    // User principal
PrincipalTypeAPIKey  // API Key principal

// Create principal context
ctx = authz.NewSystemContext(ctx)           // System principal
ctx = authz.NewUserContext(ctx, userID)     // User principal
ctx = authz.NewAPIKeyContext(ctx, apiKeyID, projectID) // API Key principal
```

--------------------------------

### Logging Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Set up logging parameters such as logger name, debug level, log format (JSON, console), and output destination (file, stdio).

```yaml
log:
  name: "axonhub"               # Logger name
  debug: false                  # Enable debug logging
  level: "info"                 # debug, info, warn, error, panic, fatal
  level_key: "level"            # Key name for log level field
  time_key: "time"              # Key name for timestamp field
  caller_key: "label"           # Key name for caller info field
  function_key: ""              # Key name for function field
  name_key: "logger"            # Key name for logger name field
  encoding: "json"              # json, console, console_json
  includes: []                  # Logger names to include
  excludes: []                  # Logger names to exclude
  output: "stdio"               # file or stdio
  file:                         # File-based logging
    path: "logs/axonhub.log"   # Log file path
    max_size: 100               # Max size in MB before rotation
    max_age: 30                 # Max age in days to retain
    max_backups: 10             # Max number of old log files
    local_time: true            # Use local time for rotated files
```

--------------------------------

### Enable AxonHub Tracing Plugin

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/guides/opencode-integration.md

Add the opencode-axonhub-tracing plugin to your opencode.json configuration file. OpenCode will automatically install it when needed.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-axonhub-tracing"]
}
```

--------------------------------

### TiDB Database Connection String

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/configuration.md

Example connection string for a TiDB database, including TLS and character set configuration.

```text
<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4
```

--------------------------------

### Recommended RunWithBypass Closure Pattern

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/authz-coding-guidelines.md

Illustrates the recommended closure pattern for RunWithBypass, ensuring bypass only covers necessary queries.

```go
// Bypass only covers necessary queries
count, err := authz.RunWithBypass(ctx, "quota-request-count", func(ctx context.Context) (int, error) {
    return client.Request.Query().Where(...).Count(ctx)
})
```

--------------------------------

### Extract and Run AxonHub Binary

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/getting-started/quick-start.md

Download the latest AxonHub release binary, extract it, make it executable, and then run the application.

```bash
unzip axonhub_*.zip
cd axonhub_*
chmod +x axonhub
./axonhub
```

--------------------------------

### Network Security Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/deployment/docker.md

Example Docker Compose configuration to enhance network security by binding the AxonHub service to localhost only.

```yaml
axonhub:
  networks:
    - axonhub_network
  ports:
    - "127.0.0.1:8090:8090"  # Bind to localhost only

networks:
  axonhub_network:
    driver: bridge
```

--------------------------------

### Initialize Weighted Load Balancer

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/openai/chat/load_balance/README.md

Create a new load balancer using a weighted strategy. This is suitable when channels have predefined weights.

```go
weightedLoadBalancer := NewLoadBalancer(systemService, NewWeightStrategy())
```

--------------------------------

### Manually Stop and Start Backend

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/e2e/E2E_QUICK_START.md

Manually control the E2E backend service. Use this for troubleshooting or specific workflow needs.

```bash
../../scripts/e2e-backend.sh stop
../../scripts/e2e-backend.sh start
```

--------------------------------

### GET /v1/models

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/openai-api.md

Lists available models with optional extended metadata. Supports filtering via the 'include' query parameter.

```APIDOC
## GET /v1/models

### Description
Lists available models with optional extended metadata. Supports filtering via the 'include' query parameter.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of fields to include, or "all" for all extended fields
```

--------------------------------

### Create Gemini Client with AxonHub

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/api-reference/gemini-api.md

Initialize the Gemini client configured to use AxonHub. Specify your AxonHub API key and the AxonHub base URL. This setup allows you to interact with various models through the Gemini API format.

```go
import (
    "context"
    "google.golang.org/genai"
)

// Create Gemini client with AxonHub configuration
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
    APIKey:  "your-axonhub-api-key",
    Backend: genai.Backend(genai.APIBackendUnspecified), // Use default backend
    HTTPOptions: genai.HTTPOptions{
		BaseURL: "http://localhost:8090/gemini",
	},
})
if err != nil {
    // Handle error appropriately
    panic(err)
}
```

--------------------------------

### Streaming Flow Overview

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/transformation-flow.md

Details the process for handling streaming requests, emphasizing the setup, continuous data flow, and completion stages.

```text
Client → Stream Request → AxonHub → Provider Stream
Provider Chunks → AxonHub Processing → Client Chunks
Provider End → AxonHub Cleanup → Client Completion
```

--------------------------------

### Test AxonHub Health Endpoint

Source: https://github.com/looplj/axonhub/blob/unstable/deploy/helm/README.md

Tests the AxonHub health endpoint by sending an HTTP GET request to the locally forwarded port.

```bash
curl http://localhost:8090/health
```

--------------------------------

### Run prek Hooks on All Files

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/development/git-workflow.md

Execute all configured prek hooks against every file in the repository.

```bash
prek run --all-files
```

--------------------------------

### Check PostgreSQL Database Tables and Data

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/e2e/E2E_QUICK_START.md

Interact with a PostgreSQL E2E database, typically running in Docker. Requires Docker to be installed and running.

```bash
docker exec axonhub-e2e-postgres psql -U axonhub -d axonhub_e2e -c "\dt; SELECT * FROM users;"
```

--------------------------------

### Check MySQL Database Tables and Data

Source: https://github.com/looplj/axonhub/blob/unstable/scripts/e2e/E2E_QUICK_START.md

Interact with a MySQL E2E database, typically running in Docker. Requires Docker to be installed and running.

```bash
docker exec axonhub-e2e-mysql mysql -u axonhub -p axonhub_e2e -e "SHOW TABLES; SELECT * FROM users;"
```

--------------------------------

### Standard Test Flow Steps

Source: https://github.com/looplj/axonhub/blob/unstable/integration_test/openai/chat/load_balance/TESTING_GUIDE.md

Outlines the sequence of actions for a standard load balancing test, from helper creation to response verification.

```text
1. Create TestHelper with unique trace ID
2. Make first request (establishes channel preference)
3. Wait for metrics to be recorded (100ms)
4. Make subsequent requests (should use same channel)
5. Verify responses and consistency
```

--------------------------------

### Create System Principal Context

Source: https://github.com/looplj/axonhub/blob/unstable/internal/authz/README.md

Use this to create a context with a System principal, typically for background tasks or internal operations. This is the initial step before performing operations that require system-level authorization.

```go
ctx = authz.NewSystemContext(ctx)
```

--------------------------------

### Logto (Self-Hosted) OIDC Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/docs/en/guides/oidc.md

Example configuration for integrating with a self-hosted Logto instance. Ensure correct Redirect URI is set in Logto.

```yaml
oidc:
  providers:
    - id: "logto"
      name: "logto"
      display_name: "Logto SSO"
      issuer_url: "https://your-logto-domain.com/oidc"
      client_id: "<App ID>"
      client_secret: "<App Secret>"
      enable_pkce: true
      jit_enabled: true
      button_color: "#5C5CFF"
```

--------------------------------

### AxonHub Environment Variables Configuration

Source: https://github.com/looplj/axonhub/blob/unstable/README.md

Example of environment variables used to override AxonHub configuration. These variables correspond to settings in the YAML file.

```bash
AXONHUB_SERVER_PORT=8090
AXONHUB_DB_DIALECT="tidb"
AXONHUB_DB_DSN="<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4"
AXONHUB_LOG_LEVEL=info
```