Suml Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require avris/suml
   

   Ensure your project uses PHP 8.0+ (SUML requires this).

2. Basic Usage

   use Avris\SUML\SUML;
   
   $suml = new SUML();
   $result = $suml->parse('Hello, world!');
   echo $result->getText(); // Outputs: "Hello, world!"
   

3. First Use Case Parse a simple text string to extract structured data (e.g., entities, relationships):

   $suml = new SUML();
   $parsed = $suml->parse('John Doe works at Acme Corp.');
   $entities = $parsed->getEntities(); // Array of detected entities
   

4. Where to Look First

   • Documentation: Check the GitLab repo for examples and API docs.
   • Tests: Browse tests/ for real-world usage patterns.
   • Core Class: Focus on Avris\SUML\SUML for primary methods like parse(), getEntities(), and getRelationships().

Implementation Patterns

Core Workflows

1. Text Parsing Pipeline

   $suml = new SUML();
   $parsed = $suml->parse($rawText);
   $entities = $parsed->getEntities();
   $relationships = $parsed->getRelationships();
   

   • Use getEntities() to extract named entities (e.g., people, organizations).
   • Use getRelationships() to analyze connections between entities.

2. Integration with Laravel

   • Service Provider: Bind SUML to the container for dependency injection:

     $this->app->singleton(SUML::class, function ($app) {
         return new SUML();
     });
     

   • Facade (Optional): Create a facade for cleaner syntax:

     // app/Facades/SUML.php
     public static function parse($text) {
         return app(SUML::class)->parse($text);
     }
     

3. Batch Processing

   $suml = new SUML();
   $texts = ['Text 1', 'Text 2', 'Text 3'];
   $results = array_map([$suml, 'parse'], $texts);
   

4. Customizing Output

   • Filter entities/relationships by type:

     $people = array_filter($entities, fn($e) => $e->getType() === 'PERSON');
     

Advanced Patterns

1. Extending SUML

   • Override parsing logic by extending the SUML class or using middleware:

     $suml->addMiddleware(function ($text, $next) {
         // Pre-process text (e.g., clean HTML)
         return $next($text);
     });
     

2. Storing Results

   • Serialize parsed data for later use:

     $serialized = $parsed->toArray();
     cache()->put('suml_result', $serialized, now()->addHours(1));
     

3. Error Handling

   • Wrap parsing in a try-catch:

     try {
         $result = $suml->parse($text);
     } catch (\Exception $e) {
         Log::error("SUML parsing failed: " . $e->getMessage());
         return response()->json(['error' => 'Processing failed'], 500);
     }
     

Gotchas and Tips

Common Pitfalls

1. Performance

   • SUML may be slow for large texts (>10,000 characters). Consider:
     • Chunking text into smaller segments.
     • Caching results (e.g., cache()->remember()).

2. Entity/Relationship Granularity

   • SUML might miss context-specific entities (e.g., niche jargon). Pre-process text with domain-specific rules if needed.

3. Dependency Conflicts

   • SUML may pull in heavy dependencies (e.g., NLP libraries). Audit composer.json for bloat.

4. Locale Support

   • Default parsing may not handle non-English text well. Check if SUML supports locale-specific models.

Debugging Tips

1. Inspect Raw Output

   $debug = $suml->parse($text, ['debug' => true]);
   dd($debug->getRawData()); // Inspect internal parsing steps
   

2. Logging

   • Enable SUML’s debug mode via config (if available) or wrap calls in Log::debug().

3. Testing Edge Cases

   • Test with:
     • Empty strings.
     • Text with special characters (e.g., John Doe & Co.).
     • Mixed languages (if applicable).

Extension Points

1. Custom Entity Types

   • Extend SUML’s entity recognition by:
     • Training a custom model (if SUML supports it).
     • Post-processing results with Laravel’s Str::contains() or regex.

2. Middleware Hooks

   • Add pre/post-processing logic:

     $suml->addMiddleware(function ($text, $next) {
         $text = preg_replace('/[^a-zA-Z0-9\s]/', '', $text); // Sanitize
         return $next($text);
     });
     

3. Configuration

   • Check for hidden config options (e.g., confidence thresholds):

     $suml->setConfig(['min_confidence' => 0.7]);
     

Laravel-Specific Tips

1. Queue Long-Running Parses

   ParseJob::dispatch($text)->onQueue('suml');
   

   • Implement ParseJob to handle SUML parsing asynchronously.

2. API Integration

   • Expose SUML via a Laravel route:

     Route::post('/api/parse', function (Request $request) {
         $suml = app(SUML::class);
         return response()->json($suml->parse($request->text)->toArray());
     });
     

3. Database Storage

   • Store parsed entities in a suml_entities table:

     $entity->save(); // Assuming Entity model with fillable fields