felo-ai 0.2.0

package/felo-search/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: felo-search
+description: "Felo AI real-time web search for questions requiring current/live information. Triggers on current events, news, trends, real-time data, information queries, location queries, how-to guides, shopping, or when Claude's knowledge may be outdated."
+---
+
+# Felo Search Skill
+
+## When to Use
+
+Trigger this skill for questions requiring current or real-time information:
+
+- **Current events & news:** Recent developments, trending topics, breaking news
+- **Real-time data:** Weather, stock prices, exchange rates, sports scores
+- **Information queries:** "What is...", "Tell me about...", product reviews, comparisons, recommendations
+- **Location-based:** Restaurants, travel destinations, local attractions, things to do
+- **How-to guides:** Tutorials, step-by-step instructions, best practices
+- **Shopping & prices:** Product prices, deals, "where to buy"
+- **Trends & statistics:** Market trends, rankings, data analysis
+- **Any question where Claude's knowledge may be outdated**
+
+**Trigger words:**
+- 简体中文: 最近、什么、哪里、怎么样、如何、查、搜、找、推荐、比较、新闻、天气
+- 繁體中文: 最近、什麼、哪裡、怎麼樣、如何、查、搜、找、推薦、比較、新聞、天氣
+- 日本語: 最近、何、どこ、どう、検索、探す、おすすめ、比較、ニュース、天気
+- English: latest, recent, what, where, how, best, search, find, compare, news, weather
+
+**Explicit commands:** `/felo-search`, "search with felo", "felo search"
+
+**Do NOT use for:**
+- Code questions about the user's codebase (unless asking about external libraries/docs)
+- Pure mathematical calculations or logical reasoning
+- Questions about files in the current project
+
+## Setup
+
+### 1. Get Your API Key
+
+1. Visit [felo.ai](https://felo.ai) and log in (or register)
+2. Click your avatar in the top right corner → Settings
+3. Navigate to the "API Keys" tab
+4. Click "Create New Key" to generate a new API Key
+5. Copy and save your API Key securely
+
+### 2. Configure API Key
+
+Set the `FELO_API_KEY` environment variable:
+
+**Linux/macOS:**
+```bash
+export FELO_API_KEY="your-api-key-here"
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+**Windows (CMD):**
+```cmd
+set FELO_API_KEY=your-api-key-here
+```
+
+For permanent configuration, add it to your shell profile (~/.bashrc, ~/.zshrc) or system environment variables.
+
+## How to Execute
+
+When this skill is triggered, execute the following steps using the Bash tool:
+
+### Step 1: Check API Key
+
+Use the Bash tool to verify the API key is set:
+
+```bash
+if [ -z "$FELO_API_KEY" ]; then
+  echo "ERROR: FELO_API_KEY not set"
+  exit 1
+fi
+echo "API key configured"
+```
+
+If the API key is not set, inform the user with setup instructions and STOP.
+
+### Step 2: Make API Request
+
+Extract the user's query and call the Felo API using a temporary JSON file to handle special characters:
+
+```bash
+# Create query JSON (replace USER_QUERY with actual query)
+cat > /tmp/felo_query.json << 'EOF'
+{"query": "USER_QUERY_HERE"}
+EOF
+
+# Call Felo API
+curl -s -X POST https://openapi.felo.ai/v2/chat \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/felo_query.json
+
+# Clean up
+rm -f /tmp/felo_query.json
+```
+
+**Notes:**
+- Replace `USER_QUERY_HERE` with the actual user query
+- Use heredoc (`cat > file << 'EOF'`) to properly handle Chinese, Japanese, and special characters
+- Use `-s` flag with curl for clean output
+
+### Step 3: Parse and Format Response
+
+The API returns JSON with this structure:
+```json
+{
+  "answer": "AI-generated answer text",
+  "query_analysis": ["optimized query 1", "optimized query 2"]
+}
+```
+
+Parse the JSON response and present it to the user in this format:
+
+```
+## 回答 / Answer
+[Display the answer field]
+
+## 搜索分析 / Query Analysis
+优化后的搜索词: [list query_analysis items]
+```
+
+## Complete Examples
+
+### Example 1: English Query
+
+**User asks:** "What's the weather in Tokyo today?"
+
+**Expected response format:**
+```
+## Answer
+Tokyo weather today: Sunny, 22°C (72°F). High of 25°C, low of 18°C.
+Light winds from the east at 10 km/h. UV index: 6 (high).
+Good day for outdoor activities!
+
+## Query Analysis
+Optimized search terms: Tokyo weather today, 東京 天気 今日
+```
+
+**Bash command:**
+```bash
+cat > /tmp/felo_query.json << 'EOF'
+{"query": "What's the weather in Tokyo today?"}
+EOF
+
+curl -s -X POST https://openapi.felo.ai/v2/chat \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/felo_query.json
+
+rm -f /tmp/felo_query.json
+```
+
+### Example 2: Simplified Chinese (简体中文)
+
+**User asks:** "杭州最近有什么新鲜事？"
+
+**Expected response format:**
+```
+## 回答
+杭州最近的新鲜事包括：亚运会场馆改造完成、西湖景区推出夜游项目、
+新的地铁线路开通等。详细信息...
+
+## 搜索分析
+优化后的搜索词: 杭州最近新闻, 杭州近期动态, Hangzhou recent news
+```
+
+**Bash command:**
+```bash
+cat > /tmp/felo_query.json << 'EOF'
+{"query": "杭州最近有什么新鲜事"}
+EOF
+
+curl -s -X POST https://openapi.felo.ai/v2/chat \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/felo_query.json
+
+rm -f /tmp/felo_query.json
+```
+
+### Example 3: Traditional Chinese - Taiwan (繁體中文-台灣)
+
+**User asks:** "台北最近有什麼好玩的地方？"
+
+**Bash command:**
+```bash
+cat > /tmp/felo_query.json << 'EOF'
+{"query": "台北最近有什麼好玩的地方"}
+EOF
+
+curl -s -X POST https://openapi.felo.ai/v2/chat \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/felo_query.json
+
+rm -f /tmp/felo_query.json
+```
+
+### Example 4: Japanese (日本語)
+
+**User asks:** "東京で今人気のレストランは？"
+
+**Bash command:**
+```bash
+cat > /tmp/felo_query.json << 'EOF'
+{"query": "東京で今人気のレストランは"}
+EOF
+
+curl -s -X POST https://openapi.felo.ai/v2/chat \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/felo_query.json
+
+rm -f /tmp/felo_query.json
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `INVALID_API_KEY` - API Key is invalid or revoked
+  - Solution: Check if your API key is correct and hasn't been revoked
+- `MISSING_PARAMETER` - Required parameter is missing
+  - Solution: Ensure the query parameter is provided
+- `INVALID_PARAMETER` - Parameter value is invalid
+  - Solution: Check the query format
+- `CHAT_FAILED` - Internal service error
+  - Solution: Retry the request or contact Felo support
+
+### Missing API Key
+
+If `FELO_API_KEY` is not set, display this message:
+
+```
+❌ Felo API Key not configured
+
+To use this skill, you need to set up your Felo API Key:
+
+1. Get your API key from https://felo.ai (Settings → API Keys)
+2. Set the environment variable:
+
+   Linux/macOS:
+   export FELO_API_KEY="your-api-key-here"
+
+   Windows (PowerShell):
+   $env:FELO_API_KEY="your-api-key-here"
+
+3. Restart Claude Code or reload the environment
+```
+
+## API Configuration
+
+**Endpoint:** `https://openapi.felo.ai/v2/chat`
+
+**Authentication:** Bearer token in Authorization header (from `FELO_API_KEY` environment variable)
+
+**Request format:**
+```json
+{
+  "query": "user's search query"
+}
+```
+
+**Response format:**
+```json
+{
+  "answer": "AI-generated comprehensive answer",
+  "query_analysis": ["optimized query 1", "optimized query 2"]
+}
+```
+
+## Important Notes
+
+- This skill should be used for any question requiring current information
+- Execute immediately using the Bash tool - don't just describe what you would do
+- Multi-language support: Fully supports Simplified Chinese, Traditional Chinese (Taiwan), Japanese, and English
+- Handle special characters properly: Use heredoc for JSON files to avoid encoding issues
+- Parse JSON response: Extract answer and query_analysis fields
+- Format nicely: Present results in a clean, readable format with proper markdown
+- The API returns results in the same language as the query when possible
+
+## Additional Resources
+
+- [Felo Open Platform Documentation](https://openapi.felo.ai)
+- [Get API Key](https://felo.ai) (Settings → API Keys)
+- [API Reference](https://openapi.felo.ai/docs)

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "felo-ai",
+  "version": "0.2.0",
+  "description": "Felo AI CLI - real-time search from the terminal",
+  "type": "module",
+  "main": "src/cli.js",
+  "bin": {
+    "felo": "src/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "felo",
+    "felo-ai",
+    "search",
+    "slides",
+    "cli",
+    "ai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Felo-Inc/felo-skills.git"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "felo-search": "^0.1.1"
+  },
+  "scripts": {
+    "test": "node --test tests/"
+  }
+}

package/src/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'module';
+import { Command } from 'commander';
+import { search } from './search.js';
+import { slides } from './slides.js';
+import * as config from './config.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('felo')
+  .description('Felo AI CLI - real-time search from the terminal')
+  .version(pkg.version);
+
+program
+  .command('search')
+  .description('Search for current information (weather, news, docs, etc.)')
+  .argument('<query>', 'search query')
+  .option('-j, --json', 'output raw JSON')
+  .option('-v, --verbose', 'show query analysis and sources')
+  .option('-t, --timeout <seconds>', 'request timeout in seconds', '60')
+  .action(async (query, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await search(query, {
+      json: opts.json,
+      verbose: opts.verbose,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exit(code);
+  });
+
+program
+  .command('slides')
+  .description('Generate PPT/slides from a prompt (async task, outputs live doc URL when done)')
+  .argument('<query>', 'PPT generation prompt (e.g. "Felo, 2 pages" or "Introduction to React")')
+  .option('-j, --json', 'output raw JSON with task_id and live_doc_url')
+  .option('-v, --verbose', 'show polling status')
+  .option('-t, --timeout <seconds>', 'request timeout in seconds for each API call', '60')
+  .option('--poll-timeout <seconds>', 'max seconds to wait for task completion', '600')
+  .action(async (query, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const pollTimeoutMs = parseInt(opts.pollTimeout, 10) * 1000 || 600000;
+    const code = await slides(query, {
+      json: opts.json,
+      verbose: opts.verbose,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+      pollTimeoutMs: Number.isNaN(pollTimeoutMs) ? 600000 : pollTimeoutMs,
+    });
+    process.exitCode = code;
+    // Defer exit so stderr can flush; reduces Node.js Windows assertion (UV_HANDLE_CLOSING)
+    setTimeout(() => process.exit(code), 0);
+  });
+
+const configCmd = program
+  .command('config')
+  .description('Manage persisted config (e.g. FELO_API_KEY). Stored in ~/.felo/config.json');
+
+configCmd
+  .command('set <key> <value>')
+  .description('Set a config value (e.g. felo config set FELO_API_KEY your-key)')
+  .action(async (key, value) => {
+    try {
+      await config.setConfig(key, value);
+      console.log(`Set ${key}`);
+    } catch (e) {
+      console.error('Error:', e.message);
+      process.exit(1);
+    }
+  });
+
+configCmd
+  .command('get <key>')
+  .description('Get a config value (sensitive keys are masked)')
+  .action(async (key) => {
+    try {
+      const value = await config.getConfigValue(key);
+      if (value === undefined || value === null) {
+        console.log('(not set)');
+      } else {
+        console.log(config.maskValueForDisplay(key, value));
+      }
+    } catch (e) {
+      console.error('Error:', e.message);
+      process.exit(1);
+    }
+  });
+
+configCmd
+  .command('list')
+  .description('List all config keys (values are hidden)')
+  .action(async () => {
+    try {
+      const c = await config.listConfig();
+      const keys = Object.keys(c);
+      if (keys.length === 0) {
+        console.log('No config set. Use: felo config set FELO_API_KEY <key>');
+        return;
+      }
+      keys.forEach((k) => console.log(k));
+    } catch (e) {
+      console.error('Error:', e.message);
+      process.exit(1);
+    }
+  });
+
+configCmd
+  .command('unset <key>')
+  .description('Remove a config value')
+  .action(async (key) => {
+    try {
+      await config.unsetConfig(key);
+      console.log(`Unset ${key}`);
+    } catch (e) {
+      console.error('Error:', e.message);
+      process.exit(1);
+    }
+  });
+
+configCmd
+  .command('path')
+  .description('Show config file path')
+  .action(() => {
+    console.log(config.getConfigPath());
+  });
+
+program
+  .command('summarize')
+  .description('Summarize text or URL (coming when API is available)')
+  .argument('[input]', 'text or URL to summarize')
+  .action(() => {
+    console.error('summarize: not yet implemented. Use felo search for now.');
+    process.exit(1);
+  });
+
+program
+  .command('translate')
+  .description('Translate text (coming when API is available)')
+  .argument('[text]', 'text to translate')
+  .action(() => {
+    console.error('translate: not yet implemented. Use felo search for now.');
+    process.exit(1);
+  });
+
+program.parse();

package/src/config.js

@@ -0,0 +1,66 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+function getConfigFilePath() {
+  return process.env.FELO_CONFIG_FILE || path.join(os.homedir(), '.felo', 'config.json');
+}
+
+const SENSITIVE_KEYS = ['FELO_API_KEY', 'API_KEY', 'SECRET', 'TOKEN', 'PASSWORD'];
+
+async function ensureConfigDir() {
+  await fs.mkdir(path.dirname(getConfigFilePath()), { recursive: true });
+}
+
+export async function getConfig() {
+  const configFile = getConfigFilePath();
+  try {
+    const raw = await fs.readFile(configFile, 'utf-8');
+    return JSON.parse(raw);
+  } catch (e) {
+    if (e.code === 'ENOENT') return {};
+    if (e instanceof SyntaxError) {
+      process.stderr.write('Warning: Invalid config file, using empty config.\n');
+      return {};
+    }
+    throw e;
+  }
+}
+
+export async function setConfig(key, value) {
+  await ensureConfigDir();
+  const config = await getConfig();
+  config[key] = value;
+  await fs.writeFile(getConfigFilePath(), JSON.stringify(config, null, 2), 'utf-8');
+}
+
+export async function getConfigValue(key) {
+  const config = await getConfig();
+  return config[key];
+}
+
+/** Returns value suitable for display; masks sensitive keys. */
+export function maskValueForDisplay(key, value) {
+  if (value === undefined || value === null) return value;
+  const s = String(value).trim();
+  if (!s) return s;
+  const upper = key.toUpperCase();
+  const isSensitive = SENSITIVE_KEYS.some((k) => upper === k || upper.endsWith('_' + k));
+  if (!isSensitive || s.length <= 8) return s;
+  return s.slice(0, 4) + '...' + s.slice(-4);
+}
+
+export async function unsetConfig(key) {
+  const config = await getConfig();
+  delete config[key];
+  await ensureConfigDir();
+  await fs.writeFile(getConfigFilePath(), JSON.stringify(config, null, 2), 'utf-8');
+}
+
+export async function listConfig() {
+  return getConfig();
+}
+
+export function getConfigPath() {
+  return getConfigFilePath();
+}

package/src/search.js

@@ -0,0 +1,142 @@
+const FELO_API = 'https://openapi.felo.ai/v2/chat';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 1000;
+
+const NO_KEY_MESSAGE = `
+❌ Felo API Key not configured
+
+To use Felo CLI, set the FELO_API_KEY environment variable or run:
+
+  felo config set FELO_API_KEY <your-api-key>
+
+Get your API key from https://felo.ai (Settings → API Keys).
+`;
+
+async function getApiKey() {
+  if (process.env.FELO_API_KEY?.trim()) {
+    return process.env.FELO_API_KEY.trim();
+  }
+  const { getConfigValue } = await import('./config.js');
+  const fromConfig = await getConfigValue('FELO_API_KEY');
+  return typeof fromConfig === 'string' ? fromConfig.trim() : '';
+}
+
+export { getApiKey, fetchWithTimeoutAndRetry, NO_KEY_MESSAGE };
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function fetchWithTimeoutAndRetry(url, options, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  let lastError;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      // Retry on 5xx (server errors)
+      if (res.status >= 500 && attempt < MAX_RETRIES) {
+        const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+        await sleep(delay);
+        continue;
+      }
+      return res;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      lastError = err;
+      if (err.name === 'AbortError') {
+        throw new Error(`Request timed out after ${timeoutMs / 1000}s`);
+      }
+      if (attempt < MAX_RETRIES) {
+        const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+        await sleep(delay);
+        continue;
+      }
+      throw lastError;
+    }
+  }
+  throw lastError;
+}
+
+export async function search(query, options = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    console.error(NO_KEY_MESSAGE.trim());
+    return 1;
+  }
+
+  try {
+    process.stderr.write('Searching...\n');
+
+    const res = await fetchWithTimeoutAndRetry(
+      FELO_API,
+      {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ query: query.trim() }),
+      },
+      options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    );
+
+    const data = await res.json().catch(() => ({}));
+
+    // API error response: { status: "error", code, message } (per doc)
+    if (data.status === 'error') {
+      const msg = data.message || data.code || 'Unknown error';
+      console.error(`Error: ${msg}`);
+      return 1;
+    }
+
+    if (!res.ok) {
+      const msg = data.message || data.error || res.statusText || `HTTP ${res.status}`;
+      console.error(`Error: ${msg}`);
+      return 1;
+    }
+
+    // Success: { status: "ok", data: { answer, query_analysis: { queries }, resources } }
+    const payload = data.data;
+    if (!payload) {
+      console.error('Error: Unexpected response format');
+      return 1;
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(data, null, 2));
+      return 0;
+    }
+
+    // Default: only the answer (stdout, pipe-friendly)
+    if (payload.answer) {
+      console.log(payload.answer);
+    }
+
+    // Verbose: add query analysis and sources (per API doc)
+    if (options.verbose) {
+      const queries = payload.query_analysis?.queries;
+      if (Array.isArray(queries) && queries.length) {
+        process.stderr.write('\n## Query Analysis\n');
+        process.stderr.write(`Optimized search terms: ${queries.join(', ')}\n`);
+      }
+      const resources = payload.resources;
+      if (Array.isArray(resources) && resources.length) {
+        process.stderr.write('\n## Sources\n');
+        resources.forEach((r) => {
+          process.stderr.write(`- ${r.title}: ${r.link}\n`);
+        });
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    console.error('Error:', err.message || err);
+    return 1;
+  }
+}