sarvamai/sarvam-campaign-calendar

sarvamai/sarvam-campaign-calendar

Language: Python

Stars: 0

Forks: 1

Open issues: 0

Created: 2026-08-08T06:45:32Z

Pushed: 2026-08-19T13:43:17Z

Default branch: main

Fork: no

Archived: no

README:

Campaign Calendar

A calendar-based monitoring tool for Sarvam Samvaad voice campaigns. Polls the Samvaad scheduling API, caches campaigns in SQLite, and serves a month-calendar view with overlap detection, capacity planning, forecasting, campaign assignment, health analytics, and calendar subscription.

Built for multi-client use — currently serving Cholamandalam, RBL Bank, and Sarvagram.

What it does

• Month calendar — each day shows campaign chips color-coded by status (active, paused, scheduled, ended, cancelled). Days with 2+ overlapping campaigns get a red dot.
• Capacity view — per-day peak CPS chart with plan ceiling overlay, concurrency estimates, call volume (with retry inflation), and cohort exhaustion days. "Show math" toggle reveals the full formula breakdown per campaign for transparency.
• Forecast view — forward-looking 7/14/30-day prediction of peak CPS, concurrency (with confidence ranges), estimated call volume, and staffing alerts. Includes pattern detection that identifies recurring campaign series and predicts the next occurrence.
• Manual campaigns — create planned campaigns manually to predict and prepare for upcoming work. Manual campaigns appear on the calendar alongside real API campaigns with a distinct "planned" status and can be edited or deleted.
• Agenda panel — click any day to see every campaign touching it, with status, call band, cohort size, and capacity.
• Detail modal — click any campaign for full metadata: campaign ID, app type/version, IST start/end, duration, schedule, cohort, capacity, assignee, and tags.
• Campaign health — fetches live call analytics (engagement funnel, connectivity summary, failure reasons) from the analytics API inside the detail modal. For workflow campaigns, also shows workflow overview (entered/completed/dropped off), per-node drop-off breakdown, and telephony node call stats.
• Overview dashboard — cross-client summary cards showing campaign counts and health per client. Click a card to drill into that client's calendar.
• Campaign search — searches across all cached campaigns by name, not just the current month. Click a result to jump to that campaign's month and open its detail.
• Campaign assignment & tags — assign campaigns to team members and tag them for grouping. Persists in SQLite. Filter the calendar by assignee or tag.
• "Only mine" filter — enter your name and toggle to see only campaigns assigned to you.
• Weekly digest — generates a plain-text summary of the week's campaigns, copyable to clipboard for Slack or email.
• ICS calendar subscription — subscribe in Google Calendar, Apple Calendar, or Outlook. Each client has its own feed URL. Each campaign becomes a recurring event with status, type, and cohort size in the description.
• Mobile view — a list-based view optimized for phones, since the Samvaad agents platform doesn't work well on mobile browsers.
• Background poller — refreshes campaign list and details every 5 minutes. Also caches per-campaign analytics (connect rate, avg talk time) from the analytics API so the forecast uses campaign-specific estimates instead of workspace-wide averages.
• Offline support — service worker caches the app shell for offline use with last-known campaign data.

Setup

Prerequisites

• Python 3.11+
• A Samvaad API key for each client (X-API-Key)

Install

git clone https://github.com/anmolsen-sarvam/sarvam-campaign-calendar.git
cd samvaad-campaign-timeline
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configure

1. Copy the env template and add your API keys:

cp .env.example .env

Edit .env — one key per client:

CHOLAMANDALAM_API_KEY=your-key-here
RBL_BANK_API_KEY=your-key-here
SARVAGRAM_API_KEY=your-key-here

2. Review config.yaml — it already has three clients configured. To add another:

clients:
- key: cholamandalam
display_name: "Cholamandalam"
org_id: "019ec301-9128-78b8-9772-4b470c04d0ad"
workspace_id: "019ec301-912f-72f9-9a58-06e9f73a6a84"
base_url: "https://apps.sarvam.ai"
api_key_env: "CHOLAMANDALAM_API_KEY"

- key: tata_capital
display_name: "Tata Capital"
org_id: ""
workspace_id: ""
base_url: "https://apps.sarvam.ai"
api_key_env: "TATA_CAPITAL_API_KEY"

Then add TATA_CAPITAL_API_KEY= to .env. No code changes needed.

Optional: Analytics (call health data)

Campaign health (pickup rates, completion stats) requires a bearer token for the analytics API. Two options:

1. Manual override — add AUTH_TOKEN=your_bearer_token to .env and restart. Tokens expire every ~2 hours. 2. SSO login — run python samvaad_auth.py login --env prod --org-id on the server. The app will auto-refresh using the stored refresh token.

Without either, the health panel shows a helpful message explaining how to configure it.

Run

python -m campaign_timeline.main

The server starts at http://0.0.0.0:8000. The poller runs immediately on startup, then every 5 minutes.

Run tests

pytest

API reference

Clients

| Method | Path | Description | |--------|------|-------------| | GET | /api/clients | List all configured clients | | GET | /api/overview | Cross-client summary: per-client campaign counts and health |

Campaigns

| Method | Path | Description | |--------|------|-------------| | GET | /api/clients/{key}/campaigns?from=YYYY-MM-DD&to=YYYY-MM-DD | Campaigns overlapping the date range | | GET | /api/clients/{key}/search?q=NameFragment | Search all cached campaigns by name | | GET | /api/clients/{key}/capacity?from=YYYY-MM-DD&to=YYYY-MM-DD | Hourly capacity buckets for the date range | | GET | /api/clients/{key}/forecast?days=N | Forward-looking forecast (peak CPS, concurrency, calls, patterns) | | GET | /api/clients/{key}/prediction-estimates | Client-level connect rate and avg talk time from analytics | | GET | /api/clients/{key}/campaigns/{id}/health | Live call analytics (funnel, connectivity, failure reasons, workflow metrics) | | GET | /api/clients/{key}/calendar.ics | ICS feed for calendar subscription |

Manual campaigns

| Method | Path | Description | |--------|------|-------------| | POST |...