kiku-agent 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# 🌸 Ju Jingyi (鞠婧祎) Portal & Kiku AI Agent
+
+> Full-stack fan archive, REST API Suite v1.0, and Autonomous AI Agent CLI powered by **LM Studio** (`gemma-4-e4b` / Gemma models).
+
+---
+
+## 🚀 Kiku AI Agent CLI
+
+The **Kiku AI Agent** is an autonomous ReAct agent and specialized encyclopedia for Ju Jingyi. It connects to your local **LM Studio** instance and has access to catalog, web, media, filesystem, and music tools.
+
+### Global installation
+
+```bash
+npm install -g kiku-agent
+kiku-agent
+```
+
+The same package also installs the stdio MCP server command:
+
+```bash
+kiku-mcp
+```
+
+For a local checkout before the package is published, use `npm pack` followed by `npm install -g ./kiku-agent-1.0.0.tgz`.
+
+### ✨ Features
+- **LM Studio Integration**: Connects seamlessly to LM Studio's OpenAI-compatible server at `http://127.0.0.1:1234/v1` (with support for `gemma-4-e4b`, `gemma-3-4b`, and auto-detection of loaded models).
+- **Validated Tool Calling**: Schema validation, argument coercion, timeouts, duplicate-call caching, normalized results, and complete catalog/media integrations.
+- **Multilingual Support**: Automatically detects and responds in Thai, Chinese, or English based on user input language.
+- **Multi-turn Memory**: Retains conversation context with clear memory controls (`/clear`).
+- **Resilient ReAct Loop**: Supports OpenAI function calling as well as structured JSON tool parsing optimized for Gemma models.
+- **Graceful Diagnostics**: Displays real-time connection status, loaded model names, and fallback search modes if LM Studio is offline.
+- **Clean Thinking Display**: Shows reasoning process without markdown artifacts for better readability.
+
+---
+
+## 🛠️ LM Studio Quick Setup
+
+1. Open **LM Studio** on your computer.
+2. In the Search tab, download or load **Gemma** (e.g. `gemma-4-e4b`, `gemma-3-4b-it`, `gemma-2-9b-it`).
+3. Click the **Developer / Local Server** tab (icon with `<->`) on the left bar.
+4. Select your loaded Gemma model and click **Start Server** on port `1234` (`http://localhost:1234`).
+5. In this terminal, run:
+   ```bash
+   npm run kiku-agent
+   ```
+
+---
+
+## 💻 CLI Usage & Commands
+
+### Interactive Chat Mode
+```bash
+npm run kiku-agent
+```
+
+### One-shot Question Query
+```bash
+npm run kiku-agent -- --query "ผลงานซีรีส์ปี 2026 มีเรื่องอะไรบ้างและรับบทเป็นใคร"
+```
+
+### Specify Custom Model or LM Studio URL
+```bash
+npm run kiku-agent -- --model gemma-4-e4b --url http://127.0.0.1:1234/v1
+```
+
+### View Catalog Overview Statistics
+```bash
+npm run kiku-agent -- --stats
+```
+
+### View All Registered Tools
+```bash
+npm run kiku-agent -- --tools
+```
+
+### Interactive Chat Slash Commands
+- `/help` — Display list of commands
+- `/tools` — View all tool names and parameter descriptions
+- `/details [Qn]` — Expand the recorded thinking and tool results for a question (`F2` opens the latest)
+- `/stats` — Print summary counts of dramas, songs, brands, and awards
+- `/model` — Inspect active models currently loaded in LM Studio
+- `/thinking [show|hide]` — Toggle reasoning process visibility
+- `/save` — Export session transcript to Markdown file
+- `/clear` — Reset conversation history
+- `/exit` — Exit the agent
+
+---
+
+## 📚 Available API Tools in Kiku Agent
+
+| # | Tool Name | Description |
+|---|---|---|
+| 1 | `get_profile_and_fandom` | Bio, Thai/Chinese/Pinyin names, Miju (蜜橘) fan community, slogans, socials |
+| 2 | `get_quotes` | Inspiring quotes with Thai translation and original Chinese text |
+| 3 | `search_works` | Filter filmography by year (2013-2026), category, keywords |
+| 4 | `get_work_detail` | Detailed synopsis, roles, ratings, streaming platform, and OST |
+| 5 | `get_character_roles` | Portrayed roles (Yang Caiwei, Lu Wuyi, Bai Suzhen, Han Yunxi, etc.) |
+| 6 | `search_discography` | Deduplicated music catalog, singles, OSTs, and albums |
+| 7 | `get_music_videos` | MVs, stage performances, dance practices, and special stages |
+| 8 | `get_brand_endorsements`| Commercial endorsements, luxury brands (PRSR, FRED), Milan fashion week |
+| 9 | `get_career_timeline` | Milestone eras from SNH48 debut (2013) to solo studio to present |
+| 10 | `get_awards` | Honors in music, television acting, and fashion influence |
+| 11 | `get_social_feed` | Recent Weibo & Douyin social media updates and metrics |
+| 12 | `get_gallery_photos` | High-res fashion sets, red carpet, photoshoot, and drama stills |
+| 13 | `global_search` | Universal fuzzy search across all entities in the database |
+| 14 | `web_search` | Live internet search for up-to-date news and info |
+| 15 | `fetch_webpage` | Extract and read content from live URLs |
+| 16 | `fetch_api` | Query the official Ju Jingyi REST API for structured JSON data |
+| 17 | `get_system_stats` | High-level summary metrics of the entire Ju Jingyi archive |
+
+---
+
+## 🌐 Web App & API Development
+
+```bash
+# Start frontend dev server
+npm run dev
+
+# Run API verification tests
+powershell -ExecutionPolicy Bypass -File test_api.ps1
+```

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "kiku-agent",
+  "version": "1.0.0",
+  "description": "Kiku AI terminal agent and MCP server for Ju Jingyi knowledge, media, and career data.",
+  "type": "module",
+  "bin": {
+    "kiku-agent": "server/agent/cli.js",
+    "kiku-mcp": "server/mcp/stdio.js"
+  },
+  "exports": {
+    ".": "./server/agent/agentCore.js",
+    "./mcp": "./server/mcp/server.js",
+    "./tools": "./server/agent/tools.js"
+  },
+  "files": [
+    "server/agent/*.js",
+    "server/mcp/*.js",
+    "server/mcp/data/*.js",
+    "server/mcp/**/*.json",
+    "src/data/**/*.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "kiku",
+    "ju-jingyi",
+    "cli",
+    "ai-agent",
+    "mcp",
+    "model-context-protocol",
+    "lm-studio"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThemeHackers/jujingyi_kikuuu.git"
+  },
+  "homepage": "https://jujingyi-kikuuu.vercel.app/",
+  "bugs": {
+    "url": "https://github.com/ThemeHackers/jujingyi_kikuuu/issues"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "kiku-agent": "node server/agent/cli.js",
+    "kiku-mcp": "node server/mcp/stdio.js",
+    "kiku-ink": "npx tsx server/agent/ink/main.jsx",
+    "test": "node --test server/agent/tests/*.test.js server/mcp/tests/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@distube/ytdl-core": "^4.16.12",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "clsx": "^2.1.1",
+    "ffmpeg-static": "^5.3.0",
+    "fluent-ffmpeg": "^2.1.3",
+    "framer-motion": "^12.4.7",
+    "ink": "^7.1.1",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "lucide-react": "^1.16.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "speaker": "^0.5.5",
+    "tailwind-merge": "^3.0.2",
+    "yt-search": "^2.13.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.9",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "@vitejs/plugin-react": "^4.3.4",
+    "tailwindcss": "^4.0.9",
+    "tsx": "^4.23.12",
+    "vite": "^6.2.0"
+  }
+}