Synapse Admin Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require arnaudmoncondhuy/synapse-admin:^0.1

Ensure synapse-core is also installed (dependency).

2. Bundle Registration: Add to config/bundles.php:

   ArnaudMoncondhuy\SynapseAdmin\SynapseAdminBundle::class => ['all' => true],
   

3. Route Configuration: Include routes in config/routes.yaml:

   synapse_admin:
       resource: '@SynapseAdminBundle/config/routes.yaml'
       prefix: /synapse/admin
   

4. Security: Protect routes in config/packages/security.yaml:

   access_control:
       - { path: ^/synapse/admin, roles: ROLE_ADMIN }
   

5. First Use Case: Access /synapse/admin to view the dashboard. Start by configuring LLM providers (e.g., OpenAI, Gemini) under Providers (/synapse/admin/intelligence/configuration-llm).

Implementation Patterns

Core Workflows

1. Provider Configuration:

   • Navigate to Providers to add/edit API credentials (stored encrypted via AdminSecurityTrait).
   • Test connections via the built-in "Test Connection" button.
   • Select default models for each provider.

2. Preset Management:

   • Create presets under Presets (/synapse/admin/presets/new).
   • Define LLM parameters (temperature, max_tokens) and safety settings.
   • Use the Live Test feature to simulate conversations with mock data (streaming supported).

3. Agent Configuration:

   • Define agents with system prompts, presets, and tools under Agents.
   • Restrict access via Symfony roles or user IDs (e.g., ROLE_SUPER_ADMIN).
   • Assign RAG sources and tone settings (e.g., "zen," "technical").

4. RAG Source Management:

   • Index documents via Sources RAG (/synapse/admin/rag).
   • Reindex asynchronously using Messenger (progress tracked in UI).
   • Visualize chunks and test relevance with synapse:rag:test console command.

5. Analytics & Quotas:

   • Monitor token usage and costs on the Dashboard.
   • Set spending limits per user/agent/preset under Quotas.
   • Audit API calls and costs via Analytics.

Integration Tips

• Leverage Twig Templates: Extend layouts with @Synapse/admin/layout.html.twig for consistent UI. Example:

  {% extends '@Synapse/admin/layout/base.html.twig' %}
  {% block body %}
      {{ include('@Synapse/admin/partials/dashboard.html.twig') }}
  {% endblock %}
  

• Customize Permissions: Extend DefaultPermissionChecker to add granular role checks:

  use ArnaudMoncondhuy\SynapseAdmin\Security\AdminSecurityTrait;
  
  class CustomPermissionChecker implements PermissionCheckerInterface
  {
      use AdminSecurityTrait;
  
      public function hasPermission($user, string $attribute, mixed $subject = null): bool
      {
          // Custom logic here
          return $this->isGranted('ROLE_CUSTOM_ADMIN', $user);
      }
  }
  

• Extend Forms: Override preset/provider forms by creating custom templates in templates/SynapseAdminBundle/ (e.g., preset/_form.html.twig).

• Async Tasks: Use Symfony Messenger for long-running tasks (e.g., RAG reindexing):

  $this->messageBus->dispatch(new ReindexRagSourceMessage($sourceId));
  

• Multilingual Support: Add translations via Symfony’s translation system (domain: synapse_admin):

  # config/packages/translation.yaml
  locales: [en, fr]
  

Gotchas and Tips

Pitfalls

1. Security Misconfigurations:

   • Issue: Forgetting to restrict /synapse/admin routes in security.yaml.
   • Fix: Always enforce ROLE_ADMIN (or custom role) via access_control.
   • Debug: Use php bin/console debug:security to verify roles.

2. Credential Leaks:

   • Issue: Hardcoding API keys in forms or logs.
   • Fix: Use AdminSecurityTrait for encrypted storage. Never log raw credentials.
   • Debug: Check var/log/synapse_admin.log for encrypted values (not plaintext).

3. RAG Indexing Failures:

   • Issue: Reindexing hangs or fails silently.
   • Fix: Enable debug mode (config/packages/dev/synapse_admin.yaml):

     debug: true
     

   • Debug: Monitor Messenger queues:

     php bin/console messenger:consume async -vv
     

4. Preset Testing Quirks:

   • Issue: Live tests show unexpected outputs.
   • Fix: Verify the preset’s system_prompt and tools in the Debug Logs (/synapse/admin/systeme/debug).
   • Tip: Use the Payload API tab to inspect raw LLM requests/responses.

5. Quota Overrides:

   • Issue: Spending limits not applying to specific users.
   • Fix: Ensure the SynapseSpendingLimit entity is flushed after updates:

     $limit->setAmount(1000);
     $entityManager->flush();
     

Debugging Tips

• Enable Debug Mode: Add to config/packages/dev/synapse_admin.yaml:

  synapse_admin:
      debug: true
  

  This logs:

  • Raw API payloads (request/response).
  • Event dispatching (e.g., preset.tested).

• Check Console Commands: Useful commands:

  # Test RAG relevance
  php bin/console synapse:rag:test "query here"
  
  # Clear cache (if UI changes aren’t reflected)
  php bin/console cache:clear
  
  # List all agents/presets
  php bin/console debug:container synapse_admin
  

• Stimulus Debugging: For Stimulus controllers (e.g., live preset testing):

  npm run dev  # Rebuild assets
  

  Check browser console for Stimulus errors (e.g., stimulus:action).

Extension Points

1. Custom Tools: Register new AiToolInterface implementations:

   // config/services.yaml
   services:
       App\Tool\CustomTool:
           tags: ['synapse_admin.tool']
   

2. Dashboard Widgets: Add custom widgets to the dashboard by extending the DashboardController:

   class CustomDashboardController extends AbstractDashboardController
   {
       public function customWidget(): Response
       {
           return $this->render('@App/custom_widget.html.twig');
       }
   }
   

3. Audit Logs: Extend audit logging by implementing SynapseAuditLoggerInterface:

   class CustomAuditLogger implements SynapseAuditLoggerInterface
   {
       public function logEvent(string $event, array $context): void
       {
           // Custom logic (e.g., send to external SIEM)
       }
   }
   

4. Multilingual Forms: Override form translations dynamically:

   {% trans with {'%model%': preset.model} from 'synapse_admin' %}
       Preset uses model: %model%
   {% endtrans %}
   

5. Health Checks: Add custom checks to /synapse/admin/systeme/health:

   use Symfony\Component\HealthCheck\HealthCheckInterface;
   
   class CustomHealthCheck implements HealthCheckInterface
   {
       public function check(HealthCheck $healthCheck): void
       {
           if ($this->isDatabaseHealthy()) {
               $healthCheck->ok();
           } else {
               $healthCheck->fail('Database unavailable');
           }
       }
   }
   

   Register in config/services.yaml:

   tags: ['health_check.checker']
   

Configuration Quirks

• Asset Mapping: If Stimulus controllers fail, ensure asset-mapper is configured:

  # config/packages/framework.yaml
  assets:
      packages:
          synapse_admin:
              json_manifest_path: '%kernel.project_dir%/public/build/manifest.json'
  

• Cache Invalidation: Clear the synapse_admin cache after:

  • Adding new tools/agents.
  • Updating translations.

  php bin/console cache:pool:clear synapse_admin
  

• Provider-Specific Settings: Some providers (e.g., OVH) require additional config. Check the DatabaseConfigProvider for defaults:

  $provider = $this->configProvider->getProvider('ovh');
  $provider->setApiKey('your_key_here');
  

• Twig Strict Variables: Avoid undefined variables in templates. Use {{ dump(var) }} to debug: