AI Financial Report

SKILL.md

# Financial Report AI (ai-financial-report)

> Upload Excel/CSV/PDF financial statements → AI auto-generates structured business analysis reports (revenue structure / cost anomalies / profitability / cash flow / balance sheet / KPI achievement / anomaly alerts).

## Tiered Features

| Feature | FREE | PRO |
|---------|:----:|:---:|
| Analyses/month | 3 | Unlimited |
| Input formats | CSV, Excel | CSV, Excel, PDF |
| Analysis dimensions | 3 basic | All 7 |
| Charts | ❌ | ✅ |
| Industry comparison | ❌ | ✅ |
| **Price** | **Free** | **$0.01 USDT/use** |

> Upgrade to PRO: [https://skillpay.me/ai-financial-report](https://skillpay.me/ai-financial-report)

---

## Architecture

```
User uploads file
    ↓
index.js (entry, routes to handlers)
    ↓
src/handlers/
  ├── skill_invoke.js    ← core analysis engine dispatcher
  ├── file_upload.js     ← file upload handler
  └── message_handler.js ← text chat handler
    ↓
src/services/
  ├── billing.js         ← SkillPay token validation + 5-min cache
  ├── file_parser.py     ← Excel/CSV/PDF parsing
  └── report_generator.py ← AI analysis + Markdown rendering
```

## Quick Start

### Upload a File (Recommended)

Upload your Excel/CSV/PDF financial file directly — AI automatically completes the full analysis.

**Supported formats**: `.csv`, `.xlsx`, `.xls`, `.pdf`

### Configure AI API Key

This skill does **not** include an AI model. Users configure their own API key.

Supported AI models (any one):

| Model | Provider | Get API Key |
|-------|----------|-------------|
| GPT-4o | OpenAI | platform.openai.com |
| Claude 3.5 | Anthropic | console.anthropic.com |
| DeepSeek V3 | DeepSeek | platform.deepseek.com |
| Qwen | Alibaba Cloud | bailian.console.aliyun.com |
| MiniMax | MiniMax | platform.minimax.chat |

> **No binding, no recommendation, no restriction** on specific models — user chooses freely.

---

## Output Example

```markdown
# Financial Report Analysis

**Company**: XX Tech Co.
**Period**: Q1 2024
**Tier**: PRO

---

## 1. Revenue Structure

| Item | Value |
|------|-------|
| Total Revenue | 3,800 (10K CNY) |
| YoY Change | +15.3% |
| QoQ Change | +8.2% |

**Structure**: Core business 82%, other business 18%

---

## 7. Anomaly Alerts

| Dimension | Severity | Description | Value |
|-----------|----------|-------------|-------|
| Cost | 🔴 HIGH | Admin expense ratio abnormally high | 18.5% (avg: 12%) |
| Cash Flow | 🟠 MEDIUM | Operating cash flow YoY declined | -12.3% |
```

---

## Data Format

| Format | Notes |
|--------|-------|
| CSV | UTF-8, first row = header |
| Excel (.xlsx) | Multi-sheet, reads first sheet by default |
| PDF | Text must be copyable (no scanned images) |

**Column guidelines**: Use clear dimension names (revenue, cost, profit, etc.). Avoid excessive merged cells.

---

## Privacy

- **No data upload**: All files processed locally, never sent to third-party servers
- **No file storage**: Temporary files deleted immediately after analysis
- **API calls**: Only uses user-configured AI API, data processed locally
- **Token validation**: Only verifies plan eligibility, no financial data stored

---

## Error Handling

| Error | Resolution |
|-------|-----------|
| "Unsupported format" | Use CSV, Excel (.xlsx/.xls), or PDF with copyable text |
| AI analysis failed | Check API key validity and balance; try another model |
| Report data inaccurate | AI analysis is for reference only; verify against source files |

---

## Tech Stack

- **Parsing**: Python 3 + pandas + openpyxl + pdfplumber
- **AI Interface**: OpenAI-compatible REST API
- **Runtime**: Node.js (OpenClaw Agent)

---

## Billing

- **Endpoint**: `POST https://skillpay.me/api/v1/billing/charge`
- **Header**: `X-API-Key: {api_key}`
- **Body**: `{"user_id": "...", "skill_id": "ai-financial-report", "amount": 0}`
- **Response**: `{"success": true, "balance": ...}`
- **Fallback**: Network error → FREE tier (usage not blocked)
- **Cache**: Validation result cached locally (SHA256 hash), TTL 5 minutes

## Env Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OPENCLAW_SKILL_DIR` | Skill root (for cache) | `__dirname/..` |
| `SKILL_BILLING_API_KEY` | Builder API Key (from SkillPay) | — |
| `SKILL_BILLING_SKILL_ID` | Skill Slug | `ai-financial-report` |

> For builder setup: visit [https://skillpay.me](https://skillpay.me)