diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 71ab6d77..cdc7bf24 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -15,7 +15,7 @@ None - Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) - [x] **Phase 1: Provider Infrastructure** - API key storage and provider settings UI ✓ -- [ ] **Phase 2: Model Discovery** - Dynamic model fetching from Replicate/fal.ai APIs +- [x] **Phase 2: Model Discovery** - Dynamic model fetching from Replicate/fal.ai APIs ✓ - [ ] **Phase 3: Generate Node Refactor** - Rename NanoBanana to generic Generate with multi-model support - [ ] **Phase 4: Model Search Dialog** - Floating action bar icons and searchable model browser - [ ] **Phase 5: Image URL Server** - Local endpoint serving images as URLs for providers @@ -43,7 +43,7 @@ Plans: Plans: - [x] 02-01: Replicate model fetching API route - [x] 02-02: fal.ai model fetching API route -- [ ] 02-03: Model caching and unified model interface +- [x] 02-03: Model caching and unified model interface ### Phase 3: Generate Node Refactor **Goal**: NanoBanana node becomes generic Generate node supporting any provider's model @@ -96,7 +96,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| | 1. Provider Infrastructure | 2/2 | Complete | 2026-01-09 | -| 2. Model Discovery | 2/3 | In progress | - | +| 2. Model Discovery | 3/3 | Complete | 2026-01-09 | | 3. Generate Node Refactor | 0/3 | Not started | - | | 4. Model Search Dialog | 0/2 | Not started | - | | 5. Image URL Server | 0/2 | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 03e320bd..6d8051ae 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,34 +5,34 @@ See: .planning/PROJECT.md (updated 2026-01-09) **Core value:** Provider infrastructure that dynamically discovers models from external APIs, enabling users to access hundreds of image/video generation models without hardcoding schemas. -**Current focus:** Phase 2 - Model Discovery +**Current focus:** Phase 3 - Generate Node Refactor ## Current Position -Phase: 2 of 6 (Model Discovery) -Plan: 2 of 3 in current phase -Status: In progress -Last activity: 2026-01-09 - Completed 02-02-PLAN.md (fal.ai provider) +Phase: 3 of 6 (Generate Node Refactor) +Plan: 0 of 3 in current phase +Status: Ready to start Phase 3 +Last activity: 2026-01-09 - Completed 02-03-PLAN.md (Model caching) -Progress: [==========================] 27% (4/15 plans) +Progress: [=================================] 33% (5/15 plans) ## Performance Metrics **Velocity:** -- Total plans completed: 4 +- Total plans completed: 5 - Average duration: 6 min -- Total execution time: 0.4 hours +- Total execution time: 0.5 hours **By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| | 1. Provider Infrastructure | 2/2 | 14 min | 7 min | -| 2. Model Discovery | 2/3 | 9 min | 4.5 min | +| 2. Model Discovery | 3/3 | 14 min | 4.7 min | **Recent Trend:** -- Last 5 plans: 12 min, 2 min, 4 min, 5 min -- Trend: improving +- Last 5 plans: 2 min, 4 min, 5 min, 5 min +- Trend: stable ## Accumulated Context @@ -51,6 +51,8 @@ Recent decisions affecting current work: - fal.ai API key optional (works without but rate limited) - fal.ai auth header: "Key {apiKey}" format (not Bearer) - fal.ai category maps directly to ModelCapability (no inference) +- 10-minute cache TTL for model lists +- Unified API at /api/models with header-based auth ### Deferred Issues @@ -63,6 +65,6 @@ None. ## Session Continuity Last session: 2026-01-09 -Stopped at: Completed 02-02-PLAN.md +Stopped at: Completed Phase 2 (02-03-PLAN.md) Resume file: None -Next action: Execute 02-03-PLAN.md (Model caching) +Next action: Plan Phase 3 (03-01-PLAN.md - Rename NanoBanana to Generate) diff --git a/.planning/phases/02-model-discovery/02-03-SUMMARY.md b/.planning/phases/02-model-discovery/02-03-SUMMARY.md new file mode 100644 index 00000000..808cc99a --- /dev/null +++ b/.planning/phases/02-model-discovery/02-03-SUMMARY.md @@ -0,0 +1,141 @@ +--- +phase: 02-model-discovery +plan: 03 +subsystem: api +tags: [caching, unified-api, model-discovery, providers] + +# Dependency graph +requires: + - phase: 02-01 + provides: Replicate provider implementation + - phase: 02-02 + provides: fal.ai provider implementation +provides: + - In-memory model caching with TTL + - Unified /api/models endpoint for all providers + - Multi-provider helper functions (listAllModels, searchAllModels) + - Cache utilities (getCachedModels, setCachedModels, invalidateCache) +affects: [model-browser, generate-node, phase-3] + +# Tech tracking +tech-stack: + added: [] + patterns: [in-memory caching with TTL, unified API aggregation, partial failure handling] + +key-files: + created: + - src/lib/providers/cache.ts + - src/app/api/models/route.ts + modified: + - src/lib/providers/index.ts + +key-decisions: + - "10-minute default cache TTL (configurable per call)" + - "Cache key format: {provider}:models or {provider}:search:{query}" + - "Unified API uses header-based auth (X-Replicate-Key, X-Fal-Key)" + - "fal.ai always included in unified response (works without key)" + - "Partial failures return successful providers with errors array" + +patterns-established: + - "Cache utilities exported from @/lib/providers for reuse" + - "Unified API endpoint pattern at /api/models" + - "Multi-provider aggregation with Promise.allSettled" + +issues-created: [] + +# Metrics +duration: 5min +completed: 2026-01-09 +--- + +# Phase 02-03: Model Caching and Unified API Summary + +**In-memory caching layer and unified /api/models endpoint aggregating Replicate and fal.ai models** + +## Performance + +- **Duration:** 5 min +- **Started:** 2026-01-09 +- **Completed:** 2026-01-09 +- **Tasks:** 3 +- **Files created:** 2 +- **Files modified:** 1 + +## Accomplishments + +- Created in-memory cache utility with 10-minute TTL for model lists +- Built unified /api/models endpoint aggregating all configured providers +- Added cache utilities export from provider index +- Implemented listAllModels and searchAllModels helper functions +- Partial failure handling - returns models from successful providers with errors array + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create model caching utility** - `83ef0b4` (feat) +2. **Task 2: Create unified models API endpoint** - `421620c` (feat) +3. **Task 3: Add provider module exports** - `91a5449` (feat) + +## Files Created/Modified + +- `src/lib/providers/cache.ts` - In-memory cache with get/set/invalidate and TTL support +- `src/app/api/models/route.ts` - Unified API aggregating Replicate and fal.ai models +- `src/lib/providers/index.ts` - Added cache exports and multi-provider helper functions + +## API Reference + +### GET /api/models + +**Query Parameters:** +- `provider`: Optional, filter to "replicate" or "fal" +- `search`: Optional, search query +- `refresh`: Optional, set to "true" to bypass cache + +**Headers:** +- `X-Replicate-Key`: Replicate API key +- `X-Fal-Key`: fal.ai API key (optional) + +**Response:** +```json +{ + "success": true, + "models": [...], + "cached": false, + "providers": { + "replicate": { "success": true, "count": 50, "cached": false }, + "fal": { "success": true, "count": 100, "cached": true } + }, + "errors": [] +} +``` + +## Decisions Made + +- Cache uses simple in-memory Map (no LRU, no persistence) +- Default TTL is 10 minutes - balance between freshness and API quota +- Cache key includes search query for separate caching of search results +- fal.ai always included in unified results (works without API key) +- Unified API returns sorted models (by provider, then name) + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered + +None. + +## Phase 2 Complete + +This plan completes Phase 2: Model Discovery. All three plans are now done: + +1. **02-01**: Replicate provider with model fetching +2. **02-02**: fal.ai provider with model fetching +3. **02-03**: Model caching and unified API + +The model discovery infrastructure is ready for Phase 3: Generate Node Refactor. + +--- +*Phase: 02-model-discovery* +*Completed: 2026-01-09*