ff1-cli 1.0.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,178 @@
+# Configuration Guide
+
+This guide explains how to configure FF1‑CLI, field by field. Configuration priority is:
+
+- `config.json` (highest)
+- `.env`
+- built‑in defaults (lowest)
+
+## Getting started
+
+```bash
+# Create example config and edit it
+npm run dev -- config init
+
+# Validate your configuration
+npm run dev -- config validate
+
+# Show current config summary
+npm run dev -- config show
+```
+
+## Top‑level fields
+
+- **defaultModel** (string)
+  - The default AI model key to use. Must match a key under `models`.
+  - Used by orchestration to pick API, timeouts, and model identifier.
+
+- **defaultDuration** (number, seconds)
+  - Intended default per‑item display duration. Some flows pass an explicit duration; when omitted, utilities fall back to 10s.
+
+## models
+
+Each key under `models` defines a model configuration used by the AI orchestrator.
+
+- `<modelName>.apiKey` (string): API key for the provider.
+- `<modelName>.baseURL` (string): Base API URL.
+- `<modelName>.model` (string): Model identifier (e.g., `grok-beta`, `gpt-4o`).
+- `<modelName>.availableModels` (string[], optional): Display/help only.
+- `<modelName>.timeout` (number, ms): HTTP timeout for requests.
+- `<modelName>.maxRetries` (number): Retry count for requests.
+- `<modelName>.temperature` (number): Generation temperature.
+- `<modelName>.maxTokens` (number): Token cap.
+- `<modelName>.supportsFunctionCalling` (boolean): Must be true; otherwise the CLI rejects the model.
+
+Environment variable helpers:
+
+- Grok: `GROK_API_KEY`, `GROK_MODEL`, `GROK_API_BASE_URL`
+- OpenAI: `OPENAI_API_KEY`
+- Gemini: `GEMINI_API_KEY`
+
+## browser
+
+Optional settings used where headless/browser‑like behavior is needed.
+
+- `browser.timeout` (number, ms): Operation timeout (default 90000).
+- `browser.sanitizationLevel` ("none" | "low" | "medium" | "high" | 0‑3): Converted to numeric via `sanitizationLevelToNumber()`; invalid values are flagged during validation.
+
+## playlist
+
+Used for signing DP‑1 playlists.
+
+- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`.
+
+### Generate an Ed25519 private key
+
+You can generate a key locally. The CLI accepts either base64 (preferred) or hex
+
+OpenSSL (recommended):
+
+```bash
+# Base64 (preferred)
+openssl genpkey -algorithm ED25519 -outform DER | base64 | tr -d '\n'
+
+# Hex (alternative)
+openssl genpkey -algorithm ED25519 -outform DER | xxd -p -c 256
+```
+
+Paste either value into `playlist.privateKey`:
+
+- Hex example (either is valid):
+  - `0xabc123...` (with prefix)
+  - `abc123...` (without prefix)
+- Base64 example: `uQd9m8S...==`
+
+If you already have a base64 key and want hex, convert it:
+
+```bash
+echo -n "<BASE64_KEY>" | base64 -d | xxd -p -c 256
+```
+
+## feed
+
+DP‑1 Feed API configuration.
+
+- `feed.baseURLs` (string[]): Array of DP‑1 Feed Operator API v1 base URLs. The CLI queries all feeds in parallel.
+- Legacy support: `feed.baseURL` (string) is still accepted and normalized to an array.
+- Default: `https://feed.feralfile.com/api/v1` if not set.
+- Compatibility: API v1 of the DP‑1 Feed Operator server. See the repository for endpoints and behavior: [dp1-feed](https://github.com/display-protocol/dp1-feed).
+
+Endpoints used by the CLI:
+
+- `GET /api/v1/playlists` (supports `limit`, `offset`, and sorting)
+- `GET /api/v1/playlists/{id}`
+
+Environment variable alternative:
+
+```env
+FEED_BASE_URLS=https://feed.feralfile.com/api/v1,https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1
+```
+
+## ff1Devices
+
+Configure devices you want to send playlists to.
+
+- `ff1Devices.devices` (array of objects):
+  - `name` (string): Friendly device label. Free‑form; pick anything memorable.
+  - `host` (string): Device base URL. For LAN devices, use `http://<ip>:1111`. The device typically listens on port `1111`.
+
+Selection rules when sending:
+
+- If you omit `-d`, the first configured device is used.
+- If you pass `-d <name>`, the CLI matches the device by `name` (exact match). If not found, you’ll see an error listing available devices.
+
+Examples:
+
+```bash
+# Send to first device
+npm run dev -- send playlist.json
+
+# Send to a specific device by exact name
+npm run dev -- send playlist.json -d "Living Room Display"
+```
+
+Minimal `config.json` example (selected fields):
+
+```json
+{
+  "defaultModel": "grok",
+  "models": {
+    "grok": {
+      "apiKey": "xai-your-api-key-here",
+      "baseURL": "https://api.x.ai/v1",
+      "model": "grok-beta",
+      "supportsFunctionCalling": true
+    }
+  },
+  "defaultDuration": 10,
+  "playlist": {
+    "privateKey": "your_ed25519_private_key_hex_or_base64_here"
+  },
+  "feed": {
+    "baseURLs": [
+      "https://feed.feralfile.com/api/v1"
+    ]
+  },
+  "ff1Devices": {
+    "devices": [
+      {
+        "name": "Living Room Display",
+        "host": "http://192.168.1.100:1111"
+      }
+    ]
+  }
+}
+```
+
+## Security and validation
+
+- Do not commit secrets. Keep `config.json`, `.env`, and keys out of version control.
+- Validate changes regularly:
+
+```bash
+npm run dev -- config validate
+```
+
+If configuration is invalid, the CLI prints actionable errors and a non‑zero exit code.
+
+

package/docs/EXAMPLES.md

@@ -0,0 +1,331 @@
+# Examples
+
+Copy‑pasteable commands that work with the current CLI.
+
+## Setup
+
+```bash
+npm install
+npm run dev -- config init
+npm run dev -- config validate
+```
+
+## Natural Language
+
+```bash
+# Interactive chat
+npm run dev chat
+
+# One-shot requests
+npm run dev -- chat "Get tokens 1,2,3 from Ethereum contract 0xabc" -o playlist.json
+npm run dev -- chat "Get token 42 from Tezos contract KT1abc"
+npm run dev -- chat "Get 3 items from Social Codes and 2 from 0xdef" -v
+
+# Switch model
+npm run dev -- chat "your request" --model grok
+npm run dev -- chat "your request" --model chatgpt
+npm run dev -- chat "your request" --model gemini
+```
+
+## Deterministic Build (no AI)
+
+```bash
+# From file
+npm run dev -- build examples/params-example.json -o playlist.json
+
+# From stdin
+cat examples/params-example.json | npm run dev -- build -o playlist.json
+```
+
+## AI‑Orchestrated Deterministic Flow (prompts)
+
+```bash
+# Show tool‑call progress and validation
+npm run dev -- chat "Build a playlist of my Tezos works from address tz1... plus 3 from Social Codes" -v -o playlist.json
+
+# Switch model if desired
+npm run dev -- chat "Build playlist from Ethereum address 0x... and 2 from Social Codes" --model chatgpt -v
+```
+
+### One‑shot complex prompt
+
+The CLI can parse rich requests and do it all in one go: fetch, build a DP‑1 playlist, shuffle, set durations, and send to a named device.
+
+```bash
+# Example: combine sources, shuffle, set 6s per item, and send to device
+npm run dev -- chat "Get tokens 1,2 from contract 0xabc and token 42 from KT1xyz; shuffle; 6 seconds each; send to 'Living Room Display'." -o playlist.json -v
+```
+
+## Natural Language: Display and Publish
+
+The CLI recognizes publishing keywords like "publish", "publish to my feed", "push to feed", "send to feed" and automatically publishes after building.
+
+### Basic Publishing
+
+```bash
+# Build and publish
+npm run dev -- chat "Build playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 with tokens 52932 and 52457; publish to my feed" -o playlist.json -v
+
+# With feed selection (if multiple servers configured)
+# The CLI will ask: "Which feed server? 1) https://feed.feralfile.com/api/v1 2) http://localhost:8787"
+npm run dev -- chat "Get 3 from Social Codes and publish to feed" -v
+
+# Publish existing playlist (defaults to ./playlist.json)
+npm run dev chat
+# Then type: "publish playlist"
+
+# Publish specific playlist file
+npm run dev chat
+# Then type: "publish the playlist ./playlist-temp.json"
+```
+
+### Combined: Display + Publish
+
+```bash
+# Display on FF1 AND publish to feed
+npm run dev -- chat "Build playlist from contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 with tokens 52932 and 52457; mix them up; send to my FF1 and publish to my feed" -o playlist.json -v
+
+# With explicit device name
+npm run dev -- chat "Get 5 from Social Codes, shuffle, display on 'Living Room', and publish to feed" -v
+```
+
+### How It Works
+
+**Mode 1: Build and Publish** (when sources are mentioned)
+1. Intent parser detects "publish" keywords with sources/requirements
+2. Calls `get_feed_servers` to retrieve configured servers
+3. If 1 server → uses it automatically; if 2+ servers → asks user to pick
+4. Builds playlist → verifies → publishes automatically
+
+**Mode 2: Publish Existing File** (e.g., "publish playlist")
+1. Intent parser detects "publish playlist" or similar phrases
+2. Calls `get_feed_servers` to retrieve configured servers
+3. If 1 server → uses it automatically; if 2+ servers → asks user to pick
+4. Publishes the playlist from `./playlist.json` (or specified path)
+
+Output shows:
+- Playlist build progress (Mode 1 only)
+- Device sending (if requested): `✓ Sent to device: Living Room`
+- Publishing status: `✓ Published to feed server`
+- Playlist ID: `Playlist ID: 84e028f8-...`
+
+## Validate / Sign / Send
+
+```bash
+# Validate playlist
+npm run dev -- validate playlist.json
+
+# Sign playlist
+npm run dev -- sign playlist.json -o signed.json
+
+# Send to device
+npm run dev -- send playlist.json -d "Living Room Display"
+```
+
+## Publish to Feed Server
+
+Publish validated playlists to a DP-1 feed server for sharing and discovery.
+
+### Configuration
+
+Add feed servers to `config.json`:
+
+```json
+{
+  "feedServers": [
+    {
+      "baseUrl": "http://localhost:8787/api/v1",
+      "apiKey": "your-api-key"
+    },
+    {
+      "baseUrl": "https://feed.example.com/api/v1",
+      "apiKey": "your-api-key"
+    }
+  ]
+}
+```
+
+### Publish Commands
+
+```bash
+# Interactive: list servers and ask which to use
+npm run dev -- publish playlist.json
+
+# Direct: publish to specific server (server index 0)
+npm run dev -- publish playlist.json -s 0
+
+# Show help
+npm run dev -- publish --help
+```
+
+### Flow
+
+1. **Validate** - Playlist verified against DP-1 specification
+2. **Select Server** - If multiple servers, choose which one (interactive or via `-s` flag)
+3. **Publish** - Send validated playlist to selected feed server
+4. **Confirm** - Returns playlist ID and server details
+
+### Example Output
+
+```
+$ npm run dev -- publish playlist.json
+
+📡 Publishing playlist to feed server...
+
+Multiple feed servers found. Select one:
+  0: http://localhost:8787/api/v1
+  1: https://feed.example.com/api/v1
+
+Select server (0-based index): 0
+
+✅ Playlist published successfully!
+   Playlist ID: 84e028f8-ea12-4779-a496-64f95f0486cd
+   Server: http://localhost:8787/api/v1
+   Status: Published to feed server (created)
+```
+
+### Error Handling
+
+**Validation failed:**
+```
+❌ Failed to publish playlist
+   Playlist validation failed: dpVersion: Required; id: Required
+```
+
+**File not found:**
+```
+❌ Failed to publish playlist
+   Playlist file not found: /path/to/playlist.json
+```
+
+**API error:**
+```
+❌ Failed to publish playlist
+   Failed to publish: {"error":"unauthorized","message":"Invalid API key"}
+```
+
+## Validate / Sign / Send / Publish (Complete Flow)
+
+```bash
+# 1. Create a playlist (via chat or build)
+npm run dev -- chat "Get tokens 1,2,3 from contract 0xabc" -o playlist.json
+
+# 2. Validate it
+npm run dev -- validate playlist.json
+
+# 3. Sign it
+npm run dev -- sign playlist.json -o signed.json
+
+# 4. Send to device
+npm run dev -- send signed.json -d "My Display"
+
+# 5. Publish to feed server
+npm run dev -- publish signed.json -s 0
+```
+
+## Troubleshooting
+
+```bash
+# Show current configuration
+npm run dev -- config show
+
+# Reinitialize config
+npm run dev -- config init
+```
+
+
+### Natural‑language one‑shot examples (proven)
+
+- **ETH contract + token IDs (shuffle/mix, generic device)**
+  - Format:
+    ```bash
+    npm run dev -- chat "Compose a playlist from Ethereum contract <0x...> with tokens <id> and <id>; [shuffle|mix]; [send to device|send to '<device>']" -o <output.json> -v
+    ```
+  - Example:
+    ```bash
+    npm run dev -- chat "Compose a playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 with tokens 52932 and 52457; mix them up; send to device" -o playlist-eth.json -v
+    ```
+
+- **TEZ contract + token IDs (shuffle, named device)**
+  - Format:
+    ```bash
+    npm run dev -- chat "Build a playlist from Tezos contract <KT1...> with tokens <id> and <id>; shuffle; send to '<device>'" -o <output.json> -v
+    ```
+  - Example:
+    ```bash
+    npm run dev -- chat "Build a playlist from Tezos contract KT1BcNnzWze3vCviwiETYNwcFSwjv6RihZEQ with tokens 22 and 8; shuffle; send to 'Living Room'" -o playlist-tez.json -v
+    ```
+
+- **Owner address (ENS → ETH), shuffled**
+  - Format:
+    ```bash
+    npm run dev -- chat "Create a playlist from address <ens> (<n> items); [shuffle|mix]; [send/push to my device]" -o <output.json> -v
+    ```
+  - Example:
+    ```bash
+    npm run dev -- chat "Create a playlist from address reas.eth (5 items); shuffle; push to my device" -o playlist-ens.json -v
+    ```
+
+- **Owner address (Tezos tz1), shuffled**
+  - Format:
+    ```bash
+    npm run dev -- chat "Create a playlist from Tezos address <tz1...> (<n> items); [shuffle|mix]; [send to device]" -o <output.json> -v
+    ```
+  - Example:
+    ```bash
+    npm run dev -- chat "Create a playlist from Tezos address tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb (3 items); mix them up; send to device" -o playlist-tz1.json -v
+    ```
+
+- **Feed playlists (named), shuffled**
+  - Format:
+    ```bash
+    npm run dev -- chat "[Create|Build] a playlist from feed '<name>' (<n> items); shuffle; [send to device]" -o <output.json> -v
+    ```
+  - Examples:
+    ```bash
+    npm run dev -- chat "Create a playlist from feed 'Unsupervised' (3 items); shuffle; send to device" -o playlist-feed1.json -v
+    npm run dev -- chat "Build a playlist from feed 'Social Codes' (3 items); shuffle; send to device" -o playlist-feed2.json -v
+    ```
+
+- **Mixed in one prompt (ETH + TEZ + feed + ENS), shuffled, named device**
+  - Format:
+    ```bash
+    npm run dev -- chat "Compose a playlist: Tezos <KT1...> tokens <id>, <id>; Ethereum <0x...> tokens <id>, <id>; <n> from '<feed>'; <m> from <ens>; shuffle; send to '<device>'" -o <output.json> -v
+    ```
+  - Example:
+    ```bash
+    npm run dev -- chat "Compose a playlist: Tezos KT1BcNnzWze3vCviwiETYNwcFSwjv6RihZEQ tokens 22, 8; Ethereum 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 tokens 52932, 52457; 3 from 'Unsupervised'; 1 from reas.eth; shuffle; send to 'Living Room'" -o playlist-mixed.json -v
+    ```
+
+- **Multiple instructions in one prompt (incremental), shuffled**
+  - Format:
+    ```bash
+    npm run dev -- chat "Create a playlist from Ethereum contract <0x...> tokens <id>, <id>; then add <n> from '<feed>'; then add <m> from <ens>; shuffle; [send/push to my device]" -o <output.json> -v
+    ```
+  - Example:
+    ```bash
+    npm run dev -- chat "Create a playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 tokens 52932, 52457; then add 2 from 'Social Codes'; then add 1 from reas.eth; shuffle; push to my device" -o playlist-multi.json -v
+    ```
+
+- **Synonym variants for the same ETH case**
+  - Format:
+    ```bash
+    npm run dev -- chat "[Build|Create|Compose] a playlist from Ethereum contract <0x...> tokens <id> and <id>; send to device" -o <output.json> -v
+    ```
+  - Examples:
+    ```bash
+    npm run dev -- chat "Build a playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 tokens 52932 and 52457; send to device" -o playlist-eth-build.json -v
+    npm run dev -- chat "Create a playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 tokens 52932 and 52457; send to device" -o playlist-eth-create.json -v
+    ```
+
+- **Device targeting: generic vs named**
+  - Format:
+    ```bash
+    npm run dev -- chat "Compose a playlist from <ens/address> (<n> items); send to device" -o <output.json> -v
+    npm run dev -- chat "Compose a playlist from <ens/address> (<n> items); send to '<device>'" -o <output.json> -v
+    ```
+  - Examples:
+    ```bash
+    npm run dev -- chat "Compose a playlist from reas.eth (3 items); send to device" -o playlist-generic-device.json -v
+    npm run dev -- chat "Compose a playlist from reas.eth (3 items); send to 'Living Room'" -o playlist-named-device.json -v
+    ```

package/docs/FUNCTION_CALLING.md

@@ -0,0 +1,92 @@
+# Function Calling Architecture
+
+How FF1‑CLI uses AI function calling to build playlists deterministically. The model orchestrates function calls; tools enforce schema and assemble the DP-1 envelope.
+
+## Overview
+
+Natural language requests become structured parameters. An AI orchestrator then calls functions to fetch items, build a DP-1 playlist, verify it, optionally sign, and send to a device.
+
+Pipeline:
+
+```
+Intent Parser → Orchestrator (function calls) → Utilities → DP-1 Playlist
+```
+
+Key files:
+
+- `src/intent-parser/` – Parses user text into `requirements` + `playlistSettings`
+- `src/ai-orchestrator/index.js` – Function schemas and orchestration logic
+- `src/utilities/` – Concrete implementations used by the orchestrator
+- `src/main.ts` – Bridges CLI commands to parser/orchestrator/utilities
+
+## Function Schemas (AI‑visible)
+
+Defined in `src/ai-orchestrator/index.js` as tool schemas for OpenAI‑compatible clients.
+
+- `query_requirement(requirement, duration)`
+  - Types: `build_playlist`, `fetch_feed`, `query_address`
+  - For `build_playlist`: requires `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`
+  - For `query_address`: requires `ownerAddress`, optional `quantity` (random selection)
+  - For `fetch_feed`: requires `playlistName`, `quantity`
+
+- `search_feed_playlist(playlistName)` → fuzzy-match across configured feeds
+- `fetch_feed_playlist_items(playlistName, quantity, duration)`
+- `build_playlist(items, title?, slug?, shuffle?)` → returns DP-1 playlist
+- `verify_playlist(playlist)` → validates DP-1 compliance (must precede send)
+- `verify_addresses(addresses[])` → validates Ethereum (0x...) and Tezos (tz.../KT1) address formats
+- `send_to_device(playlist, deviceName?)`
+- `resolve_domains(domains[], displayResults?)` → ENS/TNS resolution
+
+Notes enforced by the orchestrator:
+
+- Always pass complete requirement objects (no truncating addresses/token IDs)
+- Resolve domains (`.eth`, `.tez`) before `query_address`
+- Build, then verify before sending to devices
+- Shuffle is controlled by `playlistSettings.preserveOrder`
+
+## Implementations (server‑side)
+
+Located in `src/utilities/` and wired in `src/ai-orchestrator/index.js`:
+
+- `buildDP1Playlist({ items, title, slug })` → `src/utilities/playlist-builder.js`
+- `sendPlaylistToDevice({ playlist, deviceName })` → `src/utilities/ff1-device.ts`
+- `resolveDomains({ domains, displayResults })` → `src/utilities/domain-resolver.ts`
+- `verifyPlaylist({ playlist })` → `src/utilities/playlist-verifier.ts`
+- `verifyAddresses({ addresses })` → `src/utilities/functions.js` (uses `address-validator.ts`)
+- Feed utilities: `feed-fetcher.js`
+
+## Deterministic Paths
+
+Two options are available:
+
+1) No-AI deterministic build (recommended for automation): Use CLI `build` command with a JSON file or stdin containing:
+
+```json
+{
+  "requirements": [
+    { "type": "fetch_feed", "playlistName": "Social Codes", "quantity": 3 },
+    { "type": "build_playlist", "blockchain": "ethereum", "contractAddress": "0x...", "tokenIds": ["1","2"], "quantity": 2 }
+  ],
+  "playlistSettings": { "durationPerItem": 10, "preserveOrder": true, "title": "My Mix" }
+}
+```
+
+This path bypasses the intent parser/orchestrator and calls utilities directly. Validation and sensible defaults are applied in `src/main.ts`.
+
+2) AI‑orchestrated deterministic build (recommended for prompts): Use `chat` with `--verbose` to see tool calls. The orchestrator enforces complete requirement objects, then validates the result with `verify_playlist` before sending.
+
+## Extending Functionality (OSS‑first)
+
+1. Add a new function in `src/utilities/` (prefer OSS libs: `viem` for Ethereum, `@taquito/taquito` for Tezos; add local caching where it helps)
+2. Export and wire it in `src/utilities/index.js`
+3. Add a corresponding schema in `src/ai-orchestrator/index.js`
+4. Update this doc if user‑facing behavior changes
+5. Run `npm run lint:fix`
+
+## Validation & Constraints
+
+- Verify via `dp1-js` for DP-1 conformance (canonical JSON + Ed25519 signing supported)
+- Enforce max item counts and ordering/shuffle rules during build
+- Batch domain resolution; report failures without crashing the flow
+
+