Improved tool descriptions

Author: luisdalmolin

composer.json

@@ -35,7 +35,8 @@
         "pestphp/pest-plugin-laravel": "^3.1",
         "pestphp/pest-plugin-livewire": "^3.0",
         "laravel/pint": "^1.21",
-        "larastan/larastan": "^3.4"
+        "larastan/larastan": "^3.4",
+        "kirschbaum-development/laravel-loop": "^0.1.1"
     },
     "config": {
         "allow-plugins": {

src/DescribeFilamentResourceTool.php

@@ -38,18 +38,10 @@ public function build(): PrismTool
     {
         return app(PrismTool::class)
             ->as($this->getName())
-            ->for('Describes the structure, fields, columns, actions, and relationships for a given Filament resource')
+            ->for('Describes the structure, fields, columns, actions, and relationships for a given Filament resource. Always call the list_filament_resources tool before calling this tool.')
             ->withStringParameter('resource', 'The class name of the resource to describe.', required: true)
             ->using(function (string $resource) {
-                $resource = $this->getResourceInstance($resource);
-
-                return json_encode([
-                    'resource' => class_basename($resource),
-                    'model' => $resource::getModel(),
-                    // 'form' => $this->extractFormSchema($resource),
-                    'table' => $this->extractTableSchema($resource),
-                    'relationships' => $this->extractRelationshipsInfo($resource),
-                ]);
+                return json_encode($this->describe($resource));
             });
     }
 
@@ -58,15 +50,28 @@ public function getName(): string
         return 'describe_filament_resource';
     }
 
-    protected function extractBasicInfo(Resource $resource): array
+    public function describe(string $resourceClass): array
+    {
+        $resource = $this->getResourceInstance($resourceClass);
+
+        return [
+            'resource' => class_basename($resource),
+            'model' => $resourceClass::getModel(),
+            // 'form' => $this->extractFormSchema($resourceClass),
+            'table' => $this->extractTableSchema($resource),
+            'relationships' => $this->extractRelationshipsInfo($resource),
+        ];
+    }
+
+    public function extractBasicInfo(Resource $resource): array
     {
         return [
             'resource' => class_basename($resource),
             'model' => $resource::getModel(),
         ];
     }
 
-    protected function extractFormSchema(Resource $resource): array
+    public function extractFormSchema(Resource $resource): array
     {
         $livewireComponent = new class extends LivewireComponent implements HasForms
         {
@@ -84,7 +89,7 @@ protected function extractFormSchema(Resource $resource): array
         return ['fields' => $fields];
     }
 
-    protected function extractNavigationInfo(Resource $resource): array
+    public function extractNavigationInfo(Resource $resource): array
     {
         return [
             'group' => $resource::getNavigationGroup(),
@@ -93,7 +98,7 @@ protected function extractNavigationInfo(Resource $resource): array
         ];
     }
 
-    protected function extractRelationshipsInfo(Resource $resource): array
+    public function extractRelationshipsInfo(Resource $resource): array
     {
         if (! method_exists($resource, 'getRelations')) {
             return [];
@@ -108,13 +113,16 @@ protected function extractRelationshipsInfo(Resource $resource): array
                 // Relationship details are often defined within the manager or inferred by naming.
                 // This requires more specific introspection or assumptions based on conventions.
                 // Placeholder: Use manager class name as key.
-                $relationName = $manager->getRelationshipName(); // Assuming this method exists or convention
+                $relationName = $manager->getRelationshipName();
+                $modelClass = $resource::getModel();
+                $modelInstance = new $modelClass();
+                $relation = $modelInstance->$relationName();
 
                 $relationships[$relationName] = [
-                    'type' => 'hasMany', // Placeholder - determining type requires deeper inspection
+                    'type' => class_basename($relation),
                     'manager' => $managerClass,
-                    // 'model' => $manager->getRelatedModel(), // Requires standard method
-                    // 'foreignKey' => $manager->getForeignKey(), // Requires standard method
+                    'model' => get_class($relation->getRelated()),
+                    'foreignKey' => $relation->getForeignKeyName(),
                 ];
             } catch (\Throwable $e) {
                 // Log error if manager instantiation fails
@@ -124,7 +132,7 @@ protected function extractRelationshipsInfo(Resource $resource): array
         return $relationships;
     }
 
-    protected function extractTableSchema(Resource $resource): array
+    public function extractTableSchema(Resource $resource): array
     {
         try {
             $livewireComponent = new class extends LivewireComponent implements HasTable
@@ -152,18 +160,14 @@ public function makeFilamentTranslatableContentDriver(): ?TranslatableContentDri
                 ->map(fn (array $column) => [
                     'name' => $column['name'],
                     'label' => $column['label'],
-                    'type' => 'searchable_column', // Indicate this is derived from a searchable column
+                    'type' => 'searchable_column',
                 ])
-                ->keyBy('name') // Key by name to potentially merge/override later if needed
+                ->keyBy('name')
                 ->all();
 
-            $filters = array_merge($searchableColumnFilters, $existingFilters); // Merge, giving priority to existing explicit filters if names collide
-
-            // $rowActions = collect($table->getActions()) // Actions column actions
-            //     ->map(fn (Action $action) => $this->mapTableAction($action))
-            //     ->all();
+            $filters = array_merge($searchableColumnFilters, $existingFilters);
 
-            $bulkActions = collect($table->getBulkActions()) // Bulk actions
+            $bulkActions = collect($table->getBulkActions())
                 ->flatMap(function ($action) {
                     if ($action instanceof BulkActionGroup) {
                         return collect($action->getActions())
@@ -188,7 +192,7 @@ public function makeFilamentTranslatableContentDriver(): ?TranslatableContentDri
         }
     }
 
-    protected function mapComponentType(Component $component): string
+    public function mapComponentType(Component $component): string
     {
         return match (true) {
             $component instanceof TextInput => 'text',
@@ -203,7 +207,7 @@ protected function mapComponentType(Component $component): string
         };
     }
 
-    protected function mapFilterType(BaseFilter $filter): string
+    public function mapFilterType(BaseFilter $filter): string
     {
         return match (true) {
             $filter instanceof TernaryFilter => 'boolean',
@@ -213,7 +217,7 @@ protected function mapFilterType(BaseFilter $filter): string
         };
     }
 
-    protected function mapFormComponent(Component $component, Resource $resource): ?array
+    public function mapFormComponent(Component $component, Resource $resource): ?array
     {
         $baseInfo = [
             'name' => $component->getName(),
@@ -246,7 +250,7 @@ protected function mapFormComponent(Component $component, Resource $resource): ?
         return $baseInfo;
     }
 
-    protected function mapTableAction(Action|BulkAction $action): string
+    public function mapTableAction(Action|BulkAction $action): string
     {
         // Map common actions to simple strings, fallback to action name
         $name = $action->getName();
@@ -258,7 +262,7 @@ protected function mapTableAction(Action|BulkAction $action): string
         // Could potentially add more details like label, icon, color if needed
     }
 
-    protected function mapTableColumn(Column $column): array
+    public function mapTableColumn(Column $column): array
     {
         $baseInfo = [
             'name' => $column->getName(),
@@ -271,7 +275,7 @@ protected function mapTableColumn(Column $column): array
         return $baseInfo;
     }
 
-    protected function mapTableFilter(BaseFilter $filter): array
+    public function mapTableFilter(BaseFilter $filter): array
     {
         $baseInfo = [
             'name' => $filter->getName(),

src/ExecuteResourceActionTool.php

@@ -24,7 +24,7 @@ public function build(): PrismTool
     {
         return app(PrismTool::class)
             ->as($this->getName())
-            ->for('Executes a specified action on a Filament resource. Always double check with the user before executing any action.')
+            ->for('Executes a specified action on a Filament resource. Always double check with the user before executing any action. Always call the describe_filament_resource tool before calling this tool.')
             ->withStringParameter('resource', 'The class name of the resource to execute action on.', required: true)
             ->withStringParameter('action', 'The name of the action to execute.', required: true)
             ->withStringParameter('actionType', 'The type of action: "bulk".', required: false)

src/GetFilamentResourceDataTool.php

@@ -22,7 +22,7 @@ public function build(): PrismTool
     {
         return app(PrismTool::class)
             ->as($this->getName())
-            ->for('Gets the data for a given Filament resource, applying optional filters provided in the describe_filament_resource tool.')
+            ->for('Gets the data for a given Filament resource, applying optional filters provided in the describe_filament_resource tool. Always call the describe_filament_resource tool before calling this tool. Try to use the available filters to get the data you need.')
             ->withStringParameter('resource', 'The resource class name of the resource to get data for, from the list_filament_resources tool.', required: true)
             ->withStringParameter('filters', 'JSON string of filters to apply (e.g., \'{"status": "published", "author_id": [1, 2]}\').', required: false)
             ->using(function (string $resource, ?string $filters = null) {

src/ListFilamentResourcesTool.php

@@ -25,7 +25,7 @@ public function build(): PrismTool
     {
         return app(PrismTool::class)
             ->as('list_filament_resources')
-            ->for('Lists all available Filament resources. Filament resources are used to list, fetch and manage data for a given data resource (database table, model, etc.). You cannot use a resource that is not listed here.')
+            ->for('Lists all available Filament resources. Filament resources are used to list, fetch and manage data for a given data resource (database table, model, etc.). You cannot use a resource that is not listed here. Always call this tool first to know which resources are available.')
             ->using(function () {
                 return collect($this->getResources())->map(
                     fn (string $resource) => $resource

tests/Feature/DescribeFilamentResourceToolTest.php

@@ -0,0 +1,130 @@
+<?php
+
+use Tests\Feature\TestUserResource;
+use Tests\Feature\TestPostWithRelationsResource;
+use Tests\Feature\TestUserWithRelationsResource;
+use Kirschbaum\Loop\Filament\DescribeFilamentResourceTool;
+
+it('can instantiate the describe filament resource tool', function () {
+    $tool = new DescribeFilamentResourceTool();
+
+    expect($tool)->toBeInstanceOf(DescribeFilamentResourceTool::class);
+    expect($tool->getName())->toBe('describe_filament_resource');
+});
+
+it('can extract table schema using the tool', function () {
+    $tool = new DescribeFilamentResourceTool();
+    $resource = app(TestUserResource::class);
+
+    $tableSchema = $tool->extractTableSchema($resource);
+
+    expect($tableSchema)->toBeArray()
+        ->and($tableSchema)->toHaveKeys(['columns', 'filters', 'actions'])
+        ->and($tableSchema['columns'])->toBeArray()
+        ->and($tableSchema['columns'])->toHaveCount(3);
+
+    $columnNames = collect($tableSchema['columns'])->pluck('name')->toArray();
+    expect($columnNames)->toContain('name', 'email', 'created_at');
+});
+
+it('can extract column properties through the tool', function () {
+    $tool = new DescribeFilamentResourceTool();
+    $resource = app(TestUserResource::class);
+
+    $tableSchema = $tool->extractTableSchema($resource);
+    $columns = $tableSchema['columns'];
+
+    $nameColumn = collect($columns)->firstWhere('name', 'name');
+    expect($nameColumn)->toBeArray()
+        ->and($nameColumn['searchable'])->toBeTrue()
+        ->and($nameColumn['sortable'])->toBeTrue();
+
+    $emailColumn = collect($columns)->firstWhere('name', 'email');
+    expect($emailColumn)->toBeArray()
+        ->and($emailColumn['searchable'])->toBeTrue()
+        ->and($emailColumn['sortable'])->toBeTrue();
+});
+
+it('can extract bulk actions through the tool', function () {
+    $tool = new DescribeFilamentResourceTool();
+    $resource = app(TestUserResource::class);
+
+    $tableSchema = $tool->extractTableSchema($resource);
+    $bulkActions = $tableSchema['actions']['bulk'];
+
+    expect($bulkActions)->toBeArray()
+        ->and($bulkActions)->toContain('delete');
+});
+
+it('can extract resource relationships through the tool', function () {
+    $tool = new DescribeFilamentResourceTool();
+    $resource = app(TestUserWithRelationsResource::class);
+
+    $relationships = $tool->extractRelationshipsInfo($resource);
+
+    expect($relationships)->toBeArray()
+        ->and($relationships)->toHaveKeys(['posts', 'comments']);
+
+    expect($relationships['posts'])->toBeArray()
+        ->and($relationships['posts']['type'])->toBe('HasMany')
+        ->and($relationships['posts']['manager'])->toBe(\Tests\Feature\TestPostsRelationManager::class);
+
+    expect($relationships['comments'])->toBeArray()
+        ->and($relationships['comments']['type'])->toBe('HasMany')
+        ->and($relationships['comments']['manager'])->toBe(\Tests\Feature\TestCommentsRelationManager::class);
+});
+
+it('can describe a complete resource using the tool', function () {
+    $tool = new DescribeFilamentResourceTool();
+
+    $result = $tool->describe(TestUserWithRelationsResource::class);
+
+    expect($result)->toBeArray()
+        ->and($result)->toHaveKeys(['resource', 'model', 'table', 'relationships'])
+        ->and($result['resource'])->toBe('TestUserWithRelationsResource')
+        ->and($result['model'])->toBe(\Tests\Feature\TestUser::class)
+        ->and($result['table'])->toBeArray()
+        ->and($result['relationships'])->toBeArray();
+
+    // Verify table structure
+    expect($result['table']['columns'])->toHaveCount(3);
+    expect($result['table']['actions']['bulk'])->toContain('delete');
+
+    // Verify relationships structure
+    expect($result['relationships'])->toHaveKeys(['posts', 'comments']);
+});
+
+it('can extract different relationship types including belongsTo', function () {
+    $tool = new DescribeFilamentResourceTool();
+    $resource = app(TestPostWithRelationsResource::class);
+
+    $relationships = $tool->extractRelationshipsInfo($resource);
+
+    expect($relationships)->toBeArray()
+        ->and($relationships)->toHaveKeys(['comments', 'category']);
+
+    expect($relationships['comments'])->toBeArray()
+        ->and($relationships['comments']['type'])->toBe('HasMany')
+        ->and($relationships['comments']['manager'])->toBe(\Tests\Feature\TestCommentsRelationManager::class);
+
+    expect($relationships['category'])->toBeArray()
+        ->and($relationships['category']['type'])->toBe('BelongsTo')
+        ->and($relationships['category']['manager'])->toBe(\Tests\Feature\TestCategoryRelationManager::class);
+});
+
+it('can describe a resource with mixed relationship types', function () {
+    $tool = new DescribeFilamentResourceTool();
+
+    $result = $tool->describe(TestPostWithRelationsResource::class);
+
+    expect($result)->toBeArray()
+        ->and($result)->toHaveKeys(['resource', 'model', 'table', 'relationships'])
+        ->and($result['resource'])->toBe('TestPostWithRelationsResource')
+        ->and($result['model'])->toBe(\Tests\Feature\TestPost::class);
+
+    // Verify we have both relationship types
+    $relationships = $result['relationships'];
+    expect($relationships)->toHaveKeys(['comments', 'category'])
+        ->and($relationships['comments']['type'])->toBe('HasMany')
+        ->and($relationships['category']['type'])->toBe('BelongsTo');
+});

tests/Feature/TestCategory.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Tests\Feature;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class TestCategory extends Model
+{
+    protected $fillable = [
+        'name',
+        'description',
+        'created_at',
+    ];
+
+    protected $casts = [
+        'created_at' => 'datetime',
+    ];
+
+    public function posts(): HasMany
+    {
+        return $this->hasMany(TestPost::class);
+    }
+}