├── .github
    └── workflows
    │   └── tests.yml
├── .gitignore
├── LICENSE
├── README.md
├── composer.json
├── composer.lock
├── config
    └── sentimento.php
├── logo.png
├── phpunit.xml.dist
├── src
    ├── Enums
    │   ├── Decision.php
    │   └── Role.php
    ├── Facade
    │   └── Sentimento.php
    ├── Http
    │   └── Client.php
    ├── Sentimento.php
    ├── SentimentoServiceProvider.php
    └── ValueObjects
    │   └── Message.php
└── tests
    ├── Pest.php
    ├── TestCase.php
    └── sentimento.php


/.github/workflows/tests.yml:
--------------------------------------------------------------------------------
 1 | name: Tests
 2 | 
 3 | on: ['push', 'pull_request']
 4 | 
 5 | jobs:
 6 |   ci:
 7 |     runs-on: ubuntu-latest
 8 |     strategy:
 9 |       matrix:
10 |         php: ['8.1', '8.2']
11 |         dependency-version: [prefer-lowest, prefer-stable]
12 | 
13 |     name: PHP ${{ matrix.php }} - ${{ matrix.dependency-version }} - ${{ matrix.parallel }}
14 | 
15 |     steps:
16 |       - name: Checkout
17 |         uses: actions/checkout@v2
18 | 
19 |       - name: Setup PHP
20 |         uses: shivammathur/setup-php@v2
21 |         with:
22 |           php-version: ${{ matrix.php }}
23 |           tools: composer:v2
24 |           coverage: none
25 | 
26 |       - name: Install PHP dependencies
27 |         run: composer update --${{ matrix.dependency-version }} --no-interaction --no-progress
28 | 
29 |       - name: Integration Tests
30 |         run: ./vendor/bin/pest --colors=always
31 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /vendor/
2 | /.phpunit.result.cache
3 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2023 Ahmed Ammar
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Sentimento
 2 | A laravel package that provides sentiment analysis capabilities using OpenAI's GPT to easily analyze text-based data and gain insight into the underlying sentiment.
 3 | 
 4 | <p align="center">
 5 |     <p align="center">
 6 |         <img alt="Laravel Version" src="https://img.shields.io/badge/Laravel-10-orange" />
 7 |         <a href="https://github.com/ahmedash95/sentimento/actions"><img alt="GitHub Workflow Status (master)" src="https://img.shields.io/github/workflow/status/ahmedash95/sentimento/Tests/master"></a>
 8 |         <a href="https://packagist.org/packages/ahmedash95/sentimento"><img alt="Total Downloads" src="https://img.shields.io/packagist/dt/ahmedash95/sentimento"></a>
 9 |         <a href="https://packagist.org/packages/ahmedash95/sentimento"><img alt="Latest Version" src="https://img.shields.io/packagist/v/ahmedash95/sentimento"></a>
