AI Agent for Nonprofits: Automate Fundraising, Donor Management & Impact Reporting

Nonprofit organizations face a paradox that grows sharper every year: the demand for transparency, measurable impact, and personalized donor engagement increases while budgets for administrative overhead remain razor-thin. Development directors juggle spreadsheets of donor histories, program managers scramble to compile quarterly funder reports, and volunteer coordinators rely on gut instinct to match people to projects. The result is talented professionals spending sixty percent of their time on tasks a machine could handle — time that should be spent building relationships and delivering on mission.

AI agents change this equation entirely. Unlike static automation tools that follow rigid if-then rules, an AI agent for nonprofits reasons about context, learns from patterns in your data, and takes autonomous action across fundraising, grant management, volunteer coordination, and impact reporting. It can analyze a donor's giving history at 2 AM, draft a grant narrative at 6 AM, and generate a board-ready impact dashboard before your morning standup.

This guide walks through six critical areas where AI agents deliver measurable value for nonprofit organizations, complete with production-ready Python code you can adapt to your own tech stack. Whether you run a community food bank or a global humanitarian organization, these patterns scale to match your complexity.

1. Donor Intelligence & Prospecting

Every nonprofit sits on a goldmine of donor data — but most organizations barely scratch the surface. The average development team uses giving history alone to prioritize outreach, ignoring the wealth of publicly available signals that reveal a donor's true capacity and inclination to give. AI agents transform donor intelligence by continuously ingesting, correlating, and scoring data from multiple sources to surface your highest-value prospects.

Wealth Screening from Public Records

Traditional wealth screening services charge nonprofits thousands of dollars per batch and deliver static reports that go stale within months. An AI agent performs continuous wealth screening by monitoring public records, real estate transactions, SEC filings, and business registrations. When a mid-level donor closes on a $2.3 million property, your agent flags them as a major gift prospect before your next cultivation meeting.

Propensity Scoring with RFM Analysis

Recency, Frequency, and Monetary (RFM) analysis has been a staple of fundraising analytics for decades, but applying it consistently across your entire donor base requires automation. The AI agent computes RFM scores, layers in engagement signals — email opens, event attendance, volunteer hours, social media interactions — and produces a composite propensity score that predicts both likelihood and capacity to give.

Major Gift Prospect Identification

The difference between a good development team and a great one is the ability to identify major gift prospects before they self-identify. Your AI agent combines wealth indicators, engagement patterns, affinity signals (board memberships at similar organizations, foundation affiliations, public statements of support), and giving trajectory to rank prospects. It then generates personalized cultivation plans with recommended touchpoints, ask amounts, and timing.

Peer Screening and Network Analysis

Donors don't exist in isolation. An AI agent maps social networks, board connections, corporate affiliations, and event co-attendance to identify peer clusters. When one member of a peer group makes a major gift, the agent automatically elevates the giving potential of connected individuals and suggests peer-to-peer solicitation strategies.

import pandas as pd
import numpy as np
from datetime import datetime, timedelta
from dataclasses import dataclass


@dataclass
class DonorProfile:
    donor_id: str
    name: str
    rfm_score: float
    wealth_indicators: dict
    engagement_score: float
    propensity_score: float
    recommended_ask: float
    cultivation_stage: str


