Synapse Core Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require arnaudmoncondhuy/synapse-core:^0.1
   php bin/console synapse:doctor --init
   

   This auto-generates entities, configs, and routes.

2. First Use Case: Inject ChatService in a controller to interact with LLM:

   use ArnaudMoncondhuy\SynapseCore\Engine\ChatService;
   
   #[Route('/ask', name: 'ask_ai')]
   public function ask(ChatService $chatService): JsonResponse {
       $response = $chatService->ask("Hello, how are you?", [
           'agent' => 'default_agent',
           'stateless' => true
       ]);
       return $this->json($response);
   }
   

Where to Look First

• SynapseDoctorCommand: Run php bin/console synapse:doctor to diagnose and fix setup issues.
• config/packages/synapse.yaml: Central configuration for persistence, admin, and providers.
• src/Entity/: Auto-generated Conversation and Message entities (extend if needed).

Implementation Patterns

Core Workflows

1. Agent-Based Interaction:

   $chatService->ask("Explain Laravel", [
       'agent' => 'technical_expert',
       'tone' => 'concise'
   ]);
   

2. Tool Integration:

   // Register a custom tool
   services:
       App\Tool\WeatherTool:
           tags: [synapse.tool]
   
   // Use in agent
   $chatService->ask("What's the weather?", [
       'agent' => 'weather_agent'
   ]);
   

3. Memory Management:

   $memoryManager = $container->get(MemoryManager::class);
   $memoryManager->addMemory("Laravel", "PHP framework...");
   

Integration Tips

• Doctrine ORM: Extend SynapseConversation and SynapseMessage for custom fields.
• Event Listeners: Hook into events like SynapseToolCallRequestedEvent for custom logic.
• Streaming Responses: Use ChatService with debug: true to inspect payloads in the admin panel.

Common Patterns

Gotchas and Tips

Pitfalls

1. Missing Entities:

   • If you skip synapse:doctor --init, manually create Conversation and Message entities with correct Doctrine mappings.
   • Fix: Ensure inversedBy and mappedBy are correctly set in bidirectional relationships.

2. Asset Configuration:

   • Forgetting to add Synapse assets to assets/controllers.json or app.css will break frontend features.
   • Fix: Run php bin/console importmap:require synapse/controllers/synapse_chat_controller.js.

3. Permission Issues:

   • The admin panel (/synapse/admin) requires ROLE_ADMIN. Test with:

     php bin/console make:user admin admin@example.com --role=ROLE_ADMIN
     

4. Token Limits:

   • Exceeding SynapseSpendingLimit throws SynapseSpendingLimitExceededEvent. Handle gracefully in listeners.

Debugging Tips

• Enable Debug Mode:

  $chatService->ask("Test", ['debug' => true]);
  

  Use the returned debug_id to inspect payloads in the admin panel under Debug Logs.

• Check Events: Subscribe to SynapseGenerationStartedEvent to log or modify LLM requests:

  services:
      App\EventListener\LogLLMRequests:
          tags:
              - { name: kernel.event_listener, event: SynapseGenerationStartedEvent, method: onGenerationStart }
  

Extension Points

1. Custom Providers: Implement SynapseProviderInterface for unsupported LLM APIs (e.g., Mistral).

2. Memory Backends: Extend VectorStoreInterface to integrate with Pinecone or Weaviate:

   class CustomVectorStore implements VectorStoreInterface {
       public function addEmbedding(array $embeddings): void { ... }
   }
   

3. Tool Registry: Dynamically register tools via services:

   services:
       App\Tool\CustomTool:
           tags: [synapse.tool]
   

Configuration Quirks

• Doctrine Mappings: Ensure ArnaudMoncondhuy namespace mappings are correctly set in doctrine.yaml:

  mappings:
      ArnaudMoncondhuy:
          type: attribute
          dir: '%kernel.project_dir%/vendor/arnaudmoncondhuy/synapse-core/src/Storage/Entity'
  

• Security: The DefaultPermissionChecker uses Symfony’s security system. Override PermissionCheckerInterface for custom logic.

• Token Accounting: Prices are stored in SynapseModel (e.g., $0.0001 per 1M tokens). Update via the admin panel or directly in the DB.

Performance Tips

• Stateless Mode: Use 'stateless' => true in ChatService to avoid DB writes for non-critical interactions.

• Caching: Cache embeddings in MemoryManager to reduce LLM calls:

  $memoryManager->setCacheTTL(3600); // Cache for 1 hour