10 |         <a href="https://packagist.org/packages/ahmedash95/sentimento"><img alt="License" src="https://img.shields.io/packagist/l/ahmedash95/sentimento"></a>
11 |     </p>
12 | </p>
13 | 
14 | ![logo](logo.png)
15 | 
16 | ```php
17 | use Ahmedash95\Sentimento\Facade\Sentimento;
18 | 
19 | $result = Sentimento::analyze("Food was great!");
20 | 
21 | $result->value; // Positive
22 | ```
23 | 
24 | 
25 | ## Installation
26 | 
27 | - First you need to install the package using composer
28 | ```bash
29 | composer require ahmedash95/sentimento
30 | ```
31 | - (Optional) Publish config file
32 | ```bash
33 | php artisan vendor:publish --tag="sentimento-config"
34 | ```
35 | - Add your OpenAI API key to your .env file
36 | ```bash
37 | SENTIMENTO_OPENAI_TOKEN=sk-xxxxxxxxxxxxxxxxxxxx
38 | ```
39 | 
40 | Now you are ready to use the package
41 | 
42 | ## Usage
43 | 
44 | OpenAI can comprehend multiple languages, and using it is as easy as invoking a function.
45 | 
46 | ```php
47 | use Ahmedash95\Sentimento\Facade\Sentimento;
48 | 
49 | Sentimento::analyze("Food was great!"); // Positive
50 | 
51 | Sentimento::analyze("Food was bad!"); // Negative
52 | 
53 | Sentimento::analyze("لما اتصلت بالدليفري قالي انه اكل الاوردر"); // Negative
54 | ```
55 | 
56 | > [!WARNING]
57 | > When calling OpenAI to analyze text, there is a possibility that HTTP exceptions may occur if the request to OpenAI fails. This can happen due to a variety of reasons, such as network connectivity issues, server errors, or even rate limiting policies imposed by OpenAI. If the request to OpenAI fails, the package may not be able to properly analyze the sentiment of the given text and may result in unexpected errors or output. To handle this, it is important to catch and handle any potential HTTP exceptions that may occur
58 | 
59 | ```php
60 | use Ahmedash95\Sentimento\Facade\Sentimento;
61 | use Illuminate\Http\Client\RequestException;
62 | 
63 | try {
64 |     $result = Sentimento::analyze("Food was great!");
65 | } catch (RequestException $e) {
66 |     // $e->getMessage()
67 | }
68 | ```
69 | 
70 | Or you can set the `report_failures` option to `false` in the config file to disable reporting failures
71 | ```php
72 | // instead of exception, the result will be Decision::Unknown
73 | 
74 | $result = Sentimento::analyze("Food was great!"); // Unknown
75 | ```
76 | ## Testing
77 | 
78 | ```bash
79 | composer test
80 | ```
81 | 
82 | ## Contributing
83 | Please feel free to fork this package and contribute by submitting a pull request to enhance the functionalities.
84 | 
85 | # Credits
86 | - [Ahmed Ammar](https://github.com/ahmedash95)
87 | - [All Contributors](../../contributors)
88 | 
89 | ## License
90 | The MIT License (MIT). Please see [License File](LICENSE) for more information.
91 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "ahmedash95/sentimento",
 3 |   "description": "A laravel package that provides sentiment analysis capabilities using OpenAI's GPT to easily analyze text-based data and gain insight into the underlying sentiment.",
 4 |   "type": "library",
 5 |   "license": "MIT",
 6 |   "autoload": {
 7 |     "psr-4": {
 8 |       "Ahmedash95\\Sentimento\\": "src/"
 9 |     }
10 |   },
11 |   "autoload-dev": {
12 |     "psr-4": {
13 |       "Tests\\": "tests/"
14 |     }
15 |   },
16 |   "authors": [
17 |     {
18 |       "name": "Ahmed Ammar",
19 |       "email": "ahmed29329@gmail.com"
20 |     }
21 |   ],
22 |   "require": {
23 |     "laravel/framework": "^9.46.0|^10.2.0",
24 |     "spatie/laravel-package-tools": "^1.14",
25 |     "guzzlehttp/guzzle": "^7.5"
26 |   },
27 |   "require-dev": {
28 |     "pestphp/pest": "^1.22",
29 |     "laravel/pint": "^1.6",
30 |     "orchestra/testbench": "^8.0"
31 |   },
32 |   "extra": {
33 |     "laravel": {
34 |       "providers": [
35 |         "Ahmedash95\\Sentimento\\SentimentoServiceProvider"
36 |       ]
37 |     }
38 |   },
39 |   "config": {
40 |     "allow-plugins": {
41 |       "pestphp/pest-plugin": true
42 |     }
43 |   },
44 |   "scripts": {
45 |     "test": "./vendor/bin/pest",
46 |     "pint": "./vendor/bin/pint"
47 |   }
48 | }
49 | 


--------------------------------------------------------------------------------
/config/sentimento.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | return [
 4 |     'token' => env('SENTIMENTO_OPENAI_TOKEN'),
 5 | 
 6 |     // Sending a request to OpenAI API might fail due to many reasons.
 7 |     // If you want to report these failures, set this to true.
 8 |     // if false, the result will be Decision::Unknown in case of api errors.
 9 |     'report_failures' => true,
10 | ];
11 | 