class DonorIntelligenceAgent:
    """AI agent for donor prospecting and wealth screening."""

    def __init__(self, crm_client, wealth_api, ai_client):
        self.crm = crm_client
        self.wealth_api = wealth_api
        self.ai = ai_client
        self.rfm_weights = {"recency": 0.30, "frequency": 0.25, "monetary": 0.45}

    def compute_rfm_scores(self, donations_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate RFM scores with quintile-based segmentation."""
        now = pd.Timestamp.now()
        rfm = donations_df.groupby("donor_id").agg(
            recency=("gift_date", lambda x: (now - x.max()).days),
            frequency=("gift_id", "count"),
            monetary=("amount", "sum"),
        )
        for col in ["frequency", "monetary"]:
            rfm[f"{col}_score"] = pd.qcut(rfm[col], 5, labels=[1, 2, 3, 4, 5])
        rfm["recency_score"] = pd.qcut(
            rfm["recency"], 5, labels=[5, 4, 3, 2, 1]
        )
        rfm["composite_score"] = (
            rfm["recency_score"].astype(float) * self.rfm_weights["recency"]
            + rfm["frequency_score"].astype(float) * self.rfm_weights["frequency"]
            + rfm["monetary_score"].astype(float) * self.rfm_weights["monetary"]
        )
        return rfm

    def screen_wealth_indicators(self, donor_id: str) -> dict:
        """Pull public wealth signals for a donor."""
        real_estate = self.wealth_api.get_property_records(donor_id)
        sec_filings = self.wealth_api.get_sec_filings(donor_id)
        business_reg = self.wealth_api.get_business_registrations(donor_id)

        total_real_estate = sum(p["assessed_value"] for p in real_estate)
        stock_holdings = sum(f["market_value"] for f in sec_filings)
        business_value = sum(b["estimated_revenue"] for b in business_reg)

        capacity_estimate = (total_real_estate + stock_holdings + business_value) * 0.03
        return {
            "real_estate_value": total_real_estate,
            "stock_holdings": stock_holdings,
            "business_interests": business_value,
            "estimated_annual_capacity": capacity_estimate,
            "data_confidence": self._confidence_level(real_estate, sec_filings),
        }

    def identify_major_gift_prospects(self, min_capacity: float = 25000) -> list:
        """Surface top prospects combining RFM, wealth, and engagement."""
        donations = self.crm.export_donations(years=5)
        rfm_scores = self.compute_rfm_scores(donations)
        prospects = []

        for donor_id in rfm_scores[rfm_scores["composite_score"] >= 3.5].index:
            wealth = self.screen_wealth_indicators(donor_id)
            engagement = self.crm.get_engagement_score(donor_id)

            if wealth["estimated_annual_capacity"] >= min_capacity:
                propensity = (
                    rfm_scores.loc[donor_id, "composite_score"] * 0.35
                    + (engagement / 100) * 5 * 0.35
                    + (wealth["data_confidence"] / 100) * 5 * 0.30
                )
                ask_amount = self._calculate_ask(donor_id, wealth, donations)
                prospects.append(DonorProfile(
                    donor_id=donor_id,
                    name=self.crm.get_donor_name(donor_id),
                    rfm_score=rfm_scores.loc[donor_id, "composite_score"],
                    wealth_indicators=wealth,
                    engagement_score=engagement,
                    propensity_score=round(propensity, 2),
                    recommended_ask=ask_amount,
                    cultivation_stage=self._assign_stage(propensity),
                ))

        return sorted(prospects, key=lambda p: p.propensity_score, reverse=True)

    def _calculate_ask(self, donor_id, wealth, donations) -> float:
        """Determine optimal ask based on giving history and capacity."""
        donor_gifts = donations[donations["donor_id"] == donor_id]
        largest_gift = donor_gifts["amount"].max()
        avg_gift = donor_gifts["amount"].mean()
        capacity = wealth["estimated_annual_capacity"]
        return round(min(capacity * 0.15, max(largest_gift * 1.5, avg_gift * 3)), -2)

    def _assign_stage(self, propensity: float) -> str:
        if propensity >= 4.0:
            return "ready_to_solicit"
        elif propensity >= 3.0:
            return "active_cultivation"
        elif propensity >= 2.0:
            return "discovery"
        return "identification"

    def _confidence_level(self, real_estate, sec_filings) -> float:
        score = 0
        if real_estate:
            score += 40
        if sec_filings:
            score += 40
        score += min(len(real_estate) + len(sec_filings), 20)
        return min(score, 100)

2. Fundraising Campaign Optimization

Running a fundraising campaign today means managing dozens of variables simultaneously: which donors receive which appeals, through which channels, with what messaging, at what ask amount, and at what time. Most nonprofits rely on broad segmentation — lapsed donors get one letter, active donors get another. An AI agent optimizes every variable at the individual donor level, treating each appeal as a personalized conversation rather than a mass mailing.

Appeal Timing Optimization

Donor responsiveness varies dramatically by segment and individual. Year-end givers respond to December appeals, but the exact optimal send date varies by timezone, past response patterns, and even day-of-week preferences. An AI agent analyzes historical response data to determine the ideal send time for each donor segment and, as data accumulates, for each individual donor.

Channel Attribution and Optimization

Multi-channel fundraising creates attribution challenges that most nonprofits never solve. A donor receives an email, ignores it, sees a social media post, then donates through direct mail two weeks later. An AI agent implements multi-touch attribution modeling, assigning fractional credit across channels to reveal the true cost-per-dollar-raised for each channel and the optimal channel mix for each donor segment.

A/B Testing Automation

Manual A/B testing is slow and statistically unreliable at the sample sizes most nonprofits work with. An AI agent implements multi-armed bandit algorithms that dynamically allocate traffic to winning variants, reaching statistical significance faster and minimizing the cost of testing. It simultaneously tests subject lines, ask amounts, imagery, and copy — running multivariate experiments that would be impossible to manage manually.

Gift Ask Optimization

The ask amount is the single most impactful variable in a fundraising appeal. Ask too low and you leave money on the table; ask too high and you suppress response rates. An AI agent generates custom ask strings for each donor based on their giving history, wealth indicators, peer giving levels, and campaign context — replacing generic ask ladders with precision-calibrated requests.

from typing import Optional
from enum import Enum
import random
import math


class Channel(Enum):
    EMAIL = "email"
    DIRECT_MAIL = "direct_mail"
    SMS = "sms"
    SOCIAL = "social"
    PHONE = "phone"
    EVENT = "event"


class FundraisingOptimizationAgent:
    """AI agent for multi-channel fundraising campaign optimization."""

    def __init__(self, crm_client, email_platform, ai_client):
        self.crm = crm_client
        self.email = email_platform
        self.ai = ai_client
        self.bandit_state = {}

    def optimize_appeal_timing(self, campaign_id: str, segment: str) -> dict:
        """Determine optimal send times per donor segment."""
        historical = self.crm.get_campaign_responses(segment, months=24)
        response_by_hour = {}
        response_by_dow = {}

        for response in historical:
            hour = response["opened_at"].hour
            dow = response["opened_at"].weekday()
            response_by_hour.setdefault(hour, []).append(response["converted"])
            response_by_dow.setdefault(dow, []).append(response["converted"])

        best_hour = max(response_by_hour, key=lambda h: np.mean(response_by_hour[h]))
        best_dow = max(response_by_dow, key=lambda d: np.mean(response_by_dow[d]))

        return {
            "segment": segment,
            "optimal_day": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"][best_dow],
            "optimal_hour": f"{best_hour}:00",
            "expected_lift": self._estimate_timing_lift(historical, best_hour, best_dow),
        }

    def generate_ask_strings(self, donor_id: str, campaign_type: str) -> dict:
        """Create personalized ask amounts based on donor giving profile."""
        history = self.crm.get_giving_history(donor_id)
        last_gift = history[-1]["amount"] if history else 0
        avg_gift = np.mean([g["amount"] for g in history]) if history else 50
        max_gift = max([g["amount"] for g in history], default=100)
        gifts_this_year = sum(1 for g in history if g["date"].year == datetime.now().year)

        if campaign_type == "annual_fund":
            base = max(last_gift, avg_gift)
            asks = [round(base * 0.8, -1), round(base, -1), round(base * 1.25, -1)]
        elif campaign_type == "capital":
            base = max_gift * 2
            asks = [round(base * 0.75, -1), round(base, -1), round(base * 1.5, -1)]
        elif campaign_type == "emergency":
            base = avg_gift * 0.6
            asks = [round(base * 0.5, -1), round(base, -1), round(base * 1.5, -1)]
        else:
            base = avg_gift
            asks = [round(base * 0.75, -1), round(base, -1), round(base * 1.5, -1)]

        asks = [max(a, 25) for a in asks]
        return {
            "donor_id": donor_id,
            "ask_low": asks[0],
            "ask_mid": asks[1],
            "ask_high": asks[2],
            "ask_string": f"${asks[0]:,.0f} / ${asks[1]:,.0f} / ${asks[2]:,.0f}",
            "recommended_default": asks[1],
        }

    def run_multivariate_bandit(self, campaign_id: str, variants: list) -> dict:
        """Thompson Sampling bandit for A/B testing fundraising variants."""
        if campaign_id not in self.bandit_state:
            self.bandit_state[campaign_id] = {
                v["id"]: {"alpha": 1, "beta": 1} for v in variants
            }

        state = self.bandit_state[campaign_id]
        samples = {
            vid: random.betavariate(s["alpha"], s["beta"])
            for vid, s in state.items()
        }
        selected = max(samples, key=samples.get)
        return {
            "selected_variant": selected,
            "exploration_rate": self._exploration_rate(state),
            "variant_probabilities": {
                vid: round(s["alpha"] / (s["alpha"] + s["beta"]), 4)
                for vid, s in state.items()
            },
        }

    def update_bandit(self, campaign_id: str, variant_id: str, converted: bool):
        """Update bandit state with observed outcome."""
        state = self.bandit_state[campaign_id][variant_id]
        if converted:
            state["alpha"] += 1
        else:
            state["beta"] += 1

    def compute_channel_attribution(self, donor_id: str, gift_id: str) -> dict:
        """Multi-touch attribution across fundraising channels."""
        touchpoints = self.crm.get_touchpoints(donor_id, before_gift=gift_id)
        if not touchpoints:
            return {}

        total_weight = 0
        weights = {}
        for i, tp in enumerate(touchpoints):
            days_before = (touchpoints[-1]["date"] - tp["date"]).days
            decay = math.exp(-0.05 * days_before)
            position_weight = 0.4 if i == 0 else (0.4 if i == len(touchpoints) - 1 else 0.2)
            w = decay * position_weight
            weights[tp["channel"]] = weights.get(tp["channel"], 0) + w
            total_weight += w

        return {
            ch: round(w / total_weight, 4)
            for ch, w in weights.items()
        }

    def _estimate_timing_lift(self, historical, best_hour, best_dow) -> float:
        optimal = [r for r in historical if r["opened_at"].hour == best_hour]
        overall_rate = np.mean([r["converted"] for r in historical])
        optimal_rate = np.mean([r["converted"] for r in optimal]) if optimal else overall_rate
        return round((optimal_rate - overall_rate) / max(overall_rate, 0.001) * 100, 1)

    def _exploration_rate(self, state: dict) -> float:
        total = sum(s["alpha"] + s["beta"] for s in state.values())
        return round(max(0.05, 1.0 - total / 1000), 4)

3. Grant Management

Grants represent the highest-stakes fundraising activity for most nonprofits. A single successful proposal can fund an entire program for years. Yet grant management is also the most labor-intensive — from identifying aligned funders to writing proposals, tracking compliance, and reconciling budgets. An AI agent transforms grant management from a reactive scramble into a proactive, systematic operation.

Grant Opportunity Matching

The grant landscape is vast and fragmented. Federal databases, foundation directories, corporate giving programs, and community foundations each have their own portals and formats. An AI agent continuously scans these sources, extracts eligibility criteria and funding priorities, and scores each opportunity against your organization's mission, programs, and capacity. Instead of manually reviewing hundreds of RFPs, your grants team receives a ranked shortlist of high-alignment opportunities with match explanations.

Proposal Writing Assistance

Grant proposals demand a specific blend of storytelling, data, and compliance with funder requirements. An AI agent extracts requirements from the RFP, maps them to your existing program data, and generates draft narratives that address each evaluation criterion. It pulls outcomes data from your impact measurement system, budget figures from your finance system, and organizational capacity statements from previous successful proposals — assembling a coherent first draft in minutes rather than weeks.

Compliance Tracking

Post-award compliance is where many nonprofits stumble. Missed reporting deadlines, incomplete documentation, and budget deviations can jeopardize current funding and future eligibility. An AI agent maintains a compliance calendar, monitors spending against budget categories, flags variances before they become problems, and sends automated reminders to program staff responsible for data collection.

Budget Reconciliation

Grant budgets require meticulous tracking of expenditures against approved line items. An AI agent reconciles transactions from your accounting system against grant budget categories, identifies miscodings, calculates burn rates, and projects whether you'll fully expend each grant by its end date — giving you time to request no-cost extensions or reallocations.

from datetime import date, timedelta
from typing import List


class GrantManagementAgent:
    """AI agent for grant discovery, proposals, and compliance."""

    def __init__(self, grants_db, finance_system, ai_client):
        self.grants_db = grants_db
        self.finance = finance_system
        self.ai = ai_client

    def match_grant_opportunities(self, org_profile: dict, min_score: float = 0.65) -> list:
        """Score grant opportunities against organizational alignment."""
        opportunities = self.grants_db.get_open_opportunities()
        matches = []

        for opp in opportunities:
            mission_sim = self._compute_similarity(
                org_profile["mission_keywords"], opp["focus_areas"]
            )
            geo_match = 1.0 if self._geo_overlap(org_profile["service_area"], opp["geo_focus"]) else 0.3
            budget_fit = self._budget_fit_score(
                org_profile["annual_budget"], opp["eligible_budget_range"]
            )
            track_record = self._track_record_score(
                org_profile["past_grants"], opp["funder_id"]
            )

            composite = (
                mission_sim * 0.40
                + geo_match * 0.20
                + budget_fit * 0.20
                + track_record * 0.20
            )

            if composite >= min_score:
                matches.append({
                    "opportunity_id": opp["id"],
                    "funder": opp["funder_name"],
                    "title": opp["title"],
                    "amount_range": opp["amount_range"],
                    "deadline": opp["deadline"],
                    "alignment_score": round(composite, 3),
                    "score_breakdown": {
                        "mission": round(mission_sim, 3),
                        "geography": round(geo_match, 3),
                        "budget_fit": round(budget_fit, 3),
                        "track_record": round(track_record, 3),
                    },
                })

        return sorted(matches, key=lambda m: m["alignment_score"], reverse=True)

    def draft_proposal_narrative(self, opportunity_id: str, program_id: str) -> dict:
        """Generate grant proposal draft from program data and RFP requirements."""
        rfp = self.grants_db.get_rfp_details(opportunity_id)
        program = self.grants_db.get_program_data(program_id)
        outcomes = self.grants_db.get_outcomes_data(program_id, years=3)
        budget = self.finance.get_program_budget(program_id)

        requirements = self._extract_requirements(rfp)
        sections = {}

        for req in requirements:
            prompt = (
                f"Write a grant proposal section addressing: {req['criterion']}\n"
                f"Program data: {program}\nOutcomes: {outcomes}\n"
                f"Word limit: {req.get('word_limit', 500)}\n"
                f"Tone: Professional, evidence-based, compelling"
            )
            sections[req["section_name"]] = self.ai.generate(prompt)

        return {
            "opportunity_id": opportunity_id,
            "sections": sections,
            "budget_narrative": self._generate_budget_narrative(budget, rfp),
            "compliance_checklist": self._build_checklist(requirements),
        }

    def track_compliance(self, grant_id: str) -> dict:
        """Monitor grant compliance: deadlines, spend, deliverables."""
        grant = self.grants_db.get_grant(grant_id)
        reports = self.grants_db.get_reporting_schedule(grant_id)
        spend = self.finance.get_grant_expenditures(grant_id)
        budget = grant["approved_budget"]

        today = date.today()
        upcoming_deadlines = [
            r for r in reports
            if today <= r["due_date"] <= today + timedelta(days=60)
        ]

        total_budget = sum(budget.values())
        total_spent = sum(spend.values())
        elapsed_pct = self._elapsed_percentage(grant["start_date"], grant["end_date"])
        burn_rate = total_spent / max(total_budget, 1)

        line_item_variances = {}
        for category, approved in budget.items():
            actual = spend.get(category, 0)
            variance_pct = ((actual - approved * elapsed_pct) / max(approved, 1)) * 100
            line_item_variances[category] = {
                "approved": approved,
                "spent": actual,
                "variance_pct": round(variance_pct, 1),
                "alert": abs(variance_pct) > 15,
            }

        return {
            "grant_id": grant_id,
            "overall_burn_rate": round(burn_rate * 100, 1),
            "elapsed_pct": round(elapsed_pct * 100, 1),
            "on_track": abs(burn_rate - elapsed_pct) < 0.10,
            "upcoming_deadlines": upcoming_deadlines,
            "line_item_variances": line_item_variances,
            "alerts": self._generate_compliance_alerts(
                burn_rate, elapsed_pct, line_item_variances, upcoming_deadlines
            ),
        }

    def _compute_similarity(self, org_keywords, opp_areas) -> float:
        org_set = set(k.lower() for k in org_keywords)
        opp_set = set(a.lower() for a in opp_areas)
        if not org_set or not opp_set:
            return 0.0
        return len(org_set & opp_set) / len(org_set | opp_set)

    def _geo_overlap(self, service_area, geo_focus) -> bool:
        return bool(set(service_area) & set(geo_focus))

    def _budget_fit_score(self, annual_budget, eligible_range) -> float:
        low, high = eligible_range
        if low <= annual_budget <= high:
            return 1.0
        if annual_budget < low:
            return max(0, 1 - (low - annual_budget) / low)
        return max(0, 1 - (annual_budget - high) / high)

    def _track_record_score(self, past_grants, funder_id) -> float:
        funder_grants = [g for g in past_grants if g["funder_id"] == funder_id]
        if not funder_grants:
            return 0.3
        success_rate = sum(1 for g in funder_grants if g["funded"]) / len(funder_grants)
        return 0.3 + success_rate * 0.7

    def _elapsed_percentage(self, start, end) -> float:
        total = (end - start).days
        elapsed = (date.today() - start).days
        return min(max(elapsed / max(total, 1), 0), 1.0)

    def _extract_requirements(self, rfp) -> list:
        return rfp.get("evaluation_criteria", [])

    def _generate_budget_narrative(self, budget, rfp) -> str:
        return f"Budget narrative for {sum(budget.values()):,.0f} total request."

    def _build_checklist(self, requirements) -> list:
        return [{"item": r["section_name"], "complete": False} for r in requirements]

    def _generate_compliance_alerts(self, burn, elapsed, variances, deadlines) -> list:
        alerts = []
        if burn > elapsed + 0.15:
            alerts.append({"level": "warning", "message": "Spending ahead of schedule"})
        if burn < elapsed - 0.20:
            alerts.append({"level": "warning", "message": "Underspending may risk clawback"})
        for cat, v in variances.items():
            if v["alert"]:
                alerts.append({"level": "info", "message": f"{cat}: {v['variance_pct']}% variance"})
        for d in deadlines:
            if (d["due_date"] - date.today()).days <= 14:
                alerts.append({"level": "urgent", "message": f"Report due: {d['due_date']}"})
        return alerts

4. Volunteer Management

Volunteers are the backbone of most nonprofit operations, yet managing them effectively remains one of the sector's biggest challenges. Matching the right volunteer to the right opportunity, scheduling around availability constraints, predicting who's at risk of disengaging, and measuring the actual impact of volunteer contributions — these tasks overwhelm manual processes. An AI agent brings data-driven precision to volunteer management.

Skills-Based Matching

Traditional volunteer signup forms capture basic availability and interest. An AI agent builds rich volunteer profiles by analyzing skills, experience, certifications, past performance ratings, and stated preferences. It then matches volunteers to opportunities using multi-factor scoring that considers skill alignment, schedule compatibility, geographic proximity, and personal growth goals — ensuring every placement maximizes both organizational value and volunteer satisfaction.

Scheduling Optimization

Volunteer scheduling is a constraint satisfaction problem that grows exponentially with the number of volunteers and shifts. An AI agent solves this by considering availability windows, skill requirements per shift, maximum consecutive hours, travel time between locations, and volunteer preferences. It handles cancellations gracefully by identifying qualified backups in real-time and sending targeted recruitment messages.

Retention Prediction

Volunteer turnover costs nonprofits an estimated $1,500-$3,000 per volunteer in recruitment and training. An AI agent identifies at-risk volunteers by tracking engagement signals: declining hours, missed shifts, reduced communication, absence from social events, and sentiment in feedback surveys. It triggers personalized retention interventions — a thank-you note, a more challenging assignment, or a check-in call — before the volunteer quietly disappears.

Impact Tracking Per Volunteer

Volunteers want to know their contribution matters. An AI agent tracks individual impact metrics — meals served, students tutored, habitat acres restored, clients counseled — and generates personalized impact reports. These reports serve double duty: they make volunteers feel valued and provide data for grant reporting and donor communications.

from dataclasses import dataclass, field
from typing import List, Optional
from datetime import datetime, time


@dataclass
class Volunteer:
    volunteer_id: str
    name: str
    skills: List[str]
    availability: List[dict]
    max_hours_week: int
    location: tuple
    engagement_score: float = 0.0
    total_hours: float = 0.0
    retention_risk: str = "low"


@dataclass
class Opportunity:
    opportunity_id: str
    title: str
    required_skills: List[str]
    location: tuple
    shifts: List[dict]
    volunteers_needed: int


class VolunteerManagementAgent:
    """AI agent for volunteer matching, scheduling, and retention."""

    def __init__(self, volunteer_db, scheduling_engine, ai_client):
        self.db = volunteer_db
        self.scheduler = scheduling_engine
        self.ai = ai_client
        self.retention_thresholds = {
            "critical": 0.3, "high": 0.5, "moderate": 0.7
        }

    def match_volunteers(self, opportunity: Opportunity) -> list:
        """Score and rank volunteers for an opportunity."""
        candidates = self.db.get_available_volunteers(
            date_range=opportunity.shifts[0]["date"],
            location_radius=30,
            center=opportunity.location,
        )
        scored = []

        for vol in candidates:
            skill_match = self._skill_match_score(vol.skills, opportunity.required_skills)
            schedule_fit = self._schedule_fit(vol.availability, opportunity.shifts)
            distance = self._haversine(vol.location, opportunity.location)
            distance_score = max(0, 1 - distance / 30)
            reliability = self._reliability_score(vol.volunteer_id)

            composite = (
                skill_match * 0.35
                + schedule_fit * 0.25
                + distance_score * 0.15
                + reliability * 0.25
            )

            scored.append({
                "volunteer": vol,
                "match_score": round(composite, 3),
                "skill_match": round(skill_match, 3),
                "schedule_fit": round(schedule_fit, 3),
                "distance_km": round(distance, 1),
                "reliability": round(reliability, 3),
            })

        return sorted(scored, key=lambda s: s["match_score"], reverse=True)[
            :opportunity.volunteers_needed * 2
        ]

    def predict_retention_risk(self, volunteer_id: str) -> dict:
        """Predict volunteer churn risk from engagement signals."""
        activity = self.db.get_activity_log(volunteer_id, months=6)
        recent_3m = [a for a in activity if a["date"] >= datetime.now() - timedelta(days=90)]
        prior_3m = [a for a in activity if a["date"] < datetime.now() - timedelta(days=90)]

        recent_hours = sum(a["hours"] for a in recent_3m)
        prior_hours = sum(a["hours"] for a in prior_3m)
        hour_trend = (recent_hours - prior_hours) / max(prior_hours, 1)

        missed_shifts = sum(1 for a in recent_3m if a["status"] == "no_show")
        cancellations = sum(1 for a in recent_3m if a["status"] == "cancelled")
        feedback_sentiment = self._analyze_feedback_sentiment(volunteer_id)

        risk_score = 1.0
        risk_score -= max(hour_trend, 0) * 0.3
        risk_score += missed_shifts * 0.15
        risk_score += cancellations * 0.08
        risk_score -= (feedback_sentiment - 0.5) * 0.4
        risk_score = max(0, min(1, risk_score))

        if risk_score >= self.retention_thresholds["critical"]:
            risk_level = "critical" if risk_score >= 0.8 else "high"
        elif risk_score >= self.retention_thresholds["moderate"]:
            risk_level = "moderate"
        else:
            risk_level = "low"

        interventions = self._recommend_interventions(risk_level, hour_trend, feedback_sentiment)

        return {
            "volunteer_id": volunteer_id,
            "risk_score": round(risk_score, 3),
            "risk_level": risk_level,
            "signals": {
                "hour_trend": round(hour_trend, 2),
                "missed_shifts": missed_shifts,
                "cancellations": cancellations,
                "sentiment": round(feedback_sentiment, 2),
            },
            "recommended_interventions": interventions,
        }

    def generate_impact_report(self, volunteer_id: str) -> dict:
        """Create personalized impact report for a volunteer."""
        activity = self.db.get_activity_log(volunteer_id, months=12)
        total_hours = sum(a["hours"] for a in activity)
        programs = {}

        for a in activity:
            prog = a["program"]
            programs.setdefault(prog, {"hours": 0, "sessions": 0, "outcomes": []})
            programs[prog]["hours"] += a["hours"]
            programs[prog]["sessions"] += 1
            if a.get("outcomes"):
                programs[prog]["outcomes"].extend(a["outcomes"])

        impact_value = total_hours * 33.49  # Independent Sector hourly value

        return {
            "volunteer_id": volunteer_id,
            "period": "Last 12 months",
            "total_hours": round(total_hours, 1),
            "total_sessions": len(activity),
            "economic_value": round(impact_value, 2),
            "programs": programs,
            "milestones": self._identify_milestones(activity),
            "narrative": self._generate_impact_narrative(volunteer_id, total_hours, programs),
        }

    def _skill_match_score(self, vol_skills, required) -> float:
        if not required:
            return 1.0
        matched = len(set(s.lower() for s in vol_skills) & set(r.lower() for r in required))
        return matched / len(required)

    def _schedule_fit(self, availability, shifts) -> float:
        fits = 0
        for shift in shifts:
            for avail in availability:
                if avail["day"] == shift["day"] and avail["start"] <= shift["start"]:
                    fits += 1
                    break
        return fits / max(len(shifts), 1)

    def _haversine(self, loc1, loc2) -> float:
        from math import radians, sin, cos, sqrt, atan2
        lat1, lon1 = radians(loc1[0]), radians(loc1[1])
        lat2, lon2 = radians(loc2[0]), radians(loc2[1])
        dlat, dlon = lat2 - lat1, lon2 - lon1
        a = sin(dlat / 2) ** 2 + cos(lat1) * cos(lat2) * sin(dlon / 2) ** 2
        return 6371 * 2 * atan2(sqrt(a), sqrt(1 - a))

    def _reliability_score(self, volunteer_id) -> float:
        stats = self.db.get_reliability_stats(volunteer_id)
        if not stats["total_shifts"]:
            return 0.5
        return stats["completed_shifts"] / stats["total_shifts"]

    def _analyze_feedback_sentiment(self, volunteer_id) -> float:
        feedback = self.db.get_feedback(volunteer_id, months=6)
        if not feedback:
            return 0.5
        return np.mean([f["sentiment_score"] for f in feedback])

    def _recommend_interventions(self, risk_level, hour_trend, sentiment) -> list:
        interventions = []
        if risk_level in ("critical", "high"):
            interventions.append("Personal check-in call from volunteer coordinator")
        if hour_trend < -0.3:
            interventions.append("Offer flexible scheduling or new role options")
        if sentiment < 0.4:
            interventions.append("Conduct exit-prevention survey")
        if risk_level == "moderate":
            interventions.append("Send personalized impact summary and thank-you")
        return interventions

    def _identify_milestones(self, activity) -> list:
        total = sum(a["hours"] for a in activity)
        milestones = []
        for threshold in [50, 100, 250, 500, 1000]:
            if total >= threshold:
                milestones.append(f"{threshold}+ hours of service")
        return milestones

    def _generate_impact_narrative(self, vol_id, hours, programs) -> str:
        program_list = ", ".join(programs.keys())
        return f"Over the past year, this volunteer contributed {hours:.0f} hours across {program_list}."

5. Impact Measurement & Reporting

Funders, boards, and stakeholders increasingly demand rigorous evidence of impact — not just outputs (meals served) but outcomes (food insecurity reduced) and ideally long-term impact (community health improved). Most nonprofits struggle to bridge this gap because impact measurement requires systematic data collection, analysis, and reporting that exceeds their technical capacity. An AI agent closes this gap by automating the entire measurement pipeline.

Outcomes Tracking with Logic Models

A logic model maps the chain from inputs through activities, outputs, outcomes, and impact. An AI agent operationalizes your logic model by defining measurable indicators at each level, setting data collection schedules, and tracking progress against targets. It distinguishes between short-term outcomes (knowledge gained), medium-term outcomes (behavior changed), and long-term impact (conditions improved) — providing a nuanced view of your program's effectiveness.

Data Collection Automation

Impact measurement is only as good as the data feeding it. An AI agent automates survey distribution at program milestones, processes responses using natural language analysis, integrates data from multiple sources (attendance systems, case management software, partner reports), and flags data quality issues before they contaminate your analysis. It handles follow-up surveys with lapsed respondents and adjusts collection methods based on response rates.

Impact Dashboard Generation

Different stakeholders need different views of the same data. Your board wants high-level trend lines, your program directors want operational metrics, and your funders want specific KPIs tied to their grant objectives. An AI agent generates role-specific dashboards that pull from the same underlying data but present information at the appropriate level of detail, with contextual narratives that explain what the numbers mean.

Funder-Specific Report Formatting

Every funder has their own reporting template, timeline, and data requirements. An AI agent maintains a registry of funder reporting specifications, maps your internal metrics to each funder's required format, and generates draft reports that comply with each funder's specific requirements. When a reporting deadline approaches, the agent assembles the report automatically, flagging any data gaps that need human attention.

from collections import defaultdict
from datetime import date, timedelta
import json


class ImpactMeasurementAgent:
    """AI agent for outcomes tracking and impact reporting."""

    def __init__(self, program_db, survey_engine, ai_client):
        self.programs = program_db
        self.surveys = survey_engine
        self.ai = ai_client

    def build_logic_model(self, program_id: str) -> dict:
        """Generate a structured logic model with measurable indicators."""
        program = self.programs.get_program(program_id)

        logic_model = {
            "program_id": program_id,
            "inputs": self._extract_inputs(program),
            "activities": self._extract_activities(program),
            "outputs": [],
            "short_term_outcomes": [],
            "medium_term_outcomes": [],
            "long_term_impact": [],
        }

        for activity in logic_model["activities"]:
            outputs = self._define_outputs(activity)
            logic_model["outputs"].extend(outputs)

            for output in outputs:
                st_outcome = {
                    "description": f"Change in knowledge/awareness from {output['description']}",
                    "indicator": output["indicator"].replace("Number of", "% reporting improvement in"),
                    "target": None,
                    "measurement_method": "pre_post_survey",
                    "frequency": "per_cohort",
                }
                logic_model["short_term_outcomes"].append(st_outcome)

        return logic_model

    def automate_data_collection(self, program_id: str) -> dict:
        """Schedule and manage survey distribution and data ingestion."""
        logic_model = self.programs.get_logic_model(program_id)
        participants = self.programs.get_active_participants(program_id)
        collection_plan = {"surveys": [], "integrations": [], "quality_checks": []}

        for outcome in logic_model.get("short_term_outcomes", []):
            if outcome["measurement_method"] == "pre_post_survey":
                survey = self.surveys.create_or_get(
                    template=f"{program_id}_pre_post",
                    indicators=[outcome["indicator"]],
                )
                for p in participants:
                    enrollment = self.programs.get_enrollment(p["id"], program_id)
                    pre_date = enrollment["start_date"]
                    post_date = enrollment["start_date"] + timedelta(days=enrollment["duration_days"])

                    self.surveys.schedule(
                        survey_id=survey["id"],
                        participant_id=p["id"],
                        send_date=pre_date,
                        type="pre",
                    )
                    self.surveys.schedule(
                        survey_id=survey["id"],
                        participant_id=p["id"],
                        send_date=post_date,
                        type="post",
                    )

                collection_plan["surveys"].append({
                    "survey_id": survey["id"],
                    "participants": len(participants),
                    "outcome": outcome["indicator"],
                })

        response_rates = self.surveys.get_response_rates(program_id)
        for survey_id, rate in response_rates.items():
            if rate < 0.60:
                collection_plan["quality_checks"].append({
                    "survey_id": survey_id,
                    "response_rate": rate,
                    "action": "send_reminder" if rate > 0.40 else "switch_to_phone",
                })

        return collection_plan

    def generate_impact_dashboard(self, program_id: str, audience: str = "board") -> dict:
        """Create audience-specific impact dashboard data."""
        outcomes = self.programs.get_outcomes_data(program_id)
        outputs = self.programs.get_outputs_data(program_id)
        budget = self.programs.get_budget_data(program_id)

        if audience == "board":
            return {
                "summary_metrics": {
                    "total_served": sum(o["participants"] for o in outputs),
                    "outcome_achievement": self._overall_outcome_rate(outcomes),
                    "cost_per_outcome": self._cost_per_outcome(budget, outcomes),
                    "year_over_year_trend": self._yoy_trend(program_id),
                },
                "key_stories": self._select_impact_stories(program_id, count=3),
                "financial_efficiency": {
                    "program_expense_ratio": budget["program"] / max(budget["total"], 1),
                    "fundraising_efficiency": budget["raised"] / max(budget["fundraising_cost"], 1),
                },
                "narrative": self._generate_board_narrative(outcomes, outputs),
            }
        elif audience == "funder":
            return {
                "grant_specific_kpis": self._map_to_funder_kpis(program_id),
                "output_targets_vs_actual": self._target_vs_actual(outputs),
                "outcome_data": outcomes,
                "participant_demographics": self.programs.get_demographics(program_id),
                "budget_vs_actual": self._budget_variance(program_id),
            }
        else:
            return {
                "operational_metrics": outputs,
                "outcome_details": outcomes,
                "data_quality": self._data_quality_report(program_id),
                "upcoming_collections": self.surveys.get_upcoming(program_id),
            }

    def format_funder_report(self, grant_id: str) -> dict:
        """Generate report matching specific funder template requirements."""
        grant = self.programs.get_grant(grant_id)
        template = self.programs.get_funder_template(grant["funder_id"])
        program_id = grant["program_id"]

        report_sections = {}
        for section in template["required_sections"]:
            if section["type"] == "narrative":
                data = self.programs.get_outcomes_data(program_id)
                report_sections[section["name"]] = self.ai.generate(
                    f"Write a {section.get('word_limit', 500)}-word report section: "
                    f"{section['prompt']}\nData: {json.dumps(data)}"
                )
            elif section["type"] == "table":
                report_sections[section["name"]] = self._build_data_table(
                    program_id, section["metrics"]
                )
            elif section["type"] == "financial":
                report_sections[section["name"]] = self._budget_variance(program_id)

        return {
            "grant_id": grant_id,
            "funder": grant["funder_name"],
            "period": grant["reporting_period"],
            "sections": report_sections,
            "attachments": self._compile_attachments(grant_id),
            "status": "draft",
        }

    def _extract_inputs(self, program) -> list:
        return program.get("inputs", [])

    def _extract_activities(self, program) -> list:
        return program.get("activities", [])

    def _define_outputs(self, activity) -> list:
        return [{
            "description": f"Completion of {activity['name']}",
            "indicator": f"Number of participants completing {activity['name']}",
            "target": activity.get("target_participants", 0),
        }]

    def _overall_outcome_rate(self, outcomes) -> float:
        if not outcomes:
            return 0.0
        achieved = sum(1 for o in outcomes if o.get("target_met"))
        return round(achieved / len(outcomes) * 100, 1)

    def _cost_per_outcome(self, budget, outcomes) -> float:
        positive = sum(1 for o in outcomes if o.get("target_met"))
        return round(budget.get("program", 0) / max(positive, 1), 2)

    def _yoy_trend(self, program_id) -> dict:
        current = self.programs.get_outcomes_data(program_id, year="current")
        previous = self.programs.get_outcomes_data(program_id, year="previous")
        current_rate = self._overall_outcome_rate(current)
        previous_rate = self._overall_outcome_rate(previous)
        return {"current": current_rate, "previous": previous_rate, "change": current_rate - previous_rate}

    def _select_impact_stories(self, program_id, count) -> list:
        return self.programs.get_impact_stories(program_id, limit=count)

    def _generate_board_narrative(self, outcomes, outputs) -> str:
        total = sum(o["participants"] for o in outputs)
        rate = self._overall_outcome_rate(outcomes)
        return f"Programs served {total} participants with {rate}% outcome achievement."

    def _map_to_funder_kpis(self, program_id) -> dict:
        return self.programs.get_funder_kpis(program_id)

    def _target_vs_actual(self, outputs) -> list:
        return [{"output": o["description"], "target": o["target"],
                 "actual": o.get("actual", 0)} for o in outputs]

    def _budget_variance(self, program_id) -> dict:
        return self.programs.get_budget_variance(program_id)

    def _data_quality_report(self, program_id) -> dict:
        return self.programs.get_data_quality(program_id)

    def _build_data_table(self, program_id, metrics) -> list:
        return self.programs.get_metrics_table(program_id, metrics)

    def _compile_attachments(self, grant_id) -> list:
        return self.programs.get_grant_attachments(grant_id)

6. ROI Analysis: The Business Case for AI Agents in Nonprofits

Let's put concrete numbers behind the value proposition. Consider a mid-size nonprofit with a $10 million annual budget, 15,000 donors, 500 active volunteers, and 8 major grant-funded programs. Here's what AI agent deployment looks like across the areas we've discussed.

Donor Retention Improvement

The average nonprofit donor retention rate is 43%. AI-driven donor intelligence and personalized engagement typically improve retention by 8-12 percentage points. For our mid-size nonprofit, moving from 43% to 51% retention on a $4 million individual giving program means approximately $320,000 in additional annual revenue — donors who would have lapsed but didn't.

Fundraising Efficiency

Campaign optimization through personalized ask strings, optimal timing, and channel attribution reduces cost-per-dollar-raised from a typical $0.20 to $0.13-$0.15. On $4 million in individual giving, that's $200,000-$280,000 in efficiency savings that can be redirected to program delivery.

Grant Win Rate

AI-assisted grant matching and proposal writing improves win rates from 20% to 38% on average. If our nonprofit submits 25 proposals per year averaging $200,000 each, going from 5 to 9-10 wins adds $800,000-$1,000,000 in grant revenue annually.

Volunteer Retention

Reducing volunteer turnover from 40% to 28% through predictive retention interventions saves recruitment and training costs and preserves institutional knowledge. For 500 volunteers at $2,000 replacement cost, keeping an additional 60 volunteers saves $120,000 annually — not counting the program delivery value of experienced volunteers.

class NonprofitROIAnalyzer:
    """ROI calculator for AI agent deployment in nonprofits."""

    def __init__(self):
        self.industry_benchmarks = {
            "donor_retention_rate": 0.43,
            "cost_per_dollar_raised": 0.20,
            "grant_win_rate": 0.20,
            "volunteer_turnover_rate": 0.40,
            "volunteer_replacement_cost": 2000,
            "admin_hours_per_report": 40,
            "hourly_staff_cost": 35,
        }
        self.ai_improvement = {
            "donor_retention_lift": 0.08,
            "cpr_reduction": 0.06,
            "grant_win_rate_lift": 0.18,
            "volunteer_turnover_reduction": 0.12,
            "report_time_reduction": 0.65,
        }

    def full_roi_analysis(
        self,
        annual_budget: float = 10_000_000,
        individual_giving: float = 4_000_000,
        num_donors: int = 15_000,
        grant_proposals_year: int = 25,
        avg_grant_size: float = 200_000,
        num_volunteers: int = 500,
        annual_reports: int = 32,
        ai_annual_cost: float = 48_000,
    ) -> dict:
        """Complete ROI analysis for AI agent deployment."""

        # 1. Donor retention improvement
        current_retained_revenue = individual_giving * self.industry_benchmarks["donor_retention_rate"]
        improved_rate = (self.industry_benchmarks["donor_retention_rate"]
                        + self.ai_improvement["donor_retention_lift"])
        improved_retained_revenue = individual_giving * improved_rate
        donor_retention_value = improved_retained_revenue - current_retained_revenue

        # 2. Fundraising efficiency
        current_fundraising_cost = individual_giving * self.industry_benchmarks["cost_per_dollar_raised"]
        improved_cpr = (self.industry_benchmarks["cost_per_dollar_raised"]
                       - self.ai_improvement["cpr_reduction"])
        improved_fundraising_cost = individual_giving * improved_cpr
        fundraising_savings = current_fundraising_cost - improved_fundraising_cost

        # 3. Grant win rate improvement
        current_wins = grant_proposals_year * self.industry_benchmarks["grant_win_rate"]
        improved_win_rate = (self.industry_benchmarks["grant_win_rate"]
                           + self.ai_improvement["grant_win_rate_lift"])
        improved_wins = grant_proposals_year * improved_win_rate
        additional_grant_revenue = (improved_wins - current_wins) * avg_grant_size

        # 4. Volunteer retention
        current_turnover = num_volunteers * self.industry_benchmarks["volunteer_turnover_rate"]
        improved_turnover_rate = (self.industry_benchmarks["volunteer_turnover_rate"]
                                - self.ai_improvement["volunteer_turnover_reduction"])
        improved_turnover = num_volunteers * improved_turnover_rate
        volunteers_saved = current_turnover - improved_turnover
        volunteer_savings = volunteers_saved * self.industry_benchmarks["volunteer_replacement_cost"]

        # 5. Reporting efficiency
        current_report_hours = annual_reports * self.industry_benchmarks["admin_hours_per_report"]
        hours_saved = current_report_hours * self.ai_improvement["report_time_reduction"]
        reporting_savings = hours_saved * self.industry_benchmarks["hourly_staff_cost"]

        # Total value and ROI
        total_annual_value = (
            donor_retention_value
            + fundraising_savings
            + additional_grant_revenue
            + volunteer_savings
            + reporting_savings
        )
        net_value = total_annual_value - ai_annual_cost
        roi_percentage = (net_value / ai_annual_cost) * 100
        payback_months = (ai_annual_cost / (total_annual_value / 12))

        return {
            "annual_budget": annual_budget,
            "ai_annual_cost": ai_annual_cost,
            "value_breakdown": {
                "donor_retention": {
                    "before": f"{self.industry_benchmarks['donor_retention_rate']:.0%}",
                    "after": f"{improved_rate:.0%}",
                    "annual_value": round(donor_retention_value),
                },
                "fundraising_efficiency": {
                    "before": f"${self.industry_benchmarks['cost_per_dollar_raised']:.2f}/dollar",
                    "after": f"${improved_cpr:.2f}/dollar",
                    "annual_value": round(fundraising_savings),
                },
                "grant_revenue": {
                    "before": f"{self.industry_benchmarks['grant_win_rate']:.0%} win rate ({current_wins:.0f} wins)",
                    "after": f"{improved_win_rate:.0%} win rate ({improved_wins:.0f} wins)",
                    "annual_value": round(additional_grant_revenue),
                },
                "volunteer_retention": {
                    "before": f"{self.industry_benchmarks['volunteer_turnover_rate']:.0%} turnover",
                    "after": f"{improved_turnover_rate:.0%} turnover",
                    "volunteers_saved": round(volunteers_saved),
                    "annual_value": round(volunteer_savings),
                },
                "reporting_efficiency": {
                    "hours_saved": round(hours_saved),
                    "annual_value": round(reporting_savings),
                },
            },
            "total_annual_value": round(total_annual_value),
            "net_annual_value": round(net_value),
            "roi_percentage": round(roi_percentage, 1),
            "payback_months": round(payback_months, 1),
        }


# Run the analysis
analyzer = NonprofitROIAnalyzer()
roi = analyzer.full_roi_analysis()

print("=" * 60)
print("AI AGENT ROI ANALYSIS — MID-SIZE NONPROFIT ($10M BUDGET)")
print("=" * 60)
for area, data in roi["value_breakdown"].items():
    print(f"\n{area.replace('_', ' ').title()}:")
    for k, v in data.items():
        print(f"  {k}: {v}")
print(f"\n{'=' * 60}")
print(f"Total Annual Value:  ${roi['total_annual_value']:,}")
print(f"AI Agent Cost:       ${roi['ai_annual_cost']:,}")
print(f"Net Annual Value:    ${roi['net_annual_value']:,}")
print(f"ROI:                 {roi['roi_percentage']}%")
print(f"Payback Period:      {roi['payback_months']} months")
print(f"{'=' * 60}")

Getting Started: Implementation Roadmap

Deploying an AI agent across your nonprofit doesn't require a massive upfront investment or a two-year implementation timeline. Here's a phased approach that delivers value from month one:

1. Month 1 — Donor Intelligence: Connect your CRM data and run the first round of RFM scoring and wealth screening. Identify your top 50 major gift prospects with the highest propensity scores. This alone justifies the investment if it surfaces even one new major gift.
2. Month 2 — Campaign Optimization: Implement personalized ask strings for your next appeal. Set up A/B testing with Thompson Sampling for email subject lines and send times. Measure the lift against your baseline.
3. Month 3 — Grant Management: Build your grant opportunity matching pipeline. Use AI-assisted proposal drafting for your next submission. Implement compliance tracking for active grants.
4. Month 4 — Volunteer & Impact: Deploy skills-based volunteer matching and retention prediction. Set up automated impact data collection and dashboard generation.
5. Month 5+ — Integration & Optimization: Connect all systems for cross-functional insights. A major gift prospect who also volunteers gets a different cultivation strategy than one who only writes checks. Let the AI agent find these patterns.

The nonprofit sector stands at an inflection point. Organizations that adopt AI agents now will compound their advantage — better data leads to better decisions, which lead to better outcomes, which lead to more funding, which enables more impact. The technology is ready. The question is whether your organization will be among the first to seize it, or among those playing catch-up in two years.