@iservu-inc/adf-cli 0.14.5 → 0.16.0

package/.project/docs/AI-MODEL-SOURCES.md

@@ -1,249 +1,217 @@
-# AI Model Documentation Sources
-
-This document tracks the official documentation URLs for AI model listings from each provider. These should be checked regularly to ensure adf-cli supports the latest models.
-
-**Last Updated:** 2025-10-04
-
----
-
-## Provider Model Documentation URLs
-
-### Anthropic Claude
-
-**Official Models Page:**
-- https://docs.anthropic.com/en/docs/about-claude/models
-
-**API Models List:**
-- ❌ No public API endpoint for listing models
-- Must use curated list from documentation
-
-**Current Models (as of 2025-10-04):**
-- `claude-sonnet-4-5-20250929`
-- `claude-3-5-sonnet-20241022`
-- `claude-3-opus-20240229`
-- `claude-3-sonnet-20240229`
-- `claude-3-haiku-20240307`
-
-**Update Strategy:** Manual curation from official docs
-
----
-
-### OpenAI
-
-**Official Models Page:**
-- https://platform.openai.com/docs/models
-
-**API Models List Endpoint:**
-- ✅ `GET https://api.openai.com/v1/models`
-- Requires API key in Authorization header
-
-**Current Model Families (as of 2025-10-04):**
-- GPT-4o series: `gpt-4o`, `gpt-4o-mini`
-- GPT-4 Turbo: `gpt-4-turbo`, `gpt-4-turbo-preview`
-- GPT-4: `gpt-4`
-- o1 series: `o1`, `o1-mini`, `o1-preview`
-- o3 series: `o3`, `o3-mini`, `o3-pro` (if available)
-- GPT-3.5: `gpt-3.5-turbo`
-
-**Update Strategy:** Dynamic fetching via API endpoint (DO NOT filter by model name prefix)
-
-**Important:**
-- OpenAI API returns ALL available models for your API key
-- Do NOT filter by prefix (e.g., `gpt-`) as this excludes o1, o3, and future model families
-- Filter only by owned_by or other metadata if needed
-
----
-
-### Google Gemini
-
-**Official Models Page:**
-- https://ai.google.dev/gemini-api/docs/models
-
-**API Models List:**
-- ⚠️ SDK has experimental listModels() but not stable
-- Must use curated list from documentation
-
-**Current Models (as of 2025-10-04):**
-
-**Gemini 2.5 Series (Latest - Stable):**
-- `gemini-2.5-pro`
-- `gemini-2.5-flash`
-- `gemini-2.5-flash-lite`
-- `gemini-2.5-flash-image`
-
-**Gemini 2.0 Series:**
-- `gemini-2.0-flash`
-- `gemini-2.0-flash-lite`
-
-**Gemini 1.5 Series (Legacy):**
-- `gemini-1.5-pro-latest`
-- `gemini-1.5-flash-latest`
-- `gemini-1.5-pro`
-- `gemini-1.5-flash`
-
-**Update Strategy:** Manual curation from official docs (SDK support pending)
-
----
-
-### OpenRouter
-
-**Official Models Page:**
-- https://openrouter.ai/models
-
-**API Models List Endpoint:**
-- ✅ `GET https://openrouter.ai/api/v1/models`
-- Returns JSON with all available models
-
-**Update Strategy:** Dynamic fetching via API endpoint
-
-**Current Implementation:** ✅ Working correctly - fetches all models dynamically
-
----
-
-## Update Process
-
-### Monthly Model Review Checklist
-
-Run this checklist at the start of each month to ensure latest models are available:
-
-1. **Anthropic Claude**
-   - [ ] Visit https://docs.anthropic.com/en/docs/about-claude/models
-   - [ ] Check for new model releases
-   - [ ] Update `AI_PROVIDERS.ANTHROPIC.defaultModels` in `lib/ai/ai-config.js`
-   - [ ] Test new models if added
-
-2. **OpenAI**
-   - [ ] Verify `fetchAvailableModels()` is NOT filtering by model prefix
-   - [ ] Test with real API key to ensure all models returned
-   - [ ] Check https://platform.openai.com/docs/models for new model families
-   - [ ] Update fallback list if API changes
-
-3. **Google Gemini**
-   - [ ] Visit https://ai.google.dev/gemini-api/docs/models
-   - [ ] Check for new Gemini versions (2.6, 3.0, etc.)
-   - [ ] Update `AI_PROVIDERS.GOOGLE.defaultModels` in `lib/ai/ai-config.js`
-   - [ ] Test new models if added
-
-4. **OpenRouter**
-   - [ ] API fetching is dynamic - no action needed
-   - [ ] Verify API endpoint still works
-   - [ ] Check for API changes at https://openrouter.ai/docs
-
-### Testing After Updates
-
-```bash
-# Test each provider's model fetching
-cd adf-cli
-npm test
-
-# Manual test with real API keys
-adf init
-# Select each provider and verify model list
-```
-
----
-
-## Known Issues
-
-### OpenAI Model Filtering Bug (CRITICAL - Fixed in v0.4.29)
-
-**Problem:**
-```javascript
-.filter(m => m.id.startsWith('gpt-'))  // ❌ TOO RESTRICTIVE
-```
-
-This filter excludes:
-- o1, o1-mini, o1-preview
-- o3, o3-pro, o3-mini
-- Any future non-GPT model families
-
-**Solution:**
-```javascript
-// Fetch ALL models without prefix filtering
-const models = response.data
-  .map(m => m.id)
-  .sort();
-```
-
-**Status:** Fixed in v0.4.29
-
----
-
-## API Response Examples
-
-### OpenAI `/v1/models` Response
-
-```json
-{
-  "object": "list",
-  "data": [
-    {
-      "id": "gpt-4o",
-      "object": "model",
-      "created": 1234567890,
-      "owned_by": "openai"
-    },
-    {
-      "id": "o1-preview",
-      "object": "model",
-      "created": 1234567890,
-      "owned_by": "openai"
-    }
-  ]
-}
-```
-
-### OpenRouter `/api/v1/models` Response
-
-```json
-{
-  "data": [
-    {
-      "id": "anthropic/claude-sonnet-4-5",
-      "name": "Claude Sonnet 4.5",
-      "pricing": { ... }
-    }
-  ]
-}
-```
-
----
-
-## Maintenance Notes
-
-- **DO NOT** hardcode model lists unless provider has no API
-- **DO NOT** filter by model name prefix unless absolutely necessary
-- **ALWAYS** fetch dynamically when API is available
-- **TEST** with real API keys before publishing updates
-- **DOCUMENT** any assumptions or limitations in this file
-
----
-
-## Future Improvements
-
-1. **Add model metadata caching**
-   - Cache API responses for 24 hours
-   - Reduce API calls during testing
-
-2. **Add model capability detection**
-   - Vision support
-   - Function calling
-   - Context window size
-   - Pricing information
-
-3. **Add model recommendation system**
-   - Suggest best model for use case
-   - Warn about deprecated models
-   - Show model capabilities in selection
-
-4. **Automated model list updates**
-   - GitHub Actions workflow
-   - Monthly PR with updated model lists
-   - Automated testing against provider APIs
-
----
-
-## Version History
-
-- **2025-10-04:** Initial documentation
-- **2025-10-04:** Identified OpenAI filtering bug (v0.4.29)
+# AI Model Documentation Sources
+
+This document tracks the official documentation URLs for AI model listings from each provider. These should be checked regularly to ensure adf-cli supports the latest models.
+
+**Last Updated:** 2026-01-12
+
+---
+
+## Provider Model Documentation URLs
+
+### Anthropic Claude
+
+**Official Models Page:**
+- https://docs.anthropic.com/en/docs/about-claude/models
+
+**API Models List:**
+- ✅ Supported via `GET /v1/models`
+- Node.js SDK: `client.models.list()`
+
+**Current Models (as of 2026-01-12):**
+- `claude-3-5-sonnet-20241022`
+- `claude-3-5-haiku-20241022`
+- `claude-3-opus-20240229`
+
+**Update Strategy:** Dynamic discovery via API
+
+---
+
+### OpenAI
+
+**Official Models Page:**
+- https://platform.openai.com/docs/models
+
+**API Models List Endpoint:**
+- ✅ `GET https://api.openai.com/v1/models`
+- Requires API key in Authorization header
+
+**Current Model Families (as of 2026-01-12):**
+- GPT-4o series: `gpt-4o`, `gpt-4o-mini`
+- o1 series: `o1`, `o1-mini`
+- o3 series: `o3`, `o3-mini`
+- GPT-5 series (if available)
+
+**Update Strategy:** Dynamic fetching via API endpoint (DO NOT filter by model name prefix)
+
+**Important:**
+- OpenAI API returns ALL available models for your API key
+- Do NOT filter by prefix (e.g., `gpt-`) as this excludes o1, o3, and future model families
+- Filter only by owned_by or other metadata if needed
+
+---
+
+### Google Gemini
+
+**Official Models Page:**
+- https://ai.google.dev/gemini-api/docs/models
+
+**API Models List:**
+- ✅ Supported via `v1beta/models` endpoint
+- Node.js SDK: `@google/genai` (Unified SDK)
+
+**Current Models (as of 2026-01-12):**
+
+**Gemini 3.0 Series (Latest - Frontier):**
+- `gemini-3.0-pro`
+- `gemini-3.0-flash`
+- `gemini-3.0-deep-think`
+
+**Gemini 2.5 Series (Stable):**
+- `gemini-2.5-pro`
+- `gemini-2.5-flash`
+- `gemini-2.5-flash-lite`
+
+**Gemini 2.0 Series (Legacy):**
+- `gemini-2.0-flash`
+- `gemini-2.0-pro`
+
+**Update Strategy:** Dynamic discovery via API
+
+---
+
+### OpenRouter
+
+**Official Models Page:**
+- https://openrouter.ai/models
+
+**API Models List Endpoint:**
+- ✅ `GET https://openrouter.ai/api/v1/models`
+- Returns JSON with all available models
+
+**Update Strategy:** Dynamic fetching via API endpoint
+
+**Current Implementation:** ✅ Working correctly - fetches all models dynamically
+
+---
+
+## Update Process
+
+### Monthly Model Review Checklist
+
+Run this checklist at the start of each month to ensure latest models are available:
+
+1. **Anthropic Claude**
+   - [ ] Visit https://docs.anthropic.com/en/docs/about-claude/models
+   - [ ] Check for new model releases
+   - [ ] Verify `fetchAvailableModels()` is getting all models via pagination
+
+2. **OpenAI**
+   - [ ] Verify `fetchAvailableModels()` is NOT filtering by model prefix
+   - [ ] Test with real API key to ensure all models returned
+   - [ ] Check https://platform.openai.com/docs/models for new model families
+
+3. **Google Gemini**
+   - [ ] Visit https://ai.google.dev/gemini-api/docs/models
+   - [ ] Check for new Gemini versions (3.1, 4.0, etc.)
+   - [ ] Verify dynamic discovery works via `v1beta/models`
+
+4. **OpenRouter**
+   - [ ] API fetching is dynamic - no action needed
+   - [ ] Verify API endpoint still works
+   - [ ] Check for API changes at https://openrouter.ai/docs
+
+### Testing After Updates
+
+```bash
+# Test each provider's model fetching
+cd adf-cli
+npm test
+
+# Manual test with real API keys
+node bin/adf.js config
+# Select each provider and verify model list
+```
+
+---
+
+## Known Issues
+
+### OpenAI Model Filtering Bug (CRITICAL - Fixed in v0.4.29)
+
+**Problem:**
+```javascript
+.filter(m => m.id.startsWith('gpt-'))  // ❌ TOO RESTRICTIVE
+```
+
+This filter excludes:
+- o1, o1-mini, o1-preview
+- o3, o3-pro, o3-mini
+- Any future non-GPT model families
+
+**Solution:**
+```javascript
+// Fetch ALL models without prefix filtering
+const models = response.data
+  .map(m => m.id)
+  .sort();
+```
+
+**Status:** Fixed in v0.4.29
+
+---
+
+## API Response Examples
+
+### OpenAI `/v1/models` Response
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "gpt-4o",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "openai"
+    },
+    {
+      "id": "o1-mini",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "openai"
+    }
+  ]
+}
+```
+
+### OpenRouter `/api/v1/models` Response
+
+```json
+{
+  "data": [
+    {
+      "id": "anthropic/claude-3-5-sonnet",
+      "name": "Claude 3.5 Sonnet",
+      "pricing": { ... }
+    }
+  ]
+}
+```
+
+---
+
+## Maintenance Notes
+
+- **DO NOT** hardcode model lists unless provider has no API
+- **DO NOT** filter by model name prefix unless absolutely necessary
+- **ALWAYS** fetch dynamically when API is available
+- **TEST** with real API keys before publishing updates
+- **DOCUMENT** any assumptions or limitations in this file
+
+---
+
+## Version History
+
+- **2026-01-12:** Updated to remove deprecated models (Gemini 1.5, GPT-3.5) and enable dynamic discovery across all providers.
+- **2025-10-04:** Initial documentation
+- **2025-10-04:** Identified OpenAI filtering bug (v0.4.29)

package/.project/docs/AI-PROVIDER-INTEGRATION.md

@@ -15,7 +15,7 @@ The adf-cli interview system now supports **4 AI providers**, giving users flexi
 | Provider | Models | API Key Format | Website |
 |----------|--------|----------------|---------|
 | **Anthropic Claude** | Sonnet 4.5, Claude 3.5, Opus | `sk-ant-*` | https://console.anthropic.com/ |
-| **OpenAI GPT** | GPT-4-turbo, GPT-4o, GPT-4, GPT-3.5-turbo | `sk-*` | https://platform.openai.com/ |
+| **OpenAI GPT** | GPT-4o, GPT-4o-mini, o1, o3 | `sk-*` | https://platform.openai.com/ |
 | **Google Gemini** | 2.0-flash-exp, 1.5-pro, 1.5-flash | (varies) | https://ai.google.dev/ |
 | **OpenRouter** | Multi-model access | `sk-or-*` | https://openrouter.ai/ |
 

package/.project/docs/PHASE-6-ADVANCED-LEARNING.md

@@ -0,0 +1,46 @@
+# Phase 6: Advanced Learning & Analytics
+
+## Overview
+Phase 6 enhances the ADF CLI Learning System with transparency, intelligence, and adaptability. It introduces a comprehensive analytics dashboard, an automated pattern decay algorithm, and multi-format data export capabilities.
+
+## Key Features
+
+### 1. Learning Analytics Dashboard
+Accessible via `adf config` → **Learning System** → **📊 Analytics Dashboard**, this interactive UI provides visibility into the learning engine's behavior.
+
+- **Skip Trends**: A 12-week visualization of manual vs. filtered skips.
+- **Category Preferences**: Heatmap of skip rates and answer quality by category (e.g., Deployment, Security).
+- **Pattern Confidence**: Distribution of learned patterns by confidence level (High, Medium, Low).
+- **Effectiveness Metrics**: Automated calculation of total development time saved (in minutes/hours).
+- **Question Statistics**: Deep dive into most-answered and most-skipped questions.
+
+### 2. Pattern Decay Algorithm
+To ensure learning data remains relevant as user habits evolve, Phase 6 implements a time-based decay system.
+
+- **Exponential Decay**: Pattern confidence reduces over time if not reconfirmed.
+- **Confidence-Based Rates**:
+  - High Confidence (≥90): 7.5% decay per month.
+  - Medium Confidence (75-89): 15% decay per month.
+  - Low Confidence (<75): 22.5% decay per month.
+- **Automatic Cleanup**: Patterns are removed if confidence falls below 40% or if inactive for 6+ months.
+- **Renewal Mechanism**: Reconfirming a pattern (skipping a question manually) provides a +10 confidence boost.
+
+### 3. Data Export
+Export learning analytics for team reporting or personal review.
+- **Formats**: JSON (single file) and CSV (5-file suite including trends, categories, and impactful patterns).
+- **Location**: Exports are saved to the user's current project directory.
+
+## Architecture
+
+- `lib/learning/analytics.js`: Calculation engine for 10+ metrics.
+- `lib/learning/decay-manager.js`: Orchestrates decay application and cleanup.
+- `lib/learning/analytics-view.js`: Handles ASCII chart generation and menu navigation.
+- `lib/learning/analytics-exporter.js`: Manages CSV/JSON serialization logic.
+
+## Technical Improvements
+- **Performance**: Optimized for 100+ sessions (<2s load time).
+- **Testing**: Added 50+ new tests covering decay logic and metric accuracy.
+- **UI**: Improved navigation with "Back" functionality and real-time refresh.
+
+---
+*Status: COMPLETE (v0.15.0)*