--------------------------------------------------------------------------------
/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ahmedash95/sentimento/8800fb6e608daee09163372ede97ea3a921eea66/logo.png


--------------------------------------------------------------------------------
/phpunit.xml.dist:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3 |          xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
 4 |          colors="true"
 5 | >
 6 |     <testsuites>
 7 |         <testsuite name="default">
 8 |             <directory suffix=".php">./tests</directory>
 9 |         </testsuite>
10 |     </testsuites>
11 |     <filter>
12 |         <whitelist processUncoveredFilesFromWhitelist="true">
13 |             <directory suffix=".php">./src</directory>
14 |         </whitelist>
15 |     </filter>
16 | </phpunit>


--------------------------------------------------------------------------------
/src/Enums/Decision.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento\Enums;
 4 | 
 5 | enum Decision: string
 6 | {
 7 |     case Positive = 'positive';
 8 |     case Negative = 'negative';
 9 |     case Natural = 'natural';
10 |     case Unknown = 'unknown';
11 | }
12 | 


--------------------------------------------------------------------------------
/src/Enums/Role.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento\Enums;
 4 | 
 5 | enum Role: string
 6 | {
 7 |     case Assistant = 'assistant';
 8 |     case User = 'user';
 9 | }
10 | 


--------------------------------------------------------------------------------
/src/Facade/Sentimento.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento\Facade;
 4 | 
 5 | use Illuminate\Support\Facades\Facade;
 6 | 
 7 | class Sentimento extends Facade
 8 | {
 9 |     protected static function getFacadeAccessor()
10 |     {
11 |         return \Ahmedash95\Sentimento\Sentimento::class;
12 |     }
13 | }
14 | 


--------------------------------------------------------------------------------
/src/Http/Client.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento\Http;
 4 | 
 5 | use Ahmedash95\Sentimento\ValueObjects\Message;
 6 | use Illuminate\Http\Client\PendingRequest;
 7 | use Illuminate\Http\Client\Response;
 8 | use Illuminate\Support\Facades\Http;
 9 | 
