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

    v1.4.1-dev - Agent runtime registry Pre-release

    FTMahringer released this 2026-05-09 00:01:20 +02:00 | 252 commits to main since this release

    Agent Runtime Registry

    First step toward agent orchestration. Tracks agent activation states.

    Features:

    • AgentActivationState enum (ACTIVE, PAUSED, DISABLED)
    • AgentRuntimeRegistry entity with timestamps
    • AgentRuntimeService for state management
    • Migration V4 with indexed table

    Next: v1.4.2-dev Main Agent router service

    Downloads
  • v1.4.0 8cbc32501d

    v1.4.0 - Chat Runtime Stable

    FTMahringer released this 2026-05-09 00:00:10 +02:00 | 253 commits to main since this release

    v1.4.0 - Chat Runtime

    Release Date: 2026-05-08
    Milestone: Chat Runtime Backend

    Overview

    Implements complete chat runtime for the Main Agent with conversation management, message persistence, model provider integration, and comprehensive API endpoints.

    Features

    Conversation Management

    • Create Conversations: REST API to start new chat sessions with agents
    • List Conversations: Query conversations by user with pagination
    • Get Conversation Details: Retrieve full conversation history with messages
    • Conversation Status: Track ACTIVE/CLOSED status for conversations

    Message Handling

    • Send Messages: POST user messages to conversations
    • Message Persistence: All messages saved with full metadata
    • Conversation History: Messages loaded in chronological order for context

    Main Agent Integration

    • Prompt Assembly: Loads Main Agent identity files (system-prompt, identity, soul, connections)
    • Model Provider Integration: Routes messages through configured Ollama provider
    • Context Building: Assembles system prompt + conversation history for each request
    • Response Persistence: Saves assistant responses with full metadata

    Response Metadata Tracking

    • Provider Tracking: Links each response to model provider used
    • Model Name: Records specific model (e.g., llama3.2)
    • Latency Tracking: Measures response time in milliseconds
    • Token Breakdown: Tracks prompt_tokens and completion_tokens separately
    • Analytics Ready: Database schema supports future usage analytics

    Error Handling

    • Provider Errors: Catches model provider failures gracefully
    • Timeout Handling: Detects and reports request timeouts
    • Error Messages: Saves error states as assistant messages with ⚠️ prefix
    • Exception Types: ModelProviderException, RequestTimeoutException

    REST API

    • POST /api/conversations - Create new conversation
    • GET /api/conversations - List user conversations
    • GET /api/conversations/{id} - Get conversation with messages
    • POST /api/conversations/{id}/messages - Send message and get response

    Technical Details

    Database Schema

    • New Migration V3: Adds metadata columns to messages table
      • provider_id (FK to model_providers)
      • model_name (VARCHAR)
      • latency_ms (INTEGER)
      • prompt_tokens (INTEGER)
      • completion_tokens (INTEGER)

    Services

    • ConversationService: CRUD operations for conversations
    • MessageService: Message send/receive with provider orchestration
    • MainAgentPromptService: Loads and assembles Main Agent identity
    • OllamaProviderService: Integration with Ollama API

    DTOs

    • CreateConversationRequest (agentId, userId from header)
    • SendMessageRequest (content)
    • ConversationResponse (full conversation data)
    • MessageResponse (message with metadata)

    Resource Files

    • Main Agent identity files copied to classpath: src/main/resources/agents/main/
    • Loaded at runtime via Spring ClassPathResource

    Documentation

    • docs/chat-api.md: Complete REST API reference with examples

    Development Steps

    This milestone consists of 7 development steps (v1.3.1-dev through v1.3.7-dev):

    1. v1.3.1-dev: Conversation CRUD APIs
    2. v1.3.2-dev: Message send API with persistence
    3. v1.3.3-dev: Main Agent prompt assembly
    4. v1.3.4-dev: Model provider integration
    5. v1.3.5-dev: Response metadata tracking
    6. v1.3.6-dev: Error handling
    7. v1.3.7-dev: API documentation

    Hotfixes

    • v1.3.8-hotfix: Fixed 6 compilation errors (ModelProvider method names, DTO entity mismatches, timestamp types)
    • v1.3.9-hotfix: Added missing UUID import in DtoMapper

    Testing

    • ✅ Maven compilation successful
    • ✅ Docker Compose build successful
    • ✅ All 3 Flyway migrations applied (V1, V2, V3)
    • ✅ Backend starts and passes health check
    • ✅ PostgreSQL 18.3 database initialized
    • ✅ All services (backend, postgres, redis, qdrant, dashboard) running

    Next Steps

    • v1.5.0 - Agent Lifecycle: Agent versioning, lifecycle hooks, state management
    • v1.6.0 - Memory Layer: Short-term/long-term memory with vector embeddings
    • v1.7.0 - Tool System: Tool definition, invocation, and response handling
    • v1.8.0 - Dashboard UI: Web interface for chat, agents, and settings

    Dependencies

    • Spring Boot 4.0.0
    • PostgreSQL 18.3
    • Hibernate 7.1.8
    • Flyway 11.2.0
    • Ollama API integration

    Migration Path

    No breaking changes. New installations will automatically run all migrations (V1, V2, V3).

    Contributors

    Implemented in collaboration with GitHub Copilot CLI.

    Downloads
  • v1.3.9-hotfix c77890ce36

    v1.3.9-hotfix - Missing UUID import Pre-release

    FTMahringer released this 2026-05-08 23:56:43 +02:00 | 254 commits to main since this release

    Import Error Fix

    Added missing UUID import to DtoMapper.

    Error:

    • DtoMapper.fromCreateRequest() uses UUID parameter
    • Missing import java.util.UUID;
    • Maven compilation failed

    Fix:

    • Added UUID import to DtoMapper.java

    Quick followup to v1.3.8-hotfix.

    Downloads
  • v1.3.8-hotfix 7572829587

    v1.3.8-hotfix - Compilation error fixes Pre-release

    FTMahringer released this 2026-05-08 23:54:55 +02:00 | 255 commits to main since this release

    Compilation Error Fixes

    Fixed 8 compilation errors discovered during Docker build testing.

    Errors Fixed:

    • ModelProvider method names: getProviderType() → getType(), isEnabled() → getEnabled()
    • ModelProvider config: getConfiguration() → getConfig()
    • ConversationResponse: getUserId() instead of getUser().getId()
    • MessageResponse: getConversationId() directly (no getConversation())
    • DtoMapper: fromCreateRequest() signature (userId param)
    • Type mismatches: OffsetDateTime → Instant

    Root Causes:

    • Wrong method names in MessageService for ModelProvider API
    • DTO field accessors mismatched with entity structure
    • Timestamp type inconsistency (Instant vs OffsetDateTime)

    Testing:

    • Discovered via docker compose build --no-cache backend
    • Maven compiler caught all issues
    • Full compilation now successful

    Fixes for v1.4.0 Chat Runtime milestone.

    Downloads
  • v1.3.7-dev 34bcdc6208

    v1.3.7-dev - Chat API documentation Pre-release

    FTMahringer released this 2026-05-08 23:51:11 +02:00 | 256 commits to main since this release

    Chat Runtime API Documentation

    Complete API reference for conversation and message endpoints.

    Documentation:

    • docs/chat-api.md with full REST API reference
    • Request/response examples with payloads
    • Metadata field descriptions
    • Error handling patterns
    • Dashboard integration roadmap (v1.8.0)

    Endpoints:

    • POST /api/conversations - Create
    • GET /api/conversations - List
    • GET /api/conversations/{id} - Details
    • GET /api/conversations/{id}/messages - History
    • POST /api/conversations/{id}/messages - Send

    Message Structure:

    • USER messages: No provider metadata
    • ASSISTANT messages: Full provider/model/token/latency data
    • ERROR messages: ⚠️ prefix, provider context

    Notes:

    • X-User-ID header for user scope
    • Main Agent prompt from classpath resources
    • First enabled Ollama provider used
    • Token/latency analytics ready

    v1.4.0 Chat Runtime Milestone: BACKEND COMPLETE ✅

    Backend APIs functional. Dashboard UI deferred to v1.8.0.

    Part of v1.4.0 Chat Runtime milestone (step 7/7).

    Downloads
  • v1.3.6-dev 16f470af12

    v1.3.6-dev - Error handling and graceful degradation Pre-release

    FTMahringer released this 2026-05-08 23:50:12 +02:00 | 257 commits to main since this release

    Error Handling for Model Providers

    Graceful error handling when model provider calls fail.

    Features:

    • Try/catch around provider API calls
    • Error messages persisted as assistant messages
    • Provider metadata tracked on failures
    • Latency captured for all requests (success/failure)

    Exception Types:

    • ModelProviderException - Provider errors
    • RequestTimeoutException - Timeout foundation

    Behavior:

    • User message always saved first
    • Error message: '⚠️ Model provider error: [details]'
    • Full context preserved (provider ID, model, latency)
    • Exception propagated for API error responses

    Future:

    • Per-provider timeout configuration
    • Retry with exponential backoff
    • Fallback provider chains
    • Circuit breaker pattern

    Part of v1.4.0 Chat Runtime milestone (step 6/7).

    Downloads
  • v1.3.5-dev ddf1ab9df3

    v1.3.5-dev - Response metadata tracking Pre-release

    FTMahringer released this 2026-05-08 23:48:45 +02:00 | 258 commits to main since this release

    Response Metadata Persistence

    Tracks provider, model, latency, and token breakdown for AI responses.

    Features:

    • New message columns: provider_id, model_name, latency_ms, prompt_tokens, completion_tokens
    • Message entity with full metadata fields
    • MessageService captures response timing and token counts

    Database Schema:

    • V3 migration adds 5 columns to messages table
    • FK to model_providers for analytics
    • Index on provider_id for queries

    Metadata Fields:

    • Provider ID: Which provider generated response
    • Model name: Specific model (e.g., llama3.2)
    • Latency (ms): API call duration
    • Prompt tokens: Context token count
    • Completion tokens: Generated token count
    • Total tokens: prompt + completion

    Use Cases:

    • Cost tracking by provider/model
    • Performance analytics
    • Token usage reports
    • Provider comparison

    Part of v1.4.0 Chat Runtime milestone (step 5/7).

    Downloads
  • v1.3.4-dev 9a86acdf45

    v1.3.4-dev - Model provider integration for chat Pre-release

    FTMahringer released this 2026-05-08 23:46:35 +02:00 | 259 commits to main since this release

    Model Provider Integration

    Connects message send API to Ollama provider for real AI responses.

    Features:

    • MessageService calls OllamaProviderService.chatCompletion()
    • Main Agent system prompt assembled from identity files
    • Conversation history loaded for context
    • Assistant responses persisted with token counts

    Flow:

    1. Save user message
    2. Load conversation history
    3. Get enabled Ollama provider
    4. Assemble Main Agent prompt (system/identity/soul/connections)
    5. Build chat messages (system + history)
    6. Call Ollama API
    7. Save assistant response with tokens

    Implementation:

    • Model from provider config (default: llama3.2)
    • Token count: prompt_eval_count + eval_count
    • First enabled Ollama provider selected

    Part of v1.4.0 Chat Runtime milestone (step 4/7).

    Downloads
  • v1.3.0.1-hotfix 8cd0e2cd42

    v1.3.0.1-hotfix - Docker Compose Startup Fixes Pre-release

    FTMahringer released this 2026-05-08 23:25:45 +02:00 | 264 commits to main since this release

    Critical fixes for Docker Compose deployment discovered during integration testing.

    Compilation Errors Fixed:

    • User.passwordHash field missing (added with getters/setters)
    • CreateUserRequest.password field missing (added with validation)
    • Database schema migrations incomplete for v1.0.7+ auth and v1.2.x providers

    Database Schema Fixes:

    • V1 migration: Added users.password_hash column (NOT NULL)
    • V1 migration: Added model_providers table (provider configuration storage)
    • V1 migration: Added provider_usage_logs table (API call tracking/analytics)
    • V2 seed data: Admin user now includes password_hash (default: admin, must change)

    Runtime Configuration Fixes:

    • SecretEncryptionService default encryption key corrected (32 bytes for AES-256)
    • docker-compose.yml: Added SECRETS_ENCRYPTION_KEY env var (AES-256 key)
    • docker-compose.yml: Added JWT_SECRET env var (HS256 signing key)
    • application.yml: Changed Hibernate ddl-auto='none' (Flyway manages schema, not Hibernate)

    Code Cleanup:

    • Removed duplicate AgentsController (conflicted with AgentManagementController GET /api/agents)

    Verification:

    • ✅ Backend starts successfully (Tomcat on :8080)
    • ✅ Flyway migrations run successfully (all tables created)
    • ✅ Health endpoint returns UP status
    • ✅ All 28 database tables present (users, agents, model_providers, provider_usage_logs, etc.)
    • ✅ Docker Compose full stack operational (postgres, redis, qdrant, backend, dashboard)

    Default Credentials (MUST CHANGE):

    • Username: admin
    • Password: admin
    • Password hash format: Argon2id (64MB, 3 iterations, parallelism=1)

    This is a RELEASE (not a development patch).

    Downloads
  • 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