Synapse Core Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Centric Design: The package is tightly coupled with Symfony (e.g., SecurityBundle, Messenger, Doctrine), making it a natural fit for Symfony-based applications but less adaptable for Laravel without significant refactoring.
• Laravel Compatibility: While PHP-based, Laravel’s ecosystem (e.g., Eloquent, service containers, routing) differs from Symfony’s. Key challenges:
  • Doctrine ORM: Laravel uses Eloquent; Doctrine would require a bridge (e.g., doctrine/dbal + custom Eloquent models).
  • Dependency Injection: Symfony’s autowiring vs. Laravel’s container binding.
  • Event System: Symfony’s EventDispatcher vs. Laravel’s Events facade.
  • Routing: Symfony’s Routing component vs. Laravel’s router.
• Core Features Alignment:
  • Multi-LLM Support: Valuable for Laravel apps needing Gemini/OVH/OpenAI integration.
  • Agent Orchestration: Useful for chatbots/tools but may require Laravel-specific wrappers.
  • Memory/Semantic Storage: Vector stores (e.g., DoctrineVectorStore) could integrate via Laravel’s database layer.
  • Accounting: Token tracking is a strong fit for cost-sensitive AI workflows.

Integration Feasibility

• High Effort: Direct integration is not plug-and-play; requires:
  • Symfony-to-Laravel Abstraction Layer: Wrap Symfony services (e.g., ChatService, ConversationManager) in Laravel-compatible facades.
  • Doctrine ↔ Eloquent Bridge: Map Doctrine entities (SynapseConversation, SynapseMessage) to Eloquent models.
  • Event Listeners: Convert Symfony events (e.g., SynapsePrePromptEvent) to Laravel listeners.
  • Routing: Replace Symfony routes with Laravel route bindings.
• Partial Adoption: Possible to use select components (e.g., LLM clients, token accounting) without full integration.

Technical Risk

Key Questions for TPM

1. Is Symfony a Hard Dependency?

   • Can the package’s core (LLM orchestration, agents, memory) be decoupled from Symfony?
   • Example: Extract SynapseAgent, VectorStore, and TokenAccountingService into standalone PHP classes.

2. What’s the Minimal Viable Integration?

   • Start with LLM clients (Gemini/OVH/OpenAI) + token accounting (lowest risk).
   • Add agents/memory only if critical for the product.

3. How Will We Handle Persistence?

   • Option 1: Doctrine DBAL + Eloquent models (higher effort).
   • Option 2: Pure Eloquent (rewrite Doctrine entities).

4. Event-Driven Workflows

   • Can Symfony events (e.g., SynapseToolCallRequestedEvent) be replaced with Laravel’s Events + Listeners?

5. Performance Impact

   • Symfony’s Messenger (async processing) vs. Laravel’s queues. Will this require a rewrite?

6. Long-Term Maintenance

   • Who will maintain the Laravel abstraction layer? The community (low stars) or internal team?

Integration Approach

Stack Fit

Migration Path

1. Phase 1: LLM Clients Only

   • Extract SynapseProvider (Gemini/OVH/OpenAI clients) into standalone PHP classes.
   • Integrate via Laravel’s HTTP client (e.g., Guzzle).
   • Risk: Minimal; no Symfony dependencies.

2. Phase 2: Token Accounting

   • Port TokenAccountingService and SynapseSpendingLimit to Laravel.
   • Use Laravel’s database for SynapseTokenUsage storage.
   • Risk: Medium; requires DB schema adaptation.

3. Phase 3: Agents & Memory

   • Rewrite SynapseAgent and VectorStore interfaces for Laravel.
   • Replace Doctrine with Eloquent or DBAL.
   • Risk: High; core orchestration logic may need refactoring.

4. Phase 4: Full Integration

   • Implement event bridges, security, and routing.
   • Risk: Critical; requires deep Symfony-to-Laravel mapping.

Compatibility

• Doctrine ↔ Eloquent:
  • Use Doctrine DBAL for queries or hybrid models (e.g., SynapseConversation extends Eloquent but uses Doctrine for complex queries).
  • Example:

    class Conversation extends Eloquent implements SynapseConversationInterface {
        public function getMessages(): Collection {
            return DBAL::fetchAll("SELECT * FROM messages WHERE conversation_id = ?", [$this->id]);
        }
    }
    

• Service Binding:
  • Bind Synapse services in AppServiceProvider:

    $this->app->bind(SynapseAgentInterface::class, function ($app) {
        return new LaravelSynapseAgent($app->make(LLMClient::class));
    });
    

• Events:
  • Create a SynapseEventDispatcher facade that translates Symfony events to Laravel:

    event(new SynapsePrePromptEvent($prompt))->toSynapseEvent();
    

Sequencing

1. Isolate Dependencies:
   • Start with LLM clients (no Symfony).
   • Add token accounting (DB-agnostic logic).
2. Database Layer:
   • Choose Doctrine DBAL (easier) or Eloquent (more Laravel-native).
3. Orchestration:
   • Refactor SynapseAgent to use Laravel’s service container.
4. Events & Security:
   • Last step; highest coupling with Symfony.

Operational Impact

Maintenance

• Short-Term:
  • High overhead: Custom abstraction layer for Symfony services.
  • Debugging: Symfony-specific errors (e.g., EventDispatcher) will require deep knowledge of the bridge.
• Long-Term:
  • Fork Risk: If the package evolves (e.g., Symfony 7+ features), Laravel integration may break.
  • Community Support: Low stars/issues mean limited external help.

Support

• Developer Ramp-Up:
  • 3–6 months for a team to master the integration (vs. 1–2 months for native Laravel packages).
  • Requires Symfony expertise to debug core issues.
• End-User Impact:
  • Minimal if API surfaces are stable (e.g., ChatService::ask()).
  • Risk of inconsistent behavior if event listeners or security checks fail silently.

Scaling

• Performance:
  • Doctrine DBAL: Slower than Eloquent for simple queries.
  • Symfony Messenger: Replace with Laravel queues (e.g., Redis, Database) for async tasks.
  • Memory Management: Vector stores (e.g., InMemory) may need Laravel-specific caching (e.g., Illuminate\Support\Facades\Cache).
• Horizontal Scaling:
  • Stateless LLM calls (e.g., ChatService::ask()) scale well.
  • Stateful operations (e.g., conversation history) require distributed caching (e.g., Redis).

Failure Modes