@whykusanagi/corrupted-theme 0.1.2 → 0.1.3

package/docs/ROADMAP.md

@@ -0,0 +1,266 @@
+# CelesteCLI Roadmap
+
+This document tracks planned features, enhancements, and potential migrations for CelesteCLI.
+
+## Current Status (December 2025)
+
+### ✅ Completed
+- Enterprise-grade RPG menu system with contextual help
+- 18 AI-powered skills via function calling
+- Multi-provider support (OpenAI, Grok, Venice, Anthropic, OpenRouter, DigitalOcean)
+- Vertex AI support via OpenAI-compatible endpoint
+- Session persistence and auto-save
+- NSFW mode with Venice.ai image generation
+- Context-aware /safe command
+- Tool result filtering (hide raw JSON from UI)
+
+---
+
+## Short-Term (Q1 2025)
+
+### High Priority
+
+#### 1. Vertex AI (Google Cloud) Setup Guide
+- **Status**: Requires complex Google Cloud configuration
+- **Goal**: Document complete Vertex AI setup for enterprise users
+- **Provider Clarification**:
+  - **Gemini AI (AI Studio)**: Simple API keys ✅ READY
+  - **Vertex AI (Google Cloud)**: OAuth2 tokens, requires setup ⚠️ ENTERPRISE ONLY
+
+**Vertex AI Requirements:**
+1. **Google Cloud Project**: Active GCP project with billing enabled
+2. **Vertex AI API**: Enable Vertex AI API in GCP console
+3. **Service Account**: Create service account with `Vertex AI User` role
+4. **Authentication**: Use OAuth2 tokens (NOT simple API keys)
+5. **Token Management**: Tokens expire after 1 hour, need refresh mechanism
+
+**Endpoint URL Format:**
+```
+https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/endpoints/openapi
+```
+
+**Configuration Example:**
+```json
+{
+  "api_key": "ya29.c.c0ASRK0Ga...",  // OAuth2 access token
+  "base_url": "https://aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/endpoints/openapi",
+  "model": "gemini-2.0-flash",
+  "timeout": 60
+}
+```
+
+**Token Generation (Go example):**
+```go
+import "golang.org/x/oauth2/google"
+
+creds, _ := google.FindDefaultCredentials(ctx, "https://www.googleapis.com/auth/cloud-platform")
+token, _ := creds.TokenSource.Token()
+config.APIKey = token.AccessToken
+```
+
+**Why Most Users Should Use Gemini Instead:**
+- Gemini AI: Simple API key from https://aistudio.google.com/apikey
+- Vertex AI: Requires GCP project, billing, OAuth2 setup
+- Both use same Gemini models, same function calling capabilities
+- Vertex AI is for enterprise users with existing GCP infrastructure
+
+- **Decision**: Gemini AI is the recommended provider for most users
+
+#### 2. Improve Error Messaging
+- **Goal**: Better error messages for common issues
+- **Tasks**:
+  - [ ] API key validation on startup
+  - [ ] Clear messages for unsupported model features
+  - [ ] Network timeout handling with retry suggestions
+  - [ ] Configuration validation with fix suggestions
+
+#### 3. Performance Optimization
+- **Goal**: Reduce latency and improve responsiveness
+- **Tasks**:
+  - [ ] Stream parsing optimization
+  - [ ] Reduce re-renders in TUI
+  - [ ] Cache provider model lists
+  - [ ] Lazy-load skill definitions
+
+### Medium Priority
+
+#### 4. Enhanced Skill Management
+- **Goal**: Better skill discovery and usage
+- **Tasks**:
+  - [ ] /skills menu shows skill descriptions on hover/selection
+  - [ ] Skill usage examples in help text
+  - [ ] Skill execution history (recent skills used)
+  - [ ] Skill favorites/pinning
+
+#### 5. Configuration Management
+- **Goal**: Easier config switching and management
+- **Tasks**:
+  - [ ] /config list shows model details and capabilities
+  - [ ] /config test <profile> - test API connectivity
+  - [ ] Config templates for common providers
+  - [ ] Import/export config profiles
+
+---
+
+## Medium-Term (Q2-Q3 2025)
+
+### Research & Evaluation
+
+#### 6. Native Vertex AI SDK Migration (Option B)
+- **Status**: Documented as potential enhancement
+- **Trigger**: If Google deprecates OpenAI-compatible endpoint OR performance benefits are significant
+- **Complexity**: MEDIUM (8-12 hours estimated)
+- **Impact**: Better long-term stability, native Gemini features
+
+**Migration Plan**:
+
+##### Phase 1: Research & Prototyping (2-3 hours)
+- [ ] Set up native genai SDK in test branch
+- [ ] Prototype skill definition conversion (JSON → genai.FunctionDeclaration)
+- [ ] Test response parsing (functionCall vs tool_calls)
+- [ ] Benchmark performance vs OpenAI-compatible endpoint
+
+##### Phase 2: Abstraction Layer (3-4 hours)
+- [ ] Create provider abstraction interface
+- [ ] Implement OpenAI provider adapter
+- [ ] Implement native Gemini provider adapter
+- [ ] Unified response format converter
+
+##### Phase 3: Testing & Validation (2-3 hours)
+- [ ] Test all 18 skills with native SDK
+- [ ] Validate function calling accuracy
+- [ ] Test multi-turn conversations
+- [ ] Compare performance metrics
+
+##### Phase 4: Migration (1-2 hours)
+- [ ] Switch default Vertex AI provider to native SDK
+- [ ] Update documentation
+- [ ] Deprecation notice for OpenAI-compatible endpoint
+
+**Code Structure Example**:
+```go
+// Future architecture with provider abstraction
+
+type Provider interface {
+    SendMessage(ctx context.Context, messages []Message, tools []Tool) (*Response, error)
+    SupportsFunctionCalling() bool
+    ConvertSkillDefinition(skill SkillDefinition) interface{}
+}
+
+type OpenAIProvider struct {
+    client *openai.Client
+}
+
+type GeminiProvider struct {
+    client *genai.Client
+}
+
+// Skills remain unchanged - adapters handle conversion
+```
+
+**Decision Criteria**:
+- Google announces deprecation of OpenAI endpoint → Migrate immediately
+- Native SDK shows >20% performance improvement → Evaluate migration
+- Native SDK enables exclusive features → Evaluate value vs effort
+- Community reports OpenAI endpoint issues → Migrate proactively
+
+**Resources**:
+- [Google GenAI SDK Docs](https://pkg.go.dev/google.golang.org/genai)
+- [Function Calling Guide](https://ai.google.dev/gemini-api/docs/function-calling)
+- [Migration Guide](https://ai.google.dev/gemini-api/docs/migrate)
+
+---
+
+### Feature Enhancements
+
+#### 7. Advanced Skill Features
+- **Goal**: More powerful AI capabilities
+- **Tasks**:
+  - [ ] Parallel skill execution (when LLM calls multiple)
+  - [ ] Skill chaining (output of one feeds another)
+  - [ ] Custom user-defined skills (plugin system)
+  - [ ] Skill templates and generators
+
+#### 8. Conversation Management
+- **Goal**: Better session handling
+- **Tasks**:
+  - [ ] Named sessions (save/load by name)
+  - [ ] Session search (find past conversations)
+  - [ ] Session export (markdown, JSON)
+  - [ ] Session branching (fork conversation)
+
+#### 9. Multi-Modal Support
+- **Goal**: Beyond text interactions
+- **Tasks**:
+  - [ ] Image input support (upload images for analysis)
+  - [ ] File attachment support
+  - [ ] Voice input/output (ElevenLabs integration)
+  - [ ] PDF parsing and analysis
+
+---
+
+## Long-Term (Q4 2025+)
+
+### Major Features
+
+#### 10. Team/Collaboration Features
+- **Goal**: Multi-user support
+- **Tasks**:
+  - [ ] Shared sessions
+  - [ ] Team workspaces
+  - [ ] Permission management
+  - [ ] Audit logs
+
+#### 11. Cloud Sync
+- **Goal**: Cross-device session sync
+- **Tasks**:
+  - [ ] Optional cloud backup
+  - [ ] Encrypted session storage
+  - [ ] Device sync
+  - [ ] Web UI companion
+
+#### 12. Advanced Analytics
+- **Goal**: Usage insights
+- **Tasks**:
+  - [ ] Token usage tracking
+  - [ ] Cost estimation per provider
+  - [ ] Skill usage analytics
+  - [ ] Performance metrics dashboard
+
+---
+
+## Deprecated/Archived
+
+### Considered but Deferred
+- **Local LLM support**: Complexity vs benefit ratio too high for v1
+- **Browser extension**: Scope too large, focus on CLI first
+- **Mobile app**: Desktop/terminal focus more valuable
+
+---
+
+## Contributing to Roadmap
+
+This roadmap is living document. To propose additions:
+
+1. Check existing items to avoid duplicates
+2. Open GitHub issue with `[Roadmap]` prefix
+3. Describe:
+   - Use case and problem being solved
+   - Estimated complexity (LOW/MEDIUM/HIGH)
+   - Impact on existing features
+   - User benefit
+
+Priority is determined by:
+- User requests and feedback
+- Technical dependencies
+- Maintenance burden
+- Strategic value
+
+---
+
+## Version History
+
+- **v0.1** (Dec 2025): Initial roadmap creation
+  - Enterprise menu system complete
+  - Vertex AI OpenAI-compatible endpoint implemented
+  - Native SDK migration documented as Option B

package/docs/ROUTING.md

@@ -0,0 +1,324 @@
+# Celeste ↔ NIKKE Sub-Agent Routing Architecture
+
+## Overview
+
+Celeste uses intelligent intent detection to route queries:
+- **NIKKE queries** → NIKKE sub-agent (dedicated for game-specific data)
+- **General queries** → Main Celeste agent (personality + streaming + general chat)
+
+This separation reduces context window bloat and improves response accuracy for both contexts.
+
+---
+
+## How Routing Works
+
+```
+User Input
+    ↓
+[celeste-widget.js: Fetch routing rules]
+    ↓
+[Detect Intent: NIKKE keywords/patterns?]
+    ├─ YES (NIKKE detected)
+    │  └─ Route to NIKKE sub-agent
+    │     └─ Return formatted response
+    └─ NO (General query)
+       └─ Send to Main Celeste agent
+          └─ Celeste responds
+```
+
+---
+
+## Intent Detection
+
+### Keywords Trigger NIKKE Routing
+```
+"nikke", "union raid", "ur", "intercept",
+"character", "tier", "tier list", "meta", "best squad",
+"farm", "build", "equipment", "weapon",
+"chapter", "raid", "boss", "strategy", "guide"
+```
+
+### Pattern Matching
+```regex
+^(who|which).*(nikke|character).*(best|good|tier)
+^(how|tips).*(farm|clear|beat)
+^(what).*(meta|tier|build)
+^(nikke).*(tier|rank|list)
+union.*raid|ur.*guide|nikke.*build
+```
+
+### Examples
+
+**Triggers NIKKE Routing:**
+- "Who's the best NIKKE character?"
+- "How do I farm efficiently?"
+- "What's the current meta?"
+- "Union Raid tier list"
+- "Build guide for Rapture"
+- "Best squad for tower?"
+
+**Does NOT Trigger NIKKE Routing:**
+- "Hi Celeste, how are you?"
+- "Tell me about yourself"
+- "What's your favorite outfit?"
+- "Stream recommendations?"
+- "Tell me some lore"
+
+---
+
+## Configuration Files
+
+### `routing/routing_rules.json`
+**Contains:** Intent detection patterns, NIKKE keywords, fallback messages
+
+**Key Section:**
+```json
+{
+  "nikke_detection": {
+    "keywords": ["nikke", "union raid", ...],
+    "patterns": [
+      "^(who|which).*(nikke|character).*(best|good|tier)",
+      ...
+    ]
+  },
+  "routing_rules": [
+    {
+      "condition": "query_matches(nikke_detection)",
+      "action": "route_to_sub_agent",
+      "sub_agent": "nikke_agent",
+      "fallback_message": "The NIKKE archives are temporarily sealed..."
+    }
+  ]
+}
+```
+
+### `routing/nikke_agent_config.json`
+**Contains:** Sub-agent endpoint, auth, timeouts, OpenSearch indices
+
+**Key Section:**
+```json
+{
+  "nikke_agent": {
+    "endpoint": "${NIKKE_AGENT_ENDPOINT}",
+    "auth": {
+      "scheme": "bearer",
+      "key": "${NIKKE_AGENT_KEY}"
+    },
+    "timeouts": {
+      "connect_ms": 5000,
+      "read_ms": 10000,
+      "total_ms": 10000
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+Set these in your `.env` or deployment configuration:
+
+```bash
+# Main Celeste Agent (Digital Ocean)
+AGENT_ENDPOINT=https://svzuwvds2ipgf4ysetvzxvai.agents.do-ai.run
+AGENT_KEY=sk-xxxxx
+
+# NIKKE Sub-Agent
+NIKKE_AGENT_ENDPOINT=https://nikke-agent.whykusanagi.xyz/v1/nikke/query
+NIKKE_AGENT_KEY=sk-nikke-xxxxx
+```
+
+---
+
+## Web Widget Integration
+
+The `celeste-widget.js` loads routing rules from celesteCLI repo:
+
+```javascript
+const CELESTE_CONFIG = {
+  routingRulesUrl: 'https://raw.githubusercontent.com/whykusanagi/celesteCLI/main/routing/routing_rules.json'
+};
+
+async function sendToCeleste(message) {
+  // Fetch routing rules
+  const routingRules = await fetch(CELESTE_CONFIG.routingRulesUrl).then(r => r.json());
+
+  // Detect intent
+  const intent = detectIntent(message, routingRules);
+
+  // Route accordingly
+  if (intent === 'nikke') {
+    // Call NIKKE sub-agent
+  } else {
+    // Call main Celeste agent
+  }
+}
+```
+
+---
+
+## Fallback Behavior
+
+If the NIKKE sub-agent is unavailable:
+
+```
+User Query (NIKKE detected)
+    ↓
+[Attempt NIKKE sub-agent]
+    ├─ Timeout after 10 seconds
+    └─ Return fallback message:
+       "The NIKKE archives are temporarily sealed. Ask again in a moment, onii-chan."
+```
+
+The widget gracefully degrades instead of hanging or throwing an error.
+
+---
+
+## OpenSearch Integration
+
+### Celeste Indices
+- `celeste_capabilities` - What Celeste can do
+- `celeste_emotes` - Emote recommendations
+- `celeste_user_profiles` - User behavior data
+- `celeste_chat_logs` - Sample interactions
+
+### NIKKE Sub-Agent Indices
+- `nikke_characters` - Character database
+- `nikke_tiers` - Tier lists
+- `nikke_guides` - Build guides
+- `nikke_union_data` - Protected union data
+
+Each agent queries its own indices only. No cross-contamination.
+
+---
+
+## Response Handling
+
+### NIKKE Sub-Agent Response
+The sub-agent returns structured data:
+```json
+{
+  "characters": [...],
+  "tiers": [...],
+  "builds": [...],
+  "recommendations": [...],
+  "source_indices": [...]
+}
+```
+
+Main Celeste agent formats this with personality:
+```
+"Based on the archives, here's what I found:
+• Top DPS: Rapi, Viper, Privaty
+• Support Meta: Modernia, Ether, Helm
+
+Want me to explain any builds, onii-chan? 💜"
+```
+
+### Celeste Direct Response
+Main agent responds directly with personality:
+```
+"Hi there! I'm Celeste, your demon noble co-host.
+I can chat, moderate chat, play games... or tease you about your questionable taste. 😈
+What'll it be?"
+```
+
+---
+
+## Monitoring
+
+### Log Entry Example
+```
+[2025-11-21 14:32:10] User: "best nikke characters?"
+[2025-11-21 14:32:10] Intent Detection: MATCHED (keyword="nikke")
+[2025-11-21 14:32:10] Routing: NIKKE_AGENT
+[2025-11-21 14:32:10] Sub-agent latency: 342ms
+[2025-11-21 14:32:10] Response: [formatted with Celeste personality]
+```
+
+### Health Checks
+```bash
+# Check main Celeste agent
+curl ${AGENT_ENDPOINT}/health
+
+# Check NIKKE sub-agent
+curl ${NIKKE_AGENT_ENDPOINT}/v1/health
+```
+
+---
+
+## Troubleshooting
+
+### Symptom: NIKKE query routed to Celeste instead of sub-agent
+**Possible Causes:**
+- Routing rules not loaded correctly
+- Intent detection pattern doesn't match query
+- Widget JavaScript error
+
+**Fix:**
+1. Verify routing rules fetch succeeds
+2. Check browser console for JavaScript errors
+3. Manually test intent detection regex
+
+### Symptom: NIKKE queries timeout
+**Possible Causes:**
+- Sub-agent endpoint unreachable
+- Timeout too short (10s default)
+- OpenSearch query is slow
+
+**Fix:**
+1. Check `nikke_agent_config.json` endpoint
+2. Verify NIKKE_AGENT_ENDPOINT env var is set
+3. Test sub-agent health endpoint
+
+### Symptom: Fallback message appears frequently
+**Possible Causes:**
+- NIKKE sub-agent is down
+- Network connectivity issue
+- Timeout threshold too low
+
+**Fix:**
+1. Check NIKKE sub-agent deployment status
+2. Increase timeout in `nikke_agent_config.json` if needed
+3. Review error logs for specific failures
+
+---
+
+## Adding New Routing Rules
+
+To route a new query type (e.g., art questions to art agent):
+
+1. **Edit `routing/routing_rules.json`:**
+```json
+{
+  "condition": "query_intent == 'art'",
+  "action": "route_to_sub_agent",
+  "sub_agent": "art_agent",
+  "endpoint_env_var": "ART_AGENT_ENDPOINT"
+}
+```
+
+2. **Edit `routing/nikke_agent_config.json`** to add the new agent config
+
+3. **Update detection keywords/patterns** in `routing_rules.json`
+
+4. **Deploy** the updated files
+
+---
+
+## Performance Targets
+
+- **Intent detection:** <10ms
+- **NIKKE sub-agent call:** <10 seconds (timeout)
+- **Fallback response:** <100ms
+- **General Celeste response:** <5 seconds
+
+---
+
+## Related Documentation
+
+- `../celeste_essence.json` - System prompt with routing logic
+- `../Celeste_Capabilities.json` - What Celeste can do
+- `../opensearch/README.md` - Index management
+- `../../nikke-agent/docs/` - NIKKE sub-agent documentation