# Smart Trade AI — User Manual

An AI sales assistant for foreign trade, covering the full chain from finding customers to securing orders.

---

## 1. Installation

### macOS / Linux

```bash
curl -fsSL https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.sh | bash
```

### Windows

```powershell
powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.ps1' -OutFile install.ps1; .\install.ps1"
```

### Startup

```bash
python server.py
# Open browser at http://127.0.0.1:9119/trade
```

The first time you start, you need to configure the LLM API Key (in Hermes settings).

---

## 2. Interface Overview

The interface is split into left and right sections:

```
┌─────────────────┬──────────────────────────────────────────┐
│   Sidebar       │          Main Content Area               │
│  (Dark bg)      │    (Light bg, dynamically switching)     │
│                 │                                          │
│  🏢 Company     │   Chat / Customer Table / Task Panel /   │
│     Selector    │   History                                │
│  ═══════════    │                                          │
│  📊 Dashboard   │                                          │
│  🔍 Lead Gen    │                                          │
│  👤 Sales Conv. │                                          │
│  🛠️ Tools       │                                          │
│  💬 History     │                                          │
└─────────────────┴──────────────────────────────────────────┘
```

---

## 3. First-Time Use

### 3.1 Creating a Company

Click the **+** button next to the company selector at the top of the sidebar → fill in company info → click "Create Company".

When creating a company, the system automatically generates a working directory on the desktop:

```
~/Desktop/{Company Name}/
├── Quotes/
├── Contracts/
├── Client Profiles/
├── Product Specs/
├── Invoices/
├── Shipping Documents/
├── Certifications/
├── Marketing Materials/
└── Customs Data/
```

Place the relevant files into these folders and the AI can read and analyze them.

### 3.2 Configuring Agent Identity

After creating a company, configure the following in the "Agent Identity" tab of the popup:
- Company products and advantages
- Target markets
- Communication style preferences

---

## 4. Feature Details

### 📊 Dashboard — Daily Briefing

Every time you open Trade or click "Daily Briefing", the system will:
- Display today's scheduled task list (completed / pending / overdue)
- Show recent conversation history
- Type "Good morning briefing" to have the AI generate a full daily report

### 🔍 Lead Generation

#### Customer Development
Paste a LinkedIn link or customer info, and the AI will:
1. Analyze the customer's background
2. Generate a customized outreach email
3. Provide a follow-up plan (Day 1 / Day 3 / Day 7)

#### Website Diagnosis
Paste any website link (Alibaba International Station, company website, standalone site), the AI will browse the page and analyze:
- SEO quality (title, keywords, description)
- Tech stack detection
- Page design evaluation
- Provide specific optimization suggestions

#### Social Media Marketing
Describe your needs, and the AI will generate:
- Facebook / Instagram / TikTok / YouTube content calendar
- Specific post copy (ready to copy and paste)
- Image suggestions and hashtags

#### LinkedIn
- Personal profile optimization suggestions
- Company page content strategy
- Annual marketing plan
- InMail outreach templates

#### Customs Data
Place customs data files (CSV/Excel) into the desktop "Customs Data" folder, and the AI will automatically:
- Filter target buyers
- Analyze purchasing patterns
- Output a prioritized development list

### 👤 Sales Conversion

#### Customer Management
- **Table view**: View all customers (name/rating/country/contact info/associated document library/last follow-up)
- **Rating system**: A-tier (high value) / B-tier (medium) / C-tier (potential)
- **Batch operations**: Multi-select → batch delete
- **Sort toggle**: By name / by last follow-up time
- **Detail panel**: Click any customer row → full info panel slides in from the right
  - Edit basic info (name/title/country/email/phone/WhatsApp/LinkedIn/website, etc.)
  - Manage associated document libraries
  - View recent conversations

#### Document Libraries
- Auto-linked to the 9 folders in the desktop working directory
- Select a document library and ask questions; the AI automatically reads file contents to answer
- Supports 16 formats including PDF/Word/Excel/PPT/Images/CSV
- Click **+** to manually add other local directories

#### Document Generation
Describe your needs, and the AI will generate:
- PPT presentations (brand colors, multiple layouts)
- Word contracts/agreements
- Excel quotes (complete data, alternating row colors)

### 🛠️ Tools

#### Customer Background Check
Enter an email/domain/company name, and the AI performs a 6-layer verification:
1. Email platform registration check (120+ platforms)
2. WHOIS domain lookup (registration date/registrar/age)
3. Corporate email verification (@company domain vs personal email)
4. Sanctions list screening (OFAC/UN/EU)
5. Tech stack detection (site builder/payment/analytics tools)
6. LinkedIn verification (browser direct access)

Output: Comprehensive risk rating (low/medium/high) + action recommendations

#### Scheduled Tasks

The page is split into upper and lower sections:

**Upper section — Template Library**:
- 9 task templates (based on standard foreign trade workflows)
- Check the desired tasks → edit time → edit Prompt → click "Batch Generate"
- Custom templates can be added
- Good morning briefing is a mandatory task

**Lower section — Active Tasks**:
- Shows all running scheduled tasks
- Each task can be "Run Now"
- "Clear All Tasks" button

### 💬 History — Conversation Records

- Shows all conversations in reverse chronological order
- Search filtering
- Click any conversation → jump to the chat window to view full context
- Each conversation can be individually deleted

---

## 5. Common Operations

### Asking Questions

- **Direct questions**: The AI will automatically identify your intent and load the corresponding skill
- **Upload files**: Place files in the desktop working directory; the AI reads them automatically
- **Specify a skill**: Say "use b2b-osint to check this company"

### Viewing the Task List

Type "show task list" or "task list" or "today's tasks" in the chat box. The system will display the completion status of all scheduled tasks.

### Switching Companies

Use the dropdown at the top of the sidebar to select a company. All data (customers/document libraries/conversations) is isolated by company.

---

## 6. Data Storage

All data is stored locally and not uploaded to any server (except for LLM API calls):

| Data | Location |
|------|----------|
| Database | `~/.trade/data/trade.db` |
| Company profiles | `~/.trade/companies/{Company Name}/` |
| Desktop working directory | `~/Desktop/{Company Name}/` |
| LLM configuration | `~/.hermes/config.yaml` |
| API Key | `~/.hermes/.env` |

---

## 7. Frequently Asked Questions

**Q: How do I change the AI model?**
Run `hermes setup` to reconfigure.

**Q: How do I back up data?**
Simply copy the `~/.trade/` directory and the desktop working directory.

**Q: What formats does the AI support for document analysis?**
PDF, Word (.docx/.doc), Excel (.xlsx/.xls), PPT (.pptx/.ppt), CSV, images (.jpg/.png), Markdown, HTML, plain text.

**Q: Scheduled tasks are not executing?**
Make sure the Gateway is running (Trade will auto-start it on launch).

---

## 8. Security Notes

This tool runs in `YOLO` mode (AI tool calls require no human approval) because the target users are foreign trade sales representatives who do not have the technical judgment to approve each call.

Please make sure to:
1. Only use it on an internal network or locally
2. Do not expose it to the public internet
3. Keep your API Key secure
4. Back up data regularly
