Contract Tracker

SKILL.md

# Contract Tracker (contract-tracker)

> Upload contract PDFs → AI extracts key fields → Manage ledger → Expiry reminders + Feishu push

---

## Trigger Phrases

`contract ledger` `contract management` `contract tracker` `pdf contract` `contract reminder`

---

## Usage

### Command Line

```bash
# Upload a contract PDF
python -m scripts.main upload /path/to/contract.pdf

# List all contracts
python -m scripts.main list

# List contracts expiring within 30 days
python -m scripts.main list --status "Active" --sort end_date

# Get contract details
python -m scripts.main get <contract_id>

# Update a contract
python -m scripts.main update <contract_id> --name "New Name" --status "Terminated"

# Delete a contract
python -m scripts.main delete <contract_id>

# Add expiry reminder
python -m scripts.main reminder <contract_id> add --days 30

# Check expiring contracts
python -m scripts.main check --days 30

# Export contracts
python -m scripts.main export --format csv -o contracts.csv
```

### Python API

```python
from scripts import extract_text_from_pdf, extract_contract_fields
from scripts import add_contract, get_contracts, get_contract
from scripts import update_contract, delete_contract

# Extract fields from PDF
text = extract_text_from_pdf("/path/to/contract.pdf")
fields = extract_contract_fields(text, "contract.pdf")
contract = add_contract(fields)

# List contracts
all_contracts = get_contracts(status="Active")
```

---

## Contract Fields Extracted

- **Contract Name** — from PDF title
- **Amount** — RMB amount via regex
- **Sign Date** — contract signing date
- **Start Date** — effective start date
- **End Date** — expiry date
- **Counterparty** — other party name
- **Key Nodes** — payment terms, renewal clauses (up to 5)
- **Status** — Active / Expired (auto-calculated)

---

## Supported Formats

| Format | Extension | Notes |
|--------|-----------|-------|
| PDF | `.pdf` | Text extraction via PyMuPDF |

---

## Tech Stack

- **Parsing**: PyMuPDF (fitz)
- **AI Field Extraction**: Regex + heuristic pattern matching (fully offline, no external AI API)
- **Storage**: JSON file in `/tmp/contract-tracker/` (fully offline, no home directory writes)
- **Notifications**: Feishu IM card format

---

## Tiered Features

| Feature | FREE | PRO |
|---------|:----:|:---:|
| Max Contracts | 5 | Unlimited |
| Max Reminders | 1 | Unlimited |
| Export Formats | CSV | CSV, XLSX, PDF |
| Feishu Reminders | No | Yes |

**Price**: $0.01 USDT per call (PRO tier). FREE tier is free.

> Get PRO: [https://skillpay.me/contract-tracker](https://skillpay.me/contract-tracker)

---

## Billing

- **Endpoint**: `POST https://skillpay.me/api/v1/billing/charge`
- **Header**: `X-API-Key: {api_key}`
- **Body**: `{"user_id": "...", "skill_id": "contract-tracker", "amount": 0.01}`
- **Response**: `{"success": true, "balance": ...}`
- **Fallback**: Network error → FREE tier (do not block usage)
- **Dev Mode**: No API key configured → `balance=999.0`, no charge

---

## Required Environment Variables

| Variable | Description |
|----------|-------------|
| `SKILL_BILLING_API_KEY` | SkillPay Builder API Key |
| `SKILL_BILLING_SKILL_ID` | Skill Slug (default: contract-tracker) |

---

## Security Notes

- All contract data stored in `/tmp/contract-tracker/` — no home directory writes
- PDF parsing is fully offline — no external network calls during extraction
- Feishu card push requires a Feishu bot token (configure separately)

---

## API Key Format

Any non-empty string works as an API key. Tier is determined automatically:
- **No API key** → FREE tier
- **Any API key** → PRO tier

---

## Slug

`contract-tracker`