10 | class Client
11 | {
12 |     private PendingRequest $client;
13 | 
14 |     const ENDPOINT = 'https://api.openai.com/v1/chat/completions';
15 | 
16 |     public function __construct(string $token)
17 |     {
18 |         $this->client = Http::withHeaders([
19 |             'Content-Type' => 'application/json',
20 |             'Authorization' => 'Bearer '.$token,
21 |         ]);
22 |     }
23 | 
24 |     /**
25 |      * @param  Message[]  $messages
26 |      * @return Response
27 |      */
28 |     public function send(string $model, array $messages)
29 |     {
30 |         return $this->client->post(self::ENDPOINT, [
31 |             'model' => $model,
32 |             'messages' => $messages,
33 |             'temperature' => 0.5,
34 |             'max_tokens' => 5,
35 |         ]);
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/src/Sentimento.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento;
 4 | 
 5 | use Ahmedash95\Sentimento\Enums\Decision;
 6 | use Ahmedash95\Sentimento\Http\Client;
 7 | use Ahmedash95\Sentimento\ValueObjects\Message;
 8 | 
 9 | class Sentimento
10 | {
11 |     public function __construct(private readonly Client $client, private $reportFailures = true)
12 |     {
13 |     }
14 | 
15 |     public function analyze($text): Decision
16 |     {
17 |         $messages = [
18 |             Message::forAssistant("I'm a sentiment analysis engine,you send me the text and I would only respond with one word either 'positive', 'negative', 'natural'")->toArray(),
19 |             Message::forUser($text)->toArray(),
20 |         ];
21 | 
22 |         $choices = $this->client
23 |             ->send('gpt-3.5-turbo', $messages)
24 |             ->throwIf($this->reportFailures)
25 |             ->json()['choices'] ?? [];
26 | 
27 |         if (empty($choices)) {
28 |             return Decision::Unknown;
29 |         }
30 | 
31 |         return Decision::tryFrom($choices[0]['message']['content']) ?? Decision::Unknown;
32 |     }
33 | }
34 | 


--------------------------------------------------------------------------------
/src/SentimentoServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento;
 4 | 
 5 | use Ahmedash95\Sentimento\Http\Client;
 6 | use Spatie\LaravelPackageTools\Package;
 7 | use Spatie\LaravelPackageTools\PackageServiceProvider;
 8 | 
 9 | class SentimentoServiceProvider extends PackageServiceProvider
10 | {
11 |     public function configurePackage(Package $package): void
12 |     {
13 |         $package
14 |             ->name('sentimento')
15 |             ->hasConfigFile();
16 |     }
17 | 
18 |     public function registeringPackage()
19 |     {
20 |         $this->app->singleton(Sentimento::class, function () {
21 |             $client = new Client(config('sentimento.token'));
22 | 
23 |             return new Sentimento($client, config('sentimento.report_failures', true));
24 |         });
25 |     }
26 | }
27 | 


--------------------------------------------------------------------------------
/src/ValueObjects/Message.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Ahmedash95\Sentimento\ValueObjects;
 4 | 
 5 | use Ahmedash95\Sentimento\Enums\Role;
 6 | 
 7 | class Message
 8 | {
 9 |     public function __construct(private readonly Role $role, private readonly string $content)
10 |     {
11 |     }
12 | 
13 |     public static function forAssistant(string $content): self
14 |     {
15 |         return new self(Role::Assistant, $content);
16 |     }
17 | 
18 |     public static function forUser(string $content): self
19 |     {
20 |         return new self(Role::User, $content);
21 |     }
22 | 
23 |     public function toArray(): array
24 |     {
25 |         return [
26 |             'role' => $this->role,
27 |             'content' => $this->content,
28 |         ];
29 |     }
30 | }
31 | 


--------------------------------------------------------------------------------
/tests/Pest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | use Ahmedash95\Sentimento\Http\Client;
 4 | use Illuminate\Support\Facades\Http;
 5 | 
 6 | function fakeClient($text = 'positive'): Client
 7 | {
 8 |     Http::fake([
 9 |         Client::ENDPOINT => Http::response([
10 |             'choices' => [['message' => ['content' => $text]]],
11 |         ]),
12 |     ]);
13 | 
14 |     return new Client('fake_token');
15 | }
16 | 


--------------------------------------------------------------------------------
/tests/TestCase.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tests;
 4 | 
 5 | use Orchestra\Testbench\TestCase as Orchestra;
 6 | 
 7 | class TestCase extends Orchestra
 8 | {
 9 | }
10 | 


--------------------------------------------------------------------------------
/tests/sentimento.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | use Ahmedash95\Sentimento\Enums\Decision;
 4 | use Ahmedash95\Sentimento\Http\Client;
 5 | use Ahmedash95\Sentimento\Sentimento;
 6 | use Illuminate\Http\Client\RequestException;
 7 | use Tests\TestCase;
 8 | 
 9 | uses(TestCase::class);
10 | 
11 | it('should return a sentiment', function () {
12 |     $sentimento = new Sentimento(fakeClient());
13 | 
14 |     expect($sentimento->analyze('Food was good!'))->toBe(Decision::Positive);
15 | });
16 | 
17 | it('should return unknown on unexpected response', function () {
18 |     $sentimento = new Sentimento(fakeClient('unexpected message'));
19 | 
20 |     expect($sentimento->analyze('Food was good!'))->toBe(Decision::Unknown);
21 | });
22 | 
23 | it('should throw exception on api errors', function () {
24 |     $sentimento = new Sentimento(new Client('fake_token'));
25 | 
26 |     $sentimento->analyze('Food was good!');
27 | })->throws(RequestException::class);
28 | 
29 | it('should fail silently if report_failures is false', function () {
30 |     $sentimento = new Sentimento(new Client('fake_token'), false);
31 | 
32 |     expect($sentimento->analyze('Food was good!'))->toBe(Decision::Unknown);
33 | });
34 | 


--------------------------------------------------------------------------------