@feralfile/cli 1.6.0 → 2.0.1

package/dist/src/intent-parser/utils.js

@@ -1,116 +0,0 @@
-"use strict";
-/**
- * Intent Parser Utilities
- * Validation and constraint enforcement for parsed requirements
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyConstraints = applyConstraints;
-const chalk_1 = __importDefault(require("chalk"));
-/**
- * Apply constraints to parsed requirements
- *
- * @param {Object} params - Parsed parameters
- * @param {Array<Object>} params.requirements - Array of requirements
- * @param {Object} [params.playlistSettings] - Playlist settings
- * @param {Object} _config - Application config (kept in the signature for
- *   call-site stability; no constraint reads it since durationPerItem
- *   pre-filling was removed in favor of DP-1 §4.1 auto timing)
- * @returns {Object} Validated parameters
- */
-function applyConstraints(params, _config) {
-    // Validate requirements array
-    if (!params.requirements || !Array.isArray(params.requirements)) {
-        throw new Error('Requirements must be an array');
-    }
-    if (params.requirements.length === 0) {
-        throw new Error('At least one requirement is needed');
-    }
-    // Validate each requirement
-    params.requirements = params.requirements.map((req, index) => {
-        const r = req;
-        if (!r.type) {
-            throw new Error(`Requirement ${index + 1}: type is required`);
-        }
-        // Validate based on type
-        if (r.type === 'build_playlist') {
-            if (!r.blockchain) {
-                throw new Error(`Requirement ${index + 1}: blockchain is required for build_playlist`);
-            }
-            if (!r.contractAddress) {
-                throw new Error(`Requirement ${index + 1}: contractAddress is required for build_playlist`);
-            }
-        }
-        else if (r.type === 'query_address') {
-            if (!r.ownerAddress) {
-                throw new Error(`Requirement ${index + 1}: ownerAddress is required for query_address`);
-            }
-        }
-        else if (r.type === 'fetch_feed') {
-            if (!r.playlistName) {
-                throw new Error(`Requirement ${index + 1}: playlistName is required for fetch_feed`);
-            }
-        }
-        else if (r.type === 'feral_file_artwork') {
-            if (!r.artworkId) {
-                throw new Error(`Requirement ${index + 1}: artworkId is required for feral_file_artwork`);
-            }
-        }
-        else {
-            throw new Error(`Requirement ${index + 1}: invalid type "${r.type}"`);
-        }
-        // Set default quantity if not provided
-        // Allow "all" as a string value for query_address type
-        let quantity;
-        if (r.quantity === 'all') {
-            quantity = 'all';
-        }
-        else if (r.quantity === null || r.quantity === undefined) {
-            quantity = 5;
-        }
-        else if (typeof r.quantity === 'string') {
-            // Try to parse string numbers
-            const parsed = parseInt(r.quantity, 10);
-            quantity = isNaN(parsed) ? r.quantity : parsed;
-        }
-        else {
-            quantity = r.quantity;
-        }
-        return {
-            ...r,
-            quantity: quantity, // No cap - registry system handles large playlists efficiently
-            tokenIds: r.tokenIds || [],
-        };
-    });
-    // Note: No cap needed - registry system handles large playlists efficiently
-    // Full items are stored in memory, only IDs are sent to AI model
-    const hasAllQuantity = params.requirements.some((r) => 'quantity' in r && r.quantity === 'all');
-    const totalRequested = params.requirements.reduce((sum, r) => {
-        if ('quantity' in r && typeof r.quantity === 'number') {
-            return sum + r.quantity;
-        }
-        return sum;
-    }, 0);
-    if (hasAllQuantity) {
-        console.log(chalk_1.default.yellow(`\nRequesting all tokens from one or more addresses. This may take a while to fetch and process.\n`));
-    }
-    else if (totalRequested > 100) {
-        console.log(chalk_1.default.yellow(`\nRequesting ${totalRequested} items. This may take a while to fetch and process.\n`));
-    }
-    // Set playlist defaults
-    if (!params.playlistSettings) {
-        params.playlistSettings = {};
-    }
-    // durationPerItem stays undefined unless the user asked for a per-item
-    // time: absence means auto timing downstream (video/audio omit duration
-    // and play their natural length per DP-1 §4.1; static media falls back to
-    // config.defaultDuration at item-build time). Pre-filling a number here
-    // would force-cut every video item.
-    // Only set preserveOrder if not already specified
-    if (params.playlistSettings.preserveOrder === undefined) {
-        params.playlistSettings.preserveOrder = true;
-    }
-    return params;
-}

package/docs/FUNCTION_CALLING.md

@@ -1,100 +0,0 @@
-# Function Calling Architecture
-
-How ff-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, validate structure (`verify_playlist`), 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`, `feral_file_artwork`, `fetch_feed`, `query_address`
-  - For `build_playlist`: requires `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`
-  - For `feral_file_artwork`: requires `artworkId`, either a Feral File public artwork id or `/exhibitions/artwork/{id}` URL
-  - 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)` → DP-1 parse/structure validation only (must precede send; use CLI `verify` for signatures)
-- `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_playlist` (structure) 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 })` in `functions.js` → delegates to `validatePlaylist` in `playlist-verifier.ts` (structure/parse only)
-- `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": "feral_file_artwork", "artworkId": "https://feralfile.com/exhibitions/artwork/..." },
-    {
-      "type": "build_playlist",
-      "blockchain": "ethereum",
-      "contractAddress": "0x...",
-      "tokenIds": ["1", "2"],
-      "quantity": 2
-    }
-  ],
-  "playlistSettings": { "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`.
-
-`playlistSettings.durationPerItem` is optional. Omit it for auto timing: video/audio items are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) and the media plays its natural length; static items fall back to `defaultDuration`. Set `durationPerItem` only to force a fixed display time on every item.
-
-2. AI‑orchestrated deterministic build (recommended for prompts): Use `chat` with `--verbose` to see tool calls. The orchestrator enforces complete requirement objects, then runs `verify_playlist` (structure only) 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