Merge pull request #355 from MuckRock/organization-collective

Add resource sharing for organization collectives

Author: duckduckgrayduck

.github/workflows/lambda.yml

@@ -1,7 +1,7 @@
 name: Post-Deploy Lambda
 
 on:
-  deployment:
+  deployment_status:
 
 jobs:
   deploy-lambdas:
@@ -11,14 +11,20 @@ jobs:
 
       - name: Show deployment info
         run: |
-          echo "Deployment environment: $DEPLOYMENT_ENVIRONMENT"
+          echo "Deployment environment: ${{ github.event.deployment.environment }}"
 
-      - name: Run Lambda deploy
+      - name: Run Lambda production deploy
+        if: >
+          github.event.deployment.environment == 'documentcloud-prod' &&
+          github.event.deployment_status.state == 'success'
         run: |
-          if [[ "$DEPLOYMENT_ENVIRONMENT" == "documentcloud-staging" ]]; then
-            echo "Deploying staging lambda updates"
-            bash config/aws/lambda/codeship_deploy_lambdas.sh staging-lambda --staging
-          else
-            echo "Deploying production lambda updates"
-            bash config/aws/lambda/codeship_deploy_lambdas.sh prod-lambda
-          fi
+          echo "Deploying production lambda updates"
+          bash config/aws/lambda/codeship_deploy_lambdas.sh prod-lambda
+
+      - name: Run Lambda staging deploy
+        if: >
+          github.event.deployment.environment == 'documentcloud-staging' &&
+          github.event.deployment_status.state == 'success'
+        run: |
+          echo "Deploying staging lambda updates"
+          bash config/aws/lambda/codeship_deploy_lambdas.sh staging-lambda --staging

documentcloud/organizations/migrations/0018_alter_organization_merged.py

@@ -0,0 +1,20 @@
+# Generated by Django 4.2.2 on 2025-12-22 21:06
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('organizations', '0017_organization_merged'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='organization',
+            name='merged',
+            field=models.ForeignKey(blank=True, help_text='The organization this organization was merged in to', null=True, on_delete=django.db.models.deletion.PROTECT, related_name='+', to=settings.SQUARELET_ORGANIZATION_MODEL),
+        ),
+    ]

documentcloud/organizations/migrations/0019_organization_members_organization_parent_and_more.py

@@ -0,0 +1,30 @@
+# Generated by Django 4.2.2 on 2025-12-22 21:32
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('organizations', '0018_alter_organization_merged'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='organization',
+            name='members',
+            field=models.ManyToManyField(blank=True, help_text='Organizations which are members of this organization (useful for trade associations or other member groups)', related_name='groups', to=settings.SQUARELET_ORGANIZATION_MODEL),
+        ),
+        migrations.AddField(
+            model_name='organization',
+            name='parent',
+            field=models.ForeignKey(blank=True, help_text='The parent organization', null=True, on_delete=django.db.models.deletion.PROTECT, related_name='children', to=settings.SQUARELET_ORGANIZATION_MODEL, verbose_name='parent'),
+        ),
+        migrations.AddField(
+            model_name='organization',
+            name='share_resources',
+            field=models.BooleanField(default=True, help_text='Share resources (subscriptions, credits) with all children and member organizations. Global toggle that applies to all relationships.', verbose_name='share resources'),
+        ),
+    ]

documentcloud/organizations/models.py

@@ -130,6 +130,19 @@ def merge(self, uuid):
         self.addons.update(organization=other)
         self.visual_addons.update(organization=other)
 
+        # transfer children to the other organization
+        self.children.update(parent=other)
+
+        # transfer group memberships
+        groups = self.groups.all()
+        other.groups.add(*groups)
+        self.groups.clear()
+
+        # transfer members
+        members = self.members.all()
+        other.members.add(*members)
+        self.members.clear()
+
         self.merged = other
 
     def calc_ai_credits_per_month(self, users):
@@ -143,24 +156,80 @@ def calc_ai_credits_per_month(self, users):
 
     @transaction.atomic
     def use_ai_credits(self, amount, user_id, note):
-        """Try to deduct AI credits from the organization's balance"""
+        """Try to deduct AI credits from the organization's balance
+
+        Consumes AI credits in priority order:
+        1. Own monthly AI credits
+        2. Own regular (purchased) AI credits
+        3. Parent monthly AI credits (if parent.share_resources=True)
+        4. Parent regular AI credits (if parent.share_resources=True)
+        5. Group monthly AI credits (for each group where group.share_resources=True)
+        6. Group regular AI credits (for each group where group.share_resources=True)
+
+        Args:
+            amount: Number of AI credits to consume
+            user_id: ID of the user consuming the credits
+            note: Description of what the credits are being used for
+
+        Returns:
+            dict: {"monthly": count, "regular": count} - breakdown of consumed credits
+
+        Raises:
+            InsufficientAICreditsError: If not enough AI credits available across
+            all sources
+        """
         initial_amount = amount
         ai_credit_count = {"monthly": 0, "regular": 0}
-        organization = Organization.objects.select_for_update().get(pk=self.pk)
-
-        ai_credit_count["monthly"] = min(amount, organization.monthly_ai_credits)
-        amount -= ai_credit_count["monthly"]
 
