Documentation Index
Fetch the complete documentation index at: https://www.getmaxim.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
Plugin Overview
Bifrost plugins provide middleware functionality:
- Request/response processing and modification
- Authentication and authorization controls
- Rate limiting and traffic shaping
- Monitoring and metrics collection
- Custom business logic injection
Current Plugin Loading (Command-line)
Go Binary:
bifrost-http -config config.json -plugins "maxim,custom-plugin"
docker run -p 8080:8080 \
-v $(pwd)/config.json:/app/config/config.json \
-e OPENAI_API_KEY \
-e APP_PLUGINS=maxim,custom-plugin \
maximhq/bifrost
Available Plugins
Maxim Logger Plugin
Official logging and analytics plugin:
# Environment variables required
export MAXIM_API_KEY="your-maxim-api-key"
export MAXIM_LOG_REPO_ID="your-repo-id"
# Start with Maxim plugin
bifrost-http -config config.json -plugins "maxim"
- Request/response logging to Maxim platform
- Performance analytics and insights
- Error tracking and debugging
- Usage pattern analysis
Prometheus Metrics Plugin
Built-in metrics collection (always loaded):
# Access metrics
curl http://localhost:8080/metrics
- Request count and latency
- Provider performance
- Error rates and types
- Resource utilization
Custom Plugin Development
Plugin Interface
Plugins implement the schemas.Plugin interface:
type Plugin interface {
Name() string
ProcessRequest(ctx BifrostContext, req *BifrostRequest) (*BifrostRequest, *BifrostError)
ProcessResponse(ctx BifrostContext, req *BifrostRequest, resp *BifrostResponse) (*BifrostResponse, *BifrostError)
}
Example Plugin Structure
package myplugin
import (
"github.com/maximhq/bifrost/core/schemas"
)
type MyPlugin struct {
config MyPluginConfig
}
func NewMyPlugin(config MyPluginConfig) *MyPlugin {
return &MyPlugin{config: config}
}
func (p *MyPlugin) Name() string {
return "my-plugin"
}
func (p *MyPlugin) ProcessRequest(
ctx schemas.BifrostContext,
req *schemas.BifrostRequest,
) (*schemas.BifrostRequest, *schemas.BifrostError) {
// Process incoming request
// Add headers, validate, modify, etc.
return req, nil
}
func (p *MyPlugin) ProcessResponse(
ctx schemas.BifrostContext,
req *schemas.BifrostRequest,
resp *schemas.BifrostResponse,
) (*schemas.BifrostResponse, *schemas.BifrostError) {
// Process outgoing response
// Log, transform, add metadata, etc.
return resp, nil
}
Plugin Use Cases
Authentication Plugin
func (p *AuthPlugin) ProcessRequest(
ctx schemas.BifrostContext,
req *schemas.BifrostRequest,
) (*schemas.BifrostRequest, *schemas.BifrostError) {
// Extract API key from headers
apiKey := ctx.GetHeader("X-API-Key")
// Validate against database/service
if !p.validateAPIKey(apiKey) {
return nil, &schemas.BifrostError{
Message: "Invalid API key",
StatusCode: &[]int{401}[0],
}
}
return req, nil
}
Rate Limiting Plugin
func (p *RateLimitPlugin) ProcessRequest(
ctx schemas.BifrostContext,
req *schemas.BifrostRequest,
) (*schemas.BifrostRequest, *schemas.BifrostError) {
clientIP := ctx.GetClientIP()
if !p.limiter.Allow(clientIP) {
return nil, &schemas.BifrostError{
Message: "Rate limit exceeded",
StatusCode: &[]int{429}[0],
}
}
return req, nil
}
func (p *TransformPlugin) ProcessRequest(
ctx schemas.BifrostContext,
req *schemas.BifrostRequest,
) (*schemas.BifrostRequest, *schemas.BifrostError) {
// Add organization context to messages
if req.Input.ChatCompletionInput != nil {
messages := *req.Input.ChatCompletionInput
// Add system message with org context
orgContext := schemas.BifrostMessage{
Role: "system",
Content: schemas.MessageContent{
Text: p.getOrganizationContext(ctx),
},
}
messages = append([]schemas.BifrostMessage{orgContext}, messages...)
req.Input.ChatCompletionInput = &messages
}
return req, nil
}
Future JSON Configuration
Planned configuration format (under development):
{
"providers": {
"openai": {
"keys": [
{
"value": "env.OPENAI_API_KEY",
"models": ["gpt-4o-mini"],
"weight": 1.0
}
]
}
},
"plugins": [
{
"name": "maxim",
"source": "../../plugins/maxim",
"type": "local",
"config": {
"api_key": "env.MAXIM_API_KEY",
"log_repo_id": "env.MAXIM_LOG_REPO_ID"
}
},
{
"name": "mocker",
"source": "../../plugins/mocker",
"type": "local",
"config": {
"enabled": true,
"default_behavior": "passthrough",
"rules": [
{
"name": "test-mock",
"enabled": true,
"priority": 1,
"probability": 1,
"conditions": {
"providers": ["openai"]
},
"responses": [
{
"type": "success",
"weight": 1.0,
"content": {
"message": "This is a mock response for testing"
}
}
]
}
]
}
}
]
}
Testing Custom Plugins
Unit Testing
func TestMyPlugin(t *testing.T) {
plugin := NewMyPlugin(MyPluginConfig{})
ctx := &schemas.BifrostContext{}
req := &schemas.BifrostRequest{
Provider: "openai",
Model: "gpt-4o-mini",
}
processedReq, err := plugin.ProcessRequest(ctx, req)
assert.Nil(t, err)
assert.NotNil(t, processedReq)
// Add your assertions
}
Integration Testing
# Build plugin
go build -buildmode=plugin -o myplugin.so ./plugins/myplugin
# Test with HTTP transport
bifrost-http -config config.json -plugins "myplugin"
# Send test request
curl -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "X-Test-Header: test-value" \
-d '{
"provider": "openai",
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "test"}]
}'
Plugin Execution Order
Plugins execute in loading order:
# This order: auth -> rate-limit -> maxim -> request
bifrost-http -plugins "auth,rate-limit,maxim"
auth.ProcessRequest()rate-limit.ProcessRequest()maxim.ProcessRequest()- Provider request
maxim.ProcessResponse()rate-limit.ProcessResponse()auth.ProcessResponse()
Architecture: For plugin system design and performance details, see Architecture Documentation.
Development: Full plugin development guide and examples available in Go Package Plugins.
