Blame for README.md

---
title: README
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
pinned: false
short_description: A simple Gradio app
hf_oauth: true
---
# StrategyStack Recovery, Enrichment & Outreach Platform

## Granular UI Features (Nov 2025)
### New Compliance, Audit, Branching & Diagnostics Widgets

#### 1. Consent/Event Audit Panel
Shows all consent events, opt-outs, and compliance flags per contact and batch. 
- **Backend mapping:** Receives list of consent events (JSON, e.g. {contact_id, event_type, opt_out, compliance_flag}) per contact or batch.
- **UI mapping:** Gradio panel renders event history per contact, batch aggregation, flags out-of-policy events.
- **State schema:** See /docs/configs/compliance_schema.json.

#### 2. Dynamic Cadence Branching Composer
Visual builder for editing & previewing cadence sequences (multi-step outreach flows with conditional logic)
- **Backend mapping:** Mirrored to cadence state JSON (see cadence_agent.py / docs/configs/cadence_tree.json)
- **UI mapping:** Interactive tabular/tree UI shows each step, transition, and condition (see new app.py logic).
- **Inline code:** Each logic widget/function takes the backend structure as argument.

#### 3. Live Diagnostics Panel (Incidents/Health)
Shows real-time and historical such as error, warning, info events for cadence or batch operations.
- **Backend mapping:** List of incidents/events from backend diagnostics state (event objects: {timestamp, type, message, level})
- **UI mapping:** Gradio Markdown log renders type/level/message per event.
- **Config:** Event/incident schema in docs/configs/diagnostics_schema.json

#### 4. Exportable Audit Trail (Compliance/Debug)
CSV/text export of event history (compliance and debug records)
- **Backend mapping:** Batch history as list of per-event dicts, same as consent_audit schema.
- **UI mapping:** Text/csv box (downloadable) shows organized history—maps to regulatory & support request export needs.

#### Usage & API Mapping
- All widgets assume backend compliance/cadence events via standardized JSON from respective APIs (see /api/diagnostics, /api/cadence, /api/compliance, etc).
- See app.py for inline documentation on each panel/component; argument signatures require the backend state JSON (typically list[dict]).

#### Inline Documentation Examples (app.py)
- Each widget (audit, diagnostics, branching, export) is documented inline for both UI and state/JSON structure.
- You can customize backend structure via docs/configs/ files and panel logic will adopt new schemas as format evolves.

## Example Panel Usage
Example construction is provided in app.py showing default data structures and rendering each widget in a Gradio tab.

---
(legacy platform and API docs retained below)

---

## API Rate Limits & Throttling

### Overview

This platform integrates with multiple external APIs for B2B outreach automation. Each service enforces rate limits to prevent abuse and ensure service stability. Understanding these limits is critical for:
- **Preventing service disruptions** (429 errors, temporary blocks)
- **Optimizing batch operations** (cadence scheduling, bulk enrichment)
- **Compliance monitoring** (audit trail accuracy)
- **Cost management** (avoiding overage charges)

**Rate Limit Reset Timing:** Most APIs reset limits at **midnight UTC** daily, with some using rolling windows.

---

### LinkedIn API Rate Limits

**Connection & Messaging Limits:**
- **Connection Requests:** 100-200 per week (varies by account reputation)
  - New accounts: ~50-75/week
  - Established accounts: ~100/week  
  - Trusted accounts (high SSI): up to 200/week
- **Messages:** 150 per day (premium accounts)
- **Profile Views:** 80/day (standard), up to 1,000/day (premium)

**API Request Limits (Scale-Dependent):**
- **1,000-5,000 members:** 7,500 requests/day, 1,500 requests/hour
- **5,001-10,000 members:** 15,000 requests/day, 15,000 requests/hour
- **10,001-20,000 members:** 30,000 requests/day, 30,000 requests/hour
- **Rate limit errors:** HTTP 429 "Too Many Requests"
- **Alert threshold:** Email notification at 75% of quota

**Best Practices:**
- Implement **exponential backoff** (15-30 minute delays) when hitting limits
- Monitor `X-RateLimit-Remaining` response headers
- Limits reset at midnight UTC daily

---

### Email API Rate Limits

#### SendGrid
- **API Rate Limit:** 600 requests/minute (varies by endpoint)
- **Free Plan:** 100 emails/day
- **Paid Plans:** Up to 1,500 emails/day, max 400 emails/hour
- **Enterprise:** 1.5M emails/month with dedicated IP

#### Mailgun
- **API Rate Limit:** 300 requests/minute
- **Free Plan:** 5,000 emails/month, 300 emails/day
- **Paid Plans:** 50,000-100,000 emails/month (Foundation/Growth/Scale)
- **Throttling:** Automatic rate limiting based on sender behavior

