paddleocr-skills 1.0.0

package/README.md

@@ -0,0 +1,220 @@
+# PaddleOCR Skills
+
+One-command installer to add PaddleOCR Skills to your Claude Code project.
+
+## Quick Start
+
+Install PaddleOCR Skills in your Claude Code project with a single command:
+
+```bash
+npx paddleocr-skills
+```
+
+The installer will:
+1. Prompt you to select skills (PP-OCRv5 and/or PaddleOCR-VL)
+2. Copy skill files to your project
+3. Install Python dependencies
+4. Guide you through API configuration
+5. Verify the installation
+
+## What's Included
+
+### PP-OCRv5 (Text OCR)
+- Fast text recognition for images and documents
+- Adaptive quality modes (auto/fast/quality)
+- Supports URLs and local files
+- Confidence scoring and quality metrics
+
+### PaddleOCR-VL (Document Parsing)
+- Advanced document structure analysis
+- Table, formula, and chart recognition
+- Layout detection (headers, footers, page numbers)
+- Complete document parsing with reading order
+
+## Prerequisites
+
+- **Node.js**: 14.0.0 or higher
+- **Python**: 3.7 or higher
+- **Claude Code**: Installed and configured
+- **API Access**: Get your API credentials at [Baidu AI Studio](https://aistudio.baidu.com/paddleocr/task)
+
+## Installation
+
+### Interactive Mode (Recommended)
+
+```bash
+npx paddleocr-skills
+```
+
+The installer will guide you through:
+- Skill selection
+- Python dependency installation
+- API configuration
+
+### Skip Configuration
+
+If you want to configure later:
+
+```bash
+npx paddleocr-skills
+# Choose "No" when asked about configuration
+```
+
+Then configure manually:
+
+```bash
+# For PP-OCRv5
+python scripts/ppocrv5/configure.py
+
+# For PaddleOCR-VL
+python scripts/paddleocr-vl/configure.py
+```
+
+## Usage
+
+After installation, use the skills in your Claude Code session:
+
+### PP-OCRv5 Example
+
+```bash
+# Extract text from an image
+python scripts/ppocrv5/ocr_caller.py --file-url "https://example.com/image.jpg" --pretty
+
+# Save result to file
+python scripts/ppocrv5/ocr_caller.py --file-path "document.pdf" --output result.json --pretty
+```
+
+### PaddleOCR-VL Example
+
+```bash
+# Parse a complex document
+python scripts/paddleocr-vl/vl_caller.py --file-url "https://example.com/paper.pdf" --pretty
+
+# Save result to file
+python scripts/paddleocr-vl/vl_caller.py --file-path "invoice.pdf" --output result.json --pretty
+```
+
+## Project Structure
+
+After installation, your project will have:
+
+```
+your-project/
+├── skills/
+│   ├── ppocrv5/
+│   │   └── SKILL.md
+│   └── paddleocr-vl/
+│       └── SKILL.md
+├── scripts/
+│   ├── ppocrv5/
+│   │   ├── ocr_caller.py
+│   │   ├── configure.py
+│   │   ├── smoke_test.py
+│   │   └── requirements.txt
+│   └── paddleocr-vl/
+│       ├── vl_caller.py
+│       ├── configure.py
+│       ├── smoke_test.py
+│       └── requirements.txt
+├── references/
+│   ├── ppocrv5/
+│   └── paddleocr-vl/
+└── .env.example
+```
+
+## Configuration
+
+### Manual Configuration
+
+If you skipped auto-configuration, create a `.env` file:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit with your credentials
+nano .env
+```
+
+Add your API credentials:
+
+```env
+# PP-OCRv5
+API_URL=https://your-api-url.aistudio-app.com/ocr
+TOKEN=your-token-here
+
+# PaddleOCR-VL
+VL_API_URL=https://your-vl-api-url.com/v1
+VL_TOKEN=your-vl-token-here
+```
+
+### Using Configuration Scripts
+
+```bash
+# Configure PP-OCRv5
+python scripts/ppocrv5/configure.py --api-url "YOUR_URL" --token "YOUR_TOKEN"
+
+# Configure PaddleOCR-VL
+python scripts/paddleocr-vl/configure.py --api-url "YOUR_URL" --token "YOUR_TOKEN"
+```
+
+## Verification
+
+Test your installation:
+
+```bash
+# Test PP-OCRv5
+python scripts/ppocrv5/smoke_test.py
+
+# Test PaddleOCR-VL
+python scripts/paddleocr-vl/smoke_test.py
+```
+
+## Troubleshooting
+
+### Python Not Found
+
+Ensure Python is in your PATH:
+
+```bash
+python --version
+```
+
+If not found, install Python 3.7+ from [python.org](https://www.python.org/).
+
+### API Configuration Error
+
+Get your API credentials:
+
+1. Visit [Baidu AI Studio](https://aistudio.baidu.com/paddleocr/task)
+2. Create a new task or use an existing one
+3. Copy the API URL and TOKEN
+4. Run the configuration script
+
+### Permission Denied
+
+On Windows, run your terminal as Administrator if you encounter permission errors.
+
+## Documentation
+
+Each skill includes comprehensive documentation:
+
+- **skills/ppocrv5/SKILL.md**: PP-OCRv5 usage guide
+- **skills/paddleocr-vl/SKILL.md**: PaddleOCR-VL usage guide
+- **references/**: Technical reference documentation
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [Report a bug](https://github.com/yourusername/PP-OCRv5-claude-code-Skill/issues)
+- Documentation: See `skills/*/SKILL.md` files
+
+## Credits
+
+Built with:
+- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) by PaddlePaddle
+- [Claude Code](https://claude.ai/claude-code) by Anthropic

package/bin/paddleocr-skills.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/**
+ * PaddleOCR Skills Installer for Claude Code
+ *
+ * Entry point for npx paddleocr-skills
+ */
+
+const { runInstaller } = require('../lib/installer');
+
+async function main() {
+  try {
+    await runInstaller();
+  } catch (error) {
+    console.error('\n❌ Installation failed:', error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/copy.js

@@ -0,0 +1,39 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Copy skill files from template to target directory
+ */
+async function copySkillFiles(skills, targetDir) {
+  const templateDir = path.join(__dirname, '../templates');
+
+  for (const skill of skills) {
+    const skillTemplateDir = path.join(templateDir, skill);
+
+    // Copy scripts directory
+    const scriptsSource = path.join(skillTemplateDir, 'scripts', skill);
+    const scriptsTarget = path.join(targetDir, 'scripts', skill);
+    await fs.copy(scriptsSource, scriptsTarget, { overwrite: false });
+
+    // Copy skills directory
+    const skillsSource = path.join(skillTemplateDir, 'skills', skill);
+    const skillsTarget = path.join(targetDir, 'skills', skill);
+    await fs.copy(skillsSource, skillsTarget, { overwrite: false });
+
+    // Copy references directory if exists
+    const referencesSource = path.join(skillTemplateDir, 'references', skill);
+    if (await fs.pathExists(referencesSource)) {
+      const referencesTarget = path.join(targetDir, 'references', skill);
+      await fs.copy(referencesSource, referencesTarget, { overwrite: false });
+    }
+  }
+
+  // Copy .env.example if it doesn't exist
+  const envExampleSource = path.join(templateDir, '.env.example');
+  const envExampleTarget = path.join(targetDir, '.env.example');
+  if (await fs.pathExists(envExampleSource)) {
+    await fs.copy(envExampleSource, envExampleTarget, { overwrite: false });
+  }
+}
+
+module.exports = { copySkillFiles };

package/lib/installer.js

@@ -0,0 +1,70 @@
+const path = require('path');
+const chalk = require('chalk');
+const { promptForSkills, promptForConfiguration } = require('./prompts');
+const { copySkillFiles } = require('./copy');
+const { installPythonDeps } = require('./python');
+const { runConfigurationWizard, runVerification } = require('./verify');
+
+/**
+ * Main installer workflow
+ */
+async function runInstaller() {
+  console.log(chalk.bold.cyan('\n🎨 PaddleOCR Skills for Claude Code\n'));
+
+  // Get current working directory (where user ran the command)
+  const targetDir = process.cwd();
+  console.log(chalk.gray(`Installing to: ${targetDir}\n`));
+
+  // Step 1: Prompt user for which skills to install
+  const { skills } = await promptForSkills();
+
+  if (skills.length === 0) {
+    console.log(chalk.yellow('\n⚠️  No skills selected. Exiting.'));
+    return;
+  }
+
+  console.log(chalk.green(`\n✓ Selected skills: ${skills.join(', ')}\n`));
+
+  // Step 2: Copy skill files to target directory
+  console.log(chalk.cyan('📁 Copying skill files...'));
+  await copySkillFiles(skills, targetDir);
+  console.log(chalk.green('✓ Files copied successfully\n'));
+
+  // Step 3: Install Python dependencies
+  console.log(chalk.cyan('🐍 Installing Python dependencies...'));
+  await installPythonDeps(skills, targetDir);
+  console.log(chalk.green('✓ Python dependencies installed\n'));
+
+  // Step 4: Ask if user wants to configure now
+  const { configureNow } = await promptForConfiguration();
+
+  if (configureNow) {
+    console.log(chalk.cyan('⚙️  Running configuration wizard...\n'));
+    await runConfigurationWizard(skills, targetDir);
+    console.log(chalk.green('✓ Configuration complete\n'));
+
+    // Step 5: Run verification
+    console.log(chalk.cyan('🔍 Verifying installation...\n'));
+    await runVerification(skills, targetDir);
+  } else {
+    console.log(chalk.yellow('\n⚠️  Skipped configuration. You can configure later by running:'));
+    if (skills.includes('ppocrv5')) {
+      console.log(chalk.gray(`   python scripts/ppocrv5/configure.py`));
+    }
+    if (skills.includes('paddleocr-vl')) {
+      console.log(chalk.gray(`   python scripts/paddleocr-vl/configure.py`));
+    }
+  }
+
+  // Success message
+  console.log(chalk.bold.green('\n✅ Installation complete!\n'));
+  console.log(chalk.cyan('Next steps:'));
+  console.log(chalk.gray('  1. Get your API credentials at: https://aistudio.baidu.com/paddleocr/task'));
+  if (!configureNow) {
+    console.log(chalk.gray('  2. Run the configuration scripts shown above'));
+  }
+  console.log(chalk.gray(`  ${configureNow ? '2' : '3'}. Use the skills in your Claude Code session`));
+  console.log(chalk.gray('\nFor more information, see the skill documentation in the skills/ directory.\n'));
+}
+
+module.exports = { runInstaller };

package/lib/prompts.js

@@ -0,0 +1,67 @@
+const prompts = require('prompts');
+
+/**
+ * Prompt user to select which skills to install
+ */
+async function promptForSkills() {
+  return await prompts({
+    type: 'multiselect',
+    name: 'skills',
+    message: 'Which PaddleOCR skills do you want to install?',
+    choices: [
+      {
+        title: 'PP-OCRv5 (Text OCR)',
+        value: 'ppocrv5',
+        description: 'Fast text recognition for images and documents',
+        selected: true
+      },
+      {
+        title: 'PaddleOCR-VL (Document Parsing)',
+        value: 'paddleocr-vl',
+        description: 'Advanced parsing with tables, formulas, charts, and layout',
+        selected: true
+      }
+    ],
+    hint: '- Space to select. Return to submit'
+  });
+}
+
+/**
+ * Prompt user for configuration preferences
+ */
+async function promptForConfiguration() {
+  return await prompts({
+    type: 'confirm',
+    name: 'configureNow',
+    message: 'Do you want to configure API credentials now?',
+    initial: true
+  });
+}
+
+/**
+ * Prompt user for API credentials
+ */
+async function promptForCredentials(skillName) {
+  const displayName = skillName === 'ppocrv5' ? 'PP-OCRv5' : 'PaddleOCR-VL';
+
+  return await prompts([
+    {
+      type: 'text',
+      name: 'apiUrl',
+      message: `Enter ${displayName} API URL:`,
+      validate: value => value.length > 0 ? true : 'API URL is required'
+    },
+    {
+      type: 'text',
+      name: 'token',
+      message: `Enter ${displayName} TOKEN:`,
+      validate: value => value.length > 0 ? true : 'TOKEN is required'
+    }
+  ]);
+}
+
+module.exports = {
+  promptForSkills,
+  promptForConfiguration,
+  promptForCredentials
+};

package/lib/python.js

@@ -0,0 +1,75 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+
+/**
+ * Check if Python is available
+ */
+async function checkPython() {
+  return new Promise((resolve) => {
+    const python = spawn('python', ['--version']);
+    python.on('close', (code) => {
+      resolve(code === 0);
+    });
+    python.on('error', () => {
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Install Python dependencies for selected skills
+ */
+async function installPythonDeps(skills, targetDir) {
+  // Check if Python is available
+  const hasPython = await checkPython();
+
+  if (!hasPython) {
+    console.log(chalk.yellow('⚠️  Python not found. Skipping dependency installation.'));
+    console.log(chalk.gray('   Please install Python dependencies manually:'));
+    for (const skill of skills) {
+      console.log(chalk.gray(`   pip install -r scripts/${skill}/requirements.txt`));
+    }
+    return;
+  }
+
+  // Install dependencies for each skill
+  for (const skill of skills) {
+    const requirementsPath = path.join(targetDir, 'scripts', skill, 'requirements.txt');
+    const spinner = ora(`Installing ${skill} dependencies...`).start();
+
+    try {
+      await runPipInstall(requirementsPath);
+      spinner.succeed(`${skill} dependencies installed`);
+    } catch (error) {
+      spinner.fail(`Failed to install ${skill} dependencies`);
+      console.log(chalk.yellow(`   You can install manually: pip install -r ${requirementsPath}`));
+    }
+  }
+}
+
+/**
+ * Run pip install for a requirements file
+ */
+function runPipInstall(requirementsPath) {
+  return new Promise((resolve, reject) => {
+    const pip = spawn('pip', ['install', '-r', requirementsPath], {
+      stdio: 'inherit'
+    });
+
+    pip.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`pip install exited with code ${code}`));
+      }
+    });
+
+    pip.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+module.exports = { installPythonDeps };

package/lib/verify.js

@@ -0,0 +1,121 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { promptForCredentials } = require('./prompts');
+
+/**
+ * Run configuration wizard for selected skills
+ */
+async function runConfigurationWizard(skills, targetDir) {
+  for (const skill of skills) {
+    console.log(chalk.bold(`\nConfiguring ${skill}...`));
+
+    // Prompt for credentials
+    const { apiUrl, token } = await promptForCredentials(skill);
+
+    // Run configure.py script
+    const configScript = path.join(targetDir, 'scripts', skill, 'configure.py');
+    const spinner = ora('Saving configuration...').start();
+
+    try {
+      await runConfigureScript(configScript, apiUrl, token);
+      spinner.succeed(`${skill} configured successfully`);
+    } catch (error) {
+      spinner.fail(`Failed to configure ${skill}`);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Run configure.py script with credentials
+ */
+function runConfigureScript(scriptPath, apiUrl, token) {
+  return new Promise((resolve, reject) => {
+    const python = spawn('python', [
+      scriptPath,
+      '--api-url', apiUrl,
+      '--token', token,
+      '--quiet'
+    ]);
+
+    let stdout = '';
+    let stderr = '';
+
+    python.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    python.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    python.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(stderr || stdout || `Configuration failed with exit code ${code}`));
+      }
+    });
+
+    python.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Run verification tests for selected skills
+ */
+async function runVerification(skills, targetDir) {
+  for (const skill of skills) {
+    const smokeTestScript = path.join(targetDir, 'scripts', skill, 'smoke_test.py');
+    const spinner = ora(`Testing ${skill}...`).start();
+
+    try {
+      await runSmokeTest(smokeTestScript);
+      spinner.succeed(`${skill} verification passed`);
+    } catch (error) {
+      spinner.warn(`${skill} verification skipped (API test requires credentials)`);
+      console.log(chalk.gray(`   You can test manually: python ${smokeTestScript}`));
+    }
+  }
+}
+
+/**
+ * Run smoke_test.py script
+ */
+function runSmokeTest(scriptPath) {
+  return new Promise((resolve, reject) => {
+    const python = spawn('python', [scriptPath]);
+
+    let stdout = '';
+    let stderr = '';
+
+    python.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    python.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    python.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(stderr || stdout || `Smoke test failed with exit code ${code}`));
+      }
+    });
+
+    python.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+module.exports = {
+  runConfigurationWizard,
+  runVerification
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "paddleocr-skills",
+  "version": "1.0.0",
+  "description": "PaddleOCR Skills - Install PP-OCRv5 and PaddleOCR-VL for Claude Code",
+  "main": "lib/installer.js",
+  "bin": {
+    "paddleocr-skills": "bin/paddleocr-skills.js"
+  },
+  "keywords": [
+    "paddle-ocr",
+    "ocr",
+    "claude-code",
+    "skill",
+    "ai-studio",
+    "ppocrv5",
+    "paddleocr-vl"
+  ],
+  "author": "Aidenwu0209 <wujinhe0209@aliyun.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.2.0",
+    "ora": "^5.4.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Aidenwu0209/PaddleORC-Skills.git"
+  },
+  "homepage": "https://github.com/Aidenwu0209/PaddleORC-Skills#readme",
+  "bugs": {
+    "url": "https://github.com/Aidenwu0209/PaddleORC-Skills/issues"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates"
+  ]
+}

package/templates/.env.example

@@ -0,0 +1,12 @@
+# PP-OCRv5 Configuration
+# Get your API credentials at: https://aistudio.baidu.com/paddleocr/task
+API_URL=
+TOKEN=
+
+# PaddleOCR-VL Configuration
+VL_API_URL=
+VL_TOKEN=
+
+# Optional: Maximum file size for local files (in MB)
+# Set to 0 for unlimited size
+# VL_MAX_FILE_SIZE_MB=20