Synapse Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Core Package

   composer require arnaudmoncondhuy/synapse-core
   

2. Run Doctor CLI for Auto-Configuration

   php bin/console synapse:doctor --init
   

   • Creates default admin user (admin/admin)
   • Generates required Doctrine entities (Conversation, Message)
   • Sets up basic synapse_core.yaml config

3. First Use Case: Programmatic Chat

   use Synapse\Core\Chat\ChatService;
   
   class MyController extends AbstractController {
       public function __invoke(ChatService $chatService) {
           $response = $chatService->ask(
               message: "Summarize this report",
               options: ['tone' => 'professional']
           );
           return $this->json($response['answer']);
       }
   }
   

Where to Look First

• Core Documentation: Synapse Core
• CLI Reference: php bin/console list synapse (for all available commands)
• Default Config: config/packages/synapse_core.yaml
• Entities: src/Entity/Conversation.php and src/Entity/Message.php

Implementation Patterns

1. Agent-Based Workflows

Pattern: Specialized AI Agents with Tools

// Define an agent in config
synapse_core:
  agents:
    report_analyst:
      instructions: "Analyze financial reports with precision"
      tools: ["spreadsheet_parser", "database_query"]
      tone: "expert_analyst"

Usage:

$agent = $this->get('synapse_core.agent.report_analyst');
$analysis = $agent->execute("Analyze Q3 2023 revenue trends");

2. Cost-Aware API Calls

Pattern: Token Budgeting

// Check budget before expensive operation
$budget = $chatService->getBudget('user_123');
if ($budget->remainingTokens < 1000) {
    throw new \RuntimeException("Token budget exhausted");
}

// Execute with cost tracking
$response = $chatService->ask(
    message: "Generate 500-word blog post",
    options: ['cost_aware' => true]
);

3. Streaming Responses

Pattern: Real-Time UI Feedback

{# templates/chat/streaming.html.twig #}
<div id="chat-stream">
    {{ include('@Synapse/chat/streaming_component.html.twig', {
        endpoint: path('synapse_chat_stream'),
        conversationId: conversation.id
    }) }}
</div>

4. RAG Integration

Pattern: Vector Store Integration

# config/packages/synapse_core.yaml
synapse_core:
  vector_store:
    class: App\Service\CustomVectorStore
    options:
      embedding_model: "text-embedding-ada-002"

5. Admin Dashboard Integration

Pattern: Monitoring Endpoints

// In your controller
public function dashboard(AnalyticsService $analytics) {
    $stats = $analytics->getUsageStats();
    return $this->render('admin/dashboard.html.twig', ['stats' => $stats]);
}

Gotchas and Tips

Common Pitfalls

1. Entity Mismatch

   • Error: Class App\Entity\Conversation does not exist
   • Fix: Run php bin/console synapse:doctor --init to generate entities or manually create them:

     php bin/console make:entity Conversation
     php bin/console make:entity Message
     

2. Token Cost Overruns

   • Gotcha: Default quotas are unlimited
   • Solution: Configure in synapse_core.yaml:

     synapse_core:
       quotas:
         default:
           daily_limit: 10000
           cost_per_token: 0.000005
     

3. Streaming Component Issues

   • Error: "CSRF token missing"
   • Fix: Ensure your Twig template includes:

     {{ form_start(form, {'attr': {'data-csrf': app.request.csrfToken}}) }}
     

Debugging Tips

1. Synapse Doctor

   php bin/console synapse:doctor --check
   

   • Validates all configurations and dependencies

2. Cost Logging Enable debug mode to see token usage:

   synapse_core:
     accounting:
       debug: true
   

3. Agent Debugging

   $agent->setDebug(true);
   $result = $agent->execute("Test query");
   // View debug output in Symfony profiler
   

Extension Points

1. Custom LLM Providers Implement Synapse\Core\LLM\ProviderInterface:

   class CustomProvider implements ProviderInterface {
       public function generate(string $prompt, array $options): string {
           // Your custom logic
       }
   }
   

   Register in config:

   synapse_core:
     providers:
       custom:
         class: App\Service\CustomProvider
   

2. Event Listeners Extend conversation processing:

   // src/EventListener/CustomChatListener.php
   class CustomChatListener implements ChatEventSubscriber {
       public static function getSubscribedEvents() {
           return [
               ChatEvents::PRE_ASK => 'onPreAsk',
           ];
       }
   
       public function onPreAsk(ChatEvent $event) {
           // Modify request before processing
       }
   }
   

3. Custom Vector Stores Implement Synapse\Core\VectorStore\StoreInterface for custom embeddings:

   class CustomVectorStore implements StoreInterface {
       public function addEmbedding(string $id, array $vector) { /* ... */ }
       public function query(string $query, int $limit) { /* ... */ }
   }
   

Configuration Quirks

1. Multilingual Support

   • Requires symfony/translation bundle
   • Configure in synapse_core.yaml:

     synapse_core:
       i18n:
         enabled: true
         default_locale: en
     

2. Auto-Titling

   • Requires synapse-chat bundle
   • Enable in config:

     synapse_chat:
       auto_titling: true
     

3. Security Notes

   • All chat endpoints are CSRF-protected by default
   • For programmatic use, disable CSRF in specific routes:

     synapse_chat:
       routes:
         ask:
           csrf_protection: false