---

### Phone/SMS API Rate Limits (Twilio)

- **Outbound Calls:** 1 call per second (CPS) per account
- **SMS Messages:** 1 message per second per phone number
- **Conversation Limit:** 30 outbound replies between two numbers in 30 seconds
- **Error Code:** 14107 when SMS rate limit exceeded
- **Webhook Limits:** Service-specific (see Twilio Verify documentation)

**Important:** The 500th user in a batch will receive their call/SMS after ~500 seconds due to 1 CPS limit.

---

### Data Enrichment API Rate Limits

#### ZoomInfo
- **Standard APIs:** 25 requests/second (1,500 requests/minute)
- **Scaling APIs:** 33 requests/second
- **Daily Limits:**
  - Pro Plan: ~1,000 API calls/day
  - Enterprise Plan: up to 10,000 API calls/day
- **Batch Enrichment:** 100,000 records max per batch
- **Pricing:** Credit-based system (~$15,000/year for 5,000 credits)

#### Clearbit (Breeze Intelligence)
- **Rate Limits:** Not publicly specified (HubSpot integration)
- **Batch Enrichment:** Limited to 100,000 records at once
- **Pricing:** Credit-based, starts at $45-50/month (100 credits)
- **Real-time Updates:** API-first approach for live data

#### Hunter.io
- **Domain Search & Email Finder:** 15 requests/second, 500 requests/minute
- **Email Verifier:** 10 requests/second, 300 requests/minute
- **Error Response:** HTTP 403 when limit exceeded
- **Plans:**
  - Free: Limited credits
  - Growth: 10,000 credits/month
  - Scale: 25,000 credits/month

#### Apollo.io
- **Free Plan:** 50 API calls/minute, 600 calls/day
- **Paid Plans:** 200 API calls/minute, 2,000 calls/day
- **Bulk Enrichment:** 1/10 of standard rate limit (but 10 inputs per call)
- **Error:** HTTP 429 after exceeding limit

---

### CRM API Rate Limits (Salesforce)

- **Daily Request Limit:** 100,000 base requests/24 hours (Enterprise Edition)
  - Plus 1,000 additional requests per user license
  - Example: 50 users = 150,000 daily requests
- **Concurrent Requests:** Max 25 long-running requests (20+ seconds)
  - Developer orgs: 5 concurrent requests
- **API Timeout:** Hard 10-minute maximum per call
- **Bulk API:** 15,000 batches/day, 10,000 records per batch
- **Report API:** 1,200 async requests/hour
- **Measurement Window:** Rolling 24-hour window (not calendar days)

---

### Platform Implementation

**Our Rate Limit Handling Strategy:**

1. **Detection:** Monitor response headers (`X-RateLimit-*`, HTTP 429 status)
2. **Exponential Backoff:** 15-minute initial delay, doubling on repeated failures
3. **Circuit Breaker:** Temporary pause (15-30 min) when threshold reached
4. **Queue Management:** Batch operations respect per-service limits
5. **Alerting:** Live Diagnostics panel logs rate limit events

**Configuration Files:**
- Rate limit configs: `/docs/configs/rate_limits.json`
- Throttling logic: See `cadence_agent.py` backoff implementation
- Monitoring: Live Diagnostics Panel tracks limit-related warnings

**Example from Live Diagnostics:**
```
[2025-11-06T06:33:00Z] warning: Rate limit reached for LinkedIn API; 
implementing exponential backoff for 15 minutes
```

---

### Monitoring & Alerts

**Dashboard Integration:**
- **Live Diagnostics Panel:** Real-time rate limit warnings
- **Audit Trail Export:** Historical rate limit incidents (CSV export)
- **Compliance Tracking:** Flags batches affected by rate limiting

**Recommended Actions:**
- Review Live Diagnostics panel regularly for rate limit patterns
- Adjust batch sizes and cadence timing based on observed limits
- Consider upgrading API plans if consistently hitting free tier limits
- Implement staggered scheduling to distribute load throughout the day

---

### Additional Resources

- LinkedIn API Documentation: [Microsoft Learn - Rate Limits](https://learn.microsoft.com/en-us/linkedin/shared/api-guide/concepts/rate-limits)
- Twilio Rate Limits: [Understanding Twilio Rate Limits](https://help.twilio.com/articles/115002943027)
- Salesforce API Limits: [API Request Limits and Allocations](https://developer.salesforce.com/docs/atlas.en-us.salesforce_app_limits_cheatsheet.meta)
- Hunter.io API: [Rate Limits Documentation](https://help.hunter.io/en/articles/1970956-hunter-api)
- Apollo.io API: [View API Usage Stats](https://docs.apollo.io/reference/view-api-usage-stats)