Bifrost v1.2 Release

[Pratham-Mishra04]

We’re excited to announce the release of v1.2 for Transports! 🎉

You’ll find the full release notes attached below. As always, we’d love your feedback, feel free to share any questions or suggestions.

Release Notes: Bifrost Transports v1.2.0

Release Date: 28 August, 2025

Previous Version: v1.1.24

This release represents a significant architectural transformation of Bifrost, focusing on extensibility, modularity, and developer experience. We've decoupled core components, introduced a unified framework package, and completely revamped the configuration system.

---

🏗️ Architectural Changes

New Framework Package

• Introduced shared framework package with unified interfaces for:
  • configstore - Configuration storage abstraction
  • vectorstore - Vector database operations for semantic features
  • logstore - Request logging and tracing storage
• Enables extensibility - easily swap SQLite for PostgreSQL, MySQL, or other storage backends
• Consistent API across all storage operations throughout the system

Plugin Decoupling & Go SDK Compatibility

Previously, plugins like telemetry, logging, and governance were tightly coupled to Bifrost Transports due to direct SQLite dependencies.

What's Changed:

• ✅ All plugins now depend on framework interfaces instead of concrete implementations
• ✅ Plugins can now be used directly in Go SDK applications by configuring storage interfaces
• ✅ Better testing and development with mock implementations of storage interfaces
• ✅ Simplified plugin architecture with cleaner dependency management

Benefits:

• Use governance, telemetry, and logging plugins in your Go applications
• Easier unit testing with interface mocking
• Plugin portability across different deployment scenarios

---

⚙️ Configuration System Transformation

Config Store Introduction

Bifrost v1.2.0 introduces the configstore module as the central interface for configuration management, fundamentally changing how Bifrost handles configuration data and storage.

How It Works Now

The system now operates with two distinct behavioral modes based on the presence and content of config.json:

Mode 1: Database-First (No config.json)

# app-dir/ (no config.json present)
├── config.db    # Auto-created by configstore
├── logs.db      # Auto-created by configstore

• configstore automatically creates and manages SQLite databases
• Web UI fully enabled with real-time configuration changes
• All configuration stored and retrieved through configstore APIs
• Zero configuration required - works out of the box

Mode 2: File-Based (config.json exists)

Without configstore definition:

{
  "providers": {...},
  "client": {...}
  // No "config_store" or "logs_store" defined
}

• Configuration loaded into memory only from config.json
• configstore is bypassed - no database operations
• Web UI disabled (read-only mode)
• Changes require restart, no persistence beyond memory

With configstore definition:

{
  "providers": {...},
  "client": {...},
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {"path": "./config.db"}
  },
  "logs_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {"path": "./logs.db"}
  }
}

Bootstrap Process:

1. configstore checks if database exists and has data
2. If empty database: Loads config.json into configstore, then switches to database mode
3. If existing database: Ignores config.json entirely, uses database
4. Post-bootstrap: All operations go through configstore APIs, config.json becomes inactive

The configstore API Layer

The configstore module now serves as the unified interface between:

• Bifrost core components
• Storage backends (SQLite, future PostgreSQL/MySQL)
• Configuration sources (file, database, API)

Key Behavioral Changes:

• Centralized access: All components use configstore APIs instead of direct file reads
• Dynamic updates: Real-time configuration changes without restarts (when database mode active)
• Validation layer: Stricter validation through configstore before applying changes
• Storage abstraction: Same API regardless of underlying storage (SQLite, future databases)

📚 Learn More: Configuration Modes Guide

---

🎯 Semantic Caching Refactor

Complete rewrite of the semantic caching system with true semantic similarity.

What's New:

• ✅ True semantic caching using vector embeddings instead of hash-based caching
• ✅ Intelligent similarity matching - cache hits for semantically similar requests
• ✅ Vector store integration using the new framework/vectorstore interfaces
• ✅ Weaviate support for production-scale vector operations
• ✅ Configurable similarity thresholds and TTL per request
• ✅ Dual-layer caching - exact hash matching + semantic similarity

What's Removed:

• ❌ Redis support completely removed

Example Benefits:

• Cache "How do I reset my password?" and get hits for "I forgot my password, what should I do?"
• Reduce API costs by 60-80% for customer support and FAQ scenarios
• Sub-millisecond cache retrieval vs multi-second API calls

📚 Learn More: Semantic Caching Guide

---

🔧 Custom Providers Support

Introducing Custom Providers - create specialized provider instances with restricted capabilities.

Features:

• ✅ Base provider customization - extend existing providers (OpenAI, Anthropic, etc.)
• ✅ Operation restrictions - limit which endpoints/operations are available
• ✅ Multiple instances - create several configurations of the same base provider
• ✅ Custom naming - brand providers for specific use cases or teams

Use Cases:

• Create "GPT-4 Limited" with only chat completions (no embeddings)
• Set up team-specific provider instances with different rate limits
• Offer customers branded provider access with controlled capabilities

---

📚 Documentation Overhaul

Complete documentation refresh now hosted at https://docs.getbifrost.ai

What's New:

• ✅ Comprehensive API reference with interactive examples
• ✅ Step-by-step setup guides for all deployment scenarios
• ✅ Architecture deep dives explaining internal systems
• ✅ Best practices guides for production deployments
• ✅ Enterprise Offerings featuring advanced capabilities for large-scale deployments

---

⚠️ Important Changes

1. Configuration System Behavioral Changes

Affected Users: Anyone with existing config.json in their app-dir

Impact:

• Existing config.json will be loaded into memory mode (Web UI disabled) unless you add config_store
• Database configurations will not be automatically created

To Maintain Current Functionality:
Add config_store and logs_store to your existing config.json pointing to your current database:

{
  // Your existing configuration...
  "providers": {...},
  "client": {...},

  // Add these to point to your existing databases
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"  // Point to your existing database
    }
  },
  "logs_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./logs.db"    // Point to your existing database
    }
  }
}

⚠️ Important Note: Once you add config_store, the system will use your existing database and future config.json updates will be ignored. All configuration changes must be made through the Web UI or API.

Alternative Options:

# Option 1: Remove config.json to use database mode (recommended for new setups)
rm /path/to/app-dir/config.json

# Option 2: Keep config.json without config_store (memory-only mode, Web UI disabled)
# No changes needed - everything works as before but Web UI is read-only

2. Breaking Change: Semantic Caching - Redis Removal

Affected Users: Anyone using Redis-based semantic caching

Impact:

• All Redis hash caching configurations will stop working
• Plugin configurations using Redis need to be updated

Migration Required:

• Set up Weaviate vector store
• Update plugin configuration to use new semantic caching
• Reconfigure cache keys and similarity thresholds

📚 Migration Guide: Semantic Caching Configuration

---

📦 Installation & Upgrade

New Installation

# NPX
npx -y @maximhq/bifrost

# Docker
docker pull maximhq/bifrost:1.2.0
docker run -p 8080:8080 maximhq/bifrost:1.2.0

Upgrading from v1.1.24

1. Backup your data (recommended):

   cp -r /path/to/app-dir /path/to/app-dir.backup

2. Check for config.json in your app-dir:

   ls /path/to/app-dir/config.json

3. If config.json exists:

   • To keep everything working as before: Add config_store and logs_store entries pointing to your existing databases (see configuration section above)
   • For new setups: Consider removing config.json to use the new database-first mode
   • For GitOps workflows: Keep config.json without config_store for memory-only mode
   • Review the configuration migration guide for detailed options

4. If using Redis semantic caching:

   • Set up Weaviate vector store
   • Update plugin configuration
   • Test cache behavior with new semantic matching

5. Update Bifrost:

   # NPX updates automatically
   npx -y @maximhq/bifrost
   
   # Docker
   docker pull maximhq/bifrost:1.2.0

6. Switch back if anything is not working as expected:
   You can always switch back to the previous version by using the following commands:

   # NPX
   npx @maximhq/bifrost --transport-version v1.1.14
   
   # Docker
   docker pull maximhq/bifrost:v1.1.24

---

🙏 Acknowledgments

This release represents weeks of architectural improvements and community feedback. Special thanks to our early adopters who tested the prerelease versions and provided invaluable feedback.

Built with ❤️ by the Maxim