Spaces:
Sleeping
Sleeping
| 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) | |