Feat add artefact group endpoints

[bedwards-ibm]

Add Artifact Sharing Visibility Endpoints

Summary

This PR adds two new REST API endpoints that provide visibility into artifact-group sharing relationships, enabling users to discover which groups have access to artifacts and what artifacts are shared with their groups.

Motivation

Previously, users could share artifacts with groups but had no way to:

1. See which groups an artifact is shared with
2. Browse all artifacts shared with a specific group
3. Filter shared artifacts by type

These endpoints address this gap by providing comprehensive visibility into sharing relationships.

Changes

New Endpoints

1. List Groups for an Artifact

GET /v2/artifacts/{artifact_type}/{artifact_id}/groups

Returns all groups that have access to a specific artifact.

Authorization:

• Artifact owners see ALL groups the artifact is shared with
• Non-owners see only groups they are members of

Example Response:

[
  {
    "group_id": "550e8400-e29b-41d4-a716-446655440000",
    "group_name": "Data Science Team",
    "granted_by": "owner@example.com",
    "granted_at": "2026-05-01T10:30:00Z",
    "user_role": "member"
  }
]

2. List Artifacts Shared with a Group

GET /v2/groups/{group_id}/artifacts (all types)
GET /v2/groups/{group_id}/artifacts/{artifact_type} (filtered by type)

Returns all artifacts shared with a group, with optional filtering by artifact type.

Authorization:

• Only group members can access this endpoint

Query Parameters:

• limit: Maximum results (default: 100, max: 1000)
• offset: Pagination offset (default: 0)

Example Response:

{
  "total": 25,
  "limit": 100,
  "offset": 0,
  "artifacts": [
    {
      "artifact_id": "dataset-123",
      "artifact_type": "dataset",
      "artifact_name": "Satellite Imagery 2026",
      "granted_by": "owner@example.com",
      "granted_at": "2026-05-01T10:30:00Z",
      "created_by": "owner@example.com",
      "created_at": "2026-04-15T08:00:00Z"
    }
  ]
}

Files Modified

gfmstudio/groups/schemas.py

• Added GroupSharingInfo schema for group sharing details
• Added ArtifactSharingDetail schema for artifact details
• Added ArtifactSharingListResponse schema for paginated responses

gfmstudio/groups/api.py

• Created new artifacts_router for artifact-centric endpoints
• Implemented list_artifact_groups() endpoint
• Implemented shared _list_group_artifacts_impl() function
• Implemented list_group_artifacts_all() endpoint (no filter)
• Implemented list_group_artifacts_by_type() endpoint (with filter)

gfmstudio/main.py

• Registered artifacts_router with /v2 prefix

Technical Details

Authorization Model

• Endpoint 1: Artifact owners see everything; non-owners see only their groups
• Endpoint 2: Group members only; non-members get 403 Forbidden

Performance Optimizations

• Efficient SQL queries with proper joins
• Batch querying by artifact type to minimize database calls
• Leverages existing indexes on ArtifactPermission table

Error Handling

• 400: Invalid artifact type
• 403: Unauthorized access (not owner/member)
• 404: Artifact or group not found

ID Type Compatibility

• Handles both UUID and string artifact IDs correctly
• Reuses existing _convert_artifact_id_for_query() helper

Usage Examples

Check which groups can access a dataset

curl -X GET "/v2/artifacts/dataset/dataset-123/groups" \
  -H "Authorization: Bearer <token>"

List all artifacts shared with a group

curl -X GET "/v2/groups/{group_id}/artifacts?limit=50&offset=0" \
  -H "Authorization: Bearer <token>"

List only models shared with a group

curl -X GET "/v2/groups/{group_id}/artifacts/model" \
  -H "Authorization: Bearer <token>"

Backward Compatibility

✅ No breaking changes

• All existing endpoints remain unchanged
• New endpoints use separate router paths
• Existing database schema is preserved

Database Impact

✅ No migrations required

• Uses existing ArtifactPermission, Group, and GroupMember tables
• Leverages existing indexes for optimal performance
• No new tables or columns needed

Testing

The implementation includes comprehensive error handling and follows existing patterns:

• Reuses existing helper functions (_require_group_member, _convert_artifact_id_for_query)
• Follows established authorization patterns
• Uses existing ARTIFACT_TYPE_TO_MODEL mapping
• Consistent error responses with other endpoints

Documentation

• Implementation plan: docs/artifact_sharing_endpoints_plan.md
• Technical summary: IMPLEMENTATION_SUMMARY.md
• Migration guide: MIGRATION_INSTRUCTIONS.md (for unrelated pre-existing issue)

Future Enhancements

Potential follow-up improvements:

• Add filtering by granted_by user
• Add date range filtering for granted_at
• Add sorting options for artifact lists
• Add bulk operations for sharing/unsharing

---

Resolves: Request for artifact sharing visibility endpoints
Type: Feature
Breaking Change: No
Database Migration: No