ICP Signal Intelligence Tool - Operator Runbook

Version: 2.0 Owner: Value Aligners Developer: Harika Chowdary Pedavalli Last Updated: May 7, 2026

---

1. What This Tool Does

The ICP Signal Intelligence Tool is an AI-powered market intelligence platform that monitors target companies, detects buying signals from real data sources, scores each company against a configurable ICP, and delivers a prioritized list with AI-written outreach briefs to the sales team every day.

It has two versions:

• Enterprise - monitors Fortune 300/500 companies using SEC filings, hiring data, and website signals
• SMB - monitors companies with 20 to 2,500 employees using compliance triggers, cloud adoption, and hiring signals

---

2. Required Environment Variables

Create a .env file in the root directory. Never commit this file to GitHub.

GROQ_API_KEY=your_groq_api_key_here ADZUNA_APP_ID=your_adzuna_app_id ADZUNA_API_KEY=your_adzuna_api_key APOLLO_API_KEY=your_apollo_api_key ZOHO_CLIENT_ID=your_zoho_client_id ZOHO_CLIENT_SECRET=your_zoho_client_secret ZOHO_REFRESH_TOKEN=your_zoho_refresh_token HAPPENSTANCE_API_KEY=your_happenstance_api_key DATABASE_URL=sqlite:///./icp_intelligence.db

What Works Without Each Key:

• No GROQ_API_KEY: AI briefs and outreach generation disabled
• No ADZUNA keys: Job board signal detection disabled
• No APOLLO_API_KEY: Company enrichment and contact discovery disabled
• No ZOHO keys: CRM push disabled
• No HAPPENSTANCE_API_KEY: Real network relationship data disabled

---

3. How to Run Locally

git clone https://github.com/HarikaPedavalli-ValueAligners/ICP-Signal-Intelligence-Tool.git cd ICP-Signal-Intelligence-Tool python -m venv venv venv\Scripts\activate pip install -r requirements.txt uvicorn backend.main:app --reload

Terminal 2: cd enterprise-dashboard && npm install && npm run dev

Terminal 3: cd smb-dashboard && npm install && npm run dev

URLs:

• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Enterprise Dashboard: http://localhost:5173
• SMB Dashboard: http://localhost:5174

---

4. ICP Configuration

All ICP profiles are in backend/icp_config/icp_configs.json.

To change weights without code: use the ICP Config button in the enterprise dashboard top right corner. Weights must sum to 100% or the save will be rejected.

Available profiles:

• icp1_enterprise - Fortune 300/500 cybersecurity ICP
• icp2_smb - SMB compliance ICP
• icp3_ai_modernization - AI modernization ICP

---

5. API Endpoints Reference

Enterprise: GET /api/enterprise/accounts - List accounts ranked by score POST /api/enterprise/accounts - Create account GET /api/enterprise/accounts/{id} - Full detail with signals POST /api/enterprise/accounts/{id}/run - Run full pipeline POST /api/enterprise/accounts/{id}/enrich - Apollo enrichment GET /api/enterprise/accounts/{id}/warm-intro - Warm intro recommendations GET /api/enterprise/dashboard - Dashboard metrics GET /api/enterprise/config/profiles - List ICP profiles PUT /api/enterprise/config/profiles/{id} - Update profile weights

SMB: GET /api/smb/accounts - List SMB accounts POST /api/smb/accounts/{id}/run - Run SMB pipeline GET /api/smb/dashboard - SMB dashboard metrics

Signal Inbox (bridge to Interaction Manager): GET /api/signal-inbox - List all scored accounts GET /api/signal-inbox/{id} - Full detail POST /api/signal-inbox/{id}/promote - Promote to prospect GET /api/signal-inbox/stats/summary - Inbox health metrics

Feedback Loop: POST /api/feedback/{id} - Submit outcome feedback GET /api/feedback/summary/all - Conversion rates and accuracy

CRM: POST /api/crm/push/{id} - Push one account to Zoho CRM POST /api/crm/push-all - Push all accounts above min score

---

6. Signal Inbox API Contract (schema_version: 1.0)

All Signal Inbox responses include schema_version: "1.0" for versioning.

Sample response from GET /api/signal-inbox:

{ "schema_version": "1.0", "account_id": 1, "company_name": "Microsoft", "composite_score": 83.75, "tier": "A", "signal_count": 4, "fresh_signal_count": 4, "suggested_action": "direct_outreach", "top_use_cases": ["GRC/compliance readiness"], "confidence": 0.84, "ready_to_promote": true, "source_app": "icp-signal-intelligence" }

Filters supported: min_score, tier, account_type, limit (default 50)

Breaking vs additive changes:

• Breaking: removing or renaming existing fields
• Additive: adding new fields (safe, consumers should ignore unknown fields)
• Bump schema_version to 2.0 for any breaking change

---

7. Smoke Test Checklist After Deploy

• GET /health returns 200
• GET /api/enterprise/accounts returns accounts
• GET /api/signal-inbox returns accounts with schema_version 1.0
• GET /api/signal-inbox/stats/summary returns counts
• GET /api/enterprise/config/profiles returns 3 profiles
• Enterprise dashboard loads with Microsoft at top
• SMB dashboard loads with Qualys at top
• Config UI opens with editable weights
• Save Changes with weights not summing to 100% shows validation error
• Save Changes with correct weights updates JSON file
• POST /api/enterprise/accounts/{id}/run completes
• GET /api/enterprise/accounts/{id}/warm-intro returns Happenstance data

---

8. Pending Integrations (Blocked on Credentials)

Amendment 5 - Apollo enrichment: waiting for API key from Waamene Amendment 6 - Zoho CRM push: waiting for credentials from Akshitha

Integration files ready to complete once credentials arrive:

• Amendment 5: backend/ingestion/apollo_enricher.py
• Amendment 6: backend/routes/crm_routes.py

---

9. Data and Compliance

PII Handling:

• Apollo enrichment pulls contact names, email addresses, and LinkedIn URLs. These are PII.
• Zoho CRM push sends account scores, signal summaries, and contact data to Zoho servers.
• Happenstance search uses network connection data from the API account holder.

What Gets Sent to Third Parties:

• Apollo: company domain and search queries
• Zoho: company name, score, signal summary, outreach brief, contact titles
• Happenstance: company name and natural language search query

Retention:

• All data is stored in SQLite locally or Azure SQL in production
• No data is stored in third party systems beyond what Zoho CRM saves as a Lead record

Access Control:

• Feedback loop POST endpoint should be restricted to authenticated sales team members in production
• Config UI PUT endpoint should be restricted to admin users in production
• Add API key authentication middleware before production deployment

Idempotency - Feedback Loop:

• Currently the feedback endpoint creates a new record on every POST
• In production add account_id and date uniqueness check to prevent duplicate entries
• Feedback events should feed into scoring via a nightly batch job not real time to prevent score drift
• Only authorized sales team members should be able to POST feedback outcomes

---

10. Known Limitations

• SQLite used locally. Switch DATABASE_URL to Azure SQL for production.
• Config UI validates weights sum to 100% before saving.
• Signal Inbox API has no pagination yet. Add offset parameter for large datasets.
• Feedback loop captures data but does not yet feed back into scoring automatically.
• Audit trail for Config UI changes is logged to console. Add database audit table for production.

---

11. GitHub

https://github.com/HarikaPedavalli-ValueAligners/ICP-Signal-Intelligence-Tool