Contract Ledger

SKILL.md

# Contract Ledger

> 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 (no external AI API needed)
- **Storage**: JSON file in `/tmp/contract-ledger/` (fully offline)
- **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 |
| Priority Support | No | Yes |

---

## Billing

**$0.01 USDT per call** — billed via SkillPay at [https://skillpay.me/contract-ledger](https://skillpay.me/contract-ledger)

> **Privacy Note:** Your Feishu User ID (Open ID) may be transmitted to skillpay.me for billing purposes only.

| Price | $0 (FREE tier) | $0.01 / call (PRO tier) |

> For paid use, visit [https://skillpay.me/contract-ledger](https://skillpay.me/contract-ledger)

---

## Required Environment Variables

| Variable | Description |
|----------|-------------|
| `SKILL_BILLING_API_KEY` | SkillPay Builder API Key (from skillpay.me) |
| `SKILL_BILLING_SKILL_ID` | Skill ID on SkillPay (default: contract-ledger) |

---

## Security Notes

- All contract data is stored locally in `/tmp/contract-ledger/` — **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)
- Token validation is handled by SkillPay billing system, not by the skill itself

---

## 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-ledger`