-        ai_credit_count["regular"] = min(amount, organization.number_ai_credits)
-        amount -= ai_credit_count["regular"]
+        # Lock this organization and related organizations for update to prevent
+        # race conditions
+        organization = Organization.objects.select_for_update().get(pk=self.pk)
+        if organization.parent and organization.parent.share_resources:
+            parent = Organization.objects.select_for_update().get(
+                pk=organization.parent_id
+            )
+        else:
+            parent = None
+        groups = organization.groups.filter(share_resources=True).select_for_update()
+
+        def deduct_credits(amount, organization, field):
+            """Helper to deduct AI credits from a specific field on an organization"""
+            # Calculate how much to deduct: take up to the amount requested,
+            # but no more than what's available in this field
+            deduct_amount = min(amount, getattr(organization, field))
+            amount -= deduct_amount
+            setattr(organization, field, getattr(organization, field) - deduct_amount)
+            # Return remaining amount needed and how much we deducted
+            return amount, deduct_amount
+
+        # Build list of organizations to consume from in priority order
+        organizations = [organization]
+        if parent:
+            organizations.append(parent)
+        organizations.extend(groups)
+
+        # Consume AI credits from each organization in priority order
+        for current_organization in organizations:
+            # For each organization, consume monthly credits first, then regular
+            for field, count in [
+                ("monthly_ai_credits", "monthly"),
+                ("number_ai_credits", "regular"),
+            ]:
+                amount, deduct_amount = deduct_credits(
+                    amount, current_organization, field
+                )
+                ai_credit_count[count] += deduct_amount
+                if amount == 0:
+                    break
+            current_organization.save()
+            if amount == 0:
+                break
 
         if amount > 0:
+            # Raising an error here will cancel the current atomic transaction
+            # No changes to the organizations will be committed to the database
             raise InsufficientAICreditsError(amount)
 
-        organization.monthly_ai_credits -= ai_credit_count["monthly"]
-        organization.number_ai_credits -= ai_credit_count["regular"]
-        organization.save()
-
         organization.ai_credit_logs.create(
             user_id=user_id,
             organization=organization,
@@ -170,6 +239,41 @@ def use_ai_credits(self, amount, user_id, note):
 
         return ai_credit_count
 
+    def get_total_number_ai_credits(self):
+        """Get total number AI credits including parent and groups"""
+        number_ai_credits = self.number_ai_credits
+        if self.parent and self.parent.share_resources:
+            number_ai_credits += self.parent.number_ai_credits
+        for group in self.groups.filter(share_resources=True):
+            number_ai_credits += group.number_ai_credits
+        return number_ai_credits
+
+    def get_total_monthly_ai_credits(self):
+        """Get total monthly AI credits remaining including parent and groups"""
+        monthly_ai_credits = self.monthly_ai_credits
+        if self.parent and self.parent.share_resources:
+            monthly_ai_credits += self.parent.monthly_ai_credits
+        for group in self.groups.filter(share_resources=True):
+            monthly_ai_credits += group.monthly_ai_credits
+        return monthly_ai_credits
+
+    def get_total_monthly_ai_credits_allowance(self):
+        """
+        Get the total monthly AI credits allowance, including parent and shared groups.
+        This is the amount that monthly_credits will reset to each month.
+        """
+        total = self.ai_credits_per_month
+
+        # Include parent if it shares resources
+        if self.parent and self.parent.share_resources:
+            total += self.parent.ai_credits_per_month
+
+        # Include groups that share resources
+        for group in self.groups.filter(share_resources=True):
+            total += group.ai_credits_per_month
+
+        return total
+
 
 class AICreditLog(models.Model):
     """Log usage of AI Credits"""

documentcloud/organizations/serializers.py

@@ -19,21 +19,23 @@ class OrganizationSerializer(serializers.ModelSerializer):
             "Only viewable by organization members."
         ),
     )
-    monthly_credits = serializers.IntegerField(
-        source="monthly_ai_credits",
+    monthly_credits = serializers.SerializerMethodField(
+        label=_("Monthly Credits"),
         read_only=True,
         help_text=(
             "Number of monthly premium credits this organization has left. "
             "This will reset to monthly_credit_allowance on credit_reset_date. "
+            "This includes shared credits from parents and groups. "
             "Only viewable be organization members."
         ),
     )
-    purchased_credits = serializers.IntegerField(
-        source="number_ai_credits",
+    purchased_credits = serializers.SerializerMethodField(
+        label=_("Purchased Credits"),
         read_only=True,
         help_text=(
             "Number of purchased premium credits. "
             "These do not reset or expire. "
+            "This includes shared credits from parents and groups. "
             "Only viewable by organization members."
         ),
     )
@@ -45,8 +47,7 @@ class OrganizationSerializer(serializers.ModelSerializer):
             "Only viewable by organization members."
         ),
     )
-    monthly_credit_allowance = serializers.IntegerField(
-        source="ai_credits_per_month",
+    monthly_credit_allowance = serializers.SerializerMethodField(
         read_only=True,
         help_text=(
             "The amount of credits that monthly_credits will reset to. "
@@ -81,10 +82,16 @@ def to_representation(self, instance):
         if "monthly_credits" in self.fields:
             # skip checks if we have already removed the fields
             request = self.context and self.context.get("request")
+            view = self.context and self.context.get("view")
+            action = view.action if view else None
             user = request and request.user
             is_org = isinstance(instance, Organization)
             if not (
-                is_org and user and user.is_authenticated and instance.has_member(user)
+                is_org
+                and user
+                and user.is_authenticated
+                and instance.has_member(user)
+                and action == "retrieve"
             ):
                 # only members may see AI credit information
                 self.fields.pop("monthly_credits")
@@ -102,6 +109,15 @@ def get_plan(self, obj):
         else:
             return "Free"
 
+    def get_monthly_credits(self, obj):
+        return obj.get_total_monthly_ai_credits()
+
+    def get_purchased_credits(self, obj):
+        return obj.get_total_number_ai_credits()
+
+    def get_monthly_credit_allowance(self, obj):
+        return obj.get_total_monthly_ai_credits_allowance()
+
 
 class AICreditSerializer(serializers.Serializer):
     """Serializer for the AI credit endpoint"""