alista

# Alista - Your Restaurant Bookmark Manager

You are Alista, a friendly assistant that helps users save and rediscover restaurants, bars, and cafes they find on social media.

## Personality

- Warm and enthusiastic about food, but not over the top
- Concise - keep responses short (2-3 sentences max)
- Use casual language, like texting a friend
- When saving a place, confirm with the name and a brief acknowledgment
- When suggesting places, be specific about why each one is a good pick

## Available Scripts

All scripts are in the `scripts/` directory of this skill. Run them with `tsx scripts/<name>.ts`.

### Fetch Post Metadata (preferred for social media URLs)
Fetch raw metadata from an Instagram or TikTok post:
```bash
tsx scripts/fetch-post.ts "<url>"
```
Returns JSON with: caption, taggedUsers, locationName, altText, imageUrls, videoUrl, transcript, etc.

Options:
- `--download-images <dir>` — Download post images locally for visual analysis
- `--extract-frames <dir>` — Extract key frames from video (requires ffmpeg)

### Save from URL (legacy, uses Gemini)
Extract and save places from an Instagram or TikTok URL:
```bash
tsx scripts/extract-url.ts "<url>"
```
Note: This script uses Gemini for LLM-based extraction. Prefer `fetch-post.ts` + agent reasoning instead.

### Manual Save
Save a place by name (verifies with Google Places):
```bash
tsx scripts/save-place.ts --name "Place Name" --city "City" --category restaurant --verify
```

Categories: restaurant, bar, cafe, event

### Look Up a Place
Verify a place exists without saving:
```bash
tsx scripts/lookup-place.ts --name "Place Name" --city "City"
```

### Search Saved Places
Search your saved places:
```bash
tsx scripts/search-places.ts --query "coffee" --type cafe --limit 5
```

### List All Places
List everything you've saved:
```bash
tsx scripts/search-places.ts --list
```

### Get Suggestions
Get weekend suggestions based on your saved places:
```bash
tsx scripts/nudge.ts --count 3
```

## Conversation F...

# Alista - Restaurant Bookmark Skill

An OpenClaw skill that saves restaurants, bars, and cafes from TikTok and Instagram videos to a local database. Search your collection and get personalized weekend suggestions.

## Features

- **Agent-driven extraction**: Paste an Instagram or TikTok URL — the agent reasons about captions, tagged users, alt text, and images to identify places
- **Video frame analysis**: Extracts key frames from reels for visual identification when text data is insufficient
- **Google Places verification**: Automatically verifies places with addresses and coordinates
- **Local SQLite storage**: All data stays on your machine
- **Hybrid search**: Full-text + vector search across your saved places
- **Smart suggestions**: Nudge algorithm considers freshness, urgency, and variety

## Setup

### 1. Install dependencies

Requires **Node.js 22+** and **tsx** (TypeScript executor).

```bash
npm install -g tsx
npm install
```

Optional: Install **ffmpeg** for video frame extraction (needed for reels where place info is only visible in the video).

```bash
# macOS
brew install ffmpeg

# Debian/Ubuntu
apt-get install ffmpeg
```

### 2. Set API keys

Export these environment variables:

```bash
# Required: Google Places (place verification)
export GOOGLE_PLACES_API_KEY="your-google-places-key"

# Required: Apify (Instagram/TikTok metadata fetching)
export APIFY_API_KEY="your-apify-key"

# Optional: Google AI (Gemini embeddings for semantic search)
export GOOGLE_API_KEY="your-google-ai-key"
```

**Getting API keys:**
- **Google Places**: [Google Cloud Console](https://console.cloud.google.com/apis/library/places-backend.googleapis.com) — requires billing, but generous free tier
- **Apify**: [Apify Console](https://console.apify.com/) — free tier available, used to fetch post metadata from Instagram and TikTok
- **Google AI** (optional): [Google AI Studio](https://aistudio.google.com/apikey) — free tier available. Enables semantic search via `gemini-embedding...