Merge pull request #64 from programmatordev/OPA-59-ai-assistant-resource

New AI Assistant resource

Author: andrepimpao

docs/02-configuration.md

@@ -72,7 +72,7 @@ $api = new OpenWeatherMap('yourapikey', [
 > To get to know about all the available methods, make sure to check the documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#documentation).
 
 The following sections have examples of some of the most important methods, 
-particularly related with the configuration of the client, cache and logger.
+particularly related to the configuration of the client, cache and logger.
 
 ### `setClientBuilder`
 

docs/03-supported-apis.md

@@ -6,6 +6,9 @@
     - [getWeatherByDate](#getweatherbydate)
     - [getWeatherSummaryByDate](#getweathersummarybydate)
     - [getWeatherOverviewByDate](#getweatheroverviewbydate)
+  - [AI Assistant](#ai-assistant)
+    - [startSession](#startsession)
+    - [resumeSession](#resumesession)
   - [Weather](#weather)
     - [getCurrent](#getcurrent)
     - [getForecast](#getforecast)
@@ -84,6 +87,36 @@ Returns a [`WeatherOverview`](05-entities.md#weatheroverview) object:
 $weatherOverview = $api->oneCall()->getWeatherOverviewByDate(50, 50, new \DateTime('today'));
 ```
 
+### AI Assistant
+
+#### `startSession`
+
+```php
+startSession(string $prompt): Answer
+```
+
+Start a new session (create a new conversation) with the Weather AI Assistant.
+
+Returns a [`Answer`](05-entities.md#answer) object:
+
+```php
+$answer = $api->assistant()->startSession('How is the weather today in Lisbon?');
+```
+
+#### `resumeSession`
+
+```php
+resumeSession(string $sessionId, string $prompt): Answer
+```
+
+Resume a session (continue a conversation) with the Weather AI Assistant.
+
+Returns a [`Answer`](05-entities.md#answer) object:
+
+```php
+$answer = $api->assistant()->resumeSession('session-id', 'Do I need an umbrella?');
+```
+
 ### Weather
 
 #### `getCurrent`
@@ -192,7 +225,7 @@ $locations = $api->geocoding()->getByLocationName('lisbon');
 getByCoordinate(float $latitude, float $longitude, int $numResults = 5): array
 ```
 
-Get name of the location (city name or area name) by using geographical coordinates (latitude, longitude). 
+Get the name of the location (city name or area name) by using geographical coordinates (latitude, longitude). 
 
 Returns an array of [`Location`](05-entities.md#location) objects.
 
@@ -261,7 +294,7 @@ withCacheTtl(?int $ttl): self
 Makes a request and saves into cache for the provided duration in seconds. 
 
 Semantics of values:
-- `0`, the response will not be cached (if the servers specifies no `max-age`).
+- `0`, the response will not be cached (if the server specifies no `max-age`).
 - `null`, the response will be cached for as long as it can (forever).
 
 > [!NOTE]

docs/05-entities.md

@@ -4,17 +4,21 @@
   - [Weather](#weather)
   - [WeatherMoment](#weathermoment)
   - [WeatherSummary](#weathersummary)
+  - [WeatherOverview](#weatheroverview)
   - [WeatherData](#weatherdata)
   - [MinuteData](#minutedata)
   - [HourData](#hourdata)
   - [DayData](#daydata)
   - [Alert](#alert)
   - [MoonPhase](#moonphase)
   - [Temperature](#temperature)
+- [AI Assistant](#ai-assistant)
+  - [Answer](#answer)
+  - [WeatherData](#weatherdata-1)
 - [Weather](#weather-1)
   - [Weather](#weather-2)
   - [WeatherCollection](#weathercollection)
-  - [WeatherData](#weatherdata)
+  - [WeatherData](#weatherdata-2)
 - [Air Pollution](#air-pollution)
   - [AirPollution](#airpollution)
   - [AirPollutionCollection](#airpollutioncollection)
@@ -171,6 +175,33 @@
 - `getMin()`: `?float`
 - `getMax()`: `?float`
 
+## AI Assistant
+
+### Answer
+
+- `getAnswer()`: `string`
+- `getSessionId()`: `string`
+- `getData()`: [`WeatherData[]`](#weatherdata-1)
+
+### WeatherData
+
+- `getLocationName()`: `string`
+- `getDateTime()`: `\DateTimeImmutable`
+- `getTemperature()`: `float`
+- `getTemperatureFeelsLike()`: `float`
+- `getAtmosphericPressure()`: `int`
+- `getVisibility()`: `?int`
+- `getHumidity()`: `int`
+- `getDewPoint()`: `float`
+- `getUltraVioletIndex()`: `?float`
+- `getCloudiness()`: `int`
+- `getWind()`: [`Wind`](#wind)
+- `getConditions()`: [`Condition[]`](#condition)
+- `getRainVolume()`: `?float`
+- `getSnowVolume()`: `?float`
+- `getSunriseAt()`: `?\DateTimeImmutable`
+- `getSunsetAt()`: `?\DateTimeImmutable`
+
 ## Weather
 
 ### Weather

src/Entity/AirPollution/AirPollutionCollection.php

@@ -3,12 +3,10 @@
 namespace ProgrammatorDev\OpenWeatherMap\Entity\AirPollution;
 
 use ProgrammatorDev\OpenWeatherMap\Entity\Coordinate;
-use ProgrammatorDev\OpenWeatherMap\Util\EntityTrait;
+use ProgrammatorDev\OpenWeatherMap\Helper\EntityHelper;
 
 class AirPollutionCollection
 {
-    use EntityTrait;
-
     private int $numResults;
 
     private Coordinate $coordinate;
@@ -20,7 +18,7 @@ public function __construct(array $data)
     {
         $this->numResults = count($data['list']);
         $this->coordinate = new Coordinate($data['coord']);
-        $this->data = $this->createEntityList(AirPollutionData::class, $data['list']);
+        $this->data = EntityHelper::createEntityList(AirPollutionData::class, $data['list']);
     }
 
     public function getNumResults(): int

src/Entity/Assistant/Answer.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Entity\Assistant;
+
+use ProgrammatorDev\OpenWeatherMap\Helper\EntityHelper;
+
+class Answer
+{
+    private string $answer;
+
+    private string $sessionId;
+
+    /** @var WeatherData[] */
+    private array $data = [];
+
+    public function __construct(array $data)
+    {
+        $this->answer = $data['answer'];
+        $this->sessionId = $data['session_id'];
+
+        if (!empty($data['data'])) {
+            $this->data = EntityHelper::createEntityKeyList(WeatherData::class, $data['data']);
+        }
+    }
+
+    public function getAnswer(): string
+    {
+        return $this->answer;
+    }
+
+    public function getSessionId(): string
+    {
+        return $this->sessionId;
+    }
+
+    public function getData(): array
+    {
+        return $this->data;
+    }
+}

src/Entity/Assistant/WeatherData.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Entity\Assistant;
+
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
+class WeatherData extends BaseWeather
+{
+    private string $locationName;
+
+    private float $temperature;
+
+    private float $temperatureFeelsLike;
+
+    private int $visibility;
+
+    private \DateTimeImmutable $sunriseAt;
+
+    private \DateTimeImmutable $sunsetAt;
+
+    public function __construct(string $locationName, array $data)
+    {
+        parent::__construct($data);
+
+        $this->locationName = $locationName;
+        $this->temperature = $data['temp'];
+        $this->temperatureFeelsLike = $data['feels_like'];
+        $this->visibility = $data['visibility'];
+        $this->sunriseAt = \DateTimeImmutable::createFromFormat('U', $data['sunrise']);
+        $this->sunsetAt = \DateTimeImmutable::createFromFormat('U', $data['sunset']);
+    }
+
+    public function getLocationName(): string
+    {
+        return $this->locationName;
+    }
+
+    public function getTemperature(): float
+    {
+        return $this->temperature;
+    }
+
+    public function getTemperatureFeelsLike(): float
+    {
+        return $this->temperatureFeelsLike;
+    }
+
+    public function getVisibility(): int
+    {
+        return $this->visibility;
+    }
+
+    public function getSunriseAt(): \DateTimeImmutable
+    {
+        return $this->sunriseAt;
+    }
+
+    public function getSunsetAt(): \DateTimeImmutable
+    {
+        return $this->sunsetAt;
+    }
+}

src/Entity/OneCall/BaseWeather.php renamed to src/Entity/BaseWeather.php

@@ -1,15 +1,11 @@
 <?php
 
-namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
+namespace ProgrammatorDev\OpenWeatherMap\Entity;
 
-use ProgrammatorDev\OpenWeatherMap\Entity\Condition;
-use ProgrammatorDev\OpenWeatherMap\Entity\Wind;
-use ProgrammatorDev\OpenWeatherMap\Util\EntityTrait;
+use ProgrammatorDev\OpenWeatherMap\Helper\EntityHelper;
 
 class BaseWeather
 {
-    use EntityTrait;
-
     private \DateTimeImmutable $dateTime;
 
     private int $atmosphericPressure;
@@ -46,7 +42,7 @@ public function __construct(array $data)
             'gust' => $data['wind_gust'] ?? null
         ]);
 
-        $this->conditions = $this->createEntityList(Condition::class, $data['weather']);
+        $this->conditions = EntityHelper::createEntityList(Condition::class, $data['weather']);
         $this->rainVolume = $data['rain']['1h'] ?? $data['rain']['3h'] ?? $data['rain'] ?? null;
         $this->snowVolume = $data['snow']['1h'] ?? $data['snow']['3h'] ?? $data['snow'] ?? null;
     }

src/Entity/OneCall/DayData.php

@@ -2,6 +2,8 @@
 
 namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
 
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
 class DayData extends BaseWeather
 {
     private Temperature $temperature;

src/Entity/OneCall/HourData.php

@@ -2,6 +2,8 @@
 
 namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
 
+use ProgrammatorDev\OpenWeatherMap\Entity\BaseWeather;
+
 class HourData extends BaseWeather
 {
     private float $temperature;

src/Entity/OneCall/Weather.php

@@ -4,12 +4,10 @@
 
 use ProgrammatorDev\OpenWeatherMap\Entity\Coordinate;
 use ProgrammatorDev\OpenWeatherMap\Entity\Timezone;
-use ProgrammatorDev\OpenWeatherMap\Util\EntityTrait;
+use ProgrammatorDev\OpenWeatherMap\Helper\EntityHelper;
 
 class Weather
 {
-    use EntityTrait;
-
     private Coordinate $coordinate;
 
     private Timezone $timezone;
@@ -43,14 +41,14 @@ public function __construct(array $data)
         $this->current = new WeatherData($data['current']);
 
         $this->minutelyForecast = isset($data['minutely'])
-            ? $this->createEntityList(MinuteData::class, $data['minutely'])
+            ? EntityHelper::createEntityList(MinuteData::class, $data['minutely'])
             : null;
 
-        $this->hourlyForecast = $this->createEntityList(HourData::class, $data['hourly']);
-        $this->dailyForecast = $this->createEntityList(DayData::class, $data['daily']);
+        $this->hourlyForecast = EntityHelper::createEntityList(HourData::class, $data['hourly']);
+        $this->dailyForecast = EntityHelper::createEntityList(DayData::class, $data['daily']);
 
         $this->alerts = isset($data['alerts'])
-            ? $this->createEntityList(Alert::class, $data['alerts'])
+            ? EntityHelper::createEntityList(Alert::class, $data['alerts'])
             : null;
     }