Metadata-Version: 2.4
Name: velox-gtm
Version: 2.0.2
Summary: Open-source GTM automation CLI: LinkedIn ICP scoring, Notion ERP provisioning, Google Docs compiler, and closed-won sales-to-ops handoff.
Author-email: Satyaneev <gtm@satyaneev.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dhruv-atomic-mui21/velox
Project-URL: Repository, https://github.com/dhruv-atomic-mui21/velox.git
Project-URL: Bug Tracker, https://github.com/dhruv-atomic-mui21/velox/issues
Keywords: gtm,sales-automation,notion,linkedin,icp-scoring,revenue-operations,revops,crm,n8n,google-docs,sales-ops,b2b,lead-enrichment,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Classifier: Topic :: Office/Business :: Groupware
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-api-python-client>=2.120.0
Requires-Dist: notion-client>=2.2.1
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Velox — GTM Automation Engine

[![PyPI](https://img.shields.io/pypi/v/velox-gtm.svg)](https://pypi.org/project/velox-gtm/)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![GitHub Stars](https://img.shields.io/github/stars/dhruv-atomic-mui21/velox?style=social)](https://github.com/dhruv-atomic-mui21/velox)

---

**Your sales team closes a deal. Someone then manually copies the company into Notion, creates a delivery project, drafts a proposal in Google Docs, and pastes Slack alerts by hand. Velox automates that entire handoff.**

Velox is an open-source Python CLI that connects LinkedIn lead capture → ICP scoring → Notion sales pipeline → closed-won ops provisioning → Google Docs proposal generation. One system, zero data-entry.

---

![velox --demo terminal output](demo.svg)

---

## See it in 60 seconds (zero setup)

The ICP scoring engine runs completely offline — no API keys, no accounts, no config:

```bash
pip install velox-gtm
velox --demo
```

You'll see a LinkedIn inbound lead event parsed, scored against a 3-axis ICP matrix (industry fit, company size, title seniority), and routed to a generated n8n webhook payload — all in one terminal scroll.

> **No OAuth. No Notion account. No credentials.json.** Just `pip install` and `velox --demo`.

---

## What Velox automates

| Workflow | What it does | Setup required |
|---|---|---|
| **ICP Lead Scoring** | Scores B2B leads 0–100 across industry, headcount, and seniority. Routes to Tier 1/2/3. | None — runs offline |
| **Notion ERP Deploy** | Provisions `Pipeline Tracker (Sales)` ↔ `Client Vault & Project Delivery (Operations)` as linked relational databases | Notion API key |
| **Closed-Won Provisioning** | Detects a deal moving to `Closed-Won` in Notion, auto-creates the delivery project, attaches a Google Doc contract, and links both records | Notion API key |
| **Google Docs Compiler** | Transforms Markdown strategy blueprints into formatted Google Docs with headings, callouts, and structured sections | Google OAuth |
| **n8n Webhook Bridge** | Generates valid n8n OAuth 2.0 credential payloads and webhook trigger bodies for any workflow above | n8n instance |

---

## Quickstart

### Option A — Try the demo (no setup)

```bash
pip install velox-gtm
velox --demo
```

### Option B — Full engine with credentials

**1. Clone and install**

```bash
git clone https://github.com/dhruv-atomic-mui21/velox.git
cd velox
pip install -r requirements.txt
pip install -e .
```

**2. Configure your environment**

```bash
cp .env.example .env
# Edit .env with your keys (see Credentials Setup below)
```

**3. Launch the CLI**

```bash
velox
```

---

## Credentials Setup

Only needed for Options 1–4 in the full CLI. Option 5 (ICP scoring demo) and Option 6 (local blueprint reader) require no credentials.

### Notion API key (Options 1 & 4)
1. Go to [notion.so/my-integrations](https://www.notion.so/my-integrations) → **New integration**
2. Copy the **Internal Integration Token** (starts with `secret_`)
3. Add `NOTION_API_KEY=secret_...` to your `.env`
4. Share your target Notion page with the integration

### Google OAuth (Options 2 & 3)
1. Go to [console.cloud.google.com](https://console.cloud.google.com) → Create a project
2. Enable the **Google Docs API** and **Google Drive API**
3. Create an **OAuth 2.0 Client ID** (Desktop app type)
4. Download `credentials.json` and place it in the project root
5. Run `velox` → Option 2 to complete the browser handshake

### n8n Webhook URL (Optional)
Set `N8N_WEBHOOK_URL` in `.env` to your self-hosted or cloud n8n webhook endpoint.

---

## ICP Scoring — how it works

The `LinkedInGTMLeadEngine.score_lead()` function is a standalone module you can import directly into any webhook server:

```python
from linkedin_gtm import LinkedInGTMLeadEngine

engine = LinkedInGTMLeadEngine()
lead = engine.score_lead({
    "prospect_name": "Sarah Jenkins",
    "prospect_title": "VP of Revenue Operations",
    "company_name": "ApexLogistics AI",
    "industry": "Logistics",
    "employee_count": 180,
    "estimated_deal_value": 45000
})

print(f"ICP Score: {lead['icp_score']}/100 | Tier: {lead['icp_tier']}")
# ICP Score: 100/100 | Tier: Tier 1 (High Priority / Immediate Ops Booking)
```

**Scoring breakdown:**
- **Industry fit** — 35 pts (Finance, B2B Sales, Logistics, SaaS, Fintech)
- **Company size** — 40 pts (50–500 employees = full score; <50 = 15 pts; >500 = 25 pts)
- **Title seniority** — 25 pts (VP, Director, Head of, C-suite)

Tier routing: `≥75` = Tier 1 (immediate ops), `≥50` = Tier 2 (standard outreach), `<50` = Tier 3 (nurture).

---

## CLI Dashboard

```
┌─────────────────────────────────────────────────────────────────────────────┐
│   ██╗   ██╗███████╗██╗      ██████╗ ██╗  ██╗                               │
│   ██║   ██║██╔════╝██║     ██╔═══██╗╚██╗██╔╝                               │
│   ██║   ██║█████╗  ██║     ██║   ██║ ╚███╔╝                                │
│   ╚██╗ ██╔╝██╔══╝  ██║     ██║   ██║ ██╔██╗                                │
│    ╚████╔╝ ███████╗███████╗╚██████╔╝██╔╝ ██╗                               │
│     ╚═══╝  ╚══════╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝                               │
│                                                                             │
│   OPEN-SOURCE GTM AUTOMATION ENGINE & SALES-TO-OPS OPERATING SYSTEM        │
└──────────────────────────────────────────────────── Version 2.0.1 (Open Source) ──┘

 1. Deploy Notion Business ERP Databases          ← requires Notion API key
 2. Run Google OAuth 2.0 Authenticator            ← requires credentials.json
 3. Create & Format Operational Blueprints        ← requires Google OAuth
 4. Run Relational Notion ERP Workflow            ← requires Notion API key
 5. Run LinkedIn GTM Lead Capture & ICP Scoring   ← NO SETUP REQUIRED ✓
 6. Read Local Operational Blueprints             ← NO SETUP REQUIRED ✓
 7. Exit
```

---

## Contributing

Pull requests are welcome. If you want to add a new ICP scoring dimension, a new Notion schema, or a new webhook integration:

1. Fork → `git checkout -b feature/your-feature`
2. Commit → `git commit -m 'Add: ...'`
3. PR → describe what workflow it automates and what problem it removes

For bugs or feature requests, [open an issue](https://github.com/dhruv-atomic-mui21/velox/issues).

---

## License

[MIT](LICENSE) — open-source for GTM engineers, growth teams, and RevOps builders.

Made by [Satyaneev](https://satyaneev.me)
