vargai 0.3.0

package/SKILLS.md

@@ -0,0 +1,173 @@
+# agent skills
+
+this sdk includes claude code agent skills for each service. each skill is co-located with its service code.
+
+## available skills
+
+### service skills
+
+located in `service/<name>/SKILL.md`:
+
+1. **image-generation** (`service/image/`)
+   - generate ai images using fal (flux models) or higgsfield soul characters
+   - cli: `bun run service/image fal|soul <prompt> [options]`
+
+2. **video-generation** (`service/video/`)
+   - generate videos from images (local or url) or text prompts using fal.ai
+   - supports local image files - automatically uploads to fal storage
+   - cli: `bun run service/video from_image|from_text <args>`
+
+3. **voice-synthesis** (`service/voice/`)
+   - generate realistic text-to-speech audio using elevenlabs
+   - cli: `bun run service/voice generate|elevenlabs <text> [options]`
+
+3b. **music-generation** (`lib/elevenlabs.ts`)
+   - generate music from text prompts using elevenlabs
+   - generate sound effects from descriptions
+   - cli: `bun run lib/elevenlabs.ts music|sfx <prompt> [options]`
+
+4. **video-lipsync** (`service/sync/`)
+   - sync video with audio using wav2lip or simple overlay
+   - cli: `bun run service/sync sync|wav2lip|overlay <args>`
+
+5. **video-captions** (`service/captions/`)
+   - add auto-generated or custom subtitles to videos
+   - cli: `bun run service/captions <videoPath> [options]`
+
+6. **video-editing** (`service/edit/`)
+   - edit videos with ffmpeg (resize, trim, concat, social media prep)
+   - cli: `bun run service/edit social|montage|trim|resize|merge_audio <args>`
+
+7. **audio-transcription** (`service/transcribe/`)
+   - transcribe audio to text or subtitles using groq/fireworks
+   - cli: `bun run service/transcribe <audioUrl> <provider> [outputPath]`
+
+### library skills
+
+8. **apify-scraping** (`lib/apify.ts`)
+   - run apify actors for web scraping (tiktok, google maps, social media, etc.)
+   - cli: `bun run lib/apify.ts run <actor_id> [input_json]`
+   - example: `bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["viral"],"resultsPerPage":10}'`
+
+### utility skills
+
+9. **telegram-send** (external: `/Users/aleks/Github/Badaboom1995/rumble-b2c`)
+   - send videos to telegram users/channels as round videos
+   - automatically converts to 512x512 square format for telegram
+   - cli: `cd /Users/aleks/Github/Badaboom1995/rumble-b2c && bun run scripts/telegram-send-video.ts <videoPath> <@username>`
+   - example: `cd /Users/aleks/Github/Badaboom1995/rumble-b2c && bun run scripts/telegram-send-video.ts /path/to/video.mp4 @caffeinum`
+
+### pipeline skills
+
+located in `pipeline/cookbooks/SKILL.md`:
+
+10. **talking-character-pipeline** (`pipeline/cookbooks/`)
+    - complete workflow to create talking character videos
+    - combines: character generation → voiceover → animation → lipsync → captions → social prep
+
+11. **round-video-character** (`pipeline/cookbooks/round-video-character.md`)
+    - create realistic round selfie videos for telegram using nano banana pro + wan 2.5
+    - workflow: generate selfie first frame (person in setting) → voiceover → wan 2.5 video
+    - uses: `bun run lib/fal.ts`, `bun run lib/replicate.ts`, `bun run lib/elevenlabs.ts`
+    - input: text script + profile photo
+    - output: extreme close-up selfie video with authentic camera shake, lighting, and audio
+
+12. **trendwatching** (`pipeline/cookbooks/trendwatching.md`)
+    - discover viral tiktok content for any topic/hashtag
+    - uses apify tiktok scraper to find trending videos
+    - get engagement metrics: plays, likes, shares, comments
+    - cli: `bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["topic"],"resultsPerPage":10}'`
+
+## structure
+
+each skill follows this pattern:
+
+```
+service/<name>/
+├── index.ts      # service implementation
+└── SKILL.md      # claude code agent skill
+```
+
+## how skills work
+
+skills are **model-invoked** - claude autonomously decides when to use them based on your request and the skill's description.
+
+**example:**
+- you say: "create a talking character video"
+- claude reads `talking-character-pipeline` skill
+- claude executes the workflow using the pipeline steps
+
+## using skills
+
+### in claude code
+
+skills are automatically discovered when you're in the sdk directory:
+
+```
+user: create an image of a sunset
+claude: [uses image-generation skill]
+        bun run service/image fal "beautiful sunset over mountains"
+```
+
+### manually
+
+you can also run services directly:
+
+```bash
+# generate image
+bun run service/image fal "sunset over mountains" true
+
+# generate video from that image
+bun run service/video from_image "camera pan" https://image-url.jpg 5 true
+
+# add voice
+bun run service/voice elevenlabs "this is a beautiful sunset" rachel true
+
+# sync with video
+bun run service/sync wav2lip https://video-url.mp4 https://audio-url.mp3
+```
+
+## skill features
+
+each skill includes:
+
+- **name**: unique skill identifier
+- **description**: when claude should use this skill
+- **allowed-tools**: restricted to Read, Bash for safety
+- **usage examples**: cli and programmatic examples
+- **when to use**: specific use cases
+- **tips**: best practices
+- **environment variables**: required api keys
+
+## benefits
+
+- **discoverability**: claude knows all available services
+- **context**: skills provide usage examples and best practices
+- **safety**: `allowed-tools` limits to read-only and bash execution
+- **documentation**: skills serve as living documentation
+
+## skill reference
+
+| skill | service | primary use case |
+|-------|---------|------------------|
+| image-generation | image | create ai images, character headshots |
+| video-generation | video | animate images, generate video clips |
+| voice-synthesis | voice | text-to-speech, voiceovers |
+| music-generation | elevenlabs | generate music, create sound effects |
+| video-lipsync | sync | sync audio with video, talking characters |
+| video-captions | captions | add subtitles, accessibility |
+| video-editing | edit | resize, trim, social media optimization |
+| audio-transcription | transcribe | speech-to-text, subtitle generation |
+| apify-scraping | lib/apify | web scraping via apify actors (tiktok, etc.) |
+| telegram-send | external | send videos to telegram as round videos |
+| talking-character-pipeline | pipeline | end-to-end talking character videos |
+| round-video-character | pipeline | telegram round selfie videos with wan 2.5 |
+| trendwatching | pipeline | discover viral tiktok content by hashtag |
+
+## see also
+
+- [README.md](README.md) - sdk overview and installation
+- [STRUCTURE.md](STRUCTURE.md) - detailed module organization
+- [pipeline/cookbooks/talking-character.md](pipeline/cookbooks/talking-character.md) - talking character workflow
+- [pipeline/cookbooks/round-video-character.md](pipeline/cookbooks/round-video-character.md) - telegram round selfie video cookbook
+- [pipeline/cookbooks/trendwatching.md](pipeline/cookbooks/trendwatching.md) - discover viral tiktok content

