diff --git a/README.md b/README.md new file mode 100644 index 0000000..85788c0 --- /dev/null +++ b/README.md @@ -0,0 +1,436 @@ +# WetroCloud SDK for PHP + +> **⚠️ Unofficial SDK**: This is an **unofficial** PHP SDK for the WetroCloud API. + +## Introduction + +The **WetroCloud SDK for PHP** provides an easy way to interact with the WetroCloud API, allowing developers to create collections, insert resources, and query data effortlessly using PHP. + +## Installation + +```bash +composer require wetrocloud/wetrocloud-sdk +``` + +## Quick Start + +```php +createCollection('my-collection'); + +// Insert a resource +$wetrocloud->insertResource('my-collection', 'https://example.com/article', 'web'); + +// Query the collection +$results = $wetrocloud->queryCollection('my-collection', 'What is this about?'); +``` + +## Available Methods + +### Collection Management + +#### 1. `createCollection()` + +Creates a new collection. + +**Parameters:** +- `?string $collectionId` - (Optional) The unique ID of the collection. + +**Returns:** `array` + +**Example:** +```php +createCollection(); + +// Create collection with custom ID +$response = $wetrocloud->createCollection('unique-collection-id'); + +echo "Creating Collection: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 2. `listAllCollections()` + +Retrieves a list of available collections. + +**Returns:** `array` + +**Example:** +```php +listAllCollections(); + +echo "Listing Collections: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 3. `deleteCollection()` + +Deletes an entire collection. + +**Parameters:** +- `string $collectionId` - The ID of the collection. + +**Returns:** `array` + +**Example:** +```php +deleteCollection('your-collection-id'); + +echo "Deleting collection: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +### Resource Management + +#### 4. `insertResource()` + +Inserts a resource into a collection. + +**Parameters:** +- `string $collectionId` - The ID of the collection. +- `string $resource` - The resource to insert. +- `string $type` - The type of resource. + +**Returns:** `array` + +**Example:** +```php +insertResource( + 'your-collection-id', + 'https://medium.com/@AlexanderObregon/a-brief-history-of-artificial-intelligence-1656693721f9', + 'web' +); + +echo "Insert a resource: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 5. `removeResource()` + +Deletes a resource from a collection. + +**Parameters:** +- `string $collectionId` - The ID of the collection. +- `string $resourceId` - The ID of the resource to delete. + +**Returns:** `array` + +**Example:** +```php +removeResource('your-collection-id', 'your-resource-id'); + +echo "Deleting resource: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +### Querying & Chat + +#### 6. `queryCollection()` + +Queries resources from a collection. + +**Parameters:** +- `string $collectionId` - The ID of the collection. +- `string $requestQuery` - The query string. +- `?string $jsonSchema` - Optional JSON schema. +- `?string $jsonSchemaRules` - Optional JSON schema rules. + +**Returns:** `array` + +**Example:** +```php +queryCollection($collectionId, $query); + +// With schema and rules +$response = $wetrocloud->queryCollection( + $collectionId, + $query, + '{"type": "object", "properties": {"answer": {"type": "string"}}}', + '{"required": ["answer"]}' +); + +echo "Querying resource: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 7. `chatCollection()` + +Chat with a collection using message history. + +**Parameters:** +- `string $collectionId` - The ID of the collection. +- `string $message` - The message to send. +- `?string $chatHistory` - Optional chat history as JSON string. + +**Returns:** `array` + +**Example:** +```php +chatCollection('your-collection-id', 'Tell me more'); + +// Chat with history +$chatHistory = json_encode([ + ['role' => 'user', 'content' => 'What is this all about?'], + ['role' => 'assistant', 'content' => 'This is about Queen Elizabeth II of England'] +]); + +$response = $wetrocloud->chatCollection( + 'your-collection-id', + 'Tell me more', + $chatHistory +); + +echo "Chat with collection: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +### AI & Content Processing + +#### 8. `categorizeResource()` + +Categorizes a resource using predefined categories. + +**Parameters:** +- `string $resource` - The resource to categorize. +- `string $type` - The type of resource. +- `string $jsonSchema` - JSON schema of the resource. +- `string $categories` - Comma-separated list of categories. +- `string $prompt` - An overall command of your request. + +**Returns:** `array` + +**Example:** +```php +categorizeResource( + 'match review: John Cena vs. The Rock', + 'text', + '{"label": ""}', + 'football,coding,entertainment,basketball,wrestling,information', + 'Where does this fall under?' +); + +echo "Categorizing resource: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 9. `textGeneration()` + +Generates text without retrieval-augmented generation (RAG). + +**Parameters:** +- `array $messages` - Array of message objects with role and content. +- `string $model` - The model to use. + +**Returns:** `array` + +**Example:** +```php + 'system', 'content' => 'You are a helpful assistant.'], + ['role' => 'user', 'content' => 'Write a short poem about technology.'] +]; + +$response = $wetrocloud->textGeneration($messages, 'llama-3.3-70b'); + +echo "Generation without RAG: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 10. `imageToText()` + +Extracts text from an image. + +**Parameters:** +- `string $imageUrl` - The URL of the image. +- `string $requestQuery` - The query to process the image. + +**Returns:** `array` + +**Example:** +```php +imageToText($imageUrl, $query); + +echo "Image to text: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +### Content Conversion + +#### 11. `markdownConverter()` + +Converts a resource (file, web, image) to Markdown. + +**Parameters:** +- `string $resource` - The resource URL (file, web page, or image). +- `string $resourceType` - The type of resource: "file", "web", or "image". + +**Returns:** `array` + +**Example:** +```php +markdownConverter( + 'https://www.forbes.com/real-time-billionaires/', + 'web' +); + +// Convert file to markdown +$response = $wetrocloud->markdownConverter( + 'https://example.com/document.pdf', + 'file' +); + +// Convert image to markdown +$response = $wetrocloud->markdownConverter( + 'https://example.com/image.jpg', + 'image' +); + +echo "Converted Markdown: " . json_encode($response, JSON_PRETTY_PRINT); +``` + +#### 12. `transcript()` + +Retrieves transcript data from a resource (e.g., YouTube video). + +**Parameters:** +- `string $link` - The URL of the resource (e.g., YouTube video link). +- `string $resourceType` - The type of resource (e.g., "youtube"). + +**Returns:** `array` + +**Example:** +```php +transcript( + 'https://www.youtube.com/watch?v=m4qBwGnubew', + 'youtube' +); + +echo "Transcript result: " . json_encode($response, JSON_PRETTY_PRINT); +``` + + +## Configuration + +### Custom Base URL + +```php +getMessage()); } } + + /** + * Generate transcript from a resource (e.g., YouTube video). + * + * @param string $link The URL of the resource (e.g., YouTube video link). + * @param string $resourceType The type of resource (e.g., "youtube"). + * @return array Response from the API containing transcript data, tokens, and success status. + * @throws \RuntimeException + */ + public function transcript(string $link, string $resourceType = 'youtube'): array + { + try { + $payload = [ + 'link' => $link, + 'resource_type' => $resourceType, + ]; + + $response = $this->client->post('/v2/transcript/', [ + 'json' => $payload, + ]); + + return $this->decodeResponse($response); + } catch (GuzzleException $e) { + throw new \RuntimeException("Failed to generate transcript: " . $e->getMessage()); + } + } } diff --git a/tests/Feature/WetrocloudSdkTest.php b/tests/Feature/WetrocloudSdkTest.php index aad9e5c..7639ccf 100644 --- a/tests/Feature/WetrocloudSdkTest.php +++ b/tests/Feature/WetrocloudSdkTest.php @@ -3,7 +3,6 @@ use Wetrocloud\WetrocloudSdk\Wetrocloud; use GuzzleHttp\Client; use GuzzleHttp\Psr7\Response; -use GuzzleHttp\Exception\RequestException; use Mockery; // Test constructor and basic setup @@ -566,7 +565,7 @@ 'markdown' => '![Image Description](image-url)\n\nDescription of the image content.', 'tokens' => 15 ])); - + $mockClient = Mockery::mock(Client::class); $mockClient->shouldReceive('post') ->with('/v2/markdown-converter/', [ @@ -577,18 +576,54 @@ ]) ->once() ->andReturn($mockResponse); - + $wetrocloud = new Wetrocloud('test-api-key'); $wetrocloudReflection = new ReflectionClass($wetrocloud); $clientProperty = $wetrocloudReflection->getProperty('client'); $clientProperty->setAccessible(true); $clientProperty->setValue($wetrocloud, $mockClient); - + $result = $wetrocloud->markdownConverter('https://example.com/image.jpg', 'image'); - + expect($result)->toBe([ 'success' => true, 'markdown' => '![Image Description](image-url)\n\nDescription of the image content.', 'tokens' => 15 ]); }); + +// Test transcript method +test('can generate transcript from youtube video', function () { + $mockResponse = new Response(200, [], json_encode([ + 'success' => true, + 'transcript' => 'Hello, welcome to this video tutorial...', + 'tokens' => 45, + 'duration' => '10:30' + ])); + + $mockClient = Mockery::mock(Client::class); + $mockClient->shouldReceive('post') + ->with('/v2/transcript/', [ + 'json' => [ + 'link' => 'https://www.youtube.com/watch?v=example123', + 'resource_type' => 'youtube' + ] + ]) + ->once() + ->andReturn($mockResponse); + + $wetrocloud = new Wetrocloud('test-api-key'); + $wetrocloudReflection = new ReflectionClass($wetrocloud); + $clientProperty = $wetrocloudReflection->getProperty('client'); + $clientProperty->setAccessible(true); + $clientProperty->setValue($wetrocloud, $mockClient); + + $result = $wetrocloud->transcript('https://www.youtube.com/watch?v=example123'); + + expect($result)->toBe([ + 'success' => true, + 'transcript' => 'Hello, welcome to this video tutorial...', + 'tokens' => 45, + 'duration' => '10:30' + ]); +});