FTMahringer/Synapse
1
0
Fork 0
Code Issues 35 Pull requests Projects Releases 152 Packages Wiki Activity Actions
152 releases 174 tags
  • v1.3.0 1c3ac0439e

    Release Notes: SYNAPSE v1.3.0 Stable

    github-actions[bot] released this 2026-05-08 22:39:53 +02:00 | 265 commits to main since this release

    Release Notes: SYNAPSE v1.3.0

    Release Date: May 8, 2026
    Milestone: Model Providers

    Overview

    SYNAPSE v1.3.0 introduces comprehensive model provider infrastructure, enabling the system to integrate with multiple AI model providers including Ollama (local), OpenAI, Anthropic, and OpenAI-compatible services. This release includes provider configuration management, API key encryption, chat completion endpoints, usage tracking, and testing capabilities.

    What's New

    Model Provider Configuration

    Provider Management

    • Configure multiple model providers through REST API
    • Supported provider types: OLLAMA, OPENAI, ANTHROPIC, OPENAI_COMPATIBLE
    • Provider-specific configuration stored in flexible JSONB format
    • Enable/disable providers without deletion
    • RESTful CRUD operations for provider management

    Secret Encryption

    • API keys encrypted at rest using AES-256-GCM
    • Encrypted secrets never exposed in API responses
    • Decryption only occurs when making provider API calls
    • Constant-time operations to prevent timing attacks

    Provider Integrations

    Ollama Provider (Local Models)

    Endpoints:

    • GET /api/providers/ollama/{id}/health - Check Ollama connectivity
    • GET /api/providers/ollama/{id}/models - List available models
    • POST /api/providers/ollama/{id}/chat - Chat completions

    Features:

    • Local model execution (no API key required)
    • Configurable base URL (default: http://localhost:11434)
    • Support for temperature, top_p, top_k, num_predict parameters
    • Token counting: prompt_eval_count, eval_count
    • Performance metrics: total_duration, load_duration, eval_duration

    OpenAI Provider (GPT Models)

    Endpoints:

    • GET /api/providers/openai/{id}/health - Check API connectivity
    • GET /api/providers/openai/{id}/models - List available models
    • POST /api/providers/openai/{id}/chat - Chat completions

    Features:

    • OpenAI API key authentication (Bearer token)
    • Compatible with OpenAI-compatible providers (OpenRouter, Azure OpenAI, etc.)
    • Configurable base URL (default: https://api.openai.com)
    • Support for temperature, max_tokens, top_p, frequency_penalty, presence_penalty
    • Token usage tracking: prompt_tokens, completion_tokens, total_tokens
    • Response metadata: finish_reason, response ID

    Anthropic Provider (Claude Models)

    Endpoints:

    • GET /api/providers/anthropic/{id}/health - Check API connectivity
    • POST /api/providers/anthropic/{id}/chat - Chat completions

    Features:

    • Anthropic API key authentication (x-api-key header)
    • Anthropic API version: 2023-06-01
    • Support for temperature, top_p, top_k, max_tokens
    • Content blocks in responses (type: text)
    • Token usage tracking: input_tokens, output_tokens
    • Stop reason tracking: end_turn, max_tokens, stop_sequence

    Usage Tracking and Analytics

    Provider Usage Logs

    • Automatic logging of all provider API calls
    • Track prompt tokens, completion tokens, total tokens
    • Track latency (milliseconds) for each request
    • Track success/failure status with error messages
    • Error logs sanitized (no secrets or sensitive content)

    Analytics Queries

    • Average latency per provider
    • Total token consumption per provider
    • Failure count and success rate calculations
    • Historical usage data for cost estimation

    Provider Testing

    Test Endpoint: POST /api/providers/test

    Features:

    • Unified testing for all provider types
    • Test with custom prompts and parameters
    • storePrompt flag (default: false) for privacy
    • Response preview (first 200 characters)
    • Success/failure status with error details
    • Latency and token usage metrics
    • Provider-specific metadata in responses

    API Examples

    Create Ollama Provider

    POST /api/providers
{
  "name": "Local Ollama",
  "type": "OLLAMA",
  "enabled": true,
  "config": {
    "baseUrl": "http://localhost:11434"
  }
}

    Create OpenAI Provider

    POST /api/providers
{
  "name": "OpenAI GPT",
  "type": "OPENAI",
  "enabled": true,
  "secrets": {
    "apiKey": "sk-..."
  }
}

    Create Anthropic Provider

    POST /api/providers
{
  "name": "Claude",
  "type": "ANTHROPIC",
  "enabled": true,
  "secrets": {
    "apiKey": "sk-ant-..."
  }
}

    Test Provider

    POST /api/providers/test
{
  "providerId": "uuid-here",
  "model": "llama3.2",
  "messages": [
    {"role": "user", "content": "Hello, world!"}
  ],
  "temperature": 0.7,
  "maxTokens": 100,
  "storePrompt": false
}

    Chat Completion (Ollama)

    POST /api/providers/ollama/{id}/chat
{
  "model": "llama3.2",
  "messages": [
    {"role": "user", "content": "Explain quantum computing"}
  ],
  "stream": false,
  "options": {
    "temperature": 0.7,
    "num_predict": 500
  }
}

    Configuration

    Required Configuration

    Application Properties:

    secrets:
  # MUST be changed in production - exactly 32 bytes for AES-256
  encryption-key: "CHANGE_ME_32_BYTE_KEY_FOR_PRODUCTION__"

    Provider Configuration

    Ollama:

    OpenAI / OpenAI-Compatible:

    • Store apiKey in provider secrets (encrypted)
    • Configure baseUrl in provider config for compatible providers (default: https://api.openai.com)

    Anthropic:

    Security Notes

    API Key Encryption

    • All API keys encrypted with AES-256-GCM before storage
    • Encryption key MUST be changed from default in production
    • Encrypted secrets never returned in API responses
    • Decryption occurs only when calling provider APIs

    Error Logging

    • Failed requests logged without exposing API keys
    • Error messages sanitized to exclude sensitive content
    • Test endpoint respects storePrompt flag for privacy
    • Usage logs track metadata without storing prompt content (by default)

    Transport Security

    • Use HTTPS in production for all provider API calls
    • API keys transmitted only in encrypted channels
    • Provider secrets encrypted at rest in database

    Migration Guide

    From v1.2.0 to v1.3.0

    Database Changes:

    1. New table: model_providers (provider configuration)
    2. New table: provider_usage_logs (usage tracking)

    Configuration Changes:

    1. Add secrets.encryption-key to application.yml (32-byte key for AES-256)

    API Changes:

    • New endpoint group: /api/providers/**
    • New endpoint: POST /api/providers/test
    • Provider-specific endpoints: /api/providers/{ollama|openai|anthropic}/{id}/**

    Setting Up Providers

    1. Create Provider via POST /api/providers
    2. Test Connectivity via GET /api/providers/{type}/{id}/health
    3. List Models (if applicable) via GET /api/providers/{type}/{id}/models
    4. Test Completion via POST /api/providers/test

    Known Limitations

    1. No Streaming Support: All chat completions are synchronous (stream: false)
    2. No Cost Calculation: Token usage tracked, but cost not calculated automatically
    3. No Retry Logic: Failed requests do not retry automatically
    4. No Fallback Providers: System does not fall back to alternative providers on failure
    5. No Rate Limiting: Provider API calls not rate-limited on client side

    Future Enhancements

    • Streaming chat completions support
    • Automatic cost calculation from token usage + pricing tables
    • Retry logic with exponential backoff
    • Fallback provider chains for reliability
    • Client-side rate limiting and quotas
    • Provider health monitoring and alerting
    • Token usage dashboards and reporting

    Exit Criteria ✅

    • ✅ Ollama can produce responses locally
    • ✅ External API-key providers (OpenAI, Anthropic) can be configured
    • ✅ Failed provider calls logged without exposing secrets
    • ✅ ECHO not used automatically when providers fail

    Technical Details

    Encryption:

    • Algorithm: AES-256-GCM
    • Key size: 32 bytes (256 bits)
    • IV: 12 bytes (random per encryption)
    • Tag: 128 bits
    • Format: Base64(IV + ciphertext)

    Provider Services:

    • OllamaProviderService: Ollama API integration
    • OpenAIProviderService: OpenAI and compatible APIs
    • AnthropicProviderService: Anthropic Messages API
    • ProviderTestService: Unified testing service

    HTTP Client:

    • Spring RestClient for all provider API calls
    • Synchronous request/response model
    • JSON serialization via Jackson

    Token Tracking:

    • Ollama: prompt_eval_count, eval_count
    • OpenAI: prompt_tokens, completion_tokens, total_tokens
    • Anthropic: input_tokens, output_tokens

    Contributors

    For detailed implementation notes, see CHANGELOG.md entry for v1.3.0.

    Downloads