package/STRUCTURE.md

@@ -0,0 +1,92 @@
+# sdk structure
+
+## lib/ - two fal implementations
+
+### lib/ai-sdk/fal.ts
+uses `@ai-sdk/fal` with vercel ai sdk
+
+**when to use:**
+- standard image generation
+- need consistent api across providers
+- want automatic image format handling
+- prefer typed aspect ratios
+
+**commands:**
+```bash
+bun run lib/ai-sdk/fal.ts generate_image <prompt> [model] [aspectRatio]
+```
+
+### lib/fal.ts
+uses `@fal-ai/client` directly
+
+**when to use:**
+- video generation (image-to-video, text-to-video)
+- advanced fal features
+- need queue/streaming updates
+- custom api parameters
+
+**commands:**
+```bash
+bun run lib/fal.ts generate_image <prompt> [model] [imageSize]
+bun run lib/fal.ts image_to_video <prompt> <imageUrl> [duration]
+bun run lib/fal.ts text_to_video <prompt> [duration]
+```
+
+### lib/higgsfield.ts
+uses `@higgsfield/client` for soul character generation
+
+**commands:**
+```bash
+bun run lib/higgsfield.ts generate_soul <prompt> [customReferenceId]
+bun run lib/higgsfield.ts create_character <name> <imageUrl1> [imageUrl2...]
+bun run lib/higgsfield.ts list_styles
+```
+
+## service/ - high-level wrappers
+
+### service/image.ts
+combines fal + higgsfield for image generation
+
+```bash
+bun run service/image.ts fal <prompt> [model] [upload]
+bun run service/image.ts soul <prompt> [customReferenceId] [upload]
+```
+
+### service/video.ts
+video generation with optional s3 upload
+
+```bash
+bun run service/video.ts from_image <prompt> <imageUrl> [duration] [upload]
+bun run service/video.ts from_text <prompt> [duration] [upload]
+```
+
+## utilities/
+
+### utilities/s3.ts
+cloudflare r2 / s3 storage operations
+
+```bash
+bun run utilities/s3.ts upload <filePath> <objectKey>
+bun run utilities/s3.ts upload_from_url <url> <objectKey>
+bun run utilities/s3.ts presigned_url <objectKey> [expiresIn]
+```
+
+## pipeline/cookbooks/
+markdown guides for complex workflows
+
+- `talking-character.md`: create talking character videos
+
+## dependencies
+
+- `@ai-sdk/fal` - vercel ai sdk fal provider
+- `@fal-ai/client` - official fal client
+- `@higgsfield/client` - higgsfield api client
+- `@aws-sdk/client-s3` - s3 storage
+- `ai` - vercel ai sdk core
+
+## key decisions
+
+1. **two fal implementations** - ai-sdk for simplicity, client for power
+2. **all scripts are cli + library** - can be run directly or imported
+3. **consistent logging** - `[module] message` format
+4. **auto image opening** - ai-sdk version opens images automatically

package/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.7/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["**", "!node_modules", "!sdk-py-reference"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  }
+}