seekdb-agent-skills 0.0.2__tar.gz

seekdb_agent_skills-0.0.2/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include skills **/*
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .git*
+recursive-exclude * *.db
+recursive-exclude * *.log

seekdb_agent_skills-0.0.2/PKG-INFO

@@ -0,0 +1,579 @@
+Metadata-Version: 2.4
+Name: seekdb-agent-skills
+Version: 0.0.2
+Summary: Install seekdb Agent Skills to various AI coding tools (Claude Code, GitHub Copilot, Codex, Cursor, etc.)
+Author: David Zhang
+License: MIT
+Project-URL: Homepage, https://github.com/oceanbase/seekdb-ecology-plugins
+Project-URL: Documentation, https://github.com/oceanbase/seekdb-ecology-plugins/tree/main/claudecode-plugin
+Project-URL: Repository, https://github.com/oceanbase/seekdb-ecology-plugins
+Project-URL: Issues, https://github.com/oceanbase/seekdb-ecology-plugins/issues
+Keywords: seekdb,vector-database,ai,agent-skills,claude-code,copilot,codex,cursor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: questionary>=1.10.0
+
+# seekdb Plugin for Claude Code
+
+> This plugin contains seekdb skill for Claude Code that provides seekdb database-related documents.
+
+## 📖 Project Overview
+
+seekdb skill is designed specifically for Claude Code, aimed at enhancing Claude's capabilities in seekdb database scenarios. Through these Skills, Claude Code can query the complete seekdb official documentation and obtain technical guidance and best practices.
+
+## ✨ Key Features
+
+- **Complete Documentation Support**: Built-in seekdb official documentation knowledge base covering comprehensive technical documentation
+- **Ready to Use**: Simple configuration to use in Claude Code
+
+## 📦 Included Skills
+
+### 1. seekdb
+
+Provides a complete seekdb database documentation knowledge base with document query and retrieval support.
+
+**Features:**
+- Covers complete seekdb official documentation
+- Supports content-based semantic search
+- Includes the following document categories:
+  - Quick Start Guide
+  - Development Guide (vector search, hybrid search, AI functions, etc.)
+  - SDK and API Reference
+  - Multi-model Data Support (JSON, spatial data, text, etc.)
+  - Integration Guide (models, frameworks, MCP clients)
+  - Deployment and Operations Guide
+  - Practice Tutorials
+  - Reference Documentation
+
+### 2. importing-to-seekdb
+
+Import CSV or Excel files into seekdb vector database with optional column vectorization for semantic search.
+
+**Features:**
+- Read and preview Excel/CSV files before importing
+- Import data to seekdb collections
+- Automatic vectorization of specified columns using embedding functions (all-MiniLM-L6-v2, 384 dimensions)
+- Batch processing for large files
+- Collection management (create/delete)
+
+### 3. querying-from-seekdb
+
+Query and export data from seekdb vector database with support for scalar search, hybrid search, and export to CSV/Excel.
+
+**Features:**
+- Scalar search with metadata filtering
+- Hybrid search combining fulltext and semantic search
+- RRF (Reciprocal Rank Fusion) result ranking
+- Export results to CSV or Excel format
+- Collection information display
+
+## 🚀 Quick Start
+
+### Installation Methods
+
+#### Method 1: Using PyPI Installer (Recommended for Multiple Tools)
+
+This package can be installed from PyPI and provides an interactive command-line installer that supports multiple AI coding tools:
+
+```bash
+# Install from PyPI
+pip install seekdb-agent-skills
+
+# Run the interactive installer
+seekdb-agent-skills
+```
+
+The interactive installer will guide you through the installation process:
+
+1. **Project Root Confirmation**: The installer detects your current directory as the project root and asks for confirmation
+2. **Tool Selection**: Choose one tool from the supported list (Claude Code, GitHub Copilot, Codex, Cursor, etc.)
+3. **Skill Selection**: Select which skills to install (you can select multiple skills using Space key)
+4. **Automatic Installation**: The installer automatically copies the selected skills to the correct directories for your chosen tool
+
+**Supported Tools:**
+- Claude Code (`.claude/skills`)
+- Cursor (`.cursor/skills`)
+- Codex (`.codex/skills`)
+- OpenCode (`.opencode/skills`)
+- GitHub Copilot (`.github/skills`)
+- Qoder (`.qoder/skills`)
+- Trae (`.trae/skills`)
+
+**Interactive Features:**
+- Navigate with arrow keys (↑↓)
+- Select multiple skills with Space key
+- Confirm with Enter
+- Cancel anytime with Ctrl+C
+
+#### Method 2: Manual Installation (Claude Code Only)
+
+For Claude Code users who prefer manual installation:
+
+```bash
+git clone https://github.com/oceanbase/seekdb-ecology-plugins.git
+cp -r seekdb-ecology-plugins/agent-skills/skills/* ~/.claude/skills/
+```
+
+### Prerequisites
+
+- Claude Code 1.0 or higher (for Claude Code)
+- Python 3.10+ (required for the installer and all skills)
+- Basic understanding of Agent Skills
+- Required Python packages (for data import/query skills):
+  ```bash
+  pip install pyseekdb pandas openpyxl
+  ```
+
+### Installing Claude Code
+
+If you haven't installed Claude Code yet, install it using npm:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+### Configure Environment Variables
+
+Claude Code requires an API key to run. Please set the following environment variables:
+
+```bash
+# Set API key (required)
+export ANTHROPIC_API_KEY="your-api-key-here"
+
+# Set API Base URL (if using a proxy or custom endpoint)
+export ANTHROPIC_BASE_URL="https://api.anthropic.com"
+```
+
+> **Tip**: You can add these environment variables to your `~/.bashrc`, `~/.zshrc`, or other shell configuration files to persist the configuration.
+
+### Configure seekdb Connection Mode
+
+The `importing-to-seekdb` and `querying-from-seekdb` skills support two connection modes for seekdb:
+
+**1. Embedded Mode (Default)**
+- No additional configuration required
+- Data is stored locally
+- Simply run the scripts without setting any seekdb environment variables
+
+**2. Server Mode**
+- Connect to a remote seekdb server
+- Configure the following environment variables:
+  ```bash
+  export SEEKDB_HOST=127.0.0.1
+  export SEEKDB_PORT=2881
+  export SEEKDB_USER=root
+  export SEEKDB_PASSWORD=""
+  export SEEKDB_DATABASE=test
+  ```
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `SEEKDB_HOST` | Server host address (if set, enables server mode) | - |
+| `SEEKDB_PORT` | Server port | 2881 |
+| `SEEKDB_USER` | Username | root |
+| `SEEKDB_PASSWORD` | Password | (empty) |
+| `SEEKDB_DATABASE` | Database name | test |
+
+> **Note**: If `SEEKDB_HOST` is not set, the scripts will automatically use embedded mode.
+
+### Configure Network Settings
+
+Since the seekdb skill plugin needs to fetch the latest documentation from GitHub, you need to configure Claude Code to allow network requests in your project directory.
+
+Create or edit the `.claude/settings.local.json` file in your project root directory:
+
+```json
+{
+  "skipWebFetchPreflight": true
+}
+```
+
+> **Important Notes**:
+> - Setting `skipWebFetchPreflight` to `true` skips the preflight check for network requests, allowing Claude to directly access remote documentation
+> - If GitHub is not accessible, the plugin will automatically fall back to local documentation
+
+### Installing the seekdb Plugin
+
+Once Claude Code is installed, follow these steps to install the seekdb plugin:
+
+1. **Add the seekdb Marketplace**
+   
+   Open Claude Code's terminal or command interface and run:
+   ```bash
+   /plugin marketplace add oceanbase/seekdb-ecology-plugins
+   ```
+   
+   This command adds the seekdb plugin marketplace to your Claude Code instance.
+
+2. **Install the Plugin**
+   
+   After adding the marketplace, install the seekdb plugin:
+   ```bash
+   /plugin install seekdb-plugin@seekdb
+   ```
+   
+   This will download and install the seekdb plugin along with all its skills.
+
+3. **Restart Claude Code**
+   
+   After installing the plugin, restart Claude Code to ensure the plugin is fully loaded and ready to use.
+
+### Configuration
+
+The plugin is ready to use immediately after installation. No additional configuration is required. The skills will be automatically available to Claude Code when you ask seekdb-related questions.
+
+## 💡 Usage Examples
+
+### Using seekdb-docs
+
+Ask Claude Code seekdb-related technical questions:
+
+```
+How to deploy a seekdb test environment?
+```
+
+```
+How to use seekdb's vector search functionality?
+```
+
+```
+How to implement hybrid search in seekdb?
+```
+
+```
+Which AI framework integrations does seekdb support?
+```
+
+Claude Code will automatically search the documentation library and provide accurate technical guidance.
+
+### Using importing-to-seekdb
+
+Import data files into seekdb with optional vectorization:
+
+**Example 1: Preview Excel file before importing**
+```
+View the sample Excel data in the importing-to-seekdb skill
+```
+
+Claude Code will use `read_excel.py` to display the file structure and preview data:
+```
+File: sample_products.xlsx (11.5 KB)
+Columns: Name, Brand, Selling Price, MRP, Discount, Ratings, No_of_ratings, Details
+Records: 9 mobile phone products
+```
+
+**Example 2: Import Excel data with vectorization**
+```
+Import sample_products.xlsx into seekdb database, vectorize the Details column
+```
+
+Claude Code will:
+1. Ask which column to vectorize (e.g., Details for semantic search)
+2. Ask for collection name (default: derived from filename)
+3. Execute the import with automatic embedding generation
+
+```
+Import Result:
+- Collection: sample_products
+- Records: 9
+- Vectorized column: Details (all-MiniLM-L6-v2, 384 dimensions)
+- Metadata fields: MRP, Name, Brand, Ratings, Discount, No_of_ratings, Selling Price
+```
+
+### Using querying-from-seekdb
+
+Query data from seekdb with hybrid search and export capabilities:
+
+**Example 1: Semantic search with metadata filtering**
+```
+Recommend 2 phones with rating above 4.3 and AMOLED screen
+```
+
+Claude Code will:
+1. First run `--info` to understand the collection structure
+2. Construct a query combining metadata filter (`Ratings >= 4.3`) and semantic search (`AMOLED screen`)
+3. Return matching results ranked by relevance
+
+```
+Found 2 results:
+1. POCO M4 Pro (Power Black 64 GB)
+   - Brand: POCO
+   - Rating: 4.3
+   - Price: 10,999
+   - Screen: 16.33 cm Full HD+ AMOLED Display
+
+2. POCO M4 Pro (Power Black 128 GB)
+   - Brand: POCO
+   - Rating: 4.3
+   - Price: 11,999
+   - Screen: 16.33 cm Full HD+ AMOLED Display
+```
+
+**Example 2: Query and export to Excel**
+```
+Recommend 2 phones with rating above 4.3 and AMOLED screen, export to Excel
+```
+
+Claude Code will execute the search and export specified fields to an Excel file:
+```
+Exported 2 records to: amoled_phones.xlsx
+
+┌─────┬──────────────────────────────────┬───────┬─────────┬─────────┬──────────┐
+│  #  │               Name               │ Brand │ Ratings │  Price  │ Discount │
+├─────┼──────────────────────────────────┼───────┼─────────┼─────────┼──────────┤
+│ 1   │ POCO M4 Pro (Power Black 64 GB)  │ POCO  │   4.3   │ ₹10,999 │  38% off │
+├─────┼──────────────────────────────────┼───────┼─────────┼─────────┼──────────┤
+│ 2   │ POCO M4 Pro (Power Black 128 GB) │ POCO  │   4.3   │ ₹11,999 │  40% off │
+└─────┴──────────────────────────────────┴───────┴─────────┴─────────┴──────────┘
+```
+
+### Complete Workflow Example
+
+Here's a complete workflow demonstrating all three skills together:
+
+1. **Ask about seekdb** (seekdb skill):
+   ```
+   How to create a vector collection in seekdb?
+   ```
+
+2. **Import data** (importing-to-seekdb skill):
+   ```
+   Import the sample_products.xlsx file, vectorize the Details column
+   ```
+
+3. **Query and export** (querying-from-seekdb skill):
+   ```
+   Find all Samsung phones with rating >= 4.4, export to CSV
+   ```
+
+## 📖 Detailed Usage Guide
+
+### Getting Started with Claude Code
+
+1. **Open a New Conversation**
+   - Launch Claude Code
+   - Start a new conversation or open an existing project
+   - The seekdb skills are automatically available in all conversations
+
+2. **Ask seekdb Questions**
+   - Simply type your question about seekdb in natural language
+   - Claude Code will automatically detect when to use the seekdb-docs skill
+   - No need to explicitly mention the skill name
+
+3. **Example Interactions**
+
+   **Basic Query:**
+   ```
+   How do I get started with seekdb?
+   ```
+   
+   **Technical Question:**
+   ```
+   What are the best practices for vector search in seekdb?
+   ```
+   
+   **Code Example Request:**
+   ```
+   Show me an example of implementing hybrid search with seekdb Python SDK
+   ```
+
+### Using Skills Effectively
+
+- **Be Specific**: The more specific your question, the better Claude Code can search the documentation
+- **Ask Follow-ups**: You can ask follow-up questions based on Claude Code's responses
+- **Request Examples**: Ask for code examples, configuration samples, or step-by-step guides
+- **Combine Topics**: Ask questions that combine multiple seekdb features
+
+### Troubleshooting
+
+If the skills don't seem to be working:
+
+1. **Verify Plugin Installation**
+   
+   In Claude Code, run the `/plugin` command. This will open an interactive interface where you can browse and manage installed plugins.
+   
+   Select "Manage and uninstall plugins" to confirm that `seekdb-plugin` exists.
+
+2. **Restart Claude Code**
+   
+   After installing new plugins or updates, you may need to restart Claude Code to load the updates.
+   
+   Completely close and reopen the Claude Code terminal session.
+
+3. **Update the Plugin**
+   
+   You can update the plugin using either the interactive interface or command line:
+   
+   a. Open the plugin management interface:
+      ```bash
+      /plugin
+      ```
+   
+   b. Navigate to "Manage marketplaces" using the arrow keys (↑↓) and press Enter to select.
+   
+   c. In the marketplace list, select the marketplace you want to update (e.g., `seekdb`).
+   
+   d. Press `u` to update the marketplace and its plugins.
+   
+   e. Press `Esc` to go back when finished.
+   
+   Make sure to use the correct plugin name and marketplace name format.
+
+## 📂 Project Structure
+
+```
+agent-skills/
+├── README.md                           # Project documentation
+├── README_CN.md                        # Chinese documentation
+├── plugin.json                         # Plugin configuration
+├── pyproject.toml                      # Python package configuration
+├── MANIFEST.in                         # Package data manifest
+├── upload_to_pypi.py                   # Build and package script
+├── .gitignore                          # Git ignore rules
+├── skills/                             # Skills directory (source)
+│   ├── seekdb/                         # SeekDB documentation skill
+│   │   ├── SKILL.md                    # Skill documentation
+│   │   └── seekdb-docs/                # Official documentation library
+│   │       ├── 10.doc-overview.md      # Documentation overview
+│   │       ├── 100.get-started/        # Quick start guide
+│   │       ├── 200.develop/            # Development guide
+│   │       ├── 300.integrations/       # Integration guide
+│   │       ├── 400.guides/             # Operations guide
+│   │       ├── 450.reference/          # Reference documentation
+│   │       ├── 500.tutorials/          # Practice tutorials
+│   │       └── 600.demos/              # Demo projects
+│   │
+│   ├── importing-to-seekdb/            # Data import skill
+│   │   ├── SKILL.md                    # Skill documentation
+│   │   ├── scripts/
+│   │   │   ├── import_to_seekdb.py     # Main import script
+│   │   │   └── read_excel.py           # Excel preview script
+│   │   └── example-data/
+│   │       ├── sample_products.csv     # Sample CSV data
+│   │       └── sample_products.xlsx    # Sample Excel data
+│   │
+│   └── querying-from-seekdb/           # Data query skill
+│       ├── SKILL.md                    # Skill documentation
+│       └── scripts/
+│           └── query_from_seekdb.py    # Main query script
+│
+└── src/                                # Python package source
+    └── seekdb_plugin_installer/        # Package directory
+        ├── __init__.py
+        ├── main.py                     # CLI entry point (interactive installer)
+        └── skills/                     # Skills (synced during build)
+            └── ...                     # Same structure as root skills/
+```
+
+## 🔧 Development & Contribution
+
+### Adding a New skill
+
+To add a new skill for seekdb:
+
+1. Create a new skill folder under the `./skills` directory
+2. Add a `SKILL.md` file defining the skill's functionality and usage
+3. Add necessary support files and example code
+4. Update this README document
+
+### Updating Documentation
+
+The documentation content for seekdb-docs is located in the `./skills/seekdb-docs/official-docs` directory and can be synchronized based on updates to the seekdb official documentation.
+
+### Building and Publishing to PyPI
+
+This project is packaged as a Python package and can be published to PyPI for easy distribution.
+
+**Package Configuration:**
+- Package name: `seekdb-agent-skills`
+- Entry point: `seekdb-agent-skills` command (defined in `pyproject.toml`)
+- Dependencies: `questionary>=1.10.0` (for interactive CLI)
+
+**Building the Package:**
+
+Use the provided build script to package the project:
+
+```bash
+# Run the build script (syncs skills, builds wheel, cleans up)
+python upload_to_pypi.py
+```
+
+This script will:
+1. Sync the `skills/` directory to `src/seekdb_plugin_installer/skills/`
+2. Build the wheel package using `python -m build`
+3. Clean up by removing the skills from the package directory
+4. Output the built artifacts in the `dist/` directory
+
+**Manual Build Steps:**
+
+If you prefer to build manually:
+
+```bash
+# 1. Sync skills to package directory
+cp -r skills src/seekdb_plugin_installer/
+
+# 2. Build the package
+python -m build
+
+# 3. Clean up (optional)
+rm -rf src/seekdb_plugin_installer/skills
+```
+
+**Publishing to PyPI:**
+
+After building, you can upload to PyPI:
+
+```bash
+# Upload to PyPI (requires authentication)
+python -m twine upload dist/*
+```
+
+**Note:** Make sure to update the version number in `pyproject.toml` before publishing a new release.
+
+## 📋 About Agent Skills
+
+Agent Skills is a powerful feature of Claude Code that allows packaging professional knowledge and workflows into reusable modules:
+
+- **Automatic Invocation**: Skills are automatically invoked by Claude Code based on context, no manual triggering required
+- **Modular Design**: Each skill is independently maintained, making it easy to organize and manage
+- **Team Sharing**: Share professional knowledge and workflows with your team through git
+- **Composability**: Multiple Skills can be combined to solve complex tasks
+
+Learn more about Agent Skills:
+- [Agent Skills Overview](https://docs.anthropic.com/en/docs/agent-skills)
+- [Using Agent Skills to Equip Agents for the Real World](https://www.anthropic.com/news/agent-skills)
+
+
+## 🔗 Related Links
+
+- [seekdb Official Website](https://www.oceanbase.ai/)
+- [seekdb Official Documentation](https://www.oceanbase.ai/docs/)
+- [Claude Code Documentation](https://www.claude.com/product/claude-code)
+
+## ❓ Frequently Asked Questions
+
+### Q: When will Skills be invoked?
+
+A: Claude Code will automatically decide when to use them based on your request content and the Skills' descriptions. When you ask questions related to seekdb technical issues, the corresponding skill will be automatically invoked.
+
+### Q: Can I use multiple Skills at the same time?
+
+A: Yes. Claude Code can combine multiple Skills to complete complex tasks.
+
+### Q: How to update Skills?
+
+A: If managed with git, simply pull the latest code. If manually copied, you need to re-copy the updated files.
+
+### Q: Will Skills affect Claude's other functionality?
+
+A: No. Skills are independent modules that are only invoked when needed and will not affect Claude Code's other functionality.
+